Content
# shopware-dev-mcp
An MCP server for exploring Shopware Admin API and Store API contracts without having to manually piece together routes, auth requirements, and multi-step workflows.
It is built to help developers who get stuck on questions like:
- Which route do I actually need?
- Is this Admin API or Store API?
- What request shape should I start with?
- Why does this flow fail even though one step worked?
- How do I chain these calls together without guessing?
## Quick Start
This server runs over MCP stdio.
The fastest way to try it locally is:
```bash
go run .
```
That starts the MCP server on stdio for an MCP client to connect to. It does not start an HTTP server.
### Requirements
- Go 1.26+
- launch the server from the repository root, or set absolute file paths in the environment
### Offline mode with bundled files
The server includes bundled Shopware contract data in `data/` and will use those files by default when they are available from the repository root.
Example:
```bash
go run .
```
This is the easiest setup for exploring the server without live Shopware credentials.
If you launch the server outside the repository root, set absolute `SHOPWARE_*_FILE` paths explicitly.
### Live mode against a Shopware instance
If you want live Shopware data, set:
```bash
export SHOPWARE_BASE_URL="https://your-shopware.example"
export SHOPWARE_ADMIN_TOKEN="..."
export SHOPWARE_STORE_ACCESS_KEY="..."
export SHOPWARE_PREFER_LIVE_DATA="true"
go run .
```
You can also combine live access with file fallbacks by setting both the live credentials and the file-path variables.
### MCP client example
Your MCP client needs to start the server from this repository and pass the environment variables above.
Example shape:
```json
{
"mcpServers": {
"shopware-dev": {
"command": "go",
"args": ["run", "."],
"cwd": "/absolute/path/to/shopware-dev-mcp"
}
}
}
```
If you launch from another working directory, add the file-path env vars explicitly.
If you build the binary first, you can replace `command` and `args` with the compiled executable path.
### First prompts to try
Once the server is connected in your MCP client, start with:
- `explain_flow` for `create a product and complete checkout`
- `explain_flow` for `investigate search criteria for product and category`
- `find_routes` with `create product`
- `describe_route` for a route returned by `find_routes`
## What This Server Does
This server combines three things:
1. Shopware API contract discovery
2. request/example generation
3. curated workflow guidance and diagnostics for common multi-step developer tasks
It can answer both low-level and high-level questions:
- low-level:
- find a route
- describe a route
- analyze the OpenAPI spec
- analyze Product/Category search-capability gaps
- assess workflow support against the spec
- generate a flow-aware checklist and request pack
- export an assessment report for review or docs work
- explain auth
- generate a request example
- high-level:
- explain how to create a product and complete checkout
- explain how to make a product discoverable in Store API
- explain how to investigate search criteria for Product and Category
- explain how customer registration, login, and order history fit together
- explain how to manage order state transitions and refunds
## What It Contains
### Source code
- [main.go](main.go)
The MCP server implementation and tool behavior
- [main_test.go](main_test.go)
Regression tests for route ranking, flow selection, and real OpenAPI-backed behavior
### Bundled contract data
- [data/admin-openapi.json](data/admin-openapi.json)
- [data/store-openapi.json](data/store-openapi.json)
- [data/admin-routes.json](data/admin-routes.json)
- [data/store-routes.json](data/store-routes.json)
- [data/entity-schema.json](data/entity-schema.json)
These files let the server work even without live Shopware credentials, and they are also used in tests.
They are also the default runtime fallback when the server is launched from the repository root.
### Curated developer flows
- [data/flows/README.md](data/flows/README.md)
- [data/flows/create_product_and_complete_checkout.json](data/flows/create_product_and_complete_checkout.json)
- [data/flows/catalog_setup_for_real_discoverability.json](data/flows/catalog_setup_for_real_discoverability.json)
- [data/flows/investigate_search_criteria_for_product_and_category.json](data/flows/investigate_search_criteria_for_product_and_category.json)
- [data/flows/customer_registration_to_order_history.json](data/flows/customer_registration_to_order_history.json)
- [data/flows/manage_order_state_and_refund.json](data/flows/manage_order_state_and_refund.json)
These flow files are human-readable artifacts you can inspect directly, and they are also loaded by the `explain_flow` MCP tool at runtime.
They also power flow scoring, checklist generation, request-pack generation, and workflow-level assessment output.
## MCP Tools
The server exposes tools for route discovery, contract inspection, examples, and workflow guidance.
### Discovery and inspection
- `list_admin_routes`
List Shopware Admin API routes
- `list_store_routes`
List Shopware Store API routes
- `get_admin_openapi`
Return the Admin API OpenAPI document
- `get_store_openapi`
Return the Store API OpenAPI document
- `get_entity_schema`
Return Shopware entity schema metadata
- `find_routes`
Search routes using ranking, confidence, and match reasons
- `describe_route`
Describe a route with method, parameters, request body, responses, confidence, and match reason
- `analyze_openapi`
Run structural diagnostics and workflow-support heuristics against Shopware OpenAPI data, including an overall score, rating, and score breakdown
- `analyze_search_capabilities`
Assess how discoverable Product and Category search capabilities are in the contract, including searchable/filterable/sortable metadata gaps and term-vs-filter clarity
- `assess_workflow_support`
Score curated workflows against the current contract and report route coverage, missing routes, weak documentation, hidden-prerequisite steps, and flow-to-contract gaps
- `generate_flow_checklist`
Turn a curated workflow into a step-by-step manual execution checklist with request examples, variable handoff hints, and route details
- `generate_flow_request_pack`
Generate a flow-aware request pack with per-step starter payloads, example requests, and evolving variable handoff context
- `export_assessment_report`
Combine OpenAPI analysis, workflow support assessment, and checklist output into a stable JSON or Markdown report
### Helpers
- `generate_criteria_payload`
Generate starter Criteria payloads for Admin API search tasks
- `generate_api_request_example`
Generate `curl` or JavaScript examples for a route
- `explain_surface`
Explain whether a use case belongs in Admin API, Store API, or extension work
- `explain_auth`
Explain likely authentication requirements
### Curated workflow tool
- `explain_flow`
Select a curated workflow from `data/flows/*.json`, enrich it with route metadata from OpenAPI, and return a structured sequence of steps
## How It Works
### Route discovery
`find_routes` and `describe_route` do more than plain substring matching.
They now use:
- normalized route matching
- token matching
- verb-to-method intent
- entity-aware ranking
- path-like query boosts
- confidence values
- match reasons
That means queries like:
- `create product`
- `checkout order`
- `search product manufacturer`
should produce more useful top results than raw text matching alone.
### Workflow guidance
The flow-driven tools like `explain_flow`, `generate_flow_checklist`, and `generate_flow_request_pack` do this:
1. load all curated flow files from `data/flows/`
2. score them against the incoming use case with weighted trigger, token, name, summary, and step relevance
3. choose the best matching flow
4. enrich each step with route details from Admin or Store OpenAPI
5. return the combined structured result
So the server is not generating workflows from scratch every time. It is selecting curated guidance and grounding it in the current Shopware contract data.
## Auth Model
### Admin API
- uses `Authorization: Bearer <token>`
### Store API
- uses `sw-access-key`
The server can work from file-based fallback data, or from live Shopware if credentials are configured.
## Environment Variables
The server reads configuration from environment variables.
### Live Shopware settings
- `SHOPWARE_BASE_URL`
- `SHOPWARE_ADMIN_TOKEN`
- `SHOPWARE_STORE_ACCESS_KEY`
- `SHOPWARE_PREFER_LIVE_DATA`
`SHOPWARE_PREFER_LIVE_DATA=true` tells the server to try the live Shopware instance before any configured file fallback.
### File fallback settings
- `SHOPWARE_ADMIN_OPENAPI_FILE`
- `SHOPWARE_STORE_OPENAPI_FILE`
- `SHOPWARE_ENTITY_SCHEMA_FILE`
- `SHOPWARE_ADMIN_ROUTES_FILE`
- `SHOPWARE_STORE_ROUTES_FILE`
Use absolute paths when possible. If you use relative paths, they are resolved from the process working directory.
You only need to set these explicitly when:
- you want to override the bundled files
- you launch the server outside the repository root
Example:
```bash
export SHOPWARE_ADMIN_OPENAPI_FILE="$PWD/data/admin-openapi.json"
export SHOPWARE_STORE_OPENAPI_FILE="$PWD/data/store-openapi.json"
export SHOPWARE_ENTITY_SCHEMA_FILE="$PWD/data/entity-schema.json"
export SHOPWARE_ADMIN_ROUTES_FILE="$PWD/data/admin-routes.json"
export SHOPWARE_STORE_ROUTES_FILE="$PWD/data/store-routes.json"
```
### Important path note
Curated workflow files are loaded from `data/flows/` at runtime.
That means your MCP client should either:
- launch the server with `cwd` set to the repository root
- or use a wrapper script/binary setup that preserves the repository-root working directory
## How To Use
This is the simplest practical sequence.
### 1. Start with the use case
Describe what you are trying to do in plain language.
Examples:
- `create a product and complete checkout`
- `make sure a product is visible in the sales channel`
- `investigate search criteria for product and category`
- `refund an order and update its state`
### 2. Ask `explain_surface`
Use this when you are unsure whether the task belongs in:
- Admin API
- Store API
- plugin/app/extension work
### 3. Ask `explain_flow`
If the task is a known workflow, this should be your main entry point.
It gives:
- summary
- ordered steps
- prerequisites
- common failure reasons
- diagnostics
- enriched route details where available
If you want the same workflow in a more execution-oriented shape, follow it with:
- `generate_flow_checklist`
- `generate_flow_request_pack`
### 4. Drill down with `find_routes`
If you need to inspect the exact available routes for a step, use `find_routes`.
Examples:
- `create product`
- `search product manufacturer`
- `checkout order`
- `order transaction state`
### 5. Inspect exact routes with `describe_route`
Use this to confirm:
- method
- route
- request body
- parameters
- response shape
### 6. Generate a starter request
Use:
- `generate_api_request_example`
- `generate_criteria_payload`
- `generate_flow_request_pack`
This gives you a concrete first request instead of a blank page.
### 7. Debug failures
If a chain still fails:
- check `explain_auth`
- check `explain_flow` failure reasons
- verify the route with `describe_route`
- compare Admin-side existence with Store-side visibility where relevant
- run `analyze_openapi` when you suspect the contract itself is incomplete, weakly described, or missing workflow-critical metadata
- run `analyze_search_capabilities` when you want a focused read on Product/Category search discoverability, field-capability metadata gaps, and term-vs-filter ambiguity
- run `assess_workflow_support` when you want to know how well the current contract supports the workflows you care about
- run `generate_flow_checklist` when you want an actionable manual sequence for executing a workflow step by step
- run `generate_flow_request_pack` when you want the actual starter requests for each step in a curated flow
- run `export_assessment_report` when you want a shareable artifact for docs, product review, or contract assessment
## Recommended Usage Patterns
### If you are lost in a workflow
Use:
1. `explain_flow`
2. `describe_route`
3. `generate_flow_request_pack`
4. `generate_api_request_example`
### If you only know the entity or action
Use:
1. `find_routes`
2. `describe_route`
### If you are debugging Criteria
Use:
1. `explain_flow`
2. `generate_criteria_payload`
3. `get_entity_schema`
4. `analyze_search_capabilities`
5. `describe_route`
## Manual Testing
Because the curated workflows now live in files, you can test them in two ways:
### Through MCP
Call the flow-oriented tools with natural-language use cases:
- `explain_flow`
- `generate_flow_checklist`
- `generate_flow_request_pack`
- `assess_workflow_support`
### Directly from the repo
Open the JSON files in [data/flows](data/flows) and follow the described steps manually.
This is useful when you want to:
- review workflow content
- edit triggers
- refine diagnostics
- compare the written flow to actual Shopware behavior
## Testing
Run:
```bash
GOCACHE=/tmp/shopware-dev-mcp-gocache go test ./...
```
The tests cover:
- route ranking behavior
- exact route description behavior
- curated flow loading
- flow enrichment against bundled OpenAPI data
- flow request-pack generation
- real-schema regression cases for Shopware Admin and Store APIs
## Current Limitations
- Curated flows are intentionally selective, not exhaustive
- Flow matching is now weighted and more resilient than plain trigger matching, but it is still heuristic and may need tuning as more workflows are added
- The server can now diagnose missing search-capability metadata, but it still cannot invent contract-level searchable/filterable/sortable fields that the Shopware spec does not expose
- Some workflow steps are still guidance-first because Shopware prerequisites are not always explicit in OpenAPI alone
## Best Fit
This server is best for:
- developers integrating with Shopware APIs
- people learning the difference between Admin API and Store API
- debugging chained API workflows
- reducing trial-and-error for common Shopware tasks
It is especially useful when raw route docs exist, but the sequence and hidden prerequisites are what actually block progress.
