jDocMunch-MCP

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 fromfiletosection. An agent retrieves the installation section, one configuration block, or a specific heading subtree — and nothing else.

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

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

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

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.

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

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

uv tool install jdocmunch-mcp jdocmunch-mcp init

initdetects 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.

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

No install step —uvxfetches and runs the server on demand. Prefer it on your PATH (and required for hooks)?uv tool install jdocmunch-mcp, thenclaude 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 yourCLAUDE.mddoes that:

Call the jdocmunch_guide tool and strictly follow its instructions.

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

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_countgreater thanfile_countis the whole point: the index addresses headings, not files.

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

The agent should callsearch_sections, thenget_sectionon the top hit — returning one section rather than a file._meta.tokens_savedon the response reports what that cost versus reading the containing document.

Next step:get_toc_treefor a structural view of the whole corpus, orindex_repoto index documentation straight from a GitHub repository.

Everything runs locally. Indexes live under your home directory; no hosted service is required for indexing or retrieval.

docs/ ──► parser (per format) ──► section tree ──► local index │ MCP client ◄── retrieval ◄──┘