ORO Commerce MCP SERVER AI

BundleOROMCPServerAI

用于OroCommerce的MCP服务器捆绑包-通过模型上下文协议公开Doctrine工具、Symfony容器调试和Maker捆绑包命令。

安装

通过包装商

通过Composer安装： composer require genaker/bundle-oro-mcp-server-ai

手动安装

安装PHP SDK依赖项： composer require modelcontextprotocol/php-sdk

然后将捆绑包复制到 src/BundleOROMCPServerAI/

捆绑注册

该捆绑包通过以下方式自动注册 src/BundleOROMCPServerAI/Resources/config/oro/bundles.yml.

对于手动注册，请将bundle类添加到您的 AppKernel.php.

需求

• PHP 8.1或更高版本
• Symfony 6.0+或7.0+
• ORM 2.0原则+
• Symfony Maker Bundle（用于Maker工具功能）

配置

将配置添加到您的 config.yml 具有主机、端口、传输类型、DDL权限和允许的查询模式选项。

运行服务器

通过控制台命令

使用以下命令运行服务器： php bin/console oro:mcp:server:run

带选项

将主机、端口和传输类型指定为命令选项。

运输类型

• 标准：从stdin读取，写入stdout（用于CLI MCP客户端）
• 超文本传输协议：HTTP服务器（用于web客户端）

可用工具

条令工具

• execute_query：对OroCommerce数据库安全执行SQL查询
• get_table_schema：获取包括列、索引和外键的表结构
• list_tables：列出所有数据库表
• get_entity_metadata：获取Doctrine实体元数据，包括字段和关联

容器工具

• list_services：列出所有Symfony容器服务
• get_service_definition：获取详细的服务定义，包括类、参数和标签
• get_container_参数：列出容器参数（敏感值已净化）
• get_service_dependency：获取服务依赖关系图

创客工具

完整的Symfony Maker Bundle命令公开，包括：

• 实体创建(make:entity)
• 控制器生成(make:controller)
• 表单类型(make:form)
• 控制台命令(make:command)
• 移民(make:migration)
• 事件听众/订阅者(make:listener, make:subscriber)
• 安全组件(make:user, make:auth, make:voter, make:validator)
• Messenger组件(make:message, make:messenger-middleware)
• 树枝组件(make:twig-component, make:twig-extension)
• CRUD生成(make:crud)
• 序列化器组件(make:serializer-encoder, make:serializer-normalizer)
• 测试(make:test, make:functional-test, make:unit-test)

使用MCP制作工具

连接到MCP服务器

使用console命令启动服务器。通过stdio（用于CLI客户端）或HTTP（用于web客户端）连接。服务器使用JSON-RPC 2.0协议。

MCP协议基础

• JSON-RPC 2.0格式
• 工具调用结构： tools/call 方法
• 请求格式包括jsonrpc版本、id、方法和参数
• 响应格式包括jsonrpc版本、id和结果
• 错误格式包括jsonrpc版本、id和错误详细信息

列出可用工具

使用方法发送请求 tools/list 获取所有可用的Maker工具及其参数和描述。

示例：通过MCP创建实体

使用 make_entity 该工具的参数包括实体名称、命名空间和字段定义。

示例：通过MCP创建控制器

使用 make_controller 具有控制器名称、命名空间、路由路径和模板名称的工具。

示例：通过MCP创建表单类型

使用 make_form 具有表单类型名称和可选实体类绑定的工具。

示例：通过MCP创建控制台命令

使用 make_command 带有命令类名和命令名的工具。

示例：通过MCP创建迁移

使用 make_migration 带有迁移描述的工具。

示例：通过MCP创建CRUD

使用 make_crud 具有实体类和控制器类的工具。

示例：通过MCP创建事件侦听器

使用 make_listener 具有侦听器名称和事件名称的工具。

示例：通过MCP创建用户实体

使用 make_user 具有用户类名、标识字段和密码字段选项的工具。

响应格式

所有Maker工具都会返回一个JSON响应，其中包含成功状态、文件数组、输出字符串和可选错误数组。

错误处理

