mcp-notes-server

AIエージェントに検索可能なマークダウンノート保管庫を提供するMCPサーバーです。YAML形式のフロントマターを持つ.mdファイルのフラットなディレクトリに対して、6つのツールを提供します。

ノートはディスク上ではプレーンなマークダウンのままです。データベースにロックインされるものはないため、同じファイルをエディタ、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 以外のもの）は引き続き投げられるため、目立つままです。

検索は重み付きの語句頻度です。 タイトル内の語句は3倍、タグ内の語句は2倍カウントされるため、sourdough を検索すると、sourdough についてのノートが、ついでに言及しているノートより上にランク付けされます。意図的にシンプルにしています — 同期するインデックスはなく、数千ノートの保管庫でも数ミリ秒でスキャンできます。

保管庫はMCPについて何も知りません。 src/vault.ts はプレーンなファイルシステムコード、src/server.ts はMCPバインディング、src/index.ts はstdioエントリポイントです。この分割により、保管庫は直接テストでき、サーバーはインメモリトランスポート上の実際のMCPクライアントを通じてテストできます。サブプロセスもモックも不要です。

開発

npm test          # 46 tests, vitest
npm run typecheck # tsc --noEmit
npm run build     # emit to dist/

テストは保管庫を直接（test/vault.test.ts）、サーバーを InMemoryTransport 上の実際のMCP Client を通じてエンドツーエンドで（test/server.test.ts）カバーしているため、ツールスキーマ、引数検証、結果の形状がすべて検証されます — その背後にあるロジックだけでなく。

ライセンス

MIT