jDocMunch MCP

jDocMunch is an MCP server for coding agents that retrieves the exact documentation section a task needs, without loading whole files into the context window.

Index a documentation set once by heading hierarchy, then fetch a single section, a heading subtree, or a ranked search result — extracted byte-precisely from the original file.

Install · Quickstart · Benchmarks · Commercial licensing

Free for personal use. Commercial use requires a paid license — terms below.

Why jDocMunch?

The problem. An agent asked "how do I configure authentication?" opens a documentation file, skims hundreds of paragraphs it does not need, opens another, and repeats. Large context windows do not fix this. They just make the waste affordable enough to ignore until the bill arrives, and they crowd out the context the model actually needed.

The mechanism. jDocMunch parses a documentation set into a section tree keyed by heading hierarchy, stores each section's byte offsets into the original file, and exposes retrieval over MCP. Sections keep durable identities across re-indexing as long as path, heading text, and heading level are unchanged.

The outcome. The unit of access changes from file to section. An agent retrieves the installation section, one configuration block, or a specific heading subtree — and nothing else.

What makes it different

Section-first retrieval

Search and retrieve documentation by section, not just file path or keyword match.

Byte-precise extraction

Full content is pulled on demand from exact byte offsets into the original file.

Stable section IDs

Sections retain durable identities across re-indexing when path, heading text, and heading level remain unchanged.

Evidence

Four benchmarks against public documentation corpora, each with the corpus, date, and per-query results recorded in benchmarks/.

Read these as per-corpus results, not as a single headline multiple. Savings depend on how large the containing file is relative to the section you needed: a small file with one heading saves almost nothing, and the Kubernetes corpus saves a great deal. The benchmark files record the queries that did poorly alongside the ones that did well.

A separate, measured result from the v1.121.0 projection work, on this repository's own docs at max_results=10: a search row went 1,989 chars → 319 with compact=true (−84%), or 431 with snippet_bytes=200 (−78%) while removing the follow-up get_section call entirely.

Retrieval quality is gated, not assumed. Every release runs a replay fixture over a frozen golden set and fails below nDCG 0.95. That gate has failed builds and blocked releases; it is not decorative.

Install

Requirements: Python 3.10+, any MCP-compatible client.

uv tool install jdocmunch-mcp
jdocmunch-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 detects your MCP clients, writes their config entries, installs the doc-exploration prompt policy so your agent actually reaches for the tools, and optionally installs hooks and indexes your docs.

Verify:

jdocmunch-mcp --version

Manual Claude Code setup:

claude mcp add -s user jdocmunch -- uvx jdocmunch-mcp

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

Installing the server makes the tools available; it does not break an agent's habit of brute-reading files. One line in your CLAUDE.md does that:

Call the jdocmunch_guide tool and strictly follow its instructions.

Quickstart

Assumes: jDocMunch installed and registered with your client, and a folder of documentation.

Index a local documentation folder:

jdocmunch-mcp index-local --path ./docs

It prints JSON naming the corpus and what it found:

{
  "success": true,
  "repo": "local/docs",
  "file_count": 1,
  "section_count": 4,
  "doc_types": { ".md": 1 },
  "semantic_search": false
}

section_count greater than file_count is the whole point: the index addresses headings, not files.

Then, inside your agent:

Using jdocmunch, search the docs for "authentication configuration" and show me that section.

The agent should call search_sections, then get_section on the top hit — returning one section rather than a file. _meta.tokens_saved on the get_section response is a modeled saving: the containing document's size minus the section served (_meta.savings_basis: "modeled"). search_sections itself earns no credit.

Next step: get_toc_tree for a structural view of the whole corpus, or index_repo to index documentation straight from a GitHub repository.

Very large folders

An MCP client stops waiting on a tool call after a fixed time. Indexing a folder with tens of thousands of files can take longer than that. On one Windows machine, a full index of 10,000 files (271,585 sections) took 67 s without embeddings, and sentence-transformers embeddings added about 3 minutes.

If a folder is that large, or an index_local call times out, index it from a shell:

jdocmunch-mcp index-local --path /path/to/folder

The CLI runs the same indexing with no tool timeout. It writes to the same store as the MCP server, so the server uses the index once the command finishes. If you set DOC_INDEX_PATH in your client's MCP config, set it in the shell too.

• Custom names. If the folder was indexed under a custom name, pass the same --name. Without it, the CLI uses the folder name and writes a second index.
• The file cap. A folder is capped at 10,000 files, newest first. Raise it with --max-files N (the CLI form of the MCP tool's max_files). When a call hits the cap, its warning prints the command with the folder's discovered count.
• Narrowing a folder. Exclude what you don't need with --extra-ignore-pattern (repeatable, the CLI form of extra_ignore_patterns), or index only listed files with --paths-from FILE (the CLI form of paths).
• Embeddings. --no-embeddings builds a lexical index first. Run the command again later with --rebuild to add embeddings.

Scanned PDFs

A scanned PDF is a picture of text, with no text layer to index. The optional [ocr] extra reads them with an OCR engine already on your machine. jDocMunch never installs or downloads an engine, a language pack or a model.

pip install "jdocmunch-mcp[ocr]"

Engines. jDocMunch looks for one in this order and uses the first that answers:

1. JDOCMUNCH_TESSERACT_PATH, if you set it.
2. tesseract on PATH.
3. Tesseract's default install folders: C:\Program Files\Tesseract-OCR, the per-user folder under %LOCALAPPDATA%\Programs, /opt/homebrew/bin, /usr/local/bin and /usr/bin.
4. On Windows, the built-in Windows OCR, if an English OCR language is installed (it is on English-language Windows).

JDOCMUNCH_OCR_ENGINE=tesseract or windows picks one. JDOCMUNCH_OCR_LANG passes Tesseract languages that are already installed (default eng).

OCR needs two keys. It runs only when both are set:

• You set JDOCMUNCH_OCR=1 in your MCP client's env block (or your shell, for the CLI).
• The call asks for it: index_local(ocr=true), or index-local --ocr on the CLI.

So an agent can't turn OCR on by itself. The choice is stored with the index, and later refreshes and the watcher reuse it; ocr=false or --no-ocr turns it off. Every respon