AdminMcpServerPlugin

<p align="center"> <a href="https://sylius.com" target="_blank"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://media.sylius.com/sylius-logo-800-dark.png"> <source media="(prefers-color-scheme: light)" srcset="https://media.sylius.com/sylius-logo-800.png"> <img alt="Sylius Logo." src="https://media.sylius.com/sylius-logo-800.png"> </picture> </a> </p> <h1 align="center">Sylius 管理后台 MCP 服务器插件</h1> <p align="center">将 Sylius 管理后台 API 暴露为模型上下文协议（MCP）服务器，并使用 OAuth 2.0 PKCE 身份验证。</p> --- 该插件将您的 Sylius 商店转变为 MCP 服务器，允许 AI 助手（Claude、Cursor 等）通过自然语言管理您的商店。它提供了 171 种工具，涵盖所有主要的 Sylius 资源 - 产品、订单、客户、促销、运输等 - 并通过完整的 OAuth 2.0 授权码 + PKCE 流进行安全保护。 ## 要求 - PHP 8.2+ - Sylius 2.1 或 2.2 - Symfony 7.4 - MySQL 或 PostgreSQL - Node.js 20+ 和 Yarn（用于前端资产） ## 安装 ### 使用 Symfony Flex 配方安装 当启用 Symfony Flex 时，`composer require sylius/admin-mcp-server-plugin` 会自动注册捆绑包、导入插件配置和导入路由。从下面的步骤 2 继续。 > **关于 `symfony/type-info` 补丁** （Sylius 2.2.x）：`symfony/type-info v7.4.x` 中的一个错误导致预热缓存错误：`Cannot create union with both "object" and class type`。应用补丁： > > ```bash > patch vendor/symfony/type-info/TypeContext/TypeContextFactory.php \ > vendor/sylius/admin-mcp-server-plugin/patches/symfony-type-info-union-fix.patch > ``` > > 要在每次 `composer update` 后自动重新应用此补丁，您可以使用 [cweagans/composer-patches](https://github.com/cweagans/composer-patches)： > > 1. `composer require --dev cweagans/composer-patches` > 2. 将补丁复制到您的项目：`mkdir -p patches && cp vendor/sylius/admin-mcp-server-plugin/patches/symfony-type-info-union-fix.patch patches/` > 3. 添加到您的 `composer.json`： > ```json > "config": { "allow-plugins": { "cweagans/composer-patches": true } }, > "extra": { > "patches": { > "symfony/type-info": { > "Fix: Cannot create union with both object and class type": "patches/symfony-type-info-union-fix.patch" > } > } > } > ``` > 4. 运行 `composer install` #### 步骤 1 - 通过 Composer 添加插件 ```bash composer require sylius/admin-mcp-server-plugin ``` > **关于 `league_oauth2_server.yaml` **：插件自带 `config/packages/league_oauth2_server.yaml`，使用 `SYLIUS_ADMIN_MCP_SERVER_OAUTH_*` 环境变量配置 OAuth2 服务器。如果 `league/oauth2-server-bundle` Flex 配方已经在您的项目中创建了 `config/packages/league_oauth2_server.yaml` 和 `config/routes/league_oauth2_server.yaml`，请用空存根替换两者 - 否则 Flex 生成的配置与插件自己的配置冲突并导致错误： > > ```bash > echo "# 由 sylius/admin-mcp-server-plugin 管理" > config/packages/league_oauth2_server.yaml > echo "# 路由由 sylius/admin-mcp-server-plugin 提供" > config/routes/league_oauth2_server.yaml > ``` #### 步骤 2 - 生成 OAuth 密钥对 插件使用专用的 RSA 密钥对（与 Lexik JWT 分开）来签署 OAuth 代币： ```bash mkdir -p config/jwt openssl genrsa -out config/jwt/mcp_private.pem 4096 openssl rsa -in config/jwt/mcp_private.pem -pubout -out config/jwt/mcp_public.pem ``` 密钥默认为 `config/jwt/mcp_private.pem` 和 `config/jwt/mcp_public.pem`。如果您想使用不同的位置，可以通过环境变量覆盖。 #### 步骤 3 - 配置环境变量 添加到您的 `.env`（或 `.env.local`）： ```dotenv ###> sylius/admin-mcp-server-plugin ### # 该应用程序的 Admin API URL（MCP 工具使用它来调用 API） SYLIUS_ADMIN_MCP_SERVER_API_URL=https://your-domain.com/api/v2/admin/ # Admin API 用户凭证 - 仅在您使用基于凭证的令牌提供程序时需要。 # 默认情况下，插件重用已登录的管理员用户的 OAuth Bearer 代币。 # 要切换到基于凭证的登录，请在您的 config/services.php 中别名服务： # ->alias('sylius_admin_mcp_server.provider.token', 'sylius_admin_mcp_server.provider.token.credentials'); SYLIUS_ADMIN_MCP_SERVER_API_EMAIL=api@example.com SYLIUS_ADMIN_MCP_SERVER_API_PASSWORD=your-api-password # 设置为 false 以禁用 SSL 验证（适用于本地 HTTPS） SYLIUS_ADMIN_MCP_SERVER_VERIFY_SSL=true # OAuth RSA 密钥对在步骤 2 中生成（与 Lexik JWT 密钥分开） SYLIUS_ADMIN_MCP_SERVER_OAUTH_PRIVATE_KEY=%kernel.project_dir%/config/jwt/mcp_private.pem SYLIUS_ADMIN_MCP_SERVER_OAUTH_PUBLIC_KEY=%kernel.project_dir%/config/jwt/mcp_public.pem SYLIUS_ADMIN_MCP_SERVER_OAUTH_PASSPHRASE= # OAuth 代币加密的随机十六进制字符串 - 使用以下命令生成：openssl rand -hex 32 SYLIUS_ADMIN_MCP_SERVER_OAUTH_ENCRYPTION_KEY=your-32-byte-hex-key-here ###< sylius/admin-mcp-server-plugin ### ``` 生成加密密钥： ```bash openssl rand -hex 32 ``` #### 步骤 4 - 运行数据库迁移 ```bash php bin/console doctrine:migrations:migrate -n ``` 这会创建三个 OAuth 表：`sylius_admin_mcp_oauth_clients`、`sylius_admin_mcp_oauth_authorization_codes`、`sylius_admin_mcp_oauth_refresh_tokens`。 #### 步骤 5 - 清除缓存 ```bash php bin/console cache:clear php bin/console cache:warmup ``` #### 步骤 6 - 构建前端资产 授权页面需要 Sylius 管理后台资产。如果您尚未安装： ```bash yarn install yarn build php bin/console assets:install ``` #### 步骤 7 - 授予管理员用户 API 访问权限 只有具有 `ROLE_API_ACCESS` 的管理员用户才能通过 OAuth 同意页面授权。通过 SQL 将其授予现有用户： ```sql UPDATE sylius_admin_user SET roles = JSON_ARRAY_APPEND(roles, '$', 'ROLE_API_ACCESS') WHERE email = 'your@admin.com'; ``` 或在您的 fixtures 中创建专用的 API 用户。 --- ### 手动安装（无 Symfony Flex） 如果您的项目不使用 Symfony Flex，则不会自动注册捆绑包、配置和路由。请参阅 [docs/manual-installation.md](docs/manual-installation.md) 以获取逐步说明。 --- ## 验证 安装完成后，验证所有功能是否正常： ```bash # 1. 检查已注册的服务 php bin/console debug:container --tag=mcp.tool | grep "Sylius" # 2. 检查已注册的路由 php bin/console debug:router | grep mcp # 3. 检查 OAuth 发现端点 curl -sk https://your-domain.com/.well-known/oauth-authorization-server | python3 -m json.tool ``` 预期路由：`/.well-known/oauth-authorization-server`、`/_mcp/oauth/register`、`/admin/mcp/oauth/authorize`、`/_mcp/oauth/token`、`/_mcp`。 --- ## 连接 MCP 客户端 安装并运行插件后，使用以下选项之一连接 AI 助手。 ### 选项 A - Claude Desktop（本地或远程） Claude Desktop 支持本地和远程 MCP 服务器，并与任何 HTTPS URL 配合使用，包括自签名证书的 `localhost`。 编辑您的 Claude Desktop 配置文件： - **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "sylius-admin": { "type": "http", "url": "https://your-domain.com/_mcp" } } } ``` Claude Desktop 会自动读取 OAuth 发现端点（`/.well-known/oauth-authorization-server`），并在您首次使用服务器时在您的默认浏览器中打开同意页面。不需要手动令牌管理。 > **本地开发**：使用 `"url": "https://127.0.0.1:8003/_mcp"`。Claude Desktop 接受自签名证书，因此不需要隧道。 ### 选项 B - 浏览器中的 Claude.ai（自定义连接器） > **要求**：Claude.ai **Pro 或 Max** 计划。服务器必须通过 HTTPS 公开访问，并具有有效的（非自签名）SSL 证书。`localhost` 不起作用 - Anthropic 的服务器从他们自己的 IP 范围调用您的端点。 1. 打开 [claude.ai](https://claude.ai) → 点击您的头像 → **自定义 Claude** → **连接器** → **+** → **添加自定义连接器** 2. 粘贴您的服务器 URL：`https://your-domain.com/_mcp` 3. 点击 **连接**。Claude.ai 自动读取 `/.well-known/oauth-authorization-server` 发现文档，并将您重定向到您的 Sylius 管理后台同意页面。 4. 以具有 `ROLE_API_ACCESS` 的管理员用户身份登录并点击 **允许**。 Claude.ai 使用 `https://claude.ai/api/mcp/auth_callback` 作为其重定向 URI，插件的动态客户端注册端点会自动接受。 > **本地开发无公共服务器**：通过 [ngrok](https://ngrok.com)、[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) 或 [LocalCan](https://www.localcan.com/) 将您的本地服务器隧道到公共 HTTPS URL： > ```bash > # 使用 ngrok 示例： > ngrok http https://127.0.0.1:8003 > # 然后在 claude.ai 中使用生成的 https://xxxx.ngrok-free.app/_mcp URL > ``` ### 选项 C - Claude Code（CLI） ```bash claude mcp add --transport http sylius-admin https://your-domain.com/_mcp ``` Claude Code 在首次使用时自动处理完整的 OAuth PKCE 流（为同意步骤打开浏览器窗口）。 ### 选项 D - Cursor 在 Cursor 设置 → **MCP** → **添加服务器**： ```json { "sylius-admin": { "url": "https://your-domain.com/_mcp", "type": "http" } } ``` --- ## 安全 - 所有 `/_mcp` 请求都需要有效的 OAuth 2.0 Bearer 代币（否则返回 `401`） - 授权仅限于具有 `ROLE_API_ACCESS` 的管理员用户 - 代币在 1 小时后过期；刷新代币有效期为 30 天 - PKCE（代码交换证明密钥）可防止授权代码拦截攻击 --- ## 文档 - [身份验证流程（OAuth 2.0 PKCE）](docs/authentication.md) - [可用的 MCP 工具](docs/tools.md) - 34 个资源组中的 171 种工具 - [配置参考](docs/configuration.md) - 选择性禁用工具组 - [手动安装](docs/manual-installation.md) - 无 Symfony Flex 的逐步指南 - [故障排除](docs/troubleshooting.md) --- ## 遥测 该插件在与 Sylius 一起使用时强制执行遥测数据收集。 详细信息请参见 [TELEMETRY_POLICY.md](./TELEMETRY_POLICY.md)。 --- ## 许可证 该插件在 [MIT License](LICENSE) 下发布。