Your AI agent reads
UserController.phpand sees a class. trace-mcp reads it and sees a route → controller → FormRequest → Eloquent model → Inertia render → Vue page → child components — in one graph.
You ask | trace-mcp answers | How |
"What breaks if I change this model?" | Blast radius across languages + risk score + linked architectural decisions |
|
"Why was auth implemented this way?" | The actual decision record with reasoning and tradeoffs |
|
"I'm starting a new task" | Optimal code subgraph + relevant past decisions + dead-end warnings |
|
"What did we discuss about GraphQL last month?" | Verbatim conversation fragments with file references |
|
"Show me the request flow from URL to rendered page" | Route → Middleware → Controller → Service → View with prop mapping |
|
"Find all untested code in this module" | Symbols classified as "unreached" or "imported but never called in tests" |
|
"What's the impact of this API change on other services?" | Cross-subproject client calls with confidence scores |
|
"Orient me — I just opened this project" | Project identity + active decisions + memory stats in ~300 tokens |
|
Three things no other tool does:
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. 53 integrations across 14 frameworks, 7 ORMs, 12 UI libraries.
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.
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.
Related MCP server: LiLBrain
AI coding agents are language-aware but framework-blind.
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 brute-read files, guess at relationships, and miss cross-language edges entirely. The bigger the project, the worse it gets.
trace-mcp builds a cross-language dependency graph from your source code and exposes it through the Model Context Protocol. Any MCP-compatible agent (Claude Code, Cursor, Windsurf, etc.) gets framework-level understanding out of the box.
Without trace-mcp | With trace-mcp |
Agent reads 15 files to understand a feature |
|
Agent doesn't know which Vue page a controller renders |
|
"What breaks if I change this model?" — agent guesses |
|
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. |
trace-mcp is not just a code intelligence server — it combines code graph navigation, cross-session memory, and real-time code understanding in a single tool. Other projects solve one of these; trace-mcp unifies all three.
Last updated: April 2026. Based on public documentation and GitHub repos. If you maintain one of these projects and see an inaccuracy, open an issue.
Tools that help AI agents read code with fewer tokens — AST parsing, outlines, context packing.
Capability | trace-mcp | Repomix | Context Mode | code-review-graph | jCodeMunch | codebase-memory-mcp | cymbal |
GitHub stars | — | 23K | 6.6K | 5.1K | 1.5K | 1.3K | 137 |
Tree-sitter AST parsing | ✅ 68 languages | ✅ compress only (~20) | ❌ no code parsing | ✅ | ✅ ~40 languages | ✅ 66 languages | ✅ 22 languages |
Token-efficient symbol lookup | ✅ outlines, symbols, bundles | ❌ packs entire files | ✅ sandboxed output | ✅ | ✅ core focus | ✅ | ✅ outline/show/context |
Cross-file dependency graph | ✅ directed edge graph | ❌ | ❌ | ✅ knowledge graph | ✅ import graph | ✅ knowledge graph | ✅ refs/importers |
Framework-aware edges | ✅ 53 integrations (14 frameworks, 7 ORMs, 12 UI libs) | ❌ | ❌ | ❌ | ✅ 21 frameworks (route/middleware) | partial (REST routes) | ❌ |
Impact analysis | ✅ reverse dep traversal + decorator filter | ❌ | ❌ | ❌ | ✅ blast radius + decorator filter | ✅ detect_changes | ✅ impact command |
Call graph | ✅ bidirectional, graph-based | ❌ | ❌ | ❌ | ✅ AST-based, bidirectional | ✅ trace_call_path | ✅ refs/importers |
Refactoring tools | ✅ rename, extract, dead code, codemod | ❌ | ❌ | ❌ | ❌ (dead code detect only) | ❌ | ❌ |
Security scanning | ✅ OWASP Top-10, taint | ✅ Secretlint | ❌ | ❌ | ❌ | ❌ | ❌ |
Multi-repo subprojects | ✅ cross-repo API linking | ✅ remote repos | ❌ | ❌ | ✅ GitHub repos | ❌ | ❌ |
Session memory | ✅ built-in | ❌ | ✅ SQLite journal | ❌ | ✅ index persistence | ✅ persistent graph | ❌ |
Written in | TypeScript | TypeScript | TypeScript | Python | Python | C | Go |
Tools that persist context across AI agent sessions — activity logs, knowledge graphs, memory compression.
Capability | trace-mcp | MemPalace | claude-mem | OpenMemory | engram | ConPort |
GitHub stars | — | 43K | 45.7K | 3.9K | 2.3K | 761 |
Cross-session context carryover | ✅ | ✅ wings/rooms | ✅ core focus | ✅ | ✅ | ✅ |
Cross-session content search | ✅ | ✅ ChromaDB semantic | ❌ | ✅ | ❌ | ❌ |
Decision knowledge graph | ✅ temporal, code-linked | ✅ temporal (text-only) | ❌ | ✅ temporal | ❌ | ✅ project-level |
Code-graph-aware memory | ✅ decisions → symbols & files | ❌ text-only | ❌ text-only | ❌ text-only | ❌ text-only | ❌ text-only |
Auto-extraction from sessions | ✅ pattern-based (0 LLM calls) | ✅ via hooks | ✅ AI-compressed | ❌ | ❌ | ❌ |
Wake-up context | ✅ ~300 tok (code-linked decisions) | ✅ ~170 tok (AAAK) | ❌ | ❌ | ❌ | ❌ |
Decision enrichment in tools | ✅ impact/plan_turn/resume | ❌ standalone | ❌ | ❌ | ❌ | ❌ |
Service/subproject scoping | ✅ decisions per service | ✅ wings per project | ❌ | ❌ | ❌ | ❌ |
Token usage analytics | ✅ per-tool cost breakdown | ❌ | partial | ❌ | ❌ | ❌ |
Code intelligence included | ✅ 130+ tools | ❌ | ❌ | ❌ | ❌ | ❌ |
Works as standalone memory | ❌ code-focused | ✅ general-purpose | ❌ Claude-specific | ✅ agent-agnostic | ✅ agent-agnostic | ✅ project-scoped |
Written in | TypeScript | Python | TypeScript | TS + Python | Go | Python |
Key difference: MemPalace stores "decided to use PostgreSQL" as text in ChromaDB. trace-mcp stores the same decision linked to
src/db/connection.ts::Pool#class— and when you runget_change_impacton that symbol, the decision shows up inlinked_decisions. General-purpose memory tools remember what you said. trace-mcp remembers what you said AND which code it's about.
Tools that generate docs from code or provide embedding-based code search for AI retrieval.
Capability | trace-mcp | Repomix | DeepContext | smart-coding-mcp | mcp-local-rag¹ | knowledge-rag¹ |
GitHub stars | — | 23K | 274 | 193 | 204 | 44 |
Real-time code understanding | ✅ live graph, always current | ❌ snapshot at pack time | ❌ manual reindex | partial (opt-in watcher) | ❌ | partial (file watcher) |
Auto-generated project docs | ✅ | ❌ raw file dump | ❌ | ❌ | ❌ | ❌ |
Semantic code search | ✅ | ❌ no search | ✅ Jina embeddings | ✅ nomic embeddings | ✅ vector search | ✅ hybrid + reranking |
Framework-aware context | ✅ routes, models, components | ❌ | ❌ | ❌ | ❌ | ❌ |
Task-focused context | ✅ | ❌ packs everything | ❌ | ❌ | ❌ | ❌ |
No doc maintenance needed | ✅ derived from code | ✅ repacks on demand | ❌ manual reindex | partial (auto on startup) | ❌ manual ingest | partial (auto-reindex) |
Works offline, no API keys | ✅ graph + FTS5 + bundled ONNX embeddings | ✅ | ❌ requires cloud API | ❌ requires local embeddings | ❌ requires local embeddings | ❌ requires local embeddings |
Incremental updates | ✅ file watcher, content hash | ❌ full repack | ✅ SHA-256 hashing | ✅ file hash + opt-in watcher | ❌ | ✅ mtime + dedup |
Written in | TypeScript | TypeScript | TypeScript | JavaScript | TypeScript | Python |
¹ mcp-local-rag and knowledge-rag are document RAG tools (PDF, DOCX, Markdown) — not code-specific. Included for comparison as they occupy adjacent mindshare.
Key difference: RAG tools answer "find code similar to this query." trace-mcp answers "show me the execution path, the dependencies, and the tests for this feature." Graph traversal finds structurally relevant code that embedding similarity misses — and never returns stale results because the graph updates incrementally with every file save.
Capability | trace-mcp | Serena | code-review-graph | codebase-memory-mcp | SocratiCode | Narsil-MCP | Roam-Code |
GitHub stars | — | 22.6K | 5.1K | 1.3K | — | — | — |
Languages | 68 | ~20 (via LSP) | ~10 | 66 | ~15 | 32 | ~10 |
Framework integrations | 53 (14 fw + 7 ORM + 12 UI + 20 other) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
Cross-language edges | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
MCP tools | 120+ | ~35 | ~15 | ~20 | ~25 | 90 | 139 |
Session memory | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
CI/PR reports | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
Multi-repo subprojects | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
Security scanning | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
Refactoring tools | ✅ | ✅ rename, symbol editing | ❌ | ❌ | ❌ | ❌ | ❌ |
Architecture governance | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
Token savings tracking | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
Written in | TypeScript | Python | Python | C | TypeScript | Rust | Python |
Why framework awareness matters: A graph that knows
UserControllerexists but doesn't know it rendersUsers/Show.vuevia Inertia is missing the edges that matter most. Framework integrations turn a syntax graph into a semantic graph — the agent sees the same connections a developer sees.
AI agents burn tokens reading files they don't need. trace-mcp returns precision context — only the symbols, edges, and signatures relevant to the query.
Benchmark: trace-mcp's own codebase (694 files, 3,831 symbols):
Task Without trace-mcp With trace-mcp Reduction
─────────────────────────────────────────────────────────────────────
Symbol lookup 42,518 tokens 7,353 tokens 82.7%
File exploration 27,486 tokens 548 tokens 98.0%
Search 22,860 tokens 8,000 tokens 65.0%
Find usages 11,430 tokens 1,720 tokens 85.0%
Context bundle 12,847 tokens 4,164 tokens 67.6%
Batch overhead 16,831 tokens 9,031 tokens 46.3%
Impact analysis 49,141 tokens 2,461 tokens 95.0%
Call graph 178,345 tokens 10,704 tokens 94.0%
Type hierarchy 94,762 tokens 1,030 tokens 98.9%
Tests for 22,590 tokens 1,150 tokens 94.9%
Composite task 93,634 tokens 3,836 tokens 95.9%
─────────────────────────────────────────────────────────────────────
Total 572,444 tokens 49,997 tokens 91.3%91% fewer tokens to accomplish the same code understanding tasks. That's ~522K tokens saved per exploration session — more headroom for actual coding, fewer context window evictions, lower API costs.
Savings scale with project size. On a 650-file project, trace-mcp saves ~522K tokens. 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, with 90%+ token reduction.
Per-task breakdown — what it actually costs to answer common questions:
Question | Naive approach | trace-mcp tool | Tokens (naive) | Tokens (trace-mcp) | Reduction |
"Where is | Grep all .ts files |
| ~12,400 | ~800 | 93% |
"What calls | Grep + Read 8 files |
| ~18,200 | ~1,100 | 94% |
"What breaks if I rename | Manual trace across 40+ files |
| ~62,000 | ~2,400 | 96% |
"Find all tests for | Glob + Read 12 test files |
| ~14,800 | ~650 | 96% |
"Understand the indexing pipeline" | Read 15 source files |
| ~89,000 | ~7,200 | 92% |
"Unused exports in src/tools/" | Read + Grep all files |
| ~38,000 | ~1,800 | 95% |
"All OpenAPI endpoints in the project" | Find + Read all .yaml/.json |
| ~22,000 | ~900 | 96% |
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 MCP tool
benchmark_project # runs against the current project
# Or via CLI
trace-mcp benchmark /path/to/projectRequest flow tracing — URL → Route → Middleware → Controller → Service, across 18 backend frameworks
Component trees — render hierarchy with props / emits / slots (Vue, React, Blade)
Schema from migrations — no DB connection needed
Event chains — Event → Listener → Job fan-out (Laravel, Django, NestJS, Celery, Socket.io)
Change impact analysis — reverse dependency traversal across languages, enriched with linked architectural decisions
Decision memory — mine sessions for decisions, link them to code symbols/files, query with temporal validity. Decisions auto-surface in get_change_impact, plan_turn, and get_session_resume
Cross-session search — "what did we discuss about auth?" — FTS5 search across all past session content
Graph-aware task context — describe a dev task → get the optimal code subgraph (execution paths, tests, types) + relevant past decisions, adapted to bugfix/feature/refactor intent
CI/PR change impact reports — automated blast radius, risk scoring, test gap detection, architecture violation checks on every PR
Call graph & DI tree — bidirectional call graphs with 4-tier resolution confidence, optional LSP enrichment for compiler-grade accuracy, NestJS dependency injection
ORM model context — relationships, schema, metadata for 7 ORMs
Dead code & test gap detection — find untested exports/symbols (with "unreached" vs "imported_not_called" classification), dead code, per-symbol test reach in impact analysis
Security scanning & MCP server analysis — OWASP Top-10 pattern scanning, taint analysis (source→sink data flow), MCP security context export for skill-scan enrichment (tool annotations verification, capability classification, sensitive data flows)
Multi-service subprojects — link graphs across services via API contracts; cross-service impact analysis; service-scoped decisions
AI-powered analysis — semantic search with zero-config local ONNX embeddings (no API keys needed), plus optional LLM summarization via Ollama/OpenAI
Languages (68): PHP, TypeScript/JavaScript, Python, Go, Java, Kotlin, Ruby, Rust, C, C++, C#, Swift, Objective-C, Dart, Scala, Groovy, Elixir, Erlang, Haskell, Gleam, Bash, Lua, Perl, GDScript, R, Julia, Nix, SQL, HCL/Terraform, Protocol Buffers, Vue SFC, HTML, CSS/SCSS/SASS/LESS, XML/XUL/XSD, YAML, JSON, TOML, Assembly, Fortran, AutoHotkey, Verse, AL, Blade, EJS, Zig, OCaml, Clojure, F#, Elm, CUDA, COBOL, Verilog/SystemVerilog, GLSL, Meson, Vim Script, Common Lisp, Emacs Lisp, Dockerfile, Makefile, CMake, INI, Svelte, Markdown, MATLAB, Lean 4, FORM, Magma, Wolfram/Mathematica
Frameworks: Laravel (+ Livewire, Nova, Filament, Pennant), Django (+ DRF), FastAPI, Flask, Express, NestJS, Fastify, Hono, Next.js, Nuxt, Rails, Spring, tRPC
ORMs: Eloquent, Prisma, TypeORM, Drizzle, Sequelize, Mongoose, SQLAlchemy
Frontend: Vue, React, React Native, Blade, Inertia, shadcn/ui, Nuxt UI, MUI, Ant Design, Headless UI
Other: GraphQL, Socket.io, Celery, Zustand, Pydantic, Zod, n8n, React Query/SWR, Playwright/Cypress/Jest/Vitest/Mocha
Full details: Supported frameworks · All tools
npm install -g trace-mcp
trace-mcp init # one-time global setup (MCP clients, hooks, CLAUDE.md)
trace-mcp add # register current project for indexingStep 1: init — one-time global setup. Configures your MCP client (Claude Code, Cursor, Windsurf, or Claude Desktop), installs the guard hook, and adds a tool routing guide to ~/.claude/CLAUDE.md.
Step 2: add — registers a project. Detects frameworks and languages, creates the index database, and adds the project to the global registry. Run this in each project you want trace-mcp to understand.
All state lives in ~/.trace-mcp/ — nothing is stored in your project directory (unless you add a .traceignore or .trace-mcp/.config.json).
Start your MCP client and use:
> get_project_map to see what frameworks are detected
> get_task_context("fix the login bug") to get full execution context for a task
> get_change_impact on app/Models/User.php to see what depends on itcd /path/to/another/project
trace-mcp addOr specify a path directly:
trace-mcp add /path/to/projectList all registered projects:
trace-mcp listAfter updating trace-mcp (npm update -g trace-mcp), re-run init in your project directory:
trace-mcp initThis runs database migrations, updates MCP client configuration, and reindexes the project with the latest plugins.
If you prefer manual control, see Configuration for all options. You can skip specific init steps:
trace-mcp init --skip-hooks --skip-claude-md --skip-mcp-clientSemantic search works out of the box — just enable AI in your config:
// ~/.trace-mcp/.config.json or project/.trace-mcp/.config.json
{ "ai": { "enabled": true } }The default provider (onnx) uses a bundled local model (Xenova/all-MiniLM-L6-v2, ~23 MB) — no API keys, no external services, fully offline after first model download. Run embed_repo once or just use search with semantic: "on" and embeddings will be computed on demand.
For LLM-powered summarization, switch to ollama or openai provider — see AI configuration.
Automatic: trace-mcp serve starts background indexing immediately and launches a file watcher. The server is ready for tool calls right away — results improve as indexing progresses. If the project isn't registered yet, serve auto-registers it.
Manual: index a project without starting the server:
trace-mcp index /path/to/project # incremental (skips unchanged files)
trace-mcp index /path/to/project --force # full reindexFiles are content-hashed (MD5). On re-index, unchanged files are skipped. Both serve and serve-http start a file watcher that debounces rapid changes (300ms) and processes deletions immediately.
All trace-mcp state is centralized:
~/.trace-mcp/
.config.json # global config + per-project settings
registry.json # registered projects
topology.db # cross-service topology + subproject graph
decisions.db # decision memory + session content (cross-session knowledge graph)
index/
my-app-a1b2c3d4e5f6.db # per-project databases (named by project + hash)Place a .traceignore file in the project root to skip files/directories from indexing entirely (gitignore syntax):
# Skip generated code
generated/
*.generated.ts
# Skip protobuf output
*_pb2.py
*.pb.go
# Negation — re-include a specific path
!generated/keep-this.tsCommon directories (node_modules, .git, dist, build, vendor, etc.) are skipped automatically.
You can also configure ignore rules in ~/.trace-mcp/.config.json (global) or project/.trace-mcp/.config.json (per-project):
{
"ignore": {
"directories": ["proto", "generated"],
"patterns": ["**/fixtures/**"]
}
}Details: Configuration — .traceignore
trace-mcp works on three levels to make AI agents use its tools instead of raw file reading:
The MCP server provides instructions and tool descriptions with routing hints that tell AI agents when to prefer trace-mcp over native Read/Grep/Glob. This works with any MCP-compatible client — no configuration needed.
Add this block to your project's CLAUDE.md (or ~/.claude/CLAUDE.md for global use) to reinforce tool routing:
## Code Navigation Policy
Use trace-mcp tools for code intelligence — they understand framework relationships, not just text.
| Task | trace-mcp tool | Instead of |
|------|---------------|------------|
| Find a function/class/method | `search` | Grep |
| Understand a file before editing | `get_outline` | Read (full file) |
| Read one symbol's source | `get_symbol` | Read (full file) |
| What breaks if I change X | `get_change_impact` | guessing |
| All usages of a symbol | `find_usages` | Grep |
| Starting work on a task | `get_task_context` | reading 15 files |
| Quick keyword context | `get_feature_context` | reading 15 files |
| Tests for a symbol | `get_tests_for` | Glob + Grep |
| HTTP request flow | `get_request_flow` | reading route files |
| DB model relationships | `get_model_context` | reading model + migrations |
Use Read/Grep/Glob for non-code files (.md, .json, .yaml, config).
Start sessions with `get_project_map` (summary_only=true).For hard enforcement, install the PreToolUse guard hook that blocks Read/Grep/Glob on source code files and redirects the agent to trace-mcp tools with specific suggestions. The hook is installed globally by trace-mcp init, or manually:
trace-mcp setup-hooks --global # install
trace-mcp setup-hooks --uninstall # removeThis copies the guard script to ~/.claude/hooks/ and adds the hook to your Claude Code settings.
What the hook does:
Blocks Read/Grep/Glob/Bash on source code files (.ts, .py, .php, .go, .java, .rb, etc.)
Allows non-code files (.md, .json, .yaml, .env, config)
Allows Read before Edit — first Read is blocked with a suggestion, retry on the same file is allowed (the agent needs full content for editing)
Allows safe Bash commands (git, npm, build, test, docker, etc.)
Redirects with specific trace-mcp tool suggestions in the denial message
Source files (PHP, TS, Vue, Python, Go, Java, Kotlin, Ruby, HTML, CSS, Blade)
│
▼
┌──────────────────────────────────────────┐
│ Pass 1 — Per-file extraction │
│ tree-sitter → symbols │
│ integration plugins → routes, │
│ components, migrations, events, │
│ models, schemas, variants, tests │
└────────────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ Pass 2 — Cross-file resolution │
│ PSR-4 · ES modules · Python modules │
│ Vue components · Inertia bridge │
│ Blade inheritance · ORM relations │
│ → unified directed edge graph │
└────────────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ Pass 3 — LSP enrichment (opt-in) │
│ tsserver · pyright · gopls · │
│ rust-analyzer → compiler-grade │
│ call resolution, 4-tier confidence │
└────────────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ SQLite (WAL mode) + FTS5 │
│ nodes · edges · symbols · routes │
│ + embeddings (local ONNX by default) │
│ + optional: LLM summaries │
└────────────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ Decision Memory (decisions.db) │
│ decisions · session chunks · FTS5 │
│ temporal validity · code linkage │
│ auto-mined from session logs │
└────────────────────┬─────────────────────┘
│
▼
MCP server (stdio or HTTP/SSE)
130+ tools · 2 resourcesIncremental by default — files are content-hashed; unchanged files are skipped on re-index.
Plugin architecture — language plugins (symbol extraction) and integration plugins (semantic edges) are loaded based on project detection, organized into categories: framework, ORM, view, API, validation, state, realtime, testing, tooling.
Details: Architecture & plugin system
Document | Description |
Complete list of languages, frameworks, ORMs, UI libraries, and what each extracts | |
All 130+ MCP tools with descriptions and usage examples | |
Config options, AI setup, environment variables, security settings | |
How indexing works, plugin system, project structure, tech stack | |
Decision knowledge graph, session mining, cross-session search, wake-up context | |
Session analytics, token savings tracking, optimization reports, benchmarks | |
Optional tweakcc integration for maximum tool routing enforcement | |
Building, testing, contributing, adding new plugins |
Every conversation with an AI agent produces decisions, discoveries, and preferences that disappear when the session ends. trace-mcp's decision memory captures them and links them to the code they're about.
Mine — mine_sessions scans Claude Code / Claw Code JSONL logs and extracts decisions using pattern matching (no LLM calls). Detects architecture decisions, tech choices, bug root causes, preferences, tradeoffs, discoveries, and conventions.
Link — each decision can be linked to a code symbol (src/auth/provider.ts::AuthProvider#class) or file. When you run get_change_impact on that symbol, the decision shows up automatically.
Search — query_decisions supports FTS5 full-text search, filtering by type/service/symbol/file/tag, and temporal queries ("what was true in January?"). search_sessions searches raw conversation content across all past sessions.
Surface — decisions auto-enrich code intelligence tools:
get_change_impact → linked_decisions on the target + affected files
plan_turn → related_decisions matched by task description + target files
get_session_resume → active_decisions for project orientation
Tool | What it does |
| Extract decisions from session logs (pattern-based, 0 LLM calls) |
| Manually record a decision with code linkage + service scoping |
| Query by type/service/symbol/file/tag + FTS5 search |
| Mark a decision as superseded (preserved for history) |
| Chronological history of decisions for a symbol/file |
| Knowledge graph overview |
| Index session content for cross-session search |
| FTS5 search: "what did we discuss about auth?" |
| Compact orientation (~300 tokens): project + decisions + stats |
trace-mcp memory mine # mine sessions for decisions
trace-mcp memory index # index session content for search
trace-mcp memory search "GraphQL migration" # search past conversations
trace-mcp memory decisions --type tech_choice # list decisions
trace-mcp memory stats # knowledge graph overview
trace-mcp memory timeline --file src/auth.ts # decision history for a fileDecisions have valid_from / valid_until timestamps. When a decision is superseded, invalidate_decision preserves it for historical queries while excluding it from active results:
query_decisions() → only active decisions
query_decisions(as_of="2025-01-15") → what was true on Jan 15
query_decisions(include_invalidated=true) → full historyIn projects with multiple services (subprojects), decisions can be scoped:
add_decision(title="Use JWT", service_name="auth-api")
query_decisions(service_name="auth-api") → only auth-api decisions
query_decisions() → all project decisionsDetails: Decision memory
A subproject is any working repository that is part of your project's ecosystem: microservices, frontends, backends, shared libraries, CLI tools, etc.
Each directory with its own root marker (package.json, composer.json, go.mod, etc.) is a subproject. A project contains one or more subprojects; the project itself is not a subproject.
trace-mcp links dependency graphs across subprojects — if subproject A calls an API endpoint in subproject B, trace-mcp knows that changing that endpoint in B breaks clients in A. Subprojects can live inside the project directory or be added from outside.
Subproject discovery is automatic by default. Every time a project is indexed (serve, serve-http, or index), trace-mcp:
Detects subprojects within the project root:
Docker Compose — parses docker-compose.yml / compose.yml
Flat workspace — first-level subdirs with root markers (e.g. project/frontend/ + project/backend/)
Grouped workspace — two-level structure (e.g. project/org/service-a/)
Monolith fallback — treats root as a single subproject
Registers each subproject bound to the project in ~/.trace-mcp/topology.db
Parses API contracts — OpenAPI/Swagger, GraphQL SDL, Protobuf/gRPC
Scans code for HTTP client calls (fetch, axios, Http::, requests, http.Get, gRPC stubs, GraphQL operations)
Links discovered calls to known endpoints from other subprojects
Creates cross-subproject dependency edges
# Index a project — subprojects are auto-detected
cd ~/projects/my-app && trace-mcp add
# → auto-detects: my-app/user-service (has openapi.yaml)
# → my-app/order-service (has axios.get('/api/users/{id}'))
# → links order-service → user-service via /api/users/{id}
# Or add an external subproject manually
trace-mcp subproject add --repo=~/projects/external-auth --project=~/projects/my-app
# Check cross-subproject impact
trace-mcp subproject impact --endpoint=/api/users
# → "GET /api/users/{id} is called by 2 client(s) in 1 subproject(s)"
# [order-service] src/services/user-client.ts:42 (axios, confidence: 85%)# Add a subproject (inside or outside project dir)
trace-mcp subproject add --repo=../service-b --project=. [--contract=openapi.yaml] [--name=my-service]
trace-mcp subproject remove <name-or-path>
trace-mcp subproject list [--project=.] [--json]
trace-mcp subproject sync # re-scan all subprojects
trace-mcp subproject impact --endpoint=/api/users [--method=GET] [--service=user-svc]Tool | What it does |
| All subprojects, their connections, and stats |
| Cross-subproject impact: what breaks if endpoint X changes (resolves to symbol level) |
| Find all client calls across subprojects that call a specific endpoint |
| Add a subproject via MCP (bound to current project, or specify |
| Re-scan all subprojects |
Subproject management builds on top of the topology system. See Configuration for options.
trace-mcp can generate automated change impact reports for pull requests — blast radius, risk scoring, test coverage gaps, architecture violations, and dead code detection.
# Generate a markdown report for changes between main and HEAD
trace-mcp ci-report --base main --head HEAD
# Output to file
trace-mcp ci-report --base main --head HEAD --format markdown --output report.md
# JSON output
trace-mcp ci-report --base main --head HEAD --format json
# Fail CI if risk level >= high
trace-mcp ci-report --base main --head HEAD --fail-on high
# Index before generating (for CI environments without pre-built index)
trace-mcp ci-report --base main --head HEAD --indexAdd this workflow to get automatic impact reports on every PR:
# .github/workflows/ci.yml (impact-report job runs after build-and-test)
- name: Index project
run: node dist/cli.js index . --force
- name: Generate impact report
run: |
node dist/cli.js ci-report \
--base ${{ github.event.pull_request.base.sha }} \
--head ${{ github.event.pull_request.head.sha }} \
--format markdown \
--output report.md
- name: Post PR comment
uses: marocchino/sticky-pull-request-comment@v2
with:
path: report.mdThe full workflow is in .github/workflows/ci.yml — it runs build → test → impact-report on every PR.
Section | What it shows |
Summary | Changed files, affected files count, risk level, gap counts |
Blast Radius | Files transitively affected by changes (depth-2 reverse dependency traversal) |
Test Coverage Gaps | Affected symbols with no matching test file. Per-symbol |
Risk Analysis | Per-file composite score: 30% complexity + 25% churn + 25% coupling + 20% blast radius |
Architecture Violations | Layer rule violations involving changed files (auto-detects clean architecture / hexagonal presets) |
Dead Code | New exports in changed files that nothing imports |
Full-stack projects in any supported framework combination
Teams using AI agents (Claude, Cursor, Windsurf) for day-to-day development
Multi-language codebases where PHP ↔ JavaScript ↔ Python boundaries create blind spots
Monorepos with multiple services and shared libraries
Microservice architectures where API changes ripple across repos
Large codebases where agents waste tokens re-reading files
Built by Nikolai Vysotskyi
Execute multiple trace-mcp tools in a single MCP request. Dispatches any registered tool by name, including tools this session's preset defers — so a deferred tool is callable here without a load_tools round-trip (tools.exclude stays a hard restriction). Use to reduce round-trips when you need several independent queries (e.g., get_outline for 3 files, or search + get_symbol together). Read-only (delegates to other tools). Returns JSON: { batch_results: [{ tool, result }], total }.
Inputs: calls (required).
Find all references to a symbol or file (imports, calls, renders, dispatches). Use instead of Grep for symbol usages — semantic, not text matches. For raw text use search_text; for a bidirectional call graph use get_call_graph. Weakly-grounded text_matched edges into a name-colliding target are dropped by default (phantom god-node filter); include_ambiguous_text_matched: true keeps them. Read-only. Returns JSON: { references: [{ edge_type, resolution_tier, file, symbol }], total, truncated?, ambiguous_filtered? } — page caps at 50, total counts all.
Inputs: fqn, limit, file_path, symbol_id, +2 more.
Build a bidirectional call graph centered on a symbol (who calls it + what it calls). Each branch keeps its direction: depth 2 = callers of callers, callees of callees. Use to understand control flow through a function. For flat list of all references use find_usages instead. Read-only. Returns JSON: { root: { symbol_id, name, calls: [...], called_by: [...] } }.
Inputs: fqn, depth, symbol_id.
Full change impact report: risk score + mitigations, breaking change detection, enriched dependents (complexity, coverage, exports), module groups, affected tests, co-change hidden couplings. Pass symbol_ids to scope to changed symbols. Use before modifying code. For a quick risk score alone use assess_change_risk; for who-calls-what use get_call_graph. compact pages results; bundle recalls. Read-only. Returns JSON: { risk, dependents, affectedTests, breakingChanges, totalAffected }.
Inputs: fqn, depth, bundle, compact, +5 more.
Get a symbol's source code + its import dependencies + optional callers, packed within a token budget. Supports batch queries with shared-import deduplication. Use instead of chaining get_symbol calls. For a single symbol without imports, use get_symbol — lighter. Read-only. Returns JSON: { primary: [{ symbol_id, file, source }], imports: [{ file, source }], token_usage }.
Inputs: fqn, symbol_id, symbol_ids, token_budget, +2 more.
Technology profile of the project: detected frameworks/ORMs/UI libs from manifests (package.json, composer.json, etc.), which are covered by trace-mcp plugins, and coverage gaps. Read-only. Returns JSON: { detected, covered, gaps }.
Inputs: no named parameters.
Execute type-checker (tsc, mypy, pyright) and map errors to enclosing AST symbols. Read-only.
Inputs: checker, file_path, max_files, timeout_ms, +2 more.
Search code by keyword/topic → returns ranked source snippets within a token budget. Use when you need to READ actual code for a concept or feature. For structured task context with tests and entry points use get_task_context instead; for symbol metadata without source use search. Read-only. Returns JSON (default) or Markdown: { items: [{ symbol_id, name, file, source, score }], token_usage } | { content: "...markdown..." }. Supports output_format: "toon". Capped by memory.recall.timeoutMs (default 5000ms); on timeout returns { items: [], token_usage, degraded: true }.
Inputs: description (required), detail_level, token_budget, output_format.
Get index status, statistics, health, and pipeline progress (indexing, summarization, embedding). Includes the session projectRoot; when the index is empty, next_steps names the empty root and points at list_projects + call_project_tool for other registered projects. Read-only, no side effects. Use to verify the index is ready before running queries. Returns JSON: { status, stats, projectRoot, next_steps?, config, warnings, pipelineProgress, embedding }.
Inputs: no named parameters.
Detect token waste patterns in AI agent sessions: repeated file reads, Bash grep instead of search, large file reads, unused trace-mcp tools. Provides savings estimates. Read-only. For usage/cost overview use get_session_analytics; for A/B savings comparison use get_real_savings. Returns JSON: { patterns: [{ type, description, savings_estimate }], total_waste }.
Inputs: period.
Get all symbols for a file (signatures only, no bodies) — cheaper than Read for understanding a file before editing. Follow up with get_symbol to read one symbol's source. nested: true expands large top-level symbols (default ≥100 LOC) into inner declarations, each carrying parentId + depth (max 3). Accepts project-relative or absolute file paths. For files in other registered projects, use call_project_tool. Read-only. Returns JSON: { path, language, symbols: [{ symbolId, name, kind, signature, lineStart, lineEnd, parentId?, depth? }] }. Supports output_format: "toon".
Inputs: path (required), nested, detail_level, output_format, +1 more.
Show active tool preset, available presets, which tools are registered in this session, and which are deferred (loadable via load_tools). Read-only. Returns JSON: { active_preset, registered_tools, tool_names, available_presets, deferred_tools }.
Inputs: no named parameters.
Get project overview: detected frameworks, languages, file counts, structure. Read-only, no side effects. Call with summary_only=true at session start to orient yourself before diving into code. Use instead of manual ls/find. Returns JSON: { frameworks, languages, fileCount, symbolCount, structure }.
Inputs: summary_only.
A/B comparison: how many tokens could be saved by using trace-mcp instead of raw Read/Bash file reads. Per-file breakdown. Read-only. For pattern-based waste detection use get_optimization_report instead. Returns JSON: { files: [{ file, raw_tokens, compact_tokens, savings }], total_savings }.
Inputs: period.
Analyze AI agent session logs: token usage, prompt-cache hit rate (blended and split by provider/model), cost breakdown by tool/server, top files, models used. Parses Claude Code JSONL logs automatically. Read-only. For waste detection use get_optimization_report; for cost trends use get_usage_trends. Returns JSON: { sessionsCount, totals, cacheHitRate: { blended, byModel, byProvider }, byToolServer, topTools, topFiles, modelsUsed }.
Inputs: period, session_id.
Token savings stats for this session: per-tool call counts, estimated token savings, reduction percentage, dedup savings, and per-tool latency (p50/p95/max/error_rate). Read-only. Returns JSON: { session: { ..., latency_per_tool }, cumulative, dedup_saved_tokens, report }.
Inputs: no named parameters.
Look up a symbol by symbol_id or FQN and return its source code. Use instead of Read when you need one specific function/class/method — returns only the symbol, not the whole file. For multiple symbols at once, prefer get_context_bundle. Read-only. Returns JSON: { symbol_id, name, kind, fqn, signature, file, line_start, line_end, source }.
Inputs: fqn, max_lines, symbol_id, verify_against_git.
All-in-one context for starting a dev task: execution paths, tests, entry points, adapted by task type. Use as your FIRST call when beginning any new task — replaces manual chaining of search → get_symbol → Read. For narrower feature-code lookup use get_feature_context instead. Read-only. Returns JSON (default) or Markdown.
Inputs: task (required), focus, detail_level, token_budget, +2 more.
Daily token usage time-series: sessions, tokens, estimated cost, tool calls, prompt-cache hit rate per day. For spotting cost spikes. Read-only. For detailed session breakdown use get_session_analytics instead. Returns JSON: { days, daily: [{ date, sessions, tokens, cost_usd, tool_calls, cache_hit_rate, cache_hit_rate_by_provider }], totals }.
Inputs: days.
Mark a decision as no longer valid. The decision remains in the knowledge graph for historical queries but is excluded from active queries. Use when a decision is superseded or reversed. Mutates the decision store; idempotent. Returns JSON: { invalidated: { id, title, valid_until } }.
Inputs: id (required), valid_until.
Load tools this session's preset deferred, by preset name and/or explicit tool names. Call with no arguments to list what is deferred. Emits notifications/tools/list_changed and returns the loaded tools' schemas, so they are usable even if your client ignores that notification (call them through batch). Returns JSON: { loaded, already_loaded, unknown, blocked, tools, hint }.
Inputs: tools, preset.
Mine Claude Code / Claw Code session logs for architectural decisions, tech choices, bug root causes, and preferences. Strategies: "regex" (default, free, ~20-40% recall), "llm" (higher recall, costs tokens), "hybrid" (regex + LLM safety net). Skips already-mined sessions unless force=true. Mutates the decision store; idempotent. Returns JSON: { mined, decisions_extracted, sessions_processed, strategy?, llm_sessions?, llm_decisions_extracted? }.
Inputs: force, strategy, project_root, min_confidence, +3 more.
Opening-move router for new tasks. Combines BM25/PageRank search + session journal (negative evidence + focus signals) + framework-aware insertion-point suggestions + change-risk + turn-budget advisor into ONE call. Returns verdict (exists/partial/missing/ambiguous), confidence, ranked targets with provenance, scaffold hints when missing, and recommended next tool calls. Call this FIRST on a new task to break the empty-result hallucination chain. Read-only. For broader task context with source code use get_task_context instead. Returns JSON: { verdict, confidence, targets, scaffoldHints, nextSteps }.
Inputs: task (required), intent, skip_risk, max_targets.
Query the decision knowledge graph. Filter by type, subproject, code symbol, file path, tag, or time — answers "why was this architecture chosen?" with the actual decision record. Defaults to approved decisions; use include_pending or review_status for other tiers. Read-only. Returns JSON: { decisions: [{ id, title, type, content, tags, review_status, cluster_ids? }], clusters_summary?, total_results }. Supports output_format: "toon".
Inputs: tag, type, as_of, limit, +13 more.
Notify trace-mcp that a file was edited. Reindexes the single file and invalidates search caches. Call after Edit/Write to keep index fresh — much lighter than full reindex. Also flags duplicate symbols — if _duplication_warnings appears, you may be recreating existing logic; review them. Each one is reported once per file, not on every edit; check_duplication re-asks. Mutates the index; idempotent. Returns JSON: { status, file, totalFiles, indexed, _duplication_warnings? }.
Inputs: file_path (required).
Live agent write into the decision knowledge graph. Confidence-scores the input and routes it through the memoir review queue: high-confidence rows enter the active graph immediately, mid-confidence rows queue for human approval, low-confidence rows are dropped without persistence. Per-session dedup + rate-limit. Use during a session to capture decisions in real time. For manual high-confidence writes use add_decision; for post-hoc extraction from session logs use mine_sessions. Returns JSON: { id, review_status, confidence, deduplicated? }.
Inputs: type (required), title (required), content (required), tags, +5 more.
Search symbols by name, kind, or text. Use instead of Grep for functions, classes, methods, variables. For raw text/comment search use search_text; for references to a known symbol use find_usages. Read-only. Returns JSON: { items: [{ symbol_id, name, kind, fqn, signature, file, line, score }], total, search_mode } — mode-specific shape when mode!=single. Supports output_format: "toon".
Inputs: query (required), kind, mode, fuzzy, +16 more.
Full-text search across all indexed files. Supports regex, glob file patterns, language filter. Use for finding strings, comments, TODOs, config values, error messages — anything not captured as a symbol. Skips .env files: secret values are never searched or returned, use get_env_vars for env keys. For symbol search (functions, classes) use search instead. Read-only. Returns JSON: { files: [{ file, language, hits: [{ line, column, match, context }] }], total_matches } — hits grouped per file, so a long path is paid once. Pass grouping: "flat" for the ungrouped matches[] shape.
Inputs: query (required), grouping, is_regex, language, +5 more.
Onboarding helper: shows top imported files, most connected symbols (PageRank), language stats, and example tool calls. Call this first when exploring an unfamiliar project. For a structured project map use get_project_map instead. Read-only. Returns JSON: { topFiles, topSymbols, languageStats, exampleQueries }.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 29 tools
Most tools target distinct operations and descriptions often point to alternatives, but there is meaningful overlap: plan_turn and get_task_context both claim to be the FIRST call for a new task, and the analytics/reporting cluster (session_stats, session_analytics, usage_trends, real_savings, optimization_report) requires careful reading to choose correctly. Context/search tools like get_feature_context, get_task_context, and get_context_bundle also have blurry boundaries.
Names are consistently snake_case and mostly follow a verb_noun pattern (get_symbol, find_usages, query_decisions, register_edit). Minor deviations like batch, search, and search_text are still readable but keep it from being perfectly uniform.
With 29 tools the surface is heavy for a single MCP server. Several tools are closely related analytics/reporting or context-entry variants that could likely be consolidated, even though the broad code-intelligence scope justifies some specialization.
Core code intelligence, decision knowledge graph, index maintenance, diagnostics, and session analytics are covered. However, several descriptions reference tools that are not present in this set (add_decision, check_duplication, list_projects, call_project_tool, assess_change_risk, get_env_vars), creating notable dead ends and gaps in the advertised surface.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Deterministic memory & code intelligence MCP for 15 IDEs (100% LongMemEval in 12.9ms, 0 LLM tokens).
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
