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

Если возвращается JSON с add_note и search_notes, сервер работает нормально. В этом случае проверяйте настройки 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