Grounded Docs MCP Server：把版本精确的文档索引塞进 AI 编码助手
Grounded Docs MCP Server: Open-Source Alternative to Context7, Nia, and Ref.Tools
秒懂
- 它是什么？
- 这是一个用 TypeScript 写的 MCP 文档服务，把官网、GitHub、npm、PyPI 和本地文件抓成本地索引，让模型按你项目里的版本查文档。它解决的是知识过期和幻觉，代价是索引要自己维护。
- 适合谁用？
- 适合已经在用 MCP 客户端、并且被旧版本文档坑过的人：把 React、某个内部 SDK 或一份 PDF 规范抓成本地索引，让模型查你实际装的版本。不适合只想零维护、或者团队没有能力跑一个常驻服务加嵌入模型的人，因为索引陈旧时它给出的答案和普通幻觉一样难查。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 17 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它要修的是版本错配，不是模型不够聪明
大模型答错库的用法，很多时候不是推理失败，而是它脑子里的那版文档和你 package.json 里的那版不是一回事。Grounded Docs 的做法很直接：不去改模型，改的是上下文来源。它把官方文档站、GitHub 仓库、npm、PyPI 以及本地文件夹抓下来，在本地建一个索引，AI 助手通过 MCP 查这个索引。README 里把卖点写成「Queries target the exact library versions in your project」，这句话是整个项目的定位。目标用户是有 MCP 客户端的人：Claude、Cline、Copilot、Gemini CLI，或者任何支持 MCP 的编辑器插件。它不打算替代你的模型，只打算替代模型对文档的记忆。
抓取管线：llms.txt、Accept 头和 hash 路由的三种分支
从 README 描述的行为看，抓取不是简单地把 URL 丢进爬虫。网页抓取和刷新会先探测文档子路径和站点根目录下的 llms.txt，找到之后，里面列出的链接会作为额外的抓取种子，并且这类页面优先取 .md 变体，比如 /guide/index.html.md，取不到才回退到原始页面。请求头默认带 Accept: text/markdown, text/html;q=0.9, */*;q=0.8，也就是先问服务端要 Markdown。这套设计的意图是绕开导航栏和脚本，直接拿正文，能省掉一部分 HTML 清洗的成本。另一条分支是 hash 路由的单页应用：只有文档站用 #/guide 这种路由时才该开 preserveHashes，README 特别提醒普通站点的 hash 通常只是页内锚点，乱开会把同一页拆成很多条目。开启后如果抓取模式是 fetch，系统会自动把任务升级成 Playwright，因为纯 fetch 无法执行客户端路由。这是一个诚实的工程取舍：需要浏览器渲染，就意味着更慢、更重。
跑起来：CLI 三条命令和 MCP 的一段 JSON
README 把 CLI 放在最前面，理由是脚本和 agent 用命令行最省事。抓取一条文档：npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react。查询：npx @arabold/docs-mcp-server@latest search react "useEffect cleanup" --output yaml。单页转 Markdown：npx @arabold/docs-mcp-server@latest fetch-url https://react.dev/reference/react/useEffect。运行环境要求 Node.js 22 以上。输出行为有明确约定：结构化命令在非交互运行时默认往 stdout 打干净的 JSON，可以用 --output json|yaml|toon 切换，诊断信息走共享 logger 并刻意避开 stdout，--quiet 压掉非错误诊断，--verbose 打开调试输出。这个约定对写管道的人比对人重要。要常驻服务就直接 npx @arabold/docs-mcp-server@latest，Web UI 在 http://localhost:6280，客户端配置里写 type 为 sse、url 为 http://localhost:6280/sse。Docker 方式在 README 里给了完整命令，挂载 /data 和 /config 两个卷，暴露 6280，启动参数是 --protocol http --host 0.0.0.0 --port 6280。
嵌入模型是可选开关，但选与不选是两种体验
README 把嵌入模型标为 optional，紧接着说它「dramatically improves search quality by enabling semantic vector search」。这两句话放在一起才是完整信息：不配也能用，但检索退化成关键词匹配，问「useEffect 清理函数怎么写」和文档里写「cleanup function」的段落可能对不上。开启方式简单到一行，OPENAI_API_KEY 作为环境变量前置即可，另外支持 Ollama、Gemini、Azure 等，具体在 docs/guides/embedding-models.md。这里有一个值得注意的取舍：本地运行是它的隐私卖点，README 写「your code never leaves your network」，但一旦选了云嵌入服务，文档内容就要出网。想守住本地这条线，得选 Ollama 这类自托管方案，代价是自己维护模型服务。仓库里还有一份 docs/guides/benchmarking.md，说明怎么用 IR 指标加 LLM 打分来衡量检索质量，这是判断该不该开嵌入、开哪种的实测入口，而不是靠感觉。
格式覆盖面很宽，宽到需要怀疑索引质量
支持列表长得有点夸张：PDF、Word、Excel、PowerPoint、OpenDocument、RTF、EPUB、FictionBook、Jupyter Notebook，压缩包 ZIP/TAR/tar.gz 会解包后逐个处理，Markdown 系有 MDX、reStructuredText、AsciiDoc、Org Mode、Textile、R Markdown，源码号称覆盖 90 多种语言，另有 JSON、YAML、TOML、CSV、XML、SQL、GraphQL、Protobuf，配置类还有 Dockerfile、Makefile、Terraform/HCL、INI、dotenv、Bazel。对需要把内部规范、Excel 接口表、Jupyter 教程一起喂给模型的人，这是实打实的便利。但覆盖面不等于解析质量：表格密集的 Excel 和扫描版 PDF 抽出来的文本通常不完整，README 没有对每种格式的抽取效果作出承诺，文档里给的是 MIME 类型和处理细节的参考。实际使用前应该拿自己最关键的那几份文件试一遍，看抽出来的文本能不能支撑问答，而不是先信这张表。
它不适合谁：索引陈旧时和幻觉没有区别
这个项目最容易被忽略的成本是索引的时效性。它抓的是快照，不是实时接口。上游文档改了、你的依赖从 18 升到 19，索引不会自己知道，除非你重新抓取或刷新。README 提到刷新会默认复用已存的 preserveHashes 设置，CLI 和 Web 入口都能显式覆盖，也就是说刷新是有人触发的动作，不是自动同步。于是出现一个尴尬场景：模型拿着一个两周前的索引，用很确定的语气回答，你反而更难发现它错了，因为答案有「来源」。另外两类人不该选它。第一类是只用云端托管文档服务、不想在本机跑常驻进程的人，6280 端口、数据卷、嵌入模型都是要管的。第二类是把整个仓库源码当文档索引的人，源码格式虽然支持，但代码检索和文档检索的目标不同，索引一大，检索精度和存储都会变差。
和 Context7 这类托管方案的差别在数据放在哪
README 自己把 Context7、Nia、Ref.Tools 列为对标对象，并把自己定位成开源替代。差别不在功能清单，而在数据流向。托管服务替你抓公开文档、维护索引，你只管调用，省掉运维，但你的查询走别人的服务，私有文档要么传上去，要么根本用不了。Grounded Docs 反过来：抓取、索引、检索都在你机器上，代价是索引的覆盖范围和新鲜度由你自己负责。判断标准因此变得很清楚。如果你只查 React、Vue 这类公开且更新频繁的库，托管方案的人力成本更低。如果你要查的是公司内部 SDK、一份 PDF 规范、一个私有 GitHub 仓库，或者合规上不允许文档内容出网，那么本地索引是唯一可行的路线。另一个区别是它的 CLI 可以脱离 MCP 单独使用，脚本和 CI 里能直接调 scrape 和 search，托管服务通常只给 MCP 或 API 一种入口。
维护成本与 MIT 许可的边界
维护成本主要来自三块。一是 Node.js 版本门槛，README 要求 22 以上，老环境要先升级。二是抓取任务本身，站点结构变了、反爬加强、llms.txt 出现或消失，都会影响结果，hash 路由站点还会因为升级到 Playwright 而变慢。三是嵌入模型，选云端要管密钥和费用，选 Ollama 要管模型服务。许可方面，仓库标注 MIT，这是宽松许可，允许修改和商用，但具体到你的分发方式、是否保留版权声明、以及嵌入模型提供商的条款，需要自己核对 LICENSE 文件和相应服务协议，这里不构成法律意见。版本节奏可以参考发布记录：v3.0.0 在 2026-08-08，v3.0.1 在 2026-08-14，v3.1.0 在 2026-08-29，三周内三个版本，说明接口和配置项还在动，升级前值得看一眼 release notes 里有没有破坏性改动。
编辑结论
适合已经在用 MCP 客户端、并且被旧版本文档坑过的人：把 React、某个内部 SDK 或一份 PDF 规范抓成本地索引，让模型查你实际装的版本。不适合只想零维护、或者团队没有能力跑一个常驻服务加嵌入模型的人，因为索引陈旧时它给出的答案和普通幻觉一样难查。上手前先确认三件事：Node.js 是否达到 22 以上，你的文档站是不是 hash 路由的 SPA（是就得加 --preserve-hashes 并会升级到 Playwright），以及是否准备配置嵌入模型，README 明确说这是可选项但会明显影响搜索质量。
社区笔记