mcp-notes-server

Сервер MCP, который предоставляет ИИ-агенту поисковое хранилище заметок в формате markdown: шесть инструментов для работы с плоским каталогом .md-файлов с frontmatter в стиле YAML.

Заметки остаются обычным 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, поэтому модель читает его и исправляет себя. Если бы оно было выброшено, клиент увидел бы ошибку протокола, от которой модель не может восстановиться. Настоящие баги (всё, что не является VaultError) по-прежнему выбрасываются, чтобы оставаться заметными.

Поиск — это взвешенная частота терминов. Термин в заголовке учитывается трижды, а термин в теге — дважды, поэтому поиск sourdough ранжирует заметку о закваске выше, чем заметку, где она упоминается вскользь. Это намеренно просто — нет индекса, который нужно синхронизировать, и хранилище из нескольких тысяч заметок сканируется за миллисекунды.

Хранилище ничего не знает об MCP. src/vault.ts — это обычный код файловой системы, src/server.ts — это привязка к MCP, а src/index.ts — это точка входа stdio. Именно из-за этого разделения хранилище можно тестировать напрямую, а сервер — через реальный MCP-клиент поверх in-memory транспорта, без подпроцесса и без моков.

Разработка

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