jCodeMunch MCP: symbol-level code retrieval for AI agents

What jCodeMunch MCP replaces

An agent that explores a repository the ordinary way opens whole files, reads thousands of lines it does not need, and repeats the exercise on the next question. The README calls this a token incinerator, and the mechanism is easy to see: file reads are billed by volume, not by relevance. jCodeMunch MCP takes the opposite position. It parses a codebase once with tree-sitter, stores structured symbol metadata (signature, kind, qualified name, summary, byte offsets) next to the raw file content in a local index, and then answers queries for a single function, class, method or constant instead of handing over a file. The audience is anyone running an MCP-compatible coding client against a repository large enough that context pressure shows up in cost or in truncated answers. The README lists Claude Code, Cursor, VS Code, Codex CLI, Windsurf, Continue and any MCP-compatible client. It is a retrieval layer, not an editor and not a linter. If your questions are already narrow, or your repository is small, the index is overhead you will pay for and not recover.

How the tree-sitter index and MCP tools fit together

The pipeline has three stages. Parsing: tree-sitter produces an AST per file, and the server extracts symbols with their byte offsets. Storage: those symbols and the raw file content go into a local index, whose location is set by CODE_INDEX_PATH (the Docker image points it at /data/code-index). Serving: an MCP client calls tools over stdio or SSE, and the server returns the exact byte range for the requested symbol. The README's benchmark workflow is search_symbols with the top 5 results plus three get_symbol_source calls per query, which is a useful sketch of the intended call pattern. Beyond plain lookup, the README names structural queries that a text search cannot answer without scripting: get_blast_radius for what breaks if a symbol changes, find_importers, get_class_hierarchy and find_dead_code. Responses can be encoded in the project's MUNCH wire format, which the README says trims a median 45.5% more bytes. The index is the whole design: cheap queries are only cheap because parsing happened once, up front.

Installing jCodeMunch MCP from PyPI or Docker

The project publishes to PyPI as jcodemunch-mcp and requires Python 3.10 or newer. The install badge in the README uses uvx, which runs the package without a permanent install, and that is the shortest path to a working server.

uvx jcodemunch-mcp

Running that command starts the server on stdio, which is what most MCP clients expect. You then register the same command in the client's MCP configuration. The README also offers one-click install badges for VS Code and VS Code Insiders that encode the uvx invocation directly.

For a shared or remote deployment, the repository ships a Dockerfile and a docker-compose.yml that pair the server with Caddy for automatic TLS. The compose file exposes the SSE transport on port 8901 and reads its bearer token and rate limit from the environment.

DOMAIN=mcp.example.com JCODEMUNCH_HTTP_TOKEN=mysecret docker compose up -d

After that, the compose file's own comment says the server is reachable at http://localhost:8901/sse for local testing without TLS. The relevant environment variables in the compose file are CODE_INDEX_PATH, JCODEMUNCH_TRANSPORT, JCODEMUNCH_HOST, JCODEMUNCH_PORT, JCODEMUNCH_HTTP_TOKEN and JCODEMUNCH_RATE_LIMIT, the last defaulting to 60. The image runs as a non-root user and declares a healthcheck that opens a socket to localhost:8901. Note that JCODEMUNCH_HTTP_TOKEN defaults to an empty string in the compose file; leaving it unset on a reachable host means no bearer token at all.

The mcp 2.x ceiling and other limits

The sharpest constraint is recorded in pyproject.toml as a comment on the dependency pin: mcp>=1.10.0,<2.0.0. The reason given is specific. Against mcp 2.2.0, measured on 2026-09-11, the 2.x low-level Server has no decorator registration, so the six @server.<handler>() sites in server.py fail at import and no stdio initialize completes. Handlers in 2.x are constructor keyword arguments such as on_call_tool with a (ctx, params) signature. The comment states plainly that moving the pin is a port, not a bump. Practically, that means a client or environment that forces the 2.x SDK will not work with this server until the port lands. A second constraint is grammar delivery. The same file notes that tree-sitter 1.x stopped bundling grammars: the wheel ships one native module and get_parser downloads the grammar into a user-level cache on first use, verified as 67 shared libraries while walking the language list. First use of a new language therefore needs network access and a writable cache. Third, the project is dual-use rather than OSI-approved: pyproject.toml declares license = "LicenseRef-jCodeMunch-Dual-Use-1" and the README says free for personal use, with commercial licences sold separately. If your procurement requires a recognised open source licence, this is the wrong tool regardless of how well the retrieval works.

How jCodeMunch MCP differs from Sourcegraph SCIP indexes

A real alternative for symbol-level code intelligence is a SCIP-based index, the format Sourcegraph uses for precise cross-repository navigation. The repository carries a SCIP.md file, which suggests the author has looked at this ground. The difference in approach is where the work happens and what it assumes. SCIP is a language-agnostic index format produced by per-language indexers and consumed by a code host; it is built for organisation-wide navigation across many repositories, and it expects infrastructure to store and serve those indexes. jCodeMunch MCP is a single local server that parses with tree-sitter, keeps its index on disk, and speaks MCP to whatever client is in front of it. Tree-sitter grammars are broader and cheaper to adopt than a full SCIP indexer per language, but tree-sitter parsing is syntactic: it does not resolve types or cross-file references the way a compiler-backed indexer can. If you need accurate go-to-definition across a monorepo and you already run Sourcegraph, SCIP is the stronger answer. If you need an agent to stop reading whole files, and you want that running locally in minutes, jCodeMunch MCP is the more direct fit.

Maintenance, releases and upgrade cost

The repository is not archived, and the last push was on 2026-09-09, so this is a project with current activity. Release cadence is unusually high: v1.108.315, v1.108.316 and v1.108.317 all landed between 2026-09-02 and 2026-09-04, and pyproject.toml already declares version 1.108.318. The patch numbers move in the hundreds, and the release notes read like a changelog of behavioural fixes rather than feature drops: one entry describes a display preference that edited the data it was displaying, another notes that a fix for a false positive can install a false negative. That cadence cuts both ways. Fixes arrive quickly, but pinning a version is the only way to keep behaviour stable, and the version string itself gives you little signal about whether a change touches parsing, storage or wire encoding. The pinned mcp ceiling is the upgrade cost that matters most: it is a deliberate hold, documented with a re-measurement date, and lifting it requires a code change in server.py. The README states a guarantee that if jCodeMunch does not pay for itself, you do not pay for it, but the terms behind that guarantee live in the commercial licensing material rather than in the README, so read them before relying on it.

Editorial conclusion

Adopt jCodeMunch MCP if your agent spends most of its context on file reads and you can accept a dual-use licence that is free for personal use only. Do not adopt it if you need an OSI-approved licence, if you run an MCP client built against the 2.x Python SDK, or if you only ever search a handful of small files. Before committing, run the index against one real repository and confirm two things: that tree-sitter has a grammar for your language, since the wheel downloads grammars into a user-level cache on first use, and that your client's MCP SDK version stays inside the mcp>=1.10.0,<2.0.0 pin recorded in pyproject.toml.

Frequently asked questions

Official sources

1. Issues
2. jgravelle/jcodemunch-mcp on GitHub
3. Project website
4. README
5. Releases