ref-tools-mcp

Ref MCP

一个 ModelContextProtocol 服务，可让你的 AI 编码工具或 Agent 访问 API、服务、库等的文档。它是你的一站式解决方案，能以快速且节省 Token 的方式，让你的 Agent 随时掌握最新文档。

了解更多信息，请访问 ref.tools

面向 Agent 的搜索，精准找到所需上下文

Ref 的工具旨在匹配模型的搜索方式，同时尽可能减少上下文使用量，从而减少上下文腐化。目标是在使用最少 Token 的情况下，精准找到编码 Agent 成功完成任务所需的上下文。

根据提示词的复杂程度，Claude Code 等大模型编码 Agent 通常会进行一次或多次搜索，然后挑选一些资源进行更深入的阅读。

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

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

对于更复杂的情况，大模型会在阅读结果时尝试完善提示词。例如：

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 绝不会返回重复结果。传统方式是通过翻到下一页来深入查看搜索结果，而这种方式让 Agent 可以在翻页的同时调整提示词。

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

阅读文档页面时，Ref 会利用 Agent 会话中的搜索历史，剔除相关性较低的部分，并返回最相关的 5k Token。这能帮助 Ref 避免标准 fetch() 网页抓取中的一个大问题：遇到大型文档页面时，很容易将 20k+ Token 加载到上下文中，其中大部分内容都无关紧要。

为什么尽量减少文档上下文中的 Token 很重要？

1. 上下文越多，模型越笨

有充分的文档表明，截至 2025 年 7 月，模型输入的 Token 越多，表现就越差。你可能听说过模型现在很擅长处理长上下文，这在一定程度上是事实，但并非全貌。想快速了解相关研究，可以观看 Chroma 团队的这段视频。

2. Token 要花 $$$

假设你将 Claude Opus 用作后台 Agent，并让它先加载文档上下文，再假设它加载了 10000 个 Token 的上下文，其中 4000 个相关，6000 个是多余的噪声。按 API 定价，这 6k 个 Token 每一步就要花约 $0.09。如果一个提示词让 Opus 最终执行 11 步，你就白白花了 $1。

设置

设置 Ref MCP 服务有两种方式：通过 streamable-http 服务（推荐），或本地 stdio 服务（旧版）。

此仓库包含旧版 stdio 服务。

Streamable 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": <sign up to get an api key>
  }
}

工具

Ref MCP 服务提供了满足 Agent 需求的各种文档相关工具。

ref_search_documentation

一个强大的搜索工具，可用于查找技术文档中的事实或代码片段。既可搜索网络或 GitHub 上的公开文档，也可搜索仓库和 PDF 等私有资源。

参数：

• query（必填）：用于搜索相关文档的查询内容。应为完整的句子或问题。

ref_read_url

一个工具，可从 URL 获取内容并将其转换为 Markdown，方便使用 Ref 阅读。与 ref_search_documentation 工具搭配使用时功能强大，该工具会返回相关内容的 URL。

参数：

• 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