trace-mcp - framework-aware codebase MCP for coding agents

trace-mcp sits in the same lane as Qartez - pre-index the codebase, hand the agent a structured graph instead of letting it grep - but it cuts the problem along a different axis. Where Qartez's edge is structural (PageRank, blast radius, complexity), trace-mcp's edge is framework-aware. It understands that Inertia::render('Users/Show', $data) connects a Laravel controller to resources/js/Pages/Users/Show.vue, and that $user->posts() means the posts table defined three migrations ago. Cross-language semantic edges are the headline feature.

The number to look at: 40-50% average token reduction on real workloads, up to 97% on individual structured tasks. The README also frames it as "one tool call replaces ~42 minutes of agent exploration" - that's marketing copy, but the underlying mechanism (graph traversal in place of repeated file reads) is real.

The 138-tool surface

Big tool count, organised into a few clean categories:

• Code navigation - get_project_map, get_task_context, get_change_impact, find_usages, apply_rename
• Analysis - get_request_flow, get_untested_symbols, get_call_graph, get_type_hierarchy
• Search - search, semantic_search, search_sessions
• Decision memory - query_decisions, mine_sessions
• Subprojects - get_subproject_graph, get_subproject_impact, get_subproject_clients
• Planning - benchmark_project, get_session_resume, plan_turn

get_request_flow and get_change_impact are the ones to lead with when you wire it up - they're the queries that visibly change how an agent plans an edit.

Decision memory is the differentiated bit

Most code-intel MCPs stop at "graph of symbols." trace-mcp also captures architectural decisions and links each one to the code it's about - so when an agent asks for the impact of editing a file, the relevant historical "we did it this way because..." surface as part of the answer.

It's not a chat log. Decisions have temporal validity (valid_from / valid_until), get auto-mined from session logs, and are queryable via query_decisions. Treat it like a code-linked changelog the agent reads automatically.

Install

npx trace-mcp benchmark .       # try it on this repo first
npm install -g trace-mcp
trace-mcp init                  # configures your MCP client
trace-mcp add                   # indexes current project

trace-mcp init autodetects Claude Code, Cursor, Windsurf, and friends; you can also drop the MCP config block in by hand.

Frameworks and languages

81 languages parsed. The framework integrations - 58 of them - are where the money is:

• Backend - Laravel (Livewire, Nova, Filament), Django, FastAPI, Express, NestJS, Rails, Spring
• Frontend - Vue, React, Next.js, Nuxt
• ORMs - Eloquent, Prisma, TypeORM, Drizzle, SQLAlchemy, Mongoose, Sequelize
• Knowledge vaults - Obsidian, Logseq, Markdown with wikilinks/frontmatter

The cross-language edges are the part nobody else does well. If your stack is Laravel + Inertia + Vue, or Rails + Hotwire + Turbo, or Django + HTMX, this is probably the most useful piece of code intel you can put in front of an agent right now.

Semantic search defaults to local

ONNX embeddings ship in the package. No API keys, no outbound calls, semantic search just works after install. You can swap to Ollama (still local) or OpenAI via config if you want a bigger model.

Ranking combines PageRank, "Signal Fusion" (the README's term for blending structural + embedding signals), and the embeddings themselves. Defaults are reasonable - tune later.

LSP enrichment is optional but worth it

Wire up tsserver, pyright, gopls, or rust-analyzer and trace-mcp gets compiler-grade resolution for call graphs and type hierarchies. The README calls it "4-tier resolution confidence" - unenriched parses still work, LSP-enriched ones are sharper.

When to reach for it

• You're on a stack with cross-language framework conventions (Laravel/Inertia/Vue, Rails/Hotwire, Django/HTMX). Most code-intel tools ignore those edges; this one indexes them.
• Your agents waste tokens re-deriving call graphs and request flows on every session. get_request_flow and get_change_impact are the high-leverage replacements.
• You want a code-linked decision log without building one yourself.

When not to

• You're on a niche stack outside the 58-framework list. Coverage is broad but uneven - the README is honest that PHP/TypeScript/Python/Go are best-supported and others trail.
• You want a global-knowledge MCP. trace-mcp is project-scoped; it won't help with non-code workloads.
• You already run Qartez and the structural signals are what you actually need. trace-mcp's value is in the framework edges and decision memory; if those don't apply to your work, the overlap isn't worth running both.

Trade-offs

The 138-tool surface is large. Some MCP clients get noisy with that many tools registered, and an agent that doesn't know which tool to pick will burn context exploring options. The README's claimed token savings assume the agent picks get_change_impact instead of opening files - if your harness biases towards file reads, you'll see less of the gain.

Decision memory is only as good as your session history. On day one, query_decisions returns nothing useful; the value compounds with use, which is the right shape but worth flagging if you're evaluating it on a fresh repo.

Local-first is the default and a feature, not a limitation. If you do flip to OpenAI embeddings for higher recall, the bundled ONNX model is still a sensible fallback for offline work.