Shopware Admin: Technische Details

Technischer Aufbau des Shopware Admin MCP-Servers: Schichten, Request-Ablauf, Verzeichnisstruktur, Cache-Laufzeiten, Fehlerformat, Abhängigkeiten und Entwicklungsbefehle.

English Version

Zurück zur Übersicht

Shopware Admin: Technische Details

Diese Dokumentation bezieht sich immer auf den aktuellen Stand des main-Branches.

Überblick

Der Server ist ein Node.js-Programm in TypeScript. Er spricht das Model Context Protocol über stdio (Standard-Ein- und Ausgabe) und bietet ausschließlich Tools an. Als Server-Name meldet er claude-mcp-shopwareadmin. Die gemeldete Versionsnummer ist im Code fest eingetragen und folgt nicht der Paketversion.

Request-Ablauf

sequenceDiagram
    participant C as Claude Code
    participant M as MCP-Server
    participant A as Authenticator
    participant S as Shopware Admin API

    C->>M: Tool-Aufruf (zum Beispiel product_get)
    M->>M: Eingabe mit Zod prüfen
    M->>A: Access-Token anfordern
    alt Token noch gültig
        A-->>M: Token aus dem Speicher
    else Token fehlt oder läuft ab
        A->>S: POST /api/oauth/token
        S-->>A: Access-Token
        A-->>M: neues Token
    end
    M->>S: API-Request mit Bearer-Token
    alt Erfolg
        S-->>M: JSON
        M-->>C: Ergebnis als JSON-Text
    else 401
        M->>A: Token verwerfen
        M->>S: einmal wiederholen
    else 429
        M->>M: warten und wiederholen, höchstens dreimal
    else Fehler
        S-->>M: Fehlerantwort
        M-->>C: Fehler mit Code
    end

Abfragen laufen über die Such-API von Shopware (POST /api/search/<entität>) mit Filtern, Assoziationen und Aggregationen. Geschrieben wird über Einzel-Endpunkte (PATCH, POST) und, bei Produkt-Updates, über die Sync-API (/api/_action/sync).

Schichten und Verzeichnisse

src/
├── index.ts                  Einstieg, MCP-Server, Tool-Verteilung, Fehlerbehandlung
├── bootstrap.ts              Konfiguration laden, Dienste verdrahten
├── config/                   .env-Lader, Content-Profile (Schema, Lader, Standardwerte)
├── application/schemas/      Zod-Schemas je Tool-Bereich
├── core/
│   ├── domain/               Entitäten und Fehlertypen
│   └── services/             Fachlogik je Bereich
├── infrastructure/
│   ├── shopware/             OAuth2-Authenticator und HTTP-Client
│   ├── cache/                In-Memory-Cache mit TTL
│   ├── logging/              Logger nach stderr
│   └── wikijs/               Wiki-Dienst (derzeit ohne Aufrufer)
└── tools/
    ├── definitions.ts        Tool-Beschreibungen für die Tool-Liste
    └── handlers/             Handler je Bereich

Die Tool-Beschreibungen in definitions.ts sind von Hand gepflegt. Maßgeblich für die Validierung sind die Zod-Schemas, und beide weichen in Einzelheiten voneinander ab. IDs bewirbt definitions.ts als Muster ^[0-9a-f]{32}$, Zod akzeptiert zusätzlich Großbuchstaben und UUIDs mit Bindestrichen und wandelt sie in kleingeschriebenes Hex um. Bei Datumswerten (Format YYYY-MM-DD oder mit Uhrzeit) und mimeTypePrefix (Format typ/) ist dagegen Zod strenger als die angebotene JSON-Beschreibung.

Cache

Der Cache liegt im Arbeitsspeicher des Prozesses, hat höchstens 500 Einträge und räumt abgelaufene Einträge jede Minute auf. Die Laufzeiten sind im Code fest vergeben und nicht über Umgebungsvariablen änderbar.

Daten	Laufzeit
Produkt (Einzelabruf nach ID oder Artikelnummer)	5 Minuten
Medium, Flow, Cross-Selling (Einzelabruf)	5 Minuten
Bestellung (Einzelabruf)	2 Minuten
Kategorien (Liste und Einzelabruf), Hersteller-Liste ohne Suche, Eigenschaftsgruppen	10 Minuten
Textbausteine, Mail-Templates (Einzelabruf)	10 Minuten
Listen und Suchen für Produkte, Medien, Bestellungen, Flows, Mail-Templates, SEO-URLs	kein Cache

Änderungen über den Server entfernen die betroffenen Einträge. Content-Profile werden einmalig beim Start geladen.

Fehlerformat

Fachliche Fehler kommen als JSON-Text mit isError: true:

{
  "error": true,
  "code": "NOT_FOUND",
  "message": "Resource not found: <Segment>",
  "recoverable": false,
  "suggestion": "Verify the resource exists",
  "context": {}
}

Code	Auslöser
`AUTH_FAILED`	Token-Anfrage abgelehnt oder Zeitüberschreitung
`API_ERROR`	Fehlerantwort oder Zeitüberschreitung der Shopware-API, `context.httpStatus` nennt den Status
`RATE_LIMITED`	429 nach drei Wiederholungen oder eigenes Test-Mail-Limit
`NOT_FOUND`	404 der API
`INVALID_INPUT`	Unbekannter Stil, fehlende Pflichtangabe, Schema-Verletzung (mit `details` je Feld)
`PRODUCT_NUMBER_EXISTS`	Doppelte Artikelnummer bei `product_create`

Als wiederholbar (recoverable: true) gelten Zeitüberschreitungen, die Status 500, 502 und 503 sowie 429. Tools, die einen einzelnen Datensatz abrufen, antworten bei fehlendem Treffer mit {"error": true, "message": "... not found"}. Ein unbekanntes Tool ergibt den Text Unknown tool: <Name>, jeder andere Fehler den Text Error: <Meldung>.

Abhängigkeiten

Paket	Zweck
`@modelcontextprotocol/sdk`	MCP-Server und stdio-Transport
`zod`	Eingabeprüfung und Konfigurations-Schema
`zod-to-json-schema`	Laufzeit-Abhängigkeit laut `package.json`

Entwicklungsabhängigkeiten sind TypeScript, ESLint, Vitest, MSW (HTTP-Mocks in Tests) und tsx.

Entwicklung

npm run typecheck   # TypeScript prüfen
npm run lint        # ESLint
npm run build       # nach dist/ kompilieren
npm run dev         # Watch-Modus mit tsx
npm test            # Tests mit Vitest

Die CI führt Typprüfung, Lint, Tests und Build auf Node.js 20 und 22 aus. Ein neues Tool braucht ein Zod-Schema, eine Service-Methode, einen Handler im passenden Bereich in tools/handlers/, einen Eintrag in definitions.ts und Tests.

Beenden

Bei SIGINT und SIGTERM beendet sich der Server geordnet. Nicht abgefangene Fehler werden geloggt, danach endet der Prozess.