三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

基于MCP协议与Yank Note构建AI Agent智能笔记工作流

发布时间：2026/8/14 3:43:34 三亩地 编程学习日记
基于MCP协议与Yank Note构建AI Agent智能笔记工作流

1. 从笔记到智能副驾驶：为什么我们需要 AI Agent

如果你和我一样，每天的工作流都离不开笔记软件，那你肯定也经历过这样的时刻：面对一个复杂的项目，你需要从十几个不同的网页、PDF文档、代码仓库里搜集信息，手动整理成一份结构清晰的报告；或者，你写了一段代码，想快速理解它的逻辑，却不得不把它复制到另一个AI聊天窗口，再手动把解释粘贴回笔记里。这个过程繁琐、割裂，而且打断了你原本流畅的思考。我们使用笔记软件的初衷，是建立一个“第二大脑”，但很多时候，这个大脑更像一个被动的、孤立的仓库，而不是一个能主动协作的伙伴。

这正是“AI Agent”概念开始渗透到笔记领域的原因。它不是一个简单的聊天机器人，而是一个能理解你的上下文、拥有特定技能（Skill）、并能自主执行一系列任务来达成目标的智能体。想象一下，在你的笔记旁边，有一个随时待命的“副驾驶”。你只需要告诉它：“帮我分析一下这个项目文件夹里的代码结构，并生成一份架构图”，它就能自动读取文件、调用代码分析工具、生成图表，并把结果直接插入到你的笔记中。整个过程无需你离开当前的编辑环境。

最近，随着 Claude Code CLI、Cursor 等工具对 MCP（Model Context Protocol）协议的支持，以及 Yank Note 这类本地优先、高度可定制的笔记工具的出现，让 AI Agent 深度融入个人笔记工作流，从一种美好的设想变成了触手可及的现实。这不仅仅是“在笔记里调用AI”那么简单，而是将你的笔记环境升级为一个智能的、可编程的“任务执行中心”。本文将基于 Yank Note 这个强大的工具，手把手带你搭建一个属于你自己的、能处理复杂任务的 AI Agent 工作流，让它真正成为你知识管理和创作过程中的得力助手。

2. 核心组件拆解：MCP、CLI 与 Git 如何协同工作

要实现一个能“干活”的 AI Agent，我们需要几个关键的基础设施。它们各自扮演着不同的角色，共同构成了 Agent 的“身体”和“感官”。

2.1 MCP：AI 的“手”和“眼睛”

MCP，即 Model Context Protocol，是 Anthropic 提出的一种协议。你可以把它理解为 AI 模型（如 Claude）与外部工具、数据源之间的“标准插座”。在没有 MCP 之前，如果你想给 AI 模型增加读取本地文件、搜索网络、操作数据库的能力，需要针对每个模型和每个工具进行复杂的集成开发。而 MCP 定义了一套标准化的通信方式。

一个MCP 服务器（MCP Server）就是一个实现了特定功能的“工具包”。例如：

  • filesystem服务器：让 AI 能安全地读取、列出你指定目录下的文件。
  • brave-search或tavily服务器：让 AI 能进行实时网络搜索。
  • git服务器：让 AI 能执行git status,git log,git diff等操作。
  • sqlite服务器：让 AI 能查询你的本地数据库。

AI 模型（通过支持 MCP 的客户端，如 Claude Code CLI）连接到这些服务器后，就瞬间获得了相应的能力。在 Yank Note 的上下文中，我们可以通过配置，让笔记内的 AI 助手（通常是调用 Claude 或 GPT 的 API）也具备连接这些 MCP 服务器的能力。这意味着，你在笔记里向 AI 提问时，它不再仅仅基于过时的训练数据回答，而是可以实时“看到”你的文件系统、“搜索”最新的网络信息。

2.2 CLI：一切操作的指挥终端

CLI（Command Line Interface）是我们与计算机底层系统交互最直接、最强大的方式。一个成熟的 AI Agent 工作流，必然离不开 CLI。这里主要涉及两个层面：

  1. AI 开发环境的 CLI：如Claude Code CLI (codex)。这是官方提供的命令行工具，它本身就是一个强大的、支持 MCP 的 AI 客户端。安装后，你可以在终端直接与 Claude 对话，并因为它内置了 MCP 客户端，可以轻松附加（attach）各种 MCP 服务器，让 Claude 在对话中直接使用工具。它是我们测试和验证 MCP 功能的关键环境。

  2. 系统与工具链的 CLI：最核心的就是Git。版本控制是开发者和知识工作者的生命线。让 AI Agent 理解并操作 Git，意味着它可以帮你总结代码变更、创建提交信息、甚至管理分支。git命令是这一切的基础。此外，像curl、jq、pandoc等命令行工具，都可以通过 Shell 脚本或更高级的 MCP 服务器封装，成为 AI Agent 的技能。

