Skip to main content

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:

TransportCommandTools
Single-repo stdiotravsr mcp28
Global (multi-repo) stdiotravsr mcp --global17
SSEtravsr serve7

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​

ToolWhat it returnsAvailability
get_dependenciesDirect and transitive imports for a fileall
get_callersAll call sites of a symbolall
find_referencesEvery use site of a symbol, not just callsstdio
find_patternTextual git grep search for what the graph cannot modelstdio
get_blast_radiusFiles that would break if this file changesall
search_symbolSymbol definition locations by nameall
get_repo_mapStructural overview of a repositoryall
get_architecture_briefComponents, weighted dependencies, layering, and cycles for the whole reposingle-repo
get_subsystem_briefCall spine, external contracts, and callers for one subsystemsingle-repo
get_execution_pathLowest-cost path (Dijkstra plus a λ-corridor) between two symbolsall
get_contextFull PPR + knapsack context for a query (synonym-aware)stdio
get_graph_statsExact node/edge counts + schema versionstdio
get_graph_jsonRaw subgraph as node/edge JSON for renderersstdio
get_snippetsKind-aware source snippets for named symbolsstdio
get_lang_statusWhether semantic (Phase B) analysis is active for a file's languageall

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

ToolWhat it returnsAvailability
get_index_statusFreshness, counts, Phase A/B state per language, semantic readinessstdio
get_daemon_logsRecent daemon log entries, severity-filtered and redactedstdio
get_graph_healthIntegrity report: ghost paths, orphan edges, lexical paritystdio

All three are read-only. They are served over single-repo and global stdio, not over SSE.

Repo management tools​

ToolWhat it doesAvailability
repo_languagesPer-language node counts for the indexed reposingle-repo
repos_listAll repos in the Travsr registry with DB existence statusstdio
repos_pruneRemove registry entries whose DB file no longer existssingle-repo
repos_removeRemove one registry entry by namesingle-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)​

ToolWhat it does
synonym_listList all synonym pairs
synonym_addAdd an alias to a term
synonym_setReplace all aliases for a term
synonym_removeRemove one exact term/alias pair
synonym_remove_termRemove all aliases for a term in one call
synonym_resetRestore 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 repo in 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) returns ok on 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, and get_lang_status genuinely 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. enum values are not enforced here: a tool with a sensible fallback (an unknown get_daemon_logs level reads as info) keeps it.
  • A long-lived travsr mcp --stdio process keeps running the build it started with. If the travsr binary 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_json is left untouched so its JSON stays parseable, and the note never appears over SSE.
  • get_graph_json also returns JSON: the node/edge payload described on its page.
  • get_callers, find_references, and get_execution_path return 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 &lt; and &gt;. 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.