trace-mcp

<p align="center"> <img src="packages/app/build/icon-256.png" alt="trace-mcp logo" width="128" /> </p> <h1 align="center">trace-mcp</h1> <p align="center"> <a href="https://github.com/nikolai-vysotskyi/trace-mcp/actions/workflows/ci.yml"><img src="https://github.com/nikolai-vysotskyi/trace-mcp/actions/workflows/ci.yml/badge.svg?branch=master" alt="CI" /></a> <a href="https://glama.ai/mcp/servers/nikolai-vysotskyi/trace-mcp"><img src="https://glama.ai/mcp/servers/nikolai-vysotskyi/trace-mcp/badges/score.svg" alt="Glama score" /></a> <a href="https://www.npmjs.com/package/trace-mcp"><img src="https://img.shields.io/npm/v/trace-mcp" alt="npm version" /></a> <img src="https://img.shields.io/node/v/trace-mcp" alt="Node.js version" /> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License" /></a> </p> <p align="center"> <a href="https://github.com/nikolai-vysotskyi/trace-mcp/actions/workflows/codeql.yml"><img src="https://github.com/nikolai-vysotskyi/trace-mcp/actions/workflows/codeql.yml/badge.svg" alt="CodeQL" /></a> <a href="https://github.com/nikolai-vysotskyi/trace-mcp/actions/workflows/semgrep.yml"><img src="https://github.com/nikolai-vysotskyi/trace-mcp/actions/workflows/semgrep.yml/badge.svg" alt="Semgrep" /></a> <a href="https://securityscorecards.dev/viewer/?uri=github.com/nikolai-vysotskyi/trace-mcp"><img src="https://api.securityscorecards.dev/projects/github.com/nikolai-vysotskyi/trace-mcp/badge" alt="OpenSSF Scorecard" /></a> <a href="https://github.com/nikolai-vysotskyi/trace-mcp/security"><img src="https://img.shields.io/badge/security-policy-blue" alt="Security policy" /></a> <a href="https://github.com/nikolai-vysotskyi/trace-mcp/security/dependabot"><img src="https://img.shields.io/badge/Dependabot-enabled-success" alt="Dependabot enabled" /></a> </p> <p align="center"> <strong>AI agents recompute the same work. trace-mcp makes them reuse instead.</strong><br> The recomputation → reuse layer for AI systems. </p> <p align="center"> <strong>40–50% fewer tokens</strong> on average &nbsp;·&nbsp; <strong>up to 2× effective capacity</strong> &nbsp;·&nbsp; <strong>up to 99% less redundant processing</strong> <br> _{Based on early benchmarks across agent workflows with repeated context and dependency traversal.} </p>

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.

<p align="center"> <img src="docs/images/app-graph.png" alt="trace-mcp desktop app — GPU graph explorer" width="820" /> <br/> _{Also ships a <a href="#desktop-app">desktop app</a> with a GPU graph explorer over the same index.} </p>

---

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:<basename> 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.

2. 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.

3. 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.

4. 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:<basename> 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 |

---

<a id="desktop-app"></a>

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.

<p align="center"> <img src="docs/images/app-projects.png" alt="trace-mcp app — Projects, MCP Clients, Settings" width="720" /> </p>

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.

<p align="center"> <img src="docs/images/app-overview.png" alt="trace-mcp app — project Overview tab" width="560" /> </p>

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.

<p align="center"> <img src="docs/images/app-dark-graph.png" alt="trace-mcp app — GPU graph explorer in dark mode" width="720" /> </p>

Install: grab the latest build from Releases —

• macOS — `trace-mcp-<version>-ar