Skip to main content

@ttsc/graph: An MCP Server That Gives AI Agents a Map of Your TypeScript Codebase

· 5 min read
Gergely Sipos
Gergely Sipos
Frontend Architect

AI coding agents waste a remarkable number of tokens just figuring out how your code connects. They open file after file, read imports, chase type definitions, and slowly build a mental model of architecture — burning through context windows and money in the process. @ttsc/graph takes a different approach: it hands the agent a compiler-resolved architecture graph upfront, so it can navigate by structure instead of reading source. It's early (v0.16), requires TypeScript v7 rc, and the benchmarks are vendor-supplied — but the idea is sharp enough to be worth knowing about. The author is Jeongho Nam (samchon), known for typia and nestia, which adds some credibility to the execution.

What it actually does​

@ttsc/graph is an MCP server that exposes a single tool: inspect_typescript_graph. Under the hood, it uses the real TypeScript compiler (the new typescript-go / TS v7 rc) to build a full dependency and type graph of your project.

The key design choice: it returns structural information only — names, edges, type signatures, file spans — never source code bodies. The agent gets a map, not the territory. It can see that UserService.create() calls validateInput() and returns Promise<User>, without reading either function's implementation.

The tool supports several operations:

  • tour — high-level project overview
  • entrypoints — find starting points into the graph
  • lookup — search for specific symbols
  • trace — follow dependency chains between nodes
  • details — get type signatures and relationships for a specific node
  • overview — summarize a module or directory
  • escape — break out of a subgraph back to a higher level

There's also a forced chain-of-thought mechanism inside the tool itself: the agent must formulate a question, draft a query plan, and review it before executing — pushing it toward the smallest possible query rather than broad reads.

The token savings claim​

The numbers from the author's benchmarks are attention-grabbing:

  • 77–86% token reduction on structural questions ("what calls what?", "what's the type of X?")
  • 94–95% fewer tool calls in Claude agent benchmarks
  • Roughly 10x reduction on "how does this work?" exploration questions

If you've been tracking Copilot's token efficiency work, you know every token has a dollar sign attached now. A tool that cuts navigation tokens by 80% on a large codebase would meaningfully change the cost profile of agentic sessions.

Honest caveat: these are vendor-published benchmarks against the author's own test cases. Independent verification on real-world projects is still pending. The claims are specific and measurable though, which makes them falsifiable — a good sign.

Setup​

caution

@ttsc/graph requires TypeScript v7 rc (the new Go-based compiler). It will not work with stable TypeScript 5.x. If your project isn't ready to try TS v7, this tool isn't for you yet.

Install the dependencies:

npm install -D ttsc @ttsc/graph typescript@rc

Add the MCP server to your .mcp.json (works with Claude Code, Codex, Cursor, or any MCP-capable agent):

.mcp.json
{
  "mcpServers": {
    "ttsc-graph": {
      "command": "npx",
      "args": ["-y", "@ttsc/graph"]
    }
  }
}

That's it. The agent will discover the inspect_typescript_graph tool and start using it for navigation.

tip

Not sure if this is worth your time? Run npx @ttsc/graph view to open a 3D visualization of your project's dependency graph in the browser. It's a zero-commitment way to see what the tool actually resolves from your codebase.

The ttsc ecosystem​

@ttsc/graph is one piece of a broader TypeScript-Go compiler toolchain by samchon:

  • ttsc — the compiler itself, with plugin support (like ts-patch but for TS v7)
  • ttsx — execute TypeScript with full type checking (like ts-node for the new compiler)
  • @ttsc/lint — surface lint violations as compiler errors rather than a separate tool pass
  • @ttsc/unplugin — integrates with Vite, Webpack, esbuild, and other bundlers

The plugin ecosystem includes typia (runtime type validators from TS types) and nestia (NestJS SDK generation). Everything is MIT licensed.

Should you try it?​

Caveats worth weighing:

  • v0.16 — this is pre-1.0 software
  • TypeScript v7 rc dependency limits who can use it today
  • Solo maintainer (prolific, but still one person)

Strengths:

  • MIT licensed, specific measurable claims, low risk to evaluate
  • Uses the actual type resolver — not regex, not tree-sitter, not an LLM summary
  • Single-purpose design (like the MDN MCP Server, focused single-purpose tools tend to work better than kitchen-sink approaches)

Differentiator vs. alternatives like codegraph or codebase-memory-mcp: @ttsc/graph is TypeScript-specific and uses the real compiler's type resolution. It knows about generics, overloads, and inferred types because it has the same information the compiler does. General-purpose code graph tools work from syntax; this works from semantics.

Bottom line: Worth a npx @ttsc/graph view on your next exploration session — not a dependency in your CI pipeline just yet.