🚀 R2R MCP Server

🚀 R2R MCP Server

R2R MCP Server предоставляет интеграцию Model Context Protocol (MCP) с системой R2R (Retrieval-to-Response) для улучшения взаимодействия с Claude и другими MCP-совместимыми моделями, обеспечивая доступ к базам знаний.

✨ Особенности

• 🔌 MCP сервер для интеграции с Claude и другими MCP-совместимыми моделями
• ⚡ Асинхронный клиент R2R для высокопроизводительного доступа к базам знаний
• 🔍 Инструменты поиска и генерации ответов на основе контекстуальных данных
• 📊 Структурированное логирование с помощью Loguru
• 🪶 Легкая архитектура с минимальными зависимостями
• 💡 Расширенные возможности RAG (Retrieval-Augmented Generation)
• 🌐 Поддержка веб-поиска для получения актуальной информации
• 🤖 Возможность исследования через агента для сложных запросов

🏗️ Архитектура

Проект разработан в соответствии с принципами SOLID, DRY и KISS:

• Single Responsibility: Каждый компонент выполняет одну задачу
• Open/Closed: Модули открыты для расширения, но закрыты для модификации
• Liskov Substitution: Компоненты взаимозаменяемы через интерфейсы
• Interface Segregation: API разделены по функциональности
• Dependency Inversion: Зависимости внедряются, а не создаются внутри компонентов

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

r2r-mcp/
│
├── app/                    # 📦 Основной код приложения
│   └── server.py           # 🖥️ Основной MCP сервер
│
├── tests/                  # 🧪 Тесты
│   ├── test_r2r_mcp.py               # Модульные тесты функциональности
│   ├── test_r2r_mcp_integration.py   # Интеграционные тесты с API
│   ├── test_r2r_mcp_performance.py   # Тесты производительности
│   └── conftest.py                   # Настройки и фикстуры для тестов
│
├── docs/                   # 📚 Документация
│   └── ...
│
├── logs/                   # 📝 Директория для логов
│   └── ...
│
├── .github/                # 🔄 GitHub конфигурация
│   └── workflows/          # CI/CD workflows
│       ├── test.yml        # Тестирование
│       └── release.yml     # Релизы
│
├── .env.example            # 🔒 Пример переменных окружения
├── Makefile                # 🛠️ Команды для разработки и тестирования
├── pyproject.toml          # ⚙️ Конфигурация проекта и зависимостей
├── CONTRIBUTING.md         # �� Руководство по контрибьютингу
├── README.md               # 📄 Документация проекта
└── .gitignore              # 🙈 Игнорируемые файлы Git

🔧 Установка

Предварительные требования

• 🐍 Python 3.12 или выше
• 🔄 uv (современный Python package manager)
• 🛠️ make (опционально, для использования Makefile)

Установка зависимостей

С использованием Makefile (рекомендуется) 👍

# Клонирование репозитория
git clone https://github.com/eagurin/r2r-mcp.git
cd r2r-mcp

# Создание виртуального окружения
uv venv
source .venv/bin/activate  # Linux/macOS
# или .venv\Scripts\activate  # Windows

# Установка основных зависимостей
make install

# Установка зависимостей для разработки
make install-dev

Вручную с помощью uv 🔧

# Установка uv, если не установлен
curl -LsSf https://astral.sh/uv/install.sh | sh

# Клонирование репозитория
git clone https://github.com/eagurin/r2r-mcp.git
cd r2r-mcp

# Создание виртуального окружения
uv venv
source .venv/bin/activate  # Linux/macOS
# или .venv\Scripts\activate  # Windows

# Установка основных зависимостей
uv pip install mcp r2r loguru

# Или установка через pyproject.toml
uv pip install .

# Установка с зависимостями для разработки
uv pip install ".[dev]"

Установка как MCP-плагин 🔌

После установки зависимостей вы можете установить сервер как MCP-плагин:

# Локальный R2R API
mcp install app/server.py -v R2R_API_URL=https://api.sciphi.ai

# Облачный R2R API
mcp install app/server.py -v R2R_API_KEY=your_api_key_here

🧰 Доступные инструменты MCP

Инструмент	Описание	Статус
search	Поиск в документах с помощью R2R, включая векторный и гибридный поиск	✅
rag	Получение ответа на основе базы знаний (RAG) с цитированием источников	✅
web_search	Поиск в интернете через R2R с результатами из открытых источников	✅
document_search	Поиск в конкретном документе или по всей базе знаний	✅
list_documents	Список доступных документов в базе знаний с метаданными	✅
agent_research	Исследование через агента для сложных запросов с использованием LLM	✅

🔍 Функциональность

Векторный и гибридный поиск 🔍

Система поддерживает современные методы информационного поиска:

• 📊 Векторный поиск по семантической близости
• 📝 Полнотекстовый поиск для точных совпадений
• 🔄 Гибридный поиск, комбинирующий оба подхода

RAG (Retrieval-Augmented Generation) 🧠

