AST API and Code Graph MCP

Getting started

Open the project in Termdock and enable Code Analysis for that workspace. HTTP defaults to port 3033 in production and 3032 in development; AST_API_PORT can override it. Use termdock hostinfo --json to discover the running app’s ports. Explicitly pass workspace to avoid querying whichever workspace is currently active.

curl -s "http://127.0.0.1:3033/api/workspaces"
curl -s "http://127.0.0.1:3033/api/search?q=UserService&workspace=<wsId>&limit=10"

Search data is an array of hits containing symbolId, name, type, file, line, column, and relevance. Use symbolId for callers, callees, and impact queries. Search line and column are zero-based; add one when displaying a source line.

HTTP queries

GET  /api/workspaces
GET  /api/workspaces/:id
GET  /api/search?q=<name>&workspace=<wsId>&limit=10
GET  /api/graph/deps?file=src/path/to/file.ts&workspace=<wsId>
GET  /api/graph/importers?file=src/path/to/file.ts&workspace=<wsId>
GET  /api/graph/callers?to=<symbolId>&workspace=<wsId>
GET  /api/graph/calls?from=<symbolId>&workspace=<wsId>
GET  /api/impact?symbolId=<id>&depth=2&workspace=<wsId>
POST /api/graph/callers/batch
POST /api/index/update

• deps returns imports and exports for a file. Prefer workspace-relative paths. importers returns file, importers, and count.
• callers returns incoming call edges; calls returns outgoing edges. These describe relationships found by the index, not a guarantee of every runtime call.
• impact recursively collects callers with depth 1–3. Check results and read the affected source before changing behavior.
• callers/batch takes JSON { symbolIds: [...], workspace: "..." }, with up to 50 symbol IDs. index/update takes JSON { workspace: "..." } to update the index.

Code graph and LSP

Since 1.16, Express, Fastify, Koa, FastAPI, and Flask routes become graph nodes linked to handlers and middleware. Diff impact analysis maps changed code to symbols and callers. Full indexing uses the Rust pipeline.

Since 1.21, UI nodes can request additional callees from the LSP. The HTTP callers query adds available LSP edges for indexed project symbols and reports lsp.targets alongside data. If the language server is unavailable or fails, static edges remain; inspect the LSP availability status instead of interpreting no extra edges as no callers.

Code Graph MCP server

The stdio server reads a Termdock-built index and binds to a project with --path. Open and index that project in the app first. It is read-only and does not rebuild the index. The launcher below needs the built dist/main/ast-mcp.js next to the app’s scripts directory; use the actual installed or built path.

node /path/to/Termdock/scripts/termdock-ast-mcp.js --path /path/to/project

• termdock_context: query or task; optional maxNodes, maxSnippets, maxBytes, includeCode. Returns budgeted context for a task.
• termdock_search: query, optional maxResults. Find symbol locations.
• termdock_callers / termdock_callees: filePath, optional symbol. Inspect directional call edges.
• termdock_impact: symbolId, optional depth. Recursively collect callers.
• termdock_node: symbolId, optional includeCode. Read symbol details.
• termdock_status: index/workspace status. termdock_files: indexed file list.

Index coverage and freshness bound the results. Empty results do not prove a symbol is unused. Verify the workspace and source, update the index in the app when needed, and search again after code changes rather than reusing stale IDs.

Install the skill

Use Settings > Skills to install termdock-ast for a supported AI tool. Check its installed instructions for the configured API or MCP path. Use literal text search when you already know the exact file or only need a string match.