Skip to main content
← MCP Tools

get_graph_json

Return a subgraph around a symbol as structured JSON for graph renderers. Unlike the other context tools, get_graph_json returns the raw node and edge structure rather than token-budget-trimmed prose, so it is meant for programmatic consumers such as the VS Code graph panel and CI tooling. Pass mode: "overview" with no query for the repository overview tile layout instead of a symbol-centered subgraph.

This tool is the backend for the visual graph panel in the VS Code extension. The extension calls it automatically when you open the panel, so you do not normally invoke it by hand.

Availability: single-repo stdio (travsr mcp) and global stdio (travsr mcp --global). Not served over SSE.

Input schema​

{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Symbol name (1-200 chars). Resolved exact-first: full signature (e.g. 'fn:charge'), then exact bare name; substring matching is only a fallback when neither matches. May be empty when kind_filter is 'file' or mode is 'overview'."
},
"direction": {
"type": "string",
"enum": ["deps", "callers", "both"],
"description": "Edge direction. Default: both"
},
"depth": {
"type": "integer",
"minimum": 1,
"maximum": 4,
"description": "BFS depth. Default: 2"
},
"kind_filter": {
"type": "string",
"enum": ["file", ""],
"description": "'file' returns only file nodes and imports edges (project module map). Default: empty (all kinds)."
},
"provenance": {
"type": "string",
"enum": ["", "ratified", "tree-sitter", "lsif", "scip", "live"],
"description": "Restrict edges by how they were derived. Default empty returns everything, including unratified 'live' edges from uncommitted edits. Every edge in the response carries its own 'provenance' field."
},
"token_budget": {
"type": "integer",
"description": "Cap the payload to roughly this many tokens (0 or omitted = unlimited). Truncation is reported via truncated_by_budget. Single-repo sessions only; absent from the global schema."
},
"mode": {
"type": "string",
"enum": ["", "overview"],
"description": "'overview' returns directory-level component tiles plus cross-component dependency edges, ranked by how depended-upon each component is. Combine with path_prefix to drill into a component."
},
"path_prefix": {
"type": "string",
"description": "When mode='overview', scope to files under this path prefix (e.g. 'src/components/')."
},
"repo": {
"type": "string",
"description": "Repo name (run repos_list to discover). Only present in global (multi-repo) sessions. Always supply to avoid cross-repo noise; omit only when explicitly querying across all repos."
}
},
"required": [],
"additionalProperties": false
}

Output schema​

This tool genuinely returns JSON (the other graph query tools return plain text), and it is returned raw, not wrapped in a <travsr-data> envelope.

{
"type": "object",
"properties": {
"nodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string", "description": "Stable id for this node: path:signature for a symbol (e.g. crates/travsr-mcp/src/sanitize.rs:fn:wrap_envelope), corpus:path for a file. Not a bare Kythe VName." },
"label": { "type": "string", "description": "Display name, with native-language prefixes stripped." },
"kind": { "type": "string" },
"path": { "type": "string" },
"package": { "type": "string" },
"score": { "type": "number", "description": "Decays with hop distance from the query symbol (0.7^hop, rounded to 3 places), so the root at hop 0 scores 1.0." },
"line": { "type": ["integer", "null"], "description": "Definition line; null when the node has none, as for a file." },
"root": { "type": "boolean", "description": "true only on the seed node(s) at hop 0; omitted otherwise." }
}
}
},
"edges": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": { "type": "string" },
"target": { "type": "string" },
"kind": { "type": "string", "description": "e.g. 'imports', 'calls'." },
"provenance": { "type": "string" },
"heuristic": { "type": "boolean", "description": "Present (true) only on a 'calls' edge with provenance 'tree-sitter': the callee was matched by bare name, not resolved by a compiler/LSIF/SCIP pass. Omitted on every other edge." }
}
}
},
"coverage": {
"type": "object",
"properties": {
"language": { "type": "string" },
"semantic": { "type": "boolean", "description": "Whether full cross-file analysis has run for this language." },
"phase_b_commit": { "type": ["string", "null"] }
}
},
"token_budget": { "type": "integer", "description": "Present only when token_budget was supplied." },
"truncated_by_budget": { "type": "boolean", "description": "Present only when token_budget was supplied." },
"ambiguous": { "type": "boolean", "description": "Present only when query matched more than one candidate symbol." },
"candidates": { "type": "array", "description": "Present only alongside ambiguous: true." },
"signals": { "type": "array", "items": { "type": "string" }, "description": "Degraded-state notes, e.g. pending semantic analysis or index/HEAD drift. Omitted when there is nothing to report." }
}
}

Example​

Run against the Travsr repository itself (node and edge lists trimmed):

Request:

{
"query": "wrap_envelope",
"direction": "callers",
"depth": 1,
"token_budget": 300
}

Response:

{
"nodes": [
{
"id": "crates/travsr-mcp/src/sanitize.rs:fn:wrap_envelope",
"kind": "function",
"label": "wrap_envelope",
"line": 138,
"package": "",
"path": "crates/travsr-mcp/src/sanitize.rs",
"root": true,
"score": 1.0
},
{
"id": "crates/travsr-mcp/src/tools.rs:fn:get_callers",
"kind": "function",
"label": "get_callers",
"line": 646,
"package": "",
"path": "crates/travsr-mcp/src/tools.rs",
"score": 0.7
},
{
"id": "github.com/travsr-com/travsr:crates/travsr-mcp/src/sanitize.rs",
"kind": "file",
"label": "sanitize.rs",
"line": null,
"package": "",
"path": "crates/travsr-mcp/src/sanitize.rs",
"score": 0.7
}
],
"edges": [
{
"kind": "calls",
"provenance": "scip",
"source": "crates/travsr-mcp/src/tools.rs:fn:get_callers",
"target": "crates/travsr-mcp/src/sanitize.rs:fn:wrap_envelope"
},
{
"kind": "defines",
"provenance": "tree-sitter",
"source": "github.com/travsr-com/travsr:crates/travsr-mcp/src/sanitize.rs",
"target": "crates/travsr-mcp/src/sanitize.rs:fn:wrap_envelope"
}
],
"coverage": {
"language": "rust",
"phase_b_commit": "31e6385f",
"semantic": true
},
"token_budget": 300,
"truncated_by_budget": false
}

When to use​

Use get_graph_json when you need the graph structure itself, not a prose summary:

  • Rendering the live code graph in a UI, for example the Cytoscape.js panel in the VS Code extension.
  • Feeding the node and edge set into a custom integration or CI check.
  • Building your own visualisation or analysis on top of the graph.

For answering a natural language question within a token budget, use get_context instead. For a one-line structural answer such as "who calls this", use the targeted tools like get_callers or get_dependencies.

Token cost​

Without token_budget, the response is the complete subgraph: payload size is proportional to subgraph size, which grows with depth and the fan-out of the center node. Passing token_budget (single-repo sessions only) caps it and sets truncated_by_budget: true when nodes were cut to fit; the seed node itself is always kept even at a very small budget. The budget is charged for the JSON actually returned, including its envelope fields, and it applies to mode: "overview" and to a path_prefix drill-down as well as to a centered subgraph. When a budget cuts the list, edges whose endpoints were dropped go with them, and the node cap is reported only when it is what limited the result. Keep depth at 1 or 2 for dense symbols to keep the payload small.