# MCP Tools

兩個唯讀 MCP tool `list_rag` 與 `search_rag` 的參考、錯誤處理，以及其名稱為何固定。

## `list_rag`

列出可搜尋的資料庫，不需要參數。

```json
{
  "loaded": ["notes"],
  "registered": [
    { "db": "notes", "createAt": "2026-07-14T07:00:00Z" }
  ]
}
```

`loaded` 是這個 process 內可查詢的名稱；`registered` 每次呼叫都從 `db.json` 重新讀取。啟動後才新增的資料庫只會出現在 `registered`。

## `search_rag`

搜尋單一資料庫，回傳依 source 分組的 file chunk。

| 參數 | 必填 | 預設 | 行為 |
|---|---|---|---|
| `db` | 是 | — | 目標資料庫名稱，由 `list_rag` 取得；前後空白會被去除 |
| `q` | 是 | — | 查詢文字；前後空白會被去除 |
| `mode` | 否 | 兩者 | `keyword` 或 `semantic`；省略則兩者都跑 |
| `limit` | 否 | `10` | 每個 mode 最多回傳的 chunk 數，1–100；其他值 fallback 為 10 |

schema 內宣告了 `mode` 的 enum、必填欄位與 `limit` 的 default，因此 SDK 會在 handler 執行前完成驗證與套用預設值。非法 enum 值或缺少必填欄位會直接以 tool error 回絕，不會碰到 SQLite。

結構化輸出與 REST response 一致，但沒跑或無結果的分支不會出現：

```json
{
  "keyword": [
    {
      "source": "/Users/example/.config/kuradb/notes/inbox/rag.md",
      "matches": [{ "chunk": 1, "content": "RAG combines retrieval with generation." }]
    }
  ]
}
```

每次呼叫都同時回傳 JSON 文字區塊與 `structuredContent`，因此支援 output schema 的 client 與只讀文字的 client 都能運作。

## 錯誤

| 情況 | 結果 |
|---|---|
| 未知 `mode`、缺少 `db` 或 `q` | 由 schema 驗證擋下，以 tool error 回傳 |
| 有 `q` 但去除空白後為空 | Tool error：`invalid argument: q is required` |
| 資料庫未載入（含空白的 `db`） | Tool error：`invalid argument: "name" not exist` |
| Keyword 或 semantic 分支失敗 | Tool error，附帶底層錯誤訊息 |

參數錯誤一律以 `search.ErrInvalidArgument` 標記。REST transport 把這個 sentinel 對應到 HTTP 400；MCP transport 則交給 SDK 標記為 `isError`。

## Tool 命名

Tool 名稱與參數對齊 [Agenvoy](https://github.com/pardnchiu/Agenvoy) 既有的 KuraDB client tool，因此消費端可以從自家 HTTP wrapper 換成這個 MCP server 而不必改寫 prompt。要改 tool 名或參數時，兩邊必須同步。