SAP Commerce MCP-Server

Dieses Projekt stellt einen MCP-Server für SAP Commerce Cloud bereit, der sich auf ASM-Mitarbeiter-Workflows konzentriert: Kundensuche, Identitätswechsel (Impersonation), Binden oder Verwalten eines Warenkorbs sowie die Durchführung von OCC-gestützten Commerce-Aktionen durch aufgabenorientierte MCP-Tools.

Das Repository wird nun als Local-First behandelt: Das erwartete Standardziel ist https://localhost:9002, wobei SAP_BASE_URL den tatsächlichen Host steuert. Remote-Mandanten können weiterhin verwendet werden, aber die Dokumentation, Tests und Validierungsabläufe sollten die lokale SAP Commerce-Laufzeitumgebung als primäre Quelle betrachten.

Was dieser Server aktuell leistet

• ASM-fokussierte Kundenaktionen: Kundensuche, Identitätswechsel eines Kunden und fortgesetztes Handeln in dessen Namen

• Sitzungsbewusste Warenkorbverwaltung: Erstellen, Prüfen, Aktualisieren, Entfernen und Leeren von Warenkörben ohne manuelles Hin- und Herwechseln

• Checkout-Ablauf: Lieferadresse, Lieferart, Gast-E-Mail und Auftragserteilung

• Produkt- und Discovery-Tools: Produktsuche, Abrufen von Details, Prüfen von Lagerbeständen, Durchsuchen von Basissites/Shops/Katalogen/Kategorien

• Zwei Tool-Ebenen: Agentenfreundliche High-Level-Tools sowie Low-Level OCC/ASM-Wrapper

• Sitzungsorientierung: get_session_status hilft Agenten, den aktuellen Kontext von Warenkorb/Benutzer/Basissite zu verstehen

• FastMCP-Transport: stdio- und SSE-Transporte für lokale oder Remote-MCP-Clients

Wie ein Request abläuft

1. Architektur auf einen Blick

Quelle: docs/diagrams/architecture.mmd

2. Beispiel-Request-Swimlane

Dies ist der typische Pfad: „Agent übernimmt die Identität eines Kunden und kauft dann in dessen Namen weiter ein“.

Quelle: docs/diagrams/example-request.mmd

MCP-Tools

High-Level-Tools

Dies sind die Hauptschnittstellen für ASM-Mitarbeiter-Workflows.

Discovery und Produkte

• search_products — Produktsuche per Schlüsselwort

• get_product — Abrufen eines Produktdetails

• get_session_status — Überprüfen des aktuellen Sitzungsstatus

Kunde / ASM

• search_customer — Schnelles Finden eines Kunden

• impersonate_customer — Handeln als Kunde starten

• end_impersonation — Zurück zum anonymen Modus

Warenkorb und Checkout

• add_to_cart — Ein Produkt hinzufügen

• get_cart — Aktuellen Warenkorb lesen

• update_cart_entry — Positionsmenge ändern

• remove_from_cart — Eine Position löschen

• clear_cart — Warenkorb leeren

• set_delivery_address — Lieferadresse hinzufügen

• set_delivery_mode — Versandart wählen

• get_delivery_modes — Versandoptionen auflisten

• set_guest_email — E-Mail für Gast-Checkout festlegen

• place_order — Bestellung absenden

Low-Level-Tools

Diese bieten engere OCC / ASM-Primitive für eine exakte Steuerung.

• basesites.list — Verfügbare Basissites auflisten

• catalogs.list — Kataloge für eine Site auflisten

• catalogs.get — Einen Katalog abrufen

• catalogVersions.get — Eine Katalogversion abrufen

• categories.products — Produkte nach Kategorie durchsuchen

• stores.list — Shops für eine Site auflisten

• stores.get — Einen Basis-Shop abrufen

• products.get — Ein OCC-Produkt abrufen

• products.stock — Lagerbestandsdaten prüfen

• products.stockCount — Lagerorte zählen

• asm.customer360 — Customer-360-Fragmente abrufen

• asm.customers.create — Einen Kunden erstellen

• asm.customers.search — ASM-Kundensuche ausführen

• asm.customers.suggest — Kundenvorschläge erhalten

• carts.list — Warenkörbe auflisten

• carts.create — Warenkorb erstellen oder wiederherstellen

• carts.get — Einen Warenkorb abrufen

• carts.delete — Einen Warenkorb löschen

