trace-mcp

trace-mcp — Code Intelligence Routing

trace-mcp is a framework-aware code intelligence MCP server. It exposes 120+ tools that return semantic, structured results over a cross-language dependency graph. When trace-mcp is available, it is almost always cheaper and more accurate than native file tools.

When to Use

Activate this skill whenever you need to:

• Find a function, class, method, route, component, or any symbol
• Understand a file, module, or feature before editing
• Determine what breaks if you change something
• Trace a request flow, call graph, or data flow
• Audit architecture, dead code, tests, or security

Do not use Read, Grep, Glob, or shell ls/find/cat/head/tail for exploring source code (.ts, .js, .py, .php, .go, .rb, .java, etc.). Use trace-mcp tools instead. Native tools stay allowed only for non-code files (.md, .json, .yaml, configs) or immediately before an Edit on a known file.

Start-of-Session Checklist

1. get_project_map with summary_only=true — orient yourself to the project structure
2. get_task_context with task: "<natural-language description>" — gather all relevant code in a single call instead of chaining search → get_symbol → Read

Decision Matrix

| Task | trace-mcp tool | Instead of | |---|---|---| | Find a symbol by name | search | Grep | | Understand a file before editing | get_outline | Read (full file) | | Read one symbol's source | get_symbol | Read (full file) | | Multiple symbols + shared imports | get_context_bundle | chained get_symbol | | What breaks if I change X | get_change_impact | guessing | | Who calls this / what does it call | get_call_graph | Grep | | All usages of a symbol | find_usages | Grep | | Implementations of an interface | get_type_hierarchy | Grep / ls | | Classes implementing X | search with implements filter | Grep | | Tests for a symbol or file | get_tests_for | Glob + Grep | | Project overview | get_project_map (summary_only) | Bash ls/find | | Context for a task | get_task_context / get_feature_context | reading many files | | HTTP request flow | get_request_flow | reading route + controller files | | DB model relationships | get_model_context | reading model + migrations | | Component tree | get_component_tree | reading component files | | Circular dependencies | get_circular_imports | manual tracing | | Dead code / dead exports | get_dead_code / get_dead_exports | Grep for unused | | Project health / coverage gaps | self_audit | manual inspection | | Complexity / hotspots | get_complexity_report / get_risk_hotspots | guessing |

Token-Efficiency Rules

1. Batch independent queries. Use batch when you need 2+ independent tool calls:

`` batch({ calls: [ { tool: "get_outline", args: { path: "src/foo.ts" } }, { tool: "get_outline", args: { path: "src/bar.ts" } }, { tool: "search", args: { query: "handleRequest", kind: "function" } } ]}) ``

1. Never read the same file twice. Use get_outline once, then get_symbol for specific pieces.
2. Prefer get_context_bundle over chained get_symbol calls — it deduplicates shared imports.
3. Read-before-Edit optimization. When you must Read a file to edit it:
4. Call get_outline first to find the line range of the target symbol.
5. Read only that range with offset + limit. Never read a 500-line file to edit 5 lines.
6. Do not delegate code exploration to subagents. Agent subprocesses carry ~50k tokens of overhead before doing anything. Use trace-mcp tools in the main conversation instead.

After Editing a File

• Call register_edit with the edited file_path to reindex just that file and invalidate caches. This is much lighter than a full reindex and keeps subsequent queries accurate.
• If the response includes _duplication_warnings, review the referenced symbols — you may be duplicating existing logic.
• Do not re-read the file to "verify" the edit. The Edit tool already confirmed success.

Before Creating New Symbols

• Call check_duplication with { name, kind } to verify no similar symbol exists. Prevents reinventing existing logic.

Health Checks (Once Per Session)

• audit_config — stale references in CLAUDE.md / settings
• self_audit — dead exports, untested code, hotspots
• get_tech_debt — per-module tech-debt grades
• get_optimization_report — detects repeated reads, Bash grep usage, missed trace-mcp opportunities

Related Skills

• trace-mcp-refactoring — safe refactoring workflow (risk assessment → rename → impact check)
• trace-mcp-codemod — bulk mechanical changes via apply_codemod
• trace-mcp-pre-commit — security, quality-gate, and antipattern checks before commit