Trace Mcp

trace-mcp

AI agents recompute the same work. trace-mcp makes them reuse instead. The recomputation → reuse layer for AI systems.

40–50% fewer tokens on average  ·  up to 2× effective capacity  ·  up to 99% less redundant processing

Based on early benchmarks across agent workflows with repeated context and dependency traversal.

> AI systems don't scale because they recompute instead of reuse. Every turn, the agent re-reads the same files, re-traverses the same dependencies, and re-inflates the context window with structure it already discovered. Token bills grow. Latency grows. Reasoning quality drops. The model isn't the bottleneck — the recomputation leak is. > > trace-mcp builds a framework-aware graph of your codebase once, then serves it through MCP so the agent reasons from a precomputed structure instead of brute-reading the repo. Ask "what breaks if I change this model?" — instead of 80 Grep calls and 190 file reads, the agent calls get_change_impact once and gets the blast radius across PHP, Vue, migrations, and DI. One tool call replaces ~42 minutes of agent exploration. 81 framework integrations across 80 languages, 170 tools. > > The same engine indexes markdown vaults. [[wikilinks]] become first-class edges, frontmatter and #tags become metadata, headings become nested sections. find_usages returns backlinks. apply_rename rewrites every link to a renamed note. One MCP for code and knowledge — no second tool to plug in.

Also ships a desktop app with a GPU graph explorer over the same index.

---

Why this matters

AI is bottlenecked not by models, but by recomputation. Agents treat the context window like a database — they re-read the same files, re-traverse the same dependencies, and re-inflate context every turn with structure they already computed five steps ago. Token bills, latency, and hallucinations all grow with project size instead of with task complexity.

trace-mcp closes the recomputation leak. The graph is built once, kept incrementally fresh, and served to every agent that asks — so the same work isn't paid for over and over.

• Lower cost — fewer tokens per successful answer, on average and at peak
• Lower latency — fewer sequential tool calls, fewer round-trips to the model
• Higher accuracy — less noise in context means fewer hallucinations and stronger first-response correctness
• Production stability — context that scales with project size, not against it

We started with code intelligence — the hardest, noisiest context most agents handle today — and the same engine now indexes markdown knowledge vaults (Obsidian, Logseq, plain MD) as a peer domain. Wikilinks, tags, frontmatter, and embeds become graph edges and symbol metadata; search, find_usages, get_change_impact, and apply_rename work identically over both.

---

What trace-mcp does for you

| You ask | trace-mcp answers | How | |---|---|---| | "What breaks if I change this model?" | Blast radius across languages + risk score + linked architectural decisions | get_change_impact — reverse dependency graph + decision memory | | "Why was auth implemented this way?" | The actual decision record with reasoning and tradeoffs | query_decisions — searches the decision knowledge graph linked to code | | "I'm starting a new task" | Optimal code subgraph + relevant past decisions + dead-end warnings | plan_turn — opening-move router with decision enrichment | | "What did we discuss about GraphQL last month?" | Verbatim conversation fragments with file references | search_sessions — FTS5 search across all past session content | | "Show me the request flow from URL to rendered page" | Route → Middleware → Controller → Service → View with prop mapping | get_request_flow — framework-aware edge traversal | | "Find all untested code in this module" | Symbols classified as "unreached" or "imported but never called in tests" | get_untested_symbols — test-to-source mapping | | "What's the impact of this API change on other services?" | Cross-subproject client calls with confidence scores | get_subproject_impact — topology graph traversal | | "What notes link to this concept?" | Backlinks across the vault, with section + alias context | find_usages on a note: symbol | | "What breaks if I rename this note?" | Every [[wikilink]] and [text](path.md) that references it | get_change_impact — wikilink-aware reverse graph |

Four things no other tool does:

1. Framework-aware edges — trace-mcp understands that Inertia::render('Users/Show') connects PHP to Vue, that @Injectable() creates a DI dependency, that $user->posts() means a posts table from migrations. 58 integrations across 15 frameworks, 7 ORMs, 13 UI libraries.

1. Code-linked decision memory — when you record "chose PostgreSQL for JSONB support", it's linked to src/db/connection.ts::Pool#class. When someone runs get_change_impact on that symbol, they see the decision. MemPalace stores decisions as text; trace-mcp ties them to the dependency graph.

1. Cross-session intelligence — past sessions are mined for decisions and indexed for search. When you start a new session, get_wake_up gives you orientation in ~300 tokens; plan_turn shows relevant past decisions for your task; get_session_resume carries over structural context from previous sessions.

