jCodeMunch MCP

Index a GitHub repository's source code. Fetches files, parses ASTs, extracts symbols, and saves to local storage. Set JCODEMUNCH_USE_AI_SUMMARIES=false to disable AI summaries globally.

Index a local folder of source code. Response surfaces `discovery_skip_counts` and `no_symbols_files` for diagnosing missing files.

Re-run AI summarization on all symbols in an existing index. Use this when index_folder completed but AI summaries are missing — e.g., the background summarization thread was interrupted, AI was disabled at index time, or the summarizer provider wasn't configured yet. With for...

Index a single file within an existing index. Surgical update after edits. The file must be under an already-indexed folder's source_root. Can also add new files.

Ingest a runtime trace file into the runtime_* tables for the target repo. source='otel' takes OTel JSON / JSON-Lines / .gz and maps spans via (file_path, line_no, function_name); source='sql_log' takes pg_stat_statements CSV or a generic SQL JSON-Lines log and maps queries vi...

Runtime coverage histogram for a repo or a single file: count of indexed symbols with vs without runtime evidence, plus the diagnostic list of unmapped runtime spans (likely reflective dispatch the AST missed). Pairs with Phase 2's per-result _runtime_confidence stamping. Retu...

Top-N symbols ranked by total runtime hit count across ingested traces, with per-symbol p50/p95 latency, sources contributing, and last_seen. Optionally filtered by a name substring. Pairs with get_blast_radius to answer 'is this PR touching code that runs 4M times/day?' Retur...

Symbols with zero (or stale) runtime hits over the look-back window. Distinct from find_dead_code: this surfaces code that's reachable on paper but never executed — only possible to detect with runtime data. Excludes test files and entry-point filenames by default. Returns an...

