Корпоративные BAU-сервисы с MCP и Gemini

Исполняемое доказательство концепции, показывающее, как ИИ-агент может работать с существующими BAU REST-микросервисами через Model Context Protocol (MCP).

Демонстрация использует Google Gemini для обнаружения MCP-инструментов, получения информации о клиентах и заказах и выполнения контролируемого действия по отмене заказа. BAU-сервисы остаются независимыми REST API; MCP обеспечивает интеграционную границу между этими API и агентом.

Демонстрация

Включённый сценарий предлагает агенту выполнить:

1. Получить профиль для CUST-1001.

2. Вывести список заказов клиента.

3. Определить заказ со статусом Processing.

4. Отменить ORD-9002 с указанной причиной.

5. Резюмировать выполненную работу.

Ожидаемая последовательность инструментов:

Gemini agent
    -> MCP tool discovery over stdio
    -> MCP server
    -> Customer and Order REST APIs
    -> Tool results returned to Gemini
    -> Final user-facing summary

Related MCP server: MCP API Tool Demo

Архитектура

+------------------+       stdio        +------------------+       HTTP       +----------------------+
| Gemini agent     | <----------------> | MCP server       | <--------------> | Customer service     |
| agent_runner.py  |                    | server.py        |                  | localhost:8001       |
+------------------+                    +--------+---------+                  +----------------------+
                                                   |
                                                   | HTTP
                                                   v
                                         +----------------------+
                                         | Order service        |
                                         | localhost:8002       |
                                         +----------------------+

MCP-инструменты

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

.
├── agent/
│   └── agent_runner.py          # Gemini agent and MCP client
├── mcp_server/
│   └── server.py                # MCP tools and REST integration
├── services/
│   ├── customer_service.py      # Mock customer REST API
│   └── order_service.py         # Mock order REST API
├── tests/
│   └── test_services.py         # Service behavior tests
├── .env.example                 # Environment variable template
├── requirements.txt             # Python dependencies
└── mcp_microservices_poc_blueprint.md
                                # Detailed design and implementation reference

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

• Python 3.11 или новее

• Ключ Gemini API из Google AI Studio

• Windows PowerShell, macOS/Linux shell или эквивалентный терминал

• Сетевой доступ к Gemini API при запуске агента

Для этого проекта не требуется ключ API Anthropic или OpenAI.

Быстрый старт в Windows

Откройте PowerShell в каталоге проекта:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item .env.example .env

Откройте .env и замените your_gemini_api_key_here на ваш ключ:

GOOGLE_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-3.6-flash

Никогда не коммитьте .env и не размещайте ключ API в исходном коде. Выбранная модель должна быть доступна для вашего аккаунта Gemini.

Запуск демонстрации

Используйте три терминала. Активируйте .venv в каждом терминале.

Терминал 1: сервис клиентов

python services/customer_service.py

Запускается на http://localhost:8001.

Терминал 2: сервис заказов

python services/order_service.py

Запускается на http://localhost:8002.

Терминал 3: агент Gemini

python agent/agent_runner.py

Агент запускает MCP-сервер как дочерний процесс, обнаруживает его инструменты и выполняет пример рабочего процесса.

Проверка локальных сервисов

Выполните эти команды, пока оба сервиса активны:

Invoke-RestMethod http://localhost:8001/health
Invoke-RestMethod http://localhost:8002/health
Invoke-RestMethod http://localhost:8001/api/v1/customers/CUST-1001
Invoke-RestMethod http://localhost:8002/api/v1/orders/customer/CUST-1001

Запуск тестов

При активной виртуальной среде:

python -m pytest -q

Тесты покрывают поиск клиента без учёта регистра, отсутствующих клиентов, отмену заказа в обработке и защиту от отмены отгруженного заказа.

Конфигурация

Область применения и ограничения

Это локальный, намеренно небольшой POC, предназначенный для того, чтобы интеграционный шаблон было легко изучить и запустить.

• Записи о клиентах и заказах хранятся в памяти и сбрасываются при перезапуске сервисов.

• Сервисы не реализуют аутентификацию или авторизацию.

• В реальной системе операция отмены должна быть защищена контролем утверждения и бизнес-политик.

• MCP использует stdio для локальной интеграции процессов. В развёрнутой архитектуре следует использовать аутентифицированный сетевой транспорт.

• Ошибки нижестоящих сервисов возвращаются в виде текста инструмента для наглядности; производственные системы должны использовать структурированные ошибки, повторы, трассировку и метрики.

• Пример агента выполняет реальный запрос к Gemini API и требует действительный ключ.

Устранение неполадок

GOOGLE_API_KEY is not set

Убедитесь, что .env существует в каталоге проекта и содержит действительный ключ. Запускайте агента из каталога проекта.

404 NOT_FOUND для модели Gemini

Установите GEMINI_MODEL в .env на модель, доступную для вашего аккаунта. По умолчанию в этом POC используется gemini-3.6-flash.

Сбой запуска MCP или обнаружения инструментов

Убедитесь, что зависимости установлены в активную виртуальную среду:

python -m pip install -r requirements.txt

Проект закрепляет MCP за диапазоном API 1.x, поскольку реализация сервера использует FastMCP.

Ошибки подключения от MCP-инструментов

Убедитесь, что оба REST-сервиса запущены на портах 8001 и 8002. Если порт уже занят, обновите порт сервиса и соответствующий URL в .env.

Дополнительные материалы

• Детали доступа к LLM

• Подробный план POC