项目介绍
技术文档摘要
Cloudflare AutoRAG MCP 服务器
这是一个提供 Cloudflare AutoRAG 实例搜索功能的模型上下文协议（MCP）服务器。该服务器使像 Claude 这样的AI助手能够通过三种不同的搜索方法直接搜索和查询您的 AutoRAG 知识库。
功能
- 🔍 基础搜索 - 不进行查询重写或答案生成的向量相似度搜索
- ✏️ 重写搜索 - 带有AI查询重写的向量搜索，但不生成答案（仅返回文档片段）
- 🤖 AI 搜索 - 完全由AI驱动的搜索，可选AI响应和可配置的查询重写
- ⚙️ 可配置参数 - 支持
score_threshold（默认：0.5）和max_num_results（1-50，默认：10） - 📄 分页支持 - AI 搜索支持基于游标的分页以处理大量结果集（v1.2.0+）
- 🏢 多AutoRAG支持 - 管理并跨多个 AutoRAG 实例搜索（v2.0.0+）
- 🌐 远程部署 - 在 Cloudflare Workers 上运行以实现可扩展性
- 🔗 MCP 兼容 - 与 Claude Desktop 和其他 MCP 客户端兼容
工具
autorag_basic_search
在您的 Cloudflare AutoRAG 索引中执行基本的向量相似度搜索，不进行AI查询重写或答案生成。仅返回原始文档片段。
参数：
query(字符串，必需) - 搜索查询文本（最大10,000字符）score_threshold(数字，可选) - 最小相似度分数阈值（0.0-1.0，默认：0.5）max_num_results(数字，可选) - 返回的最大结果数（1-50，默认：10）autorag_name(字符串，可选) - 要使用的 AutoRAG 实例名称（默认为已配置的默认实例）
autorag_rewrite_search
执行带有AI查询重写的向量搜索，但不生成答案。使用 Cloudflare 的 search() 方法，并通过可配置的 rewrite_query 来提高语义匹配度，仅返回文档片段。
参数：
query(字符串，必需) - 搜索查询文本（最大10,000字符）score_threshold(数字，可选) - 最小相似度分数阈值（0.0-1.0，默认：0.5）max_num_results(数字，可选) - 返回的最大结果数（1-50，默认：10）rewrite_query(布尔值，可选) - 是否重写查询以获得更好的匹配（默认：true）autorag_name(字符串，可选) - 要使用的 AutoRAG 实例名称（默认为已配置的默认实例）
autorag_ai_search
使用 Cloudflare 的 aiSearch() 方法执行由AI驱动的搜索，可选AI生成的响应。返回文档片段，并根据 include_ai_response 参数可选地返回AI答案。支持对大量结果集的分页。
参数：
query(字符串，必需) - 搜索查询文本（最大10,000字符）score_threshold(数字，可选) - 最小相似度分数阈值（0.0-1.0，默认：0.5）max_num_results(数字，可选) - 返回的最大结果数（1-50，默认：10）rewrite_query(布尔值，可选) - 是否重写查询以获得更好的语义匹配（默认：true）include_ai_response(布尔值，可选) - 是否在输出中包含AI生成的回答（默认：false）cursor(字符串，可选) - 从上一个响应获取的分页游标，用于获取下一页的结果（v1.2.0+）autorag_name(字符串，可选) - 要使用的 AutoRAG 实例名称（默认为已配置的默认实例）
响应包括：
data- 包含分数和元数据的源文档片段数组（始终包含）response- 根据检索到的文档生成的AI回答（仅当include_ai_response: true时）has_more- 表示是否还有更多结果的布尔值next_page- 当has_more为真时用于获取下一页的游标令牌nextCursor- 符合 MCP 规范的游标字段（反映next_page的值）
list_autorags (v2.0.0+)
列出服务器中配置的所有可用 AutoRAG 实例。
参数： 无
响应包括：
autorags- 包含名称、描述和默认标志的 AutoRAG 实例数组total- 配置的 AutoRAG 实例总数default- 默认 AutoRAG 实例的名称
get_current_autorag (v2.0.0+)
获取当前配置的默认 AutoRAG 实例的信息。
参数： 无
响应包括：
current_autorag- 当前默认 AutoRAG 实例的名称description- 实例的描述is_default- 对于此端点始终为真
部署前提条件
- Cloudflare 账户，具有 AutoRAG 访问权限
- AutoRAG 实例 - 在您的 Cloudflare 账户中创建并索引
- Wrangler CLI - 用于部署 (
npm install --save-dev wrangler)
部署
-
克隆仓库：
git clone <repository-url> cd cf-autorag-mcp -
安装依赖项：
npm install -
配置您的 AutoRAG 实例： 编辑
wrangler.toml并更新配置：对于单个 AutoRAG 实例：
[vars] AUTORAG_NAME = "your-autorag-instance-name"对于多个 AutoRAG 实例：
[vars] AUTORAG_INSTANCES = "instance1,instance2,instance3" AUTORAG_DESCRIPTIONS = "Description 1,Description 2,Description 3" -
部署到 Cloudflare Workers：
npx wrangler deploy这将输出您的 Worker URL，您需要将其用于 MCP 客户端配置。
Claude Desktop 配置
要使用此 MCP 服务器与 Claude Desktop，需在您的 Claude Desktop 配置文件中添加以下配置：
macOS
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：
Windows
编辑 %APPDATA%/Claude/claude_desktop_config.json：
配置
{
"mcpServers": {
"cf-autorag-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-worker-url.workers.dev/"
]
}
}
}
替换 https://your-worker-url.workers.dev/ 为您实际部署的 Worker URL。
更新配置后：
- 重启 Claude Desktop
- 您应在对话中看到 AutoRAG 搜索工具
配置
环境变量
服务器使用以下 Cloudflare Worker 绑定：
AI- Cloudflare AI 绑定，用于 AutoRAG 访问（处理所有 AutoRAG 操作）AUTORAG_NAME- 您的 AutoRAG 实例名称（对于单实例配置）AUTORAG_INSTANCES- 多个 AutoRAG 实例的逗号分隔列表（对于多实例配置）AUTORAG_DESCRIPTIONS- 每个实例的描述的逗号分隔列表
Wrangler 配置
wrangler.toml 文件包括：
name = "cf-autorag-mcp"
main = "src/server.ts"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]
[vars]
# 对于单个 AutoRAG 实例：
AUTORAG_NAME = "your-autorag-instance-name"
# 对于多个 AutoRAG 实例（v2.0.0+）：
# AUTORAG_INSTANCES = "default-autorag,secondary-autorag,specialized-autorag"
# AUTORAG_DESCRIPTIONS = "Main knowledge base,Secondary knowledge base,Specialized documents"
[ai]
binding = "AI"
注意： 不需要 VECTORIZE 绑定。AutoRAG 通过 AI 绑定内部管理其自己的向量索引访问。
使用示例
配置好与 Claude Desktop 后，您可以这样使用这些工具：
基础搜索（无查询重写，无AI响应）：
在 AutoRAG 中搜索关于“机器学习”的文档，最小分数阈值为0.7
重写搜索（AI查询重写，无AI响应）：
使用重写搜索查找“部署策略”信息，启用查询重写
AI 搜索仅带文档片段（默认行为）：
使用AI搜索查找“部署策略”信息，最多返回5个结果
AI 搜索带AI生成的响应：
使用AI搜索查找“部署策略”信息，并包含AI生成的响应
多AutoRAG 使用（v2.0.0+）：
列出所有可用的 AutoRAG 实例
在 secondary-autorag 实例中搜索“安全政策”
在 specialized-autorag 中使用AI搜索查找“合规要求”，并包含AI响应
重要提示：
autorag_basic_search执行纯向量搜索，没有AI增强autorag_rewrite_search使用AI查询重写，但仅返回文档片段autorag_ai_search默认仅返回文档片段（让客户端LLM生成响应），但可以选择包含Cloudflare的AI生成的响应- 如果未指定，所有工具都使用默认分数阈值0.5
- 所有工具支持相同的参数结构，以便一致使用
- 元数据过滤不受 Workers 绑定支持 - 如需过滤查询，请使用 REST API
开发
本地开发
# 启动本地开发服务器
npm run dev
# 构建生产版本
npm run build
项目结构
cf-autorag-mcp/
├── src/
│ └── server.ts # 主 MCP 服务器实现
├── wrangler.toml # Cloudflare Workers 配置
├── package.json # 依赖项和脚本
└── README.md # 本文档
技术细节
- 协议：HTTP 上的 JSON-RPC 2.0
- 运行时：具有 Node.js 兼容性的 Cloudflare Workers
- MCP 版本：2024-11-05
- 传输：基于 HTTP（无流式传输）
- 默认分数阈值：所有搜索工具均为0.5
- 参数验证：全面验证，附带清晰的错误消息
故障排除
常见问题
-
“AutoRAG 实例未找到”
- 验证您的
AUTORAG_NAME在wrangler.toml中 - 确保您的 AutoRAG 实例已正确创建并索引
- 验证您的
-
“MCP 服务器断开连接”
- 检查 Claude Desktop 配置中的 Worker URL 是否正确
- 确认 Worker 已部署且可访问
-
“工具未找到” 错误
- 在配置更改后重启 Claude Desktop
- 检查 Worker 日志：
npx wrangler tail
-
空搜索结果
- 尝试降低
score_threshold参数（默认为0.5） - 确保您的 AutoRAG 索引已填充文档
- 检查查询词是否存在于索引内容中
- 尝试降低
日志
查看已部署 Worker 的实时日志：
npx wrangler tail
版本历史
- v2.0.0 - 多AutoRAG支持，增强的模式文档，移除VECTORIZE绑定
- v1.2.0 - 为AI搜索工具添加基于游标的分页支持
- v1.1.3 - 移除过滤器参数（不受 Workers 绑定支持），为过滤尝试添加有用的错误消息
- v1.1.2 - 尝试修复过滤器格式（发现 Workers 绑定不支持过滤器）
- v1.1.1 - 为AI搜索工具添加
include_ai_response参数，设置默认分数阈值为0.5，全面参数验证 - v1.1.0 - 添加三个不同的搜索工具，支持布尔参数
- v1.0.0 - 初始发布
许可
本项目采用 MIT 许可证。
贡献
- 分叉仓库
- 创建功能分支
- 进行更改
- 彻底测试
- 提交拉取请求
支持
针对以下问题：
- Cloudflare AutoRAG：Cloudflare AutoRAG 文档
- 模型上下文协议：MCP 文档
- 此服务器：在此仓库中打开一个问题