1. Code and knowledge in one graph — point trace-mcp at a markdown vault (Obsidian, Logseq, plain MD) and the same engine indexes it: each note becomes a note: symbol, headings become nested sections, [[wikilinks]] and ![[embeds]] become graph edges, frontmatter and #tags ride on metadata. PageRank, Signal Fusion ranking, embeddings, and rename refactoring all apply unchanged. The agent does not learn a second tool — it learns one graph that happens to contain both your codebase and your second brain.

---

The problem

AI coding agents recompute the same work every turn — and they're framework-blind while doing it.

They re-read UserController.php, then re-read it again next turn. They don't know that Inertia::render('Users/Show', $data) connects a Laravel controller to resources/js/Pages/Users/Show.vue. They don't know that $user->posts() means the posts table defined three migrations ago. They can't trace a request from URL to rendered pixel — so they trace it again, and again, every session.

The result: 5–15× repeated reads of hot files in a single task, context windows used as scratch databases, and agents that get more expensive the bigger the project gets — instead of more capable.

The solution

trace-mcp builds a cross-language dependency graph from your source code and exposes it through the Model Context Protocol — the plugin format Claude Code, Cursor, Windsurf and other AI coding agents speak. Any MCP-compatible agent gets framework-level understanding out of the box.

| Without trace-mcp | With trace-mcp | |---|---| | Agent reads 15 files to understand a feature | get_task_context — optimal code subgraph in one shot | | Agent doesn't know which Vue page a controller renders | routes_to → renders_component → uses_prop edges | | "What breaks if I change this model?" — agent guesses | get_change_impact traverses reverse dependencies across languages | | Schema? Agent needs a running database | Migrations parsed — schema reconstructed from code | | Prop mismatch between PHP and Vue? Discovered in production | Detected at index time — PHP data vs. defineProps |

---

Desktop app

trace-mcp ships with an optional Electron desktop app (packages/app) that gives you a visual surface over the same index the MCP server uses. It manages multiple projects, wires up MCP clients, and provides a GPU-accelerated graph explorer — all without opening a terminal.

Projects & clients. The menu window lists indexed projects with live status (Ready / indexing / error) and re-index / remove controls. The MCP Clients tab detects installed clients (Claude Code, Claw Code, Claude Desktop, Cursor, Windsurf, Continue, Junie, JetBrains AI, Codex, AMP, Warp, Factory Droid) and wires trace-mcp into them with one click, including enforcement level (Base / Standard / Max — CLAUDE.md only, + hooks, + tweakcc & agent-behavior rules; Max-tier features are Claude Code–specific). Warp and JetBrains AI require manual paste in the IDE because their config storage is GUI-only.

Per-project overview. Each project opens in its own tabbed window: Overview (files, symbols, edges, coverage, linked services, re-index), Ask (natural-language query over the index), and Graph. Overview also surfaces Most Symbols files, last-indexed timestamp, and the dependency coverage meter.

GPU graph explorer. The Graph tab renders the full dependency graph on the GPU via cosmos.gl — tens of thousands of nodes/edges at interactive frame rates. Filter by Files / Symbols, overlay detected communities, highlight groups, toggle labels/FPS, and step through graph depth. Good for getting a feel for coupling, hotspots, and how a codebase is actually shaped before you dive into tools.

Install: grab the latest build from Releases —

• macOS — trace-mcp--arm64-mac.zip (Apple Silicon) or trace-mcp--mac.zip (Intel). Unzip and drag trace-mcp.app into /Applications.
• Windows — run trace-mcp.Setup..exe.

