# MCP 伺服器

提供 agent `list_rag` 與 `search_rag` 兩個工具的 Model Context Protocol（MCP）伺服器，走 stdio，或選擇性走 HTTP。

## 傳輸方式

| 傳輸 | 啟動 | 程序 | 說明 |
|---|---|---|---|
| stdio | `kura mcp` | 由 MCP client 啟動的獨立程序 | 自行開啟每個已註冊資料庫的 `data.db`，不執行 watcher；開啟失敗的資料庫會被略過 |
| Streamable HTTP | `kura remote enable` | 執行中的 daemon，位於 `<endpoint>/mcp` | 預設關閉；路由在 daemon 啟動時決定，啟用時會重啟執行中的 daemon |

兩種傳輸共用同一份伺服器定義：名稱 `kuradb`、下方的伺服器 instructions，以及相同的兩個工具。工具呼叫直接進入 `search.Search`，結果與 [HTTP API](/zh/http-api) 一致。

## Client 設定

Claude Code，stdio：

```bash
claude mcp add kura -- kura mcp
```

讀取 `mcpServers` JSON 檔的任何 client，stdio：

```json
{
  "mcpServers": {
    "kura": { "command": "kura", "args": ["mcp"] }
  }
}
```

Claude Code，HTTP（先固定連接埠，讓 URL 保持不變）：

```bash
kura port set 23456
kura remote enable
claude mcp add --transport http kura http://localhost:23456/mcp
```

伺服器送出的 instructions 會告訴 agent：不知道資料庫名稱時先呼叫 `list_rag`，再呼叫 `search_rag`；並說明伺服器只存已索引的檔案，沒有對話紀錄或 session 記憶。

## 工具：list_rag

不需參數，回傳格式與 `GET /api/list` 相同：

```json
{ "loaded": ["notes"], "registered": [{ "db": "notes", "createAt": "2026-10-21T07:13:55Z" }] }
```

## 工具：search_rag

| 參數 | 型別 | 必填 | 規則 |
|---|---|---|---|
| `db` | string | 是 | 目標資料庫名稱；去除前後空白 |
| `q` | string | 是 | 以空白分隔的關鍵字；去除前後空白 |
| `limit` | integer | 否 | 1 到 100，預設 10；不合法的值改用 10 |
| `mode` | string | 否 | 只有 `keyword`；不分大小寫，省略即使用 |

結構化結果為 `{"keyword": [{"source": ..., "matches": [{"chunk": ..., "content": ...}]}]}`。沒有命中時省略 `keyword` 欄位，結果為 `{}`。資料庫不存在等驗證錯誤會以 `isError: true` 的工具錯誤回傳，訊息如 `invalid argument: "x" not exist`。

## 相關頁面

- [關鍵字搜尋](/zh/keyword-search)
- [設定](/zh/configuration)
- [CLI 指令](/zh/cli-reference)