R2r Ultra MCP Server

R2R FastMCP服务器

FastMCP服务器为R2R API集成提供工具。使用斜线命令进行1对1映射 .claude/commands/.

特性

8个MCP工具

1. r2r_search -混合搜索（语义+全文）
2. r2r_rag -生成RAG查询
3. r2r代理 -多回合代理对话
4. r2r_collections_list/create/get -收藏管理
5. r2r_upload -文档上传
6. r2r_示例 -交互式示例目录
7. r2r工作流 -自动化工作流程
8. r2r_quick -快速单行任务

安装

# Install dependencies with uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .

配置

创建 .env 项目根目录中的文件：

R2R_BASE_URL=http://localhost:7272  # Your R2R instance URL
API_KEY=your_api_key_here            # R2R API key

在Cursor中安装

步骤1：安装依赖项

cd /Users/laptop/dev/r2r-fastmcp/mcp-server
uv sync
# or
pip install -e .

步骤2：配置MCP服务器

打开光标设置(Cmd + ,) → 搜索“MCP”→ 点击“在settings.json中编辑”

或手动编辑 ~/.cursor/settings.json:

{
  "mcpServers": {
    "r2r": {
      "command": "python",
      "args": ["/Users/laptop/dev/r2r-fastmcp/mcp-server/server.py"],
      "env": {
        "R2R_BASE_URL": "{{R2R_BASE_URL}}",
        "API_KEY": "{{API_KEY}}"
      }
    }
  }
}

步骤3：设置环境变量

创建 ~/.cursor/.env 或添加到您的shell配置文件中：

export R2R_BASE_URL=http://localhost:7272
export API_KEY=your_api_key_here

步骤4：重新启动游标

关闭并重新打开Cursor以加载MCP服务器。

步骤5：验证安装

在光标聊天中，键入 @ 你应该看看 r2r 配备可用工具的MCP服务器。

部署

💡 快速开始：参见 QUICK_DEPLOY.md 3分钟的云部署！

针对不同用例的多种部署选项。

快速选项

🚀 FastMCP云（推荐）

部署到生产中 3个步骤 通过自动HTTPS、监控和GitHub集成：

1. 将代码推送到GitHub
2. 访问 fastmcp.cloud 并连接您的仓库
3. 配置入口点： mcp-server/server.py:mcp

结果：您的服务器位于 https://your-project.fastmcp.app/mcp ✅

特性:

• ✅ 个人免费使用
• ✅ 自动HTTPS和SSL
• ✅ git推送自动重新部署
• ✅ 内置监控仪表板
• ✅ 环境变量管理
• ✅ PR预览部署

📚 完整指南: FASTCMP_CLOUD_DEPLOY.md

快速入门：本地HTTP/SSE服务器

对于自托管部署：

cd /Users/laptop/dev/r2r-fastmcp/mcp-server

# Run server with HTTP/SSE transport
python server.py --transport sse --port 8000

# Or with fastmcp CLI
fastmcp run server.py --transport sse --port 8000

# Access at: http://localhost:8000/sse

从游标连接（远程）

{
  "mcpServers": {
    "r2r-cloud": {
      "url": "https://your-project.fastmcp.app/mcp",
      "transport": "sse"
    }
  }
}

或者对于自托管：

{
  "mcpServers": {
    "r2r-remote": {
      "url": "http://your-server:8000/sse",
      "transport": "sse"
    }
  }
}

完整部署指南

☁️ FASTCMP_CLOUD_DEPLOY.md -零配置云部署：

• 使用GitHub逐步设置
• 环境变量配置
• 自动重新部署工作流
• 监控和指标
• PR预览部署
• 常见问题解答和故障排除

🔧 部署.md -自托管部署：

• Docker&Docker编写
• 系统化服务配置
• 带SSL的Nginx反向代理
• 环境变量最佳实践
• 监控和日志记录
• 安全强化
• 更新策略
• 故障排除指南

用法

运行MCP服务器（独立）

# Stdio transport
python server.py

# Or with fastmcp CLI
fastmcp run server.py

在Claude桌面中配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "r2r": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-server/server.py"],
      "env": {
        "R2R_BASE_URL": "http://localhost:7272",
        "API_KEY": "your_api_key_here"
      }
    }
  }
}

工具示例

搜索

# Basic search
result = await r2r_search("machine learning", limit=3)

# Collection-specific search
result = await r2r_search(
    "neural networks",
    limit=5,
    collection_id="col_abc123"
)

RAG查询

# Simple question
answer = await r2r_rag("What is FastMCP?", max_tokens=1000)

# Detailed analysis
answer = await r2r_rag(
    "Explain transformer architecture in detail",
    max_tokens=8000
)

Agent会话

# Initial query
response = await r2r_agent(
    "Research AI safety implications",
    mode="research"
)

# Follow-up
response = await r2r_agent(
    "Tell me more about alignment",
    conversation_id=response["conversation_id"]
)

# With extended thinking
response = await r2r_agent(
    "Deep analysis required",
    mode="research",
    enable_thinking=True
)

集合

# List collections
collections = await r2r_collections_list(limit=10)

# Create collection
collection = await r2r_collections_create(
    "AI Research",
    "Papers about artificial intelligence"
)

# Get collection details
details = await r2r_collections_get("col_abc123")

快速任务

# Quick search + RAG answer
result = await r2r_quick("ask", query="What is RAG?")

# System status
status = await r2r_quick("status")

# Quick collection create
col = await r2r_quick("col", name="Test", description="Test collection")

工作流

# Research workflow with extended thinking
result = await r2r_workflows(
    "research",
    query="Analyze quantum computing implications"
)

# Create collection workflow
result = await r2r_workflows(
    "create-collection",
    name="Research Papers",
    description="Academic papers"
)

映射到Slash命令

使用的API端点

• 搜索： POST /v3/retrieval/search
• 抹布： POST /v3/retrieval/rag
• 代理人： POST /v3/retrieval/agent
• 收藏列表： GET /v3/collections
• 集合创建： POST /v3/collections
• 收藏获得： GET /v3/collections/{id}
• 文档创建： POST /v3/documents/create

发展

运行测试

pytest

棉绒和格式

ruff check .
ruff format .

建筑

┌─────────────────┐
│  Claude Code    │  Uses MCP tools
│   (Client)      │  via MCP protocol
└────────┬────────┘
         │ MCP stdio
┌────────▼────────┐
│  FastMCP Server │  8 @mcp.tool decorators
│  (server.py)    │  Map to R2R API
└────────┬────────┘
         │ HTTP + JSON
┌────────▼────────┐
│      R2R        │  v3 API endpoints
│   (Backend)     │  /v3/retrieval/*
└─────────────────┘

比较：Bash与MCP

之前（Bash脚本）

# Requires shell execution
.claude/scripts/r2r search "query" --limit 3

# Output: text parsing needed

之后（MCP工具）

# Native function call
result = await r2r_search("query", limit=3)

# Output: structured JSON

MCP的好处

1. 类型安全： Python类型提示、JSON模式
2. 错误处理： 适当的例外、验证
3. 集成： Claude中的原生工具调用
4. 异步支持： 非阻塞I/O
5. 可组合性： 工具可以调用其他工具
6. 测试： 每个工具的单元测试
7. 文档： 从文档字符串自动生成

许可证

麻省理工学院