MCP・APIインターフェース仕様書 (MCP & API Specification)

1. プロトコル設計思想

本システムは、Anthropic が提唱する Model Context Protocol (MCP) に準拠しています。これにより、IDE（Cursor 等）や外部エージェントが、本システムを単なる「静的なドキュメント」としてではなく、対話可能な「インテリジェントな知識ベース」として認識できるようになります。

1.1 なぜ SSE (Server-Sent Events) なのか

MCP には Stdio と SSE の 2 つのトランスポートがありますが、本システムでは SSE を採用しています。

UIとの親和性: GUI を持つデスクトップアプリでは、Stdio は標準入出力の競合が発生しやすいため、HTTP ベースの SSE が適しています。
多重接続: 同時に複数のエージェント（例：IDE とブラウザ拡張）からの要求を並行して処理することが可能です。

2. インターフェース定義

ポート: 3001 (固定)
エンドポイント:
- Connection: GET /sse (接続維持・通知受取)
- Message: POST /messages?session_id={uuid} (コマンド送信)

3. 提供ツール (Capabilities)

本システムのリソースへアクセスするための具体的なコマンド群です。

ツール名	役割	解説
`add_item_text`	文書の永続化	テキストを Embedding 化して DB へ保存。
`search_text`	意味検索	記述内容の類似度に基づいたベクトル検索。
`update_item`	知識の更新	ID 指定による既存データの書き換え。
`delete_item`	知識の抹消	ID 指定による物理削除。
`get_item_by_id`	生データ取得	メタデータを含むレコードの直接参照。

4. 通信シーケンスとレスポンス形式

ツール呼び出しは JSON-RPC 2.0 に準拠しており、結果は常に MCP 規格の content 配列形式で返されます。

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[結果メッセージ]"
      }
    ]
  },
  "id": "req-123"
}

5. 開発者向けデバッグ情報

/status エンドポイントにアクセスすることで、現在の MCP セッション数やシステム負荷状況を確認できます。
エラーコード -32000 が返された場合は、バックグラウンドの llama-server との通信エラー（タイムアウト等）の可能性が高いです。