Agent Docs

Agent Docs

一个 MCP 服务，为 AI Agent 提供 Claude Code、Cursor、Codex 和 MCP 的最新官方文档。

这些工具的变化速度比模型训练数据更新得更快。Agent Docs 将其官方文档中约 600 个页面保存在搜索索引中，每天刷新，并为你的 Agent 提供两个工具：一个用于查找相关段落，另一个用于读取整个章节。Agent 根据真实文档作答，并可链接到这些文档。

它以远程 MCP 服务的形式运行（也支持 REST）。你可以使用免费的 Cohere 密钥试用。

按自己的节奏逐步查看（可使用方向键），或打开静态图片：

15 个步骤的静态图片

_{源代码及重建方法：[docs/flow/](docs/flow/)}

构建方式及测量结果：ARCHITECTURE.md。

---

连接

将此服务添加到任意 MCP 客户端（Claude Code、Cursor、OpenWebUI 等）：

{
  "mcpServers": {
    "agent-docs": {
      "url": "https://agent-docs-mcp.onrender.com/mcp/",
      "headers": { "X-Cohere-Api-Key": "<your Cohere key>" }
    }
  }
}

调用工具需要以下两种请求头之一：

• 你自己的 Cohere 密钥： X-Cohere-Api-Key: <key>。免费试用密钥可在 dashboard.cohere.com 获取。该密钥仅用于 为这一次请求的重排序付费；不会被存储或记录。限制：每个 IP 每分钟 30 次请求。
• 所有者提供的令牌： Authorization: Bearer <API_TOKEN>。如需访客令牌，请提交 issue， 标题为 “Guest token request”。

此服务使用免费套餐：闲置 15 分钟后，首个请求需要约一分钟。

工具	返回内容
search_docs(query, limit=8, product=None, response_format="concise")	按排名返回每个匹配页面中最相关的段落，以及页面的一行描述和相关性评分。每次调用询问一个主题。product：claude-code、cursor、codex、mcp
read_section(url, heading=None, offset=0, outline_depth=2)	不指定标题时：返回页面描述和大纲（outline_depth=3 会添加子章节）。指定标题时：返回整个章节，每次调用最多 8,000 个字符（next_offset 可获取剩余内容）

通过 REST 使用：

curl -X POST https://agent-docs-mcp.onrender.com/ask \
  -H "Authorization: Bearer $API_TOKEN" -H 'content-type: application/json' \
  -d '{"question": "How do I add an MCP server in Claude Code?"}'

使用自己的密钥时，将 Authorization 行替换为 -H "X-Cohere-Api-Key: $COHERE_API_KEY"。

端点	用途
GET /health	存活状态检查，无需令牌
POST /ask	带引用的文字答复
POST /search	带页面描述的段落（search_docs）
POST /pages	页面卡片：描述和大纲
POST /section	页面中的一个章节（read_section）
POST /mcp/	MCP（可流式 HTTP）
GET /docs	交互式 API 文档（使用令牌点击 Authorize）

本地使用，无需服务（stdio，无需令牌）：

{ "mcpServers": { "agent-docs": { "command": "uv",
  "args": ["run", "--directory", "/path/to/agent-docs", "rag-mcp"] } } }

**适用于 MCP 目录：**连接和列出工具无需密钥（每个 IP 每分钟 30 次请求）；只有 tools/call 需要密钥。此服务不保留会话，因此 GET /mcp 会返回 405；所有请求都必须使用 POST 发送。已作为 io.github.KonstantinStarovoytov/agent-docs 列入 官方 MCP 注册表（server.json）。

覆盖范围

产品	来源
Claude Code（包括 Agent SDK、插件）	code.claude.com/docs/llms.txt
Cursor	cursor.com/llms.txt
Codex	developers.openai.com/codex/llms.txt
MCP（最新规范、注册表、扩展）	modelcontextprotocol.io/llms.txt

---

工作原理

你的 Agent 会调用 search_docs，然后在段落内容不足时调用 read_section。此服务不会运行大模型；Agent 会读取这些段落并自行编写答复。

search_docs 分四步工作：

1. 同时按含义（嵌入）和精确词语（BM25）进行搜索，因此“连接工具服务”和 claude mcp add 都能找到正确页面。
2. 按排名合并两个结果列表。排名相同时按固定顺序排列，因此相同问题总会得到相同结果。
3. 重排序器（Cohere）会结合问题读取排名前 20 的结果，并为每个结果的匹配程度打分。
4. 保留每个页面中最相关的段落，并添加页面的一行描述及其他匹配章节的标题。

read_section 从已存储的页面副本中读取内容；不会调用大模型。搜索记录会发送到 Langfuse。

REST 端点 /ask 面向非 Agent 客户端。它还会将俄语和波兰语问题翻译成英语；当最佳候选结果的评分低于 0.55 时，会说明“文档未涵盖此内容”；选取 8 个文本块（同一章节最多 2 个），并由 gpt-6-luna 根据这些文本块撰写带引用的答复。

每日更新

