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
get_project_map with summary_only=true — orient yourself to the project structureget_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
- 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" } }
]})
- Never read the same file twice. Use
get_outline once, then get_symbol for specific pieces.
- Prefer
get_context_bundle over chained get_symbol calls — it deduplicates shared imports.
- Read-before-Edit optimization. When you must
Read a file to edit it:
- Call
get_outline first to find the line range of the target symbol.
- Read only that range with
offset + limit. Never read a 500-line file to edit 5 lines.
- 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 AGENTS.md / settingsself_audit — dead exports, untested code, hotspotsget_tech_debt — per-module tech-debt gradesget_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_codemodtrace-mcp-pre-commit — security, quality-gate, and antipattern checks before commit
1---2name: trace-mcp3description: Use trace-mcp tools for code navigation, impact analysis, and framework-aware queries instead of Read/Grep/Glob/Bash. Activate whenever the agent needs to explore, understand, or modify a codebase that has trace-mcp indexed.4---56# trace-mcp — Code Intelligence Routing78trace-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.910## When to Use1112Activate this skill whenever you need to:13- Find a function, class, method, route, component, or any symbol14- Understand a file, module, or feature before editing15- Determine what breaks if you change something16- Trace a request flow, call graph, or data flow17- Audit architecture, dead code, tests, or security1819**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.2021## Start-of-Session Checklist22231. `get_project_map` with `summary_only=true` — orient yourself to the project structure242. `get_task_context` with `task: "<natural-language description>"` — gather all relevant code in a single call instead of chaining `search` → `get_symbol` → `Read`2526## Decision Matrix2728| Task | trace-mcp tool | Instead of |29|---|---|---|30| Find a symbol by name | `search` | Grep |31| Understand a file before editing | `get_outline` | Read (full file) |32| Read one symbol's source | `get_symbol` | Read (full file) |33| Multiple symbols + shared imports | `get_context_bundle` | chained `get_symbol` |34| What breaks if I change X | `get_change_impact` | guessing |35| Who calls this / what does it call | `get_call_graph` | Grep |36| All usages of a symbol | `find_usages` | Grep |37| Implementations of an interface | `get_type_hierarchy` | Grep / ls |38| Classes implementing X | `search` with `implements` filter | Grep |39| Tests for a symbol or file | `get_tests_for` | Glob + Grep |40| Project overview | `get_project_map` (summary_only) | Bash ls/find |41| Context for a task | `get_task_context` / `get_feature_context` | reading many files |42| HTTP request flow | `get_request_flow` | reading route + controller files |43| DB model relationships | `get_model_context` | reading model + migrations |44| Component tree | `get_component_tree` | reading component files |45| Circular dependencies | `get_circular_imports` | manual tracing |46| Dead code / dead exports | `get_dead_code` / `get_dead_exports` | Grep for unused |47| Project health / coverage gaps | `self_audit` | manual inspection |48| Complexity / hotspots | `get_complexity_report` / `get_risk_hotspots` | guessing |4950## Token-Efficiency Rules51521. **Batch independent queries.** Use `batch` when you need 2+ independent tool calls:53 ```54 batch({ calls: [55 { tool: "get_outline", args: { path: "src/foo.ts" } },56 { tool: "get_outline", args: { path: "src/bar.ts" } },57 { tool: "search", args: { query: "handleRequest", kind: "function" } }58 ]})59 ```602. **Never read the same file twice.** Use `get_outline` once, then `get_symbol` for specific pieces.613. **Prefer `get_context_bundle`** over chained `get_symbol` calls — it deduplicates shared imports.624. **Read-before-Edit optimization.** When you must `Read` a file to edit it:63 - Call `get_outline` first to find the line range of the target symbol.64 - Read only that range with `offset` + `limit`. Never read a 500-line file to edit 5 lines.655. **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.6667## After Editing a File6869- 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.70- If the response includes `_duplication_warnings`, review the referenced symbols — you may be duplicating existing logic.71- Do **not** re-read the file to "verify" the edit. The `Edit` tool already confirmed success.7273## Before Creating New Symbols7475- Call `check_duplication` with `{ name, kind }` to verify no similar symbol exists. Prevents reinventing existing logic.7677## Health Checks (Once Per Session)7879- `audit_config` — stale references in AGENTS.md / settings80- `self_audit` — dead exports, untested code, hotspots81- `get_tech_debt` — per-module tech-debt grades82- `get_optimization_report` — detects repeated reads, Bash grep usage, missed trace-mcp opportunities8384## Related Skills8586- `trace-mcp-refactoring` — safe refactoring workflow (risk assessment → rename → impact check)87- `trace-mcp-codemod` — bulk mechanical changes via `apply_codemod`88- `trace-mcp-pre-commit` — security, quality-gate, and antipattern checks before commit
opencue