onX Documentation

Juniper Commerce Docs

Everything you need to understand the onX standard, build your adapter, integrate with UCP, and validate conformance.

Commerce Operations Foundation GitHub: mcp-reference-server

Getting Started

The onX (Order Network eXchange) standard defines a common MCP (Model Context Protocol) interface for commerce fulfillment operations. Any AI platform can connect to any onX-compliant adapter using a single, consistent protocol.

1. Clone and run this reference app

The onX standard is developed by the Commerce Operations Foundation . Source code: mcp-reference-server on GitHub .

bash

git clone https://github.com/commerce-operations-foundation/mcp-reference-server
cd mcp-reference-server/juniper-app
npm install
npm run dev
# → http://localhost:3000

2. Run the MCP server

bash

cd ../server
npm install && npm run build
ADAPTER_TYPE=built-in ADAPTER_NAME=mock node dist/index.js

3. Test conformance

bash

npx onx-conform --endpoint http://localhost:3000
# Runs 17 tests across 5 suites
# Outputs pass/fail report to console

💡 TipThe Juniper app uses an in-memory data layer that mirrors the onX MCP server contract. You can swap it for a real MCP server call by updating src/lib/onx-client.ts.

Architecture

The onX standard uses the Model Context Protocol (MCP) over stdio transport. Adapters implement the IFulfillmentAdapter interface and expose 12 operations.

The 12 Operations

get-productsList product catalog

get-product-variantsList SKUs & options

get-inventoryStock levels by SKU/location

get-customersCustomer lookup

get-ordersOrder history & filtering

create-sales-orderPlace a new order

update-orderModify an existing order

cancel-orderCancel with reason

fulfill-orderShip with tracking

get-fulfillmentsFulfillment status

create-returnInitiate return/RMA

get-returnsReturn history

Three-Layer Architecture

text

Protocol Layer  (MCP SDK, stdio transport)
    ↓
Service Layer   (ServiceOrchestrator, Validator, ErrorHandler)
    ↓
Adapter Layer   (IFulfillmentAdapter implementations)

ℹ️ InfoThe Juniper app's onx-client.ts shows how to consume these operations from a Next.js application. In a real deployment, replace the in-memory calls with HTTP/stdio calls to a running MCP server.

Build Your Adapter

An adapter wraps your fulfillment system (Shopify, NetSuite, custom WMS, etc.) and implements the onX interface. Use the template from adapter-template/ as your starting point.

Step 1: Scaffold

bash

cp -r adapter-template my-adapter
cd my-adapter
npm install
# Edit src/adapter.ts

Step 2: Implement the interface

typescript

import { IFulfillmentAdapter } from '@onx/server';

export class MyAdapter implements IFulfillmentAdapter {
  async getOrders(params) {
    // Fetch from your system
    const orders = await myAPI.listOrders(params);
    // Return in onX format
    return { items: orders.map(toOnXOrder), total: orders.length };
  }

  async createSalesOrder(input) {
    const order = await myAPI.createOrder(input);
    return toOnXOrder(order);
  }

  // ... implement all 12 operations
}

Step 3: Configure and test

bash

# Set your adapter as the MCP server adapter
ADAPTER_TYPE=local ADAPTER_PATH=./dist/adapter.js node server/dist/index.js

# Run conformance to verify
npx onx-conform --endpoint http://localhost:3000

Step 4: Publish to npm

bash

npm publish --access public
# Consumers can then use:
# ADAPTER_TYPE=npm ADAPTER_PACKAGE=@myco/onx-adapter

💡 TipAll 12 operations have JSON Schema definitions in schemas/. The conformance runner validates your adapter against these schemas automatically.

UCP Integration

The Universal Commerce Protocol (UCP) lets AI platforms discover and consume your commerce capabilities via a standardized manifest. This app implements the full UCP bridge.

Discovery Manifest

Expose your capabilities at /.well-known/ucp:

json

{
  "version": "1.0",
  "name": "My Store",
  "baseUrl": "https://store.example.com",
  "capabilities": [
    {
      "id": "dev.ucp.shopping.catalog",
      "type": "catalog",
      "endpoint": "/api/ucp/catalog",
      "methods": ["GET", "POST"]
    },
    {
      "id": "dev.ucp.shopping.checkout",
      "type": "checkout",
      "endpoint": "/api/ucp/checkout",
      "methods": ["POST"]
    }
  ],
  "auth": {
    "type": "apiKey",
    "apiKeyHeader": "Authorization"
  }
}

Request/Response Flow

text

AI Platform → POST /.well-known/ucp discovery
AI Platform → GET /api/ucp/catalog?query=jacket
AI Platform → POST /api/ucp/checkout { items, customer, address }
              → translates to onX create-sales-order
              → returns { orderId, status, total }
AI Platform → GET /api/ucp/fulfillment?orderId=X
              → translates to onX get-fulfillments
              → returns { orderId, status, trackingNumbers }

ℹ️ InfoThis app uses API key auth for the demo. For production, implement OAuth 2.0 client credentials flow. The manifest documents the token URL and scopes.

Conformance Testing

The conformance runner validates that any onX endpoint meets the standard. Run it from the web UI or via CLI.

CLI Usage

bash

# Run against any endpoint
npx onx-conform --endpoint http://localhost:3000

# With JSON output
npx onx-conform --endpoint http://localhost:3000 --json

# Run specific suite only
npx onx-conform --endpoint http://localhost:3000 --suite catalog

What's Tested

UCP Discovery (3 tests)Manifest exists, has required fields, capabilities array

Catalog API (4 tests)Endpoint reachable, response shape, items structure, search works

Checkout API (3 tests)Creates order, response has orderId, rejects invalid input

Fulfillment API (4 tests)Status lookup, response shape, 400 on missing, 404 on unknown

onX Bridge (3 tests)Products, orders, inventory endpoints all return 200

Open Web Runner