ref-tools/ref-tools-mcp
Helping coding agents never make mistakes working with public or private libraries without wasting the context window.
Ref MCP – 用于文档查询的 Model-Context-Protocol 服务器
它是什么 – Ref MCP 是一个实现了 Model Context Protocol (MCP) 的小型 Node-JS 服务。它让基于 LLM 的编码助手（例如 Claude Code、Cursor）仅能获取 API 或库文档中真正需要的部分，从而保持较低的 Token 数量并降低成本。
为什么重要 – 当代理在网上搜索函数签名或使用示例时，原始 HTML 可能会达到数万个 Token。将所有内容喂给模型会浪费上下文、增加模型推理的噪声，并提高 API 成本。Ref MCP 通过以下方式解决此问题：
- 搜索优先 – 代理使用自然语言查询调用
ref_search_documentation。Ref 会返回一个匹配的简短 URL 列表。 - 选择性读取 – 代理随后调用
ref_read_url。Ref 会利用会话的搜索记录将页面修剪为最相关的约 5k 个 Token，并舍弃不相关的部分。 - 会话感知 – 同一个 MCP 会话中的重复搜索会被去重，且服务器会记住页面中哪些部分已经被读取，进一步减少 Token 浪费。
通过 MCP 公开的核心工具
| 工具 | 用途 | 参数 |
|---|---|---|
ref_search_documentation (别名 search) |
对公开文档、GitHub repos、PDF 等进行全文搜索 | query – 描述代理需求的句子或问题 |
ref_read_url (别名 fetch) |
获取 URL 并返回经过 Markdown 处理且筛选过相关性的片段 | url – 要读取的页面 |
如何运行
- Streamable-HTTP 服务器 (推荐) – 将服务器部署于
https://api.ref.tools/mcp，并通过简单的 JSON 配置将您的代理指向它。 - 传统 stdio 服务器 – 使用
npx ref-tools-mcp@latest在本地运行。存储库中包含此模式的代码。
两种模式都需要从 ref.tools 获取的 API 密钥 (REF_API_KEY)。
典型工作流程示例
Agent: SEARCH "Figma API post comment endpoint documentation"
Ref MCP → 返回 Figma 文档 URL (≈54 tokens)
Agent: READ https://www.figma.com/developers/api#post-comments-endpoint
Ref MCP → 仅返回描述该端点的 385-token 片段
对于更复杂的查询，代理可以交替进行额外的搜索与读取，Ref 会记住会话状态以避免重复结果。
开发与调试
npm run dev– 启动具备热重载功能的服务器。npm run inspect– 启动 MCP Inspector UI 进行工具调用的可视化测试。- 提供标准 Node 脚本 (
build,watch等)。
授权 – MIT，因此您可以自由地将此服务器嵌入或修改到您自己的 AI 工具堆栈中。
总结 – Ref MCP 是 LLM 代理与不断增长的技术文档海洋之间实用且具备 Token 效率的桥梁，让代理在不被无关文字淹没的情况下保持最新状态。
相关
- 项目
- 项目
- 项目
- 项目