ShipSmart-MCP
ShipSmart-MCP
Автономный MCP-сервер (Model Context Protocol), предоставляющий инструменты доставки ShipSmart (validate_address, get_quote_preview и т. д.) через простой HTTP-контракт.
Он является единственным источником достоверной информации о работе инструментов на всей платформе. Как ShipSmart-API (Python / FastAPI — RAG и LLM), так и ShipSmart-Orchestrator (Java / Spring Boot — будущие функции ИИ) обращаются к этому серверу, вместо того чтобы реализовывать инструменты внутри своих процессов.
HTTP-контракт
Метод | Путь | Назначение |
GET |
| Обнаружение сервиса (имя, версия, количество инструментов, эндпоинты). |
GET |
| Проверка работоспособности (Liveness probe), используемая Render. |
POST |
| Возврат схем для всех зарегистрированных инструментов. |
POST |
| Выполнение инструмента по имени с предоставленными аргументами. |
GET |
| Swagger UI (только для непроизводственных сред). |
GET |
| ReDoc (только для непроизводственных сред). |
Совместим на уровне протокола с семантикой MCP tools/list и tools/call: каждый вызов возвращает { success, content: [...], error? }, где content — это список блоков {type, text}, подходящих для обработки LLM.
/docs и /redoc подключаются только при APP_ENV != production.
Аутентификация
Если на сервере установлен MCP_API_KEY, каждый запрос POST /tools/* должен содержать соответствующее значение в заголовке X-MCP-Api-Key. Если MCP_API_KEY пуст, аутентификация отключена (только для локальной разработки). Запросы GET / и GET /health всегда не требуют аутентификации, чтобы проверки работоспособности и обнаружение сервиса работали без общего секретного ключа.
Ответы об ошибках
Условие | HTTP | Тело |
Отсутствующий или неверный | 401 |
|
Неизвестное имя инструмента | 404 |
|
Ошибка валидации или исключение инструмента | 200 |
|
Ошибки валидации и выполнения намеренно возвращают HTTP 200 с success=false, чтобы потребители могли отличить сбои на уровне протокола (4xx) от сбоев на уровне инструмента (200 + success=false).
Related MCP server: DB2ST MCP
Инструменты
Имя | Описание |
| Проверка + нормализация адреса доставки через настроенного перевозчика. |
| Необязывающий предварительный просмотр тарифов для посылки. Окончательные тарифы приходят из Java API. |
Инструменты делегируют выполнение подключаемым реализациям ShippingProvider, выбранным через SHIPPING_PROVIDER.
Провайдер | Статус |
| Полностью рабочий. Возвращает детерминированные фиктивные данные для локальной разработки и тестов. |
| Заглушка — класс существует, но еще не готов к работе в продакшене. |
| Заглушка — класс существует, но еще не готов к работе в продакшене. |
| Заглушка — класс существует, но еще не готов к работе в продакшене. |
| Заглушка — класс существует, но еще не готов к работе в продакшене. |
Добавление инструмента сводится к добавлению нового класса в app/tools/ и его регистрации в app/main.py.
Поведение провайдера при запуске
SHIPPING_PROVIDER=mock(по умолчанию) при запуске выводит громкое предупреждениеWARNING, чтобы операторы не были удивлены фиктивными данными.Выбор реального перевозчика (
ups/fedex/dhl/usps) без всех необходимых учетных данных вызываетValueErrorпри запуске. Тихий откат кmockотсутствует — неправильная конфигурация приводит к быстрому и явному сбою.
Конфигурация
Все настройки загружаются из переменных окружения (или .env для локальной разработки). Полный список и значения по умолчанию см. в .env.example.
Переменная | Назначение |
|
|
| Адрес привязки. По умолчанию |
| Стандартный уровень логирования (по умолчанию |
| Разделенный запятыми список источников, разрешенных CORS-middleware. |
| Общий секретный ключ для |
| Один из вариантов: |
| Учетные данные и базовые URL для каждого перевозчика. |
Локальный запуск
Предварительные требования: Python 3.13+ и uv.
cp .env.example .env
# fill in credentials if you want real carrier integration; default is SHIPPING_PROVIDER=mock
uv sync
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8001Дымовое тестирование:
curl -s http://localhost:8001/health
curl -s -X POST http://localhost:8001/tools/list
curl -s -X POST http://localhost:8001/tools/call \
-H 'Content-Type: application/json' \
-d '{
"name": "validate_address",
"arguments": {
"street": "123 Main St",
"city": "San Francisco",
"state": "CA",
"zip_code": "94105"
}
}'Тесты
uv run pytestНаблюдаемость
RequestLoggingMiddleware (app/core/middleware.py) обрабатывает идентификаторы корреляции (correlation IDs) для каждого запроса:
Считывает
X-Request-Idиз входящего запроса или создает UUID hex, если он отсутствует.Считывает W3C
traceparentили создает новый, если он отсутствует или поврежден.Дублирует оба заголовка в ответе, чтобы вызывающие стороны могли использовать
grepпо ID во всех сервисах.Выводит одну строку лога на каждый запрос в логгер
shipsmart_mcp.requests:
GET /health → 200 (1.4ms) [a1b2c3...]Передавайте X-Request-Id из вышестоящих сервисов, чтобы связать единый запрос по цепочке ShipSmart-API → MCP → API перевозчиков.
Развертывание (Render)
render.yaml — это чертеж (Blueprint) Render, определяющий развернутый сервис:
Python веб-сервис, сборка через
pip install uv && uv sync, запуск черезuvicorn app.main:app --host 0.0.0.0 --port $PORT.Проверка работоспособности по адресу
/health.MCP_API_KEYимеет параметрsync: false— установите его один раз в панели управления Render и используйте то же значение дляSHIPSMART_MCP_API_KEYу каждого потребителя.По умолчанию
SHIPPING_PROVIDER=fedexуказывает наhttps://apis-sandbox.fedex.com(песочница FedEx, не продакшен). Переопределите базовый URL при переходе на реальный трафик перевозчика.Источники CORS закреплены в чертеже за развернутыми URL потребителей.
Для развертывания укажите Render на этот репозиторий; все переменные окружения с sync: false должны быть заполнены до успешного первого развертывания.
Потребители
ShipSmart-API (Python / FastAPI; развернут как
shipsmart-api-pythonна Render): указываетSHIPSMART_MCP_URLна этот сервер и вызывает/tools/list+/tools/callиз своих сервисов оркестрации и консультирования.ShipSmart-Orchestrator (Java / Spring Boot; развернут как
shipsmart-api-javaна Render): будет вызывать тот же HTTP-контракт из своих будущих потоков ИИ-помощника. Логика инструментов не содержится в кодовой базе Java.
Это позволяет централизовать уровень инструментов — добавьте инструмент один раз, и он станет доступен всем сервисам.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
A paid remote MCP for ShipSwift, built to return verdicts, receipts, usage logs, and audit-ready JSO
MCP server for EasyPost — rate shipments, buy & refund labels, track packages, verify addresses.
MCP server for SkuVault — products, inventory, sales, purchase orders and stock adjustments.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with ShipEngine's shipping API, allowing users to manage shipments, labels, carriers, and other shipping operations through natural language commands.-
- AlicenseNot gradedqualityDmaintenanceA horizontally scalable Model Context Protocol server for exposing shipment tracking (and other data sources) as authenticated MCP tools, starting with DB Schenker's public tracking endpoint.1MIT
- AlicenseBqualityDmaintenanceAn MCP server that wraps the ShipSaving logistics REST API, enabling AI assistants like Claude to perform shipping operations through natural language.3040 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server exposing Shopify commerce backend with ~22 typed tools for orders, inventory, logistics, and fulfillment, including read/write separation and structured errors.ISC