ShipSmart-MCP

Eigenständiger MCP-Server (Model Context Protocol), der die Versand-Tools von ShipSmart (validate_address, get_quote_preview, …) über einen kompakten HTTP-Vertrag bereitstellt.

Er ist die einzige Quelle der Wahrheit für das Tool-Verhalten innerhalb der Plattform. Sowohl ShipSmart-API (Python / FastAPI — RAG & LLMs) als auch ShipSmart-Orchestrator (Java / Spring Boot — kommende KI-Funktionen) rufen diesen Server auf, anstatt die Tools prozessintern zu implementieren.

HTTP-Vertrag

Methode	Pfad	Zweck
GET	`/`	Service-Discovery (Name, Version, Tool-Anzahl, Endpunkte).
GET	`/health`	Liveness-Probe, die von Render verwendet wird.
POST	`/tools/list`	Gibt Schemas für alle registrierten Tools zurück.
POST	`/tools/call`	Führt ein Tool anhand des Namens mit den bereitgestellten Argumenten aus.

Wire-kompatibel mit der MCP tools/list und tools/call Semantik: Jeder Aufruf gibt { success, content: [...], error? } zurück, wobei content eine Liste von {type, text}-Blöcken ist, die für die LLM-Verarbeitung geeignet sind.

Authentifizierung

Wenn MCP_API_KEY auf dem Server gesetzt ist, muss jede POST /tools/*-Anfrage den passenden Wert im Header X-MCP-Api-Key senden. Wenn MCP_API_KEY leer ist, ist die Authentifizierung deaktiviert (nur für lokale Entwicklung).

Tools

Name	Beschreibung
`validate_address`	Validierung + Normalisierung einer Versandadresse über den konfigurierten Versanddienstleister.
`get_quote_preview`	Unverbindliche Preisvorschau für ein Paket. Endgültige Preise stammen aus der Java-API.

Tools delegieren an austauschbare ShippingProvider-Implementierungen (mock, ups, fedex, dhl, usps), die über SHIPPING_PROVIDER ausgewählt werden. Das Hinzufügen eines Tools erfolgt durch das Ablegen einer neuen Klasse in app/tools/ und deren Registrierung in app/main.py.

Lokal ausführen

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

Konsumenten

ShipSmart-API (Python/FastAPI): Verweist SHIPSMART_MCP_URL auf den bereitgestellten Server und ruft /tools/list + /tools/call von seinen Orchestrierungs- und Advisor-Diensten aus auf.
ShipSmart-Orchestrator (Java/Spring Boot): Wird denselben HTTP-Vertrag aus seinen kommenden KI-Assistenz-Flows aufrufen. Es befindet sich keine Tool-Logik in der Java-Codebasis.

Dies hält die Tool-Ebene zentralisiert — ein Tool einmal hinzufügen, und jeder Dienst erhält es.