Diese Dokumentation bezieht sich immer auf den aktuellen Stand des main-Branches.
| Aspekt | Verhalten |
|---|---|
| Speicherort | Klartext in der .env-Datei (oder in der Umgebung des Prozesses). Die Datei steht in der .gitignore und gehört nie in ein Repository. |
| Weitergabe | Client-ID und Client-Secret gehen ausschließlich per POST an <SHOPWARE_URL>/api/oauth/token. Der Server erzwingt kein HTTPS, bei http:// erscheint nur eine Warnung auf stderr. |
| Verfahren | OAuth2 Client Credentials. Die Rechte der Integration in Shopware bestimmen, was der Server darf. |
| Token | Liegt nur im Arbeitsspeicher. Es wird erst beim ersten API-Aufruf geholt und 60 Sekunden vor Ablauf erneuert, gleichzeitige Erneuerungen werden zu einer Anfrage zusammengefasst. Die Token-Anfrage hat 15 Sekunden Timeout. |
| Token-Fehler | Antwortet Shopware bei einem API-Aufruf mit 401, wird das Token verworfen und der Aufruf einmal mit einem neuen Token wiederholt. |
Wer die
.envlesen kann, kann mit denselben Rechten direkt auf die Admin API zugreifen. Lege für den Server eine eigene Integration mit minimalen Rechten an und nutze getrennte Integrationen für Test und Produktion.
Alle Tool-Parameter gelten als nicht vertrauenswürdig, weil sie von einem Sprachmodell kommen.
| Schutz | Wirkung |
|---|---|
| Eingabeprüfung | Jeder Aufruf wird mit einem Zod-Schema geprüft: Typen, Längen, Wertebereiche und Aufzählungen. Fehler kommen als INVALID_INPUT mit Feldliste zurück. |
| ID-Prüfung | IDs müssen 32 Zeichen Hex (oder UUID mit Bindestrichen) sein, damit nichts anderes in einen API-Pfad gelangt. |
| Inaktiv anlegen | product_create erzeugt immer ein inaktives Produkt. |
| Bestellungen nur lesend | Es gibt kein Tool, das Bestellungen ändert. |
| Kein Löschen | Es gibt kein Lösch-Tool. Einzige Ausnahme: Schlägt media_upload_url nach dem Anlegen fehl, wird das eben angelegte Medium wieder entfernt. |
| Schutz vor internen URLs | media_upload_url lehnt Adressen ab, deren Host localhost, 0.0.0.0, eine rein numerische Adresse, ein Loopback-, privates (10., 172.16. bis 172.31., 192.168.), Link-Local- (169.254.) oder Shared-Address-Netz (100.64. bis 100.127.) oder eine IPv6-Loopback-, Unique-Local- oder Link-Local-Adresse ist, außerdem die Metadaten-Hosts metadata.google.internal und metadata.goog. Erlaubt sind nur http und https. |
| Test-Mail-Limit | mail_template_send_test ist auf 5 Aufrufe je Template und 10 insgesamt pro Minute begrenzt. Der Empfänger darf weder localhost enthalten noch eine IP-Adresse als Domain haben. |
| Timeouts und Retries | 30 Sekunden je API-Anfrage. Bei 429 wiederholt der Server bis zu dreimal mit wachsender Wartezeit (1, 2, 4 Sekunden). |
| Fehlerausgabe | Bei Serverfehlern (500, 502, 503) lautet die Meldung "Shopware API error (500): Shopware server error", die Details der Shopware-Antwort erscheinen darin nicht. Andere Fehler zeigen höchstens 200 Zeichen der Shopware-Meldung. Bei 404 wird nur der letzte Pfadabschnitt genannt. |
Die Prüfung auf interne URLs wertet nur den Host-Text der URL aus. Sie löst keine Namen auf. Ein öffentlicher Hostname, der intern auf eine private Adresse zeigt, wird nicht erkannt. Den Download selbst führt Shopware aus, nicht der MCP-Server.
Der Server schreibt ausschließlich nach stderr, damit der Protokollkanal auf stdout sauber bleibt. Jede Zeile enthält Zeitstempel und Stufe. Standard ist info.
debug stehen Methode und Endpunkt jedes API-Aufrufs, Request-Bodies nur als Längenangabe.ab***@domain) und in der Erfolgsmeldung vollständig im Log.| Daten | Ziel |
|---|---|
| Tool-Aufrufe und Ergebnisse (Produkttexte, Preise, Medien, Mail-Templates) | Sind Teil der Konversation mit Claude und gehen damit an Anthropic. |
| Bestelldaten | order_list liefert unter anderem Kunden-Name und E-Mail. order_get liefert zusätzlich Firma, Telefonnummern, Rechnungs- und Lieferadresse, Positionen und den Kundenkommentar. Alles wird Teil der Konversation. Rufe diese Tools nur auf, wenn das mit eurer Datenschutz-Vereinbarung vereinbar ist. order_stats liefert nur aggregierte Zahlen. |
| Requests an die Admin API | Nur an die konfigurierte SHOPWARE_URL. |
Dateien für media_upload_url |
Shopware lädt sie von der angegebenen URL, sie laufen nicht über den MCP-Server. |
| Zugangsdaten | Nur an den Shop, nie an Claude. |
Der Server enthält keine Telemetrie und keine weiteren externen Aufrufe. Die Wiki-Anbindung ist im Code vorhanden, wird aber nie aufgerufen.
SHOPWARE_URL mit https:// verwenden..env weitergegeben wurde.product_set_active aktivieren.