Labsco
jgravelle logo

jCodeMunch-MCP

β˜… 2,000

from jgravelle

Token-efficient MCP server for GitHub source code exploration via tree-sitter AST parsing

πŸ”₯πŸ”₯πŸ”₯πŸ”₯βœ“ VerifiedFreeAdvanced setup
#email#automation#social-media#analytics#browser#database#voice#cloud

jCodeMunch MCP

The leading, most token-efficient MCP server for precise GitHub source code retrieval via tree-sitter AST parsing. Cut AI token costs 95%+ on code exploration β€” stop burning your context window reading entire files.

Real results, live from production 313B+ tokens saved Β· 45,000+ developers Β· $1.58M+ in AI spend avoided Β· 37,500+ kg COβ‚‚ prevented Live telemetry at jcodemunch.com β€” benchmark: 95% average token reduction (15 tasks / 3 repos, 99.8% peak).

Works with Claude Code, Cursor, VS Code, Codex CLI, Continue, Windsurf, and any MCP-compatible client.

One-click installs:

Prefer the command line?

Copy & paste β€” that's it
pip install jcodemunch-mcp
uvx jcodemunch-mcp

For pinned/B2B deployments that want a version-stable install channel independent of PyPI, install straight from the repo (requires git, builds from source):

Copy & paste β€” that's it
pip install git+https://github.com/jgravelle/jcodemunch-mcp.git
uvx --from git+https://github.com/jgravelle/jcodemunch-mcp.git jcodemunch-mcp

Quickstart - https://github.com/jgravelle/jcodemunch-mcp/blob/main/QUICKSTART.md

A crapload of detailed info: http://jcodemunch.com/

Live OSS code-health observatory β€” weekly six-axis health snapshots of Express, FastAPI, Gin, Pydantic, Django, Flask, NestJS, Cobra, and this very repo: https://jgravelle.github.io/jcodemunch-observatory/

Token Cost Radar β€” daily intelligence on AI token costs, minimization strategies, and budget trends for teams running Claude Code / Cursor / MCP: https://jcodemunch.com/radar/

FREE FOR PERSONAL USE

Use it to make money, and Uncle J. gets a taste. Fair enough? details

Our guarantee: If jCodeMunch doesn't pay for itself, you don't pay for jCodeMunch!

Documentation

Doc What it covers QUICKSTART.md Zero-to-indexed in three steps USER_GUIDE.md Full tool reference, workflows, and best practices AGENT_HOOKS.md Agent hooks and prompt policies CONFIGURATION.md JSONC config file reference, migration from env vars GROQ.md Groq Remote MCP integration, deployment, gcm CLI HEADLESS.md Using jCodeMunch with claude -p (and the jragmunch CLI) ARCHITECTURE.md Internal design, storage model, and extension points LANGUAGE_SUPPORT.md Supported languages and parsing details CONTEXT_PROVIDERS.md dbt, Git, and custom context provider docs TROUBLESHOOTING.md Common issues and fixes AGENT_INSTALL_UNIVERSAL.md Paste-and-go prompt for installing jCodemunch guidance into agent/IDE clients without a first-class jcm install target (Codex CLI, Cline, JetBrains AI, Aider, etc.). For Claude Code, Cursor, Windsurf, Continue β€” use jcm install <client> instead.

Compact output β€” the second token axis (MUNCH)

Retrieval decides what to send. MUNCH decides how to pack it.

Every tool response can be emitted in a purpose-built compact wire format instead of verbose JSON. Path prefixes are interned to short handles, homogeneous lists of dicts pack into single-character-tagged CSV rows, and per-column types are preserved so the decode is lossless.

Copy & paste β€” that's it
# any tool call accepts format=
find_references(identifier="get_user", format="auto")
# auto β€” emit compact if savings β‰₯ 15%, otherwise JSON
# compact β€” always compact
# json β€” never compact (back-compat passthrough)

Benchmark (v1.56.0): median 45.5% bytes saved across 6 representative tools, peaks at 55.4% on graph and outline responses. Full spec in SPEC_MUNCH.md; numbers and harness in TOKEN_SAVINGS.md.

Encoding savings stack on top of retrieval savings β€” every byte off the wire is a byte the agent doesn't pay to read.

Structured code retrieval for serious AI agents

What's new

  • v1.108.91 (2026-07-01) β€” Endpoint-scoped infrastructure links (get_endpoint_impact include_infra)

  • v1.108.90 (2026-06-30) β€” New tool: get_endpoint_impact (endpoint-centric blast radius)

  • v1.108.89 (2026-06-30) β€” Revert the 1.108.88 Antigravity install target; document correct manual config

Mentioned by

  • Artur SkowroΕ„ski (VirtusLab) β€” "roughly 80% fewer tokens, or 5Γ— more efficient β€” index once, query cheaply forever" Β· GitHub All-Stars #15

  • Julian Horsey (Geeky Gadgets) β€” "3,850 tokens reduced to just 700 β€” a 5.5Γ— improvement" Β· JCodeMunch AI Token Saver

  • Sion Williams β€” "preserving tokens for tasks that actually require reasoning rather than retrieval" Β· March 2026 AI Workflow Update

  • Traci Lim (AWS Β· ASEAN AI Lead) β€” "structural queries that native tools can't answer: find_importers, get_blast_radius, get_class_hierarchy, find_dead_code" Β· 5 Repos That Save Token Usage in Claude Code

  • Eric Grill β€” "context is the scarce resource. Cut it by 90% and the whole stack gets cheaper and more reliable" Β· jCodemunch: Context Engine for AI Agents

