MCPcopy Create free account
hub / github.com/jgravelle/jcodemunch-mcp

github.com/jgravelle/jcodemunch-mcp

Chat with this repo
repository ↗ · DeepWiki ↗ · release v1.108.330 ↗ · + Follow · compare 202 versions
17,554 symbols 64,615 edges 1,148 files ⚖ MIT 8,014 documented · 46% ● updated 45d agov1.108.327 · 2026-10-02★ 2,7273 open issues

Browse by type

⨍ Functions 15,787◇ Types & classes 1,647↳ Endpoints 120
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

jCodeMunch MCP

The most token-efficient MCP server for precise source code retrieval via tree-sitter AST parsing. Cut AI token costs 86-99% on code exploration (96% average, benchmarked at 28.3x fewer tokens than a grep-and-read agent) and stop burning your context window reading entire files.

Real results, live from production 838B+ tokens saved · 136,000+ reporting installs · $4.2M+ in AI spend avoided · 100,000+ kg CO₂ prevented Counter figures as of 2026-08-17, valued at the $5/MTok Claude Opus input rate. All four only grow, so read them as floors. Live at jcodemunch.com.

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

Install now · Quickstart · See the evidence · Pricing

PyPI version PyPI - Python Version License MCP Local-first Issues closed DOI

Free for personal use. Use it to make money, and Uncle J. gets a taste. Fair enough? Commercial licenses below. Our guarantee: if jCodeMunch doesn't pay for itself, you don't pay for jCodeMunch.


Why jCodeMunch?

Most AI agents explore repositories the expensive way: open entire files, skim thousands of irrelevant lines, repeat. That is not "a little inefficient." That is a token incinerator.

jCodeMunch indexes a codebase once and lets agents retrieve only the exact code they need: functions, classes, methods, constants, outlines, and tightly scoped context bundles, with byte-level precision. It parses source with tree-sitter, stores structured symbol metadata (signature, kind, qualified name, summary, byte offsets) alongside raw file content in a local index, and fetches exact implementations on demand instead of re-reading files over and over.

Task Traditional approach With jCodeMunch
Find a function Open and scan large files Search symbol, fetch exact implementation
Understand a module Read broad file regions Pull only relevant symbols and imports
Explore repo structure Traverse file after file Query outlines, trees, and targeted bundles
"What breaks if I change X?" Not possible get_blast_radius

Index once. Query cheaply. Keep moving. Precision context beats brute-force context.


Evidence

Reproducible token efficiency benchmark

Measured with tiktoken cl100k_base across three public repos pinned to upstream commits, run 2026-09-03 on v1.108.316. Workflow: search_symbols (top 5) + get_symbol_source × 3 per query. Two baselines, same run, same corpus, same file reader:

  • Grep-top-3: rg -l the query terms, rank files by match count, open the top 3 whole. This is what a competent agent without the tool actually does, and it is the number to quote.
  • Read-all: every indexed source file concatenated. A ceiling nobody pays; retained for continuity with previously published figures.
Repository Files Symbols Grep-top-3 baseline jCodeMunch vs grep vs read-all
expressjs/express 186 455 15,724 avg 1,007 avg 15.6x 153.5x
fastapi/fastapi 1,186 13,240 85,296 avg 2,149 avg 39.7x 384.1x
gin-gonic/gin 98 1,451 31,975 avg 1,537 avg 20.8x 98.8x
Grand total (15 task-runs) 664,975 23,467 28.3x 241.1x

Against a grep-and-read agent: 96.5% reduction, 28.3x fewer tokens. No single multiple describes every query; the per-repo rows above are the spread. Against read-all the figure is 99.6%, but nobody pays that ceiling. Compact MUNCH wire encoding then trims a median 45.5% more bytes off responses.

Full methodology, pinned commits, harness, and known caveats: benchmarks/METHODOLOGY.md · Reproduce it yourself · TOKEN_SAVINGS.md

Independent A/B test on a production codebase

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: success rate 80% vs 72%, timeout rate 32% vs 40%, mean cache creation down 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

Mentioned by

Full recognition page →


Install

One-click installs

Install in VS Code Install in VS Code Insiders Install in Cursor

Recommended: one command

uv tool install jcodemunch-mcp
jcodemunch-mcp init

No virtualenv to manage, nothing written into system Python, and it works as-is on PEP 668 distros (Ubuntu 24.04+, Debian 12+) where bare pip install is refused. Don't have uv yet?

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, optionally indexes your project, and audits your agent config files for token waste.

Other install paths

Command Use it when
uvx jcodemunch-mcp Zero install. Runs from an ephemeral environment — nothing lands on disk permanently. The client entries init writes already invoke the server this way, so for most setups this is all that ever runs. ⚠ Enforcement hooks are the exception: they're spawned by a minimal-PATH subshell and resolve the executable by name, so they need uv tool install (or pipx/pip) to work.
pipx install jcodemunch-mcp You already standardise on pipx
pip install jcodemunch-mcp Inside a virtualenv you manage yourself

Verify:

jcodemunch-mcp --version

Manual Claude Code setup

claude mcp add -s user jcodemunch -- uvx jcodemunch-mcp

No install step — uvx fetches and runs the server on demand. Prefer it on your PATH (and required for enforcement hooks)? uv tool install jcodemunch-mcp, then claude mcp add -s user jcodemunch jcodemunch-mcp.

