mcp_OVS

# 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-сервера:

Остальные (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

1. В личном кабинете Cloud.ru создать Docker / Artifact Registry.

2. Выполнить docker login по инструкции Cloud.ru:

---
   docker login <registry_name>.cr.cloud.ru -u <user_or_key> -p <password>
---

3. Протегировать и отправить образ:

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

1. В разделе Artifact Registry открыть загруженный образ и выбрать «Создать Container App».

2. Указать:

   • порт контейнера: 8000;
   • переменные окружения: минимум EVOLUTION_API_KEY и SECRET_KEY (значения – как в локальном .env).

3. Дождаться запуска и запомнить публичный URL контейнера, например:

---
   https://mcp-biz-server.containers.cloud.ru
---

Проверка:

---
curl https://mcp-biz-server.containers.cloud.ru/api/v1/health
---

6. Подключение MCP-сервера к Evolution AI Agents

1. В Cloud.ru открыть AI Factory → AI Agents → MCP-серверы.

2. Нажать «Создать MCP-сервер».

3. Указать:

   • название (например, Biz MCP Server);
   • описание (кратко: «MCP-сервер для бизнес-инструментов»);
   • URL: https://mcp-biz-server.containers.cloud.ru/mcp (или ваш реальный адрес).

4. Сохранить и дождаться статуса «Готов».

7. Создание агента в Evolution AI Agents

1. В разделе AI Factory → AI Agents → Агенты нажать «Создать агента».
2. Выбрать модель из Evolution Foundation Models.
3. В разделе Инструменты / MCP выбрать созданный MCP-сервер Biz MCP Server.
4. Сохранить агента.

Дальше можно тестировать в веб-интерфейсе 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).

• Возможность локального запуска и деплоя в Docker/Container Apps на Cloud.ru.

• Подключение MCP-сервера к Evolution AI Agents.

Планы развития (после хакатона):

• полноценная реализация resources (подключение к внешним источникам данных);
• расширенный набор бизнес-инструментов;
• включение продвинутых мидлварей (аутентификация, rate limiting, корреляция запросов, метрики);
• развитие agent_system/ в сторону полноценной многоагентной платформы;
• UI-дашборд (папка src/) для бизнес-пользователей (визуализация сценариев, алёрты и т.д.).

---