---
slug: "r2r"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/eagurin/r2r-mcp@main/README.md"
repo: "https://github.com/eagurin/r2r-mcp"
source_file: "README.md"
branch: "main"
---
# 🚀 R2R MCP Server

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-brightgreen.svg)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![UV](https://img.shields.io/badge/UV-Package_Manager-purple.svg)](https://astral.sh/uv)

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:

- **S**ingle Responsibility: Каждый компонент выполняет одну задачу
- **O**pen/Closed: Модули открыты для расширения, но закрыты для модификации
- **L**iskov Substitution: Компоненты взаимозаменяемы через интерфейсы
- **I**nterface Segregation: API разделены по функциональности
- **D**ependency Inversion: Зависимости внедряются, а не создаются внутри компонентов

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

```bash
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 (рекомендуется) 👍

```bash
# Клонирование репозитория
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 🔧

```bash
# Установка 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-плагин:

```bash
# Локальный 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 для удобного выполнения задач разработки:

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

```bash
make help
```

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

```bash
make run
```

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

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

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

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

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

```bash
# Форматирование кода и сортировка импортов
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) ⚡

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

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

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

```bash
make test
```

## 👥 Contributing

Мы приветствуем вклад в развитие проекта! Подробная информация доступна в [CONTRIBUTING.md](https://github.com/eagurin/r2r-mcp/blob/HEAD/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](https://modelcontextprotocol.io)
- 🔗 [Python SDK для MCP](https://pypi.org/project/mcp/)
- 🔗 [UV Package Manager](https://astral.sh/uv)
- 🔗 [Инструменты MCP](https://modelcontextprotocol.io/examples)

## 📄 Лицензия

MIT