Sylius Admin: Installation

Sylius Admin Claude-Code-Plugin installieren: Marketplace hinzufügen, Plugin aktivieren, Setup-Skill ausführen, Zugangsdaten eintragen, Server prüfen, manuelle Installation ohne Plugin-System und Deinstallation.

English Version

Zurück zur Übersicht

Sylius Admin: Installation

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Voraussetzungen

Anforderung	Hinweise
Claude Code	Mit Plugin-Unterstützung (Marketplace)
Python	3.12 oder neuer (`requires-python = ">=3.12"`)
Sylius	2.2 mit erreichbarer Admin API (`/api/v2/admin/`)
Admin-User	Eigener Sylius-Admin-User für die API, siehe Konfiguration

Die Python-Abhängigkeiten (mcp, httpx, python-dotenv, anyio) installiert der Setup-Skill aus der requirements.txt des Plugins.

Installation

Als Claude-Code-Plugin (empfohlen)

Marketplace hinzufügen: claude plugin marketplace add markus-michalski/claude-plugin-syliusadmin
Das Plugin syliusadmin aus diesem Marketplace aktivieren.
Den Setup-Skill ausführen: /syliusadmin:setup
Zugangsdaten in beide .env-Dateien eintragen (siehe unten und Konfiguration).
Claude Code neu starten.

Der Setup-Skill erledigt folgende Schritte:

Schritt	Ergebnis
Python finden	Probiert `python3`, `python` und `py -3`, unter Windows zusätzlich bekannte Installationspfade
Version prüfen	Python 3.12 oder neuer
Venv anlegen	`~/.claude-plugin-syliusadmin/venv` (Windows: `%USERPROFILE%\.claude-plugin-syliusadmin\venv`)
Abhängigkeiten installieren	`pip install -r requirements.txt` aus dem Plugin-Verzeichnis
`.env`-Dateien anlegen	`~/.claude-plugin-syliusadmin/stage/.env` und `~/.claude-plugin-syliusadmin/prod/.env`, jeweils aus `.env.example`; in der Prod-Datei wird `SYLIUS_ENVIRONMENT=prod` gesetzt
Layout prüfen	Server-Modul importierbar, `bin/run-server` und beide `.env`-Dateien vorhanden

Der Skill trägt niemals Zugangsdaten für dich ein, er legt nur die Dateien an. Er läuft bei jedem Aufruf erneut und korrigiert dabei auch eine falsch beschriftete prod/.env, ist also zugleich der Reparaturweg.

Nach dem Setup registriert das Plugin zwei MCP-Server:

Server	Umgebung	Konfigurationsdatei
`syliusadmin-stage-mcp`	Stage	`~/.claude-plugin-syliusadmin/stage/.env`
`syliusadmin-prod-mcp`	Prod	`~/.claude-plugin-syliusadmin/prod/.env`

Direkt nach der Installation steht syliusadmin-prod-mcp auf failed. Das ist erwartet: Die prod/.env enthält noch keine echten Zugangsdaten. Erst nach dem Befüllen und einem Neustart wird auch der Prod-Server connected.

Der Starter bin/run-server ruft den Python-Interpreter aus ~/.claude-mcp-syliusadmin/venv auf (Windows: %USERPROFILE%\.claude-mcp-syliusadmin\venv), während der Setup-Skill das venv unter ~/.claude-plugin-syliusadmin/venv anlegt. Bleiben beide Server trotz befüllter .env-Dateien auf failed, fehlt das venv am vom Starter erwarteten Pfad. Lege es dort mit denselben Abhängigkeiten an, siehe Fehlerbehebung.

Manuell ohne Plugin-System

Dieser Weg verzichtet auf das Plugin-System. Es gibt dann keine Skills (Setup, Produkt-Wizard), der MCP-Server selbst funktioniert gleich.

mkdir -p ~/.claude/mcp-servers/syliusadmin-stage
cp -r servers/syliusadmin-server/src servers/syliusadmin-server/run.py requirements.txt \
  ~/.claude/mcp-servers/syliusadmin-stage/
cp .env ~/.claude/mcp-servers/syliusadmin-stage/.env
cd ~/.claude/mcp-servers/syliusadmin-stage && python3 -m venv venv && ./venv/bin/pip install -r requirements.txt

claude mcp add --scope user --transport stdio syliusadmin-stage -- \
  ~/.claude/mcp-servers/syliusadmin-stage/venv/bin/python3 \
  ~/.claude/mcp-servers/syliusadmin-stage/run.py

Für Prod wiederholst du die Schritte in einem eigenen Verzeichnis (zum Beispiel ~/.claude/mcp-servers/syliusadmin-prod/) mit SYLIUS_ENVIRONMENT=prod und den Prod-Zugangsdaten.

Ohne SYLIUS_ENV_NAME und SYLIUS_ENV_FILE liest run.py die .env direkt neben sich selbst.

Für die Entwicklung

Zum Ausführen der Tests reicht ein venv im Projektordner, ein MCP-Betrieb ist dafür nicht nötig:

python3 -m venv venv
./venv/bin/pip install -r requirements-dev.txt
cp .env.example .env
./venv/bin/python3 -m pytest

Installation prüfen

/mcp in Claude Code öffnen: syliusadmin-stage-mcp muss connected sein.
Ein lesendes Tool aufrufen lassen, zum Beispiel: "Liste mir die Channels des Shops." Das ruft list_channels auf.
Antwortet das Tool mit den Channel-Codes, sind Login und Verbindung in Ordnung.

Zugangsdaten und Neustart

Nach dem Eintragen der Zugangsdaten lädt Claude Code die MCP-Server beim nächsten Start neu. run.py liest die .env bei jedem Start und die Datei gewinnt gegen bereits gesetzte SYLIUS_*-Variablen im Prozess.

Deinstallation

Plugin in Claude Code deaktivieren beziehungsweise entfernen. Damit verschwinden beide MCP-Server und die Skills.
Den Ordner ~/.claude-plugin-syliusadmin/ löschen (Windows: %USERPROFILE%\.claude-plugin-syliusadmin). Er enthält das venv und beide .env-Dateien mit den Zugangsdaten.
Falls vorhanden, das venv am Starter-Pfad ~/.claude-mcp-syliusadmin/ löschen.
Bei manueller Installation: claude mcp remove --scope user syliusadmin-stage (und syliusadmin-prod) ausführen und das Verzeichnis unter ~/.claude/mcp-servers/ löschen.
Optional: den Sylius-Admin-User für die API im Shop löschen oder sperren.

Auf dem Sylius-Shop selbst bleibt nichts zurück, der Server installiert dort nichts.

Migration von einem manuellen Deployment

Lief der Server bisher als git clone unter ~/.claude/mcp-servers/syliusadmin-stage, geh so vor:

Inhalt der alten .env-Dateien sichern.
Plugin installieren und /syliusadmin:setup ausführen.
Gesicherte Zugangsdaten in die neuen .env-Dateien unter ~/.claude-plugin-syliusadmin/ eintragen.
Alte Registrierung entfernen, sonst existiert dieselbe Umgebung doppelt: claude mcp remove --scope user syliusadmin-stage (und -prod).
Den alten Checkout-Ordner löschen und dort nicht mehr git pull ausführen, weil run.py im Repo inzwischen unter servers/syliusadmin-server/ liegt.