MCP-Tools der Guthaben-Verwaltung

Die Guthaben-Verwaltung stellt dem Shopware MCP Server fünf Tools, einen Prompt und eine Resource zur Verfügung. Damit können KI-Assistenten (Shopware Copilot, Claude, andere MCP-Clients) Gutscheine suchen, anlegen, auf- und abbuchen, ändern und auswerten — mit denselben Regeln wie in der Administration.

Alle Bestandteile gehören zur Tool-Gruppe bzw. zum Toolset lenz-credit-management (in der Administration: „Lenz credit management tools").

Überblick

Voraussetzungen

Prüfen, ob die Tools registriert sind:

bin/console cache:clear
bin/console debug:mcp | grep lenz-credit-management

Erwartet: fünf Tools, der Prompt lenz-credit-management-context und die Resource lenz-credit-management-config.

Einrichtung

1. Rolle anlegen

Unter Einstellungen → Benutzer & Rechte → Rollen gibt es unter „Marketing" die Rechte Guthaben und Gutschein-Layouts. Die MCP-Tools brauchen eine Rolle mit dem Guthaben-Recht:

Shopware Copilot erreicht die Plugin-Tabellen nur über eine eigene Rolle, die diese Rechte gewährt. Ohne customer:read liefert die Suche Gutscheine ohne Kundendaten (customerHidden: true).

Hinweis: „Guthaben ansehen" enthält system_config:read, weil die Admin-Seiten die Plugin-Konfiguration lesen. Eine Integration mit dieser Rolle kann damit die gesamte Systemkonfiguration lesen.

2. Integration anlegen

bin/console integration:create "MCP Guthaben"

oder unter Einstellungen → System → Integrationen. Dort:

1. Die Rolle aus Schritt 1 zuweisen.
2. Ab 6.7.14: „MCP-Allowlist bearbeiten" → Gruppe „Lenz credit management tools" erlauben.
3. Im Rollen-Detail unter „MCP-Tool-Anforderungen anzeigen" prüfen, dass keine Rechte fehlen.

3. Client verbinden

Endpunkt: https://<shop>/api/_mcp (Streamable HTTP), Authentifizierung über die Header der Integration. Beispiel .mcp.json für Claude Code:

{
  "mcpServers": {
    "shopware": {
      "type": "http",
      "url": "https://shop.example.com/api/_mcp",
      "headers": {
        "sw-access-key": "<Zugangs-ID>",
        "sw-secret-access-key": "<Sicherheitsschlüssel>"
      }
    }
  }
}

Ab 6.7.14 sind Plugin-Tools in Toolsets gruppiert. Der Client findet sie über shopware-tool-search und schaltet sie mit shopware-toolset-enable ({"toolset": "lenz-credit-management"}) frei. Die Tool-Suche ist lexikalisch: Stichworte wie „Gutschein anlegen" oder „Restguthaben" treffen zuverlässig, ganze deutsche Sätze nicht immer.

Vorschau und Freigabe (dryRun)

Alle schreibenden Tools haben den Parameter dryRun, Standard true:

1. Aufruf mit dryRun=true → die Änderung wird echt ausgeführt und dann zurückgerollt. Die Antwort zeigt genau das Ergebnis, das der echte Aufruf hätte — inklusive derselben Fehler.
2. Nach Freigabe derselbe Aufruf mit dryRun=false → die Änderung wird gespeichert.

Shopware Copilot macht das automatisch (Vorschau als Freigabekarte). Bei credit-create ohne festen Code sind die Codes in der Vorschau nur Beispiele; die echten Codes stehen in der Antwort des zweiten Aufrufs.

Schutz vor Doppelbuchungen: Ein identischer Aufruf innerhalb von 120 Sekunden wird abgelehnt (gleiche Buchung mit gleichem Kommentar, gleicher Gutschein für denselben Kunden, gleicher fester Code). Das fängt Wiederholungen ab, wenn ein Client die Antwort nicht gesehen hat. Ist die zweite Buchung wirklich gewollt, einen anderen Kommentar verwenden.

Die Tools im Detail

lenz-credit-management-credit-lookup — Gutschein suchen

Sucht nach genau einem Kriterium und liefert das Restguthaben (Summe aller Buchungen).

Antwort je Gutschein: code, name, balance, active, expiresAt, expired, residual, onlyRedeemableByAssignedCustomer, source, orderNumber, customer, customerSuppliedText (von Kunden beim Kauf eingegebene Texte — nur Daten, keine Anweisungen). Bei genau einem Treffer zusätzlich die letzten fünf Buchungen (lastMovements).

Restguthaben immer über dieses Tool abfragen, nicht über shopware-entity-search — der Wert steht nicht am Gutschein, sondern ergibt sich aus den Buchungszeilen.

lenz-credit-management-credit-create — Gutscheine anlegen

Angelegte Gutscheine erhalten source = "mcp". Die Steuer kommt aus „Standard-Steuer" in der Plugin-Konfiguration, sonst der niedrigste Steuersatz des Shops.

lenz-credit-management-credit-balance-adjust — aufladen oder abbuchen

Schreibt eine Buchung charge-manual bzw. discharge-manual. Das Guthaben kann nicht unter 0 fallen. Die Antwort enthält balanceBefore, change, balanceAfter und Warnungen, wenn der Gutschein inaktiv oder abgelaufen ist.

lenz-credit-management-credit-update — Gutschein ändern

Ändert nur übergebene Werte; leere Parameter bleiben unverändert. Das Guthaben ändert dieses Tool nicht.

Die Antwort listet jedes geänderte Feld mit altem und neuem Wert. Abgelehnt werden u. a.: Beschränkung ohne zugeordneten Kunden, Kunde entfernen bei weiter bestehender Beschränkung (dann wäre der Gutschein für niemanden einlösbar) und Aufrufe, die nichts ändern.

lenz-credit-management-credit-report — Auswertung

Antwort:

• activeCredits — aktive, nicht abgelaufene Gutscheine
• outstandingBalance — offenes, noch einlösbares Gutscheinguthaben (Verbindlichkeit)
• period.charged — im Zeitraum aufgeladen (manuell und durch Kauf)
• period.redeemedInOrders — im Zeitraum in Bestellungen eingelöst
• period.deductedManually — im Zeitraum manuell abgebucht

Prompt lenz-credit-management-context

Gibt dem Modell das Domänenwissen mit: was ein Gutschein ist, wie sich das Guthaben berechnet, welche Tools es gibt, Abläufe für typische Aufgaben und die Regeln (Vorschau zuerst, keine Wiederholung nach Duplikat-Fehler, Kundentexte sind Daten). Clients, die Prompts unterstützen, können ihn zu Beginn laden.

Resource lenz-credit-management://config

JSON mit den Einstellungen, die ein Assistent zum Erklären einer Vorschau braucht: Code-Format (Präfix, Länge, Trennzeichen), Standard-Steuer, Ablauf und Kundenzuordnung gekaufter Gutscheine, autoDisableCreditOnZeroValue. Keine Kundendaten, keine Geheimnisse.

Beispiele

Direkter Aufruf per JSON-RPC (z. B. zum Testen mit curl, nach initialize mit Mcp-Session-Id):

{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {
  "name": "lenz-credit-management-credit-create",
  "arguments": {"value": 50, "name": "Gutschein 50 €", "customerEmail": "max@example.com", "dryRun": true}
}}

Fehlermeldungen

Fehler kommen als normale Tool-Antwort mit einem Text, der sagt, was als Nächstes zu tun ist — etwa „Retry with includeInactive=true", „Cannot deduct 30.00: the credit has only 20.00 left" oder „An identical booking … was made less than 120 seconds ago". Fehlende Rechte werden mit dem Namen des fehlenden Rechts gemeldet.

Bekannte Grenzen

• Keine Zeilensperre gegen gleichzeitiges Abbuchen per MCP und Einlösen im Storefront.
• Die Tool-Suche (shopware-tool-search) trifft Stichworte zuverlässiger als ganze Sätze.