Full recognition page β†’

Commercial licenses

jCodeMunch-MCP is free for non-commercial use.

Commercial use requires a paid license.

jCodeMunch-only licenses

Want the full jMunch suite (code + docs + data)?

Stop paying your model to read the whole damn file.

jCodeMunch turns repo exploration into structured retrieval.

Instead of forcing an agent to open giant files, wade through imports, boilerplate, comments, helpers, and unrelated code, jCodeMunch lets it navigate by what the code is and retrieve only what matters.

That means:

  • 95%+ lower code-reading token usage in many retrieval-heavy workflows

  • less irrelevant context polluting the prompt

  • faster repo exploration

  • more accurate code lookup

  • less repeated file-scanning nonsense

It indexes your codebase once using tree-sitter, stores structured symbol metadata plus byte offsets into the original source, and retrieves exact implementations on demand instead of re-reading entire files over and over.

Recent releases have made that retrieval workflow sharper and more useful in real engineering work, with BM25-based symbol search, fuzzy matching, semantic/hybrid search (opt-in, zero mandatory dependencies), query-driven token-budgeted context assembly (get_ranked_context), dead code detection (find_dead_code), untested symbol detection (get_untested_symbols), git-diff-to-symbol mapping (get_changed_symbols), architectural centrality ranking (get_symbol_importance, PageRank), cold-start orientation maps (get_repo_map β€” query-less, token-budgeted, signature-only repo overview ranked by PageRank), consolidation candidate detection (find_similar_symbols β€” multi-signal duplicate finder blending semantic embeddings, structural signature, and behavioral callee Jaccard; union-find clustering with verdict tiers and PageRank-based canonical-pick), cross-repo API contract surfacing (get_group_contracts β€” group of indexed repos in, ranked shared-symbol contracts out, each classified as de_facto_api / leaky_internal / dead_contract / version_skew with stability + breaking-change history + runtime hits), concrete-implementation discovery (find_implementations β€” multi-source resolution across LSP dispatch / class hierarchy / duck-typed / decorator-handler with confidence scoring), deletion preflight (check_delete_safe β€” composite verdict from importers + references + dead-code + runtime evidence + entry-point heuristics, with ranked blockers and recommended action), edit-safety preflight (check_edit_safe β€” the companion that answers "can I modify this," fusing signature impact, cyclomatic complexity, test-coverage presence, and runtime traffic into a verdict + recommended action), task-aware single-call context orchestration (assemble_task_context β€” natural-language task in, source-attributed context capsule out; auto-classifies into one of six intents with explainable keyword matching, auto-extracts anchor symbols from the task, runs the intent-appropriate sub-tool sequence end-to-end under one token budget), blast-radius depth scoring with source snippets, context bundles with token budgets, AST-derived call graphs and call hierarchy traversal, decorator-aware search and filtering, hotspot detection (complexity x churn), dependency cycles and coupling metrics, session-aware routing (plan_turn, turn budgets, negative evidence), agent config auditing, complexity-based model routing (Agent Selector), enforcement hooks (PreToolUse/PostToolUse/PreCompact), dependency graphs, class hierarchy traversal, multi-symbol bundles, live watch-based reindexing, automatic Claude Code worktree discovery (watch-claude), registry-wide auto-reindexing with one-command login-service install (watch-all + watch-install / watch-uninstall / watch-status; also exposed as MCP tool get_watch_status), auto-watch on demand (when watch: true in config, the server automatically indexes and watches any repo a tool is called against β€” ensuring fresh results from the first call), trusted-folder access controls, edit-ready refactoring plans (plan_refactoring) for rename, move, extract, and signature change operations, symbol provenance archaeology (get_symbol_provenance β€” full git lineage, semantic commit classification, evolution narrative), unified PR risk profiling (get_pr_risk_profile β€” composite risk score fusing blast radius, complexity, churn, test gaps, and volume), automatic response secret redaction (AWS/GCP/Azure/JWT/GitHub tokens scrubbed before reaching the LLM context window), and cross-language AST pattern matching (search_ast β€” 10 preset anti-pattern detectors + custom mini-DSL for structural queries like call:*.unwrap, string:/password/i, nesting:5+; works across all 70+ languages with universal node-type mapping).

Real-world results

Reproducible token efficiency benchmark

Measured with tiktoken cl100k_base across three public repos. Workflow: search_symbols (top 5) + get_symbol_source Γ— 3 per query. Baseline: all source files concatenated (minimum cost for an agent that reads everything). Full methodology and harness β†’

Repository Files Symbols Baseline tokens jCodeMunch tokens Reduction expressjs/express 34 117 73,838 ~1,300 avg 98.4% fastapi/fastapi 156 1,359 214,312 ~15,600 avg 92.7% gin-gonic/gin 40 805 84,892 ~1,730 avg 98.0% Grand total (15 task-runs) 1,865,210 92,515 95.0%

Per-query results range from 79.7% (dense FastAPI router query) to 99.8% (sparse context-bind query on Express). The 95% figure is the aggregate. Run python benchmarks/harness/run_benchmark.py to reproduce.

