Oro Commerce Mcp Server

🏪 ORO Commerce MCP 服务

一个动态的 Model Context Protocol（MCP）服务，可与 ORO Commerce 无缝集成。它会根据你的 ORO Commerce API 架构自动生成工具，让你可以通过 Claude 等 AI 助手即时访问所有可用端点。

✨ 功能

🚀 动态 API 集成

• 自动从 ORO Commerce Swagger 架构中发现所有 API 端点
• 完整覆盖 API——每个端点都会成为可用的 MCP 工具
• 自动更新——新的 API 端点会自动变为可用
• 无需硬编码 API 调用——所有内容均在运行时生成

🔧 智能工具生成

• 智能端点选择——优先关注最实用的 API
• 根据 OpenAPI 架构自动验证参数
• 全面的错误处理和响应格式化
• 按类别整理（Accounts、Customers、Products 等）

🏪 完整覆盖 ORO Commerce

• Accounts 和客户管理——完整的 B2B 客户生命周期
• 产品目录和套件商品——产品、类别、套件配置、自定义字段
• 订单处理——订单、含套件详情的订单项、状态跟踪
• 活动管理——通话、电子邮件、备注、任务
• 扩展实体——自定义字段和实体扩展
• 关系和复杂操作——所有 API 端点，包括高级功能

🔐 适用于企业

• OAuth2 身份验证，支持自动管理令牌
• 默认只读——适用于生产环境
• 可配置的端点筛选——控制开放哪些 API
• 全面的日志记录和调试支持

🚀 快速开始

1. 安装

npm install -g oro-commerce-mcp-server

或在本地运行：

git clone https://github.com/clicktrend/oro-commerce-mcp-server.git
cd oro-commerce-mcp-server
npm install
npm run build

2. 配置 ORO Commerce

在 ORO Commerce 后端创建 OAuth 应用：

1. 前往 System → Integrations → OAuth Applications
2. 使用 Client Credentials 授权类型创建新应用
3. 记下 Client ID 和 Client Secret
4. 为你想要查询的实体授予 API 访问权限

3. 更新 API 架构

生成并复制当前 API 架构：

在你的 ORO Commerce 服务上：

# In your ORO Commerce application directory
console api:swagger:dump > oro_commerce_swagger_dump.json

复制到你的 MCP 项目目录：

# Copy the file to where you'll run the MCP server
# Example: scp from remote server
scp user@oro-server:/path/to/oro_commerce_swagger_dump.json ./oro_commerce_swagger_dump.json

# Or: Copy from local ORO Commerce installation
cp /path/to/oro-commerce/oro_commerce_swagger_dump.json ./oro_commerce_swagger_dump.json

注意： oro_commerce_swagger_dump.json 文件必须位于启动 MCP 服务的同一目录中。

4. 启动服务

# Set environment variables
export ORO_SHOP_URL="https://your-oro-commerce.com"
export ORO_CLIENT_ID="your_client_id"
export ORO_CLIENT_SECRET="your_client_secret"

# For local/development with self-signed certificates:
export NODE_ENV=development
# OR use this for production with self-signed certs:
export DISABLE_SSL_VERIFY=true

# Start server
npm start

5. 使用 MCP Inspector 进行测试（开发）

在开发和测试时，你可以使用 MCP Inspector：

# Install and run MCP Inspector in the project directory
npx @modelcontextprotocol/inspector

# In the browser interface:
# - Command: "node"
# - Arguments: "dist/index.js"
# - Click "Connect"

这样你就可以在部署到 Claude Desktop/Code 之前交互式测试所有工具。

SSL 证书处理：

• 开发/本地： 设置 NODE_ENV=development，自动忽略 SSL 证书错误
• 使用自签名证书的生产环境： 设置 DISABLE_SSL_VERIFY=true，以关闭 SSL 验证
• 使用有效证书的生产环境： 无需额外配置

