trace-mcp
/trace-mcp
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.
- Author
- nikolai-vysotskyi ↗
- Repository
- trace-mcp ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Original author description
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.
How it works
- When to Use
- Start-of-Session Checklist
- Decision Matrix
- Environment Variables (Safe Path)
- Token-Efficiency Rules
- After Editing a File
- Before Creating New Symbols
- Health Checks (Once Per Session)
- Related Skills
SKILL.md preview
---
name: trace-mcp
description: 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.
---
# 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
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_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; requires `file`).
- 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 any
> `os.environ` / `process.env` printout
> - never import-diff the environment: `before = dict(os.environ)`, import a module,
> then diff `os.environ` to see what it touched
> - never `print(module.__file__)` for file discovery
> - never `cat` or directly Read a `.env` file for discovery
## 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" } }
]})
```
2. **Never read the same file twice.** Use `get_outline` once, then `get_symbol` for specific pieces.
3. **Prefer `get_context_bundle`** over chained `get_symbol` calls — it deduplicates shared imports.
4. **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.
5. **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
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · nikolai-vysotskyi/trace-mcp | 100 | MIT |
| opencue/cuecards | 100 | MIT |
| opencue/cuecards | 100 | MIT |
Database snapshot: 13.11.2026 · package version fcf4ca4a2b85 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100trace-mcp-pre-commit
Run trace-mcp security, quality-gate, and antipattern checks before committing or opening a PR. Activate when the agent is about to create a commit or pull request in a project indexed by trace-mcp. - 100trace-mcp-codemod
Use trace-mcp apply_codemod for any bulk mechanical change instead of repeated Edit calls. Activate whenever the same edit pattern would be applied 2+ times, across one file or many. - 100trace-analysis
ARM64 trace 通用证据分析方法论。当用户给出一段 ARM64 执行 trace 文件并询问字段含义、执行流、检测点、数据来源、call 边界、buffer 生命周期等开放问题(不属于纯密文还原)时使用。提供搜索键选择、单一目的搜索纪律、call 边界解析、字段语义分层、执行流抽取与检测点分析的完整方法论。激活此 skill 前应已通过 ak MCP 的 bind_trace 工具绑定 trace 文件并选择 mode=general。 - 100codegraph
Pre-indexed code knowledge graph for codebase exploration, symbol navigation, call chains, and change-impact analysis. Use when exploring an unfamiliar repo, tracing callers/callees, or assessing blast radius before a change — replaces grep+Read loops with one query. - 95codebase-explore
Read-only codebase exploration and analysis. Use when the user asks "analyze codebase", "explore code", "what does this project do", "find files related to", "understand architecture", or needs to research the codebase before making changes. Cannot modify any files. - 80Navigating Codebases with CodeGraph
Query a pre-indexed knowledge graph of a codebase (symbols, call graphs, dependencies, impact) instead of scanning files with grep/glob/Read. Use when exploring an unfamiliar codebase, tracing who calls or is called by a function, assessing the blast radius of a change, finding…