# 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/埋め込みの初期化失敗時はログでエンジン状態を確認してください。
