typegraph

typegraph-mcp

Supercharge your AI coding agent with TypeScript superintelligence.

14 semantic navigation tools delivered via the Model Context Protocol so any MCP-compatible agent can use them.

• Instant type resolution — hover info, generics, inferred types without reading files
• Instant call tracing — follow a symbol from handler to implementation in one call
• Instant impact analysis — "what breaks if I change this?" across the entire codebase
• Instant dependency mapping — what imports what, direct and transitive, by package
• Instant cycle detection — circular imports found in <1ms
• Zero false positives — semantic references, not string matches

The problem

AI coding agents navigate TypeScript blind. They grep for a symbol name and get string matches instead of real references. They read entire files to find a type that's re-exported through three barrel files. They can't tell you what depends on what, or whether your refactor will break something two packages away.

Every wrong turn burns context tokens and degrades the agent's output.

The difference

Measured on a real 440-file TypeScript monorepo:

	grep	typegraph-mcp
Context tokens	~113,000	1,006
Files touched	47	3
False positives	dozens	0
Barrel file resolution	reads 6 files, still guessing	1 tool call, exact source
Cross-package impact	1,038 string matches	31 direct + 158 transitive, by package
Circular dependency detection	impossible	instant
Avg latency (semantic)	n/a	16.9ms
Avg latency (graph)	n/a	0.1ms

99% context reduction. 100% accuracy. Full benchmarks.

Before: grep-based navigation

Agent: I need to find where createUser is implemented.
  → grep "createUser" across project
  → 47 results: test files, comments, variable names, string literals, actual definitions
  → reads 6 files trying to follow the chain
  → burns ~113,000 tokens, still not sure it found the right implementation

After: typegraph-mcp

Agent: ts_trace_chain({ file: "src/handlers.ts", symbol: "createUser" })
  → 3-hop chain: handlers.ts → UserService.ts → UserRepository.ts
  → each hop shows the exact line with a code preview
  → 1,006 tokens, done

Quick start

Step 1: Install

cd /path/to/your-ts-project
npx typegraph-mcp setup

The interactive setup auto-detects your AI agents, installs the plugin into ./plugins/typegraph-mcp/, registers the MCP server, copies workflow skills, appends agent instructions, and runs verification. Use --yes to skip prompts.

Step 2: Launch your agent

Claude Code — load the plugin for the full experience:

claude --plugin-dir ./plugins/typegraph-mcp

This gives you 14 MCP tools, 5 workflow skills that teach Claude when and how to chain tools, /typegraph:check, /typegraph:test, and /typegraph:bench slash commands, and a SessionStart hook for dependency verification.

Other agents (Cursor, Codex CLI, Gemini CLI, GitHub Copilot) — restart your agent session. The MCP server and skills are already configured.

For Codex CLI, setup now writes a project-local .codex/config.toml entry using absolute paths so the tools stay scoped to the project and still work when Codex launches from a subdirectory.

First query takes ~2s (tsserver warmup). Subsequent queries: 1-60ms.

Requirements

• Node.js >= 22
• TypeScript >= 5.0 in the target project
• npm for dependency installation

Tools

Semantic queries (tsserver)

Tool	Description
ts_find_symbol	Find a symbol's location in a file by name
ts_definition	Go to definition — resolves through imports, re-exports, barrel files, generics
ts_references	Find all semantic references (not string matches)
ts_type_info	Get type and documentation — same as VS Code hover
ts_navigate_to	Search for a symbol across the entire project
ts_trace_chain	Follow definition hops automatically, building a call chain
ts_blast_radius	Analyze impact of changing a symbol — all usage sites and affected files
ts_module_exports	List all exports from a module with resolved types

Import graph queries (oxc-parser + oxc-resolver)

Tool	Description
ts_dependency_tree	Transitive dependency tree of a file
ts_dependents	All files that depend on a given file, grouped by package
ts_import_cycles	Detect circular import dependencies
ts_shortest_path	Shortest import path between two files
ts_subgraph	Extract the neighborhood around seed files
ts_module_boundary	Analyze module coupling: incoming/outgoing edges, isolation score

CLI