Fulfillment Triage MCP

A remotely hosted TypeScript MCP server that helps commerce operations investigate delayed fulfillment stages and create safe, deduplicated human-review escalations.

• Hosted MCP endpoint: https://fulfillment-triage-mcp.onrender.com/mcp
• Health check: fulfillment-triage-mcp.onrender.com/health
• Source: github.com/vdhkcheems/fulfillment-triage-mcp
• Asynchronous demo: Google Drive video

All records are synthetic. The hosted demo requires no local setup.

Try the hosted workflow

Connect any Streamable HTTP-compatible MCP client to:

https://fulfillment-triage-mcp.onrender.com/mcp

For Claude, add this URL under Settings → Connectors → Add custom connector, enable Fulfillment Triage in a new chat, and try:

Investigate CASE-PICKING-OVERDUE. Explain the current stage, timing, threshold, source-reported signals, and supported next action. Do not create an escalation.

Then explicitly approve the only business mutation:

Create the human-review escalation using the investigation you just completed. Do not retry or change the fulfillment itself.

Finally verify persistence and a refusal:

Re-investigate the fulfillment using the previous investigation token.

Investigate CASE-WITHIN-THRESHOLD and try to create an escalation.

Expected results:

• Picking is overdue after strictly exceeding its eight-hour threshold.
• The operator must explicitly request escalation.
• Creation writes an immutable escalation, audit event, and idempotency result only.
• Re-investigation returns ALREADY_ESCALATED.
• The within-threshold request is rejected with FULFILLMENT_NOT_OVERDUE.

The free hosting tier can take about a minute to wake after inactivity.

Product boundary

The selected user is a commerce operations specialist investigating a fulfillment that appears stuck in:

Stage	Escalation threshold
Picking	More than 8 hours after warehouse acceptance
Packing	More than 4 additional hours after picking completion
Carrier handoff	More than 48 additional hours after packing completion

The MCP gathers synthetic order, warehouse, carrier, and existing-escalation evidence. It derives the active stage, calculates elapsed time, distinguishes source observations from proven causes, and recommends a supported next action.

It can create one human-review escalation. It cannot retry, requeue, reroute, cancel, change an address, update fulfillment state, or mutate anything after carrier handoff or dispatch.

MCP surface

Capability	Type	Purpose
investigate_fulfillment	Read-only tool	Evaluate one fulfillment reference and return evidence, timing, decision, signals, and a signed continuation token
create_fulfillment_escalation	Additive tool	Revalidate the signed investigation and create or safely refuse a deduplicated escalation
fulfillment-triage://demo/scenarios	Resource	Describe the synthetic scenarios available in each isolated workspace

Some AI clients do not expose MCP resources or structuredContent to the model. For compatibility, the investigation’s plain-text content includes the essential decision, detailed source-attributed signals, and exact signed continuation token.

Why MCP is central

The model does not receive a generic database or HTTP wrapper. The MCP defines the product workflow and safety boundary:

flowchart LR
    O["Operations specialist"] --> C["MCP-compatible AI client"]
    C --> I["investigate_fulfillment"]
    I --> E["PostgreSQL evidence"]
    I --> D["Derived delay decision"]
    D -->|"Explicit operator approval"| X["create_fulfillment_escalation"]
    X --> R["Lock and revalidate evidence"]
    R --> A["Escalation + audit + idempotency"]

The model cannot supply a stage, threshold, elapsed duration, evidence version, queue, or evidence snapshot. Those values are calculated or recovered from trusted server state.

Safety and correctness

• Source order, warehouse, carrier, and fulfillment records are read-only to MCP tools.
• Threshold equality is not overdue; the stage must strictly exceed its limit.
• Missing or contradictory evidence produces a refusal instead of a guess.
• Source messages are labeled as untrusted observations, not instructions or proven root causes.
• A short-lived HMAC-signed investigation token preserves the exact evidence across clients that open a new MCP session for each tool call.
• Escalation creation locks and reloads evidence, recalculates eligibility, and rejects stale versions.
• Idempotency prevents repeated identical commands; a separate stable episode key prevents duplicates submitted with different keys.
• Escalation, audit event, and idempotency result commit atomically.
• Synthetic workspaces are isolated and expire automatically.
• Request size, origin, active-session, session-lifetime, and error-disclosure boundaries are enforced.

