MCP tools
kivgraph serve registers twelve tools over stdio once a generation is
published. Eleven are read-only. index_project is the only one that mutates
anything, and only after explicit consent. A server with no published
generation registers index_project alone; see
Before a generation is published.
Every tool answers from the published HotSnapshot. serve does not open the
database and does not run the TypeScript worker.
Pick the tool by the question
Section titled “Pick the tool by the question”| The question | The tool |
|---|---|
| I do not know its name; which files do I open | find_by_intent |
| Who calls this, what references this | find_references |
| What breaks if I change this | get_blast_radius |
| What does this reach outwards | trace_dependencies |
| Who uses it from another repository | find_cross_repo_consumers |
| Where is it declared | find_symbol |
| What is declared in this package | get_file_outline |
| Give me the code of these symbols | get_source |
| Everything known about one symbol | get_symbol |
| What is indexed, and is it current | graph_status |
| Which repositories are registered | list_repositories |
| Index a project and rebuild | index_project |
Edges are resolved by language analyzers, never by matching names, and the
resolution is not uniform across the five languages: Go, TypeScript and Rust
edges are type-checked; Dart edges are resolved by Dart Analysis Server; Python
uses exact semantic facts when a configured analyzer provides them and
CANDIDATE facts in its bundled AST fallback. Where the edge is type-checked,
an empty reference list means nobody calls it, and two homonymous methods are
two different symbols. grep can say neither.
It is not always the cheaper route either way. On the 29-question benchmark
grep costs fewer tokens than these tools on five questions — rare names in a
single repository, where both sides answer correctly. See the
comparison.
See Using it from an agent for the response envelope, the cursor
contract, and how to read coverage, guidance and completeness.
Reference
Section titled “Reference”Read-only, symbols and source:
Read-only, graph traversal:
Read-only, the index itself:
Mutating:
Addressing a symbol
Section titled “Addressing a symbol”Every tool that takes a symbol accepts either a stable_key or the triple
repository, repository-relative path and qualified_name — exactly one of
the two. Supplying both is rejected rather than resolved quietly, because two
selectors can disagree and answering one of them answers a question nobody
asked.
Every row a tool returns already carries a repository, a path, a qualified name and a line range, so the next call is built from the answer just received and stable keys never have to enter the conversation.
Before a generation is published
Section titled “Before a generation is published”With no published generation there is no query surface. The server completes
the handshake, publishes only index_project, and puts the rebuild command in
its instructions.
A client launches the process itself, so exiting would read as a crash, and
publishing tools that answer INDEX_NOT_READY to everything would teach the
agent that the tools do not work. See
Troubleshooting.
One channel per response
Section titled “One channel per response”No tool publishes an outputSchema. With one, the SDK marshals the typed
result into structuredContent and repeats the same JSON in the text block, so
the response is paid for twice.
get_source goes further and answers in prose:
source inside a JSON string costs more than the same source as text.