Sylius Admin: Tool-Referenz

Alle 55 Tools des Sylius-Admin-Servers mit Parametern: Produkte, Varianten, Kategorien, Attribute, Optionen, Bilder, Länder, Zonen, Versand, Steuerklassen und Plugin-Daten. Plus Schutzregeln und Besonderheiten.

English Version

Zurück zur Übersicht

Sylius Admin: Tool-Referenz

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

Der Server registriert 55 Tools. Claude Code stellt jedem Tool-Namen einen Präfix des jeweiligen MCP-Servers (syliusadmin-stage-mcp oder syliusadmin-prod-mcp) voran. Die Tabellen unten nennen die Namen ohne Präfix.

Übersicht

Kategorie	Tools	Anzahl
Produkte	`list_products`, `get_product`, `search_products`, `create_product`, `update_product`, `set_product_active`	6
Varianten und Preise	`list_variants`, `get_variant`, `add_variant`, `update_variant`, `update_variant_channel_pricing`	5
Kategorien (Taxons)	`list_taxons`, `get_taxon`, `create_taxon`, `update_taxon`	4
Attribute	`list_product_attributes`, `get_product_attribute`, `create_product_attribute`	3
Optionen	`list_product_options`, `get_product_option`, `create_product_option`	3
Bilder	`list_product_images`, `add_product_image`, `list_taxon_images`, `add_taxon_image`	4
Channels	`list_channels`	1
Länder	`list_countries`, `get_country`, `create_country`, `update_country`	4
Zonen	`list_zones`, `get_zone`, `create_zone`, `update_zone`	4
Versandkategorien	`list_shipping_categories`, `get_shipping_category`, `create_shipping_category`, `update_shipping_category`	4
Versandarten	`list_shipping_methods`, `get_shipping_method`, `create_shipping_method`, `update_shipping_method`, `archive_shipping_method`, `restore_shipping_method`	6
Steuerklassen	`list_tax_categories`, `get_tax_category`, `create_tax_category`, `update_tax_category`	4
Marketplace-Links (Plugin)	`list_product_marketplace_links`, `get_product_marketplace_link`, `create_product_marketplace_link`, `update_product_marketplace_link`, `delete_product_marketplace_link`	5
Eingabefelder (Plugin)	`list_product_custom_input_fields`, `get_product_custom_input_field`	2
Gesamt		55

Jede Liste ist paginiert: page (ab 1) und items_per_page (1 bis 100, Standard 30). Codes (Produkt, Variante, Kategorie und so weiter) dürfen nur Buchstaben, Ziffern, Unterstrich und Bindestrich enthalten und höchstens 255 Zeichen lang sein, sonst lehnt der Server den Aufruf ab, bevor etwas gesendet wird.

Produkte

Tool	Zweck	Pflichtparameter	Optionale Parameter
`list_products`	Produkte listen	-	`page`, `items_per_page`, `code` (Teilstring), `name` (Teilstring)
`get_product`	Ein Produkt lesen	`code`	-
`search_products`	Suche mit allen Filtern und Sortierung	-	`page`, `items_per_page`, `code`, `name`, `taxon_code`, `main_taxon_code`, `channel_code`, `sort_by` (`code`, `createdAt`, `name`), `sort_direction` (`asc`, `desc`), `locale` (Pflicht bei `sort_by=name`)
`create_product`	Produkt anlegen, immer deaktiviert	`code`, `channel_codes`, `translations`	`main_taxon_code`, `option_codes`
`update_product`	Produkt ändern, nur übergebene Felder	`code`	`channel_codes`, `translations`, `main_taxon_code`, `option_codes`, `enabled`
`set_product_active`	Produkt sichtbar oder unsichtbar schalten	`code`, `enabled`	-

Wichtige Regeln:

channel_codes ist bei create_product Pflicht und darf nicht leer sein: Ein Produkt ohne Channel ist in keinem Shop sichtbar.
translations ist je Locale (zum Beispiel de_DE) ein Objekt mit mindestens name (2 bis 255 Zeichen). Weitere Schlüssel: slug, description, shortDescription, metaKeywords, metaDescription (je höchstens 255 Zeichen bei Meta-Feldern) sowie die SEO-Felder unten.
Bei update_product werden translations pro Locale und Feld mit dem Bestand zusammengeführt; nicht genannte Locales bleiben unberührt. channel_codes und option_codes ersetzen dagegen die ganze Liste.
option_codes macht ein Produkt konfigurierbar. Ein leerer Wert entfernt alle Optionen, Sylius übernimmt das aber nur, solange das Produkt noch keine Variante hat; danach bleibt die alte Optionsliste ohne Fehlermeldung bestehen.
Aktivieren (enabled=true über set_product_active oder update_product) lehnt der Server ab, solange das Produkt keine Variante hat. Der Server liest dafür das Produkt vor dem Schreiben noch einmal.

