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.

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)

Tool	Purpose
describe_type	Full definition of an item type (attributes, parent, deployment table).
list_types	Enumerate type codes, optional substring filter.
run_flexible_search	Execute a read-only FlexibleSearch SELECT, capped rows.
validate_impex	Statically validate ImpEx against the live type model before applying.

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"] }
  }
}

Roadmap

• [ ] LiveConnector over HAC + OCC + a read-only DB view.
• [ ] 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).

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.

See the full landscape, go-to-market and the IP / conflict-of-interest discussion in sap-commerce-general-ideas-for-startup.md.

---

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.