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

203

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, 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 · Licencia comercial

Gratis para uso personal. El uso comercial requiere una licencia de pago — términos abajo.

¿Por qué jDocMunch?

El problema. Un agente que pregunta "¿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 asequible 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 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 mantienen identidades duraderas a través de re-indexaciones 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 precisa de bytes

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

IDs de sección estables

Las secciones conservan identidades duraderas a través de re-indexaciones cuando la ruta, el texto del encabezado y el nivel del encabezado permanecen sin cambios.

Evidencia

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

Corpus	Escala	Indexado en	Resultado
Kubernetes (`kubernetes/website`, 2026-03-04)	1,569 `.md` archivos, 4,355 secciones, 16 MB	3,352 ms	27,285 tokens ahorrados en una sola consulta de afinidad de nodo; 100 ms de latencia
SciPy	10,402 secciones, ~855,000 tokens del corpus	2,247 ms	135–152 ms por consulta en búsquedas de solvers dispersos, FFT y optimización
LangChain (MDX)	5,973 secciones	5,204 ms	El seccionado consciente de MDX encontró un 754% más de secciones que el pase ingenuo
Wiki	Corpus 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 es el archivo contenedor en relación con la sección que necesitabas: un archivo pequeño con un 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 separado y medido del trabajo de proyección v1.121.0, sobre la documentación propia de este 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 eliminaba por completo la llamada de seguimiento get_section.

La calidad de recuperación está garantizada, no asumida. 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 bloqueado versiones; no es decorativa.

Instalación

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

uv tool install jdocmunch-mcp
jdocmunch-mcp init

Sin virtualenv que gestionar, nada escrito en el Python del sistema, y funciona tal cual en distribuciones PEP 668 (Ubuntu 24.04+, Debian 12+) donde se rechaza pip install sin más. ¿Aún no tienes uv?

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

Otras rutas de instalación

Comando	Úsalo cuando
`uvx jdocmunch-mcp`	Instalación cero. Se ejecuta desde un entorno efímero — nada queda en disco de forma permanente. Las entradas de cliente que escribe `init` ya invocan el servidor de esta manera, así que para la mayoría de configuraciones esto es todo lo que se ejecuta. ⚠ Los hooks son la excepción: se lanzan desde un subshell con PATH mínimo y resuelven el ejecutable por nombre, así que necesitan `uv tool install` (o `pipx`/`pip`) para funcionar.
`pipx install jdocmunch-mcp`	Ya estandarizas en pipx
`pip install jdocmunch-mcp`	Dentro de un virtualenv que gestionas tú mismo

Verifica:

jdocmunch-mcp --version

Configuración manual de Claude Code:

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

Sin paso de instalación — uvx obtiene y ejecuta el servidor bajo demanda. ¿Lo prefieres en tu PATH (y es necesario para los hooks)? uv tool install jdocmunch-mcp, luego claude mcp add -s user jdocmunch jdocmunch-mcp.

Instalar el servidor hace que las herramientas estén disponibles; no rompe el hábito de un agente de leer archivos por fuerza bruta. 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 nombrando el 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 aborda encabezados, no 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, luego get_section en el resultado principal — devolviendo una sección en lugar de un archivo. _meta.tokens_saved en la respuesta informa cuánto costó eso frente a leer el documento contenedor.

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

Recuperar 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.
Buscar 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.
Navegar la estructura. get_toc, get_toc_tree, get_section_path, get_section_descendants y section_neighbors recorren el árbol de encabezados sin leer contenido.
Encontrar documentación que falta o está obsoleta. get_doc_coverage, get_undocumented_symbols, get_stale_pages, get_orphan_sections, get_broken_links y doc_health_radar.
Trabajar 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.
Preverificar cambios de documentación. check_section_delete_safe y get_section_blast_radius antes de eliminar o reestructurar.
Saber 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 bajo 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 BM25 léxico por defecto, híbrido cuando hay embeddings disponibles.
Los embeddings son opcionales e independientes del proveedor — Gemini, OpenAI, un endpoint compatible con OpenAI, o un modelo local sin conexión mediante FastEmbed (ONNX) o sentence-transformers (torch). Sin uno, la búsqueda permanece léxica y completamente sin conexión.

Detalles más profundos: ARCHITECTURE.md y SPEC.md.

Seguridad y privacidad

Local-primero 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 conteos agregados de tokens, sin contenido, sin rutas, sin PII.

Exclúyete por completo:

JDOCMUNCH_SHARE_SAVINGS=0

Los proveedores de embeddings y resumidores 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