The app talks to the same trace-mcp daemon (http://127.0.0.1:3741) that MCP clients use, so anything you index from the app is immediately available to Claude Code / Cursor / etc.

---

How trace-mcp compares

trace-mcp combines code graph navigation, cross-session memory, and real-time code understanding in a single tool. Most adjacent projects solve one of these — trace-mcp unifies all three and is the only one with framework-aware cross-language edges (81 integrations) and code-linked decision memory.

• vs. token-efficient exploration (Repomix, jCodeMunch, cymbal) — trace-mcp adds framework edges, refactoring, security, and subprojects on top of symbol lookup.
• vs. session-memory tools (MemPalace, claude-mem, ConPort) — trace-mcp links decisions to specific symbols/files, so they surface automatically in impact analysis.
• vs. RAG / doc-gen (DeepContext, smart-coding-mcp) — trace-mcp answers "show me the execution path, deps, and tests," not "find code similar to this query."
• vs. code-graph MCP servers (Serena, Roam-Code) — trace-mcp has the broadest language coverage (81) and is the only one with cross-language framework edges.

> Full side-by-side tables with GitHub stars, languages, and per-capability coverage: [docs/comparisons.md](docs/comparisons.md).

---

Token reduction — measured, not marketed

AI agents burn tokens recomputing what they already discovered last turn — re-reading files, re-traversing dependencies, re-inflating context. trace-mcp replaces that with precision context: only the symbols, edges, and signatures relevant to the query, served from a graph that was computed once.

What to expect — by workload:

| Workload | Typical reduction | |---|---| | Mixed real-world production (code-aware tasks across a typical session) | ~40–50% on average | | Effective capacity at the same context budget | up to ~2× | | Structured code-navigation tasks (symbol lookup, impact analysis, type hierarchy, call graph) | up to 99% less redundant processing | | Targeted research / planning queries (composite tasks that replace ~10 sequential operations) | up to ~40× on individual calls | | Non-code workloads (raw text, unstructured data) | Out of scope today |

The averages are the honest number to plan against: across a typical session you're mixing high-leverage graph queries with reads, edits, and cheaper calls, and the net usually lands at 30–60% depending on stack and task mix. The peaks (up to 99% on individual structured calls) are real and reproducible — that's where recomputation gets eliminated most cleanly — but they're per-call, not per-session.

Benchmark: trace-mcp's own codebase (694 files, 3,831 symbols → 929 files, 5,197 symbols in v1.30):

Task                    Without trace-mcp    With trace-mcp    Reduction
───────────────────────────────────────────────────────────────────────────
Symbol lookup                42,518 tokens       1,162 tokens       97.3%
File exploration             27,486 tokens         855 tokens       96.9%
Search                       22,860 tokens       8,000 tokens       65.0%
Find usages                  11,430 tokens       1,720 tokens       85.0%
Context bundle               12,847 tokens       3,485 tokens       72.9%
Batch overhead               16,831 tokens       8,299 tokens       50.7%
Impact analysis              49,141 tokens       1,856 tokens       96.2%
Call graph                  178,345 tokens       9,285 tokens       94.8%
Type hierarchy               94,762 tokens         855 tokens       99.1%
Tests for                    22,590 tokens       1,150 tokens       94.9%
Composite task              223,721 tokens      14,245 tokens       93.6%
───────────────────────────────────────────────────────────────────────────
Total                       702,532 tokens      50,812 tokens       92.8%

Across 11 structured task categories, recomputation drops by up to ~99% per call when the agent reuses the graph instead of re-reading files — peaks where the math gets dramatic. Read that as a peak structured-task result on a well-supported TS/Vue codebase, not a number you should expect on every project. In production, on mixed workloads, expect ~40–50% on average. Less noise in context also means fewer hallucinations and better first-response accuracy — a quality benefit you don't see in token counts.

Savings scale with project size. On a 650-file project, structured-task savings cluster around ~522K tokens per session. On a 5,000-file enterprise codebase, savings grow non-linearly — without trace-mcp, the agent reads more wrong files before finding the right one. With trace-mcp, graph traversal stays O(relevant edges), not O(total files).

Composite tasks deliver the biggest wins. A single get_task_context call replaces a chain of ~10 sequential operations (search → get_symbol × 5 → Read × 3 → Grep × 2). That's one round-trip instead of ten — fewer tokens, lower latency, and one clean answer instead of ten partial ones.

Run it on your codebase

npx trace-mcp benchmark .

Per-category token savings against your actual repo in ~5 minutes — no install, no signup, all local. Numbers above are from trace-mcp's own TypeScript/Vue codebase (929 files, 5,197 symbols) under structured benchmarks; production reduction on mixed workloads will be lower (typically 30–60% depending on stack), but the per-task patterns hold for any well-supported stack.

Methodology

Measured using benchmark_project — runs eleven real task categories (symbol lookup, file exploration, text search, find usages, context bundle, batch overhead, impact analysis, call graph traversal, type hierarchy, tests-for, composite task context) against the indexed project. "Without trace-mcp" = estimated tokens from equivalent Read/Grep/Glob operations (full file reads, grep output). "With trace-mcp" = actual tokens returned by trace-mcp tools (targeted symbols, outlines, graph results). Token counts estimated using trace-mcp's built-in savings tracker.

Reproduce it yourself:

# Via CLI (no install)
npx trace-mcp benchmark /path/to/project

# Or via MCP tool
benchmark_project  # runs against the current project

---

Key capabilities

• Request flow tracing — URL → Route → Middleware → Controller → Service,

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nikolai-vysotskyi
• Source: nikolai-vysotskyi/trace-mcp
• License: MIT
• Homepage: https://trace-mcp.com

Install and usage instructions live in the source repository linked above.