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

1. プロトコル定義

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

• プロトコルバージョン: 2024-11-05 (最新安定版)
• トランスポート: SSE (Server-Sent Events)
• エンドポイント:
  • Connection: GET /sse
  • Message: POST /messages?session_id={uuid}
    • GET /sse 接続時にサーバーから送られる endpoint イベント内のパスを使用すること。

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

[!NOTE] 検索 (search_text) に加え、登録・更新・削除の全 CRUD ツールが実装・公開されています。

2.1 add_item_text (登録)

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

• 引数:
  • content (string): 本文 (必須)
  • path (string): メタデータ (任意)
• 戻り値: 成功メッセージと ID

2.2 search_text (意味検索)

自然言語による検索を実行します。

• 引数:
  • content (string): 検索クエリ (必須)
  • limit (number): 取得件数 (デフォルト: 10)
• 戻り値: 類似度順の結果リスト（テキスト形式）

2.3 update_item (更新)

既存のアイテムとベクトルを最新の内容で書き換えます。

• 引数:
  • id (integer): 更新対象の文章番号（ID） (必須)
  • content (string): 新しい本文 (必須)
  • path (string): 新しいメタデータ (任意)
• 戻り値: 更新完了通知

2.4 delete_item (削除)

指定された文章番号（ID）のデータを削除します。

• 引数:
  • id (integer): 削除対象の文章番号（ID） (必須)
• 戻り値: 削除完了通知

3. レスポンスフロー (SSE)

MCP SSE 規格に基づき、リクエストとレスポンスは以下のフローで行われます。

1. 接続: クライアントが GET /sse を開始。
2. 通知: サーバーが event: endpoint でメッセージ送信先パスを返却。
3. 送信: クライアントが POST /messages?session_id=... で命令を送信。
4. 応答: サーバーが SSE ストリーム上で event: message として結果を返却。HTTP 自体は 202 Accepted を返却する。

4. エラー定義