2.3 Git：工作流的版本控制与协作基石

为什么特别强调 Git？因为在 AI Agent 参与的工作流中，可追溯性和安全性至关重要。你肯定不希望一个自动执行的 Agent 胡乱覆盖你的重要文件。通过 Git，我们可以实现：

  • 变更隔离：让 Agent 在独立的分支上工作。完成并审核后，再合并到主分支。
  • 操作回溯：所有由 Agent 产生的修改都有清晰的提交历史，随时可以查看“它到底改了哪里”。
  • 安全网：如果 Agent 的操作导致了问题，一个简单的git reset或git checkout就能回滚到安全状态。

因此，在搭建工作流之初，确保你的笔记项目（尤其是 Yank Note 的库目录）本身就是一个 Git 仓库，是至关重要的一步。这为后续所有自动化操作提供了安全护栏。

2.4 协同工作流

这三者的关系可以这样概括：MCP 协议为 AI 模型定义了调用工具的“语言”和“接口”；各种 CLI（特别是codex和git）是具体指令的“执行器”和“验证器”；而 Git 则为整个工作流提供了“操作日志”和“安全回滚机制”。Yank Note 则作为集大成者，提供了一个统一的图形界面，让你能以自然语言发起请求，背后则由这个稳固的三角支撑体系默默完成所有复杂任务。

3. 环境搭建：从零开始配置你的智能笔记工作流

理论讲完了，我们开始动手。这里假设你从零开始，目标是配置一个能让 Yank Note 内的 AI 助手连接 MCP 服务器，从而获得额外能力的完整环境。

3.1 基础准备：安装 Git 与 Node.js

这是所有现代开发工作流的基础，也是运行很多 MCP 服务器的前提。

  1. 安装 Git：

    • Windows：访问 git-scm.com ，下载安装程序。安装过程中，关键选项建议如下：
      • “Choosing the default editor used by Git”：这里选择你熟悉的编辑器，比如Vim、Nano或Visual Studio Code。如果你不常在终端编辑提交信息，选Vim或Nano即可。这个设置影响git commit时不使用-m参数时弹出的编辑器。
      • “Adjusting your PATH environment”：选择“Git from the command line and also from 3rd-party software”。这确保 Git 命令在任何终端（包括 Yank Note 未来可能调用的 shell）中都能被找到。
      • 其他选项保持默认即可。安装完成后，在终端输入git --version验证。
    • macOS：通常已预装。如果没有或版本旧，可通过 Homebrew 安装：brew install git。
    • Linux：使用包管理器安装，如sudo apt install git(Ubuntu/Debian) 或sudo yum install git(CentOS)。

  2. 安装 Node.js 和 npm：

    • 访问 nodejs.org ，下载LTS（长期支持版）安装包。这同时会安装 Node.js 运行时和 npm（包管理器）。
    • 安装后，在终端输入node --version和npm --version验证。

3.2 核心引擎：安装与配置 Claude Code CLI

Claude Code CLI (codex) 是我们连接 Claude 和 MCP 的官方桥梁。

  1. 安装codex：

    • 打开终端，执行以下命令：
      npm install -g @anthropic-ai/codex
    • 如果遇到权限错误（EACCES），请不要使用sudo。更安全的做法是参考 npm 官方文档，为 npm 配置一个无 root 权限的全局安装目录。一个快速解决方法是使用sudo，但这不是最佳实践：sudo npm install -g @anthropic-ai/codex。
    • 安装完成后，输入codex --version验证。

  2. 配置 Claude API 密钥：

    • 你需要一个 Claude API 密钥。前往 Anthropic 控制台 创建。
    • 在终端中设置环境变量（当前会话有效）：
      export ANTHROPIC_API_KEY='你的-api-key'
    • 为了永久生效，将上述命令（替换为你的真实密钥）添加到你的 shell 配置文件（如~/.zshrc或~/.bashrc）中，然后执行source ~/.zshrc。

  3. 初步测试：

    • 在终端输入codex，进入交互模式。你可以直接问它问题，比如“用 Python 写一个快速排序函数”。此时，它的能力还仅限于对话。

3.3 扩展能力：安装关键的 MCP 服务器

