Ref MCP
为编程助手按需检索并提取技术文档，减少无关上下文。
- Star 数
- ★ 1.2k
- 最近更新
- 9 天前
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 49/100 · 缺口较多
30 秒速览
- 可在哪里用
- 通用 · 跨平台OpenAI API
- 开始前需要
- 典型场景
- 使用 Claude Code 的开发者需要查询 Figma Comment REST API 的具体端点时，可先搜索再读取对应文档页面。
- 主要局限
- 使用 HTTP 或 stdio 配置都需要注册并提供 Ref API key。
这个 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？
推荐使用 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 有哪些优点和局限？
- 通过 MCP 会话搜索轨迹抑制相似查询的重复结果。
- 读取页面时会依据搜索历史过滤不相关章节，并将返回内容控制在最相关的约 5,000 个 token。
- 同时提供推荐的 Streamable HTTP 接入和遗留的本地 stdio 接入。
- 针对 OpenAI deep research 提供明确的 search/fetch 命名映射。
- 使用 HTTP 或 stdio 配置都需要注册并提供 Ref API key。
- 仓库将 stdio 服务标为 legacy，采用该模式的用户需承担迁移到 HTTP 模式的可能性。
- 私有仓库和 PDF 的搜索虽被提及，但仓库未说明授权配置、支持范围或访问控制细节。
- 仓库未提供定价、配额、可用性或失败重试策略的说明。
这个 Agent 与同类方案有什么区别？
仓库将其读取策略与标准 fetch() 网页抓取对比：后者在大型文档页上可能把 20,000+ token 带入上下文；Ref 说明会按会话搜索历史筛选相关章节，并返回最相关的约 5,000 个 token。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|
| Ref MCP 当前 | 49 · 缺口较多 | ★ 1.2k | 9 天前 | TypeScript | OpenAI API |
| pg-aiguide：PostgreSQL 智能助手 | 33 · 缺口较多 | ★ 1.8k | 15 天前 | Python | ChatGPT · Codex · Claude Code |
| Grounded Docs MCP 服务器 | 50 · 缺口较多 | ★ 1.8k | 2 天前 | TypeScript | ChatGPT · Claude Code |
| Ori Mnemos | 80 · 表现良好 | ★ 324 | 4 天前 | TypeScript | Claude Code · OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：工具仅需API密钥，无额外权限声明；README说明数据流向（搜索、读取URL）；依赖仅axios等常见库；有外部网络请求（搜索、读取URL）。扣分：无用户确认机制、无回滚机制、无明确数据保留策略、发布者未验证。
证据显示：README与package.json一致，工具名称一致；依赖为npm包，有版本范围；无错误处理文档。扣分：无失败消息示例，无错误处理说明。
证据显示：明确目标用户（AI编码代理），场景（文档搜索、读取）；工具参数明确；支持stdio和HTTP传输。扣分：未说明环境限制（如网络要求）。
证据显示：README结构清晰，安装说明详细，命名稳定（ref_search_documentation等），有示例，MIT许可证，版本号存在。扣分：无已知限制章节，无变更日志，维护责任不明确。
证据显示：输出为markdown，可直接使用；价值在于减少token消耗；成本效益有说明（token成本）。扣分：无实际性能数据。
证据显示：README中的声明（如token效率）无外部引用；无测试或独立验证。扣分：无测试，无外部佐证。
- 源码中未见：执行前用户确认开启或自行加上执行前确认；先在沙箱或测试环境跑通，确认行为后再接入真实数据。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 发布者身份未验证，需谨慎使用。
- 工具会发起外部网络请求，可能泄露查询内容，需注意数据隐私。
- 无用户确认机制，代理可能自动执行搜索和读取操作。