DocGraph

Reponativer Markdown-Kontext-Broker – ein MCP-Tool, das Codierungsagenten aufgabenrelevante Dokumente liefert, anstatt docs/** auszuschütten.

Richten Sie es auf ein Repo, und Claude Code (oder jeder andere MCP-Client) erhält ein einziges Tool, docgraph_context(task, max_tokens), das eine Aufgabenbeschreibung in ein bewertetes, token-budgetiertes Markdown-Paket verwandelt, das aus der eigenen Dokumentation dieses Repos stammt – anstatt ganze Dateien pauschal zu lesen und zu hoffen, dass der relevante Teil irgendwo darin steckt.

Warum

Agenten-Kontextfenster sind endlich und Dokumentationsbäume sind nicht für den Abruf kuratiert. "Lies docs/**" sprengt entweder das Budget bei einem großen Repo oder übersieht stillschweigend Dateien außerhalb von docs/. DocGraph indexiert, was tatsächlich Dokumentation ist (Skills, Monorepo-Subprojekt-READMEs, lose Root-Dateien – nicht nur docs/), teilt lange katalogartige Dateien in ihre eigentlichen Abschnitte auf und gibt nur das zurück, was eine bestimmte Aufgabe benötigt.

Keine Embeddings, keine LLM-Aufrufe im Abrufpfad. Deterministisch und überprüfbar – Sie können immer sehen, warum ein Dokument in ein Paket aufgenommen wurde.

Related MCP server: search-docs

So funktioniert es

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

Installieren

pip install -e .

Verwendung

# 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"

Aufgabenstrings werden als Stichwortsuche verwendet, nicht als semantische Suche – seien Sie spezifisch und vermeiden Sie es, eine Datei zu nennen, die Sie gerade erstellen möchten (sie kann nichts finden, was noch nicht existiert).

Registrieren bei 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

Eine Serverinstanz = ein Repo + ein Index. Für mehrere Repos registrieren Sie mehrere Server mit unterschiedlichen Namen und separaten .db-Dateien.

Erkennungsregel

• root – lose .md-Dateien direkt im Repo-Root

• docs – alles unter einem Verzeichnis namens docs, jede Tiefe

• skills – ebenso für ein Verzeichnis namens skills (erfasst .claude/skills/ und .agents/skills/)

• subdir-allcaps – Dateien genau eine Ebene unter dem Root, in einem anderen Unterverzeichnis, deren Dateiname in GROSSBUCHSTABEN ist (README, TODO, ARCHITECTURE...) – deckt Monorepo-Subprojekt-Metadokumente ab

Jeder Bucket kann pro Lauf mit --exclude-bucket ausgeschlossen werden.

Design-Anmerkungen

• FTS5 mit Porter-Stemming, keine Embeddings. Deterministisch, günstig und gut genug – explizite verknüpfungsübergreifende Links wurden bei jedem echten Repo, gegen das dies getestet wurde, durchweg nahe Null getestet.

• Kookkurrenz-Kanten, keine expliziten Links. Dateien im selben Verzeichnis erhalten eine schwache "verwandte" Kante, da dies das Signal ist, das tatsächlich vorhanden ist. Begrenzt auf 10 Dateien pro Verzeichnis – ab diesem Punkt ist "gleicher Ordner" keine sinnvolle Beziehung mehr, sondern wird zum Rauschen.

• Rekursives Chunking, keine feste Tiefe. Lange Dokumente werden bei H2 aufgeteilt; jeder Abschnitt, der immer noch zu groß ist und echte Unterstruktur hat, wird bei H3, dann H4 erneut aufgeteilt. Manche Repos haben flache Kataloge von H2-Abschnitten, andere haben ein einziges allgemeines H2, das die eigentliche Struktur bei H3 verbirgt – eine feste Tiefe ist in beiden Fällen falsch.

• AND-zuerst, ODER-Fallback-Abfragen. Versuchen Sie zuerst, jedes Abfragewort gemeinsam auftreten zu lassen; erweitern Sie nur auf ODER, wenn nichts gefunden wird. Ein einzelner präziser Treffer ist ein besserer Beleg als mehrere verrauschte.

• Content-Hash-Deduplizierung zur Indexzeit. Gespiegelte Dateien (z. B. ein Skill, der sowohl unter .claude/ als auch unter .agents/ dupliziert ist) werden einmal indexiert, nicht zweimal.

Status

MVP, validiert gegen drei reale Repos unterschiedlicher Form (10-, 8- und 72-Dateien-Korpora) und im Live-Einsatz über Claude Code. Nicht gebaut: Embeddings, Watch-Mode, eine echte Graph-Benutzeroberfläche jenseits des Visualisierungs-POCs, Repo-übergreifende Suche.

Lizenz

Persönliches Projekt, keine Lizenz angegeben.