Juniper Commerce

Juniper Commerce — onX Reference Implementation

[](LICENSE) [](https://commerceopsfoundation.org) [](https://nextjs.org) [](https://typescriptlang.org) [](Dockerfile)

Juniper Commerce is a full outdoor-gear storefront that implements all 12 onX operations. It serves as a reference implementation for vendors building onX-compliant systems.

What's Inside

| Component | Description | |-----------|-------------| | Storefront | Product catalog, cart, checkout, order tracking | | Admin | Dashboard, order management, inventory overview | | AI Playground | Natural-language commerce powered by onX tools | | REST API | All 12 onX operations at /api/onx/* | | Conformance | Test any onX endpoint for spec compliance | | API Docs | Swagger UI at /api/docs |

Quick Start (Docker)

Prerequisites

• Docker Desktop installed and running
• Git
• The mcp-reference-server repo cloned alongside this repo (only needed if you want the MCP server)

Your folder structure should look like:

# Clone the MCP server (optional — only needed for --profile mcp)
git clone https://github.com/commerce-operations-foundation/mcp-reference-server.git

some-parent/
├── juniper-commerce/         ← this repo
└── mcp-reference-server/     ← MCP server repo (optional)
    └── server/

Option A: Interactive Setup (recommended)

cd juniper-app
npm install        # first time only, installs the prompts package
npm run setup

The setup wizard will ask:

1. Quick Demo or Full Install
2. Data store: PostgreSQL or SQLite
3. AI provider: Anthropic / OpenAI / Gemini / Ollama / Skip
4. Include MCP reference server?
5. Seed sample data?

It generates a .env and prints the exact docker compose command to run.

Option B: Manual Setup

Demo mode (simplest — no database, no keys)

cd juniper-app
docker compose up --build

Visit http://localhost:3000. You get the full storefront with 24 products, 9 orders, and 6 customers loaded in memory.

Full mode with PostgreSQL

cd juniper-app

# Create .env
cat > .env  .env <<'EOF'
APP_MODE=full
DATA_MODE=postgres
DATABASE_URL=postgres://juniper:juniper@db:5432/juniper
ONX_MCP_SERVER_URL=http://mcp-server:8080
SEED_DATA=true
PORT=3000
NODE_ENV=production
EOF

docker compose --profile postgres --profile mcp up --build

This starts all three containers:

• Juniper on http://localhost:3000
• PostgreSQL on localhost:5432
• MCP Server on http://localhost:8080

Tear Down

# Stop everything and remove volumes
docker compose --profile postgres --profile mcp down -v

What to Test

1. Storefront

• http://localhost:3000 — Homepage
• http://localhost:3000/products — Browse 24 products, search, filter by category
• Click any product → variant selector, inventory status, add to cart
• http://localhost:3000/cart → http://localhost:3000/checkout — Full checkout flow

2. Admin

• http://localhost:3000/admin — Dashboard with order counts, inventory stats
• http://localhost:3000/admin/orders — Order list with status management
• http://localhost:3000/admin/inventory — Stock levels by warehouse

3. API

• http://localhost:3000/api/health — Health check
• http://localhost:3000/api/onx/products — List products (JSON)
• http://localhost:3000/api/onx/orders — List orders
• http://localhost:3000/api/onx/customers — List customers
• http://localhost:3000/api/onx/inventory — Inventory levels
• http://localhost:3000/api/onx/fulfillments — Fulfillments
• http://localhost:3000/api/onx/returns — Returns
• http://localhost:3000/api/onx/product-variants — Product variants
• POST http://localhost:3000/api/onx/orders/update — Update order
• POST http://localhost:3000/api/onx/orders/cancel — Cancel order

4. AI Playground

• http://localhost:3000/playground — Chat with onX tools
• Requires an AI API key (set via setup wizard, .env, or Settings page)
• Try: "Show me all hiking boots", "Check inventory for Trail Runner Pro"
• The right panel shows actual tool calls with input/output

5. API Documentation

• http://localhost:3000/api/docs — Swagger UI
• http://localhost:3000/openapi.yaml — Raw OpenAPI spec

6. Conformance

• http://localhost:3000/conformance — Run 17 tests against any onX endpoint

7. Settings (Full Mode only)

• http://localhost:3000/settings — Configure AI provider, data store, MCP URL
• In demo mode this page redirects to home (by design)

8. MCP Server (if started with --profile mcp)

• http://localhost:8080/health — Server health
• http://localhost:8080/api/tools — Lists all 12 onX tools
• Test a tool: curl -X POST http://localhost:8080/api/tools/get-products -H "Content-Type: application/json" -d "{}"

Two Modes

| | Demo Mode | Full (Install) Mode | |---|---|---| | Data | In-memory (TypeScript arrays) | PostgreSQL or SQLite | | Persistence | Session-scoped, resets on restart | Persistent across restarts | | AI | Rate-limited (20 msgs/min) | Your own key, no limits | | Settings | Hidden | Full config screen | | MCP Server | Not included | Optional via --profile mcp |

Architecture

┌────────────────────────────────────────────────────┐
│  Juniper Commerce (Next.js 15)                     │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────┐ │
│  │ Storefront   │  │ Admin        │  │ Playground│ │
│  │ /products    │  │ /admin       │  │ /playground│ │
│  │ /cart        │  │ /admin/orders│  │           │ │
│  │ /checkout    │  │ /admin/inv   │  │           │ │
│  └──────┬───────┘  └──────┬───────┘  └─────┬─────┘ │
│         │                 │                │       │
│  ┌──────▼─────────────────▼────────────────▼─────┐ │
│  │  onX Client (src/lib/onx-client.ts)           │ │
│  │  → DataProvider interface                     │ │
│  └──────┬──────────────┬───────────────┬─────────┘ │
│         │              │               │           │
│  ┌──────▼─────┐ ┌──────▼─────┐ ┌──────▼─────┐     │
│  │ InMemory   │ │ Postgres   │ │ SQLite     │     │
│  │ Provider   │ │ Provider   │ │ Provider   │     │
│  └────────────┘ └────────────┘ └────────────┘     │
│                                                    │
│  ┌─────────────────────────────────────────────┐   │
│  │  LLM Provider (src/lib/ai/llm-provider.ts) │   │
│  │  Anthropic │ OpenAI │ Gemini │ Ollama       │   │
│  └─────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────┘
         │
         ▼ (optional)
┌────────────────────────────┐
│  MCP Reference Server      │
│  12 onX tools over HTTP    │
│  Mock adapter (built-in)   │
│  http://mcp-server:8080    │
└────────────────────────────┘

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | APP_MODE | demo | demo or full | | DATA_MODE | memory | memory, postgres, or sqlite | | DATABASE_URL | — | Postgres or SQLite connection string | | ANTHROPIC_API_KEY | — | Anthropic API key | | OPENAI_API_KEY | — | OpenAI API key | | GOOGLE_AI_API_KEY | — | Google Gemini API key | | OLLAMA_URL | — | Ollama server URL | | OLLAMA_MODEL | — | Ollama model name | | ONX_MCP_SERVER_URL | — | MCP HTTP server URL | | SEED_DATA | false | Load sample data on first run | | SESSION_TTL_MINUTES | 30 | Demo session timeout | | MAX_MESSAGES_PER_SESSION | 20 | Rate limit for playground in demo mode |

Local Development (without Docker)

cd juniper-app
npm install
cp .env.example .env.local   # edit with your keys
npm run dev

Visit http://localhost:3000.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: commerce-operations-foundation
• Source: commerce-operations-foundation/juniper-commerce
• License: MIT
• Homepage: https://junipercommerce.fulfillmentiq.com

Install and usage instructions live in the source repository linked above.