Ref MCP Server

官方

为你的编码助手提供最新文档，覆盖数千个公共仓库和网站。由 ref.tools 构建。

GitHub
1.1k

文档

Documentation for your agent smithery badge Website License npm version

Ref MCP

一个 ModelContextProtocol 服务器，让你的 AI 编程工具或智能体能够访问 API、服务、库等文档。它是让你的智能体以快速且节省 token 的方式获取最新文档的一站式解决方案。

更多信息请参阅 ref.tools

智能体搜索，精准定位上下文

Ref 的工具旨在匹配模型的搜索方式，同时使用尽可能少的上下文来减少 上下文腐化。其目标是精准找到你的编程智能体成功所需的上下文，同时使用最少的 token。

根据提示的复杂程度，像 Claude Code 这样的 LLM 编程智能体通常会进行一次或多次搜索，然后选择一些资源进行深入阅读。

对于一个关于 Figma 评论 REST API 的简单查询，它会进行几次调用来获取所需内容：

SEARCH 'Figma API post comment endpoint documentation' (54 tokens)
READ https://www.figma.com/developers/api#post-comments-endpoint (385 tokens)

对于更复杂的情况，LLM 会在阅读结果时尝试优化其提示。例如：

SEARCH 'n8n merge node vs Code node multiple inputs best practices' (126)
READ https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.merge/#merge (4961)
READ https://docs.n8n.io/flow-logic/merging/#merge-data-from-multiple-node-executions (138)
SEARCH 'n8n Code node multiple inputs best practices when to use' (107)
READ https://docs.n8n.io/code/code-node/#usage (80)
SEARCH 'n8n Code node access multiple inputs from different nodes' (370)
SEARCH 'n8n Code node $input access multiple node inputs' (372)
READ https://docs.n8n.io/code/builtin/output-other-nodes/#output-of-other-nodes (2310)

Ref 利用 MCP 会话来跟踪搜索轨迹并最小化上下文使用。还有很多想法正在酝酿中，但以下是我们目前已经实现的功能。

1. 过滤搜索结果

对于会话中重复的相似搜索，Ref 绝不会返回重复的结果。传统上，你需要通过翻到下一页结果来深入挖掘，但这种方法允许智能体在翻页的同时调整提示。

2. 获取页面中重要的部分

当阅读文档页面时，Ref 会利用智能体的会话搜索历史，丢弃不太相关的部分，并返回最相关的 5k token。这有助于 Ref 避免标准 fetch() 网页抓取的一个大问题，即当它遇到一个大型文档页面时，你很容易将 20k+ token 拉入上下文，其中大部分都是无关的。

为什么最小化文档上下文中的 token 很重要？

1. 更多上下文会让模型变笨

有充分记录表明，截至 2025 年 7 月，当你输入更多 token 时，模型会变得更笨。你可能听说过现在模型在处理长上下文方面表现出色，这在一定程度上是对的，但并非全貌。想快速了解一些研究，请观看 Chroma 团队的这段视频。

2. Token 花费金钱

想象一下，你正在使用 Claude Opus 作为后台智能体，你首先让智能体拉取文档上下文，假设它拉取了 10000 token 的上下文，其中 4000 是相关的，6000 是额外的噪音。按 API 定价，那 6k token 每步大约花费 0.09 美元。如果一个提示最终在 Opus 上执行了 11 步，你就白白花费了 1 美元。

设置

将 Ref 设置为 MCP 服务器有两种选择，通过 streamable-http 服务器（推荐）或本地 stdio 服务器（旧版）。

此仓库包含旧版 stdio 服务器。

Streamable HTTP（推荐）

Install Ref MCP in Cursor

"Ref": {
  "type": "http",
  "url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
}

stdio

Install Ref MCP in Cursor (stdio)

"Ref": {
  "command": "npx",
  "args": ["ref-tools-mcp@latest"],
  "env": {
    "REF_API_KEY": <sign up to get an api key>
  }
}

工具

Ref MCP 服务器为你的智能体需求提供了所有与文档相关的工具。

ref_search_documentation

一个强大的搜索工具，用于查阅技术文档。非常适合查找事实或代码片段。可用于搜索网络或 GitHub 上的公共文档，以及来自私有资源（如仓库和 PDF）的文档。

参数：

  • query（必需）：用于搜索相关文档的查询。这应该是一个完整的句子或问题。

ref_read_url

一个工具，用于从 URL 获取内容并将其转换为 markdown，以便使用 Ref 轻松阅读。当与返回相关内容 URL 的 ref_search_documentation 工具结合使用时，此工具功能强大。

参数：

  • url（必需）：要读取的网页的 URL。

OpenAI 深度研究支持

Ref 可用作深度研究的来源。OpenAI 需要特定的工具定义，因此当与 OpenAI 客户端一起使用时，Ref 将提供相同的工具，但命名略有不同。

ref_search_documentation(query) -> search(query)
ref_read_url(url) -> fetch(id)

开发

npm install
npm run dev

使用 Inspector 运行

出于开发和调试目的，你可以使用 MCP Inspector 工具。Inspector 提供了一个可视化界面，用于测试和监控 MCP 服务器交互。

请访问 Inspector 文档 获取详细的设置说明。

要在本地使用 Inspector 进行测试：

npm run inspect

或者同时运行监视器和 inspector：

npm run dev

本地开发

  1. 克隆仓库
  2. 安装依赖项：
npm install
  1. 构建项目：
npm run build
  1. 用于自动重新构建的开发模式：
npm run watch

许可证

MIT