• cartEntries.list — Warenkorbpositionen auflisten

• cartEntries.add — Eine Position hinzufügen

• cartEntries.get — Eine Position abrufen

• cartEntries.update — Positions-Payload ersetzen

• cartEntries.patch — Position teilweise aktualisieren

• cartEntries.delete — Eine Position löschen

Konfiguration

1. Abhängigkeiten installieren:

   uv sync

2. Umgebungsvorlage kopieren:

   cp .env.example .env

3. Für die lokale SAP Commerce-Instanz festlegen:

   SAP_BASE_URL=https://localhost:9002

4. Behalten oder passen Sie diese Pfadfragmente an, falls Ihre SAP-Bereitstellung abweicht:

   • OCC_API_PATH=/occ/v2

   • OAUTH_PATH=/authorizationserver/oauth/token

   • ASM_PATH=/assistedservicewebservices

5. Konfigurieren Sie OAuth-Anmeldeinformationen für den lokalen Mandanten oder den Remote-Mandanten, gegen den Sie validieren. Für das standardmäßige lokale Sample-Data-Setup sind dies die erwarteten Standardwerte:

   OAUTH_CLIENT_ID=mobile_android
   OAUTH_CLIENT_SECRET=secret
   OAUTH_USERNAME=asmagent
   OAUTH_PASSWORD=nimda
   OAUTH_SCOPE=basic

Ausführung

• Stdio:

  python -m app.server

• SSE:

  fastmcp serve app/server.py --sse :8080

Testen

• Vollständige Verifizierungssuite:

  uv run ruff check app tests
  uv run mypy app
  uv run pytest -q

• Smoke-Tests:

  uv run pytest tests/integration/test_smoke.py -q

• Live-Discovery-Ablauf:

  uv run pytest tests/integration/test_integration_live.py -s

Hinweis Live-Tests dienen dazu, den aktuellen Vertrag gegen eine echte SAP Commerce-Laufzeitumgebung zu validieren. Wenn SAP_BASE_URL=https://localhost:9002 gesetzt ist, sollte die lokale OCC/ASM-Instanz das primäre Ziel sein. Wenn OAuth- oder ASM-Daten falsch konfiguriert sind, diagnostizieren Sie dies lokal, bevor Sie den Umfang erweitern.

Lokaler SAP-Hinweis Einige lokale SAP 2211-Stacks enthalten messagecentercsocc, dessen später Oauth2UserFilter den /users/{customerId}-Kontext im Auftrag des Kunden wieder mit dem authentifizierten Agenten überschreiben kann. Wenn Warenkorb-Aufrufe von asmagent zu EmployeeModel -> CustomerModel-Cast-Fehlern führen, patchen Sie diesen Filter so, dass er den bereits zugeordneten Kunden beibehält, wenn sich der aktuelle OCC-Benutzer vom OAuth-Principal unterscheidet.

Qualitäts-Gates

• Ruff für Linting und Import-Hygiene

• Mypy für ein praktisches statisches Typ-Gate über app/

• Pytest + coverage.xml, damit SonarQube dieselben lokalen Nachweise verwenden kann wie in der CI

Lokale SonarQube-Analyse kann veröffentlicht werden mit:

uv run pytest -q
sonar-scanner

sonar-project.properties ist eingecheckt, sodass lokale Scans und CI-Scans denselben Projektschlüssel/Quell-Layout verwenden.

Dokumentation

• Workflows — praktische Tool-Call-Sequenzen

• Architektur Mermaid — Quelle für das Systemdiagramm

• Request Mermaid — Quelle für das Swimlane-Diagramm

• MCP-Manifest und Tool-Registrierung: app/server.py

• Beitrag-Leitfaden: AGENTS.md

Zukünftige Verbesserungen

• Hinzufügen eines optionalen externen Backing-Stores nur, falls das Projekt später eine Multi-Prozess- oder horizontal skalierte Sitzungspersistenz benötigt

Unterstützte OCC / ASM-Abdeckung

Der aktuelle Server deckt die für die oben genannten Abläufe erforderlichen Endpunkte ab, einschließlich Basissites, Kataloge, Shops, Produkte, Warenkörbe, Warenkorbpositionen, Checkout-Adress-/Liefervorgänge, Auftragserteilung sowie ASM-Kundensuche / Customer 360 / Warenkorb-Bindungs-Operationen.