doctree-mcp

Búsqueda BM25 + navegación por árbol sobre documentos markdown para agentes de IA. Sin embeddings, sin llamadas a LLM en el momento de la indexación.

GitHub
1
Prueba este MCPPatrocinado

Documentación

doctree-mcp

Recuperación documental agéntica sobre markdown, CSV y JSONL. BM25 + navegación por árbol vía MCP — sin base de datos vectorial, sin embeddings, sin llamadas a LLM en tiempo de indexación.

La propuesta: MCP proporciona los primitivos estructurales (un árbol navegable, BM25, glosario, búsqueda por fila). Las skills incluidas proporcionan el conocimiento procedimental (cómo recorrer ese árbol). Juntos, el agente se comporta como un bibliotecario de investigación entrenado — no como un buscador de un solo disparo. Ver El patrón Skill + MCP.

Inicio rápido

¿Ya tienes documentación? Apunta un cliente hacia ella:

# In your AI tool's MCP config — see docs/CLIENTS.md for per-tool snippets
{ "mcpServers": { "doctree": {
    "command": "bunx", "args": ["doctree-mcp"],
    "env": { "DOCS_ROOT": "./docs", "WIKI_WRITE": "1" }
} } }

Reinicia la herramienta → pregunta "busca en los docs X" o invoca el prompt doc-read.

¿Empiezas desde cero? Genera una wiki LLM estilo Karpathy LLM wiki:

bunx doctree-mcp init          # configure current tool
bunx doctree-mcp init --all    # configure every supported client
bunx doctree-mcp init --dry-run

Crea docs/wiki/ (mantenida por LLM) + docs/raw-sources/ (tus entradas), escribe la configuración de MCP, instala un hook de lint post-escritura, añade las convenciones de la wiki a CLAUDE.md / AGENTS.md / .cursor/rules/.

Modos de operación

ModoCuándo usarloGuía
stdio (predeterminado)Desarrollo local, agente en tu máquinaConfiguración del cliente
HTTP (Streamable HTTP)Equipos, CI, agentes alojadosDespliegue — Railway · Fly · Render · Cloudflare Containers · Docker
CLIinit, lint, debug-indexModos de operación

Árbol de decisión completo: Modos de operación.

Cómo funciona — Recupera · Cura · Añade

Agent: "How does token refresh work?"

→ search_documents("token refresh")
  #1  auth/middleware.md § Token Refresh Flow       score: 12.4
  #2  auth/oauth.md       § Refresh Token Lifecycle  score: 8.7

→ get_tree("docs:auth:middleware")
  [n1] # Auth Middleware
    [n4] ## Token Refresh Flow
      [n5] ### Automatic Refresh

→ navigate_tree("docs:auth:middleware", "n4")   ← n4 + descendants

Herramientas de lectura principales (siempre activas):

HerramientaPropósito
search_documentsBúsqueda por palabras clave BM25 + filtros por faceta + expansión de glosario (markdown · CSV · JSONL)
get_treeTabla de contenidos — encabezados, recuentos de palabras, resúmenes
get_node_contentTexto completo de una sección específica por ID de nodo
navigate_treeUna sección más todos sus descendientes en una sola llamada
lookup_rowBúsqueda O(1) por clave exacta para filas de datos estructurados (p. ej. PROJ-44)

Herramientas de escritura de wiki (opt-in con WIKI_WRITE=1):

HerramientaPropósito
find_similarDetección de duplicados con ratios de solapamiento
draft_wiki_entryScaffold: ruta sugerida, frontmatter inferido, coincidencias de glosario
write_wiki_entryEscritura validada: contención de ruta, esquema, protecciones contra duplicados, dry-run

Seguridad: contención de ruta · validación de frontmatter · detección de duplicados · dry-run · protección contra sobrescritura.

Alias obsoletos (list_documents, find_files, find_symbol) quedan superados por search_documents — siguen funcionando, pero ya no se recomiendan.

El patrón Skill + MCP

La mayoría de las herramientas de recuperación le dan al agente un cuadro de búsqueda y esperan lo mejor. doctree-mcp le entrega un árbol, y las skills incluidas le enseñan a recorrerlo.

  • MCP = primitivos estructurales. search_documents, get_tree, navigate_tree, get_node_content, lookup_row devuelven posiciones del árbol sobre las que el agente razona — no respuestas terminadas.
  • Skills = conocimiento procedimental. /doc-read, /doc-write, /doc-lint codifican el drill-down por migas de pan: buscar → esquema → navegar → recuperar. El agente aprende la política, no solo la API.

