jDocMunch-MCP

jDocMunch-MCP permite que los agentes de IA naveguen por la documentación por secciones en lugar de leer archivos por fuerza bruta.

GitHub
202
Prueba este MCPPatrocinado

Documentación

jDocMunch MCP

jDocMunch es un servidor MCP para agentes de codificación que recupera la sección exacta de documentación que una tarea necesita, sin cargar archivos completos en la ventana de contexto.

Indexa un conjunto de documentación una vez por jerarquía de encabezados y luego obtén una sola sección, un subárbol de encabezados o un resultado de búsqueda clasificado, extraído con precisión de bytes del archivo original.

Instalar · Inicio rápido · Benchmarks · Licencias comerciales

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

Gratis para uso personal. El uso comercial requiere una licencia de pago: términos a continuación.

¿Por qué jDocMunch?

El problema. Un agente al que se le pide «¿cómo configuro la autenticación?» abre un archivo de documentación, hojea cientos de párrafos que no necesita, abre otro y repite. Las ventanas de contexto grandes no solucionan esto. Solo hacen que el desperdicio sea lo bastante barato como para ignorarlo hasta que llega la factura, y desplazan el contexto que el modelo realmente necesitaba.

El mecanismo. jDocMunch analiza un conjunto de documentación y lo convierte en un árbol de secciones organizado por jerarquía de encabezados, almacena los desplazamientos de bytes de cada sección dentro del archivo original y expone la recuperación a través de MCP. Las secciones conservan identidades estables entre reindexaciones siempre que la ruta, el texto del encabezado y el nivel del encabezado no cambien.

El resultado. La unidad de acceso cambia de archivo a sección. Un agente recupera la sección de instalación, un bloque de configuración o un subárbol de encabezados específico, y nada más.

Qué lo hace diferente

Recuperación centrada en secciones

Busca y recupera documentación por sección, no solo por ruta de archivo o coincidencia de palabras clave.

Extracción con precisión de bytes

El contenido completo se obtiene bajo demanda desde los desplazamientos de bytes exactos dentro del archivo original.

IDs de sección estables

Las secciones conservan identidades estables entre reindexaciones cuando la ruta, el texto del encabezado y el nivel del encabezado permanecen sin cambios.

Evidencia

Cuatro benchmarks sobre corpus de documentación públicos, cada uno con el corpus, la fecha y los resultados por consulta registrados en benchmarks/.

CorpusEscalaIndexado enResultado
Kubernetes (kubernetes/website, 2026-03-04)1.569 archivos .md, 4.355 secciones, 16 MB3.352 ms27.285 tokens ahorrados en una sola consulta de afinidad de nodo; latencia de 100 ms
SciPy10.402 secciones, ~855.000 tokens de corpus2.247 ms135–152 ms por consulta en búsquedas de solvers dispersos, FFT y optimización
LangChain (MDX)5.973 secciones5.204 msEl seccionado compatible con MDX encontró un 754 % más de secciones que el paso ingenuo
WikiCorpus de 7.449 tokens—La búsqueda devuelve metadatos clasificados en ~190 tokens frente a una lectura completa del corpus de 7.449 tokens

Léelos como resultados por corpus, no como un único múltiplo destacado. Los ahorros dependen de cuán grande sea el archivo contenedor en relación con la sección que necesitabas: un archivo pequeño con un solo encabezado ahorra casi nada, y el corpus de Kubernetes ahorra muchísimo. Los archivos de benchmark registran las consultas que funcionaron mal junto con las que funcionaron bien.

Un resultado adicional y medido del trabajo de proyección v1.121.0, sobre la documentación de este propio repositorio en max_results=10: una fila de búsqueda pasó de 1.989 caracteres → 319 con compact=true (−84 %), o 431 con snippet_bytes=200 (−78 %) mientras se eliminaba por completo la llamada de seguimiento a get_section.

La calidad de recuperación está garantizada, no se asume. Cada versión ejecuta un fixture de reproducción sobre un conjunto dorado congelado y falla por debajo de nDCG 0,95. Esa compuerta ha hecho fallar builds y ha bloqueado versiones; no es decorativa.

Instalación

Requisitos: Python 3.10+, cualquier cliente compatible con MCP.

pip install jdocmunch-mcp
jdocmunch-mcp init

init detecta tus clientes MCP, escribe sus entradas de configuración, instala la política de indicaciones de exploración de documentación para que tu agente realmente use las herramientas y, opcionalmente, instala hooks e indexa tus documentos.

Ubuntu 24.04+ / Debian 12+: el Python del sistema está gestionado externamente (PEP 668). Usa pipx install jdocmunch-mcp o uv tool install jdocmunch-mcp.

