v0.6.0
Home GitHub

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.

{
  "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:

{
  "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, 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.

中文