SEO-Felder der Übersetzungen

Zusätzlich zu metaKeywords und metaDescription akzeptieren die Übersetzungen von Produkten und Kategorien die Felder des Plugins sylius-seo-suite-pro:

Feld	Regel
`metaTitle`	Text, höchstens 255 Zeichen, nicht leer; `null` entfernt den Override
`canonicalPathOverride`	Pfad dieses Shops mit genau einem führenden Schrägstrich, keine URL; höchstens 255 Zeichen
`robotsIndex`, `robotsFollow`	`true` oder `false`
`metaDescription` (nur Kategorien)	Höchstens 512 Zeichen

Diese Felder existieren nur, wo die Übersetzungs-Klassen des Shops die Traits des Plugins sylius-seo-suite-pro verwenden. Sonst ignoriert die API sie ohne Fehlermeldung: Ein erfolgreicher Aufruf beweist das Speichern nicht, lies die Übersetzung zurück.

Varianten und Preise

Tool	Zweck	Pflichtparameter	Optionale Parameter
`list_variants`	Varianten listen	-	`product_code`, `page`, `items_per_page`, `code`, `name`
`get_variant`	Eine Variante lesen	`code`	-
`add_variant`	Variante anlegen	`product_code`, `code`, `channel_pricings`	`translations`, `option_value_codes`, `enabled`, `tax_category_code`, `shipping_category_code`, `shipping_required`, `tracked`, `on_hand`, `weight`, `width`, `height`, `depth`, `position`
`update_variant`	Variante ändern, ohne Preise	`code`	`translations`, `option_value_codes`, `enabled`, `tax_category_code`, `shipping_category_code`, `shipping_required`, `tracked`, `on_hand`, `weight`, `width`, `height`, `depth`, `position`
`update_variant_channel_pricing`	Preis für genau einen Channel setzen	`code`, `channel_code`, `price`	`original_price`, `minimum_price`, `clear_original_price`, `clear_minimum_price`

Preise sind ganze Zahlen in der kleinsten Währungseinheit (Cent) und mindestens 0.
channel_pricings bei add_variant ist je Channel-Code ein Objekt mit price und optional originalPrice und minimumPrice. Es muss jeden Channel abdecken, dem das Produkt zugeordnet ist, sonst bricht der Server vor dem Schreiben mit einer klaren Meldung ab.
Hat das Produkt Optionen, braucht jede Variante option_value_codes mit genau einem Wert je Optionscode des Produkts, nicht mehr und nicht weniger. update_variant ersetzt die Optionswerte komplett.
update_variant_channel_pricing lässt alle anderen Channels sowie originalPrice und minimumPrice des Channels unberührt, außer du übergibst einen neuen Wert oder das passende clear_*-Flag.
Steuer- und Versandkategorie lassen sich mit diesen Tools zuweisen, aber nicht wieder entfernen. onHold (Reservierungen) ist nicht schreibbar. on_hand und die Maße müssen mindestens 0 sein.

Kategorien (Taxons)

Tool	Zweck	Pflichtparameter	Optionale Parameter
`list_taxons`	Kategorien listen, mit verschachtelten Kindern	-	`page`, `items_per_page`
`get_taxon`	Eine Kategorie lesen	`code`	-
`create_taxon`	Kategorie anlegen	`code`, `translations`	`parent_code`, `enabled` (Standard `true`)
`update_taxon`	Kategorie ändern oder verschieben	`code`	`translations`, `parent_code`, `clear_parent`, `enabled`, `position`

Es gibt keinen Filter nach Code oder Name: Zum Suchen blätterst du durch die Liste oder nutzt get_taxon.
parent_code und clear_parent schließen sich gegenseitig aus. Ein Name-Update erzeugt den Slug nicht neu.
Die Antwort von list_taxons wächst mit der Baumtiefe, nutze bei tiefen Kategoriebäumen ein kleines items_per_page.

