Universal Logistics MCP

Единый калькулятор логистики — решение для хакатона Cloud.ru MCP 2024.

Агрегатор логистических сервисов, который позволяет сравнивать цены и сроки доставки от разных провайдеров (СДЭК, Почта России, Деловые Линии) через единый AI-интерфейс.

Ключевые возможности

• Сравнение цен — параллельный опрос всех провайдеров одним запросом
• Создание заказов — оформление накладных в СДЭК, Почте России, Деловых Линиях
• AI-рекомендации — генерация объяснений с помощью Evolution Foundation Models
• Chat UI — удобный веб-интерфейс для взаимодействия с агентом

Быстрый старт

Требования

• Python 3.11+
• Windows / Linux / Mac

Запуск одной командой (Windows)

cd logistics-chat
run_all.bat

Запуск одной командой (Linux/Mac)

cd logistics-chat
chmod +x run_all.sh
./run_all.sh

Скрипт автоматически:

1. Создаст виртуальные окружения
2. Установит зависимости
3. Запустит MCP-сервер (http://localhost:8000)
4. Запустит Chat UI (http://localhost:8501)

Ручной запуск

Терминал 1 — MCP-сервер:

cd logistics-mcp
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e .
python server.py

Терминал 2 — Chat UI:

cd logistics-chat
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
streamlit run app.py

URLs после запуска

Сервис	URL
MCP Server	http://localhost:8000/mcp
Chat UI	http://localhost:8501

Переменные окружения

Создайте файл .env в директории logistics-chat/ (автоматически копируется в logistics-mcp):

# Evolution Foundation Models API (для AI-рекомендаций и Chat UI)
EVOLUTION_API_KEY=your_api_key_here
EVOLUTION_MODEL=MiniMaxAI/MiniMax-M2

# MCP Server
MCP_SERVER_URL=http://localhost:8000

# Порт MCP сервера (опционально)
PORT=8000

# СДЭК API (опционально, есть тестовые ключи)
# CDEK_ACCOUNT=your_account
# CDEK_PASSWORD=your_password

# Деловые Линии API (опционально)
# DELLIN_APPKEY=your_appkey

# Почта России API (опционально, есть демо-режим)
# POCHTA_LOGIN=your_login
# POCHTA_PASSWORD=your_password
# POCHTA_TOKEN=your_token

Описание переменных

Переменная	Обязательная	Описание	По умолчанию
EVOLUTION_API_KEY	Да*	API ключ Evolution FM для Chat UI	—
EVOLUTION_MODEL	Нет	Модель LLM	MiniMaxAI/MiniMax-M2
MCP_SERVER_URL	Нет	URL MCP сервера	http://localhost:8000
PORT	Нет	Порт MCP сервера	8000
CDEK_ACCOUNT	Нет	СДЭК Account ID	Тестовые ключи
CDEK_PASSWORD	Нет	СДЭК Password	Тестовые ключи
DELLIN_APPKEY	Нет	Деловые Линии AppKey	Демо-режим
POCHTA_LOGIN	Нет	Логин API Почты России	Демо-режим
POCHTA_PASSWORD	Нет	Пароль API Почты России	Демо-режим
POCHTA_TOKEN	Нет	Токен API Почты России	Демо-режим

*EVOLUTION_API_KEY обязателен только для Chat UI. MCP-сервер работает без него.

Примеры запросов

После запуска откройте http://localhost:8501 и попробуйте:

Сравни цены доставки из Москвы (101000) в Казань (420000), вес 2 кг

Какой самый дешевый способ отправить посылку 5 кг в Новосибирск?

Создай заказ СДЭК из Санкт-Петербурга в Москву

Проверь доступность логистических сервисов

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

mcp-mail/
├── logistics-mcp/           # MCP сервер
│   ├── mcp_instance.py      # Единый экземпляр FastMCP
│   ├── server.py            # Точка входа
│   ├── tools/               # MCP инструменты
│   │   ├── aggregator.py    # compare_logistics
│   │   ├── cdek.py          # СДЭК API
│   │   ├── pochta.py        # Почта России API
│   │   ├── dellin.py        # Деловые Линии API
│   │   └── evolution_client.py  # Evolution FM
│   ├── metrics.py           # Prometheus метрики
│   ├── env_options.json     # Конфигурация Cloud.ru
│   ├── mcp-server-catalog.yaml
│   ├── mcp_tools.json
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── DEPLOY.md            # Деплой на Cloud.ru
│   └── README.md            # Документация MCP
│
├── logistics-chat/          # Chat UI (Streamlit)
│   ├── app.py               # Веб-интерфейс
│   ├── agent.py             # AI-агент с tool calling
│   ├── mcp_client.py        # Клиент MCP
│   ├── run_all.bat          # Запуск всего (Windows)
│   ├── run_all.sh           # Запуск всего (Linux/Mac)
│   ├── run_mcp.bat          # Запуск MCP
│   ├── run.bat              # Запуск Chat UI
│   └── README.md            # Документация Chat
│
└── README.md                # Этот файл

Соответствие требованиям хакатона

Проект соответствует стандартам Cloud.ru MCP:

Требование	Статус	Файл/Директория
Единый экземпляр FastMCP	✅	logistics-mcp/mcp_instance.py
Главный файл запуска	✅	logistics-mcp/server.py
Инструменты в отдельных файлах	✅	logistics-mcp/tools/
Зависимости проекта	✅	logistics-mcp/pyproject.toml
Пример переменных окружения	✅	logistics-mcp/.env.example
Описание переменных для Cloud.ru	✅	logistics-mcp/env_options.json
Каталог MCP сервера	✅	logistics-mcp/mcp-server-catalog.yaml
JSON описание инструментов	✅	logistics-mcp/mcp_tools.json
Документация	✅	README.md, logistics-mcp/README.md
Docker контейнеризация	✅	Dockerfile, docker-compose.yml
Prometheus метрики	✅	logistics-mcp/metrics.py
OpenTelemetry трейсинг	✅	Интегрирован в tools
Streamable-HTTP транспорт	✅	server.py
Асинхронные инструменты	✅	Все tools async
Context для логирования	✅	Все tools используют ctx
Pydantic Field для параметров	✅	Все параметры описаны
McpError для ошибок	✅	Обработка ошибок

MCP Инструменты

Инструмент	Описание
compare_logistics	Сравнение цен доставки у всех провайдеров
create_cdek_order	Создание накладной в СДЭК
create_pochta_order	Создание отправления в Почте России
create_dellin_order	Создание заявки в Деловых Линиях
explain_logistics_choice	AI-объяснение выбора тарифа
check_providers	Проверка доступности провайдеров

Деплой на Cloud.ru

Подробная инструкция по развертыванию на платформе Cloud.ru:

# Сборка Docker образа
cd logistics-mcp
docker build -t logistics-mcp:1.0.3 .

# Загрузка в Artifact Registry
docker login <registry>.cr.cloud.ru -u <key_id> -p <key_secret>
docker tag logistics-mcp:1.0.3 <registry>.cr.cloud.ru/logistics-mcp:1.0.3
docker push <registry>.cr.cloud.ru/logistics-mcp:1.0.3

Подробнее: logistics-mcp/DEPLOY.md

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

# Запуск тестов MCP сервера
cd logistics-mcp
pip install -e ".[test]"
pytest

# E2E тест (сервер должен быть запущен)
python test_scenario.py

Лицензия

MIT License

---

Разработано для хакатона Cloud.ru MCP 2024