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-контракт

Совместим на уровне протокола с семантикой 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 200 с success=false, чтобы потребители могли отличить сбои на уровне протокола (4xx) от сбоев на уровне инструмента (200 + success=false).

Related MCP server: DB2ST MCP

Инструменты

Инструменты делегируют выполнение подключаемым реализациям ShippingProvider, выбранным через SHIPPING_PROVIDER.

Добавление инструмента сводится к добавлению нового класса в app/tools/ и его регистрации в app/main.py.

Поведение провайдера при запуске

• SHIPPING_PROVIDER=mock (по умолчанию) при запуске выводит громкое предупреждение WARNING, чтобы операторы не были удивлены фиктивными данными.

• Выбор реального перевозчика (ups/fedex/dhl/usps) без всех необходимых учетных данных вызывает ValueError при запуске. Тихий откат к mock отсутствует — неправильная конфигурация приводит к быстрому и явному сбою.

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

Все настройки загружаются из переменных окружения (или .env для локальной разработки). Полный список и значения по умолчанию см. в .env.example.

Локальный запуск

Предварительные требования: 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.

Это позволяет централизовать уровень инструментов — добавьте инструмент один раз, и он станет доступен всем сервисам.