jDocMunch-MCP

jDocMunch-MCP permite que agentes de IA naveguem pela documentação por seção, em vez de ler arquivos por força bruta.

GitHub
203
Experimente este MCPPatrocinado

Documentação

jDocMunch MCP

jDocMunch é um servidor MCP para agentes de codificação que recupera a seção exata da documentação que uma tarefa precisa, sem carregar arquivos inteiros no contexto.

Indexe um conjunto de documentação uma vez pela hierarquia de títulos e, em seguida, busque uma única seção, uma subárvore de títulos ou um resultado de busca ranqueado — extraído com precisão de bytes do arquivo original.

Instalar · Início rápido · Benchmarks · Licenciamento comercial

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

Gratuito para uso pessoal. Uso comercial requer uma licença paga — termos abaixo.

Por que jDocMunch?

O problema. Um agente perguntou "como configuro a autenticação?" abre um arquivo de documentação, percorre centenas de parágrafos que não precisa, abre outro e repete. Janelas de contexto grandes não resolvem isso. Elas apenas tornam o desperdício acessível o suficiente para ignorar até a conta chegar, e elas ocupam o espaço que o modelo realmente precisava.

O mecanismo. jDocMunch analisa um conjunto de documentação em uma árvore de seções organizada pela hierarquia de títulos, armazena os offsets de bytes de cada seção no arquivo original e expõe a recuperação via MCP. As seções mantêm identidades duráveis entre reindexações, desde que o caminho, o texto do título e o nível do título permaneçam inalterados.

O resultado. A unidade de acesso muda de arquivo para seção. Um agente recupera a seção de instalação, um bloco de configuração ou uma subárvore de títulos específica — e nada mais.

O que o torna diferente

Recuperação por seção em primeiro lugar

Busque e recupere documentação por seção, não apenas por caminho de arquivo ou correspondência de palavras-chave.

Extração com precisão de bytes

O conteúdo completo é puxado sob demanda a partir de offsets de bytes exatos no arquivo original.

IDs de seção estáveis

As seções mantêm identidades duráveis entre reindexações quando o caminho, o texto do título e o nível do título permanecem inalterados.

Evidências

Quatro benchmarks contra corpora de documentação pública, cada um com o corpus, a data e os resultados por consulta registrados em benchmarks/.

CorpusEscalaIndexado emResultado
Kubernetes (kubernetes/website, 2026-03-04)1.569 arquivos .md, 4.355 seções, 16 MB3.352 ms27.285 tokens economizados em uma única consulta de afinidade de nó; latência de 100 ms
SciPy10.402 seções, ~855.000 tokens de corpus2.247 ms135–152 ms por consulta em buscas de solvers esparsos, FFT e otimização
LangChain (MDX)5.973 seções5.204 msA seccionamento ciente de MDX encontrou 754% mais seções do que a passagem ingênua
WikiCorpus de 7.449 tokens—A busca retorna metadados ranqueados em ~190 tokens contra uma leitura de corpus inteiro de 7.449 tokens

Leia estes como resultados por corpus, não como um único múltiplo de destaque. As economias dependem de quão grande é o arquivo contido em relação à seção que você precisava: um arquivo pequeno com um título economiza quase nada, e o corpus Kubernetes economiza muito. Os arquivos de benchmark registram as consultas que tiveram desempenho ruim junto com as que tiveram bom desempenho.

Um resultado separado e medido do trabalho de projeção v1.121.0, na documentação deste próprio repositório em max_results=10: uma linha de busca foi de 1.989 caracteres → 319 com compact=true (−84%), ou 431 com snippet_bytes=200 (−78%) enquanto removia completamente a chamada de acompanhamento get_section.

A qualidade da recuperação é garantida, não presumida. Cada versão executa um fixture de replay sobre um conjunto dourado congelado e falha abaixo de nDCG 0,95. Esse portão já falhou builds e bloqueou versões; não é decorativo.

Instalação

Requisitos: Python 3.10+, qualquer cliente compatível com MCP.

uv tool install jdocmunch-mcp
jdocmunch-mcp init

Sem virtualenv para gerenciar, nada escrito no Python do sistema, e funciona como está em distros PEP 668 (Ubuntu 24.04+, Debian 12+) onde pip install puro é recusado. Ainda não tem uv?

init detecta seus clientes MCP, escreve suas entradas de configuração, instala a política de prompt de exploração de documentação para que seu agente realmente alcance as ferramentas e, opcionalmente, instala hooks e indexa seus documentos.