Позволяет получать обоснованные ответы на основе документов:

• 🔎 Автоматический подбор релевантных источников
• 📃 Генерация связного ответа с цитированием
• ⚙️ Настраиваемые параметры генерации (температура, длина ответа)

Агентские исследования 🕵️‍♂️

Для сложных запросов доступен режим исследования с агентом:

• 🔬 Глубокий анализ темы с использованием мощных LLM-моделей
• 🔗 Комбинирование разных источников информации
• 📊 Формирование обоснованных выводов и рекомендаций

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

После установки как MCP-плагина, Claude автоматически получает доступ к инструментам R2R и может использовать их для:

1. 🔍 Поиска информации в ваших документах и получения конкретных фрагментов текста
2. ❓ Ответов на вопросы с опорой на данные из базы знаний с указанием источников
3. 📚 Проведения исследования путем комбинирования разных источников информации
4. 🌐 Поиска актуальной информации в интернете при необходимости

💡 Claude автоматически выберет соответствующий инструмент MCP и получит доступ к вашим данным через R2R API.

👨‍💻 Разработка

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

Проект включает Makefile для удобного выполнения задач разработки:

Показать список доступных команд 📜

make help

Запустить MCP сервер локально 🚀

make run

Запуск тестов вручную 🧪

# Установка зависимостей для разработки
make install-dev

# Запуск тестов
make test

# Запуск с отчетом о покрытии
make test-cov

Форматирование и проверка кода ✨

# Форматирование кода и сортировка импортов
make format

# Проверка типов
make mypy

# Проверка стиля кода
make lint

# Запуск всех проверок и тестов
make all

🧪 Тестирование

Проект включает комплексную систему тестирования:

Модульные тесты (test_r2r_mcp.py) 🔬

Проверяют отдельные компоненты и функции системы:

• Тесты вспомогательных функций форматирования
• Тесты инициализации сервера
• Тесты инструментов MCP
• Тесты взаимодействия с клиентом R2R

Интеграционные тесты (test_r2r_mcp_integration.py) 🔄

Проверяют взаимодействие с реальным API R2R:

• Тесты с реальными API-вызовами (требуют настройки R2R_API_URL или R2R_API_KEY)
• Тесты с моками для имитации API-вызовов
• Пропуск тестов при отсутствии настроек API

Тесты производительности (test_r2r_mcp_performance.py) ⚡

Измеряют эффективность работы компонентов:

• Тесты производительности форматирования результатов
• Тесты скорости обработки инструментов
• Бенчмаркинг на разных размерах данных

Запуск всех категорий тестов:

make test

👥 Contributing

Мы приветствуем вклад в развитие проекта! Подробная информация доступна в CONTRIBUTING.md.

Краткие шаги:

1. 🍴 Форкните репозиторий
2. 🌱 Создайте ветку для вашей функциональности (git checkout -b feature/amazing-feature)
3. ✏️ Внесите изменения и отформатируйте код (make format)
4. 🧪 Запустите проверки и тесты (make all)
5. 📝 Сделайте коммит (git commit -m 'Add amazing feature')
6. 📤 Отправьте изменения (git push origin feature/amazing-feature)
7. 🔄 Откройте Pull Request

⚡ Производительность

Проект оптимизирован для высокой производительности:

• 🔄 Асинхронные клиенты для параллельной обработки запросов
• 📊 Эффективное форматирование результатов поиска
• 🔄 Кэширование клиентов для повторного использования
• 📈 Строгие тесты производительности для контроля эффективности

🔄 Интеграция с другими MCP-совместимыми моделями

R2R MCP Server может работать с любыми MCP-совместимыми моделями, включая:

• 🤖 Claude (через Claude.app или API)
• 🔄 Другие LLM-модели с поддержкой MCP
• ⚙️ Кастомные клиенты MCP

📦 Зависимости проекта

Проект использует минимальный набор необходимых зависимостей из pyproject.toml:

Зависимость	Версия	Статус	Описание
mcp	>=0.1.0	✅	Model Context Protocol для интеграции с LLM
r2r	>=0.1.0	✅	Клиент для R2R API
loguru	>=0.7.0	✅	Структурированное логирование

Зависимости для разработки

Зависимость	Версия	Статус	Описание
pytest	>=8.0.0	✅	Фреймворк для тестирования
pytest-asyncio	>=0.23.0	✅	Поддержка асинхронных тестов
pytest-cov	>=6.1.1	✅	Отчеты о покрытии кода тестами
black	>=24.1.0	✅	Форматирование кода
isort	>=5.13.0	✅	Сортировка импортов
mypy	>=1.8.0	✅	Статическая проверка типов
ruff	>=0.2.0	✅	Линтер кода
httpx	>=0.26.0	✅	HTTP-клиент для тестов

📚 Полезные ресурсы

• 🔗 Документация MCP
• 🔗 Python SDK для MCP
• 🔗 UV Package Manager
• 🔗 Инструменты MCP

📄 Лицензия

MIT