Where a raw agent runs Read and Grep over whole files, trace-mcp answers from an index — one symbol, one call graph, one context bundle — which is why its own tooling tracks token savings so closely. The decision memory is the less obvious value: query_decisions ties an architectural choice back to the code it governs, so 'why is it built this way' has an answer that survives past the session that made it.
A code-intelligence server that builds a local index of your project and exposes 55 tools over it: symbol lookup, semantic search, call graphs, change-impact and risk analysis, dead-code and security scans, git-history trends, a decision knowledge graph, and session analytics. Semantic search runs offline by default.
- Reading code by the symbol, not the file: get_symbol returns one function's source, get_outline lists a file's signatures without bodies, and get_context_bundle packs a symbol with its imports and callers inside a token budget
- get_task_context is the all-in-one first call for a new task — execution paths, tests and entry points — while get_feature_context returns ranked snippets for a concept and plan_turn routes an opening move with a verdict of exists, partial, missing or ambiguous
- Semantic and text search separated: search finds symbols by name, kind or text; search_text does regex and glob full-text; find_usages and get_call_graph trace who references and who calls a symbol
- Change safety before you edit: get_change_impact gives a risk score with mitigations and breaking-change detection, assess_change_risk a quick level, check_rename a pre-rename collision check, and get_changed_symbols and get_tests_for map a diff to affected symbols and their tests
- Codebase health: self_audit, get_dead_exports, get_dead_code, get_coupling, get_circular_imports, get_complexity_report, get_tech_debt (A–F per module), detect_antipatterns and scan_security for OWASP Top-10 patterns
- Git-history trends — get_complexity_trend, get_coupling_trend, get_symbol_complexity_trend and predict_bugs — show whether a file is improving or degrading over commits
- Safe mutation tools: remove_dead_code and apply_codemod (AST-aware or regex) are dry-run by default, and check_quality_gates runs pass/fail gates built for CI
- A decision knowledge graph: remember_decision routes an input through a confidence-scored review queue, query_decisions answers 'why was this chosen?' linked to the actual code, and invalidate_decision retires a superseded one; mine_sessions pulls decisions out of past Claude Code logs
- Session economics: get_session_analytics, get_optimization_report, get_real_savings and get_usage_trends measure token spend and where trace-mcp saves it, and batch runs several tools in one request
Node, run as npx trace-mcp over stdio. Semantic search works out of the box with bundled ONNX embeddings — no API keys and no outbound calls — and you can switch to Ollama or OpenAI for LLM-powered summarisation through config. The index is a local SQLite database; the history-trend tools (get_complexity_trend, get_coupling_trend, predict_bugs) require git. `trace-mcp init` can install a PreToolUse guard hook that redirects an agent's Read/Grep/Glob on source files to these tools.
One command — npm install -g trace-mcp