现在，我们来为codex装上“工具”。

  1. 安装 MCP 服务器： MCP 服务器通常是 npm 包。我们安装几个最实用的：

    # 文件系统访问（核心中的核心） npm install -g @modelcontextprotocol/server-filesystem # 网络搜索（使用 Brave Search API，需自备API Key） npm install -g @modelcontextprotocol/server-brave-search # Git 操作 npm install -g @modelcontextprotocol/server-git

  2. 运行并附加服务器到codex： 我们需要在一个终端运行 MCP 服务器，在另一个终端让codex连接它。这里以filesystem为例，演示标准流程：

    • 终端 A（运行服务器）：
      # 启动 filesystem 服务器，并允许它访问当前目录（.） npx @modelcontextprotocol/server-filesystem .
      启动后，服务器会输出一个标准输入输出（stdio）正在监听的提示，它等待客户端连接。
    • 终端 B（连接客户端）：
      # 启动 codex，并附加（attach）正在运行的服务器 # 这里假设服务器运行在默认的 stdio 方式，codex 会自动处理连接 codex --attach @modelcontextprotocol/server-filesystem
      更常见的做法是使用codex的配置来自动化这个过程（见下一步）。

    实操注意点：直接通过npx运行服务器并手动附加比较麻烦。社区更推荐使用mcp这个命令行工具来统一管理 MCP 服务器，或者直接配置codex的配置文件。

  3. 配置codex自动加载 MCP 服务器（推荐）：codex会读取用户主目录下的配置文件~/.codex/config.json。我们可以在这里预定义要连接的服务器。

    • 创建或编辑配置文件：
      mkdir -p ~/.codex nano ~/.codex/config.json
    • 填入以下配置内容（按需调整）：
      { "mcpServers": { "fs": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/你的用户名/SafeDirectory" // 指定一个允许访问的安全目录，绝对路径！ ] }, "git": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-git" ] } } }
    • 保存退出。现在，每次启动codex，它都会自动启动并连接filesystem和git服务器。你可以将/Users/你的用户名/SafeDirectory替换为你希望 AI 有权限访问的目录路径，例如你的 Yank Note 库目录。

  4. 验证 MCP 功能： 重新启动codex，现在你可以尝试一些需要工具交互的命令了：

    $ codex > 请列出当前目录下的所有 Markdown 文件。

    如果配置正确，Claude 会调用filesystem服务器，读取你配置的安全目录，并返回文件列表。你可以进一步测试：“读取project_plan.md文件的前三行”或“当前 Git 仓库的状态是什么？”。

4. 与 Yank Note 深度集成：构建无缝的 AI 笔记体验

Yank Note 是一款支持插件、高度可定制、本地优先的 Markdown 笔记应用。它的强大之处在于可以通过插件系统扩展功能。虽然截至我撰写时，Yank Note 可能还没有一个官方的、开箱即用的 MCP 客户端插件，但我们可以通过其“自定义插件”或“外部 API 调用”功能，模拟出类似的效果，或者期待社区插件的出现。这里提供两种集成思路。

4.1 思路一：利用 Yank Note 的“运行代码块”功能作为桥梁

Yank Note 支持在笔记中执行多种语言的代码块（如 JavaScript、Python、Shell）。我们可以利用这个特性，创建一个“AI Agent 指令面板”。

  1. 创建 Agent 指令模板： 在你的 Yank Note 中创建一个名为“AI Agent 工作区”的笔记。在里面，你可以设计一些代码块模板。

    // 代码块语言选择 `node` 或 `bash` // 示例：调用本地脚本与 AI 交互 const { exec } = require('child_process'); const util = require('util'); const execPromise = util.promisify(exec); async function askClaudeWithContext(question, filePath) { // 1. 先通过 MCP 服务器读取文件内容 const readCmd = `codex --request '{"tool": "read_file", "path": "${filePath}"}'`; // 假设的简化调用 // 2. 将文件内容和问题组合，发送给 Claude API // ... 实际实现需要更复杂的拼接和 API 调用 console.log(`处理问题：${question}，基于文件：${filePath}`); } // 调用示例（这里需要你编写真实的集成逻辑） // askClaudeWithContext(“总结这个文档的核心观点”, “./我的论文草稿.md”);

    这个方法的本质是，你在 Yank Note 里点击“运行”这个代码块，它会执行一个本地 Node.js 脚本。这个脚本可以：

    • 读取当前笔记的内容或指定的文件。
    • 调用配置好的codexCLI（它已连接 MCP 服务器）或直接调用 Claude API。
    • 将结果写回 Yank Note 或生成一个新笔记。

  2. 封装常用操作为快捷命令： 你可以将上述脚本封装成更简单的 Shell 命令，然后利用 Yank Note 的“自定义快捷键”或“插件”功能，绑定一个快捷键。例如，选中一段文本，按Ctrl+Shift+A，触发一个脚本，将选中的文本作为上下文，向 AI 提问并替换选中内容。

