Skip to main content
Glama

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

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

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

原语

谁决定

该服务器中的内容

工具

模型判断

add_note(添加笔记)/search_notes(搜索笔记)

资源

AI 应用获取并传递

notes://all(所有已保存的笔记)

提示

用户明确选择

weekly_review(本周回顾)

先决条件

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

  • git

Related MCP server: mcp-snippetbox

设置

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 之后是否跟着错误。

日志中显示的内容

原因

解决方法

Cannot find module '/.../index.js'

args 的路径不正确

在仓库根目录下执行 pwd,将其输出加上 /index.js 重新粘贴

spawn node ENOENT

AI 应用找不到 node。当使用 nvm / volta 且 PATH 仅存在于 shell 配置中时会发生

将 which node 的输出(绝对路径)直接写入 command

Cannot find package '@modelcontextprotocol/server'

依赖未安装

在仓库根目录下执行 npm ci

日志为空或未更新

配置未加载

检查 JSON 语法(逗号、括号),完全退出 Claude Desktop(macOS 按 ⌘Q)后重新启动

区分是服务器端还是 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 时都会生效。

设置

作用

ignore-scripts=true

安装时不会执行依赖包的生命周期脚本(如 postinstall)。阻止被劫持的包首先使用的执行路径。npm start / npm run 仍然正常工作(只有 pre / post 脚本不会运行)

save-exact=true

npm install <pkg> 会在 package.json 中写入完整版本号,不带 ^

min-release-age=7

仅安装发布超过 7 天的版本。npm 会将其转换为 before=<7天前的日期> 来解析依赖

依赖在 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

Available Tools

2 tools
add_noteメモを追加するA

メモを1件保存する。打ち合わせの決定事項や、あとで思い出したいことを記録するときに使う。

Inputs: text (required), tags.

search_notesメモを検索するB

保存済みのメモをキーワードで検索する。本文とタグの両方を対象にする。

Inputs: keyword (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have completely distinct purposes: one creates/ stores a note, the other retrieves notes via search. There is no overlap or ambiguity between writing and searching.

    Naming Consistency5/5

    Both tool names follow a consistent verb_noun pattern (add_note, search_notes) using lowercase with underscores. The naming is predictable and clear.

    Tool Count3/5

    With only 2 tools, the set feels minimal. While the tools cover basic create and read/search operations, the server's purpose (saving and retrieving notes) could reasonably include more tools (e.g., update, delete, list tags) to avoid being overly thin.

    Completeness2/5

    The domain is a personal note-taking system, but only add and search operations are provided. Missing critical operations like update, delete, and get all notes (without search) create significant gaps that would frustrate or block a typical agent workflow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers