Commerce Operations MCP

Status: domain/data foundation plus a working MCP server exposing four read-only investigation tools, served over both local stdio and remote Streamable HTTP (hosted on Render). No write/action tool yet — see "Current limitations".

Hosted MCP URL: https://e-commerce-mcp.onrender.com/mcp (Streamable HTTP, stateless — see "Connecting to the hosted server" below)

Working name: commerce-ops-mcp (may change before final delivery).

An AI-native commerce operations investigator focused on delayed-order investigation, exposed through a remotely hosted MCP server.

Problem

An operations specialist needs to answer, for a given order: "why is this order delayed, and what should I do about it?" Answering that well often requires checking payment status, inventory availability, and fulfillment state — but the product is that one investigation workflow, not standalone tooling for payments, inventory, or fulfillment.

Confirmed scope (client-clarified): a single, focused end-to-end workflow — delayed-order investigation — is the right level of scope. Separate coverage of all four commerce domains (orders, payments, inventory, fulfillment) as independent workflows is explicitly out of scope. The project intentionally does not provide independent workflows for payments, inventory, fulfillment, or general order management; those systems are consulted only as supporting evidence when investigating a delayed order.

Current scope

This repository implements the backend foundation plus a working MCP server on top of it:

• Domain types and status enums
• A synthetic, internally consistent commerce dataset (static TypeScript modules)
• A repository layer over that dataset
• An OrderContextService that composes operational facts (not diagnoses) for a given order
• A DelayDiagnosisService that applies deterministic rules to those facts to identify the likely delay cause
• A ResolutionService that maps a diagnosis to recommended next actions
• An MCP server exposing search_orders, get_order_context, diagnose_order_delay, and recommend_resolution as tools, over two transports sharing the same tool registration (src/mcp/create-server.ts):
  • src/mcp/server.ts — stdio, for local MCP clients (Claude Desktop/Code, MCP Inspector)
  • src/mcp/http.ts — Streamable HTTP (stateless), deployed remotely on Render for AI agents to connect to without any local setup
• Tests covering all of the above

No write/action tool (create_resolution_ticket), LLM/agent integration, database, or frontend exists yet. See CLAUDE.md for the explicit scope boundary and docs/assumptions.md / docs/decisions.md for what's decided vs. pending.

Architecture

Synthetic data (src/data/*.ts — static, typed TypeScript modules)
        ↓
Repositories (src/repositories/*.repository.ts)
        ↓
Domain services (order-context.service.ts, delay-diagnosis.service.ts,
                  resolution.service.ts)
        ↓
src/mcp/create-server.ts — search_orders, get_order_context,
                            diagnose_order_delay, recommend_resolution
        ↓                              ↓
src/mcp/server.ts (stdio)   src/mcp/http.ts (Streamable HTTP → Render)

Repositories hide the underlying data representation; services and the MCP tools depend only on repository method signatures, not on how the data is stored. See docs/decisions.md for why static TypeScript modules were chosen over PostgreSQL, why the MCP tool set stops at four read-only tools for now, and why the remote transport runs in stateless mode.

Connecting to the hosted server

No local setup is required to try the deployed workflow — point any MCP client that supports Streamable HTTP at:

https://e-commerce-mcp.onrender.com/mcp

For example, with the MCP Inspector:

npx @modelcontextprotocol/inspector
# then connect with transport "Streamable HTTP" and the URL above

The server is stateless and unauthenticated (read-only synthetic data only — see docs/decisions.md for that tradeoff, stated explicitly rather than left implicit). The /mcp endpoint is rate-limited to 60 requests per IP per minute (in-memory, per-instance — see docs/decisions.md) as a basic abuse guard given the lack of authentication.

Running locally

npm install
npm run typecheck
npm test

# stdio transport (for Claude Desktop/Code, MCP Inspector over stdio)
npm run build
npm start

# Streamable HTTP transport (what's deployed to Render)
npm run build
npm run start:http   # listens on $PORT, defaults to 3000

Point any MCP client (e.g. npx @modelcontextprotocol/inspector node dist/server.js, or Claude Desktop/Code's MCP config) at npm start (from this directory) to connect over stdio.

Testing

Tests use Vitest and live in tests/, mirroring src/:

• tests/repositories/ — finder methods, including missing-record cases
• tests/services/ — OrderContextService (context composition, including the ORD-1003 inventory-shortage case), DelayDiagnosisService (all seven scenario orders map to their expected category), and ResolutionService
• tests/data/ — cross-record invariant checks (foreign keys, order totals, one-record-per-order cardinality, required scenario orders) run against the real dataset and against deliberately broken copies of it — checks TypeScript's structural typing can't express on its own

Synthetic data

src/data/ contains 18 products, 15 customers, 50 orders, and their corresponding payments/inventory/fulfillment records — all synthetic, INR-priced, .test-domain emails, MockPay as the fake payment provider. Each entity is a static, typed TypeScript module (e.g. src/data/orders.ts) rather than a JSON file; the dataset was generated once and is now finalized and hand-editable in place — see docs/decisions.md.

Seven orders (ORD-1001–ORD-1007) are deterministic, hand-crafted scenarios representing known operational situations (payment failure, inventory shortage, fulfillment delay, etc.) — see docs/test-scenarios.md for the full table.

Current limitations

• No write/action tool (create_resolution_ticket) — read-only investigation, diagnosis, and recommendation only.
• No persistence beyond static TypeScript modules; no database.
• No authentication/authorization on the hosted HTTP endpoint — deliberate and disclosed, not an oversight; see docs/decisions.md. Acceptable here because the tool set is read-only and the data is synthetic; would need revisiting before any real data touched this server. Mitigated in part by a per-IP rate limit (60 req/min, in-memory) on /mcp, but that limits abuse per-instance only, not a substitute for real auth.
• No real external integrations of any kind.

Future stages

Not yet built, and out of scope for this submission: one controlled, confirmation-gated write action (create_resolution_ticket), and authentication on the hosted endpoint if this ever handled real data. See CLAUDE.md and docs/decisions.md / docs/assumptions.md for what's confirmed vs. still open.