ShipSmart-MCP

Standalone MCP (Model Context Protocol) server exposing ShipSmart's shipping tools (validate_address, get_quote_preview, …) over a small HTTP contract.

It is the single source of truth for tool behavior across the platform. Both ShipSmart-API (Python / FastAPI — RAG & LLMs) and ShipSmart-Orchestrator (Java / Spring Boot — upcoming AI features) call this server instead of implementing tools in-process.

---

HTTP contract

Method	Path	Purpose
GET	/	Service discovery (name, version, tool count, endpoints).
GET	/health	Liveness probe used by Render.
POST	/tools/list	Return schemas for all registered tools.
POST	/tools/call	Execute a tool by name with the provided arguments.

Wire-compatible with the MCP tools/list and tools/call semantics: each call returns { success, content: [...], error? }, where content is a list of {type, text} blocks suitable for LLM consumption.

Auth

If MCP_API_KEY is set on the server, every POST /tools/* request must send the matching value in X-MCP-Api-Key. If MCP_API_KEY is empty, auth is disabled (local dev only).

---

Tools

Name	Description
validate_address	Validate + normalize a shipping address through the configured carrier.
get_quote_preview	Non-binding rate preview for a package. Final rates come from the Java API.

Tools delegate to pluggable ShippingProvider implementations (mock, ups, fedex, dhl, usps) selected by SHIPPING_PROVIDER. Adding a tool is a matter of dropping a new class into app/tools/ and registering it in app/main.py.

---

Running locally

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

Smoke test:

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"
        }
      }'

Tests

uv run pytest

---

Consumers

• ShipSmart-API (Python/FastAPI): points SHIPSMART_MCP_URL at the deployed server and calls /tools/list + /tools/call from its orchestration and advisor services.
• ShipSmart-Orchestrator (Java/Spring Boot): will call the same HTTP contract from its upcoming AI-assist flows. No tool logic lives in the Java codebase.

This keeps the tool layer centralized — add a tool once, every service gets it.