# 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)](https://modelcontextprotocol.io). 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](#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/`](./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`](./src/mock-connector.ts) 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

```bash
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):

```jsonc
{
  "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

```ts
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:

```text
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/`](./examples/). Run them
with `tsx` (already a dev dependency) — no build step:

| Example | Run it | Teaches |
|---------|--------|---------|
| `examples/01-mock-tools.ts` | `npx tsx examples/01-mock-tools.ts` | `MockConnector` + `buildTools()` driven offline: `describe_type`, `list_types`, `run_flexible_search` (including the read-only rejection of a `DELETE`) and `validate_impex`. Pure offline, zero config. |
| `examples/02-live-connector.ts` | `npx tsx examples/02-live-connector.ts` | The `LiveConnector` over HAC. Runs offline (prints setup guidance and falls back to the MockConnector); set the env vars below to run `run_flexible_search`, `listTypes` and `describeType` against a real instance. |

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

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

## Roadmap

- [x] `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`):

```bash
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](./CONTRIBUTING.md). This project follows conventional commits and keeps generated code out of version control.

## License

[MIT](./LICENSE) © 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.*