mcp-server-sample — 最小化的 MCP 服务器，用于保存和搜索笔记

这是一个仅用于保存和搜索笔记的最小化 MCP 服务器。它不连接任何外部系统。 保存位置仅在同文件夹的 notes.json 文件中。

它包含 MCP 的三种原语，每种一个。

先决条件

• Node.js 24 或更高版本（LTS。用 node --version 确认）

• git

设置

git clone https://github.com/utakatano/mcp-server-sample.git
cd mcp-server-sample
npm install

如果 npm install 成功，则准备就绪。此时不会启动。 MCP 服务器由 AI 应用启动，因此无需自己从终端运行。

连接到 AI 应用

Claude Code

claude mcp add notes -- node /絶対パス/mcp-server-sample/index.js

如果 claude mcp list 显示 ✔ Connected，则表示已连接。

Claude Desktop

设置 → Developer → 点击「Edit Config」打开 claude_desktop_config.json，并添加以下内容。

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/絶対パス/mcp-server-sample/index.js"]
    }
  }
}

保存后，完全退出 Claude Desktop 并重新启动（仅关闭窗口不会生效）。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

验证

「来週までにネットワーク構成を確認する」とメモして

「ネットワーク」を含むメモを探して

可以看到 notes.json 被创建，并且内容不断增加。

更改保存位置

通过环境变量 NOTES_FILE 传递绝对路径，可以更改保存位置。

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/絶対パス/mcp-server-sample/index.js"],
      "env": { "NOTES_FILE": "/絶対パス/my-notes.json" }
    }
  }
}

无法连接时

首先查看日志。原因通常出现在这里。

tail -20 ~/Library/Logs/Claude/mcp-server-notes.log   # macOS
# Windows: %APPDATA%\Claude\logs\mcp-server-notes.log

检查 Server started and connected successfully 之后是否跟着错误。

区分是服务器端还是 AI 应用端的问题，最快的方法是在本地直接测试。

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}\n' \
  | node /絶対パス/mcp-server-sample/index.js

如果返回包含 add_note 和 search_notes 的 JSON，则服务器正常。在这种情况下，请检查 AI 应用端的配置（路径、JSON 编写方式、重启）。

供应链安全对策

在 .npmrc 中设置了针对 npm 包被劫持的配置。每次 npm install / npm ci 时都会生效。

依赖在 package.json 中完全固定（@modelcontextprotocol/server 为 2.0.0，zod 为 4.4.3）， 并在 package-lock.json 中记录带有 integrity 哈希的版本。 如果需要严格按照 lock 文件安装，请使用 npm ci 而不是 npm install。

更新依赖时，请逐个有意图地升级。

npm outdated
npm install @modelcontextprotocol/server@2.1.0   # save-exact により完全固定で書かれる
npm ls --all                                      # 増えた依存を目で確認する

许可证

MIT