Outros caminhos de instalação
ComandoUse quando
uvx jdocmunch-mcpInstalação zero. Executa a partir de um ambiente efêmero — nada é gravado permanentemente no disco. As entradas de cliente que init escreve já invocam o servidor dessa forma, então para a maioria das configurações isso é tudo o que é executado. ⚠ Hooks são a exceção: eles são gerados por um subshell com PATH mínimo e resolvem o executável pelo nome, então precisam de uv tool install (ou pipx/pip) para funcionar.
pipx install jdocmunch-mcpVocê já padroniza com pipx
pip install jdocmunch-mcpDentro de um virtualenv que você gerencia

Verifique:

jdocmunch-mcp --version

Configuração manual do Claude Code:

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

Sem etapa de instalação — uvx busca e executa o servidor sob demanda. Prefere no seu PATH (e necessário para hooks)? uv tool install jdocmunch-mcp, depois claude mcp add -s user jdocmunch jdocmunch-mcp.

Instalar o servidor torna as ferramentas disponíveis; não quebra o hábito de um agente de ler arquivos por completo. Uma linha no seu CLAUDE.md faz isso:

Call the jdocmunch_guide tool and strictly follow its instructions.

Início rápido

Pressupõe: jDocMunch instalado e registrado no seu cliente, e uma pasta de documentação.

Indexe uma pasta de documentação local:

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

Ele imprime JSON nomeando o corpus e o que encontrou:

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

section_count maior que file_count é o ponto principal: o índice endereça títulos, não arquivos.

Então, dentro do seu agente:

Usando jdocmunch, busque nos documentos por "configuração de autenticação" e mostre-me essa seção.

O agente deve chamar search_sections, depois get_section no resultado principal — retornando uma seção em vez de um arquivo. _meta.tokens_saved na resposta relata o custo em comparação com a leitura do documento contido.

Próximo passo: get_toc_tree para uma visão estrutural de todo o corpus, ou index_repo para indexar documentação diretamente de um repositório GitHub.

O que você pode fazer

  • Recupere uma seção em vez de um documento. get_section e get_sections puxam conteúdo com precisão de bytes do arquivo original; get_section_excerpt estreita ainda mais.
  • Busque por significado, não apenas por palavras-chave. search_sections combina BM25 com cosseno semântico quando um provedor de embeddings está configurado. compact=true, fields=[...] e snippet_bytes=N reduzem ainda mais a resposta.
  • Navegue pela estrutura. get_toc, get_toc_tree, get_section_path, get_section_descendants e section_neighbors percorrem a árvore de títulos sem ler conteúdo.
  • Descubra o que está faltando ou desatualizado na documentação. get_doc_coverage, get_undocumented_symbols, get_stale_pages, get_orphan_sections, get_broken_links e doc_health_radar.
  • Trabalhe com especificações de API. find_endpoint, list_endpoints_by_tag, find_operations_using_schema e get_schema_graph tratam documentos OpenAPI como cidadãos de primeira classe.
  • Valide mudanças na documentação. check_section_delete_safe e get_section_blast_radius antes de remover ou reestruturar.
  • Saiba quando uma resposta está desatualizada. Leituras de conteúdo divulgam _meta.freshness, _meta.verdict e qual camada de origem respondeu.

64 ferramentas no total. A referência completa está em USER_GUIDE.md.

Como funciona

Tudo roda localmente. Os índices ficam no seu diretório pessoal; nenhum serviço hospedado é necessário para indexação ou recuperação.

docs/ ──► parser (per format) ──► section tree ──► local index
                                                      │
                          MCP client ◄── retrieval ◄──┘
  • Análise é por formato, um módulo para cada: Markdown/MDX, reStructuredText, AsciiDoc, notebooks Jupyter, HTML, texto simples, OpenAPI (YAML), JSON/JSONC, XML/SVG/XHTML, cenas Godot e — via o extra opcional [office] — PDF, DOCX, PPTX e EPUB.
  • Armazenamento é um índice local versionado (INDEX_VERSION = 3) que migra automaticamente no primeiro carregamento. Uma versão 1.x nunca força uma reindexação.
  • Recuperação é lexical BM25 por padrão, híbrida quando embeddings estão disponíveis.
  • Embeddings são opcionais e independentes de provedor — Gemini, OpenAI, um endpoint compatível com OpenAI ou um modelo local offline via FastEmbed (ONNX) ou sentence-transformers (torch). Sem um, a busca permanece lexical e totalmente offline.

Detalhes mais profundos: ARCHITECTURE.md e SPEC.md.

Segurança e privacidade

