mcp-server-sample
mcp-server-sample — 最小化的 MCP 服务器,用于保存和搜索笔记
这是一个仅用于保存和搜索笔记的最小化 MCP 服务器。它不连接任何外部系统。
保存位置仅在同文件夹的 notes.json 文件中。
它包含 MCP 的三种原语,每种一个。
原语 | 谁决定 | 该服务器中的内容 |
工具 | 模型判断 |
|
资源 | AI 应用获取并传递 |
|
提示 | 用户明确选择 |
|
先决条件
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.jsonWindows:
%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 应用找不到 | 将 |
| 依赖未安装 | 在仓库根目录下执行 |
日志为空或未更新 | 配置未加载 | 检查 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 时都会生效。
设置 | 作用 |
| 安装时不会执行依赖包的生命周期脚本(如 |
|
|
| 仅安装发布超过 7 天的版本。npm 会将其转换为 |
依赖在 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 toolsadd_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
Scored across 2 tools
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.
Both tool names follow a consistent verb_noun pattern (add_note, search_notes) using lowercase with underscores. The naming is predictable and clear.
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.
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
Related MCP Connectors
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables adding, getting, and listing notes through MCP, with state persisted to a JSON file in the home directory.MIT
- AlicenseNot gradedqualityCmaintenanceEnables managing notes through a simple MCP server, providing tools to add, retrieve, update, delete, and list notes for use with Claude Desktop.MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI clients to create, list, and search notes stored in a local JSON file through the Model Context Protocol.-
- AlicenseNot gradedqualityCmaintenanceEnables Claude Desktop to add, retrieve, update, delete, and list notes persisted in a JSON file whose path is set via MCP_NOTES_FILE or --notes-file, with atomic, lock-protected saves.MIT