R2R MCP服务器
基于FastMCP模型上下文协议（MCP）的R2R API服务器，提供与文档、知识图和RAG管理系统的集成。
⚡ 重要：为了正确使用OpenAPI 3.1规范，建议启用实验性的FastMCP解析器。添加FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER=true在.env文件 。
机会
- 自动生成 OpenAPI规范中的MCP组件
- 语义路由：get操作为resources，post/put/delete为tools
- 认证：通过环境变量支持Bearer令牌
- 双重运输：stdio（用于Claude Desktop）和HTTP（用于开发/测试）
- 完全覆盖R2R API:
- Chunks管理（搜索、创建、更新、删除） - 文档管理（下载、导出、元数据） - 集合和访问权限 - 知识图（实体提取、演绎、社区建设） - 转换和通信
安装
1.克隆和环境配置
# Установка зависимостей через uv (рекомендуется)
uv venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
uv pip install -e .2.配置
创建 .env 基于文件 .env.example:
cp .env.example .env编辑 .env:
# Обязательные параметры
R2R_BASE_URL=http://localhost:7272
R2R_API_KEY=your_actual_api_key_here
# Рекомендуется: включить экспериментальный парсер (лучшая совместимость с OpenAPI 3.1)
FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER=true
# Опциональные параметры производительности
R2R_TIMEOUT=30.0 # Таймаут запросов (секунды)
DEBUG_LOGGING=false # Детальное логирование для отладки重要的是： .env文件中密钥API格式：
# ✅ ПРАВИЛЬНО - без кавычек, без "Bearer"
R2R_API_KEY=your_actual_api_key_here
# ❌ НЕПРАВИЛЬНО - с кавычками
R2R_API_KEY="your_actual_api_key_here"
# ❌ НЕПРАВИЛЬНО - со словом Bearer
R2R_API_KEY=Bearer your_actual_api_key_here代码在生成HTTP头时自动添加“bearer”。
性能优化：
- DEBUG_LOGGING=true -显示OpenAPI解析器和查询构建的详细信息
- 实验解析器 -自动用于100-200ms快速启动
使用
FastMCP Cloud（推荐）🚀
最简单的方法是把 FastMCP云:
- 入口点：
src/server.py:mcp - 环境变量： 添加您的R2R信用卡
- 身份验证： 启用安全
📖 详细说明： 部署.md
Claude Desktop（STDIO）
通过start.sh推荐 （自动导出.env变量）：
./start.sh
# или
make run或者 （需要手动导出变量）：
# Экспортируем переменные из .env
set -a && source .env && set +a
# Запускаем сервер
uv run python -m src.server启动HTTP服务器（用于开发）
通过start.sh推荐:
./start.sh http 8000
# или
make run-http或者:
# Экспортируем переменные из .env
set -a && source .env && set +a
# Запускаем HTTP сервер
uv run python -m src.server http 8000然后通过MCP客户端连接到 http://localhost:8000/mcp
与Claude Desktop集成
添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：
{
"mcpServers": {
"r2r": {
"command": "uv",
"args": [
"--directory",
"/path/to/fastmcp-r2r-openapi-integration",
"run",
"python",
"-m",
"src.server"
],
"env": {
"R2R_BASE_URL": "http://localhost:7272",
"R2R_API_KEY": "your_api_key_here"
}
}
}
}Route Maps架构
服务器使用语义路由来优化Endpoints的组织：
Resources（只读）
GET /v3/chunks/{id}→ 资源模板GET /v3/documents/{id}→ 资源模板GET /v3/documentsResource（列表）GET /health→ 资源
Tools（数据修改）
POST /v3/chunks/searchTool（搜索）POST /v3/documentsTool（创建）DELETE /v3/documents/{id}工具（Tool）POST /v3/documents/{id}/extractTool（实体提取）POST /v3/graphs/{collection_id}/communities/build工具（知识图）
使用示例
搜索文档
# Через MCP клиент
result = await client.call_tool("search_chunks", {
"query": "machine learning",
"limit": 5
})获取文件
# Как Resource
content = await client.read_resource("uri://r2r/documents/uuid-here")从文档中提取实体
# Tool для граф знаний
result = await client.call_tool("extract_entities_from_document", {
"id": "document-uuid"
})开发
Linting和格式化
# Проверка кода
uv run ruff check .
# Автоисправление
uv run ruff check --fix .
# Форматирование
uv run ruff format .更新OpenAPI规范
curl -o openapi.json http://localhost:7272/openapi.json建筑
类型化客户端（新）
项目使用 打字包装 在保持Serverless Compatibility的同时提供更好的DX方法：
# src/r2r_typed.py - Type-safe wrapper around httpx
from src.r2r_typed import R2RTypedClient
_client = httpx.AsyncClient(auth=DynamicBearerAuth())
r2r = R2RTypedClient(_client) # ← Typed wrapper
# Type-safe search with autocomplete
results = await r2r.search(
query="machine learning",
limit=10,
use_hybrid_search=True # ← IDE autocomplete!
)优点：
- ✅ 类型提示（IDE自动补全，mypy检查）
- ✅ DynamicBearerAuth（兼容无服务器）
- ✅ 减少样板
- ✅ 完全HTTP控制
见E/CN.4/Sub.2/2000/SR.1。: docs/R2R_CLIENT_ANALYSIS.md 对于细节。
项目结构
.
├── src/
│ ├── __init__.py
│ ├── server.py # Основной MCP сервер (использует R2RTypedClient)
│ ├── r2r_typed.py # Type-safe wrapper (NEW)
│ └── pipelines.py # Pipeline compositions
├── scripts/ # Standalone scripts с R2RClient (NEW)
│ ├── README.md # Документация scripts
│ ├── batch_ingest.py # Batch document upload
│ └── search_cli.py # Interactive search CLI
├── docs/
│ ├── R2R_CLIENT_ANALYSIS.md # R2RClient vs httpx analysis (NEW)
│ ├── R2R_FASTMCP_INTEGRATION.md # Integration guide (NEW)
│ ├── INTEGRATION_QUICKSTART.md # Quick start guide (NEW)
│ ├── DEPLOYMENT.md # Руководство по деплою
│ ├── QUICKSTART.md # Быстрый старт
│ └── SUMMARY.md # Обзор проекта
├── requirements.txt # Python зависимости
├── pyproject.toml # Конфигурация проекта (uv + ruff)
├── Makefile # Удобные команды
├── CLAUDE.md # Память для Claude Code
├── LICENSE # MIT License
├── README.md # Эта документация
├── .env.example # Шаблон конфигурации
├── .gitignore # Git игнорирование
└── openapi.json # R2R OpenAPI спецификация有用的链接
文件
内部文件
- R2R↔ FastMCP集成分析 综合一体化分析：
- 架构相容性（4-Layer Model） - 函数交叉 - 迁移路径（Migration Paths） - 共生：最佳实践 - 生产模式 - 实例
- FastMCP架构 多层FastMCP应用架构
- R2R文档中心 -8разделовR2R文件
- FastMCP文档中心 8个FASTMCP文档
- 克劳德代码文档中心 -13个代码文档
更新日志
看 更改日志.md 查看版本历史和发行说明。
许可证
麻省理工学院