5. 配合 Claude Desktop 或 Claude Code 使用

Claude Desktop 配置：

添加到你的 Claude Desktop 配置中：

{
  \"mcpServers\": {
    \"oro-commerce\": {
      \"command\": \"oro-commerce-mcp-server\",
      \"env\": {
        \"ORO_SHOP_URL\": \"https://your-oro-commerce.com\",
        \"ORO_CLIENT_ID\": \"your_client_id\", 
        \"ORO_CLIENT_SECRET\": \"your_client_secret\",
        \"NODE_ENV\": \"development\"
      }
    }
  }
}

Claude Code 配置：

对于 Claude Code 项目，复制示例配置：

# Copy example configuration
cp .mcp.json.example .mcp.json

# Edit with your credentials
nano .mcp.json

或者在项目根目录手动创建 .mcp.json：

{
  \"mcpServers\": {
    \"oro-commerce\": {
      \"command\": \"oro-commerce-mcp-server\",
      \"env\": {
        \"ORO_SHOP_URL\": \"https://your-oro-commerce.com\",
        \"ORO_CLIENT_ID\": \"your_client_id\",
        \"ORO_CLIENT_SECRET\": \"your_client_secret\",
        \"NODE_ENV\": \"development\"
      },
      \"description\": \"Dynamic ORO Commerce API integration\"
    }
  }
}

注意： Claude Code 会在重启时自动加载 .mcp.json 文件，并将其添加到 .gitignore，以防止凭据泄露。

🛠️ 可用工具

该服务提供 30 多个动态生成的工具：

核心工具（4 个）

• configure_oro_connection - 设置 API 连接
• test_connections - 验证 API 连通性
• list_dynamic_tools - 浏览所有可用工具
• get_dynamic_tool_info - 获取详细的工具文档

动态工具（26+）

根据您的 ORO Commerce API 自动生成：

账户管理（15 个工具）

• accounts_get - 列出所有账户
• accounts_id_get - 获取特定账户的详细信息
• accounts_id_contacts_get - 获取账户联系人
• accounts_id_b2bcustomers_get - 获取 B2B 客户
• 以及更多账户相关端点……

B2B 客户管理（11+ 个工具）

• b2bcustomers_get - 列出 B2B 客户
• b2bcustomers_id_get - 获取客户详细信息
• b2bcustomers_id_orders_get - 获取客户订单
• 以及更多客户相关端点……

其他类别

• 产品与目录管理
• 订单处理与跟踪
• 库存与定价
• 活动管理（通话、电子邮件、任务）
• 自定义实体扩展

📖 使用示例

基本数据查询

// List all accounts
{
  \"name\": \"accounts_get\",
  \"arguments\": {}
}

// Get specific customer details  
{
  \"name\": \"b2bcustomers_id_get\",
  \"arguments\": { \"id\": \"123\" }
}

// Search tools by category
{
  \"name\": \"list_dynamic_tools\", 
  \"arguments\": { \"category\": \"accounts\" }
}

高级集成

// Get comprehensive account data
{
  \"name\": \"accounts_id_get\",
  \"arguments\": { 
    \"id\": \"1\",
    \"include\": \"contacts,addresses,activities\"
  }
}

// Filter B2B customers by criteria
{
  \"name\": \"b2bcustomers_get\",
  \"arguments\": {
    \"filter[name]\": \"Acme Corp\",
    \"page[limit]\": 10
  }
}

⚙️ 配置

环境变量

# Required
ORO_SHOP_URL=https://your-oro-commerce.com
ORO_CLIENT_ID=your_oauth_client_id
ORO_CLIENT_SECRET=your_oauth_client_secret

# Optional  
DEBUG=mcp:*
NODE_ENV=development
DISABLE_SSL_VERIFY=true

保持架构为最新

重要： 定期更新 API 架构，确保所有工具都反映您当前的 ORO Commerce 设置：