按自己的节奏逐步了解，或查看静态图片：

12 个步骤的静态图片

每天 06:00 UTC，GitHub Actions 作业会读取每个供应商的页面列表 （llms.txt），并更新索引：

• 变更的页面会重新生成嵌入；未变更的页面则会跳过。
• 新页面会先经过检查。可疑页面会暂留在 GitHub issue 中，直到所有者勾选 Index 或 Decline。
• 从列表中消失的页面会被删除，除非一次消失的页面过多。
• 产品变更的简短报告会发布到 reports/docs-changes/。

测得的结果

保留每项更改前，都先用带标签的问题进行测量。所有实验，包括未奏效的实验： ARCHITECTURE.md。

更改	测得的效果
/ask 使用 8 个分块，而不是 5 个	多部分问题得到完整覆盖：25% → 75%
非英语问题的英文副本	Hit@5：0.958 → 1.000
重排器使用 10 个候选项，而非 20 个	完整覆盖率：75% 对比 50%（额外候选项挤掉了第二个主题）
使用 gpt-6-luna，而不是 gpt-5.6-luna	忠实度：0.975 → 0.994
按固定顺序处理平局	同一个问题总会得到相同的结果（之前并非如此）
search_docs 每页返回一个段落	前 5 个结果中的不同页面数：3.1 → 5.0；页面命中率@5：0.936 → 0.979
页面其他匹配部分的标题（other_sections）	可见的带标签部分：0.667 → 0.867；使用真实 Agent 时，正确率相同，且部分读取失败更少（11 → 1）

答案遗漏问题的某个部分时，搜索通常已经找到了正确文本。问题出在后续环节：候选内容被精简到模型可见的范围时，相关信息就丢失了。

---

运行位置

部分	服务	方案
API + MCP 服务	Render，服务 agent-docs，位于 agent-docs-mcp.onrender.com	免费 Web 服务
向量索引	Qdrant Cloud	免费 1 GB 集群
追踪记录、评估数据集、提示词	Langfuse Cloud	免费 Hobby 方案
每日重新索引、CI	GitHub Actions	免费
嵌入、答案	OpenAI（text-embedding-3-small、gpt-6-luna）	按使用量付费
重排	Cohere（rerank-v4.0-fast）	试用密钥 + 备用密钥

仅在 CI 通过后才会部署。整个服务都定义在 render.yaml 中。

部署你自己的实例： Render → New → Blueprint → 选择此仓库。填写所需的密钥（OPENAI_API_KEY、COHERE_API_KEY、可选的 COHERE_API_KEY_FALLBACK、 QDRANT_URL、QDRANT_API_KEY、LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY）； 系统会为你生成 API_TOKEN。如果更改主机名，请更新 API_ALLOWED_HOSTS（MCP 传输会拒绝未知主机）。清除 API_GUEST_TOKEN 即可撤销访客访问权限。

费用

项目	费用
托管、数据库、追踪、CI	$0 / 月（免费套餐）
一次回答（/ask）	≈ $0.0007（OpenAI；重排使用免费试用额度）
一次搜索（search_docs）	≈ $0（一次嵌入 + 一次重排）
每日重新索引，内容无变化	$0
每日重新索引，少量页面有变化	< $0.01（嵌入 + 每个新页面一次简短的大模型检查）
完整重建索引	一次性约 $0.10–0.30（嵌入约 $0.07 + 每页一次简短的大模型检查）

免费方案的限制：Cohere 试用版每个密钥每月允许重排 1,000 次（两个密钥），每分钟 10 次；API 的付费请求上限为每分钟 60 次。

---

开发

uv sync --locked                      # Python 3.14
cp .env.example .env                  # OpenAI, Cohere, Qdrant, Langfuse keys
docker compose up -d                  # local Qdrant + API on :8080
uv run python -m src.ask "How do skills work?"
uv run pytest -q && uv run ruff check src evals tests && uv run ruff format --check src evals tests && uv run mypy

在本地重新索引：uv run python -m src.reindex --dry-run --out /tmp/r （不写入任何数据）——也可以在 GitHub Actions 中运行 Reindex 工作流。

文件夹	内容
src/ingestion/	页面筛选、分块、垃圾内容过滤、变更报告
src/rag/	搜索、重排、上下文选择、生成
src/service/	REST API 和 MCP 服务（共用一个处理程序）
src/prompts/	提示词，在 Langfuse 中进行版本管理
evals/	评估门禁：数据集、运行程序、评分器（指南）
reports/	实验结果和每日变更报告（索引）
docs/	图表、动画、发现、发布说明
data/manifests/	各索引包含的内容，按页面列出
scripts/	图表渲染、使用项目密钥的 Langfuse CLI

图表：编辑 docs/diagrams/*.mmd，然后运行 uv run python scripts/render_diagrams.py。 动画：编辑 docs/flow/flows/ask.js（一个问题）或 docs/flow/flows/reindex.js （每日重新索引），然后运行 docs/flow/render.sh。

许可证

MIT