Fulfillment Review MCP

A Streamable HTTP MCP server for investigating partial-fulfillment holds and preparing complete human-review cases. It reads a synthetic commerce snapshot, calculates source-supported fulfillment options, presents delivery-date and shipping-cost effects together, and persists one immutable escalation for a human decision.

The server does not modify inventory, reservations, fulfillment routing, or shipments. It does not rank, recommend, select, or execute an option.

Workflow

Workflow diagram showing four MCP tools from hold investigation to human review

The accessible sequence is: investigate the hold, preview options from the same evidence version, create the escalation, read it back, then hand it to a human reviewer.

The evidence version is a SHA-256 digest of canonical source data. Preview and escalation calls fail closed when that version is stale. The escalation tool accepts only an order ID and evidence version; the server reconstructs the evidence and options instead of trusting model-authored case content.

MCP tools

Tool	Effect	Purpose
`investigate_fulfillment_hold`	Read-only	Gather order, reservation, inventory, quote, and hold evidence.
`preview_fulfillment_options`	Read-only	Return source-supported options with both date and cost effects.
`create_human_review_escalation`	Additive, idempotent write	Persist or return one canonical review case for an evidence version.
`get_human_review_escalation`	Read-only	Read back the exact persisted case for verification.

The create tool is the only write. Its MCP annotations mark it as non-destructive and idempotent. All tools operate in a closed domain.

Synthetic scenario

The included order, ORD-1042, is partially reserved at a Bengaluru warehouse. One line item is unavailable there. The source snapshot supports two alternatives:

One complete shipment from Mumbai, arriving one day after the promised date for INR 100.00 more than the current plan.
A Bengaluru and Hyderabad split, arriving on the promised date for INR 115.00 more than the current plan.

Both are facts, not recommendations. A human reviewer owns the tradeoff.Option IDs are sorted only for reproducible output; their order has no preference meaning.

Architecture

Component architecture showing transport, MCP tools, domain logic, and storage boundaries

src/http.ts owns transport and request security. src/server.ts and src/tools/ own the MCP boundary. src/domain/ owns evidence, versioning, option feasibility, and review-case invariants. src/infrastructure/ provides the immutable commerce source and append-only SQLite review cases.

The domain layer does not know about HTTP or MCP. The commerce source exposes no mutation methods. SQLite stores only review cases and has no update or delete operation.

Requirements

Node.js 24 LTS
npm 11 or later

All direct dependencies are pinned and the lockfile is committed.

Run locally

nvm use
cp .env.example .env
npm ci
npm run dev

The default endpoints are:

MCP: http://127.0.0.1:3000/mcp
Health: http://127.0.0.1:3000/health

Run the complete four-tool smoke test in another terminal:

npm run smoke -- http://127.0.0.1:3000/mcp

The smoke script uses the official MCP client, validates every structured result, creates an escalation, and reads it back.

MCP client configuration

{
  "mcpServers": {
    "fulfillment-review": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

List tools with the official MCP Inspector:

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:3000/mcp --transport http --method tools/list

Configuration

Variable	Default	Description
`HOST`	`127.0.0.1`	HTTP bind address.
`PORT`	`3000`	HTTP port.
`DATABASE_PATH`	`./data/review-cases.sqlite`	SQLite database path.
`ALLOWED_HOSTS`	`localhost,127.0.0.1`	Allowed Host header hostnames without ports.
`ALLOWED_ORIGIN_HOSTS`	`localhost,127.0.0.1`	Allowed Origin hostnames without schemes or ports. Requests without Origin are allowed for non-browser MCP clients.
`LOG_LEVEL`	`info`	`debug`, `info`, `warn`, or `error`.

Configuration is validated before the server starts. Logs are structured JSON and exclude request bodies, evidence payloads, environment values, database paths, and secrets.

Verification

npm run verify

This runs:

Prettier check
ESLint with zero warnings
Strict TypeScript checking
Unit, integration, transport, and MCP end-to-end tests
V8 coverage with 95 percent global thresholds
Production TypeScript build

The test suite covers deterministic hashing, missing inventory, unsupported or incomplete splits, date and cost deltas, stale evidence, immutable and idempotent storage, exact MCP annotations, arbitrary-field rejection, sanitized errors, Host and Origin validation, body limits, health checks, and the complete four-tool workflow.

Container

docker build -t fulfillment-review-mcp .
docker run --rm \
  -p 3000:3000 \
  -v fulfillment-review-data:/data \
  -e ALLOWED_HOSTS=localhost,127.0.0.1 \
  -e ALLOWED_ORIGIN_HOSTS=localhost,127.0.0.1 \
  fulfillment-review-mcp

The image uses Node.js 24, runs as a non-root user, includes a health check, and stores SQLite data in /data.

For a remote deployment, terminate TLS at a reverse proxy, keep the application port private, preserve the public Host header, configure the exact public hostname allowlists, and mount /data persistently.

Security and production boundary

This repository is a bounded demonstration using synthetic data. Authentication is intentionally excluded. A production commerce integration would additionally require:

OAuth and tenant isolation
authorization for each merchant and order
managed secret storage
external rate limiting and abuse controls
real commerce-source credentials and availability handling
database backup, migration, retention, and deletion policies
operational metrics and alerting

The current public endpoint can write at most one review case for each finite order and evidence version. Repeated requests return the existing record.

Assumptions and exclusions

This demonstration assumes:

The commerce source is authoritative for order, reservation, inventory, split-support, and shipping-quote data.
Upstream systems have already calculated shipping costs and estimated delivery dates.
Any source-data change produces a new evidence version before another workflow step can continue.
A human reviewer acts on the recorded case through a separate operations system.

The repository intentionally excludes:

inventory, reservation, routing, and shipment mutations
option ranking, recommendation, selection, or execution
review approval and resolution workflows
live commerce-provider integrations and customer data
authentication, tenant management, and a frontend

Design decisions

No embedded model call: the MCP host performs reasoning; the server owns facts and deterministic calculations.
No ORM: one append-only table is clearer as direct SQL.
No web framework: Node HTTP plus the official MCP Node adapter covers the transport surface.
No mutable commerce adapter: unsafe operations are absent rather than guarded by prompt instructions.
Integer minor currency units: cost calculations avoid floating-point ambiguity.
Fixed synthetic dates: tests and demonstrations remain reproducible.

License

MIT

Fulfillment Review MCP