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

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.

/docs und /redoc werden nur eingebunden, wenn APP_ENV != production ist.

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). GET / und GET /health sind immer unauthentifiziert, damit Health-Checks und Service-Discovery ohne das geteilte Geheimnis funktionieren.

Fehlerantworten

Validierungs- und Ausführungsfehler geben bewusst HTTP 200 mit success=false zurück, damit Konsumenten zwischen Fehlern auf Protokollebene (4xx) und Fehlern auf Tool-Ebene (200 + success=false) unterscheiden können.

Related MCP server: DB2ST MCP

Tools

Tools delegieren an austauschbare ShippingProvider-Implementierungen, 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.

Startverhalten des Providers

• SHIPPING_PROVIDER=mock (Standard) gibt beim Start eine deutliche WARNING aus, damit Betreiber nicht von Fake-Daten überrascht werden.

• Die Auswahl eines echten Versanddienstleisters (ups/fedex/dhl/usps) ohne alle erforderlichen Anmeldedaten löst beim Start einen ValueError aus. Es gibt kein stilles Fallback auf mock — Fehlkonfigurationen schlagen sofort und sichtbar fehl.

Konfiguration

Alle Einstellungen werden aus Umgebungsvariablen (oder .env für die lokale Entwicklung) geladen. Siehe .env.example für die vollständige Liste und Standardwerte.

Lokal ausführen

Voraussetzungen: Python 3.13+ und 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

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

Observability

RequestLoggingMiddleware (app/core/middleware.py) verwaltet Korrelations-IDs für jede Anfrage:

• Liest X-Request-Id aus der eingehenden Anfrage oder erstellt ein UUID-Hex, falls nicht vorhanden.

• Liest W3C traceparent oder erstellt ein neues, falls nicht vorhanden oder fehlerhaft.

• Spiegelt beide Header in der Antwort, damit Aufrufer nach ID über Dienste hinweg grepen können.

• Gibt eine Log-Zeile pro Anfrage im shipsmart_mcp.requests-Logger aus:

  GET /health → 200 (1.4ms) [a1b2c3...]

Übergeben Sie X-Request-Id von Upstream-Diensten, um eine einzelne Anfrage über ShipSmart-API → MCP → Carrier-APIs hinweg zu verknüpfen.

Deployment (Render)

render.yaml ist ein Render-Blueprint, der den bereitgestellten Dienst definiert:

• Python-Webdienst, Build via pip install uv && uv sync, Start via uvicorn app.main:app --host 0.0.0.0 --port $PORT.

• Health-Check unter /health.

• MCP_API_KEY ist sync: false — setzen Sie ihn einmal im Render-Dashboard und verwenden Sie denselben Wert für den SHIPSMART_MCP_API_KEY jedes Konsumenten.

• Standard SHIPPING_PROVIDER=fedex zeigt auf https://apis-sandbox.fedex.com (FedEx Sandbox, nicht Produktion). Überschreiben Sie die Basis-URL bei der Umstellung auf Live-Versandverkehr.

• CORS-Ursprünge sind im Blueprint auf die bereitgestellten Konsumenten-URLs festgelegt.

Stellen Sie den Dienst bereit, indem Sie Render auf dieses Repository verweisen; alle sync: false Umgebungsvariablen müssen ausgefüllt sein, bevor das erste Deployment erfolgreich ist.

Konsumenten

• ShipSmart-API (Python / FastAPI; bereitgestellt als shipsmart-api-python auf Render): verweist SHIPSMART_MCP_URL auf diesen Server und ruft /tools/list + /tools/call von seinen Orchestrierungs- und Advisor-Diensten aus auf.

• ShipSmart-Orchestrator (Java / Spring Boot; bereitgestellt als shipsmart-api-java auf Render): wird denselben HTTP-Vertrag aus seinen kommenden KI-Assistenz-Flows aufrufen. Im Java-Codebase befindet sich keine Tool-Logik.

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