Demo scenarios

Reference	Expected investigation
CASE-PICKING-OVERDUE	Picking overdue; escalation supported
CASE-PACKING-OVERDUE	Packing overdue; escalation supported
CASE-HANDOFF-OVERDUE	Carrier handoff overdue; escalation supported
CASE-WITHIN-THRESHOLD	Not overdue; escalation refused
CASE-ALREADY-ESCALATED	Existing escalation returned
CASE-CANCELLED	Readable but ineligible
CASE-DISPATCHED	Post-dispatch read-only
CASE-MISSING-EVIDENCE	Insufficient evidence; no guess

Architecture

• Node.js 22 and strict TypeScript
• Official MCP TypeScript SDK with Streamable HTTP at /mcp
• PostgreSQL 16 with an executable migration
• Zod input/output schemas
• Domain policy separated from repositories, service orchestration, MCP handlers, and HTTP transport
• Render-hosted Node service and PostgreSQL database

The eight-table schema models demo workspaces, orders, fulfillments, warehouse/carrier evidence, escalations, idempotency, and audit events. See database-schema.md for relationships, statuses, invariants, indexes, rationale, and exclusions.

Local setup

Prerequisites:

• Node.js 22
• Docker

Start PostgreSQL:

docker run --name fulfillment-triage-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=fulfillment_triage \
  -p 5432:5432 \
  -d postgres:16

Install, migrate, and run:

npm ci

export DATABASE_URL='postgresql://postgres:postgres@127.0.0.1:5432/fulfillment_triage'
export INVESTIGATION_TOKEN_SECRET='local-development-secret-at-least-32-characters'

npm run db:migrate
npm run dev

Verify:

curl http://127.0.0.1:3000/health

Use MCP Inspector:

npx @modelcontextprotocol/inspector

Select Streamable HTTP and connect to http://127.0.0.1:3000/mcp.

Verification

Run the complete typecheck, test, and build pipeline against PostgreSQL:

TEST_DATABASE_URL='postgresql://postgres:postgres@127.0.0.1:5432/fulfillment_triage' \
  npm run check

The current suite contains 66 tests covering:

• Exact SLA boundaries and invalid evidence
• All approved and refused scenario decisions
• Read-only investigation behavior
• Atomic escalation, audit, and idempotency writes
• Stale evidence, duplicate keys, and concurrent races
• Signed-token tampering and expiry
• Cross-session investigation, creation, visibility, and replay
• MCP discovery, schemas, text compatibility, resources, and annotations
• HTTP origin, size, session, health, and cleanup controls

The hosted endpoint was also exercised with the official MCP SDK across separate connections and manually through Claude as an independent AI consumer.

Decisions, assumptions, and exclusions

Key decisions:

• Prefer one coherent fulfillment workflow over broad order/payment/inventory coverage.
• Escalate to a human instead of automating operational recovery.
• Keep the mutation additive and make source-system state unreachable from MCP writes.
• Use realistic PostgreSQL-backed synthetic systems rather than hard-coded tool responses.
• Preserve workflow continuity with a signed capability instead of assuming every MCP client retains a transport session.

Assumptions:

• Stage clocks run continuously; calendars and paused SLA windows are out of scope.
• Only the current active stage is eligible.
• Source timestamps and status fields are the available evidence.
• FULFILLMENT_OPERATIONS is a simulated queue represented by PostgreSQL records, not an external ticketing system.

Explicit exclusions:

• Real commerce, warehouse, carrier, or customer data
• Retry, requeue, reroute, cancellation, address changes, refunds, or customer communication
• Escalation assignment, acknowledgement, closure, or downstream queue processing
• Authentication, production tenant identity, and a frontend
• Background monitoring or automatic escalation

Known production limitations:

• Authentication is intentionally omitted because the public assessment uses isolated synthetic data.
• MCP transport sessions are process-local, so the demo runs as one service instance; signed workflow tokens can still reference the database-backed workspace across fresh sessions.
• /health is a process liveness check, not a database-readiness probe.
• The free hosting/database tiers may sleep or expire and are not production infrastructure.
• Rotating the investigation-token secret invalidates outstanding short-lived tokens.

Supporting documents

• Proposed product and technical plan
• Domain contract and safety rules
• PostgreSQL schema rationale
• AI worklog