Ref MCP
为编程助手按需检索并提取技术文档，减少无关上下文。
这个 Agent 能做什么，适合哪些场景？
Ref MCP 是一个 Model Context Protocol（MCP）服务器，为 AI 编程工具提供 API、服务和库的文档访问能力。它提供推荐的 Streamable HTTP 服务，也保留本地 stdio 服务模式。服务器包含 ref_search_documentation 和 ref_read_url 两个文档工具，前者搜索公开网页、GitHub 以及所述的私有资源，后者将指定网页转换为 Markdown。它利用 MCP 会话中的搜索轨迹避免在相似查询中重复返回结果，并在读取文档时保留最相关的最多约 5,000 个 token。仓库还说明了面向 OpenAI deep research 客户端的 search 与 fetch 工具命名映射。
编程助手先调用 ref_search_documentation(query)，以完整句子或问题搜索相关技术文档；该工具返回可继续读取的文档结果。随后助手调用 ref_read_url(url)，服务器获取该网页并转换成 Markdown；读取时会参考当前 MCP 会话的搜索历史，过滤相关性较低的页面段落并返回最相关的内容。对于重复的相近搜索，服务器不重复返回已有结果。通过 OpenAI 客户端使用时，ref_search_documentation(query) 映射为 search(query)，ref_read_url(url) 映射为 fetch(id)。
- 使用 Claude Code 的开发者需要查询 Figma Comment REST API 的具体端点时，可先搜索再读取对应文档页面。
- 维护 n8n 工作流的工程师需要比较 Merge 节点和 Code 节点的多输入处理方式时，可连续搜索并读取多个相关章节。
- 将 MCP 工具接入支持 Streamable HTTP 的编程环境的团队，需要让编码助手按需读取 API、服务或库文档时。
- 需要通过 npx 在本机以 stdio 方式运行文档工具的开发者，可将其配置为本地 MCP 服务器。
- 通过 OpenAI 客户端开展 deep research 的用户，需要以 search 和 fetch 形式调用同一套文档检索与读取能力时。
这个 Agent 有哪些优点和局限？
- 通过 MCP 会话搜索轨迹抑制相似查询的重复结果。
- 读取页面时会依据搜索历史过滤不相关章节，并将返回内容控制在最相关的约 5,000 个 token。
- 同时提供推荐的 Streamable HTTP 接入和遗留的本地 stdio 接入。
- 针对 OpenAI deep research 提供明确的 search/fetch 命名映射。
- 使用 HTTP 或 stdio 配置都需要注册并提供 Ref API key。
- 仓库将 stdio 服务标为 legacy，采用该模式的用户需承担迁移到 HTTP 模式的可能性。
- 私有仓库和 PDF 的搜索虽被提及，但仓库未说明授权配置、支持范围或访问控制细节。
- 仓库未提供定价、配额、可用性或失败重试策略的说明。
如何安装或部署这个 Agent？
推荐使用 Streamable HTTP 配置，并先注册获取 Ref API key：
"Ref": {
"type": "http",
"url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
}
本地 stdio 模式可配置为：
"Ref": {
"command": "npx",
"args": ["ref-tools-mcp@latest"],
"env": {
"REF_API_KEY": "<sign up to get an api key>"
}
}
本地开发仓库时可运行 npm install，然后 npm run build；开发自动重建可运行 npm run watch。
如何使用这个 Agent？
配置完成后，在 MCP 客户端调用 ref_search_documentation，并提供必填的 query，例如“Figma API post comment endpoint documentation”。从搜索结果中选择 URL，再调用 ref_read_url，并提供必填的 url。若通过 OpenAI 客户端使用 deep research 工具定义，则调用 search(query) 和 fetch(id)。
这个 Agent 与同类方案有什么区别？
仓库将其读取策略与标准 fetch() 网页抓取对比：后者在大型文档页上可能把 20,000+ token 带入上下文；Ref 说明会按会话搜索历史筛选相关章节，并返回最相关的约 5,000 个 token。