Verifica:

jdocmunch-mcp --version

Configuración manual de Claude Code:

pip install jdocmunch-mcp
claude mcp add -s user jdocmunch jdocmunch-mcp

Instalar el servidor hace que las herramientas estén disponibles; no rompe el hábito del agente de leer archivos completos. Una línea en tu CLAUDE.md hace eso:

Call the jdocmunch_guide tool and strictly follow its instructions.

Inicio rápido

Supone: jDocMunch instalado y registrado con tu cliente, y una carpeta de documentación.

Indexa una carpeta de documentación local:

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

Imprime JSON con el nombre del corpus y lo que encontró:

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

section_count mayor que file_count es el punto clave: el índice apunta a encabezados, no a archivos.

Luego, dentro de tu agente:

Usando jdocmunch, busca en los documentos «configuración de autenticación» y muéstrame esa sección.

El agente debería llamar a search_sections y luego a get_section sobre el primer resultado, devolviendo una sección en lugar de un archivo. _meta.tokens_saved en la respuesta informa cuánto costó en comparación con leer el documento completo.

Siguiente paso: get_toc_tree para una vista estructural de todo el corpus, o index_repo para indexar documentación directamente desde un repositorio de GitHub.

Lo que puedes hacer

  • Recupera una sección en lugar de un documento. get_section y get_sections extraen contenido con precisión de bytes del archivo original; get_section_excerpt reduce aún más.
  • Busca por significado, no solo por palabras clave. search_sections fusiona BM25 con similitud coseno semántica cuando hay un proveedor de embeddings configurado. compact=true, fields=[...] y snippet_bytes=N recortan aún más la respuesta.
  • Navega por la estructura. get_toc, get_toc_tree, get_section_path, get_section_descendants y section_neighbors recorren el árbol de encabezados sin leer contenido.
  • Encuentra qué documentación falta o está obsoleta. get_doc_coverage, get_undocumented_symbols, get_stale_pages, get_orphan_sections, get_broken_links y doc_health_radar.
  • Trabaja con especificaciones de API. find_endpoint, list_endpoints_by_tag, find_operations_using_schema y get_schema_graph tratan los documentos OpenAPI como ciudadanos de primera clase.
  • Verifica los cambios de documentación antes de aplicarlos. check_section_delete_safe y get_section_blast_radius antes de eliminar o reestructurar.
  • Sabe cuándo una respuesta está desactualizada. Las lecturas de contenido revelan _meta.freshness, _meta.verdict y qué capa de origen respondió.

64 herramientas en total. La referencia completa está en USER_GUIDE.md.

Cómo funciona

Todo se ejecuta localmente. Los índices viven en tu directorio de inicio; no se requiere ningún servicio alojado para indexar o recuperar.

docs/ ──► parser (per format) ──► section tree ──► local index
                                                      │
                          MCP client ◄── retrieval ◄──┘
  • Análisis es por formato, un módulo para cada uno: Markdown/MDX, reStructuredText, AsciiDoc, cuadernos Jupyter, HTML, texto plano, OpenAPI (YAML), JSON/JSONC, XML/SVG/XHTML, escenas de Godot y, mediante el extra opcional [office], PDF, DOCX, PPTX y EPUB.
  • Almacenamiento es un índice local versionado (INDEX_VERSION = 3) que se auto-migra en la primera carga. Una versión 1.x nunca fuerza una reindexación.
  • Recuperación es léxica con BM25 por defecto, híbrida cuando hay embeddings disponibles.
  • Los embeddings son opcionales e independientes del proveedor — Gemini, OpenAI, un endpoint compatible con OpenAI o sentence-transformers locales. Sin uno, la búsqueda sigue siendo léxica y completamente offline.

Más detalle: ARCHITECTURE.md y SPEC.md.

Seguridad y privacidad

Local-first por diseño. Tu documentación se analiza y almacena en tu máquina, y el único comportamiento de red por defecto del paquete base es un contador de ahorro anónimo: un ID aleatorio más recuentos agregados de tokens, sin contenido, sin rutas, sin PII.

Desactívalo por completo:

JDOCMUNCH_SHARE_SAVINGS=0

Los proveedores de embeddings y resúmenes llaman a su API configurada solo cuando los habilitas, y nunca por defecto. watch-install registra un servicio de inicio de sesión solo cuando lo ejecutas tú mismo.

Comportamiento en segundo plano, totalmente divulgado

