AI-First Commerce Operations Investigator

A remotely hosted TypeScript MCP that helps a commerce operations specialist answer one bounded question:

Why has this paid order not reached shipment creation?

The workflow collects synthetic order, payment, inventory, fulfilment, event, and shipment evidence; checks whether that evidence is complete and coherent; applies deterministic TypeScript rules; persists an immutable investigation and audit trail; and can create a human-review escalation. It recommends a next step but never changes commerce state.

Live review

Start here:

• Reviewer guide

• Final evaluation

• Verification evidence

• Hosted verification PDF

• Engineering decisions and bugs

• AI worklog

Demo video: Watch the 4–5 minute hosted MCP workflow demo

Related MCP server: commerce-operations-mcp

Product workflow

The model is used only for natural-language interaction, approved tool selection, and explanation of validated server results. It does not create business facts, calculate diagnosis, select an arbitrary queue, or mutate commerce data.

Why MCP is central

• The AI host reaches the workflow through Streamable HTTP MCP, not through workflow or database imports.

• Tool schemas define the complete capability surface and reject unsupported fields.

• Tool descriptions explain side effects, identifiers, and safe retry behavior.

• The server returns versioned structured results and finite safe errors.

• MCP Inspector, Gemini CLI, the direct evaluator, and the model-backed host use the same /mcp contract.

• The deterministic MCP remains usable when the external model provider is unavailable.

Exact MCP tool surface

Investigation and escalation write workflow records only. The MCP exposes no order update, inventory reservation, warehouse reassignment, fulfilment retry, shipment creation, SQL, reset, or unrestricted HTTP tool.

Data and safety boundary

commerce schema - runtime SELECT only
- orders and order items
- payments
- warehouses and source-specific inventory observations
- fulfilments and fulfilment events
- shipments

operations schema - scoped workflow writes
- investigations
- immutable evidence snapshots
- human-review escalations
- idempotency records
- append-only audit events

The running API uses a restricted PostgreSQL role and cannot insert, update, or delete commerce records. Every investigation and escalation response states commerceStateChanged=false.

Approved synthetic scenarios

The fixtures use a fixed reference time and contain no real customer data. See the approved scenario contract.

Verification summary

MCP Inspector: exact five-tool discovery

Hosted workflow: grounded investigation result

Automated hosted model-backed evaluation

Independent MCP-compatible AI client

The complete sequence, including the authenticated Inspector setup and investigation input, is documented in the Reviewer guide and evidence index.

Important tradeoffs and limitations

• Deterministic diagnosis: results are testable and auditable, but adding a diagnosis requires a reviewed code change.

• Immutable decision-time evidence: newer source evidence is evaluated through a new investigation rather than rewriting history.

• No automatic operational fix: the workflow stops at a recommendation and optional human-review case.

• Sequential Gemini requests: reduces free-tier rate-limit pressure but increases latency and limits throughput.

• Bounded retries: exhausted daily or project quota still returns a provider error.

• Shared reviewer bearer token: suitable for a bounded review window, not individual production identity.

• Single EC2 and PostgreSQL deployment: intentionally simple and continuously available, but without automated failover.

• Synthetic fixed dataset: repeatable for evaluation, not a production commerce integration.

• No frontend: reviewers interact through MCP Inspector or an MCP-compatible AI client.

Documentation

• Reviewer guide

• Final evaluation

• Engineering decisions and bug report

• AI worklog

• Workflow contract

• Approved PostgreSQL schema

• Approved synthetic scenarios

• Architecture and package graph

• AWS deployment guide

• Detailed Phase 12 report

Final submission checklist

• Hosted MCP URL

• Source repository

• Concise README

• Product decisions, assumptions, and exclusions

• Focused tests and runtime verification

• MCP Inspector verification

• MCP-compatible AI-client verification

• AI worklog

• Reviewer token-sharing process

• Four-to-five-minute demo video