错误以标准JSON-RPC错误格式返回，包括错误代码、消息和数据。

最佳实践

• 在继续之前，始终检查响应是否成功
• 提交前检查生成的文件
• 为您的项目结构使用适当的命名空间
• 在创建之前验证实体名称和字段类型
• 使用非交互模式（自动启用）进行自动化

在Docker/容器之外运行

在Docker或Warden之外运行MCP服务器时，您需要确保适当的权限和环境设置。

系统要求

1. PHP-CLI：确保已安装并可访问PHP CLI（PHP 8.1+）

1. 所需的PHP扩展：验证是否安装了PDO、数据库驱动程序（PDO_pgsql/PDO_mysql）、json和mbstring扩展

1. 文件权限：运行服务器的用户需要：

- 读取项目文件的访问权限 - 写入访问权限 src/ 目录（用于Maker命令） - 执行权限 bin/console

设置权限

Linux/macOS

确保控制台命令可执行，为src/目录设置适当的所有权，并为Maker命令配置创建文件的权限。

用户特定设置

如果以特定用户身份运行（建议用于开发），请创建一个专用用户，添加到适当的组中，并设置所有权和权限。

环境变量

在Docker外部运行时，如果环境变量不在.ENV文件中，请确保设置了包括APP_ENV、APP_DEBUG和DATABASE_URL在内的环境变量。

作为系统服务运行

创建一个systemd服务文件，用于将MCP服务器作为守护进程运行。配置用户、组、工作目录、环境变量和重启行为。使用systemctl命令启用并启动服务。

在反向代理后面运行

对于生产环境，请在nginx或Apache后面运行。配置反向代理以将请求转发到MCP服务器，设置适当的标头，并配置超时设置。

身份验证和授权

默认情况下，MCP服务器不包括内置身份验证。对于生产使用，您应该实现身份验证。以下是几种方法：

选项1：API密钥验证（推荐）

通过扩展命令创建自定义身份验证中间件。在HTTP服务器方法中添加API密钥属性、构造函数参数和身份验证检查。从授权头中提取API密钥并对其进行验证。同时支持“Bearer”和“ApiKey”格式。

通过环境变量或配置文件配置API密钥。进行HTTP请求时，请使用授权标头中的API密钥。

选项2：基于令牌的身份验证

对于更高级的场景，请实现JWT或OAuth2。从Authorization标头中提取令牌，并根据您的身份验证系统对其进行验证。

选项3:IP白名单

限制对特定IP地址的访问。实现IP匹配逻辑，包括对网络范围的CIDR表示法支持。

选项4：基本身份验证

实现简单的用户名/密码身份验证。从Basic Auth标头中提取凭据，并根据环境变量进行验证。

选项5:Symfony安全集成

为了实现完整的Symfony安全集成，请创建自定义防火墙和身份验证器。使用防火墙模式和自定义验证器类配置security.yaml。

stdio传输的身份验证

对于stdio传输（由Cursor、Claude Desktop使用），身份验证通常在进程级别处理：

1. 过程级安全：只允许受信任的用户运行服务器
2. 文件权限：限制谁可以执行控制台命令
3. 环境变量：使用环境变量进行敏感配置

限制控制台命令执行权限，并通过环境变量设置API密钥。

身份验证的最佳实践

1. 使用环境变量：切勿硬编码API密钥或密码
2. 定期旋转按键：定期更改API密钥
3. 使用HTTPS：在生产环境中始终使用HTTPS（通过反向代理）
4. 速率限制：实施限速以防止滥用
5. 审计日志：记录所有身份验证尝试和工具调用
6. 最小权限：授予所需的最低权限
7. 独立按键：针对不同的环境使用不同的API密钥

示例：完成身份验证设置

为API密钥、允许的IP和速率限制配置环境变量。更新配置文件以使用这些环境变量。

安全考虑

