English Version

Zurück zur Übersicht

Sylius Admin: Technische Details

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

Aufbau des Plugins

Gesamtbild

graph TD
    A["Claude Code"] --> B["syliusadmin-stage-mcp"]
    A --> C["syliusadmin-prod-mcp"]
    B --> D["run.py mit SYLIUS_ENV_NAME=stage"]
    C --> E["run.py mit SYLIUS_ENV_NAME=prod"]
    D --> F["stage/.env"]
    E --> G["prod/.env"]
    D --> H["Sylius Stage Admin API"]
    E --> I["Sylius Prod Admin API"]

Beide Server laufen aus derselben Codebasis. Sie unterscheiden sich nur durch die Variable SYLIUS_ENV_NAME, die run.py in den Pfad der jeweiligen .env übersetzt. Der Server meldet sich gegenüber Claude als sylius-admin-<umgebung> und nennt die Umgebung in seinen Anweisungen.

Ablauf eines Tool-Aufrufs

sequenceDiagram
    participant C as "Claude"
    participant T as "Tool"
    participant K as "SyliusClient"
    participant S as "Sylius Admin API"

    C->>T: Tool-Aufruf mit Parametern
    T->>T: Parameter validieren
    T->>K: get, post, put, patch oder delete
    K->>K: Scope-Allowlist prüfen
    alt Pfad nicht erlaubt
        K-->>T: SyliusScopeError
        T-->>C: Fehlermeldung
    else Pfad erlaubt
        K->>S: Login falls kein gültiges Token
        S-->>K: JWT
        K->>S: Request mit Bearer-Token
        S-->>K: Antwort
        K-->>T: JSON
        T-->>C: Ergebnis
    end

Ablauf im Detail

1. Parameter prüfen: Jedes Tool validiert seine Eingaben, bevor ein Request entsteht (Codes, Längen, Wertebereiche, Pflichtkombinationen).
2. Scope prüfen: SyliusClient gleicht Methode und Pfad gegen die Allowlist ab. Außerdem lehnt er Formularfelder ab, die mit _method beginnen.
3. Authentifizieren: Das JWT kommt von POST /api/v2/admin/administrators/token, wird im Speicher gehalten und 30 Sekunden vor Ablauf neu geholt.
4. Request senden: Mit Authorization: Bearer ..., Accept: application/json und, falls konfiguriert, X-Stage-Api-Key. Das HTTP-Timeout beträgt 30 Sekunden.
5. Antwort auswerten: Statuscodes ab 400 werden zu SyliusApiError (mit Status, Methode, Pfad, Umgebung und höchstens 500 Zeichen Detail). Ein leerer Body oder 204 wird zu null.
6. Fehler übersetzen: Alle eigenen Fehlerklassen des Clients werden zentral in ToolError umgewandelt, damit Claude die ursprüngliche Meldung sieht statt eines allgemeinen Tool-Fehlers.

Besonderheiten

Angesprochene Admin-API-Ressourcen

Alle Pfade liegen unter /api/v2/admin/.

Server-Verzeichnisstruktur

servers/syliusadmin-server/
├── run.py                      # Einstiegspunkt, .env-Auswahl
└── src/syliusadmin/
    ├── server.py               # create_server()-Factory, Tool-Registrierung
    ├── config.py               # SyliusConfig aus der Umgebung
    ├── sylius_client.py        # HTTP-Client, JWT, Scope-Allowlist
    └── tools/
        ├── _errors.py          # SyliusError wird zu ToolError
        ├── _codes.py           # Code-Validierung
        ├── _translations.py    # Zusammenführen von Übersetzungen, SEO-Felder
        ├── products.py
        ├── variants.py
        ├── taxons.py
        ├── attributes.py
        ├── options.py
        ├── product_images.py
        ├── channels.py
        ├── countries.py
        ├── zones.py
        ├── shipping_categories.py
        ├── shipping_methods.py
        ├── tax_categories.py
        ├── marketplace_links.py
        └── custom_input_fields.py

Protokoll und Abhängigkeiten

Tools, die nur lesen, sind mit dem MCP-Hinweis read_only markiert. Schreibende Tools tragen die entsprechenden Hinweise, Ersetzungen und das Löschen von Marketplace-Links sind als destructive gekennzeichnet.