MCP Tools

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

`list_rag`

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

{
  "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 一致，但沒跑或無結果的分支不會出現：

{
  "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 既有的 KuraDB client tool，因此消費端可以從自家 HTTP wrapper 換成這個 MCP server 而不必改寫 prompt。要改 tool 名或參數時，兩邊必須同步。