Diese Dokumentation bezieht sich immer auf den aktuellen Stand des main-Branches.
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.
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).
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.
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.
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>.
| 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.
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.
Bei SIGINT und SIGTERM beendet sich der Server geordnet. Nicht abgefangene Fehler werden geloggt, danach endet der Prozess.