A/B test on production codebase

Independent 50-iteration A/B test on a real Vue 3 + Firebase production codebase β€” JCodeMunch vs native tools (Grep/Glob/Read), Claude Sonnet 4.6, fresh session per iteration:

Metric Native JCodeMunch Success rate 72% 80% Timeout rate 40% 32% Mean cost/iteration $0.783 $0.738 Mean cache creation 104,135 93,178 (βˆ’10.5%)

Tool-layer savings isolated from fixed overhead: 15–25%. One finding category appeared exclusively in the JCodeMunch variant: orphaned file detection via find_importers β€” a structural query native tools cannot answer without scripting.

Full report: benchmarks/ab-test-naming-audit-2026-03-18.md

Why agents need this

Most agents still inspect codebases like tourists trapped in an airport gift shop:

  • open entire files to find one function

  • re-read the same code repeatedly

  • consume imports, boilerplate, and unrelated helpers

  • burn context window on material they never needed in the first place

jCodeMunch fixes that by giving them a structured way to:

  • search symbols by name, kind, or language β€” with fuzzy matching and optional semantic/hybrid search

  • inspect file and repo outlines before pulling source

  • retrieve exact symbol implementations only

  • grab a token-budgeted context bundle or ranked context pack for a task

  • fall back to text search when structure alone is not enough

  • detect dead code, trace impact, rank by centrality, and map git diffs to symbols

  • plan the next turn with plan_turn β€” confidence-guided routing before the first read

  • assemble a whole task's context in one call with assemble_task_context β€” intent-classified, multi-tool, single token budget

  • track session state and avoid re-reading files the agent already explored

Agents do not need bigger and bigger context windows.

They need better aim.

What you get

Symbol-level retrieval

Find and fetch functions, classes, methods, constants, and more without opening entire files.

Faster repo understanding

Inspect repository structure and file outlines before asking for source.

Lower token spend

Send the model the code it needs, not 1,500 lines of collateral damage.

One-call task orchestration β€” the tools compose, they don't sit in isolation

The retrieval primitives below are not a disconnected bag of tools the agent has to wire together by hand. Two composition tools drive the rest:

  • assemble_task_context takes a natural-language task and returns a single source-attributed context capsule under a token budget. It auto-classifies the task into one of six intents (explore / debug / refactor / extend / audit / review), auto-extracts the anchor symbols, and runs the intent-appropriate sequence of the tools below end-to-end β€” so the agent gets the whole context for a task in one request instead of chaining five. Every entry is tagged with its stage and source_tool, so the provenance is auditable.

  • plan_turn is the opening move: it analyzes the query against the index and returns a confidence-guided route β€” which tools to call, on which symbols, under a turn budget β€” before the first read. Low confidence means "this probably doesn't exist," so the agent stops instead of burning a budget hunting for a feature that isn't there.

  • get_ranked_context packs the most relevant symbols for a query into a fixed token budget (BM25 + PageRank), when you want a ranked context pack rather than a full intent sequence.

The point: jCodeMunch is structured retrieval with an orchestration layer over it, not a pile of primitives. The composition tools run the right sub-tools, in the right order, under one budget, in one call.

Structural queries native tools can't answer

find_importers tells you what imports a file. get_blast_radius tells you what breaks if you change a symbol, with depth-weighted risk scores and optional source snippets. get_class_hierarchy traverses inheritance chains. get_call_hierarchy traces callers and callees N levels deep using AST-derived call graphs, with optional LSP-enriched dispatch resolution for interface/trait method calls. find_dead_code finds symbols and files unreachable from any entry point. get_untested_symbols finds functions with no evidence of test-file reachability β€” the intersection of import-graph analysis and test-file detection. get_changed_symbols maps a git diff to the exact symbols that were added, modified, or removed. get_symbol_importance ranks your codebase by architectural centrality using PageRank on the import graph. get_hotspots surfaces the riskiest code by combining complexity with git churn. get_dependency_cycles detects circular imports. get_coupling_metrics measures module coupling and instability. get_tectonic_map discovers the logical module topology by fusing three coupling signals (imports, shared references, git co-churn) β€” revealing hidden module boundaries, misplaced files, and god-module risk without any configuration. get_signal_chains traces how external signals (HTTP requests, CLI commands, scheduled tasks, events) propagate through the codebase via the call graph β€” discovery mode maps all entry-point-to-leaf pathways and reports orphan symbols, lookup mode tells you which user-facing chains a specific symbol participates in (e.g. "validate_email sits on POST /api/users and cli:import-users"). get_endpoint_impact answers the endpoint-shaped version of "what breaks if I change X": give it an HTTP endpoint (GET /users) or a handler symbol and it resolves the route to its handler β€” across string-dispatch (Django/Express/Flask/Rails) and decorator routes (Flask/FastAPI/Spring) β€” then fuses the blast radius (importing files + callers) with the templates that handler renders, in one read-only call mapping a URL to everything a change to it would touch; pass include_infra=true and it also crosses the code/infra boundary, surfacing the env vars, compose services, Dockerfiles, CI jobs, and scripts whose project-intel cross-references land in that endpoint's blast radius. These are not "faster grep" β€” they are questions grep cannot answer at all.

Agent config hygiene