Attribute und Optionen

Tool	Zweck	Pflichtparameter	Optionale Parameter
`list_product_attributes`	Attribut-Definitionen listen	-	`page`, `items_per_page`
`get_product_attribute`	Eine Attribut-Definition lesen	`code`	-
`create_product_attribute`	Attribut-Definition anlegen	`code`, `type`, `translations`	`translatable` (Standard `true`), `configuration`, `position`
`list_product_options`	Optionen listen	-	`page`, `items_per_page`
`get_product_option`	Eine Option mit Werten lesen	`code`	-
`create_product_option`	Option mit Werten anlegen	`code`, `translations`, `values`	`position`

Attribut-Typen, die der Server dokumentiert: text, textarea, checkbox, integer, float, percent, datetime, date, select. Der Typ wird nicht lokal geprüft; Sylius lehnt einen unbekannten Typ ab. Typ und Code sind nach dem Anlegen unveränderlich. select verlangt configuration mit choices.
Jeder Wert bei create_product_option hat einen eigenen code, der über alle Optionen hinweg eindeutig sein muss (zum Beispiel color_red statt red), und translations mit dem Schlüssel value.
Es gibt weder Update- noch Lösch-Tools für Attribute und Optionen.

Bilder

Tool	Zweck	Pflichtparameter	Optionale Parameter
`list_product_images`	Bilder eines Produkts listen	`product_code`	`page`, `items_per_page`, `variant_code`
`add_product_image`	Bild hinzufügen	`product_code` und genau eines von `image_path` oder `cdn_url`	`image_type`, `variant_codes` (nicht mit `cdn_url`)
`list_taxon_images`	Bilder einer Kategorie listen	`taxon_code`	`page`, `items_per_page`
`add_taxon_image`	Kategorie-Bild hinzufügen	`taxon_code` und genau eines von `image_path` oder `cdn_url`	`image_type`

image_path: Der Server liest die Datei lokal und lädt die Bytes per Multipart-Upload hoch. Voraussetzung ist SYLIUS_IMAGE_UPLOAD_BASE_DIR, die Datei muss darin liegen, .jpg, .jpeg, .png, .gif oder .webp sein und höchstens 10.000.000 Bytes haben.
cdn_url: Ein Bild, das schon auf dem CDN liegt. Es wird nur die http(s)-URL (höchstens 255 Zeichen) gespeichert, es wird nichts hochgeladen und keine lokale Datei gelesen. Das setzt das Shop-Plugin sylius-cdn-product-images voraus.
Bilder lassen sich über diesen Server nicht ändern oder löschen.

Channels, Länder, Zonen

Tool	Zweck	Pflichtparameter	Optionale Parameter
`list_channels`	Channel-Codes nachschlagen (nur lesen)	-	-
`list_countries`	Länder listen	-	`page`, `items_per_page`
`get_country`	Land lesen	`code`	-
`create_country`	Land registrieren	`code`	`enabled` (Standard `true`)
`update_country`	Land aktivieren oder deaktivieren	`code`, `enabled`	-
`list_zones`	Zonen listen	-	`page`, `items_per_page`
`get_zone`	Zone lesen	`code`	-
`create_zone`	Zone anlegen	`code`, `name`, `type`, `members`	`scope` (Standard `all`), `priority` (Standard 0)
`update_zone`	Zone ändern	`code`	`name`, `members`, `priority`

Länder haben keinen Namen, den die API schreiben lässt; update_country schaltet nur enabled.
type einer Zone ist country, province oder zone und bestimmt, was members enthält. type, scope und code sind nach dem Anlegen unveränderlich. members ersetzt bei update_zone die ganze Liste und darf nicht leer sein.

Versandkategorien und Versandarten

