docs: add MCP server documentation#2264
Open
Björn Meyer (BrocksiNet) wants to merge 15 commits into
Open
Conversation
Adds complete documentation for Shopware's native MCP server introduced in 6.7: - guides/development/tooling/mcp-server/ — 8 pages covering concepts, getting started, configuration, best practices, examples, troubleshooting, tools reference, and Shopware extensions (Copilot, SwagMcpMerchantAssistant, SwagMcpDevTools, ai-coding-tools) - guides/plugins/plugins/mcp-server.md — how-to for extending via plugin - guides/plugins/apps/mcp-server.md — how-to for extending via app (webhook) - 4 Admin UI screenshots for tool allowlist and ACL privilege flows - Navigation entries in tooling, plugins, apps, and extensions indexes
references - Fix McpContextProvider namespace (Context\ sub-namespace) and requirePrivilege return value pattern in plugin sample code - Fix shopware-media-upload has no dryRun, theme-config action/config defaults, debug:mcp column list, tool count claim - Add extending.md: side-by-side quick reference for tools/prompts/resources across app, plugin, and bundle - Add webhook handler examples for prompts and resources in apps/mcp-server.md - Link SwagMcpAdminUsers and McpHelloWorld example repos in plugin and app docs - Expand MCP acronym on first use in mcp-concepts.md, fix lowercase mcp in headings to use backticks - Fix duplicate heading in shopware-extensions.md
- Document required-privileges in app mcp.xml (informational only; apps must enforce ACL themselves) - Add array/object to supported input schema property types - Add internal URL mode (url="/...") for routing to app scripts - Document integration.mcp_tool_allowlist semantics (null/array/empty) - Replace stale mcp.yaml snippet with mcp.php note; clarify the bundle loads automatically when MCP_SERVER feature flag is active - Add --integration flag to debug:mcp; remove non-existent --all flag - Add Symfony bundle stub guide
reference - Add three new subsections to best-practices.md: writing descriptions for agent routing, the DI container cache requirement after description changes, and using the system prompt as the disambiguation override layer - Fix shopware-theme-config salesChannelId row in tools-reference.md to reflect that it is optional in the schema and validated at runtime
- Rename "Edit MCP Tools" → "Edit MCP Allowlist" across all docs - Update integration.mcp_tool_allowlist semantics to mcp_allowlist (JSON object with tools/resources/prompts keys, scoped to integration credentials only — admin user bearer tokens bypass the allowlist) - Document scope in configuration.md and add a row to the troubleshooting quick reference explaining why bearer tokens see all capabilities - Replace four allowlist UI screenshots with new versions reflecting vendor groupings, expandable tool descriptions, and the per-type toggles (tools/resources/prompts) - Add a "Limit tool count" illustration to best-practices.md showing the inline privilege-gap warnings when everything is enabled - Clarify in configuration.md that the bundle config loads automatically only when the MCP_SERVER feature flag is active - Replace "eval" with "evaluation" in best-practices.md for clarity
- Drop Feature::has('MCP_SERVER') gate from bundle build() examples;
core mcp.php loads services unconditionally and only the controller
checks the flag
- Add title attribute to McpTool/McpPrompt examples and document its
purpose
- Clarify configuration.md: symfony/mcp-bundle's mcp.php is loaded
unconditionally; the flag gates /api/_mcp only
- Point bundle extension docs to the new bundle.md#optional-bundles
pattern (gate in bundles.php, not build())
- Fix compiler pass name: McpToolCompilerPass →
McpToolDiscoveryCompilerPass
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new documentation section for Shopware’s native MCP server (6.7+) and extension guides for contributing MCP capabilities via plugins and apps, plus navigation and spellcheck updates to surface the new content across the docs.
Changes:
- Add a new
guides/development/tooling/mcp-server/documentation set (concepts, setup, configuration, best practices, examples, troubleshooting, tools reference, extensions). - Add “extend via plugin” and “extend via app” how-tos, and link them from the plugin/app guide indexes.
- Update navigation entries and expand
.wordlist.txtfor MCP-related terminology.
Reviewed changes
Copilot reviewed 19 out of 24 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| guides/plugins/plugins/mcp-server.md | New guide for extending MCP via Shopware plugin/Symfony bundle (tools/prompts/resources). |
| guides/plugins/plugins/index.md | Adds MCP extension entry to plugin topic index table. |
| guides/plugins/plugins/bundle.md | Adds “Optional bundles” guidance (InstalledVersions/Feature guards). |
| guides/plugins/apps/mcp-server.md | New guide for extending MCP via apps (mcp.xml + webhook protocol). |
| guides/plugins/apps/index.md | Adds link to the new MCP app extension guide. |
| guides/development/tooling/using-watchers.md | Renames nav title to “Hot Module Replacement”. |
| guides/development/tooling/mcp-server/index.md | New MCP server landing page (capabilities, architecture, section index). |
| guides/development/tooling/mcp-server/mcp-concepts.md | New concepts page explaining tools/resources/prompts. |
| guides/development/tooling/mcp-server/getting-started.md | New setup guide for enabling MCP and configuring clients. |
| guides/development/tooling/mcp-server/configuration.md | New configuration guide (feature flag, allowlists, session store, CLI). |
| guides/development/tooling/mcp-server/best-practices.md | New best-practices guide for MCP tool/prompt/resource design. |
| guides/development/tooling/mcp-server/examples.md | New end-to-end workflow examples using core tools/resources. |
| guides/development/tooling/mcp-server/extending.md | New side-by-side extension reference (app vs plugin vs bundle). |
| guides/development/tooling/mcp-server/troubleshooting.md | New troubleshooting quick reference and common issues. |
| guides/development/tooling/mcp-server/tools-reference.md | New reference for built-in tools/resources/prompt and parameters. |
| guides/development/tooling/mcp-server/shopware-extensions.md | New overview of MCP-related Shopware extensions/projects. |
| guides/development/tooling/index.md | Adds MCP Server entry to tooling overview. |
| guides/development/extensions/index.md | Adds MCP extensibility section linking to plugin/app guides. |
| .wordlist.txt | Adds MCP-related terms for spellcheck. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+204
to
+211
| const expected = crypto | ||
| .createHmac('sha256', appSecret) | ||
| .update(body) | ||
| .digest('hex'); | ||
| return crypto.timingSafeEqual( | ||
| Buffer.from(signature), | ||
| Buffer.from(expected) | ||
| ); |
Comment on lines
75
to
77
| Archlinux | ||
| ArrayAdapter | ||
| ArrayFacade |
Micha Hobert (Isengo1989)
requested review from
Micha Hobert (Isengo1989),
somethings (lasomethingsomething) and
Su (sushmangupta)
Micha Hobert (Isengo1989)
added
the
Undocumented Feature
somethings (lasomethingsomething)
requested review from
Paul Riga (RigaPaul)
and removed request for
somethings (lasomethingsomething)
- Fix broken relative links (../../plugins → ../../../plugins) in index and mcp-concepts - Align bundle prompt/resource tabs with feature-flag guidance (gates HTTP endpoint, not DI) - Harden Node.js HMAC example: guard missing signature and mismatched lengths - Clarify admin user vs --admin integration in configuration and troubleshooting tables - Fix "Hot Module Reloading" → "Hot Module Replacement" for consistency in using-watchers - Add products/tools/ index and lightweight MCP Server entry point linking to full docs
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds complete documentation for Shopware's native MCP server introduced in 6.7:
Related links
relates: shopware/shopware#15346
Checklist
PageRefreferences where relevant..gitbook.yamlif pages were moved, renamed, or deleted..wordlist.txt(and sorted it) if spellcheck flags new legitimate terms.Notes