作者 ref-tools · ref-tools/ref-tools-mcp
帮助编码 Agent 快速找到正确的文档 — 公开库、私有仓库、内部 PDF — 不浪费 context 在错误的页面上。
ref-tools/ref-tools-mcp（由 Ref 开发）提供两个工具：一个跨公网、GitHub 仓库和私有资源的精准文档搜索，以及一个返回 markdown 的 URL 读取工具。需要 REF_API_KEY。
%APPDATA%\Claude\claude_desktop_config.json{
"mcpServers": {
"ref-tools": {
"command": "npx",
"args": [
"-y",
"ref-tools-mcp"
],
"_inferred": true
}
}
}打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。
{
"mcpServers": {
"ref-tools": {
"command": "npx",
"args": [
"-y",
"ref-tools-mcp"
],
"_inferred": true
}
}
}Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。
{
"mcpServers": {
"ref-tools": {
"command": "npx",
"args": [
"-y",
"ref-tools-mcp"
],
"_inferred": true
}
}
}点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。
{
"mcpServers": {
"ref-tools": {
"command": "npx",
"args": [
"-y",
"ref-tools-mcp"
],
"_inferred": true
}
}
}格式与 Claude Desktop 相同。重启 Windsurf 生效。
{
"mcpServers": [
{
"name": "ref-tools",
"command": "npx",
"args": [
"-y",
"ref-tools-mcp"
]
}
]
}Continue 使用服务器对象数组，而非映射。
{
"context_servers": {
"ref-tools": {
"command": {
"path": "npx",
"args": [
"-y",
"ref-tools-mcp"
]
}
}
}
}加入 context_servers。Zed 保存后热重载。
claude mcp add ref-tools -- npx -y ref-tools-mcp一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。
何时使用： Agent 自信地写出与当前库版本不匹配的代码。
结果： 能针对真实库版本编译的代码。
何时使用： Agent 需要遵循公司特定的模式，而不是 StackOverflow 上的任意内容。
结果： 符合内部标准的输出。
何时使用： 你想要文章文本，不要导航/广告/JS 垃圾。
结果： 清晰的内容，快速获得。
用官方文档引用来支撑 PR 审查
结合 Ref 的文档搜索和 markdownify 处理 Ref 中未索引的本地 PDF
| 工具 | 输入参数 | 何时调用 | 成本 |
|---|---|---|---|
| ref_search_documentation | query: str, sources?: str[] | 基于库或内部文档回答问题 | 1 Ref API call |
| ref_read_url | url: str | 将页面转换为清晰 markdown | 1 Ref API call |
REF_API_KEY 存储在环境变量中不要广泛分享你的工作区密钥；如果 Ref 支持，使用每用户密钥401 Unauthorized缺少或无效的 REF_API_KEY。
echo $REF_API_KEY搜索返回过时结果私有源重新索引可能延迟；从 Ref 仪表板强制重新索引。
ref_read_url 返回空某些网站阻止爬取。使用 markdownify 中的 webpage-to-markdown 作为后备方案。
配额超出升级 Ref 计划或分散搜索使用。
| 替代方案 | 何时用它替代 | 权衡 |
|---|---|---|
| Context7 MCP | 你想要免费的公开库文档检索 | 没有私有源索引 |
| Apple Docs MCP / pg-aiguide | 你只关心特定平台的文档 | 范围受限；不是通用工具 |