Shopware Admin: Technical details

Technical structure of the Shopware Admin MCP server: layers, request flow, directory structure, cache durations, error format, dependencies and development commands.

Deutsche Version

Back to overview

Shopware Admin: Technical details

This documentation always describes the current state of the main branch.

Overview

The server is a Node.js program written in TypeScript. It speaks the Model Context Protocol over stdio (standard input and output) and offers tools only. It reports claude-mcp-shopwareadmin as its server name. The reported version number is hard-coded and does not follow the package version.

Request flow

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

    C->>M: Tool call (for example product_get)
    M->>M: Validate input with Zod
    M->>A: Request access token
    alt Token still valid
        A-->>M: Token from memory
    else Token missing or expiring
        A->>S: POST /api/oauth/token
        S-->>A: Access token
        A-->>M: New token
    end
    M->>S: API request with bearer token
    alt Success
        S-->>M: JSON
        M-->>C: Result as JSON text
    else 401
        M->>A: Discard token
        M->>S: Retry once
    else 429
        M->>M: Wait and retry, at most three times
    else Error
        S-->>M: Error response
        M-->>C: Error with code
    end

Queries run through Shopware's search API (POST /api/search/<entity>) with filters, associations and aggregations. Writes go through single endpoints (PATCH, POST) and, for product updates, through the sync API (/api/_action/sync).

Layers and directories

src/
├── index.ts                  entry point, MCP server, tool dispatch, error handling
├── bootstrap.ts              load configuration, wire services
├── config/                   .env loader, content profiles (schema, loader, defaults)
├── application/schemas/      Zod schemas per tool area
├── core/
│   ├── domain/               entities and error types
│   └── services/             business logic per area
├── infrastructure/
│   ├── shopware/             OAuth2 authenticator and HTTP client
│   ├── cache/                in-memory cache with TTL
│   ├── logging/              logger to stderr
│   └── wikijs/               wiki service (currently without callers)
└── tools/
    ├── definitions.ts        tool descriptions for the tool list
    └── handlers/             handlers per area

The tool descriptions in definitions.ts are maintained by hand. Validation is governed by the Zod schemas, and the two differ in details. For IDs definitions.ts advertises the pattern ^[0-9a-f]{32}$, while Zod additionally accepts uppercase letters and UUIDs with hyphens and converts them to lowercase hex. For date values (format YYYY-MM-DD or with time) and mimeTypePrefix (format type/), on the other hand, Zod is stricter than the advertised JSON description.

Cache

The cache lives in the process's memory, holds at most 500 entries and removes expired entries every minute. The durations are fixed in the code and cannot be changed through environment variables.

Data	Duration
Product (single lookup by ID or product number)	5 minutes
Medium, flow, cross-selling (single lookup)	5 minutes
Order (single lookup)	2 minutes
Categories (list and single lookup), manufacturer list without search, property groups	10 minutes
Snippets, mail templates (single lookup)	10 minutes
Lists and searches for products, media, orders, flows, mail templates, SEO URLs	no cache

Changes made through the server remove the affected entries. Content profiles are loaded once at startup.

Error format

Domain errors arrive as JSON text with isError: true:

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

Code	Trigger
`AUTH_FAILED`	Token request rejected or timed out
`API_ERROR`	Error response or timeout from the Shopware API, `context.httpStatus` names the status
`RATE_LIMITED`	429 after three retries or the server's own test mail limit
`NOT_FOUND`	404 from the API
`INVALID_INPUT`	Unknown style, missing required value, schema violation (with `details` per field)
`PRODUCT_NUMBER_EXISTS`	Duplicate product number in `product_create`

Timeouts, the statuses 500, 502 and 503 and 429 count as retryable (recoverable: true). Tools that fetch a single record answer a miss with {"error": true, "message": "... not found"}. An unknown tool yields the text Unknown tool: <name>, any other error the text Error: <message>.

Dependencies

Package	Purpose
`@modelcontextprotocol/sdk`	MCP server and stdio transport
`zod`	Input validation and configuration schema
`zod-to-json-schema`	Runtime dependency according to `package.json`

Development dependencies are TypeScript, ESLint, Vitest, MSW (HTTP mocks in tests) and tsx.

Development

npm run typecheck   # check TypeScript
npm run lint        # ESLint
npm run build       # compile to dist/
npm run dev         # watch mode with tsx
npm test            # tests with Vitest

CI runs type check, lint, tests and build on Node.js 20 and 22. A new tool needs a Zod schema, a service method, a handler in the matching area under tools/handlers/, an entry in definitions.ts and tests.

Shutdown

On SIGINT and SIGTERM the server shuts down in an orderly way. Uncaught errors are logged, then the process exits.