Esa combinación no existe limpiamente en otros lugares:

EnfoquePrimitivoLa skill enseñaCarencia
RAG híbrido gestionado (Cloudflare AI Search, Nia)Chunks planos + similitud—Puntuación de caja negra, sin rastro de auditoría
Herramienta-devuelve-respuesta (Context7)2 herramientas que devuelven respuestasForma de la consultaEl agente no puede razonar sobre contenido omitido
Skill-sobre-CLI (QMD)CLI sobre búsqueda planaExpansión de consultaNo hay árbol que navegar
doctree-mcp + /doc-readÁrbol navegableMigas de pan, enrutamiento multi-instancia, compilación de wiki—

Por qué gana la recuperación iterativa:

  • Podredumbre de contexto. Llenar una ventana de 1M de tokens con chunks degrada la salida. La navegación por migas de pan mantiene la memoria de trabajo pequeña.
  • Auditabilidad. search_documents → get_tree → navigate_tree → get_node_content es un rastro reproducible. Una puntuación de coseno no lo es. Los dominios regulados pueden publicar lo primero.
  • Divulgación progresiva. Menos primitivos navegables superan a la proliferación de herramientas (cf. Cloudflare Code Mode).

Multi-instancia = federación del lado del cliente. Registra varios servidores doctree con nombres distintos; la skill /doc-read codifica la política de enrutamiento. Añade o elimina instancias sin tocar la skill. Ver Configuración del cliente → Enrutamiento multi-instancia.

El patrón LLM Wiki

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Raw Sources    │     │  The Wiki        │     │  The Schema     │
│  (immutable)    │ ──→ │  (LLM-maintained)│ ←── │  (you define)   │
│  notes · logs   │     │  runbooks · refs │     │  CLAUDE.md rules │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Inspirado en LLM Wiki de Karpathy. Recorrido completo: docs/LLM-WIKI-GUIDE.md.

Configuración (resumen)

---
title: "Descriptive Title"
description: "One-line summary — boosts ranking"
tags: [relevant, terms]
type: runbook          # runbook | guide | reference | tutorial | architecture | adr
category: auth
---

Todos los campos de frontmatter no reservados se convierten en facetas de filtro:

search_documents("auth", filters: { type: "runbook", tags: ["production"] })

Variables de entorno comunes:

VariablePredeterminadoDescripción
DOCS_ROOT./docsCarpeta de docs
DOCS_GLOB**/*.mdGlobs separados por comas (**/*.md,**/*.csv,**/*.jsonl)
DOCS_ROOTS—Multi-colección ponderada (./wiki:1.0,./rfcs:0.5)
PORT3100Puerto del modo HTTP
WIKI_WRITE(sin definir)1 habilita las herramientas de escritura
GLOSSARY_PATH$DOCS_ROOT/glossary.jsonGlosario de expansión de consultas

Referencia completa: docs/CONFIGURATION.md.

Glosario — coloca glossary.json en la raíz de los docs para expansión bidireccional de consultas:

{ "CLI": ["command line interface"], "K8s": ["kubernetes"] }

Las definiciones de acrónimos como "TLS (Transport Layer Security)" también se extraen automáticamente.

Datos estructurados — los archivos CSV/JSONL se convierten en documentos donde cada fila es un nodo del árbol. Los roles de columna (id, title, description, facets, URL) se detectan automáticamente a partir de los encabezados. Ver docs/STRUCTURED-DATA.md.

Ejecución desde el código fuente

git clone https://github.com/joesaby/doctree-mcp.git
cd doctree-mcp && bun install

DOCS_ROOT=./docs bun run serve          # stdio
DOCS_ROOT=./docs bun run serve:http     # HTTP (port 3100)
DOCS_ROOT=./docs bun run index          # CLI: inspect indexed output
bun test

Rendimiento

OperaciónTiempoCoste de tokens
Índice completo (900 docs)2–5s0
Re-indexación incremental~50ms0
Búsqueda5–30ms~300–1K tokens
Esquema del árbol<1ms~200–800 tokens

Documentación

Configuración y operación

Patrones y conceptos

Código fuente

Sobre hombros de gigantes

Licencia

MIT