mcp-notes-server

一个 MCP 服务器，为 AI 代理提供一个可搜索的 Markdown 笔记库：即基于一个包含 YAML 风格 frontmatter 的 .md 文件的扁平目录提供六个工具。

笔记在磁盘上保持纯 Markdown 形式。没有任何内容被封存在数据库中，因此同一批文件可以在你的编辑器、grep 和 git 中使用。

~/notes/
├── pad-thai.md
├── sourdough-starter.md
└── weekly-review.md

工具

安装

npm install
npm run build

与 MCP 客户端一起使用

将它添加到客户端的服务器配置中——以 Claude Desktop 为例，claude_desktop_config.json：

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-notes-server/dist/src/index.js", "--vault", "/absolute/path/to/notes"]
    }
  }
}

笔记库目录按以下顺序解析：--vault <dir>，然后是 $NOTES_VAULT，最后是 ~/notes。如果该目录不存在，会在启动时创建。

设计说明

slug 是身份标识，并且会经过验证。 笔记位于 <vault>/<slug>.md，每个 slug 在到达文件系统之前都会对照 /^[a-z0-9]+(?:-[a-z0-9]+)*$/ 进行检查。正是这一点让 read_note({slug: "../../.ssh/id_rsa"}) 成为不可能，而不仅仅是可能性极低——这是一个白名单，而不是转义处理。slug 在更新过程中也保持稳定：如果标题改变时重命名文件，就会使模型在先前工具调用中仍然持有的任何 slug 失效。

工具错误是数据，而不是异常。 “没有 slug 为 X 的笔记”会以带有 isError: true 的正常工具结果返回，因此模型能够读取并自行纠正。如果是被抛出，客户端将看到协议错误，模型无法从中恢复。真正的 bug（任何不是 VaultError 的情况）仍然会被抛出，因此它们不会被掩盖。

搜索采用加权词频。 标题中的词条计为三倍，标签中的词条计为两倍，因此搜索 sourdough 会将一篇关于 sourdough 的笔记排在顺带提到它的笔记之上。它刻意保持简单——无需保持同步的索引，几千条笔记的笔记库只需毫秒级即可扫描完成。

笔记库对 MCP 一无所知。 src/vault.ts 是纯文件系统代码，src/server.ts 是 MCP 绑定，src/index.ts 是 stdio 入口点。正是这种拆分使得笔记库可以直接测试，服务器也可以通过真实 MCP 客户端在内存传输上端到端测试，无需子进程，也无需模拟。

开发

npm test          # 46 tests, vitest
npm run typecheck # tsc --noEmit
npm run build     # emit to dist/

测试直接覆盖笔记库（test/vault.test.ts），并通过真实 MCP Client 在 InMemoryTransport 上对服务器进行端到端测试（test/server.test.ts），因此工具模式、参数验证和结果形状都得到了检验——而不仅仅是其背后的逻辑。

许可证

MIT