技能介绍

解决的问题

当你让 AI 编程助手写一个真实库的调用代码时，它给的答案经常来自训练记忆：函数名拼错、参数顺序颠倒，或者干脆引用了某个旧版本里早已删除的 API。模型不会告诉你这份文档是哪个版本的，也不会承认它根本没看过官方文档。结果就是看似自信的代码，跑起来全是 TypeError 和 AttributeError。

问题根源是文档访问与版本漂移。助手在训练时见过的文档是静态快照，而 npm、PyPI、GitHub 上的库每周都在变。手工查文档又太慢——让 agent 一边写代码一边开浏览器翻页，上下文很快就被无关内容填满。

核心能力与工作方式

Grounded Docs MCP 服务器的思路是给 agent 一条版本感知的文档索引，把官方来源变成可查询的检索层。

从源头抓取：支持网站、GitHub、npm、PyPI 和本地文件。每个索引绑定明确的版本号，检索时能区分"这个库 1.x 的用法"和"2.x 的新写法"。
语义搜索而非关键词匹配：用 search 这类查询接口做向量检索。你可以直接问 "useEffect cleanup" 这种自然语言问题，而不是去猜文档里用了什么标题。
定点取页：fetch-url 直接拉取某个具体页面，避免 agent 拿到整个文档站的噪音。
输出结构化结果：搜索结果可以指定 --output yaml 之类的形式返回，方便 agent 把片段塞进上下文，而不是把整页 HTML 灌进去。

整个流程是：agent 遇到 API 问题 → 向索引发起语义查询 → 拿到带版本标注的文档片段 → 基于真实文档生成代码。由于答案锚定在索引内容上，幻觉率会明显下降。

适用边界与注意点

索引质量取决于来源质量：它从官方渠道抓取，但官方文档本身也可能写错或过时。生产环境的关键路径仍要人工 review。
首次索引有成本：抓取和向量化整个文档站需要时间，小项目可以先试，大型仓库需要评估等待时间。
版本对齐是硬要求：如果索引的版本和项目 package.json / requirements.txt 里的版本不一致，检索结果依然会误导你。部署时最好把版本固定下来。
本地文件支持有边界：能索引本地文件，但路径权限、.gitignore 约定等仍需自己处理，服务器不会替你决定哪些文件该进索引。
不是 RAG 替代品：它解决的是"查官方文档"，不负责代码库内部知识、PR 历史或团队约定。