Tool	Zweck	Pflichtparameter	Optionale Parameter
`list_shipping_categories`	Versandkategorien listen	-	`page`, `items_per_page`
`get_shipping_category`	Eine Kategorie lesen	`code`	-
`create_shipping_category`	Kategorie anlegen	`code`, `name`	`description`
`update_shipping_category`	Kategorie ändern	`code`	`name`, `description`
`list_shipping_methods`	Versandarten listen	-	`page`, `items_per_page`, `archived`
`get_shipping_method`	Versandart lesen	`code`	-
`create_shipping_method`	Versandart anlegen	`code`, `zone_code`, `calculator`, `translations`	`configuration`, `channel_codes`, `rules`, `enabled` (Standard `true`), `position`, `min_delivery_time_days`, `max_delivery_time_days`
`update_shipping_method`	Versandart ändern	`code`	`zone_code`, `calculator`, `configuration`, `translations`, `channel_codes`, `rules`, `enabled`, `position`, `min_delivery_time_days`, `max_delivery_time_days`
`archive_shipping_method`	Versandart archivieren (statt löschen)	`code`	-
`restore_shipping_method`	Archivierte Versandart wiederherstellen	`code`	-

Versandkategorien sind nicht übersetzbar (name und description sind einfache Felder) und lassen sich in dieser Sylius-Version nicht über die API mit einer Versandart verknüpfen.
calculator und rules[].type werden nicht gegen eine feste Liste geprüft, weil Sylius' Registry erweiterbar ist; Sylius selbst lehnt unbekannte Werte ab. Bekannt sind die Berechner flat_rate, per_unit_rate (beide mit Betrag je Channel) und free (ohne Konfiguration).
configuration und kanalabhängige Regeln brauchen einen Eintrag für jeden Channel des Shops, nicht nur für die zugeordneten, zum Beispiel {"WEB": {"amount": 500}} (Betrag in Cent).
Bei update_shipping_method ersetzen channel_codes, rules und configuration jeweils den kompletten Bestand, translations werden je Locale und Feld zusammengeführt.
Die Lieferzeit-Angaben liegen zwischen 0 und 1000 Tagen, das Maximum darf nicht unter dem Minimum liegen.

Steuerklassen

Tool	Zweck	Pflichtparameter	Optionale Parameter
`list_tax_categories`	Steuerklassen listen	-	`page`, `items_per_page`, `code`, `name` (je Teilstring, ohne Groß-/Kleinschreibung)
`get_tax_category`	Steuerklasse lesen	`code`	-
`create_tax_category`	Steuerklasse anlegen	`code`, `name`	`description`
`update_tax_category`	Name oder Beschreibung ändern	`code`	`name`, `description`

Der Code einer Steuerklasse ist der Wert für tax_category_code bei Varianten. Steuersätze (Tax Rates) verwaltet der Server bewusst nicht.

Daten von Shop-Plugins

Tool	Zweck	Pflichtparameter	Optionale Parameter
`list_product_marketplace_links`	Marketplace-Links listen	-	`product_code`, `page`, `items_per_page`
`get_product_marketplace_link`	Link lesen	`link_id` (numerisch)	-
`create_product_marketplace_link`	Link anlegen	`product_code`, `reference`	`type` (`amazon` oder `shopware_store`), `amazon_domain`
`update_product_marketplace_link`	Link ändern	`link_id`	`reference`, `type`, `amazon_domain`, `clear_amazon_domain`
`delete_product_marketplace_link`	Link entfernen	`link_id`	-
`list_product_custom_input_fields`	Eingabefeld-Definitionen listen	-	`product_code`, `page`, `items_per_page`
`get_product_custom_input_field`	Definition lesen	`field_id` (numerisch)	-

Ein Marketplace-Link schickt Käufer eines Produkts zu Amazon oder zum Shopware Store statt in den Warenkorb. Ein Produkt hat höchstens einen Link. reference ist bei Amazon die ASIN (10 Zeichen), bei shopware_store eine https://store.shopware.com/...-URL. Gültige Amazon-Domains: de, com, co.uk, fr, it, es, nl, pl, se, ca. Das Produkt eines Links ist nur beim Anlegen setzbar.
Eingabefeld-Definitionen (zum Beispiel Gravurtext, Datum, Auswahl) sind nur lesbar; Anlage und Änderung geschehen im Sylius-Admin.

Was die Tools nicht tun

Bereich	Verhalten
Löschen	Der einzige Löschvorgang ist `delete_product_marketplace_link`. Der Client lehnt `DELETE` auf allen anderen Ressourcen ab, auch wenn die API es anbieten würde. Versandarten werden archiviert.
Bestellungen, Kunden, Promotions	Keine Tools, und die Pfad-Allowlist blockiert sie zusätzlich.
Channels	Nur lesen.
Rollback	Es gibt keinen. Bereits angelegte Objekte bleiben bestehen, wenn eine spätere Operation einer Reihe scheitert.