Sylius Admin MCP Server Plugin

Exposes Sylius Admin API as a Model Context Protocol (MCP) server with OAuth 2.0 PKCE authentication.

--- This plugin turns your Sylius store into an MCP server, allowing AI assistants (Claude, Cursor, etc.) to manage your store through natural language. It provides 171 tools covering all major Sylius resources - products, orders, customers, promotions, shipping, and more - secured by a full OAuth 2.0 Authorization Code + PKCE flow. ## Requirements - PHP 8.2+ - Sylius 2.1 or 2.2 - Symfony 7.4 - MySQL or PostgreSQL - Node.js 20+ and Yarn (for frontend assets) ## Installation ### Installation with Symfony Flex recipe When Symfony Flex is active, `composer require sylius/admin-mcp-server-plugin` automatically registers the bundles, imports the plugin configuration, and imports the routes. Continue from Step 2 below. > **Note on `symfony/type-info` patch** (Sylius 2.2.x): A bug in `symfony/type-info v7.4.x` causes a cache warmup error: `Cannot create union with both "object" and class type`. Apply the patch that ships with the plugin: > > > > To re-apply this patch automatically after every `composer update`, you can use [cweagans/composer-patches](https://github.com/cweagans/composer-patches): > > 1. `composer require --dev cweagans/composer-patches` > 2. Copy the patch to your project: `mkdir -p patches && cp vendor/sylius/admin-mcp-server-plugin/patches/symfony-type-info-union-fix.patch patches/` > 3. Add to your `composer.json`: > > 4. Run `composer install` #### Step 1 - Add the plugin via Composer > **Note on `league_oauth2_server.yaml`**: the plugin ships its own `config/packages/league_oauth2_server.yaml` that configures the OAuth2 server using `SYLIUS_ADMIN_MCP_SERVER_OAUTH_*` environment variables. If the `league/oauth2-server-bundle` Flex recipe has already created a `config/packages/league_oauth2_server.yaml` and `config/routes/league_oauth2_server.yaml` in your project, replace both with empty stubs — otherwise the Flex-generated config conflicts with the plugin's own configuration and causes errors: > > #### Step 2 - Generate OAuth keypair The plugin uses a dedicated RSA keypair (separate from Lexik JWT) for signing OAuth tokens: The keys default to `config/jwt/mcp_private.pem` and `config/jwt/mcp_public.pem`. Override via env vars if you want a different location. #### Step 3 - Configure environment variables Add to your `.env` (or `.env.local`): Generate the encryption key: #### Step 4 - Run database migrations This creates three OAuth tables: `sylius_admin_mcp_oauth_clients`, `sylius_admin_mcp_oauth_authorization_codes`, `sylius_admin_mcp_oauth_refresh_tokens`. #### Step 5 - Clear cache #### Step 6 - Build frontend assets The admin authorization page requires Sylius admin panel assets. If you haven't already: #### Step 7 - Grant API access to an admin user Only admin users with `ROLE_API_ACCESS` can authorize via the OAuth consent page. Grant it to an existing user via SQL: Or create a dedicated API user in your fixtures. --- ### Manual Installation (without Symfony Flex) If your project does not use Symfony Flex, the bundles, configuration, and routes are not registered automatically. See [docs/manual-installation.md](docs/manual-installation.md) for step-by-step instructions. --- ## Verification After installation, verify everything is working: Expected routes: `/.well-known/oauth-authorization-server`, `/_mcp/oauth/register`, `/admin/mcp/oauth/authorize`, `/_mcp/oauth/token`, `/_mcp`. --- ## Connecting MCP Clients Once the plugin is installed and running, connect an AI assistant using one of the options below. ### Option A - Claude Desktop (local or remote) Claude Desktop supports both local and remote MCP servers and works out of the box with any HTTPS URL - including `localhost` with a self-signed certificate. Edit your Claude Desktop configuration file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` Claude Desktop reads the OAuth discovery endpoint (`/.well-known/oauth-authorization-server`) automatically and opens the consent page in your default browser when you first use the server. No manual token management is required. > **Local development**: Use `"url": "https://127.0.0.1:8003/_mcp"`. Claude Desktop accepts self-signed certificates, so no tunnelling is needed. ### Option B - Claude.ai in the browser (Custom Connectors) > **Requirements**: Claude.ai **Pro or Max** plan. The server must be publicly accessible over HTTPS with a **valid (non-self-signed) SSL certificate**. `localhost` does not work - Anthropic's servers call your endpoint from their own IP ranges. 1. Open [claude.ai](https://claude.ai) → click your avatar → **Customize Claude** → **Connectors** → **+** → **Add custom connector** 2. Paste your server URL: `https://your-domain.com/_mcp` 3. Click **Connect**. Claude.ai reads the `/.well-known/oauth-authorization-server` discovery document automatically and redirects you to your Sylius admin consent page. 4. Log in as an admin user with `ROLE_API_ACCESS` and click **Allow**. Claude.ai uses `https://claude.ai/api/mcp/auth_callback` as its redirect URI, which the plugin's dynamic client registration endpoint accepts automatically. > **Local development without a public server**: Tunnel your local server through a public HTTPS URL using [ngrok](https://ngrok.com), [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/), or [LocalCan](https://www.localcan.com/): > ### Option C - Claude Code (CLI) Claude Code handles the full OAuth PKCE flow automatically on first use (opens a browser window for the consent step). ### Option D - Cursor In Cursor settings → **MCP** → **Add server**: --- ## Security - All `/_mcp` requests require a valid OAuth 2.0 Bearer token (returns `401` otherwise) - Authorization is limited to admin users with `ROLE_API_ACCESS` - Tokens expire after 1 hour; refresh tokens are valid for 30 days - PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks --- ## Documentation - [Authentication Flow (OAuth 2.0 PKCE)](docs/authentication.md) - [Available MCP Tools](docs/tools.md) - 171 tools across 34 resource groups - [Configuration Reference](docs/configuration.md) - selectively disabling tool groups - [Manual Installation](docs/manual-installation.md) - step-by-step guide for projects without Symfony Flex - [Troubleshooting](docs/troubleshooting.md) --- ## Telemetry This plugin enforces telemetry data collection when used with Sylius. Details are described in [TELEMETRY_POLICY.md](./TELEMETRY_POLICY.md). --- ## License This plugin is released under the [MIT License](LICENSE).