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.

Аутентификация

Если на сервере установлен MCP_API_KEY, каждый запрос POST /tools/* должен содержать соответствующее значение в заголовке X-MCP-Api-Key. Если MCP_API_KEY пуст, аутентификация отключена (только для локальной разработки).

Инструменты

Инструменты делегируют задачи подключаемым реализациям ShippingProvider (mock, ups, fedex, dhl, usps), выбранным через SHIPPING_PROVIDER. Добавление инструмента сводится к созданию нового класса в app/tools/ и его регистрации в app/main.py.

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

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

Потребители

• ShipSmart-API (Python/FastAPI): указывает SHIPSMART_MCP_URL на развернутый сервер и вызывает /tools/list + /tools/call из своих сервисов оркестрации и консультирования.

• ShipSmart-Orchestrator (Java/Spring Boot): будет вызывать тот же HTTP-контракт из своих будущих потоков ИИ-помощника. В кодовой базе Java нет логики инструментов.

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