DevDocs 完全教程:把技术文档站爬成本地知识库,再通过 MCP 喂给 AI 编程助手
用 AI 编程助手写代码时,最常见的翻车原因是:模型脑子里的文档是旧的。你让它按某个库的最新 API 写代码,它一本正经地用上一个大版本的写法;你把文档链接发给它,它又读不了几页。人工查文档、复制粘贴给 AI,既慢又碎。
DevDocs(GitHub:cyberagiinc/DevDocs,Apache-2.0 协议,约 2.1k Star)解决的正是这个问题:它是一个完全免费、本地私有、带 Web 界面的技术文档 MCP 服务器。你给它一个技术文档站的网址,它自动发现并爬取整站相关页面,把内容清洗成干净的 Markdown 存到本地,然后通过 MCP(Model Context Protocol)协议提供给 Cursor、Windsurf、Cline、Roo Code、Claude Desktop 等 AI 工具随时检索。相当于先把「最新文档」搬进本地知识库,再让 AI 在写代码时随查随用。
本文按官方 README 与仓库配置实测整理:功能与架构、Docker 安装、环境配置、从爬取文档到接入 AI 客户端的完整流程,以及必须提前知道的维护状态等注意事项。
一、功能总览与架构
DevDocs 的工作可以概括为四步:发现 → 爬取 → 清洗存储 → MCP 供给。核心功能如下:
- 智能爬取:输入一个文档 URL 后自动发现子链接并绘制站点结构,爬取深度可设 1–5 层;支持选择性爬取,只抓你勾选的页面
- 高性能抓取:基于 Crawl4AI(Playwright 驱动)并行爬取多页,带智能缓存避免重复抓取,支持现代 Web 应用的懒加载,并有速率限制,不会把目标站点打挂
- 内容处理:提取正文、去除噪音,输出结构清晰的内容;可导出 Markdown 或 JSON(JSON 适合做大模型微调数据),抓取结果落在本地
storage/markdown目录 - MCP 服务器集成:内置 fast-markdown MCP 服务,把本地文档库以「目录(Table of Contents)」和「章节(Section)」两个工具暴露给 AI 客户端,AI 先查目录定位、再按节取原文,引用可溯源
- 企业级特性:失败自动重试的错误恢复、全量操作日志、API 访问、团队席位与角色管理
技术栈与部署形态:前端是 Next.js(TypeScript),后端与爬虫是 Python(Crawl4AI),Docker Compose 一键拉起四个容器——devdocs-frontend(界面,端口 3001)、devdocs-backend(API,端口 24125)、devdocs-crawl4ai(爬取服务,端口 11235)和 devdocs-mcp(MCP 服务器)。全部跑在自己机器上,文档数据不出本地,这也是它主打「private」的含义。官方在 README 中将它与 Firecrawl 对比:DevDocs 免费、可自托管、不限页数且原生支持 MCP,而 Firecrawl 是按月付费的云服务——是否选它,主要就看你是否需要本地私有化。
二、安装与配置
前置条件只有两样:Docker(含 Docker Compose)和 Git。官方推荐 Docker 方式,三步启动:
# 1. 克隆仓库
git clone https://github.com/cyberagiinc/DevDocs.git
cd DevDocs
# 2. 准备环境变量
cp .env.template .env
# 3. 启动全部服务(会自动建目录、设权限、构建并拉起容器、做健康监测)
./docker-start.sh
启动前检查 .env 里最关键的一项:NEXT_PUBLIC_BACKEND_URL 要指向后端地址(本机使用即 http://localhost:24125),它决定浏览器里的前端能否连上后端。其余可调项都在 .env.template 里有注释,常用的有:
# Crawl4AI 接口令牌(可选,生产环境建议改掉模板里的演示值)
CRAWL4AI_API_TOKEN=your-token
# 爬取并发任务数,按机器配置调整
MAX_CONCURRENT_TASKS=5
# 后端等待爬取发现结果的超时(秒)
DISCOVERY_POLLING_TIMEOUT_SECONDS=300
# 如需启用 Crawl4AI 的 LLM 能力,再填这两项
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
启动完成后,三个入口分别是:
- 前端界面:
http://localhost:3001 - 后端 API:
http://localhost:24125 - Crawl4AI 服务:
http://localhost:11235
Windows 也可以跑,但官方明确标注为实验性、未充分测试:需先装好 WSL 2 与 Docker Desktop,再运行 docker-start.bat;若遇到权限问题,要给 logs、storage、crawl_results 三个目录补权限。Linux 用户若碰到容器间连通问题,可在 .env 里放开 MCP_HOST 并填宿主机 IP(macOS/Windows 用 host.docker.internal 自动处理,无需设置)。停止服务只需在运行 docker-start 的终端按 Ctrl+C。
三、使用教程:从爬文档到让 AI 查文档
步骤 1:打开界面,输入文档地址
浏览器打开 http://localhost:3001,把目标技术文档的入口 URL 填进去(比如某个库的官方文档首页)。DevDocs 会先做一次「发现(Discovery)」:顺着链接把站点结构摸清,按层级列出可抓取的页面,最多 5 层。
步骤 2:选深度、勾页面、开始爬取
在发现结果里设置爬取深度(1–5),勾选真正需要的页面——不必整站全抓,手册类文档抓核心章节即可,既快又省空间。确认后开始爬取,多页并行执行,失败的页面会自动重试;进度和结果都可以在界面里查看,抓好的内容会以 Markdown 形式存入本地 storage/markdown,也可以按需导出 MD 或 JSON 文件。
步骤 3:把 MCP 服务器接入 AI 客户端
这是 DevDocs 的点睛之笔。仓库自带了一份 Claude 客户端的配置示例 claude_mcp_settings.json,原理是让 AI 客户端通过 docker exec 调用正在运行的 devdocs-mcp 容器里的 fast-markdown 服务:
把这段配置合并进你的 AI 客户端的 MCP 设置里(Claude Desktop、Cursor、Windsurf、Cline、Roo Code 的配置入口都在各自的 MCP 设置页),重启客户端后,它就能识别到名为 fast-markdown 的 MCP 服务器。注意前提:DevDocs 的 Docker 服务必须处于运行状态,容器不在,AI 就连不上文档库。
步骤 4:在 AI 对话里查文档写代码
接入后,AI 客户端会多出两个文档工具:Table Of Contents(返回文档目录,可按关键词过滤)和 Section Access(按节取详细内容)。正确的工作姿势是让 AI「先查目录、再钻章节」:你问「这个库的重试机制怎么配置」,AI 先用目录工具定位到相关章节,再取原文,最后基于原文回答并标注出处,而不是凭记忆编造。
官方还给 Roo Code 用户提供了一个进阶玩法:在 Roo Code 里新建一个专用模式(例如命名为 Research_MCP),在模式的角色定义与自定义指令里写明「凡是涉及文档的问题,必须先调用 Table Of Contents 工具定位、再用 Section Access 工具取原文,回答要给出章节出处」,把查文档的流程固化成 Agent 的行为规范。这样在开发时切到这个模式提问,答案的准确性和可溯源性会明显好于直接裸问模型。
步骤 5:日常运维与排障
仓库附带了一批脚本:check_mcp_health.sh 检查 MCP 服务器健康状态、restart_and_test_mcp.sh 重启容器并测试 MCP 连通性、check_crawl4ai.sh / debug_crawl4ai.sh 检查与调试爬取服务、view_result.sh 格式化查看爬取结果。出问题先看容器日志:
# 分别查看四个容器的日志
docker logs devdocs-frontend
docker logs devdocs-backend
docker logs devdocs-mcp
docker logs devdocs-crawl4ai
# 实时跟踪后端日志(排障常用)
docker logs -f devdocs-backend
不用 Docker 的本地开发场景也有 start.sh / start.bat / start.ps1 一键脚本(前端、后端、MCP 一起拉起),改源码调试时用它更方便。
四、注意事项
- 维护状态(重要):仓库 README 顶部明确声明,公开版本目前不再公开维护(Not publicly maintained),增强版在 CyberAGI 内部开发、称后续会发布。也就是说,现在的开源版可以正常自托管使用,但不要期待官方持续修 bug 和发新版,生产引入前要评估这一点
- Windows 支持是实验性的:官方未充分测试,权限与 docker-compose 编码都可能踩坑,Windows 用户优先考虑 WSL 2 环境里按 Linux 流程跑
- 资源占用:Crawl4AI 基于真实浏览器(Playwright)抓取,四个容器同时运行对内存有一定要求;并发数
MAX_CONCURRENT_TASKS默认 5,小内存机器建议调低,抓大站时留意磁盘上的 markdown 与缓存增长 - 爬取礼仪与合规:它自带速率限制,但抓取深度和范围仍由你控制;只抓你有权使用的公开文档,尊重目标站点的 robots 与服务条款,别拿它当通用爬虫去批量采集内容站
- 数据时效:本地文档库是抓取时刻的快照,目标文档更新后需要重新爬取才能同步;把它当「可刷新的缓存」,而不是一次抓完永久有效
- 路线图功能尚不存在:官方 Roadmap 里的动态内容增强爬取、浏览器池热加载、界面内 PDF 上传提取、托管版持久化等都还是计划项,不要按已实现功能去规划使用
五、适用人群与小结
DevDocs 适合这几类人:重度使用 Cursor、Cline、Roo Code 等 AI 编程工具、经常被模型「用旧 API 写新代码」坑到的开发者;需要频繁对接新框架、新 SDK,想把查文档时间从数周压到数小时的团队;以及有内部文档、希望在不出内网的前提下让 AI 能查私有知识库的企业研发团队(全部组件本地运行,这一点对数据敏感场景很关键)。反过来,如果你只是偶尔问 AI 一两个 API 用法,直接联网搜索或把单页文档贴给模型就够了,专门部署一套四容器服务并不划算。
总结一下:DevDocs 的思路是把「让 AI 读最新文档」这件事工程化——Crawl4AI 负责把文档站高质量地搬下来,Markdown 做统一的本地存储格式,MCP 负责把文档库标准化地供给任何支持该协议的 AI 客户端。这个组合在今天的 AI 编程工作流里相当实用。唯一的保留意见是它的公开维护已经暂停:个人和团队尝鲜、内部小规模使用没问题;若要把它放进关键生产链路,建议先评估 fork 自维护的成本,或观望官方所说的增强版公开发布。







