Skip to content

Commit 63a01d7

Browse files
sushmanguptasushmangupta
committed
Update Shopware MCP docs
1 parent b39f2af commit 63a01d7

2 files changed

Lines changed: 131 additions & 127 deletions

File tree

‎products/tools/mcp-server/mcp-concepts.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ nav:
77

88
# MCP Concepts
99

10-
The Model Context Protocol (MCP) defines three building blocks that servers can expose: **tools**, **resources**, and **prompts**. Knowing what each one does and when to use it is the starting point for working with Shopware's MCP server or building your own extensions.
10+
MCP defines three building blocks that servers can expose: **tools**, **resources**, and **prompts**. Knowing what each one does and when to use it is the starting point for working with Shopware's MCP server or building your own extensions.
1111

1212
The full specification is available at [modelcontextprotocol.io](https://modelcontextprotocol.io/specification/).
1313

‎products/tools/mcp-server/sample-implementation.md‎

Lines changed: 130 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1,184 +1,200 @@
11
---
22
nav:
3-
title: Build an AI Merchant Assistant
3+
title: Build an AI Catalog Quality Assistant
44
position: 15
55

66
---
77

8-
9-
# Build an AI Merchant Assistant using the Shopware Admin MCP Server
8+
# Build an AI Catalog Quality Assistant using the Shopware Admin MCP Server
109

1110
## Overview
1211

13-
The Shopware Admin MCP Server enables AI agents to interact with Shopware MCP. Instead of integrating directly with the Shopware Administration API, AI clients discover and execute Shopware capabilities exposed by the MCP Server.
14-
15-
In this tutorial, you'll build an AI-powered merchant assistant that can perform common administrative tasks through natural language while abiding by Shopware's authentication and authorization model.
12+
In this tutorial, you'll build an AI-powered catalog quality assistant that helps merchants identify and improve incomplete or inconsistent product data using the Shopware Admin MCP Server.
1613

17-
At the end of this tutorial, your assistant will be able to:
14+
Instead of implementing custom integrations against the Shopware Administration API, you'll use the Shopware Admin MCP Server to expose Shopware capabilities to any MCP-compatible AI client.
1815

19-
- Connect to a Shopware instance
20-
- Discover available MCP capabilities
21-
- Retrieve Shopware entities
22-
- Execute merchant operations
23-
- Abide Shopware ACL permissions
24-
- Execute write operations safely
16+
The assistant will help merchants maintain a high-quality product catalog by identifying missing or incomplete product information and enriching it using AI.
2517

2618
## Use case
2719

28-
You're developing an AI-powered administration assistant for a Shopware project.
20+
Catalog quality has a direct impact on customer experience, search relevance, and conversion rates. As product catalogs grow, manually identifying and correcting incomplete product data becomes increasingly time-consuming.
2921

30-
Instead of implementing custom integrations against the Shopware Administration API, you'll use the `shopware-admin-mcp` server to expose Shopware capabilities to any MCP-compatible AI client.
22+
In this tutorial, you'll build an AI assistant that can help merchants:
3123

32-
The resulting assistant can help merchants perform administrative tasks such as:
24+
- Identify products without descriptions.
25+
- Find products missing images.
26+
- Detect missing SEO metadata.
27+
- Identify incomplete product attributes.
28+
- Review inconsistent catalog data.
29+
- Generate or improve product descriptions.
30+
- Enrich missing catalog information.
31+
- Safely apply bulk updates after validation.
3332

34-
- Searching products
35-
- Retrieving order information
36-
- Updating product data
37-
- Reviewing inventory
38-
- Managing media
39-
- Generating reports
40-
41-
Because the assistant communicates through the Shopware MCP Server, all requests follow Shopware's authentication, authorization, and extension mechanisms.
33+
The assistant communicates with Shopware through the Shopware Admin MCP Server and performs all operations using the authenticated user's permissions.
4234

4335
# What you'll build
4436

45-
By the end of this tutorial, your architecture will look like this:
37+
By the end of this tutorial, you'll have an AI assistant capable of:
38+
39+
- Connecting to the Shopware Admin MCP Server.
40+
- Discovering available MCP capabilities.
41+
- Searching and retrieving Shopware entities.
42+
- Identifying catalog quality issues.
43+
- Enriching catalog data.
44+
- Previewing changes using Dry Run.
45+
- Applying validated updates.
46+
47+
# Prerequisites
48+
49+
Before you begin, ensure you have:
50+
51+
- Shopware **6.7.11.0** or later
52+
- Shopware Admin MCP Server configured
53+
- API credentials with appropriate permissions
54+
- An MCP-compatible AI client (Claude Desktop, Cursor, Codex, ChatGPT, or another compatible client)
55+
56+
If you haven't configured the Shopware Admin MCP Server yet, complete the following guides first:
57+
58+
- Install the Shopware Admin MCP Server
59+
- Configure Authentication
60+
61+
# Architecture
4662

4763
```text
4864
Merchant
4965
50-
↓
66+
│
67+
68+
▼
5169
52-
Claude Desktop / Cursor / Codex
70+
AI Client
71+
(Claude, Cursor, Codex, ...)
5372
54-
↓
73+
│
74+
75+
▼
5576
5677
Shopware Admin MCP Server
5778
58-
↓
79+
│
80+
81+
▼
5982
6083
Shopware Administration API
6184
62-
↓
85+
│
86+
87+
▼
6388
6489
Shopware Core
6590
```
6691

67-
The assistant communicates with Shopware through MCP instead of calling the Administration API directly.
92+
The Shopware Admin MCP Server exposes Shopware capabilities as MCP Tools, Resources, and Prompts that AI clients can discover automatically.
6893

69-
# Prerequisites
94+
# Step 1 — Connect your AI client
7095

71-
Before you begin, ensure you have:
96+
Connect your preferred MCP-compatible AI client to the Shopware Admin MCP Server.
7297

73-
- Shopware **6.7.11.0** or later
74-
- [Shopware Admin MCP Server](https://github.com/shopware/shopware-admin-mcp)
75-
- API credentials
76-
- An MCP-compatible AI client
77-
- Access to the Shopware Administration
98+
After connecting, verify that the client successfully discovers the Shopware MCP Server and its available capabilities.
7899

79-
If you haven't configured the MCP Server yet, complete:
100+
# Step 2 — Discover available capabilities
80101

81-
- Install the Shopware Admin MCP Server
82-
- Configure Authentication
102+
Once connected, the AI client automatically retrieves the capabilities exposed by the Shopware Admin MCP Server.
83103

84-
# Step 1 — Install the Shopware Admin MCP Server
104+
These include:
85105

86-
Follow the installation guide:
106+
| Capability | Description |
107+
|------------|-------------|
108+
| Tools | Execute Shopware operations |
109+
| Resources | Access Shopware reference information |
110+
| Prompts | Provide Shopware-specific context |
87111

88-
[Install the Shopware Admin MCP Server](https://github.com/shopware/shopware-admin-mcp#installation)
112+
The available capabilities depend on the authenticated user, installed extensions, and configured permissions.
89113

90-
Once installed, verify that the MCP endpoint is available.
114+
# Step 3 — Identify catalog quality issues
91115

92-
# Step 2 — Configure authentication
116+
Ask your assistant to analyze your product catalog.
93117

94-
Configure your preferred authentication method.
118+
Example prompts:
95119

96-
Supported methods include:
120+
> Find all products without descriptions.
97121
98-
- Bearer Token
99-
- SW Access Key
122+
> Find products missing images.
100123
101-
The authenticated user determines which MCP capabilities are available.
124+
> List products without SEO metadata.
102125
103-
# Step 3 — Connect an MCP-compatible AI client
126+
> Identify products with missing manufacturer information.
104127
105-
Connect your preferred AI client.
128+
> Show products that are missing required attributes.
106129
107-
Supported examples include:
130+
The assistant discovers the appropriate MCP tools and retrieves the requested information from Shopware.
108131

109-
- Claude Desktop
110-
- Cursor
111-
- Codex
112-
- Shopware Copilot
132+
# Step 4 — Enrich catalog data
113133

114-
Once connected, verify that the client discovers the Shopware MCP Server.
134+
Once quality issues have been identified, ask the assistant to generate or improve the missing information.
115135

116-
# Step 4 — Discover available Shopware capabilities
136+
Examples:
117137

118-
After establishing the connection, the AI client automatically discovers the capabilities exposed by the Shopware MCP Server.
138+
> Generate descriptions for products without descriptions.
119139
120-
These include:
140+
> Create SEO titles and meta descriptions for products missing metadata.
121141
122-
| Capability | Description |
123-
|------------|-------------|
124-
| Tools | Execute Shopware operations |
125-
| Resources | Access Shopware reference information |
126-
| Prompts | Provide Shopware-specific guidance |
142+
> Suggest alternative text for product images.
127143
128-
The available capabilities depend on:
144+
> Improve existing product descriptions based on product specifications.
129145
130-
- Installed extensions
131-
- Authenticated user
132-
- Configured allowlists
146+
The generated content can be reviewed before applying any changes.
133147

134-
# Step 5 — Execute merchant operations
148+
# Step 5 — Validate changes
135149

136-
Your assistant can now perform merchant operations using natural language.
150+
Before modifying Shopware data, execute the operation using **Dry Run** mode.
137151

138-
Example prompts:
152+
Dry Run validates:
153+
154+
- User permissions
155+
- Entity resolution
156+
- Operation parameters
157+
- Expected changes
139158

140-
> Show products that are currently out of stock.
159+
without updating any Shopware data.
141160

142-
> List all pending orders.
161+
Review the generated changes before continuing.
143162

144-
> Find products without descriptions.
163+
# Step 6 — Apply updates
145164

146-
The MCP Server automatically discovers the appropriate tools and executes the requested operations.
165+
Once you've reviewed the proposed changes, execute the update.
147166

148-
# Step 6 — Execute write operations safely
167+
Example:
149168

150-
Write operations support **Dry Run** mode.
169+
> Apply the generated descriptions to all reviewed products.
151170
152-
Before updating Shopware data, execute the operation in Dry Run mode to validate:
171+
The Shopware Admin MCP Server performs the requested operations using the authenticated user's permissions.
153172

154-
- Permissions
155-
- Entity resolution
156-
- Parameters
173+
# Step 7 — Secure the assistant
157174

158-
Once validated, execute the operation normally.
175+
Restrict the assistant to only the capabilities required for catalog management.
159176

160-
# Step 7 — Restrict your assistant
177+
For example:
161178

162-
Merchant assistants rarely require unrestricted access.
179+
| Allowed | Restricted |
180+
|----------|------------|
181+
| Search Products | Delete Products |
182+
| Update Products | Create Users |
183+
| Read Categories | Modify System Configuration |
184+
| Generate Product Content | Manage Integrations |
163185

164-
Restrict the assistant using:
186+
Access is controlled using:
165187

166-
- ACL permissions
188+
- Shopware ACL permissions
167189
- Tool allowlists
168190
- Resource allowlists
169191
- Prompt allowlists
170192

171-
For example:
193+
# Extend the assistant
172194

173-
| Allowed | Restricted |
174-
|----------|------------|
175-
| Search Products | Delete Products |
176-
| Read Orders | Create Users |
177-
| Generate Reports | Modify System Configuration |
178-
179-
# Step 8 — Extend the assistant
195+
The Shopware MCP ecosystem can be extended with custom capabilities.
180196

181-
You can expose additional capabilities by creating custom:
197+
You can create custom:
182198

183199
- Tools
184200
- Resources
@@ -190,40 +206,28 @@ using:
190206
- Symfony Bundles
191207
- Apps
192208

193-
The Shopware MCP Server automatically exposes these extensions to connected AI clients.
194-
195-
# Verify the implementation
209+
These extensions become automatically discoverable by connected MCP clients.
196210

197-
Verify that your assistant can:
211+
# Result
198212

199-
- Discover Shopware capabilities
200-
- Retrieve Shopware entities
201-
- Execute merchant operations
202-
- Respect ACL permissions
203-
- Execute write operations
204-
205-
If the assistant cannot discover tools, verify:
206-
207-
- Authentication
208-
- MCP configuration
209-
- User permissions
213+
Congratulations!
210214

211-
# Related repositories
215+
You have built an AI-powered catalog quality assistant that can:
212216

213-
| Repository | Purpose |
214-
|------------|---------|
215-
| `shopware/shopware` | Core Shopware platform |
216-
| `shopware-admin-mcp` | Shopware Admin MCP Server |
217-
| `SwagMcpMerchantTools` | Merchant-specific MCP capabilities |
218-
| `SwagMcpDevTools` | Development and debugging tools |
217+
- Analyze your Shopware product catalog.
218+
- Identify incomplete or inconsistent product data.
219+
- Generate enriched product content.
220+
- Preview changes safely using Dry Run.
221+
- Apply validated updates through the Shopware Admin MCP Server.
219222

220223
# Next steps
221224

222-
Now that you've built a merchant assistant, continue with:
225+
Continue exploring the Shopware MCP ecosystem:
223226

224-
- Connect additional MCP clients
225-
- Extend the Shopware MCP Server
226-
- Create custom MCP Tools
227-
- Create custom Resources
228-
- Create custom Prompts
227+
- Build an AI Inventory Assistant
228+
- Build an AI Order Operations Assistant
229+
- Extend the Shopware Admin MCP Server
230+
- Create Custom MCP Tools
231+
- Create Custom Resources
232+
- Create Custom Prompts
229233
- Explore the MCP Server Reference

0 commit comments

Comments
 (0)