Skip to main content
Glama
ShipSmart-MCP
by nia194

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, verwendet von Render.

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.

GET

/docs

Swagger UI (nur außerhalb der Produktion).

GET

/redoc

ReDoc (nur außerhalb der Produktion).

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

Bedingung

HTTP

Body

Fehlender oder ungültiger X-MCP-Api-Key

401

{"detail": "Invalid or missing X-MCP-Api-Key"}

Unbekannter Tool-Name

404

{"detail": "Tool not found: <name>"}

Eingabevalidierungsfehler oder Tool-Ausnahme

200

{"success": false, "content": [], "error": "..."}

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

Name

Beschreibung

validate_address

Validierung + Normalisierung einer Versandadresse durch den konfigurierten Versanddienstleister.

get_quote_preview

Unverbindliche Preisvorschau für ein Paket. Endgültige Preise kommen von der Java-API.

Tools delegieren an austauschbare ShippingProvider-Implementierungen, die über SHIPPING_PROVIDER ausgewählt werden.

Provider

Status

mock

Voll funktionsfähig. Gibt deterministische Fake-Daten für lokale Entwicklung und Tests zurück.

ups

Stub — Klasse existiert, ist aber noch nicht produktionsreif.

fedex

Stub — Klasse existiert, ist aber noch nicht produktionsreif.

dhl

Stub — Klasse existiert, ist aber noch nicht produktionsreif.

usps

Stub — Klasse existiert, ist aber noch nicht produktionsreif.

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.

Variable

Zweck

APP_ENV

development oder production. Steuert /docs + /redoc.

APP_HOST / APP_PORT

Bind-Adresse. Standard 0.0.0.0:8001.

LOG_LEVEL

Standard-Logging-Level (Standard INFO).

CORS_ALLOWED_ORIGINS

Kommagetrennte Ursprünge, die durch die CORS-Middleware erlaubt sind.

MCP_API_KEY

Geteiltes Geheimnis, erzwungen bei /tools/*. Leer deaktiviert die Authentifizierung.

SHIPPING_PROVIDER

Einer der Werte mock, ups, fedex, dhl, usps.

UPS_* / FEDEX_* / DHL_* / USPS_*

Anmeldedaten und Basis-URLs pro Versanddienstleister.


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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A horizontally scalable Model Context Protocol server for exposing shipment tracking (and other data sources) as authenticated MCP tools, starting with DB Schenker's public tracking endpoint.
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that wraps the ShipSaving logistics REST API, enabling AI assistants like Claude to perform shipping operations through natural language.
      30
      40 npm
      MIT