MCP Tools Reference
Travsr exposes its tools over the Model Context Protocol, all using JSON-RPC 2.0. How many you see depends on how the server was started:
| Transport | Command | Tools |
|---|---|---|
| Single-repo stdio | travsr mcp | 28 |
| Global (multi-repo) stdio | travsr mcp --global | 17 |
| SSE | travsr serve | 7 |
Global stdio omits get_architecture_brief, get_subsystem_brief, repo_languages, the six synonym_* tools, repos_prune, and repos_remove. SSE serves only get_dependencies, get_callers, get_blast_radius, get_lang_status, search_symbol, get_repo_map, and get_execution_path, and it does not implement tools/list (the call returns METHOD_NOT_FOUND), so an SSE client has to call those tools by name.
In the tables below, all means all three transports, stdio means single-repo and global stdio but not SSE, and single-repo means single-repo stdio only.
Graph query tools
| Tool | What it returns | Availability |
|---|---|---|
get_dependencies | Direct and transitive imports for a file | all |
get_callers | All call sites of a symbol | all |
find_references | Every use site of a symbol, not just calls | stdio |
find_pattern | Textual git grep search for what the graph cannot model | stdio |
get_blast_radius | Files that would break if this file changes | all |
search_symbol | Symbol definition locations by name | all |
get_repo_map | Structural overview of a repository | all |
get_architecture_brief | Components, weighted dependencies, layering, and cycles for the whole repo | single-repo |
get_subsystem_brief | Call spine, external contracts, and callers for one subsystem | single-repo |
get_execution_path | Lowest-cost path (Dijkstra plus a λ-corridor) between two symbols | all |
get_context | Full PPR + knapsack context for a query (synonym-aware) | stdio |
get_graph_stats | Exact node/edge counts + schema version | stdio |
get_graph_json | Raw subgraph as node/edge JSON for renderers | stdio |
get_snippets | Kind-aware source snippets for named symbols | stdio |
get_lang_status | Whether semantic (Phase B) analysis is active for a file's language | all |
Observability tools
Every tool above answers a question about your code. These answer questions about the index those answers came from, which is what lets an agent tell "there are no callers" from "the graph cannot see them yet".
| Tool | What it returns | Availability |
|---|---|---|
get_index_status | Freshness, counts, Phase A/B state per language, semantic readiness | stdio |
get_daemon_logs | Recent daemon log entries, severity-filtered and redacted | stdio |
get_graph_health | Integrity report: ghost paths, orphan edges, lexical parity | stdio |
All three are read-only. They are served over single-repo and global stdio, not over SSE.
Repo management tools
| Tool | What it does | Availability |
|---|---|---|
repo_languages | Per-language node counts for the indexed repo | single-repo |
repos_list | All repos in the Travsr registry with DB existence status | stdio |
repos_prune | Remove registry entries whose DB file no longer exists | single-repo |
repos_remove | Remove one registry entry by name | single-repo |
repos_prune and repos_remove mutate the registry and are withheld from global stdio; repos_list is read-only and is served there (#374). None of the four is served over SSE.
Synonym tools (single-repo stdio only)
| Tool | What it does |
|---|---|
synonym_list | List all synonym pairs |
synonym_add | Add an alias to a term |
synonym_set | Replace all aliases for a term |
synonym_remove | Remove one exact term/alias pair |
synonym_remove_term | Remove all aliases for a term in one call |
synonym_reset | Restore built-in synonym defaults |
Hidden diagnostics
Two diagnostic tools are served in single-repo stdio only and are deliberately left out of tools/list, so an agent calls them by name: seed_trace (the full seed-selection trace for a query) and embed_knn_probe (the raw embedding KNN ranking for a query, with no fusion). They are tuning instruments, not retrieval paths.
JSON Schema conventions
All tools accept a single JSON object. Required fields are marked "required": [...]. Paths are relative to the repository root. The repo parameter exists only in global (travsr mcp --global) sessions and on SSE, where it selects one registered repo; a single-repo session is bound to one repository and its schemas do not take repo (the one exception is get_snippets, whose single-repo schema lists repo but documents it as global-only). Use dot notation for symbols (ClassName.methodName) or #-qualified signatures (src/auth/jwt.ts#sign).
How tools report problems
Travsr does not use a structured error envelope or error codes. Every tool returns plain text (a content: [{ "type": "text", "text": "..." }] block, per the MCP spec), and a problem is reported as a short, specific sentence in that same text rather than as a separate error object:
- An argument that does not resolve (an unknown file, an unrecognized symbol, an unknown
repoin global mode) gets a sentence naming what was tried and what to do instead, for example:no file matched 'auth.ts'; get_dependencies takes a repo-relative file path (run get_repo_map to list files). - An invalid enum-like argument (an unrecognized
provenance, an unknown component name) names the valid values or lists the real ones from this repo. - A write tool (the
synonym_*mutators) returnsokon success, or the underlying store error as plain text on failure, such as the 200-row synonym cap message. get_index_status,get_daemon_logs,get_graph_health, andget_lang_statusgenuinely return a JSON object (see each tool's own page), and for these four a resolution failure there comes back as{"error": "..."}inside that JSON rather than as plain text.- An argument that breaks the tool's advertised schema is rejected before the tool runs, with a sentence naming the problem:
<tool>: unknown argument `x`; expected one of: ...,<tool>: missing required argument `x`,<tool>: `x` must not be empty, a wrong type, or<tool>: `x` must be a non-negative integer, got -1. Previously a misspelled or mistyped argument ran the tool on an empty value. An integer or boolean sent as a string ("6000","true") is converted first, because some clients send every argument that way.enumvalues are not enforced here: a tool with a sensible fallback (an unknownget_daemon_logslevel reads asinfo) keeps it. - A long-lived
travsr mcp --stdioprocess keeps running the build it started with. If thetravsrbinary on disk has since changed, each text response carries[note: this MCP server is running a different build than the travsr binary on disk; ...]inside its envelope. Reconnect the MCP server to pick up the new build.get_graph_jsonis left untouched so its JSON stays parseable, and the note never appears over SSE. get_graph_jsonalso returns JSON: the node/edge payload described on its page.get_callers,find_references, andget_execution_pathreturn a{"status":"pending","message":"..."}JSON object instead of their usual text when the semantic (Phase B) index has never finished for the repo.
There is no GRAPH_STALE or BUDGET_EXCEEDED style code to match on. Check get_index_status directly if you need to know whether the graph is stale before trusting an answer.
The <travsr-data> envelope
Most responses are sanitised and wrapped in a <travsr-data>...</travsr-data> envelope so a model reads them as data rather than instructions; inside it, < and > from source text are escaped as < and >. Some tools return their text raw instead: get_graph_stats, get_graph_json, get_lang_status, repo_languages, the synonym_* tools, and the repos_* tools, as does the pending JSON above. Bracketed [note: ...] lines about index freshness can also sit just outside the closing tag.