# Update schema after:
# - Installing new ORO Commerce bundles
# - Adding custom entities/fields  
# - Upgrading ORO Commerce versions
# - Modifying API configurations

# On ORO Commerce server:
console api:swagger:dump > oro_commerce_swagger_dump.json

# Copy to MCP project directory and restart server:
cp oro_commerce_swagger_dump.json /path/to/mcp-project/
# Restart MCP server to reload tools

🏗️ 架构

动态工具生成

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ ORO Commerce    │───▶│ Swagger Schema   │───▶│ MCP Tools       │
│ API Endpoints   │    │ oro_commerce_    │    │ (Generated      │
│ (3500+ total)   │    │ swagger_dump.json│    │ Automatically)  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

智能端点选择

服务会智能选择最实用的端点：

• 热门实体（账户、客户、订单、产品）
• 只读操作（适合在生产环境中使用）
• 文档完善的端点，参数清晰
• 按类别筛选，避免让用户应接不暇

🔧 开发

项目结构

src/
├── index.ts              # Main MCP server
├── oro-client.ts         # ORO Commerce OAuth2 client  
├── swagger-parser.ts     # Dynamic schema parser
├── dynamic-client.ts     # API execution engine
└── types.ts              # TypeScript definitions

从源代码构建

git clone https://github.com/clicktrend/oro-commerce-mcp-server.git
cd oro-commerce-mcp-server
npm install
npm run build
npm start

扩展服务

// Add more endpoint categories in swagger-parser.ts
getEndpointsByTags([
  'products', 'orders', 'categories', 
  'inventory', 'prices', 'promotions'
])

🚀 使用场景

电商管理

• 客户关系管理 - 访问完整的客户档案
• 订单处理 - 跟踪订单、订单项和履约情况
• 产品目录管理 - 查询产品、属性和类别
• 库存监控 - 检查库存水平和可用性

商业智能

• 销售分析 - 分析订单模式和客户行为
• 客户洞察 - 了解客户生命周期和偏好
• 产品表现 - 跟踪畅销产品和库存周转情况
• 账户管理 - 监控 B2B 客户关系

集成与自动化

• 数据同步 - 让外部系统与 ORO Commerce 保持同步
• 报告生成 - 根据 ORO Commerce 数据创建自定义报告
• 工作流自动化 - 根据 ORO Commerce 事件触发操作
• AI 驱动的洞察 - 使用 AI 助手分析业务数据

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

快速贡献指南

1. Fork 此仓库
2. 创建 功能分支：git checkout -b feature/amazing-feature
3. 提交 更改：git commit -m 'Add amazing feature'
4. 推送 到分支：git push origin feature/amazing-feature
5. 创建 Pull Request

📋 要求

• Node.js 18+ - 运行时环境
• TypeScript 5.3+ - 开发依赖项
• ORO Commerce 实例 - 已启用 API 访问
• OAuth2 凭据 - 来自 ORO Commerce 的客户端 ID 和密钥

🐛 故障排除

常见问题

身份验证失败：

# Test OAuth2 credentials manually
curl -X POST https://your-oro-commerce.com/oauth2-token \\
  -d \"grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET\"

缺少工具：

# Update your API schema
console api:swagger:dump > oro_commerce_swagger_dump.json
# Restart the server
npm restart

连接问题：

# Enable debug logging
DEBUG=mcp:* npm start

获取帮助

• 问题： GitHub Issues
• 讨论： GitHub Discussions
• 文档： Wiki

📄 许可证

本项目采用 MIT License 许可 - 详情请参阅 LICENSE 文件。

🙏 致谢

• ORO Commerce - 感谢提供全面的 API 文档
• Model Context Protocol - 感谢支持 AI 助手集成
• Anthropic Claude - 感谢启发智能 API 交互

---

由 Clicktrend 倾心打造
在 Claude.ai 的协助下构建

将您的 ORO Commerce 数据转化为 AI 可访问的洞见