audit_agent_config scans your CLAUDE.md, .cursorrules, copilot-instructions.md, and other agent config files for token waste: per-file token cost, stale symbol references (cross-referenced against the index β€” catches renamed or deleted functions), dead file paths, redundancy between global and project configs, bloat, and scope leaks. No other tool can tell you "line 15 references a function that was renamed three weeks ago."

Symbol provenance and PR risk profiling

get_symbol_provenance is git archaeology: given a symbol, it traces every commit that touched it, classifies each into semantic categories (creation, bugfix, refactor, feature, perf, rename, revert), extracts commit intent, and generates a human-readable narrative explaining who created it, why, and how it evolved. get_pr_risk_profile produces a unified risk assessment for a branch or PR β€” one call fuses blast radius, complexity, churn, test gaps, and change volume into a composite risk score (0.0–1.0) with actionable recommendations. get_delivery_metrics quantifies durable-change delivery over a window: of the non-merge commits in the last N days, how many landed and stuck versus were reverted or re-touched (churn-back) within a short horizon β€” with churn-hub files (CHANGELOG, version, a monolithic dispatch module) excluded from the rework signal so a shared ledger can't masquerade as rework. The durable count is the honest numerator for a cost-per-outcome ratio: pair it with AI spend (the delivery CLI takes --cost) to show how much got done for how little, instead of rewarding raw activity. All responses are automatically scanned for leaked credentials (AWS keys, JWTs, GCP service accounts, etc.) and redacted before reaching the LLM.

Cross-language AST pattern matching

search_ast brings structural code analysis to every language jCodeMunch indexes β€” write one query, match across all 70+ languages. Preset anti-patterns detect common problems without any configuration: empty_catch (silently swallowed errors), bare_except (catch-all handlers), deeply_nested (5+ control-flow levels), nested_loops (O(nΒ³)+ performance risk), god_function (100+ line functions), eval_exec (injection-risk dynamic execution), hardcoded_secret (credential patterns in strings), todo_fixme (unfinished work markers), magic_number (unexplained numeric constants), and reassigned_param (overwritten function parameters). Run category='all' for a full sweep, or focus on security, error_handling, complexity, performance, or maintenance. Custom queries use a mini-DSL: call:*.unwrap (find method calls by glob), string:/password/i (regex over string literals), comment:/TODO/i (regex in comments), nesting:5+, loops:3+, lines:80+ (threshold queries). Every match is attributed to its enclosing indexed symbol with complexity metadata β€” so you can see not just where the problem is, but how bad the surrounding function already is.

Multi-axis constraint queries

winnow_symbols composes signals that every other tool exposes separately β€” kind, complexity, decorator, direct call references, file glob, name regex, git churn, and PageRank importance β€” into a single AND-intersected query. Agents stop making four or five calls and merging results by hand: "functions that call db.Exec, cyclomatic > 10, churned in the last 30 days, ranked by importance" resolves in one round trip. Supported axes expose their own operator set (eq, in, matches, contains, numeric comparisons); the window for churn-based filters is per-criterion. Results include per-symbol importance, complexity, and churn scores so the agent can explain why each survivor made the cut.

Better engineering workflows

Useful for onboarding, debugging, refactoring, impact analysis, and exploring unfamiliar repos without brute-force file reading.

Refactoring Planner

plan_refactoring generates exact edit-ready instructions for rename, move, extract, and signature change operations. Returns {old_text, new_text} blocks compatible with any editor's find-and-replace, plus import rewrites, collision detection, new file generation, and multi-file coordination.

Calibrated retrieval signals (v1.74.0+ telemetry initiative)

Every retrieval result now ships with three machine-readable health signals so agents can stop guessing whether to trust the response:

  • _meta.confidence β€” calibrated 0–1 score combining top-1/top-2 score gap, top-1 strength, identity-match presence, and freshness. Lets an agent gate follow-up get_symbol_source calls on a single number.

  • _freshness ∈ {fresh, edited_uncommitted, stale_index} on every result entry, plus a _meta.freshness summary. Derived from index SHA vs git rev-parse HEAD and per-file mtime checks.

  • Per-tool latency telemetry (p50/p95/max/error_rate) exposed via get_session_stats.latency_per_tool and the analyze_perf tool. Optional SQLite sink (~/.code-index/telemetry.db) for cross-session analysis.

The tune_weights tool reads the persistent ranking ledger and learns per-repo retrieval weights (saved to ~/.code-index/tuning.jsonc). check_embedding_drift pins a 16-string canary to detect silent provider model changes. benchmarks/replay/ provides a CI-friendly retrieval-quality regression gate (nDCG/MRR/Recall) that every release runs against.

The suggest_corrections tool (and the reflect CLI) close the loop: they mine the same ranking ledger for retrieval regret β€” where retrieval failed and the agent had to re-ask β€” and return a prioritized, explainable set of suggested fixes (a CLAUDE.md routing or glossary line as a unified-diff preview, an index-freshness hint, a stale-config finding, a dry-run weight proposal). It is read-only by design: it suggests a patch and shows you the diff; applying it is your keystroke, never the server's. Requires perf_telemetry_enabled (it has a ledger to read only then) and returns an honest hint when off.

Local-first speed

Indexes are stored locally for fast repeated access.

How it works

jCodeMunch indexes local folders or GitHub repos, parses source with tree-sitter, extracts symbols, and stores structured metadata alongside raw file content in a local index. Each symbol includes enough information to be found cheaply and retrieved precisely later.