Then tell the agent to prefer the tools. This matters more than people think; installation makes the tools available but does not break the agent's brute-reading habit. One line in your CLAUDE.md does it:

Call the jcodemunch_guide tool and strictly follow its instructions.

Using Cursor, Windsurf, Codex CLI, Antigravity, Gemini CLI, Qwen Code, Kiro, Cline, Zed, Goose, Hermes, Odysseus, or Paperclip? Every tested client configuration lives in CLIENTS.md. Optional extras (local semantic search, AI summaries per provider) are in QUICKSTART.md; the system surfaces each extra pulls in are documented in SECURITY.md.


Quickstart

Full walkthrough: QUICKSTART.md. The two-minute version, inside your agent after init:

  1. Ask: "Index this repo with jcodemunch."
  2. Ask: "Using jcodemunch, find the function that handles authentication and show me its source."

The agent should answer via search_symbols and get_symbol_source, returning tens of lines instead of whole files. Confirm with get_session_stats: it reports tokens served and savings for the session. That is where the numbers on the meter come from.

Want to skip initial indexing for popular frameworks? Pre-built starter packs: jcodemunch-mcp install-pack --list (free packs need no license).


What you can do

  • Retrieve one symbol instead of loading a file. get_symbol_source returns the exact function body, byte-precise, for the majority of edits that touch one function in a 700-line file (~95% savings on that read).
  • Assemble a whole task's context in one call. assemble_task_context classifies the task intent, extracts anchor symbols, and runs the right tool sequence under one token budget. plan_turn routes the turn before the first read.
  • Ask structural questions grep can't answer. find_importers, get_blast_radius, get_call_hierarchy, find_dead_code, get_changed_symbols, get_hotspots, search_ast anti-pattern sweeps, and more. Two of them sound alike and are not: check_references answers where a name is used (import sites plus every file whose content mentions it), find_references answers who imports it, over the import graph alone, so a call site is invisible to it.
  • Preflight risky changes, and know when to stop. check_edit_safe, check_delete_safe, get_pr_risk_profile, and plan_refactoring with edit-ready {old_text, new_text} blocks. The two safety checks return stop_rule.terminal: true means no further jcodemunch call moves the verdict, so re-running find_importers or check_references to be sure is wasted work. It means final, not safe. corpus_inadequate (the index could not back an absence claim) and dynamic_import_boundary (a dynamic import can load the file) are never terminal, and each tool's description lists every verdict it returns. check_rename_safe answers safe: null rather than true when the import graph could not reach the symbol's file, so the files that use it were never checked, and get_pr_risk_profile answers risk_score: null with unmeasurable_axes when it could not measure the blast axis; a CI gate should fail on null. Hand the server your type checker's own output (jcodemunch-mcp import-trace --diagnostics <file>: mypy --output json, pyright --outputjson, tsc --pretty false, ruff --output-format json) and check_edit_safe, get_changed_symbols, get_pr_risk_profile and get_symbol_provenance say which symbols the checker already flags, as of which commit. Nothing runs a checker for you. False names the specific thing that would change the answer.
  • Trust the answers. Calibrated confidence scores, freshness flags, coverage contracts on absence claims, compiler-verified references via SCIP import, and automatic secret redaction before anything reaches the LLM.
  • Keep the index fresh automatically. Watch modes, agent hooks, and a VS Code extension close the staleness gap.

That's the highlight reel. The complete tour of 90+ tools, the MUNCH compact wire format, evidence receipts, offloadable-work annotation, and the session-economics instrumentation is in CAPABILITIES.md, with internals in UNDER_THE_HOOD.md.

What's new

  • v1.108.330 (2026-10-06) — the parse budget bounds a file's Python-side time
  • v1.108.329 (2026-10-05) — the parse budget stops a slow parse
  • v1.108.328 (2026-10-04) — a file a package.json script runs is an entry po

Extension points exported contracts — how you extend this code

browse all types & interfaces →

Core symbols most depended-on inside this repo

browse all functions →

Shape

Function 9,813
Method 5,974
Class 1,623
Route 120
Interface 12
Enum 6
Struct 6

Languages

Python99%
TypeScript1%
Rust1%
Go1%
C#1%
PHP1%

Modules by API surface

src/jcodemunch_mcp/parser/extractor.py387 symbols
tests/test_config.py150 symbols
tests/test_plan_refactoring.py137 symbols
src/jcodemunch_mcp/server.py126 symbols
tests/test_racket_language.py119 symbols
tests/test_watcher_serve.py115 symbols
tests/test_find_importers.py103 symbols
tests/test_v1_108_183.py99 symbols
tests/test_security.py91 symbols
src/jcodemunch_mcp/storage/token_tracker.py89 symbols
src/jcodemunch_mcp/storage/sqlite_store.py87 symbols
tests/test_project_intel.py82 symbols

Dependencies from manifests, versioned

@types/node20.0.0 · 1×
@types/vscode1.85.0 · 1×
typescript5.3.0 · 1×
faiss-cpu1.7.0 · 1×
httpx0.27.0 · 1×
langchain0.3.0 · 1×
langchain-community0.3.0 · 1×
langchain-huggingface0.1.0 · 1×
langchain-text-splitters0.3.0 · 1×
pathspec0.12.0 · 1×
pyyaml6.0 · 1×

Datastores touched

mydbDatabase · 1 repos

For agents

$ claude mcp add jcodemunch-mcp \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

Ask about this repo answers extend the page