此思路的优缺点：

  • 优点：灵活，完全可控，不需要等待特定插件。
  • 缺点：需要一定的编程能力来搭建桥梁；体验不够无缝，需要在笔记和脚本间切换。

4.2 思路二：期待或开发 Yank Note 的 MCP 客户端插件

这是最理想的集成方式。一个成熟的 Yank Note MCP 插件应该能做到：

  • 全局配置：在 Yank Note 设置中填入 Claude API Key 和 MCP 服务器配置（类似~/.codex/config.json）。
  • 上下文感知：AI 助手能自动获取当前笔记、整个库、甚至特定文件夹作为上下文。
  • 工具调用可视化：当 AI 决定调用工具（如搜索、读文件）时，在界面上有清晰的提示和确认。
  • 内联操作：在笔记的任何位置，通过一个快捷键或右键菜单，就能唤出 AI 助手并基于当前上下文执行复杂任务。

虽然这样的插件可能需要社区或官方来开发，但你可以关注 Yank Note 的 GitHub 仓库或社区论坛。基于其活跃的插件生态，出现类似功能的可能性很大。

当前实践建议： 在等待完美插件的同时，采用“思路一”作为过渡方案。你可以先打造几个非常实用的“原子操作”脚本：

  • “解释这段代码”脚本：将选中的代码块发送给 AI，让其解释，并将结果插入到代码块下方。
  • “研究当前主题”脚本：提取当前笔记的标题或关键词，调用brave-searchMCP 服务器进行网络搜索，并将摘要整理到笔记末尾。
  • “整理会议纪要”脚本：读取一个录音转文字的文件，让 AI 总结要点、生成待办事项，并格式化成 Markdown 表格。

这些脚本虽然初期搭建有成本，但一旦完成，就能极大提升你在 Yank Note 中的工作效率。

5. 实战案例：打造自动化的项目调研笔记助手

让我们用一个完整的场景，串联起前面所有的组件。假设你正在研究“如何使用 Rust 开发 WebAssembly 模块”，你需要整理一份学习笔记。

传统流程：

  1. 打开浏览器，搜索“Rust WebAssembly 教程”。
  2. 打开多个标签页，阅读、复制、粘贴关键信息到 Yank Note。
  3. 找到官方 GitHub 示例库，克隆到本地，阅读代码。
  4. 手动总结步骤、注意事项，整理成笔记。
  5. 遇到问题，再次搜索或去社区提问。

AI Agent 辅助流程：

  1. 在 Yank Note 中，新建笔记“Rust WebAssembly 学习指南”。

  2. 向内置 AI 助手（已集成 MCP）发出指令：

    “我需要学习用 Rust 开发 WebAssembly。请执行以下任务：

    1. 使用网络搜索，查找三篇最新的（2023年以后的）、评分较高的入门教程，并总结它们的核心教学路径和优缺点。
    2. 在 GitHub 上搜索rustwasm/wasm-pack这个关键项目，获取其 README 中的快速开始指南。
    3. 在我的本地~/projects/learn-wasm目录下，按照官方指南创建一个hello-world项目。
    4. 将以上所有信息，整理成一份结构化的 Markdown 文档，包含：学习路线图、环境准备步骤、核心概念解释、第一个示例代码及注释，以及常见问题排查。”

  3. Agent 自主执行：

    • 它调用brave-searchMCP 服务器，执行搜索，分析结果。
    • 它可能调用github相关的 MCP 服务器（如果有）或通过搜索获取wasm-pack的 README 内容。
    • 它调用filesystem服务器，在你的指定目录创建项目。
    • 它调用git服务器，初始化仓库（如果你要求）。
    • 它使用codex的核心推理能力，综合所有信息，生成结构化的内容。

  4. 结果交付： AI Agent 将最终生成的、包含代码块、链接和步骤的完整 Markdown 文档，直接插入或更新到你的 Yank Note 中。你得到的是一个立即可用的、信息丰富的学习笔记初稿，而你只付出了一句指令的成本。

这个案例中的技术要点：

  • 指令的精确性：给 AI 的指令需要具体、可操作。明确数量（“三篇”）、时间（“2023年以后”）、来源（“GitHub”）、动作（“创建项目”）。
  • MCP 服务器的组合使用：一个复杂任务需要多个 MCP 服务器协同工作。
  • 安全边界：通过filesystem服务器严格限制了 AI 可访问的目录（~/projects/learn-wasm），防止其误操作其他文件。
  • 人机协作：生成的初稿需要你复核、调整和深化。AI Agent 负责的是信息搜集和初步整合，你负责最终的质量控制和深度思考。