1. 查询验证：默认情况下会阻止DDL操作（DROP、ALTER等），除非 allow_ddl 已启用
2. 参数绑定：始终使用预处理语句进行SQL查询
3. 访问控制：实施生产使用的身份验证/授权（见上文身份验证部分）
4. 敏感数据：包含密码、机密或密钥的参数值将在响应中自动清除
5. 速率限制：考虑对生产中的查询实施速率限制
6. 文件系统权限：确保创建Maker命令文件的文件系统权限正确
7. 网络安全：绑定到 127.0.0.1 仅限本地主机，使用反向代理进行外部访问
8. TLS/SSL：始终通过反向代理（nginx/Apache）在生产中使用HTTPS
9. API密钥管理：安全存储API密钥，定期轮换，每个环境使用不同的密钥
10. 审计日志：记录所有用于安全审计的工具调用和身份验证尝试

故障排除

服务器无法启动

• 检查端口是否已在使用中
• 验证PHP扩展（用于HTTP传输的套接字）
• 检查Symfony控制台应用程序是否配置正确

未找到制造商命令

• 确保已安装Symfony Maker捆绑包
• 使用控制台列表命令验证Maker命令是否可用

数据库连接错误

• 验证条令是否配置正确
• 检查中的数据库凭据 .env 文件
• 确保数据库服务器正在运行

权限错误

• 检查的文件系统权限 src/ 目录
• 确保web服务器用户具有写入权限
• 验证 bin/console 可执行
• 检查用户/组所有权是否与您的设置匹配
• 对于Docker：确保卷权限正确

身份验证错误

• 401未经授权：检查API密钥是否正确并且与配置匹配
• 缺少授权标头：确保客户端发送授权标头
• API密钥格式无效：验证密钥格式是否与预期模式匹配
• 环境变量：确保在环境中设置了API密钥
• IP白名单：验证客户端IP是否在允许的列表中
• 令牌已过期：对于基于令牌的身份验证，请检查令牌过期

运行外部容器问题

• 未找到PHP：确保PHP CLI在PATH中或使用完整路径
• 数据库连接：验证数据库是否可以从主机（而不仅仅是容器）访问
• 文件权限：检查运行服务器的用户是否具有读/写访问权限
• 环境变量：运行前导出所需变量
• 端口冲突：确保端口3000未被其他服务使用

与AI工具集成

MCP服务器可以与支持模型上下文协议（MCP）的各种AI工具集成。这允许AI助手直接与您的OroCommerce应用程序进行交互。

光标IDE

Cursor通过其配置支持MCP服务器。要连接OroCommerce MCP服务器：

1. 创建MCP配置文件

在以下位置创建或编辑MCP配置文件 ~/.cursor/mcp.json （macOS/Linux）或 %APPDATA%\Cursor\mcp.json （Windows）。使用命令、参数和工作目录配置服务器。

1. 使用Docker/Warden

如果在Docker中运行OroCommerce（例如Warden），请创建一个包装器脚本，该脚本将更改为项目目录，并通过Warden执行命令。使脚本可执行，并配置Cursor以使用它。

1. 重新启动游标

配置后，重新启动Cursor以加载MCP服务器。

1. 在游标中使用MCP服务器

连接后，您可以要求Cursor：

- 查询数据库：“显示oro_user表中的所有用户” - 检查服务：“Doctrine提供哪些服务？” - 生成代码：“创建一个包含名称、价格和描述字段的新产品实体” - 创建控制器：“使用CRUD操作生成ProductController”

克劳德桌面（拟人）

Claude Desktop通过其配置支持MCP服务器：

1. 配置Claude桌面

在以下位置编辑Claude Desktop配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）。使用命令、参数和工作目录配置服务器。

1. 重新启动克劳德桌面

重新启动应用程序以加载MCP服务器配置。

基于Web的工具的HTTP传输

对于通过HTTP而不是stdio连接的AI工具：

1. 启动HTTP服务器

使用HTTP传输启动服务器，指定主机和端口。

1. 配置您的工具

使用JSON-RPC 2.0协议将AI工具指向服务器URL。

AI工具配置示例

光标（macOS/Linux）

使用PHP命令、项目路径、控制台命令、stdio传输和工作目录进行配置。可选择设置环境变量。

光标（Windows）

使用PHP命令、Windows风格的项目路径、控制台命令、stdio传输和工作目录进行配置。

