Ref MCP

一个 ModelContextProtocol 服务器，它使您的AI编码工具或代理能够访问API、服务、库等的文档。它是您一站式更新代理文档的快速且令牌高效的解决方案。

更多信息请参见 ref.tools

针对特定上下文的代理搜索

Ref 的工具旨在匹配模型在搜索时使用尽可能少的上下文以减少 上下文腐化。目标是找到您的编码代理成功所需的确切上下文，同时使用最少的令牌。

根据提示的复杂性，像 Claude Code 这样的LLM编码代理通常会进行一次或多次搜索，然后选择几个资源进行更深入的阅读。

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

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

对于更复杂的场景，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 个令牌。这有助于 Ref 避免标准 fetch() 网页抓取的一个大问题：当遇到大型文档页面时，很容易将 20k+ 个令牌拉入上下文中，其中大部分都是无关紧要的。

为什么最小化来自文档上下文的令牌很重要？

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

众所周知，截至2025年7月，随着您输入更多令牌，模型会变得更笨。您可能听说过模型现在擅长处理长上下文，这在某种程度上是正确的，但并不是全部。为了快速了解一些研究，请查看 Chroma 团队的这段视频。

2. 令牌成本$$$

想象一下，您正在使用 Claude Opus 作为后台代理，并让代理从文档上下文中获取信息，假设它拉入了10000个令牌的上下文，其中有4000个是相关的，而6000个是多余的噪音。按API定价，这6k个令牌每步大约花费$0.09。如果一个提示最终需要11步，那么您就白白花费了$1。

设置

有两种方法可以设置 Ref 作为 MCP 服务器，一种是通过流式 HTTP 服务器（推荐），另一种是本地 stdio 服务器（遗留）。

此仓库包含遗留 stdio 服务器。

流式 HTTP（推荐）

"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": <注册以获取 API 密钥>
  }
}

工具

Ref MCP 服务器提供了所有与文档相关的工具，满足您的代理需求。

ref_search_documentation

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

参数：

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

ref_read_url

一个工具，从 URL 获取内容并将其转换为 Markdown 格式以便于阅读。当与返回相关内容 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

3. 构建项目：

npm run build

4. 开发时自动重建：

npm run watch

许可证

MIT