That includes metadata like:

  • signature

  • kind

  • qualified name

  • one-line summary

  • byte offsets into the original file

So when the agent wants a symbol, jCodeMunch can fetch the exact source directly instead of loading and rescanning the full file.

Background behavior, fully disclosed

Everything jCodeMunch does beyond answering a tool call is listed here. All of it is visible, opt-in or opt-out, and reversible.

  • File watching. The watch / watch-all / watch-claude commands (and watch: true in config) re-index files when they change. Watching runs inside a process you started and stops when that process exits. Nothing monitors your filesystem unless a jCodeMunch process you launched is running.

  • Login service β€” explicit opt-in only. jcodemunch-mcp watch-install registers watch-all as a login service (Windows Task Scheduler / macOS launchd / Linux systemd) so indexes stay fresh across reboots. This happens only when you run watch-install yourself; init, install, and normal server use never register a service. Inspect it with watch-status; remove it with watch-uninstall.

  • Anonymous savings telemetry. The server periodically sends a random anonymous ID plus aggregate token-savings counters to the project's public community meter. No code, no file paths, no repo names, no PII β€” counters only. The sender is a single background daemon thread that starts lazily on the first share (never at import, and never if you have opted out), so a plain import has no background side effect. Opt out with share_savings: false in config.jsonc or JCODEMUNCH_SHARE_SAVINGS=0; redirect the endpoint with JCODEMUNCH_TELEMETRY_URL.

  • Agent hooks. init / install can write hook entries (auto-reindex on edit, read-interception nudges) into your MCP client's settings. They're offered during the interactive flow, shown before writing, and fully removed by uninstall.

  • Local index storage. Indexes live at ~/.code-index/ (override with CODE_INDEX_PATH). Delete the directory and every trace of indexing is gone.

  • Live session journal. While the server runs, it periodically writes a small _session_live.json in ~/.code-index/ recording the files and searches the agent touched this session (paths and query strings only, no file contents). It exists so the out-of-process PreCompact hook can restore session orientation after context compaction. Throttled, atomically written, overwritten in place; disable with JCODEMUNCH_LIVE_JOURNAL=0.

The base package makes no other network calls and leaves no other persistent processes. AI-summary extras call their configured provider's API only when you enable them β€” see the extras matrix under Start fast .

Start fast

Ubuntu 24.04+ / Debian 12+: System Python is externally managed (PEP 668). Use pipx install jcodemunch-mcp or uv tool install jcodemunch-mcp instead of bare pip install.

Option A: One command (recommended)

Copy & paste β€” that's it
pip install jcodemunch-mcp
jcodemunch-mcp init

init auto-detects your MCP clients (Claude Code, Claude Desktop, Cursor, Windsurf, Continue), writes their config entries, installs the CLAUDE.md prompt policy so your agent actually uses jCodeMunch, optionally installs enforcement hooks (PreToolUse read guard + PostToolUse auto-reindex + PreCompact session snapshot), optionally indexes your project, and audits your agent config files for token waste. Run jcodemunch-mcp init --help for all flags.

Prefer a one-line CLAUDE.md? From v1.71.0 the server exposes a jcodemunch_guide tool that returns the same policy snippet claude-md --generate prints β€” with the running version embedded. Keep this single line in your CLAUDE.md / AGENT.md and the guide always matches the installed server:

Copy & paste β€” that's it
Call the jcodemunch_guide tool and strictly follow its instructions.

The tool is force-included, so it can't be hidden by disabled_tools or tier filtering.

For non-interactive CI or scripting:

Copy & paste β€” that's it
jcodemunch-mcp init --yes --claude-md global --hooks --index --audit

Option B: Manual setup

1. Install it

Copy & paste β€” that's it
pip install jcodemunch-mcp

Want semantic search? Install the local embedding extra for zero-config semantic search β€” no API keys, no internet after first download:

Copy & paste β€” that's it
pip install "jcodemunch-mcp[local-embed]" # bundled ONNX encoder (recommended)
jcodemunch-mcp download-model # fetch model (~23 MB, one-time)

Want AI-generated summaries? Install the extra for your provider:

Copy & paste β€” that's it
pip install "jcodemunch-mcp[anthropic]" # Claude
pip install "jcodemunch-mcp[gemini]" # Gemini
pip install "jcodemunch-mcp[openai]" # OpenAI-compatible
pip install "jcodemunch-mcp[all]" # all providers + local embeddings

Without an extra, summaries fall back to signatures (which still works β€” you just get shorter descriptions). Run jcodemunch-mcp config --check to verify your provider is installed and working.

Extras matrix β€” system surfaces each extra pulls in Most extras are pure-Python and self-contained. A few pull libraries that touch system surfaces worth noting for managed-endpoint and SOC 2 / HIPAA-adjacent deployments. For the base package alone, none of these surfaces are introduced.

Extra Transitive dependencies of note System surfaces (base, no extra) none none [local-embed] onnxruntime local CPU inference (no network after model download); model fetched on first run [anthropic] anthropic SDK outbound HTTPS to api.anthropic.com when AI summaries are enabled [gemini] google-generativeai outbound HTTPS to Google AI endpoints when AI summaries are enabled [openai] openai SDK outbound HTTPS to api.openai.com (or OPENAI_API_BASE) when AI summaries are enabled [groq] openai SDK outbound HTTPS to Groq endpoints; used by the gcm CLI and speedreview Action [groq-voice] sounddevice, numpy microphone access β€” sounddevice.InputStream opens the system audio device when the voice path is invoked [groq-explain] Pillow image decode / re-encode of attached screenshots [all] union of all the above union of all surfaces above, including microphone ([groq-voice]) and image libraries ([groq-explain])

