# MCP Tools

Reference for the two read-only MCP tools, `list_rag` and `search_rag`, their errors, and why their names are fixed.

## `list_rag`

Lists the databases that can be searched. It takes no arguments.

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

`loaded` names are queryable in this process; `registered` entries are re-read from `db.json` on each call. A database added after startup appears only in `registered`.

## `search_rag`

Searches one database and returns file chunks grouped by source.

| Parameter | Required | Default | Behavior |
|---|---|---|---|
| `db` | Yes | — | Target database name, as reported by `list_rag`; surrounding whitespace is trimmed |
| `q` | Yes | — | Query text; surrounding whitespace is trimmed |
| `mode` | No | Both | `keyword` or `semantic`; omit to run both |
| `limit` | No | `10` | Maximum chunks per mode, 1–100; other values fall back to 10 |

The schema declares the `mode` enum, the required fields, and the `limit` default, so the SDK validates arguments and applies defaults before the handler runs. An invalid enum value or a missing required field is rejected as a tool error without touching SQLite.

Structured output mirrors the REST response, except that branches which did not run or returned no chunks are omitted:

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

Every call returns both a JSON text block and `structuredContent`, so clients that understand output schemas and clients that only read text both work.

## Errors

| Condition | Result |
|---|---|
| Unknown `mode`, missing `db` or `q` | Rejected by schema validation, returned as a tool error |
| `q` present but empty after trimming | Tool error: `invalid argument: q is required` |
| Database not loaded (including an empty `db`) | Tool error: `invalid argument: "name" not exist` |
| Keyword or semantic branch failure | Tool error carrying the underlying message |

Argument mistakes are reported through `search.ErrInvalidArgument`. The REST transport maps that sentinel to HTTP 400; the MCP transport lets the SDK mark the result with `isError`.

## Tool naming

The tool names and parameters match the KuraDB client tools already shipped by [Agenvoy](https://github.com/pardnchiu/Agenvoy), so a consumer can switch from its own HTTP wrapper to this MCP server without rewriting prompts. Renaming a tool or changing a parameter requires updating both sides.