Magento2 Onx MCP

magento2-onx-mcp

一 onX（订单网络交换） Magento 2和Adobe Commerce的适配器。实施 商业运营基金会的onX规范 MCP（模型上下文协议） 服务器。

此适配器使任何onX兼容系统（AI代理、OMS、WMS、3PL、ERP）都可以使用标准化的商业操作语言与Magento 2商店进行交互。

这有什么作用

适配器位于onX客户端和Magento 2的REST API之间，将标准化的onX请求转换为Magento API调用，并将响应映射回onX模式：

onX Client (AI agent, OMS, WMS, etc.)
        │
        ▼
   ┌────────────────┐
   │  magento2-onx  │  ← This adapter
   │  (MCP Server)  │
   └────────────────┘
        │
        ▼
   Magento 2 REST API

onX覆盖范围

在7个商务原语中实现onX参考服务器的所有12个操作（5个操作+7个查询）。

行动工具（5）

查询工具（7）

商业原语（7）

订单、客户、产品、产品变体、库存项目、履行、退货

兼容性

• Magento开源 2.4.x--完全支持。退货使用贷项凭单。
• Adobe商务 2.4.x--完全支持。退货使用带有贷项凭单回退的本地RMA。
• Adobe商务即云服务（ACCS） -通过REST API兼容。
• Mage操作系统 -兼容（共享Magento 2 API表面）。

快速开始

先决条件

• Node.js 18+
• 具有REST API访问权限的Magento 2实例
• 集成访问令牌（管理>系统>集成）

安装

git clone https://github.com/benmarks/magento2-onx-mcp.git
cd magento2-onx-mcp
npm install
cp .env.example .env
# Edit .env with your Magento 2 credentials

配置

编辑 .env 使用您的Magento 2连接详细信息：

M2_BASE_URL=https://your-store.example.com
M2_ACCESS_TOKEN=your_integration_access_token

看 .env.example 用于所有配置选项，包括OAuth、多存储和MSI设置。

构建与运行

npm run build
npm start

发展

npm run dev    # Watch mode with hot reload
npm test       # Run tests
npm run lint   # Lint

与Claude Desktop一起使用

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "magento2-onx": {
      "command": "node",
      "args": ["/path/to/magento2-onx/dist/index.js"],
      "env": {
        "M2_BASE_URL": "https://your-store.example.com",
        "M2_ACCESS_TOKEN": "your_token"
      }
    }
  }
}

建筑

src/
├── index.ts                        # MCP server entry point
├── config.ts                       # Environment configuration
├── client/
│   └── magento-client.ts           # Magento 2 REST API client
├── mappers/
│   ├── order-mapper.ts             # M2 order → onX Order
│   ├── product-mapper.ts           # M2 product → onX Product
│   ├── product-variant-mapper.ts   # M2 simple product → onX ProductVariant
│   └── customer-mapper.ts          # M2 customer → onX Customer
└── tools/                          # 12 onX MCP tool implementations
    ├── _helpers.ts                 # Shared TemporalPagination & response helpers
    ├── create-sales-order.ts       # Action
    ├── update-order.ts             # Action
    ├── cancel-order.ts             # Action
    ├── fulfill-order.ts            # Action
    ├── create-return.ts            # Action
    ├── get-orders.ts               # Query
    ├── get-customers.ts            # Query
    ├── get-products.ts             # Query
    ├── get-product-variants.ts     # Query
    ├── get-inventory.ts            # Query
    ├── get-fulfillments.ts         # Query
    └── get-returns.ts              # Query

自定义字段

根据onX规范，使用 customFields 具有命名空间名称的数组。此适配器使用 m2 默认情况下为命名空间（可通过以下方式配置 ONX_VENDOR_NAMESPACE):

{
  "customFields": [
    { "name": "m2:state", "value": "processing" },
    { "name": "m2:status", "value": "pending_shipment" },
    { "name": "m2:store_id", "value": "1" }
  ]
}

贡献

欢迎捐款。请先打开一个问题来讨论重大更改。

许可证

Apache 2.0——请参阅 许可证.

链接

• 商业运营基金会
• onX规格
• onX参考服务器
• 模型上下文协议