Deutsche Version

Back to overview

Sylius Admin: Technical Details

This documentation always describes the latest published version.

Plugin layout

Overview

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

Both servers run from the same codebase. They differ only by the variable SYLIUS_ENV_NAME, which run.py translates into the path of the respective .env. The server introduces itself to Claude as sylius-admin-<environment> and names the environment in its instructions.

Flow of a tool call

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

    C->>T: Tool call with parameters
    T->>T: Validate parameters
    T->>K: get, post, put, patch or delete
    K->>K: Check scope allowlist
    alt Path not allowed
        K-->>T: SyliusScopeError
        T-->>C: Error message
    else Path allowed
        K->>S: Login if no valid token
        S-->>K: JWT
        K->>S: Request with bearer token
        S-->>K: Response
        K-->>T: JSON
        T-->>C: Result
    end

Flow in detail

1. Validate parameters: Every tool validates its inputs before a request is built (codes, lengths, value ranges, required combinations).
2. Check scope: SyliusClient matches method and path against the allowlist. It also rejects form fields starting with _method.
3. Authenticate: The JWT comes from POST /api/v2/admin/administrators/token, is kept in memory and fetched again 30 seconds before expiry.
4. Send the request: With Authorization: Bearer ..., Accept: application/json and, if configured, X-Stage-Api-Key. The HTTP timeout is 30 seconds.
5. Evaluate the response: Status codes of 400 and above become SyliusApiError (with status, method, path, environment and at most 500 characters of detail). An empty body or 204 becomes null.
6. Translate errors: All of the client's own error classes are converted centrally into ToolError, so Claude sees the original message instead of a generic tool error.

Special behavior

Admin API resources used

All paths are under /api/v2/admin/.

Server directory structure

servers/syliusadmin-server/
├── run.py                      # entry point, .env selection
└── src/syliusadmin/
    ├── server.py               # create_server() factory, tool registration
    ├── config.py               # SyliusConfig from the environment
    ├── sylius_client.py        # HTTP client, JWT, scope allowlist
    └── tools/
        ├── _errors.py          # SyliusError becomes ToolError
        ├── _codes.py           # code validation
        ├── _translations.py    # merging translations, SEO fields
        ├── 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

Protocol and dependencies

Read-only tools are marked with the MCP hint read_only. Writing tools carry the corresponding hints; replacements and the deletion of marketplace links are marked destructive.