io.github.nikolai-vysotskyi/trace-mcp

Execute multiple trace-mcp tools in a single MCP request. Dispatches any registered tool by name, including tools this session's preset defers — so a deferred tool is callable here without a load_tools round-trip (tools.exclude stays a hard restriction). 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 }.

Find all references to a symbol or file (imports, calls, renders, dispatches). Use instead of Grep for symbol usages — semantic, not text matches. For raw text use search_text; for a bidirectional call graph use get_call_graph. Weakly-grounded `text_matched` edges into a name-colliding target are dropped by default (phantom god-node filter); `include_ambiguous_text_matched: true` keeps them. Read-only. Returns JSON: { references: [{ edge_type, resolution_tier, file, symbol }], total, truncated?, ambiguous_filtered? } — page caps at 50, `total` counts all.

Build a bidirectional call graph centered on a symbol (who calls it + what it calls). Each branch keeps its direction: depth 2 = callers of callers, callees of callees. 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. Pass symbol_ids to scope to changed symbols. Use before modifying code. For a quick risk score alone use assess_change_risk; for who-calls-what use get_call_graph. compact pages results; bundle recalls. Read-only. Returns JSON: { risk, dependents, affectedTests, breakingChanges, totalAffected }.

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. For a single symbol without imports, use get_symbol — lighter. Read-only. Returns JSON: { primary: [{ symbol_id, file, source }], imports: [{ file, source }], token_usage }.

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 }.

Execute type-checker (tsc, mypy, pyright) and map errors to enclosing AST symbols. Read-only.

Search code by keyword/topic → returns ranked source 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..." }. Supports `output_format: "toon"`. Capped by `memory.recall.timeoutMs` (default 5000ms); on timeout returns `{ items: [], token_usage, degraded: true }`.

Get index status, statistics, health, and pipeline progress (indexing, summarization, embedding). Includes the session projectRoot; when the index is empty, next_steps names the empty root and points at list_projects + call_project_tool for other registered projects. Read-only, no side effects. Use to verify the index is ready before running queries. Returns JSON: { status, stats, projectRoot, next_steps?, config, warnings, pipelineProgress, embedding }.

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) — cheaper than Read for understanding a file before editing. Follow up with get_symbol to read one symbol's source. `nested: true` expands large top-level symbols (default ≥100 LOC) into inner declarations, each carrying `parentId` + `depth` (max 3). Read-only. Returns JSON: { path, language, symbols: [{ symbolId, name, kind, signature, lineStart, lineEnd, parentId?, depth? }] }. Supports `output_format: "toon"`.

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

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 }.

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 }.

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, report }.

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 }.

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.

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 }.

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 } }.

Load tools this session's preset deferred, by preset name and/or explicit tool names. Call with no arguments to list what is deferred. Emits notifications/tools/list_changed and returns the loaded tools' schemas, so they are usable even if your client ignores that notification (call them through `batch`). Returns JSON: { loaded, already_loaded, unknown, blocked, tools, hint }.

Mine Claude Code / Claw Code session logs for architectural decisions, tech choices, bug root causes, and preferences. Strategies: "regex" (default, free, ~20-40% recall), "llm" (higher recall, costs tokens), "hybrid" (regex + LLM safety net). Skips already-mined sessions unless force=true. 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 }.

Query the decision knowledge graph. Filter by type, subproject, code symbol, file path, tag, or time — answers "why was this architecture chosen?" with the actual decision record. Use service_name to scope to a subproject. Defaults to auto+human-approved decisions; use include_pending or review_status for other tiers. Rows carry `cluster_ids` when part of a topical cluster (see `clusters_summary`). Read-only. Returns JSON: { decisions: [{ id, title, type, content, tags, review_status, cluster_ids? }], clusters_summary?, total_results }. Supports `output_format: "toon"`. Capped by `memory.recall.timeoutMs` (default 5000ms); 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 flags duplicate symbols — if `_duplication_warnings` appears, you may be recreating existing logic; review them. Each one is reported once per file, not on every edit; `check_duplication` re-asks. Mutates the index; idempotent. Returns JSON: { status, file, totalFiles, indexed, _duplication_warnings? }.

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? }.

Search symbols by name, kind, or text. Use instead of Grep for functions, classes, methods, variables. For raw text/comment search use search_text; for references to a known symbol use find_usages. Read-only. Returns JSON: { items: [{ symbol_id, name, kind, fqn, signature, file, line, score }], total, search_mode } — mode-specific shape when mode!=single. Supports `output_format: "toon"`.

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: { files: [{ file, language, hits: [{ line, column, match, context }] }], total_matches } — hits grouped per file, so a long path is paid once. Pass `grouping: "flat"` for the ungrouped matches[] shape.

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 }.