doctree-mcp

doctree-mcp

针对 Markdown、CSV 和 JSONL 的 Agentic 文档检索。 通过 MCP 实现 BM25 + 树导航——索引时无需向量数据库、嵌入或调用大模型。

核心思路： MCP 提供结构化原语（可导航的树、BM25、术语表、行查找）。捆绑的技能提供流程知识（如何遍历这棵树）。二者结合后，Agent 的表现就像训练有素的研究馆员，而不是只会一次性搜索的工具。请参阅 技能 + MCP 模式。

---

快速开始

已有文档？ 将客户端指向文档：

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

重启工具 → 提问 “搜索文档中的 X”，或调用 doc-read 提示词。

从头开始？ 搭建 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

创建 docs/wiki/（由 LLM 维护）和 docs/raw-sources/（你的输入），写入 MCP 配置，安装写入后 lint 钩子，并将 wiki 约定附加到 CLAUDE.md / AGENTS.md / .cursor/rules/。

---

运行模式

模式	适用场景	指南
stdio（默认）	本地开发、Agent 在你的机器上运行	客户端配置
HTTP（Streamable HTTP）	团队、CI、托管 Agent	部署 — Railway · Fly · Render · Cloudflare Containers · Docker
CLI	init、lint、debug-index	运行模式

完整决策树：运行模式。

---

工作原理 — 检索 · 整理 · 添加

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

核心读取工具（始终启用）：

工具	用途
search_documents	BM25 关键词搜索 + 分面筛选 + 术语表扩展（Markdown · CSV · JSONL）
get_tree	目录 — 标题、字数、摘要
get_node_content	按节点 ID 获取特定章节的全文
navigate_tree	一次调用获取某章节及其所有子章节
lookup_row	对结构化数据行进行 O(1) 精确键查找（例如 PROJ-44）

Wiki 写入工具（通过 WIKI_WRITE=1 选择启用）：

工具	用途
find_similar	根据重叠率检测重复项
draft_wiki_entry	脚手架：建议路径、推断的 frontmatter、术语表命中项
write_wiki_entry	经验证的写入：路径包含检查、架构验证、重复项防护、试运行

安全机制：路径包含检查 · frontmatter 验证 · 重复项检测 · 试运行 · 覆盖保护。

已弃用的别名（list_documents、find_files、find_symbol）已由 search_documents 取代——仍可使用，但不再推荐。

---

Skill + MCP 模式

大多数检索工具只是给 Agent 一个搜索框，然后听天由命。doctree-mcp 提供的是一棵树，而随附的技能会教它如何在树中探索。

• MCP = 结构化原语。 search_documents、get_tree、navigate_tree、get_node_content、lookup_row 返回的是 Agent 可以据此推理的树中位置，而不是现成答案。
• 技能 = 程序性知识。 /doc-read、/doc-write、/doc-lint 编码了沿线索逐步深入的流程：搜索 → 大纲 → 导航 → 检索。Agent 学到的是策略，而不只是 API。

这种搭配在其他地方并不存在：

方案	原语	技能传授的内容	差距
托管式混合 RAG（Cloudflare AI Search、Nia）	扁平分块 + 相似度	—	黑箱评分，没有审计轨迹
工具直接返回答案（Context7）	2 个返回答案的工具	查询形式	Agent 无法推理被跳过的内容
基于 CLI 的技能（QMD）	针对扁平搜索的 CLI	查询扩展	没有可供导航的树
doctree-mcp + /doc-read	可导航的树	线索导航、多实例路由、维基编纂	—

迭代式检索为何更胜一筹：

• 上下文退化。 将分块内容塞进 1M-token 窗口会降低输出质量。线索导航能让工作记忆保持精简。
• 可审计性。 search_documents → get_tree → navigate_tree → get_node_content 是可重放的轨迹；余弦评分则不是。受监管领域可以部署前者。
• 渐进式披露。 少量可导航原语胜过工具泛滥（参见 Cloudflare Code Mode）。

多实例 = 客户端侧联邦。 使用不同名称注册多个 doctree 服务；/doc-read 技能会编码路由策略。添加或移除实例无需修改技能。请参阅客户端设置 → 多实例路由。

---

LLM 维基模式

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

灵感来自 Karpathy 的 LLM Wiki。完整演练：docs/LLM-WIKI-GUIDE.md。

---

配置（摘要）

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

所有非保留的 frontmatter 字段都会成为筛选维度：

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

常用环境变量：

变量	默认值	描述
DOCS_ROOT	./docs	文档文件夹
DOCS_GLOB	**/*.md	逗号分隔的 glob 模式（**/*.md,**/*.csv,**/*.jsonl）
DOCS_ROOTS	—	加权多集合（./wiki:1.0,./rfcs:0.5）
PORT	3100	HTTP 模式端口
WIKI_WRITE	(未设置)	1 表示启用写入工具
GLOSSARY_PATH	$DOCS_ROOT/glossary.json	查询扩展词汇表

完整参考：docs/CONFIGURATION.md。

词汇表 — 将 glossary.json 放在文档根目录中，以进行双向查询扩展：

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

诸如 "TLS (Transport Layer Security)" 这样的首字母缩略词定义也会自动提取。

结构化数据 — CSV/JSONL 文件会转换为文档，每行都是一个树节点。列角色（id、标题、描述、筛选维度、URL）会根据表头自动检测。请参阅docs/STRUCTURED-DATA.md。

---

从源代码运行

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

---

性能

操作	耗时	Token 开销
完整索引（900 份文档）	2–5s	0
增量重新索引	~50ms	0
搜索	5–30ms	~300–1K tokens
树大纲	<1ms	~200–800 tokens

---

文档

设置与运行

• 运行模式 — stdio · HTTP · CLI
• 客户端设置 — Claude Code · Cursor · Windsurf · Codex · OpenCode · Claude Desktop
• 部署 — Railway · Fly.io · Render · Cloudflare Containers · Docker
• 配置 — 环境变量、frontmatter、排序调优

模式与概念

• LLM Wiki 指南 — 由 Agent 维护的知识库使用指南
• 结构化数据 — CSV / JSONL 索引
• 架构与设计 — BM25 内部机制、树形导航
• 竞品分析 — PageIndex、QMD、GitMCP、Context7、托管式 RAG

源代码

• 提示词 — MCP 提示词模板
• 技能：/doc-read · /doc-write · /doc-lint

---

站在巨人的肩膀上

• PageIndex — 分层树形导航
• CloudCannon 的 Pagefind — BM25 评分、位置索引、分面
• Oven 的 Bun.markdown — 原生 CommonMark 解析器
• Karpathy 的 LLM Wiki — 由 LLM 维护的 Wiki 模式

许可证

MIT