DocGraph

Репозиторий-нативный брокер контекста в Markdown — MCP-инструмент, который предоставляет кодирующим агентам релевантную задаче документацию вместо сброса docs/**.

Укажите репозиторий, и Claude Code (или любой MCP-клиент) получит единственный инструмент, docgraph_context(task, max_tokens), который превращает описание задачи в ранжированный, ограниченный по токенам набор Markdown-файлов, извлечённый из документации самого репозитория — вместо того, чтобы читать целые файлы целиком и надеяться, что нужная часть где-то там есть.

Зачем

Окна контекста агентов конечны, а структуры документации не предназначены для поиска. «Прочитать docs/**» либо превышает бюджет в большом репозитории, либо молча пропускает файлы вне docs/. DocGraph индексирует то, что действительно является документацией (навыки, README подпроектов монорепозитория, отдельные корневые файлы — не только docs/), разбивает длинные файлы-каталоги на их реальные разделы и возвращает только то, что нужно для конкретной задачи.

Никаких эмбеддингов, никаких вызовов LLM в процессе поиска. Детерминированно и проверяемо — вы всегда можете увидеть, почему документ попал в набор.

Related MCP server: search-docs

Как это работает

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

Установка

pip install -e .

Использование

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

Строки задачи используются как поиск по ключевым словам, а не семантический поиск — будьте конкретны и избегайте указания имени файла, который вы собираетесь создать (он не может совпасть с тем, чего ещё не существует).

Регистрация в 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

Один экземпляр сервера = один репозиторий + один индекс. Для нескольких репозиториев зарегистрируйте несколько серверов с разными именами и отдельными файлами .db.

Правило обнаружения

• root — отдельные файлы .md непосредственно в корне репозитория

• docs — всё, что находится в каталоге с именем docs на любой глубине

• skills — то же самое для каталога с именем skills (захватывает .claude/skills/ и .agents/skills/)

• subdir-allcaps — файлы ровно на один уровень ниже корня, в другом подкаталоге, имя которых (без расширения) написано ЗАГЛАВНЫМИ БУКВАМИ (README, TODO, ARCHITECTURE...) — охватывает мета-документы подпроектов монорепозитория

Любое хранилище может быть исключено из запуска с помощью --exclude-bucket.

Заметки по дизайну

• FTS5 с портерной стеммингом, без эмбеддингов. Детерминированно, дёшево и достаточно хорошо — явные ссылки между документами стабильно близки к нулю во всех реальных репозиториях, на которых это тестировалось.

• Рёбра по совместному расположению, а не явные ссылки. Файлы в одном каталоге получают слабое ребро «связан», так как это сигнал, который действительно присутствует. Ограничение — 10 файлов на каталог; после этого «одна папка» перестаёт быть значимой связью и становится шумом.

• Рекурсивное разбиение, а не фиксированная глубина. Длинные документы разбиваются на уровне H2; любой раздел, всё ещё слишком большой с реальной подструктурой, разбивается снова на уровне H3, затем H4. В одних репозиториях плоские каталоги разделов H2, в других — один всеобъемлющий H2, скрывающий реальную структуру под H3 — фиксированная глубина в любом случае неверна для одного из них.

• Сначала AND, затем OR при неудаче. Сначала попробуйте требовать совместного вхождения всех слов запроса; расширяйте до OR только если ничего не найдено. Одно точное совпадение — лучшее доказательство, чем несколько шумных.

• Дедупликация по хешу содержимого при индексации. Зеркальные файлы (например, навык, дублированный в .claude/ и .agents/) индексируются один раз, а не два.

Статус

MVP, протестирован на трёх реальных репозиториях разной структуры (корпуса из 10, 8 и 72 файлов) и используется вживую через Claude Code. Не реализовано: эмбеддинги, режим наблюдения, реальный интерфейс графа (кроме прототипа визуализации), поиск по нескольким репозиториям.

Лицензия

Личный проект, лицензия не указана.