fastmcp-r2r-openapi-integration by evgenygurin - MCP Server

R2R MCP Server

FastMCP-based Model Context Protocol (MCP) сервер для R2R API, обеспечивающий интеграцию с системами управления документами, графами знаний и RAG.

⚡ Важно: Для корректной работы с OpenAPI 3.1 спецификацией рекомендуется включить экспериментальный парсер FastMCP. Добавьте FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER=true в .env файл.

Возможности

Автоматическая генерация MCP компонентов из OpenAPI спецификации
Семантическая маршрутизация: GET операции как Resources, POST/PUT/DELETE как Tools
Аутентификация: Поддержка Bearer token через переменные окружения
Двойной транспорт: 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           # Детальное логирование для отладки

ВАЖНО: Формат API ключа в .env файле:

# ✅ ПРАВИЛЬНО - без кавычек, без "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

Код автоматически добавляет "Bearer " при формировании HTTP заголовка.

Performance Optimizations:

DEBUG_LOGGING=true - показывает детали работы OpenAPI парсера и построения запросов
Experimental parser - автоматически используется для 100-200ms faster startup

Использование

Деплой на FastMCP Cloud (рекомендуется) 🚀

Самый простой способ - задеплоить на FastMCP Cloud:

Entrypoint: src/server.py:mcp
Environment Variables: Добавьте ваши R2R креденшалы
Authentication: Включите для безопасности

📖 Подробная инструкция:

Запуск для 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} → ResourceTemplate
GET /v3/documents/{id} → ResourceTemplate
GET /v3/documents → Resource (список)
GET /health → Resource

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 → Tool (граф знаний)

Примеры использования

Поиск документов

# Через 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"
})

Разработка

Линтинг и форматирование

# Проверка кода
uv run ruff check .

# Автоисправление
uv run ruff check --fix .

# Форматирование
uv run ruff format .

Обновление OpenAPI спецификации

curl -o openapi.json http://localhost:7272/openapi.json

Архитектура

Typed Client (NEW)

Проект использует typed wrapper подход для лучшего DX, сохраняя serverless compatibility:

# 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!
)

Преимущества:

✅ Type hints (IDE autocomplete, mypy checking)
✅ DynamicBearerAuth (serverless compatible)
✅ Less boilerplate
✅ Full HTTP control

См.: docs/R2R_CLIENT_ANALYSIS.md для details.

Структура проекта

.
├── 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 спецификация

Полезные ссылки

Документация

Внутренняя документация

- Комплексный анализ интеграции:
- Архитектурная совместимость (4-layer model)
- Функциональные пересечения
- Возможности перехода (migration paths)
- Симбиоз: лучшие практики
- Production patterns
- Практические примеры
- Многослойная архитектура FastMCP приложений
- 8 разделов R2R documentation
- 8 разделов FastMCP documentation
- 13 разделов Claude Code documentation

Changelog

See for version history and release notes.

Лицензия

MIT