Fork: 0
dtmoyaji / TelosDB
Transfer to URL with SHA Find file
Newer
Older
TelosDB / docs / specification / 04_mcp_api_specification.md
@楽曲作りまくりおじさん 楽曲作りまくりおじさん 8 hours ago 5 KB Release 0.3.3.1: list_documents paging, list_categories, UI paging, search empty handling, spec updates
Raw Blame History

MCP・API 仕様 (MCP & API Specification)

1. トランスポート

  • 方式: Model Context Protocol に準拠。SSE (Server-Sent Events) で接続維持・イベント配信。
  • ポート: 3001（固定）
  • エンドポイント:
    • GET /sse — 接続確立・通知受信
    • POST /messages?session_id={uuid} — JSON-RPC リクエスト送信

2. 提供ツール一覧

ツール名 役割
search_text 意味・全文ハイブリッド検索。結果は文書単位で結合可能。カテゴリで絞り込み可。
add_item_text テキストをチャンクとして登録。オプションで category を指定可能。ベクトル化はエディションに応じて LSA または埋め込み。
update_item 指定 ID のチャンクを更新。ベクトル再計算。
delete_item 指定 ID のチャンクを削除。
get_item_by_id 指定 ID のメタデータ・本文・category を取得。
list_documents ドキュメント一覧をページングで取得（id, path, mime, chunk_count, category 等）。limit・page で指定。戻りに items・total_count・total_pages・page を含む。
list_categories ドキュメントに設定されているカテゴリ名の一覧（重複なし）。search_text の category フィルタ用。
get_document_count 文書（documents）の総件数。
get_document 文書 ID で全文・チャンク一覧を取得。
delete_document 文書とその全チャンクを削除。
lsa_retrain RE-INDEX。FTS/ベクトルを再構築（Community: LSA 再学習、Pro: vec_items 再投入・HNSW 再構築）。

3. search_text パラメータ

パラメータ 型 必須 既定値 説明
content string ○ — 検索クエリ。短い語句・自然文どちらも可。空の場合は items: [] で返す。
limit integer — 5 返却最大件数。
min_score number — 0.3 類似度の足切り（0〜1）。
group_by_document boolean — true true のとき文書単位で結合して返す。
category string — — 指定時はそのカテゴリのドキュメントのみに絞り込む。list_categories で取得した値を使用。
  • 結果の similarity は 0〜1。ベクトルと FTS のスコアの大きい方を採用。

3.1 search_text レスポンス形式（統一）

成功時は常に次の形で返す。マッチ 0 件・空クエリ・内部エラー時もエラーにせず、同一形式で返す（Issue #11 対応）。

  • content[0].text は JSON 文字列。パースすると:
    • items: 配列。各要素は id, document_id, path, mime, category, content, similarity を持つ。0 件のときは []。
    • vector_search_used: boolean。ベクトル検索が使われたか。

クライアントは parsed.items が常に配列であることを前提に処理できる。

4. list_documents パラメータ・戻り値（ページング）

全件取得は避け、ページングで取得する。

パラメータ 型 必須 既定値 説明
limit integer — 20 1 ページあたりの件数（1〜100）。
page integer — 1 ページ番号（1 始まり）。範囲外のときは items: [] のまま返す。

戻り値（content[0].text を JSON パースしたオブジェクト）:

キー 型 説明
items array そのページのドキュメント配列。範囲外ページは []。
total_count number ドキュメント総数。
total_pages number 総ページ数（0 件のとき 0）。
page number 現在のページ番号（1 始まり）。

5. add_item_text パラメータ（補足）

パラメータ 型 必須 説明
content string ○ 登録する本文。
path string ○ ドキュメントの論理パス（一意）。
mime string — MIME タイプ。未指定時は拡張子から推測。
category string — カテゴリラベル。フォルダ監視で割り当てたものと合わせて利用可能。

6. HTTP API（補助）

メソッド パス 説明
GET /edition 起動中エディション（community / pro）。Pro 時は embedding_loaded も含む。
GET /version アプリバージョン（例: {"version":"0.3.3"}）。
GET /heal FTS 同期実行。{"synced": n}。
GET /model_name エディション名・Pro 時は埋め込みモデル名等。
GET /settings 設定取得（monitor_paths, run_on_login, min_score, limit 等）。
POST /settings 設定保存。フォルダ監視・カテゴリ割り当ての更新を含む。
GET /indexing_status インデックス状態（idle / training 等）。

7. レスポンス形式

ツール呼び出しは JSON-RPC 2.0。結果は MCP の content 配列（type: "text", text に JSON 文字列）で返します。

エラー時は -32000 等。LSA/埋め込みの初期化失敗時はログでエンジン状態を確認してください。