DocGraph

仓库原生 Markdown 上下文代理 — 一个 MCP 工具，它能为编码代理提供任务相关的文档，而不是直接倾倒 docs/** 目录。

将其指向一个仓库，Claude Code（或任何 MCP 客户端）就能获得一个单一工具 docgraph_context(task, max_tokens)，该工具将任务描述转化为一个有序、符合 token 预算的 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 文件。

发现规则

• 根目录 — 仓库根目录下的松散 .md 文件

• docs — 位于名为 docs 的目录下的任何内容，任意深度

• skills — 同上，针对名为 skills 的目录（捕获 .claude/skills/ 和 .agents/skills/）

• 子目录全大写 — 根目录下恰好深一层、位于另一个子目录中、文件名主干为全大写（README、TODO、ARCHITECTURE...）的文件 — 涵盖单体仓库子项目元文档

任何桶都可使用 --exclude-bucket 参数在每次运行时排除。

设计说明

• FTS5 带 porter 词干提取，无需嵌入向量。 确定、廉价且足够好 — 跨文档的显式链接在所有针对此构建的真实仓库中持续测试接近零。

• 共置边，而非显式链接。 同一目录中的文件获得一个弱“相关”边，因为这是实际存在的信号。每个目录最多 10 个文件 — 超过此数，“同一文件夹”就不再是有意义的关系，而成了噪音。

• 递归分块，而非固定深度。 长文档在 H2 处拆分；任何仍过大的部分若包含真实子结构，则在 H3 处再次拆分，然后是 H4。有些仓库具有 H2 部分扁平目录，其他仓库则有一个包罗万象的 H2 隐藏了实际结构在 H3 — 固定深度对其中一种情况总是错误的。

• AND 优先，OR 后备查询。 首先尝试要求每个查询词共现；仅在找不到任何结果时扩展为 OR。一个精确匹配优于多个嘈杂匹配。

• 索引时内容哈希去重。 镜像文件（例如，一个技能重复出现在 .claude/ 和 .agents/ 下）只被索引一次，而非两次。

状态

最小可行产品，已针对三个不同形状的真实仓库（10、8 和 72 个文件的语料库）进行验证，并正在通过 Claude Code 进行实际使用。尚未构建的功能：嵌入向量、监视模式、超越可视化概念验证的真正图形界面、跨仓库搜索。

许可证

个人项目，未指定许可证。