6. 避坑指南与高级技巧

在实际搭建和使用的过程中，你肯定会遇到一些问题。这里分享一些我踩过的坑和总结的经验。

6.1 常见问题与排查

  • codex启动报错“Couldn‘t get current server api group list...”： 这类错误通常与codex本身或网络配置无关，而是误传的错误信息。更常见的问题是MCP 服务器启动失败或配置错误。请按以下步骤排查：

    1. 检查 MCP 服务器命令：确保~/.codex/config.json中command和args的路径和参数完全正确。特别是npx命令，如果全局包安装有问题，可以尝试使用node直接运行服务器的 JS 文件（找到node_modules中的入口文件）。
    2. 手动测试服务器：单独在终端运行配置中的命令，例如npx -y @modelcontextprotocol/server-filesystem /safe/path，看服务器是否能正常启动并等待连接。
    3. 检查 API 密钥：确认ANTHROPIC_API_KEY环境变量已设置且有效。
    4. 查看详细日志：启动codex时添加--verbose标志，可以输出更详细的连接和错误信息。

  • AI 拒绝使用工具或使用工具结果不佳：

    1. 指令不够明确：AI 需要清晰的授权。在指令中明确说“请使用文件系统工具查看docs文件夹”，比“看看我的文档”要好得多。
    2. 工具描述不清：有些 MCP 服务器功能复杂。在初次使用时，可以先让 AI “列出所有可用的工具”，然后针对性地调用。
    3. 上下文不足：确保你的问题提供了足够的背景。例如，想让 AI 修改代码，最好先让它读取整个文件，理解上下文后再指定修改位置。

  • npm install -g安装失败： 这是 Node.js 环境常见的权限问题。永远不要养成使用sudo npm的习惯，这有安全风险。正确的解决方案是：

    1. 为 npm 配置无 root 权限的全局安装目录（推荐）：
      mkdir ~/.npm-global npm config set prefix '~/.npm-global'
      然后将~/.npm-global/bin添加到你的PATH环境变量中（在~/.zshrc或~/.bashrc中添加export PATH=~/.npm-global/bin:$PATH）。
    2. 使用nvm等 Node 版本管理器，它通常能更好地管理环境。

6.2 性能与成本优化

  • 选择性连接 MCP 服务器：不要在config.json里一次性加载所有服务器。只加载当前项目需要的。频繁的网络搜索或大型文件遍历会消耗更多的 Token，增加 API 调用成本和时间。
  • 设置使用限额：在 Anthropic 控制台为 API 密钥设置每日或每月使用限额，防止意外超支。
  • 本地模型作为补充：对于简单的文本处理、格式整理等任务，可以考虑在 Yank Note 中集成本地运行的轻量级模型（通过 Ollama 等工具），节省成本并提升响应速度。

6.3 扩展你的 Agent 技能栈

除了官方和常见的 MCP 服务器，你可以探索更多社区服务器，甚至自己开发：

  • 数据库操作：server-sqlite可以让 AI 查询你的本地数据库。
  • 网页抓取与自动化：server-playwright让 AI 能控制浏览器进行自动化操作和抓取。
  • 绘图与图表：寻找或开发能生成图表（如 Mermaid, PlantUML）的服务器，让 AI 能将数据可视化并插入笔记。
  • 自定义脚本：这是最强大的部分。你可以写一个简单的 MCP 服务器，封装你常用的 Shell 脚本或内部工具。例如，一个“部署到测试环境”的服务器，AI 在完成代码审查后，可以一键触发部署流程。

自己开发一个简单的 MCP 服务器并不复杂，它本质上是一个遵循特定 JSON-RPC 协议的 STDIO 程序。你可以从@modelcontextprotocol/sdk包开始，快速上手。

将 AI Agent 引入笔记工作流，不是一个一蹴而就的“安装即用”功能，而是一个需要你亲手搭建和调教的“系统升级”。它开始可能有些笨拙，需要你清晰地指令、耐心地调试配置。但一旦跑通，你会发现它从根本上改变了你与知识交互的方式——从被动的记录和检索，转变为主动的协作与创造。你的笔记软件，从此不再只是一个存储箱，而是一个拥有强大外脑和灵活双手的智能工作台。这个过程本身，也是对你个人工作流进行的一次深度审视和优化。我自己的体验是，花在搭建和调试上的时间，会在未来无数个需要跨工具、跨信息源处理复杂任务的场景中，十倍百倍地回报回来。现在，就从配置好你的第一个filesystemMCP 服务器开始吧。

编程学习 学习日记 实战经验
← 返回列表