Per-pattern PII redaction counts from runtime_redaction_log. Operators run this to verify the redaction chokepoint is firing on production traffic — covers the OTel / SQL / stack ingest paths (file-based or HTTP live-ingest, Phase 6). Returns {patterns: [{source, pattern, coun...

List all indexed repositories. START HERE before using Grep/Read/search tools — check if the project is already indexed, then use search_symbols / get_symbol_source instead of native file reads. If jcodemunch tools appear as deferred in your tool list, call ToolSearch to load...

No parameters. Call it with no arguments.

Report watch-all daemon coverage: every locally-indexed repo, each repo's staleness / reindex-in-progress state, and the OS-level service status. Call before relying on index freshness when you suspect files may have changed since the last index.

No parameters. Call it with no arguments.

Resolve a filesystem path to its indexed repo identifier. O(1) lookup — faster than list_repos for finding a single repo. Accepts repo root, worktree, subdirectory, or file path.

Get the file tree of an indexed repository, optionally filtered by path prefix. Results are capped at max_files (default 500) to prevent token overflow; use path_prefix to scope large trees.

Get all symbols (functions, classes, methods) in a file with full signatures (including parameter names) and summaries. Use signatures to review naming at parameter granularity without reading the full file. Pass repo and file_path (e.g. 'src/main.py').

Get full source of one symbol (symbol_id → flat object) or many (symbol_ids[] → {symbols, errors}). Supports verify, context_lines, and fqn (PHP FQN via PSR-4).

Get cached source for a file, optionally sliced to a line range.

Search for symbols matching a query across the entire indexed repository. Returns matches with signatures and summaries.

Delete the index and cached files for a repository. Forces a full re-index on next index_repo or index_folder call.

Full-text search across indexed file contents. Useful when symbol search misses (e.g., string literals, comments, config values). Supports regex (is_regex=true) and context lines around matches (context_lines=N, like grep -C).

Get a high-level overview of an indexed repository: directories, file counts, language breakdown, symbol counts. Lighter than get_file_tree.

Find all files that import a given file. Answers 'what uses this file?'. has_importers=false on a result means that importer is itself unreachable (dead code chain). Supports dbt {{ ref() }} edges. Use file_paths for batch queries. Set cross_repo=true to also find importers in...

Find all files that import or reference an identifier via the import graph. Answers 'where is this imported / re-exported?'. SCOPE: import sites + dbt `{{ ref() }}` edges + (when `include_call_chain=true`) symbols whose bodies textually mention the identifier. Does NOT exhaust...

Check if an identifier is referenced anywhere: imports + file content. Combines find_references and search_text into one call. Returns is_referenced (bool) for quick dead-code detection. Accepts multiple identifiers in one call via identifiers param.

Search column metadata across indexed models. Works with any ecosystem provider that emits column data (dbt, SQLMesh, database catalogs, etc.). Returns model name, file path, column name, and description. Use instead of grep/search_text for column discovery — 77% fewer tokens.

Get full source + imports for one or more symbols in one call. Multi-symbol bundles deduplicate shared imports. Set token_budget to cap response size; use budget_strategy to control what's kept. Supports fqn (PHP FQN via PSR-4) as alternative to symbol_id.

Get token savings stats for the current MCP session. Returns tokens saved and cost avoided (this session and all-time), per-tool breakdown, session duration, and cumulative totals. Use to see how much jCodeMunch has saved you.

No parameters. Call it with no arguments.

Per-tool latency telemetry: p50/p95/max in ms, error rate, plus cache hit-rate by tool. Defaults to the in-memory session ring; pass window=1h|24h|7d|all to query persisted telemetry.db (requires perf_telemetry_enabled). Useful for finding slow tools, cold caches, and regressi...

Pin (or re-check) a 16-string canary against the active embedding provider. On first run with capture=True (or force=True), embeds CANARY_STRINGS and persists the vectors to ~/.code-index/embed_canary.json. Subsequent calls re-embed those strings and report cosine drift; alarm...

Learn per-repo retrieval weights from the v1.78.0 ranking ledger. Computes confidence correlations for the semantic and identity-match channels and writes overrides to ~/.code-index/tuning.jsonc. search_symbols reads those overrides at query time when the caller doesn't pass a...

Get the current session context — files accessed, searches performed, and edits registered during this MCP session. Use to avoid re-reading the same files.

Get a compact session snapshot for context continuity. Returns a ~200 token markdown summary of files explored, edits made, searches performed, and dead ends. Designed for injection after context compaction to restore session orientation.

Per-symbol composite risk for one file. For each function or method, returns a 0-100 composite score (higher = healthier; lower = riskier) plus per-axis sub-scores (complexity, exposure, churn, test_gap). Powers the VS Code risk-density gutter. complexity is per-symbol (cyclom...

Compare two health-radar payloads (from get_repo_health.radar) and return axis-by-axis deltas, composite delta, grade movement, and a one-line verdict. Pure data transform — no index access, no I/O. Designed for PR-time diff-grade reports: run get_repo_health on the base branc...

Agent stand-up briefing for a repo. Returns a tight (~200 token) markdown digest of (a) what changed since the agent's last session (by tracking git HEAD between calls), (b) the current risk surface (top hotspots by complexity × churn), and (c) dead-code candidates. Each item...

Plan the next turn by analyzing query against the codebase. Returns confidence level (high/medium/low), recommended symbols/files, and guidance. Use as opening move for any task.

Register file edits to invalidate caches. Call after editing files to clear BM25 cache and search result cache for the repo.

Audit agent configuration files (CLAUDE.md, .cursorrules, copilot-instructions.md, etc.) for token waste. Reports per-file token cost, stale symbol references, dead file paths, redundancy between global and project configs, bloat patterns, and scope leaks. Cross-references aga...

Get the file-level dependency graph for a given file. Traverses import relationships up to 3 hops. Use to understand what a file depends on ('imports'), what depends on it ('importers'), or both. Prerequisite for blast radius analysis. Set cross_repo=true to include cross-repo...

Diff symbol sets between two indexed snapshots. Shows added, removed, and changed symbols. Branch workflow: index branch A as repo-main, index branch B as repo-feature, then diff.

Get the full inheritance hierarchy for a class: ancestors (base classes via extends/implements) and descendants (subclasses/implementors). Works across Python, Java, TypeScript, C#, and any language where class signatures contain 'extends' or 'implements'.

Find symbols related to a given symbol using heuristic clustering: same-file co-location (weight 3), shared importers (weight 1.5), and name-token overlap (weight 0.5/token). Useful for discovering what else to read when exploring an unfamiliar codebase.

Suggest search queries, entry-point files, and index stats. Good first call on an unfamiliar repo — surfaces most-imported files, top keywords, and ready-to-run example queries.

Find all files affected by changing a symbol. Returns confirmed files (import + name match) and potential files (import only, e.g. wildcard). Use before renaming or deleting a symbol. Set cross_repo=true to also find consumers in other indexed repos. Set include_source=true to...

Return incoming callers and outgoing callees for a symbol, N levels deep. Uses AST-derived call detection: callers = symbols in importing files that mention this name; callees = imported symbols mentioned in this symbol's body. Useful for understanding how a symbol fits into t...

Show what breaks if a symbol is removed or renamed. Walks the call graph transitively to find every symbol that calls this one, returning affected symbols grouped by file with call-chain paths. Use this before deleting or renaming a symbol to understand full impact. For a stru...

Trace the complete authorship lineage and evolution narrative of a symbol through git history. Returns every commit that touched the symbol (or its file), classified into semantic categories (creation, bugfix, refactor, feature, perf, rename, revert, etc.) with extracted commi...

Produce a unified risk assessment for all changes between two git refs (branch, PR, or SHA range). Fuses five signals — blast radius, complexity, churn, test gaps, and change volume — into a single composite risk_score (0.0–1.0) with actionable recommendations. Returns the top...

Detect circular import chains in a repository. Returns every strongly-connected component (set of files that mutually import each other, directly or transitively). Run this to identify architectural problems before a refactor, or to understand why a module is hard to test in i...

Return afferent coupling (Ca), efferent coupling (Ce), and instability score for a file/module. Ca = files that import this module (dependents). Ce = files this module imports (dependencies). Instability I = Ce/(Ca+Ce): 0 = stable, 1 = unstable. Use to identify fragile modules...

Check whether imports respect declared architectural layer boundaries. Reports every import that crosses a forbidden layer boundary. Layer rules can be passed directly or defined in .jcodemunch.jsonc under 'architecture.layers'. Use to enforce clean architecture and detect dep...

Check whether renaming a symbol to a new name would cause name collisions. Scans the symbol's own file and every file that imports it, looking for an existing symbol with the proposed new name. Returns safe=true when no collisions are found. Run this before any rename/refactor...

Composite preflight: can this symbol be deleted safely? Combines find_importers (cross-repo), check_references, find_dead_code confidence, runtime evidence (Phase 7 traces when available), and entry-point heuristics into a single verdict + one-line recommended_action. Verdict...

Find concrete implementations of an interface, abstract class, or method. Multi-source resolution with confidence scoring: LSP dispatch (1.0), AST class hierarchy (0.85), duck-typed name match (0.65), decorator handler (0.45). Classifies each impl (subclass_override / interfac...

Generate edit-ready refactoring instructions for renaming, moving, extracting, or changing the signature of a symbol. Returns {old_text, new_text} blocks for every affected file — directly compatible with Edit tool. Handles import rewrites, collision detection, new file genera...

Find likely-dead functions and methods using three independent evidence signals: (1) the symbol's file is not reachable from any entry point via the import graph (filename heuristic + package.json main/module/exports/bin), (2) no indexed symbol calls this symbol in the call gr...

Identify functions in a file that are good candidates for extraction to a shared module. A candidate must have high cyclomatic complexity (doing a lot) AND be called from multiple other files (already implicitly shared). Results are ranked by score = complexity × caller_file_c...

Return cyclomatic complexity, nesting depth, and parameter count for a single symbol. Complexity data is stored at index time (requires jcodemunch-mcp >= 1.16 / INDEX_VERSION 7). assessment field: 'low' (1-4), 'medium' (5-10), 'high' (11+). Re-index the repo if all metrics sho...

Return git churn metrics for a file or symbol: commit count, unique authors, first_seen date, last_modified date, and churn_per_week over a configurable window. assessment: 'stable' (<=1/week), 'active' (<=3/week), 'volatile' (>3/week). Requires a locally indexed repo (index_f...

Return the top-N highest-risk symbols ranked by hotspot score = cyclomatic_complexity x log(1 + commits_last_N_days). Identifies code that is both complex and frequently changed — the highest bug-introduction risk in the codebase. Methodology matches CodeScene/Adam Tornhill. R...

Return a one-call triage snapshot of the entire repository: symbol counts, dead code %, average cyclomatic complexity, top 5 hotspots, dependency cycle count, and unstable module count. Designed to be the first tool called in any new session — one call gives a complete picture...

Find functions and methods with no evidence of being exercised by any test file. Uses import-graph reachability + name matching (AST call_references when available, word-boundary text heuristic as fallback). Returns symbols classified as 'unreached' (no test file imports the s...

Cross-language AST pattern matching. Finds structural code patterns across all 70+ indexed languages using a single query — no need to know language-specific AST node types. Two modes: (1) preset anti-patterns (empty_catch, bare_except, deeply_nested, nested_loops, god_functio...

Return the most architecturally important symbols in a repo, ranked by PageRank or in-degree centrality on the import graph. Useful for orientation: surfaces the symbols that most of the codebase depends on. New tool: use after indexing to understand repo architecture at a gla...

Find clusters of similar functions/methods/classes — consolidation candidates. Blends three signals: semantic (embedding cosine when embed_repo has run), structural (signature-token Jaccard + size ratio), and behavioral (callee-set Jaccard). Runs union-find clustering, classif...

Query-less, token-budgeted, signature-level overview of a repository. Groups symbols by file, ranks files by PageRank on the import graph, and greedy-packs signatures (not bodies) under token_budget. Designed for cold-start orientation — 'I just cloned this repo, what matters...

Find dead code — files and symbols with zero importers and no entry-point role. Uses the import graph to identify unreachable code. Returns confidence scores (1.0 = provably unreachable, 0.7 = all importers are themselves dead). Set granularity='file' for file-level results only.

Assemble the best-fit context for a query within a token budget. Ranks all symbols by relevance (BM25) and/or centrality (PageRank), loads source for the top candidates, and packs greedily until token_budget is exhausted. Use when you want 'the best N tokens of context for thi...

Task-aware single-call orchestrator. Auto-classifies task into explore/debug/refactor/extend/audit/review intent, runs the right sub-tools, returns one source-attributed capsule under token_budget.

Map a git diff to affected symbols: given two commits, returns which symbols were added, removed, modified, or renamed. Useful after merging a PR to answer 'what actually changed?' for code review or regression triage. Requires a locally indexed repo (index_folder). Defaults t...

Precompute and cache symbol embeddings for semantic search. Optional warm-up: search_symbols with semantic=true lazily embeds missing symbols on first use, but embed_repo warms the cache upfront so the first semantic query returns immediately. Requires an embedding provider (J...

Return which indexed repos depend on which other indexed repos at the package level. Shows the full cross-repository dependency map based on package names extracted from manifest files (pyproject.toml, package.json, go.mod, Cargo.toml, etc.). Use to visualize how your indexed...

Surface the de-facto API contracts across a group of indexed repos. Walks each member's named imports, resolves them to symbols in other members via the package registry, and classifies each shared symbol into one of four verdict tiers: 'de_facto_api' (used by ≥min_importers e...

Discover the logical module topology of a codebase by fusing three coupling signals: structural (import edges), behavioral (shared symbol references), and temporal (git co-churn). Returns tectonic plates (auto-detected file clusters), each with an anchor file, cohesion score,...

Discover how external signals (HTTP requests, CLI commands, scheduled tasks, events) propagate through the codebase via the call graph. Each signal chain traces a path from a gateway (entry point) through its callees to leaf symbols. Two modes: (1) Discovery — omit symbol to m...

Render any graph-producing tool's output as rich, annotated Mermaid markup. Pass the raw output dict from get_call_hierarchy, get_signal_chains, get_tectonic_map, get_dependency_cycles, get_impact_preview, get_blast_radius, or get_dependency_graph. Auto-detects the source tool...

Auto-discover and parse non-code knowledge files (Dockerfiles, CI configs, docker-compose, K8s manifests, .env templates, Makefiles, package.json scripts) and cross-reference them to indexed code symbols. Returns structured intelligence grouped by category: infra, ci, config,...

Enumerate monorepo workspace members for an indexed repo. Detects pnpm (pnpm-workspace.yaml), yarn/npm (package.json workspaces), turborepo (turbo.json), lerna (lerna.json), rush (rush.json), Go (go.work), and Cargo ([workspace] members). Returns [{path, package_name, manager}...

Run a multi-axis constraint query against the index in a single round trip. Accepts an ordered list of criteria (AND) intersecting signals no other tool composes: kind, language, name (regex), file glob, cyclomatic complexity, decorator, direct call references, summary/docstri...

Explicit tier override for the current session. Narrows or widens the exposed tool list to 'core' / 'standard' / 'full'. Prefer plan_turn(model=...) for routine per-task use; use set_tool_tier only when you need an explicit override (e.g. escalate mid-task to 'full' after a ca...

Agent self-reports its active model identifier. Server resolves to a tier via model_tier_map (fuzzy: normalize → exact → glob → substring → '*' → 'full') and narrows the exposed tool list accordingly. Idempotent: a second call with the same model is a cheap no-op. Prefer calli...