使用Docker/Warden

使用warden命令、在容器中执行PHP的参数、控制台命令、stdio传输和工作目录进行配置。

测试MCP连接

配置后，测试连接：

1. 在光标中：打开MCP面板，验证“oro commerce”是否出现在连接的服务器列表中。

1. 手动测试：使用echo和管道向控制台命令发送测试请求。

1. 检查日志：服务器将记录工具调用和响应以进行调试。

AI工具集成故障排除

服务器未启动

• 检查PHP路径：确保PHP命令在PATH中或使用完整路径
• 检查权限：确保控制台命令可执行
• 检查工作目录：验证工作目录指向您的项目根目录
• 检查环境：确保设置了所需的环境变量

连接超时

• 运输类型：使用 stdio 对于基于CLI的工具， http 基于网络的工具
• 端口冲突：如果使用HTTP，请确保端口3000未被使用
• 防火墙：如果远程连接，请检查防火墙设置

工具不可用

• 验证服务器已启动：检查MCP服务器进程是否正在运行
• 检查日志：查看服务器日志中的错误
• 手动测试：使用curl或echo直接测试服务器

Docker/管理员问题

• 集装箱运行：确保Docker/Warden容器正在运行
• 命令路径：使用完整路径或确保命令位于容器内的PATH中
• 工作目录：将工作目录设置为容器内的项目目录

人工智能工具的安全考虑

当使用带有AI工具的MCP时：

1. 仅限本地访问：默认情况下，绑定到 127.0.0.1 （仅限本地主机）
2. 认证:

- 对于本地开发：stdio传输是安全的（进程级） - 对于远程/生产：实现API密钥身份验证（请参见身份验证部分） - 对API键使用环境变量，从不进行硬编码

1. DDL操作：保持 allow_ddl: false 除非特别需要
2. 敏感数据：服务器自动清除敏感参数
3. 速率限制：监控工具使用情况，防止滥用
4. 审计日志：启用日志记录以跟踪AI工具交互
5. 文件权限：确保只有受信任的用户可以执行控制台命令
6. 网络安全：使用HTTPS反向代理进行HTTP传输

向AI工具配置添加身份验证

如果您已经实现了API密钥验证，请更新您的AI工具配置，将API密钥包含在环境变量中。对于stdio传输，由于HTTP标头不可用，身份验证通常通过环境变量或进程级安全来处理。

示例

MCP客户端连接示例（stdio）

使用stdio传输启动服务器。使用echo和管道到控制台命令通过stdin发送请求。

MCP客户端连接示例（HTTP）

使用HTTP传输启动服务器，指定主机和端口。通过JSON-RPC格式的curl发送请求。

示例：AI工具查询数据库

当通过Cursor或Claude连接时，您可以要求AI查询数据库。AI工具将使用 execute_query 使用SQL查询的工具。

示例：AI工具创建代码

让AI创建代码，它将使用适当的Maker工具（例如。， make_entity)自动生成代码。

快速参考：常见场景

场景1：使用游标进行本地开发（无需授权）

使用PHP命令、项目路径、控制台命令和stdio传输配置Cursor。安全性是在进程级别处理的（只有您可以运行它）。

场景2：具有API密钥的生产HTTP服务器

将API键设置为环境变量。在本地主机上使用HTTP传输启动服务器。客户端请求包括带有API密钥的授权头。

场景3：带身份验证的Docker/Warden

创建包装器脚本，设置API密钥环境变量，并通过监狱长执行命令。配置Cursor以使用包装器脚本。

场景4：使用API密钥的系统服务

使用环境变量中的API键创建systemd服务文件。使用PHP路径、项目路径、控制台命令、HTTP传输、主机和端口配置ExecStart。

场景5：使用HTTPS的Nginx反向代理

为Nginx配置SSL证书、到localhost MCP服务器的代理传递以及包括Authorization在内的代理标头。客户端请求使用HTTPS，授权标头中包含API密钥。

许可证

麻省理工学院

支持

有关问题和疑问，请在GitHub存储库上打开问题。