commerce-mcp

An AI / MCP control plane for SAP Commerce Cloud (Hybris).

🌐 Live site: https://alextsvetkov.github.io/commerce-mcp/

commerce-mcp exposes a SAP Commerce estate to LLM agents and developer copilots as a set of safe, typed, read-only tools over the Model Context Protocol (MCP). Instead of clicking through HAC and Backoffice, an engineer (or an agent acting on their behalf) can ask:

"Describe the Order type." "Why did order PROD-4471 fail validation?" "Write ImpEx to add a loyaltyTier attribute to Customer — and validate it against the live model first."

⚠️ Status: early scaffold. The tool surface, safety model and mock connector are real and tested; the live Hybris connector is a documented extension point, not yet implemented. See Roadmap.

Why this exists

SAP Commerce is powerful but opaque and expertise-gated. Every meaningful interaction — inspecting the type system, running a FlexibleSearch, writing correct ImpEx, tracing an order — requires deep tribal knowledge and manual navigation. LLMs can't help today because they have no safe, structured way in.

commerce-mcp is that way in. It is the "hands and eyes" that make a legacy commerce platform legible to agents — collapsing the single biggest cost driver on any SAP Commerce program: scarce expertise and slow onboarding.

See docs/ (the GitHub Pages site) for the full benefits narrative.

Related MCP server: odata-mcp-proxy

Design principles

1. Read-only by default. Every shipped tool is non-mutating. run_flexible_search rejects anything that isn't a SELECT; write paths (applying ImpEx) are deliberately out of scope for this surface and require separate, explicit authorization.

2. Safe by construction. Row caps, keyword denylists, and (planned) PII redaction + audit logging are product features, not afterthoughts.

3. Offline-first. A fixture-backed MockConnector makes the entire tool surface runnable and testable with zero configuration — no live instance needed for demos or CI.

4. Transport-neutral core. Tools are plain (schema, description, handler) triples; MCP is one adapter. A CLI or HTTP surface can reuse the same catalogue.

Architecture

        LLM / Agent (Claude, Copilot, …)
                    │  MCP (stdio)
        ┌───────────▼───────────┐
        │   commerce-mcp server  │  src/server/index.ts
        ├────────────────────────┤
        │   tool catalogue       │  src/tools/index.ts  (zod-typed, read-only)
        ├────────────────────────┤
        │   CommerceConnector    │  src/types.ts (interface)
        │   ├─ MockConnector     │  fixtures — offline
        │   └─ LiveConnector*    │  HAC / OCC / read-only DB view  (*planned)
        └────────────────────────┘
                    │
          SAP Commerce Cloud (Hybris)

Tools (v0.1)

Quick start

npm install
npm run build
npm start          # runs the MCP server on stdio against the MockConnector
npm test           # unit tests, no live instance required

Use from an MCP client

Add to your client's MCP server config (example for a Claude-style client):

{
  "mcpServers": {
    "commerce": { "command": "node", "args": ["dist/server/index.js"] }
  }
}

Usage

This snippet is distilled from the runnable example below; the Output: block is the real captured stdout.

MockConnector + buildTools() — describe, query, and the read-only guard

import { MockConnector } from "commerce-mcp/src/mock-connector.js";
import { buildTools } from "commerce-mcp/src/tools/index.js";

const connector = new MockConnector();
const tools = buildTools(connector);
const call = (name: string) => tools.find((t) => t.name === name)!;

console.log("tools:", tools.map((t) => t.name).join(", "));

// describe_type: full type definition (parent, deployment table, attributes).
const product = await call("describe_type").handler({ code: "Product" }) as any;
console.log(`describe_type Product: extends=${product.extends}, table=${product.deploymentTable}, attrs=[${product.attributes.map((a: any) => a.qualifier).join(", ")}]`);

// run_flexible_search: a read-only SELECT returns capped fixture rows.
const res = await call("run_flexible_search").handler({ query: "SELECT {code},{name} FROM {Product}", maxRows: 10 }) as any;
console.log("run_flexible_search:", JSON.stringify(res));

// SAFETY: a mutating statement is rejected before it reaches the backend.
try {
  await call("run_flexible_search").handler({ query: "DELETE FROM {Product}", maxRows: 10 });
} catch (err) {
  console.log(`DELETE rejected: ${(err as Error).name}: ${(err as Error).message}`);
}

Output:

tools: describe_type, list_types, run_flexible_search, validate_impex
describe_type Product: extends=GenericItem, table=products, attrs=[code, name, catalogVersion]
run_flexible_search: {"columns":["code","name"],"rows":[{"code":"PROD-001","name":"Sample Product"},{"code":"PROD-002","name":"Another Product"}],"rowCount":2,"capped":false,"tookMs":3}
DELETE rejected: ReadOnlyViolationError: Only SELECT queries are permitted through this tool.

Examples

Runnable, heavily-commented tutorials live in examples/. Run them with tsx (already a dev dependency) — no build step:

Run example 02 against a local SAP Commerce / HAC instance:

COMMERCE_BASE_URL=https://localhost:9002 \
COMMERCE_USER=admin COMMERCE_PASSWORD=nimda COMMERCE_INSECURE_TLS=true \
npx tsx examples/02-live-connector.ts

Roadmap

• LiveConnector over HAC (login + FlexibleSearch + type introspection), verified against a real instance.

• OCC read paths + a read-only DB view connector.

• PII redaction layer + structured audit log for every tool call.

• explain_business_process, list_feature_toggles, trace_order tools.

• zod-to-json-schema wiring so tool input schemas are fully published to the client.

• Opt-in, separately-authorized write surface (apply validated ImpEx).

Connecting to a real Hybris instance

By default the server uses the offline MockConnector. Set these env vars to point it at a live SAP Commerce instance (it auto-switches to LiveConnector):

export COMMERCE_BASE_URL=https://localhost:9002   # HAC base (root context)
export COMMERCE_USER=admin
export COMMERCE_PASSWORD=nimda
export COMMERCE_INSECURE_TLS=true                 # allow self-signed TLS (local dev)
npm start

Verified live against the SAP cloud-commerce-sample-setup: run_flexible_search, list_types, and describe_type return real data; run_flexible_search rejects any non-SELECT statement.

Contributing

See CONTRIBUTING.md. This project follows conventional commits and keeps generated code out of version control.

License

MIT © 2026 Aliaksandr Tsviatkou

Honest assessment

From the v2 self-critical analysis. Scores use Gap · Value · Moat · Time-to-revenue · Risk (for Risk, higher = safer). Prior art is named deliberately — "no competitor" is almost never true.

Scores: Gap 5 · Value 4 · Moat 3 · TTR 4 · Risk 3 (higher=safer)

• Prior art / competition. MCP is new; SAP's Joule/CX AI is storefront-facing, not developer/ops-facing. Thin prior art — the strongest of the suite.

• True differentiator. Depth and safety of type-system / ImpEx / FlexibleSearch semantics, and being the first safe agent entry point others build on.

• Kill criterion. If target teams won't let an agent touch prod data even read-only, and won't pay for a sandboxed variant, the wedge is weaker than it looks.

• Verdict. Build this as the one commercial wedge — but from public HAC/OCC APIs, never internal employer code.

This assessment is part of a broader, self-critical analysis of the whole tool suite (problem landscape, go-to-market, and an IP / conflict-of-interest review) maintained privately by the author.

Part of a suite of backend tools for SAP Commerce Cloud. commerce-mcp is the AI-native flagship; sibling projects cover schema migration, ImpEx tooling, tracing, upgrades, and eventing correctness.