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`	文書の永続化	テキストを LSA 解析によってベクトル化し DB へ保存。
`search_text`	意味検索	記述内容を LSA 解析し、類似度に基づいたベクトル検索を実行。FTS5 (BM25) とベクトル検索のハイブリッド。
`update_item`	知識の更新	ID 指定による既存データの書き換え。
`delete_item`	知識の抹消	ID 指定による物理削除。
`get_item_by_id`	生データ取得	メタデータを含むレコードの直接参照。

3.1 search_text パラメータ

パラメータ	型	必須	既定値	説明
`content`	string	○	—	検索クエリ文字列。
`limit`	integer	—	10	返却する最大件数（1〜100）。
`min_score`	number	—	0.3	足切り閾値（0〜1）。この値未満の類似度の結果は返却しない。

省略時: min_score を省略した場合は 0.3 が適用される。
スコア: 各結果の similarity は 0〜1 に正規化され、ベクトル検索と FTS5 のスコアの大きい方が採用される。
該当語句がない場合: クエリのトークンが LSA 語彙に1つも存在しない場合はベクトル検索をスキップし、FTS5 の結果のみ返す（無関係なドキュメントに 1.0 が付くのを防ぐ）。

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

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

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

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

/status エンドポイントにアクセスすることで、現在の MCP セッション数やシステム負荷状況を確認できます。
エラーコード -32000 が返された場合は、内部の LSA Engine の初期化不良（語彙データが空、またはメモリ不足）の可能性が高いです。ログを確認して LSA モデルが正しくロードされているか検証してください。