mcp-ecommerce

An MCP server that lets an AI agent investigate stuck orders, surface fulfillment anomalies, and create escalation records — turning a multi-tab ops investigation into a single natural-language query.

Deployed on Railway with a PostgreSQL database. Connect any MCP-compatible client to the hosted URL and start querying immediately — no local setup required to evaluate.

Hosted MCP Server

https://ecom-mcp-production-f5bf.up.railway.app/sse

The server and its PostgreSQL database are both running on Railway. The /sse endpoint is live and accepting MCP client connections.

Connect via the included Groq client

git clone https://github.com/beinghadibadami/ecom-mcp.git
cd ecom-mcp
npm install
cp .env.example .env 
# add GROQ_API_KEY  and MCP_SERVER_URL=https://ecom-mcp-production-f5bf.up.railway.app

npm run client:remote -- "why is order ord_pick_002 stuck?"

The client prints each tool call and result as it runs, then a [final answer].

Related MCP server: ShopBot AI MCP Server

MCP Tools

Anomaly thresholds (hardcoded in src/constants.ts)

Thresholds are enforced in code — the model never invents or infers them.

Demo Orders (seeded synthetic data)

Architecture

Ops Engineer (natural-language query)
        ↓
Groq client — llama-3.3-70b-versatile
  drives multi-turn tool-call loop (max 10 iterations)
        ↓  MCP JSON-RPC over SSE
MCP Server (Railway) — SSEServerTransport
        ↓  pg connection pool
PostgreSQL (Railway) — orders, payments, fulfillments, escalations

Transport is selected by environment: MCP_TRANSPORT=http → SSE (Railway), otherwise stdio (local dev).

Key Product Decisions

Escalation enforcement — 3 layers

A write operation that creates a manager-review ticket needs to be safe. Enforcement works at three independent levels:

1. System prompt — instructs the model to only call create_escalation on explicit single-order investigation requests, never during general listing queries

2. Business layer — hasConfirmedAnomaly() re-queries the database before any insert; if no SLA breach or payment failure is confirmed, the function returns a blocked error and nothing is written

3. Database constraint — UNIQUE on escalations.order_id prevents duplicates even under concurrent requests

Listing vs. investigation intent

General listing queries ("show me flagged orders") call list_flagged_orders and return evidence only. Specific order queries ("investigate ord_pick_002") follow the full chain and may escalate. This distinction is enforced in the system prompt and backed by the business layer — listing can never accidentally trigger a write.

Idempotency

create_escalation called twice for the same order returns created: false with the existing record. The anomaly gate still runs on the second call, so only genuinely anomalous orders can ever hold an escalation.

Running Tests

Tests use Node's built-in test runner against a live local database — no mocking.

# make sure local DB is running and seeded first
npm test

Out of Scope

Frontend, authentication, real payment provider integrations, and CI/CD are intentionally excluded per the assignment brief.