Stalled Fulfillment Recovery — MCP Server

An MCP server that lets ops (via an AI assistant) diagnose and recover orders stuck in "processing" due to missing or failed fulfillment tasks.

Safety by construction: the only write tools are retry_fulfillment (resets a fulfillment task) and escalate_order (writes an audit entry). There are no payment mutation tools — the domain boundary is the safety boundary.

Product Decisions & Assumptions

Problem: Operations teams can't independently diagnose or fix stalled fulfillment issues — they lack cross-system visibility and safe write access, so even routine cases get escalated to engineers.

Scope: Single-order investigation of stalled fulfillment. We handle three known stall patterns (no fulfillment task, failed task, silently stalled task). Genuinely novel or ambiguous failures escalate to humans via escalate_order.

Assumptions:

• User interacts via an MCP-connected AI client (e.g. Claude Desktop) — no custom frontend
• Writes are simulated (no real warehouse/carrier API) but safety boundaries (dry-run, rate-limit, escalation) are real
• Single-order investigation, not batch operations

Exclusions: Authentication, multi-tenant access control, payment mutations, real carrier integrations, batch operations, frontend.

Database Setup (PostgreSQL)

This server uses PostgreSQL for persistent data storage. Tables are auto-created on startup.

# Environment Variable (optional, defaults to postgres://localhost:5432/fulfillment_mcp)
export DATABASE_URL="postgres://username:password@localhost:5432/fulfillment_mcp"

Quick Start

npm install
npm run build && npm start   # production on :3000
# or
npm run dev                  # dev server on :3000

Health check:

curl http://localhost:3000/health

MCP Inspector:

npx @modelcontextprotocol/inspector --url http://localhost:3000/mcp

MCP Capabilities

Tools

Tool	Type	Description
get_order	Read	Fetches an order + its fulfillment task in one call
get_fulfillment	Read	Fetches a fulfillment task by ID with full failure detail
list_stalled_orders	Read	Surfaces all orders stuck in processing (3 stall types) via optimized SQL JOIN
retry_fulfillment	Write	Resets a stalled fulfillment to pending. Always dry-run first
escalate_order	Write (audit only)	Flags an order for human review without mutating state
get_audit_log	Read	Returns the full action history for an order

Resources

Resource URI	Description
order://{order_id}	Direct JSON access to an order and its fulfillment task
fulfillment://{order_id}	Direct JSON access to a fulfillment task by order ID

Prompts

Prompt	Description
diagnose_stalled_orders	Guided workflow that instructs the AI to discover stalled orders, inspect each, decide retry vs escalate, and summarize actions. Accepts optional threshold_hours parameter.

Stall Detection

list_stalled_orders detects three types of stall for any paid/processing order older than threshold_hours (default: 24h), using a single optimized SQL LEFT JOIN query:

stall_reason	Condition
no_fulfillment_task	No FulfillmentTask row was ever created
fulfillment_failed	FulfillmentTask.status === "failed"
fulfillment_stalled	Task is pending/in_progress but lastActivityAt is older than the threshold

Example Workflow

Ops: "Show me all stuck orders"

AI: → list_stalled_orders(threshold_hours: 24)
    ← 3 stalled orders found

AI: → get_order("ORD-1042")
    ← Order: processing, Fulfillment: failed (warehouse_api_timeout, 2 attempts)

AI: → retry_fulfillment("ORD-1042", confirm=false)
    ← dry_run: will reset FUL-1042 to pending (attempt 3)

Ops: "Looks good, go ahead."

AI: → retry_fulfillment("ORD-1042", confirm=true)
    ← success: fulfillment reset, audit entry created

AI: → get_audit_log("ORD-1042")
    ← [fulfillment_retry @ 2026-08-01T04:15:00Z]

Safety Details

• Dry-run required: retry_fulfillment returns a preview when confirm=false without mutating anything. Show this to the operator before confirming.
• Rate-limit: A second retry on the same order within 10 minutes is rejected with double_retry_prevented. This is a rate-limit (time window), not true idempotency — a second retry after the cooldown is permitted, because the first may itself have failed.
• Escalation path: When an order doesn't match the standard stall pattern, use escalate_order to write a permanent audit entry recording why the AI declined to act automatically.
• No payment tools: There is no refund or payment write tool in this MCP. The scope boundary enforces the safety boundary.

Development & Testing

npm run build         # TypeScript compile
npm run test          # Vitest safety tests against live PostgreSQL
npm run test:watch    # Watch mode

Tests run against live PostgreSQL and create their own data at runtime — no hardcoded fixtures or seed data dependencies.

Live Hosted Deployment

The MCP server is live and hosted on Render:

• Base URL: https://mcp-ecom.onrender.com
• MCP Endpoint: https://mcp-ecom.onrender.com/mcp
• Health Check: https://mcp-ecom.onrender.com/health

Connecting in Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "stalled-fulfillment-recovery": {
      "url": "https://mcp-ecom.onrender.com/mcp"
    }
  }
}

Deployment

The server listens on process.env.PORT (default: 3000). Deploy anywhere that runs Node.js and has PostgreSQL access:

• Railway / Render / Fly.io / Heroku: push the repo, set DATABASE_URL and PORT
• Docker: node dist/index.js
• The MCP endpoint is POST /mcp (stateless HTTP, no sessions)

After deploying:

curl https://mcp-ecom.onrender.com/health
npx @modelcontextprotocol/inspector --url https://mcp-ecom.onrender.com/mcp

Tech Stack

• Database: PostgreSQL (pg driver)
• MCP SDK: @modelcontextprotocol/sdk ^1.12 (stable)
• Transport: StreamableHTTPServerTransport (stateless, HTTP)
• Framework: Express 5
• Validation: Zod 3
• Tests: Vitest — focused safety verification against live PostgreSQL
• Language: TypeScript (ESM, strict)