DocGraph

Broker de contexto markdown nativo del repositorio — una herramienta MCP que proporciona a los agentes de codificación documentación relevante para la tarea, en lugar de volcar docs/**.

Apúntalo a un repositorio, y Claude Code (o cualquier cliente MCP) obtiene una única herramienta, docgraph_context(task, max_tokens), que convierte una descripción de tarea en un paquete markdown rankeado y ajustado a un presupuesto de tokens, extraído de la documentación del propio repositorio — en lugar de leer archivos completos sin criterio esperando que la parte relevante esté ahí.

Por qué

Las ventanas de contexto de los agentes son finitas y los árboles de documentación no están curados para la recuperación. "Leer docs/**" o bien agota el presupuesto en un repositorio grande, o silenciosamente omite archivos fuera de docs/. DocGraph indexa lo que realmente es documentación (habilidades, READMEs de subproyectos en monorepo, archivos sueltos en la raíz — no solo docs/), divide archivos extensos tipo catálogo en sus secciones reales, y devuelve solo lo que una tarea específica necesita.

Sin embeddings, sin llamadas LLM en la ruta de recuperación. Determinista e inspeccionable — siempre puedes ver por qué un documento llegó al paquete.

Related MCP server: search-docs

Cómo funciona

repo markdown
     │
     ▼
discover.py    4-bucket rule: root files, docs/, skills/, monorepo
     │         subproject READMEs (all-caps filename, one level deep)
     ▼
index.py       SQLite + FTS5 (porter stemming), recursive H2→H4 chunking
     │         for long catalog docs, content-hash dedup, size-capped
     │         co-location edges between files in the same directory
     ▼
db/docgraph.db
     │
     ▼
context.py     task → AND-first/OR-fallback FTS query → co-location
     │         neighbor expansion (score-floored) → token-budget trim
     ▼
mcp_server.py  wraps it as one MCP tool, stdio transport

Instalación

pip install -e .

Uso

# Build the index for a repo
python -m docgraph.index /path/to/repo db/my-repo.db

# Generate a context pack directly (useful for testing before wiring into an agent)
python -m docgraph.context /path/to/repo db/my-repo.db "task description" --max-tokens 8000

# Run as an MCP server (stdio) — point your MCP client's config at this
python -m docgraph.mcp_server /path/to/repo db/my-repo.db

# Simple graph visualization (file-level nodes, co-location edges)
python -m docgraph.visualize db/my-repo.db graphs/my-repo_graph.html --title "my-repo"

Las cadenas de tarea se usan como búsqueda por palabras clave, no búsqueda semántica — sé específico y evita nombrar un archivo que estás a punto de crear (no puede coincidir con algo que aún no existe).

Registro con Claude Code

claude mcp add my-repo-docs -s user -e PYTHONIOENCODING=utf-8 -- \
  python -m docgraph.mcp_server /path/to/repo /full/path/to/db/my-repo.db

Una instancia de servidor = un repositorio + un índice. Para múltiples repositorios, registra múltiples servidores con nombres distintos y archivos .db separados.

Regla de descubrimiento

• raíz — archivos .md sueltos directamente en la raíz del repositorio

• docs — cualquier cosa bajo un directorio llamado docs, a cualquier profundidad

• skills — igual, para un directorio llamado skills (captura .claude/skills/ y .agents/skills/)

• subdir-mayusculas — archivos exactamente un nivel bajo la raíz, en otro subdirectorio, cuyo nombre de archivo (sin extensión) está en MAYÚSCULAS (README, TODO, ARCHITECTURE...) — cubre metadocumentos de subproyectos de monorepo

Cualquier cubo puede excluirse por ejecución con --exclude-bucket.

Notas de diseño

• FTS5 con stemming de Porter, sin embeddings. Determinista, barato y suficientemente bueno — los enlaces explícitos entre documentos dieron consistentemente cerca de cero en todos los repositorios reales contra los que se construyó.

• Aristas de co-ubicación, no enlaces explícitos. Los archivos en el mismo directorio obtienen una arista débil de "relacionado", ya que esa es la señal que realmente está presente. Limitado a 10 archivos por directorio — más allá, "misma carpeta" deja de ser una relación significativa y se vuelve ruido.

• Fragmentación recursiva, no de profundidad fija. Documentos largos se dividen en H2; cualquier sección que aún sea demasiado grande con subestructura real se divide de nuevo en H3, luego H4. Algunos repositorios tienen catálogos planos de secciones H2, otros tienen un H2 comodín que oculta la estructura real en H3 — la profundidad fija es incorrecta para uno u otro.

• Consultas AND-primero, OR-respaldo. Primero intenta que todas las palabras de la consulta coincidan; solo se amplía a OR si eso no encuentra nada. Una coincidencia precisa única es mejor evidencia que varias ruidosas.

• Deduplicación por hash de contenido en tiempo de indexación. Los archivos duplicados (p.ej., una habilidad copiada bajo .claude/ y .agents/) se indexan una vez, no dos.

Estado

MVP, validado contra tres repositorios reales de diferentes formas (corpora de 10, 8 y 72 archivos) y en uso activo mediante Claude Code. No construido: embeddings, modo de vigilancia, una interfaz de grafo real más allá del POC de visualización, búsqueda entre repositorios.

Licencia

Proyecto personal, sin licencia especificada.