# 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 解析し、類似度に基づいたベクトル検索を実行。 |
| `update_item` | 知識の更新 | ID 指定による既存データの書き換え。 |
| `delete_item` | 知識の抹消 | ID 指定による物理削除。 |
| `get_item_by_id` | 生データ取得 | メタデータを含むレコードの直接参照。 |

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

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

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

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

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