# MCP Business AI Transformation (Cloud.ru Hackathon)
Прототип решения для хакатона Cloud.ru: MCP-сервер + набор бизнес-инструментов, которые вызываются из Evolution AI Agents через протокол Model Context Protocol (MCP).
Решение показывает, как:
- оборачивать внешние сервисы / бизнес-логику в MCP-tools;
- подключать MCP-сервер к Evolution AI Agents;
- работать с ним в интерфейсе Cloud.ru.
---
## 1. Архитектура решения
В репозитории реализованы следующие компоненты:
- **`mcp_server/`** – основной MCP-сервер на FastAPI:
- `/health`, `/api/v1/health` – health-чек сервера;
- `/mcp` – MCP-endpoint (JSON-RPC 2.0) с методами:
- `initialize`
- `tools/list`
- `tools/call`
- `resources/list` (пока заглушка)
- `resources/read` (пока заглушка);
- `app/api/v1/tools.py` – объявление MCP-инструментов и `tool_registry`.
- **`agent_system/`** – заготовка многоагентной системы (орchestrator, агенты и т.д.).
Для хакатона основное внимание на **MCP-сервере**; агентную систему можно развивать дальше.
- **`src/`** – фронтенд на Next.js (UI-панель).
Для проверки решения на Cloud.ru не обязателен, но показывает, как можно визуализировать работу.
## 2. Быстрый старт локально (Windows / macOS / Linux)
### 2.1. Предварительные требования
- Python 3.11+
- Git
- (опционально) Docker, если нужен запуск в контейнере
### 2.2. Клонирование репозитория
```
---
git clone https://github.com/<ВАШ_АККАУНТ>/<ВАШ_РЕПОЗИТОРИЙ>.git
cd mcp-biz-master
---
2.3. Настройка переменных окружения
Создаём .env из примера:
---
cp .env.example .env
---
Минимальный набор для запуска MCP-сервера:
---
EVOLUTION_API_KEY=ВАШ_КЛЮЧ_ОТ_CLOUD_RU
SECRET_KEY=любая_длинная_строка_для_подписи
---
Все остальные переменные могут остаться как в .env.example – они используются вспомогательными сервисами, которые для демо не критичны.
В репозиторий коммитится только
.env.example. Файл.envдолжен быть в.gitignore.
2.4. Установка зависимостей и запуск MCP-сервера
---
cd mcp_server
python -m venv .venv
# Windows:
.\.venv\Scripts\activate
# Linux/macOS:
# source .venv/bin/activate
pip install -r requirements.txt
# запуск MCP-сервера
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
---
После старта сервер доступен по адресу http://localhost:8000.
3. Проверка работы локально
Открыть новый терминал (сервер оставить запущенным).
3.1. Health-чек
---
curl http://localhost:8000/api/v1/health
---
Ожидаемый ответ:
---
{
"status": "ok",
"version": "...",
"app": "..."
}
---
То же самое будет по http://localhost:8000/health.
3.2. MCP tools/list
---
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'
---
Ответ – JSON с перечнем доступных MCP-tools:
---
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{
"name": "...",
"description": "...",
"inputSchema": { ... }
}
]
}
}
---
3.3. MCP tools/call (пример)
Пример общего вида запроса (конкретные имена и параметры смотрите в app/api/v1/tools.py):
---
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "SOME_TOOL_NAME",
"arguments": {
"param1": "value1"
}
}
}'
---
4. Переменные окружения (.env)
Полный перечень переменных – в .env.example.
Ключевые для запуска MCP-сервера:
| Переменная | Обязательна | Назначение |
|---|---|---|
EVOLUTION_API_KEY | API-ключ Cloud.ru Foundation Models / Agents | |
SECRET_KEY | Секрет для подписи токенов / внутреннего использования |
Остальные (DATABASE_URL, REDIS_URL, POSTGRES_*, RABBITMQ_*, GF_SECURITY_* и т.д.) используются для расширенной инфраструктуры (БД, кэш, очереди, мониторинг). Для базового демонстрационного запуска их можно оставить как в примере.
5. Деплой MCP-сервера в Cloud.ru (Artifact Registry + Container Apps)
5.1. Сборка Docker-образа
---
cd mcp_server
docker build -t mcp-biz-server:latest .
---
5.2. Публикация образа в Artifact Registry
-
В личном кабинете Cloud.ru создать Docker / Artifact Registry.
-
Выполнить
docker loginпо инструкции Cloud.ru:
---
docker login <registry_name>.cr.cloud.ru -u <user_or_key> -p <password>
---
- Протегировать и отправить образ:
---
docker tag mcp-biz-server:latest <registry_name>.cr.cloud.ru/mcp-biz-server:latest
docker push <registry_name>.cr.cloud.ru/mcp-biz-server:latest
---
5.3. Создание Container App
-
В разделе Artifact Registry открыть загруженный образ и выбрать «Создать Container App».
-
Указать:
- порт контейнера: 8000;
- переменные окружения: минимум
EVOLUTION_API_KEYиSECRET_KEY(значения – как в локальном.env).
-
Дождаться запуска и запомнить публичный URL контейнера, например:
---
https://mcp-biz-server.containers.cloud.ru
---
Проверка:
---
curl https://mcp-biz-server.containers.cloud.ru/api/v1/health
---
6. Подключение MCP-сервера к Evolution AI Agents
-
В Cloud.ru открыть AI Factory → AI Agents → MCP-серверы.
-
Нажать «Создать MCP-сервер».
-
Указать:
- название (например,
Biz MCP Server); - описание (кратко: «MCP-сервер для бизнес-инструментов»);
- URL:
https://mcp-biz-server.containers.cloud.ru/mcp(или ваш реальный адрес).
- название (например,
-
Сохранить и дождаться статуса «Готов».
7. Создание агента в Evolution AI Agents
- В разделе AI Factory → AI Agents → Агенты нажать «Создать агента».
- Выбрать модель из Evolution Foundation Models.
- В разделе Инструменты / MCP выбрать созданный MCP-сервер
Biz MCP Server. - Сохранить агента.
Дальше можно тестировать в веб-интерфейсе Cloud.ru:
- задать вопрос в свободной форме («Покажи, какие инструменты у тебя есть»);
- агент через LLM вызовет
tools/listи вернёт список инструментов; - затем можно запускать конкретные
tools/callпо смыслу запроса.
8. Что реализовано сейчас и что планируется
Реализовано в MVP:
-
MCP-сервер на FastAPI (
mcp_server/):- health-эндпоинты
/healthи/api/v1/health; - MCP-endpoint
/mcpс методамиinitialize,tools/list,tools/call,resources/list,resources/read; - интеграция с реестром инструментов
tool_registry(см.app/api/v1/tools.py).
- health-эндпоинты
-
Возможность локального запуска и деплоя в Docker/Container Apps на Cloud.ru.
-
Подключение MCP-сервера к Evolution AI Agents.
Планы развития (после хакатона):
- полноценная реализация
resources(подключение к внешним источникам данных); - расширенный набор бизнес-инструментов;
- включение продвинутых мидлварей (аутентификация, rate limiting, корреляция запросов, метрики);
- развитие
agent_system/в сторону полноценной многоагентной платформы; - UI-дашборд (папка
src/) для бизнес-пользователей (визуализация сценариев, алёрты и т.д.).
---