Ref MCP

Ref MCP

Ref MCP 是一个模型上下文协议（MCP）服务器，旨在为 AI 代理和编码工具提供高效、实时的技术文档访问，涵盖 API、库和服务。它可以精确、节省令牌地检索文档上下文，从而增强代码理解和自动化。

Author: ref-tools


查看协议

什么是 Ref MCP？

Ref MCP 是一个专门的 MCP 服务器，连接编码代理和开发工具与精心策划的技术文档集合。它使代理能够按需搜索、检索和分析相关文档的部分，最小化令牌使用，提高处理 API 和库时的 LLM 性能。

如何配置 Ref MCP

有两种主要方法可以将 Ref MCP 设置为 MCP 服务器：

1. 可流式 HTTP（推荐）：

  • 通过支持的客户端（如 Cursor）使用提供的安装链接或直接指定服务器配置来安装 Ref MCP： 
    "Ref": {
  "type": "http",
  "url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
}
  • 您需要在 ref.tools 上注册以获取 API 密钥。

2. 本地 stdio 服务器（旧版）：

"Ref": {
  "command": "npx",
  "args": ["ref-tools-mcp@latest"],
  "env": {
    "REF_API_KEY": <your_api_key>
  }
}
  • 需要 Node.js 和 npm。

可选地，您可以克隆 Ref MCP 仓库，使用 npm install 安装依赖项，然后使用 npm run dev 进行本地开发和调试。

如何使用 Ref MCP

  1. 使用上述配置将支持 MCP 的代理或工具连接到 Ref MCP 服务器。
  2. 使用可用工具，如 ref_search_documentation 搜索 API 文档，或使用 ref_read_url 获取和提取相关文档内容。
  3. 代理可以进行迭代搜索和阅读，智能地减少上下文，仅保留生成代码或理解所需的信息。
  4. 对于 OpenAI 集成，Ref MCP 自动将其工具映射到 OpenAI 兼容的函数名称。

用于开发和检查，请使用 MCP Inspector 进行可视化测试和监控互动。

主要特点

  • 节省令牌的文档检索： 仅返回最相关的上下文部分，避免过高的令牌成本和性能下降。
  • 迭代、代理友好的搜索： 在会话中适应搜索结果，对相似提示不会重复结果。
  • 按需上下文补充： 使 LLM 在需要时准确提取文档。
  • 支持公开和私有资源： 在公共文档、网页、GitHub 和私有资源（如内部仓库或 PDF）中进行搜索。
  • 集成会话管理： 在代理会话内跟踪搜索和阅读轨迹，以获得最佳上下文策划。
  • 兼容 OpenAI： 自动调整工具命名，以便与 OpenAI 的研究和编码代理无缝使用。

使用案例

  • AI 驱动的代码助手： 使用精确的技术文档访问增强编码代理（如 Claude Desktop 或 Cursor）。
  • 自动化 API 集成： 帮助代理理解、实现和排除 API 端点的问题，提供最相关的文档。
  • 代码审查和审核机器人： 使代理能够在审查代码时提取和引用权威文档。
  • 开发者入职工具： 通过搜索和提取公司或公共文档中的信息，动态回答常见开发问题。
  • 深入技术研究： 高效地查询多个源，聚焦于最小的上下文集以获得准确答案。

常见问题

问1：为什么在文档上下文中最小化令牌很重要？
答1：LLM 在处理较大且嘈杂的上下文窗口时表现较差，而令牌是需要花钱的。通过只提取相关文档的部分，Ref MCP 提高了 LLM 性能，并减少了不必要的 API 支出。

问2：Ref MCP 可以搜索哪些类型的文档？
答2：Ref MCP 搜索广泛的公共文档（API、库、网页文档），也可以索引私有/内部资源，包括 GitHub 仓库和 PDF。

问3：Ref MCP 如何确保 LLM 代理避免重复阅读相同内容？
答3：在活动会话中，Ref MCP 跟踪以前的搜索和返回的结果，确保每个相似的搜索返回新的、非重复的文档，以促进有效的提示工程。

问4：我可以将 Ref MCP 与我自己的代理或工具一起使用吗？
答4：可以，任何支持 MCP 协议的代理或应用程序都可以通过 HTTP 或 stdio 模式与 Ref MCP 连接。

问5：ref_search_documentation 和 ref_read_url 之间有什么区别？
答5：ref_search_documentation 通过查询查找相关文档链接和上下文；ref_read_url 从目标页面获取并转换内容为 markdown 格式，以便代理轻松处理。