# OrderOps MCP

OrderOps is a small, AI-native operations service for investigating and safely
resolving commerce order exceptions. It gives an MCP-capable assistant a
coherent workflow across synthetic order, payment, inventory, and fulfillment
systems without requiring an operator to ask an engineer for every trace.

Source repository: <https://github.com/Flamki/order-ops-mcp>

The deliberately narrow automated path is an expired inventory reservation:
when payment is captured, stock is available, and fulfillment is blocked on the
missing reservation, an operator can review a state-bound proposal and approve
a re-reservation. Payment changes, customer data, refunds, cancellations, and
customer contact are never automated.

## Hosted endpoint

- MCP: `https://order-ops-mcp.shared-trapezoid.workers.dev/mcp`
- Health: `https://order-ops-mcp.shared-trapezoid.workers.dev/health`

The Cloudflare deployment has been claimed by its owner and the deployed
Streamable HTTP endpoint has been verified with the included MCP client.
Proposal, execution, and idempotency state is coordinated in one SQLite-backed
Durable Object.

## Product workflow

1. `orders_list_exceptions` discovers the three synthetic exception cases.
2. `orders_investigate` joins evidence from the OMS, payment processor,
   inventory service, and fulfillment provider.
3. `orders_propose_resolution` rechecks policy and creates a 10-minute proposal
   bound to the current order-state fingerprint.
4. The assistant presents the evidence, exact changes, and approval phrase to a
   human and stops.
5. `orders_execute_resolution` validates exact approval, expiry, unchanged
   state, policy preconditions, and an idempotency key before mutating the
   synthetic order.
6. The operator receives a structured before/after receipt. An exact retry
   returns the original receipt and does not mutate twice.

The MCP is the product boundary, not a wrapper around a separate UI. Tool
descriptions tell the model when to call each capability, Zod schemas advertise
and validate inputs and structured outputs, annotations identify read and write
behavior, and the server exposes the governing runbook as an MCP resource. A
prompt provides a client-independent triage workflow.

## MCP surface

| Capability | Role | Side effect |
|---|---|---|
| `orders_list_exceptions` | Discover synthetic cases | None |
| `orders_investigate` | Explain cross-system root cause and evidence | None |
| `orders_propose_resolution` | Create a short-lived, state-bound proposal | No order mutation |
| `orders_execute_resolution` | Apply the single permitted resolution and return a receipt | Mutates synthetic state |
| `demo_reset_synthetic_state` | Let another evaluator replay the synthetic workflow | Clears all demo state |
| `ops://runbooks/order-exceptions/v1` | Machine-readable automation policy | None |
| `triage-order-exception` | Prompt that enforces investigate → propose → wait | None |

## Demo cases

| Order | Diagnosis | Automated? |
|---|---|---|
| `ORD-1001` | Captured payment, expired reservation, fulfillment blocked, stock available | Yes, with explicit approval |
| `ORD-1002` | Payment failed | No |
| `ORD-1003` | Invalid shipping address | No |
| `ORD-1004` | Healthy control order | No action needed |

All records are synthetic and contain no customer PII or production
credentials.

## Test with an MCP client

Use the MCP Inspector and connect to `http://localhost:8787/mcp`:

```bash
npx @modelcontextprotocol/inspector@latest
```

Or use the included real Streamable HTTP client:

```bash
npm install
npm run dev
```

In a second terminal:

```bash
npm run demo
```

The default demo stops before mutation. Only after reviewing the proposal:

```bash
npm run demo -- --execute-approved
```

If another evaluator has already resolved the shared synthetic order:

```bash
npm run demo -- --reset-first --execute-approved
```

To target a deployed server:

```powershell
$env:MCP_URL = "https://your-worker.workers.dev/mcp"
npm run demo
```

## Verify and deploy

Requirements: Node.js 22+ and npm.

```bash
npm install
npm run verify
npx wrangler deploy --dry-run
npm run deploy
```

`npm run verify` performs strict TypeScript checking and 14 focused tests. The
tests cover diagnosis, out-of-policy cases, exact approval, proposal expiry,
stale state, mutation receipts, idempotent replay, and idempotency conflicts.
`npm audit` currently reports zero known vulnerabilities.

Cloudflare Workers is used because it directly supports remote Streamable HTTP
MCP via the TypeScript MCP SDK and provides a small deployment surface. The
server follows the current stateless handler pattern rather than the deprecated
sessionful `McpAgent` path.

## Architecture and boundaries

```text
MCP client
    |
Streamable HTTP /mcp
    |
tool schemas + policy gates
    |
investigation / proposal / execution domain
    |
synthetic OMS + payments + inventory + fulfillment adapter
```

For the bounded demo, a named Durable Object serializes operations and persists
the synthetic adapter, proposals, receipts, and idempotency ledger in SQLite.
A production version would replace the synthetic order adapter with internal
OMS/WMS APIs, add OAuth and role scopes, retain immutable audit events,
rate-limit writes, and define operational reset/recovery procedures. The domain
rules and tests remain reusable.

Human approval is a semantic client boundary, not proof of human presence: an
untrusted client can copy an approval phrase. Production execution therefore
also needs authenticated operator identity and an approval UI or MCP
elicitation flow.

See [product decisions](docs/PRODUCT_DECISIONS.md),
[AI worklog](docs/AI_WORKLOG.md), [demo script](docs/DEMO_SCRIPT.md), and
[client communication drafts](docs/CLIENT_COMMUNICATION.md).