nikolai-vysotskyi/trace-mcp / skills/trace-mcp
trace-mcp
VerifiedUse 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.
trace-mcp — Code Intelligence Routing
trace-mcp is a framework-aware code intelligence MCP server. It exposes 182 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_mapwithsummary_only=true— orient yourself to the project structureget_task_contextwithtask: "<natural-language description>"— gather all relevant code in a single call instead of chainingsearch→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_implementations | 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 (mode: "exports_only") | Grep for unused |
| Project health / coverage gaps | self_audit | manual inspection |
| Complexity / hotspots | get_complexity_report / get_risk_hotspots | guessing |
| List env keys / what config exists | get_env_vars (keys + types/formats only, never values) | os.environ dump, cat of a .env file |
Environment Variables (Safe Path)
- Task "list env keys / what config exists" →
get_env_vars. It returns keys plus inferred types/formats only — never values, so it is safe for secrets. get_env_vars { "pattern": "DB_" }filters by key prefix.get_env_vars { "file": ".env", "redacted": true }gives a line-by-line redacted per-file view (keys + type hints, no values, preserves order/comments; requiresfile).- Config file discovery goes via
search/get_symbol/get_outline/get_task_context— never by importing a module to see what it touches.
FORBIDDEN — never use these for env/config discovery (values leak into model context):
- never dump the environment:
python -c "import os; print(os.environ)"or anyos.environ/process.envprintout- never import-diff the environment:
before = dict(os.environ), import a module, then diffos.environto see what it touched- never
print(module.__file__)for file discovery- never
cator directly Read a.envfile for discovery
Token-Efficiency Rules
- Batch independent queries. Use
batchwhen 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_outlineonce, thenget_symbolfor specific pieces. - Prefer
get_context_bundleover chainedget_symbolcalls — it deduplicates shared imports. - Read-before-Edit optimization. When you must
Reada file to edit it:- Call
get_outlinefirst 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.
- Call
- 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_editwith the editedfile_pathto reindex just that file and invalidate caches. This is much lighter than a fullreindexand 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
Edittool already confirmed success.
Before Creating New Symbols
- Call
check_duplicationwith{ name, kind }to verify no similar symbol exists. Prevents reinventing existing logic.
Health Checks (Once Per Session)
audit_config— stale references in CLAUDE.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 viaapply_codemodtrace-mcp-pre-commit— security, quality-gate, and antipattern checks before commit
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |