Trace MCP

Structural (AST-aware) or regex find-and-replace across files. Default engine "auto": when the pattern is an ast-grep pattern (concrete syntax with $META metavariables, e.g. "foo($$$ARGS)") supported code files (.ts/.tsx/.js/.jsx) are matched syntactically — so occurrences inside strings and comments are NOT touched. Plain regex patterns fall back to the text engine. Dry-run by default — first call shows preview (with engine_used), second call with dry_run=false applies. Potentially destructive. Always preview with dry_run=true first. Returns JSON: { success, engine_used, dry_run, matches, files_modified, total_replacements, total_files }.

Before modifying a file or symbol, predict risk level (low/medium/high/critical) with contributing factors and recommended mitigations. Combines blast radius, complexity, git churn, test coverage, and coupling. Use as a quick risk check. For full impact report with affected tests and dependents use get_change_impact instead. Read-only. Returns JSON: { risk, level, factors: [{ name, value }], mitigations }.

Execute multiple trace-mcp tools in a single MCP request. Returns results for all calls. Use to reduce round-trips when you need several independent queries (e.g., get_outline for 3 files, or search + get_symbol together). Read-only (delegates to other tools). Returns JSON: { batch_results: [{ tool, result }], total }.

Check if a function/class name already exists elsewhere in the codebase before creating it. Prevents duplicating existing logic. Call with just a name when planning new code (an existing match means the name is taken — this is expected when used as a pre-create check), or symbol_id to check an existing symbol against others (the supplied symbol_id is always excluded from results — a symbol is never its own duplicate). Use exclude_symbol_id to suppress additional known symbols. Returns scored matches — score ≥0.7 means high likelihood of duplication, review the existing symbol before proceeding. Read-only. Returns JSON: { duplicates: [{ symbol_id, name, file, score }], hasDuplication }.

Run configurable quality gate checks against the project. Returns pass/fail for each gate (complexity, coupling, circular imports, dead exports, tech debt, security, antipatterns, code smells). Designed for CI integration — AI can verify gates pass before committing. Use before PR/commit to ensure quality standards. Read-only. When no gates are defined (no quality_gates in config and no inline config.rules), the result is NO_GATES_CONFIGURED with a _warnings advisory — NOT a misleading PASS. Pass use_default_gates: true to opt in to a conservative built-in ruleset (max_cyclomatic=30 error, max_circular_import_chains=0 error, max_coupling_instability=0.9 warning). Returns JSON: { gates, summary: { result: "PASS"|"FAIL"|"WARNING"|"NO_GATES_CONFIGURED", ... }, _warnings?, _defaults_used? }.

Pre-rename collision detection: checks the symbol's own file and all importing files for existing symbols with the target name. Use before apply_rename to verify safety. Read-only (does not modify files). Returns JSON: { safe, conflicts: [{ symbol_id, name, file }] }.

Detect performance & design antipatterns: N+1 query risks, missing eager loading, unbounded queries, event listener leaks (via callSites — framework-managed listeners like Livewire/Socket.IO/NestJS gateways/Mongoose/Sequelize hooks are excluded), circular ORM association cycles, missing FK indexes, memory leaks (unbounded caches, closure-captured growing collections), god classes (>=25 methods or >=500 LOC), long methods (>=60 LOC), long parameter lists (>=6 params), deep nesting (>=5 indent levels). ORM-scoped signals require an active ORM plugin; size/complexity detectors (god_class, long_method, long_parameter_list, deep_nesting) run on every indexed symbol. For ES/CJS import cycles use get_circular_imports. For code quality (TODOs, debug artifacts, hardcoded values) use scan_code_smells. For security use scan_security. Read-only. Returns JSON: { findings: [{ category, severity, file, line, message, suggestion }], total }.

Find all places that reference a symbol or file (imports, calls, renders, dispatches). Use instead of Grep for symbol usages — understands semantic relationships, not just text matches. For bidirectional call graph use get_call_graph instead. By default, weakly-grounded text_matched edges into a target whose simple name collides with many other symbols are dropped (phantom god-node filter). Pass include_ambiguous_text_matched: true to keep them. Read-only. Returns JSON: { references: [{ file, line, kind, context }], total, ambiguous_filtered? }.

Build a bidirectional call graph centered on a symbol (who calls it + what it calls). Use to understand control flow through a function. For flat list of all references use find_usages instead. Read-only. Returns JSON: { root: { symbol_id, name, calls: [...], called_by: [...] } }.

Full change impact report: risk score + mitigations, breaking change detection, enriched dependents (complexity, coverage, exports), module groups, affected tests, co-change hidden couplings. Supports diff-aware mode via symbol_ids to scope analysis to only changed symbols. Use before modifying code to understand blast radius. For quick risk assessment without full report, use assess_change_risk instead. Read-only. Returns JSON: { risk, dependents, affectedTests, breakingChanges, totalAffected }.

Map a git diff to affected symbols (functions, classes, methods). For PR review. If "since" is omitted, auto-detects main/master as the base. Requires git. Use for PR review to see which symbols changed. For full branch comparison with risk assessment use compare_branches instead. Read-only. Returns JSON: { changes: [{ symbol_id, name, kind, file, changeType }], total }. Set output_format: "toon" for lossless TOON encoding — cheaper LLM tokens on tabular payloads.

Find circular dependency chains in the import graph (Kosaraju SCC algorithm). Considers only import-typed edges (esm_imports / imports / py_imports / py_reexports); call, reference, member_of, and test_covers edges are NOT walked. Test files (paths matching tests/, /*.test.*, **/*.spec.*, /__tests__/) are excluded by default to suppress spurious test↔source cycles — pass include_tests: true to opt in. Use to detect and break dependency cycles. Read-only. Returns JSON: { total_cycles, cycles: [{ files, length }] }.

Get complexity metrics (cyclomatic, max nesting, param count) for symbols in a file or across the project. Use to identify complex code before refactoring. For historical trends use get_complexity_trend instead. Read-only. Returns JSON: { symbols: [{ symbol_id, name, kind, file, line, cyclomatic, max_nesting, param_count }], total }. Set output_format: "toon" for lossless TOON encoding — cheaper LLM tokens on tabular payloads.

File complexity over git history: cyclomatic complexity at past commits. Shows if a file is getting more or less complex. Requires git. Use to track whether a file is improving or degrading. For current snapshot use get_complexity_report; for symbol-level trends use get_symbol_complexity_trend. Read-only. Returns JSON: { file, snapshots: [{ commit, date, complexity }] }.

Get a symbol's source code + its import dependencies + optional callers, packed within a token budget. Supports batch queries with shared-import deduplication. Use instead of chaining get_symbol calls — deduplicates shared imports across symbols. For a single symbol without imports, get_symbol is lighter. Read-only. Returns JSON: { primary: [{ symbol_id, file, source }], imports: [{ file, source }], token_usage }.

Build a Control Flow Graph (CFG) for a function/method: if/else branches, loops, try/catch, returns, throws. Shows logical paths through the code. Outputs Mermaid diagram, ASCII, or JSON. Use to understand branching logic before modifying complex functions. For call-level graph (who calls whom) use get_call_graph instead. Read-only. Returns Mermaid/ASCII/JSON: { nodes, edges, entryPoint, exitPoints }.

Coupling analysis: afferent (Ca), efferent (Ce), instability index per file. Shows which modules are stable vs unstable. Use to identify fragile or overly-depended-on modules. For coupling changes over time use get_coupling_trend instead. Read-only. Returns JSON: [{ file, ca, ce, instability, assessment }]. Set output_format: "toon" for lossless TOON encoding — cheaper LLM tokens on tabular payloads.

File coupling over git history: Ca/Ce/instability at past commits. Shows if a module is stabilizing or destabilizing. Requires git. Use to track module stability over time. For current coupling snapshot use get_coupling instead. Read-only. Returns JSON: { file, snapshots: [{ commit, date, ca, ce, instability }] }.

Technology profile of the project: detected frameworks/ORMs/UI libs from manifests (package.json, composer.json, etc.), which are covered by trace-mcp plugins, and coverage gaps. Read-only. Returns JSON: { detected, covered, gaps }.

Dead code detection. Two modes: (1) "multi-signal" (default) combines import graph, call graph, and barrel export analysis with confidence scores. (2) "reachability" runs forward BFS from auto-detected entry points (tests, package.json main/bin, src/{cli,main,index}, routes, framework-tagged controllers) — stricter but more accurate when entry points are enumerable. Pass entry_points to add custom roots. Both modes emit _methodology and _warnings. Use for comprehensive dead code analysis. For quick export-only scan use get_dead_exports; to safely remove detected dead code use remove_dead_code.

Find exported symbols whose export keyword has no external consumer. Each item carries signals (which detectors fired) and recommendation: "remove_export_keyword" when the symbol is still used inside its own file (just un-export it, keep the declaration), "delete_symbol" when no in-file usage was detected. NOTE: this tool flags dead EXPORT KEYWORDS, not necessarily dead SYMBOLS. For strict dead-symbol detection (multi-signal: import graph + call graph + barrel re-exports + intra-file usage, only flags symbols with NO incoming references anywhere) use get_dead_code instead — it will reject anything get_dead_exports tags remove_export_keyword. Paginated: caps result list at limit (default 100, max 500); when more exist the response includes truncated: true and total_dead reflects the full count. Read-only. Returns JSON: { dead_exports: [{ symbol_id, name, kind, file, line, signals, recommendation }], total_dead, total_exports, truncated? }. Set output_format: "toon" for lossless TOON encoding — cheaper LLM tokens on tabular payloads.

List environment variable keys from .env files with inferred value types/formats. Never exposes actual values — only keys, types (string/number/boolean/empty), and formats (url/email/ip/path/uuid/json/base64/csv/dsn/etc). Read-only, no side effects, safe for secrets. Use to understand project configuration without accessing actual values. Pass redacted: true together with file to receive a line-by-line redacted view of that one file (keys + type hints, no values) — useful when ordering and comments matter, e.g. when reviewing a config layout. Returns JSON grouped by file by default: { [file]: [{ key, type, format, comment }] }.

Search code by keyword/topic → returns ranked source code snippets within a token budget. Use when you need to READ actual code for a concept or feature. For structured task context with tests and entry points, use get_task_context instead. For symbol metadata without source, use search. Read-only. Returns JSON (default) or Markdown: { items: [{ symbol_id, name, file, source, score }], token_usage } | { content: "...markdown..." }. Set output_format: "toon" for lossless TOON encoding — cheaper LLM tokens on tabular payloads. Hard-capped by memory.recall.timeoutMs (default 5000 ms); on timeout returns { items: [], token_usage, degraded: true } so the agent turn never blocks on slow IO.

Find all classes that implement or extend a given interface or base class. Use when you know the interface name. For full hierarchy tree (ancestors + descendants) use get_type_hierarchy instead. Read-only. Returns JSON: { implementations: [{ symbol_id, name, kind, file, line }], total }.

Get index status, statistics, health information, and pipeline progress (indexing, summarization, embedding). Read-only, no side effects. Use to verify the index is ready before running queries. Returns JSON: { totalFiles, totalSymbols, languages, frameworks, pipelineProgress }.

Detect token waste patterns in AI agent sessions: repeated file reads, Bash grep instead of search, large file reads, unused trace-mcp tools. Provides savings estimates. Read-only. For usage/cost overview use get_session_analytics; for A/B savings comparison use get_real_savings. Returns JSON: { patterns: [{ type, description, savings_estimate }], total_waste }.

Get all symbols for a file (signatures only, no bodies). Use instead of Read to understand a file before editing — much cheaper in tokens. For reading one symbol's source, follow up with get_symbol. Pass nested: true to expand large top-level symbols (default ≥100 LOC) into their inner function-like declarations — each child carries parentId + depth (max depth 3). Read-only. Returns JSON: { path, language, symbols: [{ symbolId, name, kind, signature, lineStart, lineEnd, parentId?, depth? }] }. Set output_format: "toon" for lossless TOON encoding — cheaper LLM tokens on tabular payloads.

Show active tool preset, available presets, and which tools are registered in this session. Read-only. Returns JSON: { active_preset, registered_tools, tool_names, available_presets }.

Get project overview: detected frameworks, languages, file counts, structure. Read-only, no side effects. Call with summary_only=true at session start to orient yourself before diving into code. Use instead of manual ls/find. Returns JSON: { frameworks, languages, fileCount, symbolCount, structure }.

A/B comparison: how many tokens could be saved by using trace-mcp instead of raw Read/Bash file reads. Per-file breakdown. Read-only. For pattern-based waste detection use get_optimization_report instead. Returns JSON: { files: [{ file, raw_tokens, compact_tokens, savings }], total_savings }.

Find symbols related via co-location (same file), shared importers, and name similarity. Use when exploring a symbol to discover sibling code. For call-graph relationships use get_call_graph instead; for all usages use find_usages. Read-only. Returns JSON: { related: [{ symbol_id, name, kind, file, relation_type, score }] }.

Analyze AI agent session logs: token usage, cost breakdown by tool/server, top files, models used. Parses Claude Code JSONL logs automatically. Read-only. For waste detection use get_optimization_report; for cost trends use get_usage_trends. Returns JSON: { sessions, tokens, cost_usd, tools, models, topFiles }.

Cross-session context carryover: shows what was explored in recent past sessions (files touched, tools used, dead-end searches). Call at session start to orient yourself without re-reading files. Much cheaper than re-exploring the codebase. Read-only. For decision-aware wake-up use get_wake_up instead. Returns JSON: { sessions: [{ files, tools, deadEnds }], active_decisions }.

Token savings stats for this session: per-tool call counts, estimated token savings, reduction percentage, dedup savings, and per-tool latency (p50/p95/max/error_rate). Read-only. Returns JSON: { session: { ..., latency_per_tool }, cumulative, dedup_saved_tokens }.

Look up a symbol by symbol_id or FQN and return its source code. Use instead of Read when you need one specific function/class/method — returns only the symbol, not the whole file. For multiple symbols at once, prefer get_context_bundle. Read-only. Returns JSON: { symbol_id, name, kind, fqn, signature, file, line_start, line_end, source }.

Single symbol complexity over git history: cyclomatic, nesting, params, lines at past commits. Requires git. Use to track a specific function's complexity evolution. For file-level trends use get_complexity_trend instead. Read-only. Returns JSON: { symbol_id, snapshots: [{ commit, date, cyclomatic, nesting, params, lines }] }.

All-in-one context for starting a dev task: execution paths, tests, entry points, adapted by task type. Use as your FIRST call when beginning any new task — replaces manual chaining of search → get_symbol → Read. For narrower feature-code lookup use get_feature_context instead. Read-only. Returns JSON (default) or Markdown.

Per-module tech debt score (A–F grade) combining: complexity, coupling instability, test coverage gaps, and git churn. Includes actionable recommendations. Use for architecture review and prioritizing cleanup. Read-only. Returns JSON: { modules: [{ module, grade, score, factors, recommendations }] }.

Find test files and test functions that cover a given symbol or file. Use instead of Glob/Grep — understands test-to-source mapping, not just filename conventions. When symbol_id (or fqn) is provided, narrows file-level reachability to test files that actually exercise the symbol — graph-resolved calls (direct_invocation), import + textual reference (import_and_call), or bare textual mention (text_match). Default min_confidence is import_and_call. For project-wide test coverage gaps use get_untested_symbols instead. Read-only. Returns JSON: { tests: [{ test_file, symbol_id, test_name, line, edge_type, confidence }], total, symbol_filtered?, fell_back_to_file_level? }.

Daily token usage time-series: sessions, tokens, estimated cost, tool calls per day. For spotting cost spikes. Read-only. For detailed session breakdown use get_session_analytics instead. Returns JSON: { days, daily: [{ date, sessions, tokens, cost_usd, tool_calls }], totals }.

List all detected monorepo workspaces with file counts, symbol counts, and languages. Returns dependency graph between workspaces showing cross-workspace imports. Use for monorepo structure overview. For impact of changes on other workspaces use get_cross_workspace_impact instead. Read-only. Returns JSON: { workspaces: [{ name, files, symbols, languages }], dependencies }.

Mark a decision as no longer valid. The decision remains in the knowledge graph for historical queries but is excluded from active queries. Use when a decision is superseded or reversed. Mutates the decision store; idempotent. Returns JSON: { invalidated: { id, title, valid_until } }.

Mine Claude Code / Claw Code session logs for architectural decisions, tech choices, bug root causes, and preferences. Strategies: "regex" (default, free, fast, ~20-40% recall — pattern-based), "llm" (uses configured AI provider for higher recall, costs tokens), "hybrid" (regex + LLM safety net, dedups overlap). Skips already-mined sessions unless force=true. Honours memory.mining.incrementalCursor for byte-offset cursor reuse; pass incremental_cursor to override per call. Mutates the decision store; idempotent. Returns JSON: { mined, decisions_extracted, sessions_processed, strategy?, llm_sessions?, llm_decisions_extracted? }.

Opening-move router for new tasks. Combines BM25/PageRank search + session journal (negative evidence + focus signals) + framework-aware insertion-point suggestions + change-risk + turn-budget advisor into ONE call. Returns verdict (exists/partial/missing/ambiguous), confidence, ranked targets with provenance, scaffold hints when missing, and recommended next tool calls. Call this FIRST on a new task to break the empty-result hallucination chain. Read-only. For broader task context with source code use get_task_context instead. Returns JSON: { verdict, confidence, targets, scaffoldHints, nextSteps }.

Heuristic bug-risk triage: ranks files by a multi-signal score (git churn, fix-commit ratio, complexity, coupling, PageRank importance, author count), NOT a validated predictor. Each prediction includes a numeric score, risk bucket (low/medium/high/critical) AND a confidence_level (low/medium/high/multi_signal) counting how many independent signals actually fired. The score is a prioritization heuristic — on this repo, a temporal-holdout calibration (scripts/calibrate-health-metrics.mjs) shows the git signals rank future-fixed files above chance (churn Spearman ~0.3, ~2x precision@K lift over random), which is useful for triage but far from a guarantee. Result envelope includes _methodology disclosure with limitations. Cached for 1 hour; use refresh=true to recompute. Requires git. Use to prioritize where to look first, not to certify a file as buggy. For complexity+churn hotspots only use get_risk_hotspots instead. Read-only. Returns JSON: { predictions: [{ file, score, risk, confidence_level, signals }], total }.

Query the decision knowledge graph. Filter by type, subproject, code symbol, file path, tag, or time. Returns decisions linked to code — "why was this architecture chosen?" answered with the actual decision record. Use service_name to filter by a specific subproject within the project. By default returns auto-approved + human-approved decisions (review_status NULL or "approved"); use include_pending to also return the review queue, or review_status to fetch a specific tier. Each row carries cluster_ids when the decision belongs to any topical cluster, and the response includes a clusters_summary keyed off those ids. Read-only. Returns JSON: { decisions: [{ id, title, type, content, tags, review_status, cluster_ids? }], clusters_summary?, total_results }. Set output_format: "toon" for lossless TOON encoding — cheaper LLM tokens on tabular payloads. Hard-capped by memory.recall.timeoutMs (default 5000 ms); on timeout returns { decisions: [], total_results: 0, degraded: true }.

Notify trace-mcp that a file was edited. Reindexes the single file and invalidates search caches. Call after Edit/Write to keep index fresh — much lighter than full reindex. Also checks for duplicate symbols — if _duplication_warnings appears in the response, you may be recreating existing logic; review the referenced symbols before continuing. Mutates the index; idempotent. Returns JSON: { status, file, totalFiles, indexed, _duplication_warnings? }.

Trigger (re)indexing of the project or a subdirectory. Mutates the local index (SQLite). Use after major file changes; for single-file updates prefer register_edit instead. The optional postprocess flag controls how much work runs after raw symbol extraction: "full" (default) does everything; "minimal" skips LSP enrichment + env-var scan + git history snapshots (~30-50% faster on warm CI runs); "none" also skips edge resolution and gives you raw symbols only. Idempotent — safe to re-run. Returns JSON: { status, totalFiles, indexed, skipped, errors, durationMs, postprocess }.

Live agent write into the decision knowledge graph. Confidence-scores the input and routes it through the memoir review queue: high-confidence rows enter the active graph immediately, mid-confidence rows queue for human approval, low-confidence rows are dropped without persistence. Per-session dedup + rate-limit. Use during a session to capture decisions in real time. For manual high-confidence writes use add_decision; for post-hoc extraction from session logs use mine_sessions. Returns JSON: { id, review_status, confidence, deduplicated? }.

Safely remove a dead symbol from its file. Verifies the symbol is actually dead (multi-signal detection or zero incoming edges) before removal. Warns about orphaned imports in other files. Dry-run by default — preview the plan, then re-call with dry_run: false to apply. Destructive when applied — deletes code from source files. Use get_dead_code first to identify candidates. Returns JSON: { success, removed: { symbol_id, file }, orphanedImports }.

Scan project files for OWASP Top-10 security vulnerabilities using pattern matching. Detects SQL injection (CWE-89), XSS (CWE-79), command injection (CWE-78), path traversal (CWE-22), hardcoded secrets (CWE-798), insecure crypto (CWE-327), open redirects (CWE-601), and SSRF (CWE-918). Skips test files. Use for pattern-based security audit. For data-flow-aware analysis use taint_analysis instead. Read-only. Returns JSON: { findings: [{ rule, severity, cwe, file, line, message }], total, summary }.

Search symbols by name, kind, or text. Use instead of Grep when looking for functions, classes, methods, or variables in source code. For raw text/string/comment search use search_text instead. For finding who references a known symbol use find_usages instead. Supports kind/language/file_pattern filters. Set fuzzy=true for typo-tolerant search (trigram + Levenshtein). For natural-language / conceptual queries set semantic="on" (requires an AI provider configured + embed_repo run once). Set fusion=true for Signal Fusion — multi-channel ranking (BM25 + PageRank + embeddings + identity match) via Weighted Reciprocal Rank fusion. Use mode to switch retrieval strategy: single (default — top-K, current behavior), tiered (high/medium/low buckets), drill (scope to a parent_path/parent_symbol_id subtree via drill_from), flat (raw FTS hits, cheapest), get (exact path/symbol_id lookup, no search). Read-only. Returns JSON: { items: [{ symbol_id, name, kind, fqn, signature, file, line, score }], total, search_mode } — mode-specific shape when mode!=single. Set output_format: "toon" for lossless TOON encoding — cheaper LLM tokens on tabular payloads.

Full-text search across all indexed files. Supports regex, glob file patterns, language filter. Use for finding strings, comments, TODOs, config values, error messages — anything not captured as a symbol. For symbol search (functions, classes) use search instead. Read-only. Returns JSON: { matches: [{ file, line, text, context }], total_matches }. Set grouping: "by_file" to deduplicate file paths in results with many hits.

Dead code & coverage audit: dead exports, untested public symbols, heritage debt. Use as a one-shot health check combining dead exports + untested symbols + heritage debt. For individual checks use get_dead_exports, get_untested_symbols, or get_dead_code separately. Read-only. Returns JSON: { deadExports, untestedSymbols, heritageDebt, summary }.

Onboarding helper: shows top imported files, most connected symbols (PageRank), language stats, and example tool calls. Call this first when exploring an unfamiliar project. For a structured project map use get_project_map instead. Read-only. Returns JSON: { topFiles, topSymbols, languageStats, exampleQueries }.