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

1. プロトコル定義

本システムは Model Context Protocol (MCP) に準拠し、外部エージェントに対してデータベース操作インターフェースを公開します。

• トランスポート: SSE (Server-Sent Events)
• ポート: 3001
• エンドポイント:
  • Connection: GET /sse
  • Message: POST /messages?session_id={uuid}
    • 接続時にサーバーから通知される endpoint イベント内のパスを使用。

2. 提供ツール定義 (Tools)

2.1 add_item_text (登録)

文章を自動ベクトル化して登録します。

• 引数: content (string, 必須), path (string, 任意)
• 戻り値: 成功通知と生成された ID。

2.2 search_text (意味検索)

sqlite-vec を用いた自然言語検索。

• 引数: content (string, 必須), limit (number, デフォルト 10)
• 戻り値: 距離（Distance）順の検索結果リスト。

2.3 update_item (更新)

既存データのテキストとベクトルを再生成して更新。

• 引数: id (integer, 必須), content (string, 必須), path (string, 任意)

2.4 delete_item (削除)

指定 ID のデータを物理削除。

• 引数: id (integer, 必須)

2.5 get_item_by_id (取得)

ID 指定により、メタデータを含む生データを取得。

• 引数: id (integer, 必須)

3. データ形式 (JSON-RPC)

3.1 ツール呼び出し例 (Request)

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_text",
    "arguments": { "content": "量子コンピュータについて" }
  },
  "id": "123"
}

3.2 応答形式 (Response)

MCP 規格に従い、ツールの戻り値は content 配列内にラップされます。

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      { "type": "text", "text": "[ID: 1, Distance: 0.12]\n検索結果の内容..." }
    ]
  },
  "id": "123"
}

4. エラー定義

• -32601: Method not found (未定義ツールの呼び出し)
• -32000: Internal error (モデルサーバー不通、DB エラー)
• 422: パラメータ不足、または形式エラー。