Una descarga de modelo, la primera vez que se ejecuta un proveedor de embeddings local. Ambos proveedores sin conexión obtienen su modelo de HuggingFace en el primer uso y lo almacenan en caché en disco. Nada se descarga hasta que habilitas embeddings, y una instalación solo-léxica nunca contacta el hub. El calentamiento de inicio se omite cuando el modelo no está ya en caché, así que una primera ejecución difiere la descarga a tu primera búsqueda en lugar de detener el apretón de manos de MCP detrás de ella (#110).

Una instalación de paquete y una descarga de modelo, solo si dices sí a init. jdocmunch-mcp init verifica si hay un proveedor de embeddings disponible. Si no lo hay, pregunta una vez si quieres activar la búsqueda semántica. La respuesta por defecto es no. Ante un sí hace dos cosas e imprime ambas antes de hacerlas:

ejecuta python -m pip install "fastembed>=0.8.0" en el entorno de Python donde se ejecuta jdocmunch (alrededor de 160 MB instalados; trae onnxruntime, no torch);
descarga un archivo de modelo, all-MiniLM-L6-v2 en formato ONNX, desde huggingface.co (87 MB, una vez).

Después de eso, los embeddings se ejecutan en tu máquina. Ningún texto de tus documentos se envía a ningún lugar. --yes no responde esta pregunta por ti: acepta ediciones de configuración, no una descarga. Una instalación por script opta con --with-embeddings. --dry-run imprime el comando y los tamaños y no toca nada. Si pip no es utilizable (una instalación uv tool o pipx no tiene ninguno) o la instalación falla, init imprime el comando manual para tu estilo de instalación y continúa con coincidencia de palabras. El propio servidor MCP nunca instala ni descarga nada sin que se le pida.

Por qué init pregunta en absoluto: en un benchmark público de 492 preguntas reales de usuarios sobre 6 conjuntos de documentación, la búsqueda semántica (híbrida) puso una respuesta directa en los 5 mejores resultados para el 47% de las preguntas, frente al 34% solo con coincidencia de palabras. Método, datos y el resultado negativo que vino con ello: jdoc-rerank-bench. Medido en una sola máquina solo-CPU, los embeddings agregaron alrededor de 7 segundos por cada 1,000 secciones a un primer índice. doc_list_repos informa has_embeddings por índice, para que puedas ver cuáles siguen siendo solo-palabras.

FastEmbed como proveedor sin conexión. pip install jdocmunch-mcp[fastembed] ejecuta el mismo modelo all-MiniLM-L6-v2 mediante onnxruntime en lugar de torch, que es una instalación mucho más pequeña. Cuando ambos proveedores sin conexión están presentes, se prefiere FastEmbed; JDOCMUNCH_EMBEDDING_PROVIDER=sentence-transformers selecciona el otro. En el modelo compartido ambos escriben el mismo almacén de vectores, así que cambiar de runtime no re-embediza tu corpus. Apunta FastEmbed a un modelo diferente con JDOCMUNCH_FASTEMBED_MODEL y mantiene sus propios vectores en su lugar, porque los vectores de dos modelos no son intercambiables (#126).

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 por primera vez un embedding — al arrancar si el modelo ya está en tu caché local de HuggingFace, de lo contrario en la primera búsqueda o indexación que lo use. Una instalación solo léxica nunca lo inicia;
no abre ninguna conexión de red y solo se comunica con su proceso 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ívelo con JDOCMUNCH_EMBED_WORKER=0, que restaura la importación previa dentro del proceso.

Un servicio de inicio de sesión, solo si instala uno. jdocmunch-mcp watch-install registra el vigilante de documentos para que se inicie al iniciar sesión (unidad de usuario de systemd, agente de launchd, o una tarea del Programador de tareas llamada jdocmunch-watch). Nada lo instala por usted. Una vez instalado:

reindexa cada repositorio de documentos indexado localmente cuando un archivo de documento cambia en disco;
se ejecuta exactamente jdocmunch-mcp watch con las banderas que pasó a watch-install — --no-ai-summaries para mantener el resumidor fuera, --quiet para suprimir sus líneas de registro por cambio;
escribe en watch.log y watch.err bajo su directorio de índice de documentos;
se elimina con jdocmunch-mcp watch-uninstall.

⚠ Volver a ejecutar watch-install reescribe la definición del servicio, por lo que una editada a mano se reemplaza. Ahora imprime lo que reemplazó; pase las banderas a watch-install mismo para que una actualización las conserve (#120).

La prevención de recorrido de rutas, la protección contra escapes de enlaces simbólicos, la exclusión de secretos, los límites de tamaño de archivo, la detección binaria y la seguridad de codificación están documentados en SECURITY.md, junto con cómo informar una vulnerabilidad.

Limitaciones

La recuperación de secciones 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 informa como unknown en lugar de asumirse actual.
jDocMunch no analiza código. Los símbolos, firmas y grafos de llamadas pertenecen a jcodemunch-mcp; los datos tabulares pertenecen a jdatamunch-mcp.

Documentación

Doc	Qué cubre
USER_GUIDE.md	Referencia completa de herramientas, flujos de trabajo y mejores prácticas
ARCHITECTURE.md	Modelo de almacenamiento, canalización de análisis, puntos de extensión
SPEC.md	Contratos de respuesta y vocabulario de códigos de razón
SECURITY.md	Controles de seguridad e informes de vulnerabilidades
TOKEN_SAVINGS.md	Cómo se cuentan e informan los ahorros
CONTRIBUTING.md	Configuración de desarrollo y requisito de CLA
CHANGELOG.md · ROADMAP.md	Historial de versiones y qué sigue

Licencias y uso comercial

Publicado bajo la Licencia de uso dual de 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 + documentos + 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 le da derecho a todas las versiones 1.x futuras. Nunca enviaremos 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 migrar automáticamente su í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 se reserva para una futura versión principal (2.x). El contrato completo verificado por máquina se aplica mediante tests/test_server.py (invariantes de nombres de herramientas y campos requeridos) y la puerta de accesorios de reproducción que se ejecuta en cada versión.

Soporte y estado del proyecto

Mantenido activamente. Problemas e informes de errores: GitHub Issues. Informes de seguridad: consulte SECURITY.md. Las preguntas de licencias comerciales se canalizan 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.