Fastmcp R2r Openapi MCP

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云:

1. 入口点： src/server.py:mcp
2. 环境变量： 添加您的R2R信用卡
3. 身份验证： 启用安全

📖 详细说明： 部署.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/documents Resource（列表）
• GET /health → 资源

Tools（数据修改）

• POST /v3/chunks/search Tool（搜索）
• POST /v3/documents Tool（创建）
• DELETE /v3/documents/{id} 工具（Tool）
• POST /v3/documents/{id}/extract Tool（实体提取）
• 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 спецификация

有用的链接

文件

• FastMCP文档
• R2R文件
• 模型上下文协议

内部文件

• R2R↔ FastMCP集成分析 综合一体化分析：

- 架构相容性（4-Layer Model） - 函数交叉 - 迁移路径（Migration Paths） - 共生：最佳实践 - 生产模式 - 实例

• FastMCP架构 多层FastMCP应用架构

• R2R文档中心 -8разделовR2R文件

• FastMCP文档中心 8个FASTMCP文档

• 克劳德代码文档中心 -13个代码文档

更新日志

看 更改日志.md 查看版本历史和发行说明。

许可证

麻省理工学院