Local-first por design. Sua documentação é analisada e armazenada na sua máquina, e o único comportamento de rede padrão do pacote base é um contador de economia anônimo — um ID aleatório mais contagens agregadas de tokens, sem conteúdo, sem caminhos, sem PII.

Desative completamente:

JDOCMUNCH_SHARE_SAVINGS=0

Provedores de embeddings e resumidores chamam sua API configurada apenas quando você os habilita, e nunca por padrão. watch-install registra um serviço de login apenas quando você mesmo o executa.

Comportamento em segundo plano, totalmente divulgado

Um download de modelo, na primeira vez que um provedor de embeddings local é executado. Ambos os provedores offline buscam seu modelo do HuggingFace no primeiro uso e o armazenam em cache no disco. Nada é baixado até que você habilite embeddings, e uma instalação apenas lexical nunca contata o hub. O aquecimento de inicialização é ignorado quando o modelo não está em cache, então uma primeira execução adia o download para sua primeira busca em vez de travar o handshake do MCP atrás dele (#110).

Uma instalação de pacote e um download de modelo, apenas se você disser sim ao init. jdocmunch-mcp init verifica se um provedor de embeddings está disponível. Se não estiver, ele pergunta uma vez se deseja ativar a busca semântica. A resposta padrão é não. Em um sim, ele faz duas coisas e imprime ambas antes de fazê-las:

  • executa python -m pip install "fastembed>=0.8.0" no ambiente Python em que o jdocmunch está rodando (cerca de 160 MB instalados; puxa onnxruntime, não torch);
  • baixa um arquivo de modelo, all-MiniLM-L6-v2 em formato ONNX, de huggingface.co (87 MB, uma vez).

Depois disso, os embeddings rodam na sua máquina. Nenhum texto dos seus documentos é enviado a lugar algum. --yes não responde essa pergunta por você: ele aceita edições de configuração, não um download. Uma instalação por script opta com --with-embeddings. --dry-run imprime o comando e os tamanhos e não toca em nada. Se o pip não for utilizável (uma instalação uv tool ou pipx não tem nenhum) ou a instalação falhar, init imprime o comando manual para seu estilo de instalação e continua com correspondência de palavras. O próprio servidor MCP nunca instala ou baixa nada sem ser solicitado.

Por que init pergunta: em um benchmark público de 492 perguntas reais de usuários em 6 conjuntos de documentação, a busca semântica (híbrida) colocou uma resposta direta nos 5 principais resultados para 47% das perguntas, contra 34% apenas para correspondência de palavras. Método, dados e o resultado negativo que veio junto: jdoc-rerank-bench. Medido em uma máquina apenas com CPU, os embeddings adicionaram cerca de 7 segundos por 1.000 seções a um primeiro índice. doc_list_repos relata has_embeddings por índice, para que você possa ver quais ainda são apenas palavras.

FastEmbed como provedor offline. pip install jdocmunch-mcp[fastembed] executa o mesmo modelo all-MiniLM-L6-v2 através do onnxruntime em vez de torch, que é uma instalação muito menor. Quando ambos os provedores offline estão presentes, o FastEmbed é preferido; JDOCMUNCH_EMBEDDING_PROVIDER=sentence-transformers seleciona o outro. No modelo compartilhado, os dois gravam o mesmo armazenamento de vetores, então alternar runtimes não re-embed seu corpus. Aponte o FastEmbed para um modelo diferente com JDOCMUNCH_FASTEMBED_MODEL e ele mantém seus próprios vetores, porque vetores de dois modelos não são intercambiáveis (#126).

Um processo filho, quando embeddings locais estão em uso. Quando o provedor sentence-transformers está ativo, o jDocMunch executa o modelo de embeddings em um processo filho (python -m jdocmunch_mcp.embeddings.worker) em vez de dentro do servidor. Ele:

  • inicia quando algo precisa de um embedding pela primeira vez — na inicialização, se o modelo já estiver no seu cache local do HuggingFace; caso contrário, na primeira busca ou indexação que o utilize. Uma instalação somente léxica nunca o inicia;
  • não abre nenhuma conexão de rede e fala apenas com seu processo pai, por um pipe privado;
  • encerra quando o servidor encerra e é morto se parar de responder;
  • não é um serviço de login, não é registrado em lugar nenhum e não sobrevive a nada.

Isso existe porque importar a pilha de embeddings dentro do processo do servidor pode causar deadlock no carregador do Windows (#118), travando todas as chamadas de ferramenta enquanto o servidor estiver em execução. Desative-o com JDOCMUNCH_EMBED_WORKER=0, que restaura a importação anterior no processo.

Um serviço de login, somente se você instalar um. jdocmunch-mcp watch-install registra o observador de documentos para iniciar no login (unidade de usuário do systemd, agente do launchd ou uma tarefa do Agendador de Tarefas chamada jdocmunch-watch). Nada o instala por você. Uma vez instalado, ele:

  • reindexa cada repositório de documentos indexado localmente quando um arquivo de documento no disco muda;
  • executa exatamente jdocmunch-mcp watch com as flags que você passou para watch-install — --no-ai-summaries para manter o resumidor fora dele, --quiet para suprimir suas linhas de log por alteração;
  • grava em watch.log e watch.err sob seu diretório de índice de documentos;
  • é removido por jdocmunch-mcp watch-uninstall.

⚠ Reexecutar watch-install reescreve a definição do serviço, portanto uma definição editada manualmente é substituída. Agora ele imprime o que substituiu; passe as flags para watch-install para que uma atualização as mantenha (#120).

Prevenção de travessia de caminho, proteção contra escape de symlink, exclusão de segredos, limites de tamanho de arquivo, detecção binária e segurança de codificação estão documentados em SECURITY.md, junto com como relatar uma vulnerabilidade.

Limitações

  • A recuperação de seções ajuda menos em arquivos pequenos. Se um documento tem um cabeçalho e 40 linhas, recuperar a seção e ler o arquivo custam quase o mesmo.
  • A busca semântica exige um provedor de embeddings. Sem um, a busca é somente léxica — boa para identificadores e frases exatas, mais fraca para perguntas parafraseadas.
  • Formatos do Office exigem o extra opcional [office] e são suportados apenas para indexação local.
  • A atualidade é divulgada, não garantida. Uma seção cuja fonte não pode ser verificada é relatada como unknown em vez de assumida como atual.
  • jDocMunch não analisa código. Símbolos, assinaturas e grafos de chamadas pertencem a jcodemunch-mcp; dados tabulares pertencem a jdatamunch-mcp.

Documentação

DocO que cobre
USER_GUIDE.mdReferência completa de ferramentas, fluxos de trabalho e melhores práticas
ARCHITECTURE.mdModelo de armazenamento, pipeline de análise e pontos de extensão
SPEC.mdContratos de resposta e vocabulário de códigos de motivo
SECURITY.mdControles de segurança e relato de vulnerabilidades
TOKEN_SAVINGS.mdComo as economias são contadas e relatadas
CONTRIBUTING.mdConfiguração de desenvolvimento e o requisito de CLA
CHANGELOG.md · ROADMAP.mdHistórico de versões e o que vem a seguir

Licenciamento e uso comercial

Publicado sob a Licença de Uso Duplo jDocMunch-MCP (termos completos). Gratuito para uso não comercial. O uso comercial exige uma licença paga, única, vendida pela jMunch LLC.

Somente jDocMunch: Builder, $29 (1 desenvolvedor) · Studio, $99 (até 5) · Platform, $499 (implantação interna em toda a organização)

Suíte completa jMunch (código + docs + dados): Trio Builder, $99 · Trio Studio, $449 · Trio Platform, $2.499

Desenvolvedores individuais e projetos não comerciais não precisam de licença. Organizações que implantam jDocMunch em equipes internas precisam.

Compromisso de compatibilidade 1.x

Toda licença 1.x dá direito a todas as versões 1.x futuras. Nunca lançaremos uma versão 1.x que:

  • remova ou renomeie uma ferramenta MCP (nomes de ferramentas obsoletos mantêm seus aliases),
  • remova um campo Section da forma da resposta,
  • force uma reindexação sem migrar automaticamente seu índice existente no primeiro carregamento,
  • altere o formato JSON na transmissão de qualquer resposta de ferramenta de forma que quebre um consumidor existente,
  • ou torne um comportamento anteriormente padrão um erro.

Qualquer coisa que exija quebrar essas promessas é reservada para uma futura versão principal (2.x). O contrato completo verificado por máquina é aplicado via tests/test_server.py (invariantes de nomes de ferramentas e campos obrigatórios) e o portão de fixtures de reprodução que roda em todo lançamento.

Suporte e status do projeto

Mantido ativamente. Problemas e relatos de bugs: GitHub Issues. Relatos de segurança: veja SECURITY.md. Perguntas sobre licenciamento comercial passam por jcodemunch.com.

Parte da suíte jMunch junto com jcodemunch-mcp (símbolos de código) e jdatamunch-mcp (dados tabulares). Todos os três implementam jMRI, a especificação de interface de recuperação aberta.