For managed-endpoint deployments where microphone access on developer machines is policy-restricted (HIPAA, SOC 2, finance), pin to the base package or to the specific provider extras you need. The voice and explain paths are opt-in features, not part of the core MCP server functionality, and [all] is the only extra that bundles them together.

Upgrading

Upgrade through whatever installed it, then restart your editor / MCP client so it relaunches the server on the new version:

Copy & paste β€” that's it
pip install -U jcodemunch-mcp # pip
pipx upgrade jcodemunch-mcp # pipx
uv tool upgrade jcodemunch-mcp # uv tool
uvx jcodemunch-mcp@latest --help # uvx (forces a cache refresh)

Check what you're running with jcodemunch-mcp --version.

Prefer not to touch the command line? jMunch Console (free, MIT, opt-in) makes upgrades one click β€” it shows an "update available" badge when a newer release exists and runs the install for you in a visible terminal (uv / pipx / pip, whichever you have), so you never copy a command.

2. Add it to your MCP client

If you’re using Claude Code, pick whichever matches what you installed in step 1.

Pip install (simplest, what most people do):

Copy & paste β€” that's it
claude mcp add -s user jcodemunch jcodemunch-mcp

The -s user flag registers it at user scope so it's available in every project. Without it, the registration is project-local and you'll see it missing the next time you cd elsewhere. If jcodemunch-mcp isn't found on PATH (common on Windows where pip install --user installs to AppData\Roaming\Python\PythonXYZ\Scripts\), use the absolute path:

Copy & paste β€” that's it
# Windows
claude mcp add -s user jcodemunch "C:\Users\YOU\AppData\Roaming\Python\Python312\Scripts\jcodemunch-mcp.exe"
# macOS/Linux β€” check `which jcodemunch-mcp` first
claude mcp add -s user jcodemunch "$(which jcodemunch-mcp)"

uvx (no pip install required, but uv must be on PATH):

Copy & paste β€” that's it
claude mcp add -s user jcodemunch uvx jcodemunch-mcp

'uvx' is not recognized (Windows / Cursor / any client)? uvx ships with uv. Install it with powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex", then fully restart your editor so it picks up the new PATH. To skip uv entirely: python -m pip install the package and launch with command: "python", args: ["-m", "jcodemunch_mcp"] instead.

If /mcp reports failed with no reason, run claude --mcp-debug or check %USERPROFILE%\AppData\Roaming\Claude\logs\mcp*.log β€” the /mcp summary hides the actual error.

If you’re using Paperclip (the multi-agent orchestration platform), add a .mcp.json to your workspace root:

Copy & paste β€” that's it
{
 "mcpServers": {
 "jcodemunch": {
 "type": "stdio",
 "command": "uvx",
 "args": ["jcodemunch-mcp"]
 },
 "jdocmunch": {
 "type": "stdio",
 "command": "uvx",
 "args": ["jdocmunch-mcp"]
 }
 }
}

Paperclip’s Claude Code agents auto-detect .mcp.json at startup. Add both servers to give your agents symbol search + doc navigation without blowing the token budget.

3. Tell your agent to actually use it

This matters more than people think.

Installing jCodeMunch makes the tools available. It does not guarantee the agent will stop its bad habit of brute-reading files unless you instruct it to prefer symbol search, outlines, and targeted retrieval. The changelog specifically calls out improved onboarding around this because it is a real source of confusion for first-time users.

A simple instruction like this helps:

Copy & paste β€” that's it
Use jcodemunch-mcp for code lookup whenever available. Prefer symbol search, outlines, and targeted retrieval over reading full files.

Note: jcodemunch-mcp init handles steps 2 and 3 automatically. For a comprehensive guide on enforcing these rules through agent hooks and prompt policies, see AGENT_HOOKS.md.

Starter Packs

Pre-built indexes for popular frameworks and libraries. Skip the initial indexing step β€” install a pack and start querying immediately.

Copy & paste β€” that's it
# List available packs
jcodemunch-mcp install-pack --list

# Install a free pack
jcodemunch-mcp install-pack fastapi

# Install a licensed pack
jcodemunch-mcp install-pack express --license YOUR-KEY

Free packs require no license. Licensed packs require a jCodeMunch license. Use --force to re-download an already-installed pack.

Groq Integration

Use jCodeMunch as a remote MCP tool with Groq's ultra-fast inference β€” answer codebase questions in seconds with zero local setup.

Copy & paste β€” that's it
from openai import OpenAI

client = OpenAI(api_key="YOUR_GROQ_KEY", base_url="https://api.groq.com/openai/v1")

response = client.responses.create(
 model="llama-3.3-70b-versatile",
 input="What does parse_file do in jgravelle/jcodemunch-mcp?",
 tools=[{
 "type": "mcp",
 "server_label": "jcodemunch",
 "server_url": "https://YOUR_JCODEMUNCH_URL",
 "headers": {"Authorization": "Bearer YOUR_TOKEN"},
 "server_description": "Code intelligence via tree-sitter AST parsing.",
 "require_approval": "never",
 }],
)