Un proceso hijo, cuando se usan embeddings locales. Cuando el proveedor sentence-transformers está activo, jDocMunch ejecuta el modelo de embeddings en un proceso hijo (python -m jdocmunch_mcp.embeddings.worker) en lugar de dentro del servidor. Este:

  • se inicia cuando algo necesita un embedding por primera vez: al arrancar si el modelo ya está en tu caché local de HuggingFace, o si no, en la primera búsqueda o indexación que lo use. Una instalación solo léxica nunca lo genera;
  • no abre ninguna conexión de red y solo se comunica con su padre, a través de una tubería privada;
  • se cierra cuando el servidor se cierra y se elimina si deja de responder;
  • no es un servicio de inicio de sesión, no está registrado en ningún lugar y no sobrevive a nada.

Esto existe porque importar la pila de embeddings dentro del proceso del servidor puede causar un interbloqueo en el cargador de Windows (#118), colgando cada llamada de herramienta mientras el servidor esté en ejecución. Desactívalo con JDOCMUNCH_EMBED_WORKER=0, que restaura la importación previa dentro del proceso.

La prevención de traversal de rutas, la protección contra escapes de symlinks, la exclusión de secretos, los límites de tamaño de archivo, la detección de binarios y la seguridad de codificación están documentados en SECURITY.md, junto con cómo reportar una vulnerabilidad.

Limitaciones

  • La recuperación por sección ayuda menos en archivos pequeños. Si un documento tiene un encabezado y 40 líneas, recuperar la sección y leer el archivo cuestan casi lo mismo.
  • La búsqueda semántica requiere un proveedor de embeddings. Sin uno, la búsqueda es solo léxica: buena para identificadores y frases exactas, más débil para preguntas parafraseadas.
  • Los formatos de Office necesitan el extra opcional [office] y solo se admiten para indexación local.
  • La frescura se divulga, no se garantiza. Una sección cuya fuente no se puede verificar se reporta como unknown en lugar de asumirse como actual.
  • jDocMunch no analiza código. Los símbolos, las firmas y los grafos de llamadas pertenecen a jcodemunch-mcp; los datos tabulares pertenecen a jdatamunch-mcp.

Documentación

DocumentoQué cubre
USER_GUIDE.mdReferencia completa de herramientas, flujos de trabajo y mejores prácticas
ARCHITECTURE.mdModelo de almacenamiento, pipeline de análisis, puntos de extensión
SPEC.mdContratos de respuesta y vocabulario de códigos de motivo
SECURITY.mdControles de seguridad y reporte de vulnerabilidades
TOKEN_SAVINGS.mdCómo se cuentan y reportan los ahorros
CONTRIBUTING.mdConfiguración de desarrollo y requisito de CLA
CHANGELOG.md · ROADMAP.mdHistorial de versiones y próximos pasos

Licencias y uso comercial

Publicado bajo la Licencia de doble uso jDocMunch-MCP (términos completos). Gratis para uso no comercial. El uso comercial requiere una licencia de pago, de pago único, vendida por jMunch LLC.

Solo jDocMunch: Builder, $29 (1 desarrollador) · Studio, $99 (hasta 5) · Platform, $499 (implementación interna a nivel de organización)

Suite completa de jMunch (código + docs + datos): Trio Builder, $99 · Trio Studio, $449 · Trio Platform, $2.499

Los desarrolladores individuales y los proyectos no comerciales no necesitan licencia. Las organizaciones que implementan jDocMunch en equipos internos sí.

Compromiso de compatibilidad 1.x

Cada licencia 1.x te da derecho a todas las versiones 1.x futuras. Nunca lanzaremos una versión 1.x que:

  • elimine o renombre una herramienta MCP (los nombres de herramientas obsoletos conservan sus alias),
  • elimine un campo Section de la forma de respuesta,
  • fuerce una reindexación sin auto-migrar tu índice existente en la primera carga,
  • cambie el formato de cable JSON de cualquier respuesta de herramienta de una manera que rompa a un consumidor existente,
  • o haga que un comportamiento previamente predeterminado genere un error. Cualquier cosa que requiera romper estas promesas está reservada para una futura versión principal (2.x). El contrato completo verificado por máquina se aplica mediante tests/test_server.py (invariantes de nombre de herramienta y campos obligatorios) y la compuerta de fixtures de reproducción que se ejecuta en cada lanzamiento.

Soporte y estado del proyecto

Mantenido activamente. Problemas e informes de errores: GitHub Issues. Informes de seguridad: consulte SECURITY.md. Las consultas sobre licencias comerciales se realizan a través de jcodemunch.com.

Parte de la suite jMunch junto con jcodemunch-mcp (símbolos de código) y jdatamunch-mcp (datos tabulares). Los tres implementan jMRI, la especificación de interfaz de recuperación abierta.