Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.
Jede Server-Instanz bedient genau eine Sylius-Umgebung. Die Konfiguration kommt aus einer .env-Datei pro Umgebung, es gibt keine Einstellungen im Claude-Code-Manifest außer der Auswahl der Umgebung.
Diese Variablen stehen in der .env-Datei der jeweiligen Umgebung. Kopiere immer die mitgelieferte .env.example als Vorlage, statt eine Datei von Grund auf neu zu schreiben (siehe Hinweis unten).
| Variable | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
SYLIUS_ENVIRONMENT |
Ja | - | stage oder prod. Jeder andere Wert verhindert den Start. Die Vorlage enthält stage. |
SYLIUS_BASE_URL |
Ja | - | Basis-URL des Shops. Ein abschließender Schrägstrich wird entfernt. |
SYLIUS_ADMIN_EMAIL |
Ja | - | E-Mail-Adresse des Admin-Users für die API. |
SYLIUS_ADMIN_PASSWORD |
Ja | - | Passwort dieses Users. |
SYLIUS_API_KEY |
Nein | leer | Zusätzliches Shared Secret, das als Header X-Stage-Api-Key bei jedem Request mitgeschickt wird, auch beim Login. Nur für Stage; auf Prod leer lassen. |
SYLIUS_IMAGE_UPLOAD_BASE_DIR |
Nein | leer | Absoluter, existierender Pfad. Nur Dateien innerhalb dieses Verzeichnisses darf add_product_image beziehungsweise add_taxon_image hochladen. Leer bedeutet: Datei-Upload ist deaktiviert (cdn_url funktioniert trotzdem). |
Eine Variable, die in einer handgeschriebenen
.envganz fehlt (statt leer zu sein), erbt einen zufällig im Prozess gesetzten Wert. Deshalb immer von.env.examplekopieren, die beide optionalen Schlüssel explizit leer enthält.
run.py bestimmt beim Start, welche Datei geladen wird, in dieser Reihenfolge:
| Variable (Prozess) | Wirkung |
|---|---|
SYLIUS_ENV_FILE |
Absoluter Pfad zu einer vorhandenen Datei. Gewinnt, wenn beide Variablen gesetzt sind. Ein relativer Pfad oder eine fehlende Datei bricht den Start ab. |
SYLIUS_ENV_NAME |
stage oder prod. Lädt ~/.claude-plugin-syliusadmin/<name>/.env. Das Plugin setzt diese Variable für seine beiden Server in der .mcp.json. Ein anderer Wert oder eine fehlende Datei bricht den Start ab. |
| keine von beiden | Die .env direkt neben run.py (Verhalten der manuellen Installation). |
Die Datei wird mit Vorrang geladen: Werte aus der Datei überschreiben bereits im Prozess gesetzte SYLIUS_*-Variablen.
Passen
SYLIUS_ENV_NAMEundSYLIUS_ENVIRONMENTin der Datei nicht zusammen, verweigert der Server den Start. Eineprod-Registrierung kann sich so nie alsstagemelden, während sie in Wirklichkeit gegen den Live-Shop schreibt.
# ~/.claude-plugin-syliusadmin/stage/.env
SYLIUS_ENVIRONMENT=stage
SYLIUS_BASE_URL=https://stage.example.com
SYLIUS_ADMIN_EMAIL=api@example.com
SYLIUS_ADMIN_PASSWORD=...
SYLIUS_API_KEY=...
SYLIUS_IMAGE_UPLOAD_BASE_DIR=/home/dein-user/shop-bilder
# ~/.claude-plugin-syliusadmin/prod/.env
SYLIUS_ENVIRONMENT=prod
SYLIUS_BASE_URL=https://shop.example.com
SYLIUS_ADMIN_EMAIL=api@example.com
SYLIUS_ADMIN_PASSWORD=...
SYLIUS_API_KEY=
SYLIUS_IMAGE_UPLOAD_BASE_DIR=
Der Server meldet sich über POST /api/v2/admin/administrators/token mit E-Mail und Passwort an und bekommt ein JWT zurück. Dafür braucht er einen eigenen Admin-User.
php bin/console sylius:create-admin-user
Der User braucht zusätzlich die Rolle ROLE_API_ACCESS. ROLE_ADMINISTRATION_ACCESS (Zugriff auf das Admin-Panel) allein reicht für die Admin API nicht: Der Login klappt dann, jeder Tool-Aufruf scheitert aber mit HTTP 403. In der Community Edition gibt es dafür keine Oberfläche, die Rolle ergänzt du im Feld roles der Tabelle sylius_admin_user.
Granulare Admin-Rollen gibt es in Sylius nur in der kostenpflichtigen Plus-Edition. In der Community Edition ist jeder Admin-User technisch Voll-Admin. Die Beschränkung auf Katalog und Shop-Konfiguration kommt allein daher, dass der Server keine Bestell-, Kunden- oder Promotion-Tools hat und jeden Request gegen eine eigene Pfad-Allowlist prüft.
Den Standard-Demo-Admin solltest du auf produktiven Systemen entfernen und stattdessen einen eigenen API-User verwenden.
Ist die Stage-Instanz per Basic Auth geschützt, kollidiert diese mit dem JWT, weil beide den Authorization-Header brauchen. In dem Setup, für das der Server gebaut wurde, ist /api/v2/admin/ deshalb von Basic Auth ausgenommen und stattdessen mit einem geteilten Secret im Header X-Stage-Api-Key abgesichert. Trage dieses Secret in SYLIUS_API_KEY ein. Es muss exakt dem Wert entsprechen, den die Stage-Instanz erwartet.
Der Server schickt den Header bei jedem Request mit, sobald SYLIUS_API_KEY gesetzt ist, unabhängig von SYLIUS_ENVIRONMENT. Auf Prod lässt du die Variable leer.
SYLIUS_IMAGE_UPLOAD_BASE_DIR muss ein absoluter Pfad zu einem vorhandenen Verzeichnis sein. Relative Pfade im Tool-Aufruf werden gegen dieses Verzeichnis aufgelöst, alle Pfade müssen nach der Auflösung (inklusive Symlinks) darin liegen. Erlaubt sind .jpg, .jpeg, .png, .gif und .webp bis 10.000.000 Bytes.
Das Verzeichnis liegt auf dem Rechner, auf dem der MCP-Server läuft, nicht auf dem Shop-Server. Details und Grenzen stehen auf der Seite Sicherheit und Datenschutz.
Einige Tools sprechen Endpunkte von Sylius-Plugins an. Sie funktionieren nur, wenn das jeweilige Plugin im Shop installiert ist:
| Plugin im Shop | Betroffene Funktion |
|---|---|
sylius-seo-suite-pro |
SEO-Felder metaTitle, canonicalPathOverride, robotsIndex, robotsFollow in den Übersetzungen von Produkten und Kategorien |
sylius-cdn-product-images |
Parameter cdn_url bei add_product_image und add_taxon_image |
sylius-marketplace-redirect |
Die fünf Marketplace-Link-Tools |
sylius-product-custom-inputs |
Die zwei Tools für Eingabefeld-Definitionen |
Ohne das jeweilige Plugin antwortet Sylius mit einem Fehler (bei den SEO-Feldern wird der Schlüssel stillschweigend ignoriert, siehe Tools).