Groq handles MCP tool discovery and execution server-side β€” one API call, no orchestration needed.

Self-host with Docker + Caddy for auto-TLS:

Copy & paste β€” that's it
DOMAIN=mcp.example.com JCODEMUNCH_HTTP_TOKEN=secret docker compose up -d

See GROQ.md for the full tutorial: allowed-tools presets, model recommendations, deployment options, and validation scripts.

speedreview β€” AI Code Review GitHub Action

Get a structured PR review in under 5 seconds:

Copy & paste β€” that's it
# .github/workflows/speedreview.yml
- uses: jgravelle/jcodemunch-mcp/[emailΒ protected]
 with:
 groq_api_key: ${{ secrets.GROQ_API_KEY }}

For stricter supply-chain hygiene, pin to the tag's commit SHA instead of the tag itself (git ls-remote https://github.com/jgravelle/jcodemunch-mcp refs/tags/v1.108.52). The action installs pinned package versions by default and exposes jcodemunch_version / openai_version inputs for override.

See speedreview/README.md for full setup and configuration.

gcm β€” Codebase Q&A CLI

Ask any question about any codebase. Get an answer in under 3 seconds.

Copy & paste β€” that's it
pip install jcodemunch-mcp[groq]
export GROQ_API_KEY=gsk_...

# Ask about a GitHub repo (auto-indexes on first use)
gcm "how does authentication work?" --repo pallets/flask

# Ask about the current directory
gcm "where are the API routes defined?"

# Interactive chat mode
gcm --chat --repo facebook/react

# Use the fast 8B model
gcm "what does parse_file do?" --fast

Combines jCodeMunch's token-efficient retrieval (BM25 + PageRank) with Groq's 280+ tok/s inference for near-instant answers. See gcm --help for all options.

gcm --voice β€” Voice-to-Codebase

Speak a question, hear the answer. Full audio loop: Whisper STT β†’ retrieval β†’ LLM β†’ Orpheus TTS.

Copy & paste β€” that's it
pip install jcodemunch-mcp[groq-voice]

# Voice conversation with a codebase
gcm --voice --repo pallets/flask

# Press Enter to start recording, Enter again to stop
# Or type a question directly as text fallback

Push-to-talk via Enter key. Caps answers to ~100 words for natural spoken delivery. Requires a microphone.

gcm explain β€” Auto Repo Explainer

Generate a narrated explainer video for any codebase in a single command.

Copy & paste β€” that's it
pip install jcodemunch-mcp[groq-explain]

# Generate a 60-second narrated explainer
gcm explain --repo pallets/flask -o flask-explainer.mp4

# With verbose timing
gcm explain --repo facebook/react -v

Pipeline: repo structure β†’ LLM narration script β†’ Orpheus TTS β†’ Pillow slides β†’ FFmpeg MP4. Requires FFmpeg on PATH.

When does it help?

A common question: does this only help during exploration, or also when the agent is prompted to read a file before editing?

It helps most when editing a specific function. The "read before edit" constraint doesn't require reading the whole file β€” it requires reading the code. get_symbol_source gives you exactly the function body you're about to touch, nothing else. Instead of reading 700 lines to edit one method, you read those 30 lines.

Scenario Native tool jCodemunch Savings Edit one function (700-line file) Read β†’ 700 lines get_symbol_source β†’ 30 lines ~95% Understand a file's structure Read β†’ full content get_file_outline β†’ names + signatures ~80% Find which file to edit Grep many files search_symbols β†’ exact match comparable Edit requires whole-file context Read β†’ full content get_file_content β†’ full content ~0% "What breaks if I change X?" not possible get_blast_radius unique capability

The cases where it doesn't help: edits that genuinely require understanding the entire file (restructuring file-level state, reordering logic that spans hundreds of lines). For those, get_file_content is roughly equivalent to Read. The cases where it helps most are targeted edits β€” one function, one method, one class β€” which is the majority of real editing work.

Best for

  • large repositories

  • unfamiliar codebases

  • agent-driven code exploration

  • refactoring and impact analysis

  • teams trying to cut AI token costs without making agents dumber

  • developers who are tired of paying premium rates for glorified file scrolling

New here?

Start with QUICKSTART.md for the fastest setup path.

Then index a repo, ask your agent what it has indexed, and have it retrieve code by symbol instead of reading entire files. That is where the savings start.

Works with

jCodeMunch is an MCP server β€” it plugs into every major agent and IDE that speaks MCP:

Claude Code Β· Claude Desktop Β· Cursor Β· Windsurf Β· Codex CLI Β· Continue Β· Cline Β· Roo Code Β· Zed Β· Goose Β· Hermes Agent Β· Paperclip β€” and more.

Tested configurations:

Platform Config Claude Code / Claude Desktop jcodemunch-mcp init (auto-detects and patches config) Cursor / Windsurf / Continue jcodemunch-mcp init or manual mcp.json Antigravity (Google) Add a jcodemunch entry to ~/.gemini/config/mcp_config.json (shared by Antigravity 2.0 / IDE / CLI). See below. OpenAI Codex CLI Add [mcp_servers.jcodemunch] block to ~/.codex/config.toml (see below) Cline / Roo Code Add via the MCP marketplace UI or paste command: uvx, args: ["jcodemunch-mcp"] Zed Add to settings.json under context_servers Goose (Block) goose configure β†’ Add Extension β†’ command uvx jcodemunch-mcp Hermes Agent Add to ~/.hermes/config.yaml β€” see skill Paperclip .mcp.json at workspace root (auto-detected) Any other MCP client stdio: jcodemunch-mcp, HTTP: jcodemunch-mcp serve --transport sse VS Code (any MCP client) Install the jCodeMunch VS Code extension for on-save auto-reindex under Copilot Chat / Continue / Cline β€” closes the staleness gap when the host doesn't fire PostToolUse hooks GitHub Copilot CLI / cloud agent jcodemunch-mcp init --copilot-hooks writes .github/hooks/hooks.json with a postToolUse rule for auto-reindex Odysseus (self-hosted AI workspace) SSE transport: run jcodemunch-mcp serve --transport sse on the host (token unset), register the URL in the MCP Registry (see below) β€” community-tested

Codex CLI config Recommended (pre-installed binary, no uvx). Codex's rmcp transport is strict about the first JSON-RPC frame on stdout. uvx's install chatter on first run can poison the handshake, which historically manifests as a silent multi-hour hang. Install the package into a project venv and point Codex at the resolved binary directly:

Copy & paste β€” that's it
python3 -m venv .venv
.venv/bin/pip install -U jcodemunch-mcp
.venv/bin/jcodemunch-mcp --help # confirm the binary resolves
Copy & paste β€” that's it
# ~/.codex/config.toml
[mcp_servers.jcodemunch]
command = "/absolute/path/to/.venv/bin/jcodemunch-mcp"
# (no args required)

If the handshake still doesn't complete, set JCODEMUNCH_HANDSHAKE_TIMEOUT=5 (the default) and watch stderr β€” v1.82.1+ emits a one-line hint when the client doesn't call any handler within the window.

Note for codex review --background and other non-interactive runs. Codex's MCP elicitation/approval system can silently decline tool calls to unrecognised servers in non-interactive mode (visible in ~/.codex/logs_2.sqlite as ResolveElicitation { decision: Decline } with no chatter on the server side). This is a Codex-side concern, not a jcodemunch one β€” track upstream here for the right per-server auto-approve key. Interactive codex runs are unaffected.

Legacy uvx config (kept for reference; works on tolerant clients, not recommended for Codex):

Copy & paste β€” that's it
[mcp_servers.jcodemunch]
command = "uvx"
args = ["jcodemunch-mcp"]

Antigravity (Google) config Antigravity (2.0, IDE, and CLI) loads MCP servers from a single shared file at ~/.gemini/config/mcp_config.json (HOME-level only β€” project-local .antigravitycli/mcp_config.json is read but not loaded). Add:

Copy & paste β€” that's it
// ~/.gemini/config/mcp_config.json
{
 "mcpServers": {
 "jcodemunch": {
 "command": "uvx",
 "args": ["jcodemunch-mcp"]
 }
 }
}

Restart Antigravity so it re-reads the config; tools appear under mcp(jcodemunch/*). To grant the jcodemunch agent skill to all Antigravity tools, drop the bundle from jcodemunch-mcp install claude-code --skills (at ~/.claude/skills/jcodemunch/SKILL.md) into the shared skills dir ~/.gemini/skills/jcodemunch/ (or the CLI-only ~/.gemini/antigravity-cli/skills/).

Hermes Agent config

Copy & paste β€” that's it
# ~/.hermes/config.yaml
mcp_servers:
 jcodemunch:
 command: "uvx"
 args: ["jcodemunch-mcp"]

Odysseus config (self-hosted AI workspace) Odysseus runs in Docker and indexes nothing itself; jCodeMunch indexes your code on the host. Run jCodeMunch as an SSE server on the host and register its URL in Odysseus. Its SSE client connects by URL only (no auth header), so leave the token unset and secure the endpoint by network binding instead.

1. Start jCodeMunch on the host (no token):

Copy & paste β€” that's it
jcodemunch-mcp index .
jcodemunch-mcp serve --transport sse --host 0.0.0.0 --port 8848

Leave JCODEMUNCH_HTTP_TOKEN unset β€” Odysseus's SSE client sends no Authorization header, so a token returns 401 on connect.

2. In Odysseus β†’ Settings β†’ MCP Registry β†’ Add server:

  • Transport: SSE

  • URL: http://host.docker.internal:8848/sse (Linux: add extra_hosts: ["host.docker.internal:host-gateway"] to the Odysseus service in docker-compose.yml)

3. Secure by network, not token. Because the SSE path is unauthenticated, bind jCodeMunch so only the Odysseus container can reach it (host-gateway interface / firewall), not a public interface. JCODEMUNCH_RATE_LIMIT adds a throttle.

4. Restart Odysseus. All jCodeMunch tools appear in chat + agents. Keep the index fresh with jcodemunch-mcp watch .; use Odysseus's per-server disabled_tools to trim the surface.

jCodeMunch is read-only by charter, and its get_* / search_* / find_* / check_* tool naming satisfies Odysseus's plan-mode read-only gate, so the suite stays usable in plan mode.

Community-tested: the MCP protocol round-trip (SSE connect + tool discovery) is verified; the container-to-host network dial depends on your Docker setup.