Commerce Operations Foundation (COF) adapter for Magento 2 / Adobe Commerce. Implements the IFulfillmentAdapter interface, enabling AI agents and commerce systems to interact with Magento stores via the onX (Order Network eXchange) standard.
Install the adapter:
npm install @benmarks/magento-onx-adapterSet the ADAPTER_CONFIG environment variable with your Magento connection details:
export ADAPTER_CONFIG='{
"apiUrl": "https://your-magento.example.com",
"authMethod": "token",
"accessToken": "your-admin-integration-token"
}'Add the following to your Claude Desktop config to use the adapter via the COF MCP server:
{
"mcpServers": {
"commerce": {
"command": "npx",
"args": ["@cof-org/mcp"],
"env": {
"ADAPTER_TYPE": "npm",
"ADAPTER_PACKAGE": "@benmarks/magento-onx-adapter",
"ADAPTER_CONFIG": "{\"apiUrl\":\"https://your-magento.example.com\",\"authMethod\":\"token\",\"accessToken\":\"your-admin-integration-token\"}"
}
}
}
}| Operation | Type | Description |
|---|---|---|
| create-sales-order | Action | Create orders via admin API (explicit prices required) |
| update-order | Action | Modify order details (hold/unhold, comments, addresses) |
| cancel-order | Action | Cancel orders with reason tracking |
| fulfill-order | Action | Create shipments with tracking numbers |
| create-return | Action | Create RMAs (Commerce) or credit memos (Open Source) |
| get-orders | Query | Retrieve orders by ID, external ID, status, or name |
| get-customers | Query | Fetch customers by ID or email |
| get-products | Query | Get catalog products by ID or SKU |
| get-product-variants | Query | Retrieve variants (simple products linked to configurables) |
| get-inventory | Query | Check stock via MSI or legacy catalogInventory |
| get-fulfillments | Query | List shipments with tracking details |
| get-returns | Query | Query RMAs or credit memos |
All fields in AdapterOptions:
| Field | Type | Default | Description |
|---|---|---|---|
apiUrl |
string |
(required) | Base URL of the Magento instance (e.g. https://magento.example.com) |
authMethod |
"token" | "oauth" |
(required) | Authentication method to use |
accessToken |
string |
— | Bearer token for token-based auth |
oauthConsumerKey |
string |
— | OAuth 1.0a consumer key |
oauthConsumerSecret |
string |
— | OAuth 1.0a consumer secret |
oauthAccessToken |
string |
— | OAuth 1.0a access token |
oauthAccessTokenSecret |
string |
— | OAuth 1.0a access token secret |
storeView |
string |
"default" |
Magento store view code |
storeCurrency |
string |
"USD" |
Default currency code |
apiVersion |
string |
"V1" |
Magento REST API version prefix |
timeout |
number |
30000 |
Request timeout in milliseconds |
retryAttempts |
number |
3 |
Number of retry attempts on transient failures |
vendorNamespace |
string |
"m2" |
Namespace prefix for external ID mapping |
debugMode |
boolean |
false |
Enable verbose request/response logging |
Create an integration in Magento Admin > System > Integrations. Use the access token:
{
"apiUrl": "https://your-magento.example.com",
"authMethod": "token",
"accessToken": "your-integration-access-token"
}For environments requiring OAuth, provide all four OAuth credentials:
{
"apiUrl": "https://your-magento.example.com",
"authMethod": "oauth",
"oauthConsumerKey": "...",
"oauthConsumerSecret": "...",
"oauthAccessToken": "...",
"oauthAccessTokenSecret": "..."
}- Magento Open Source 2.4.x
- Adobe Commerce 2.4.x
- Adobe Commerce as a Cloud Service (ACCS)
- Mage-OS
npm run build # Compile TypeScript
npm test # Run tests
npm run lint # ESLint
npm run dev # Watch modeThis adapter's architecture follows the COF adapter template pattern. The VirtoCommerce onX adapter served as a key reference implementation during development, demonstrating how to structure a production COF adapter with services, transformers, and clean separation of concerns.
MIT