Ops Lense

Ops Lense is a remotely hosted Model Context Protocol (MCP) server for commerce operations. It helps an operations specialist investigate stuck orders, understand what went wrong, and take the next safe action without needing an engineer for every incident.

This assignment intentionally focuses on one workflow in depth: stuck-order investigation and remediation across orders, payments, inventory, and fulfillment.

What it demonstrates

An operator can ask an MCP-enabled AI client questions such as:

Why is this paid order still stuck?

The AI can use Ops Lense to:

1. find the order;
2. inspect its operational timeline;
3. diagnose the likely failure from backend data;
4. determine how safely the proposed action can be performed;
5. preview and execute a bounded remediation after operator confirmation; or
6. send a high-risk action to a manual-review queue instead of executing it.

The MCP is therefore the core product interface, not an additional integration around a separate application.

Safety model

Not every commerce operation should have the same level of AI autonomy. Ops Lense separates actions into three categories.

Category	Behavior	Examples
Instant	Read-only investigation can run immediately	Search orders, view timeline, diagnose an order, view statistics
Confirmation required	MCP previews the change first and executes only after explicit operator approval	Resync a missing inventory reservation
Manual review only	MCP cannot execute the action; it creates a pending review request	Refund payment, cancel a shipped order, override fulfillment, adjust inventory

Confirmation flow

resync_inventory_reservation is a guarded write operation.

First call:

confirmed=false

The server validates the order and returns the proposed effect without changing the database.

After the operator explicitly approves the action, the client may call:

confirmed=true

The server then performs the bounded mutation and records an audit entry.

Manual-review flow

Critical actions are intentionally unavailable as direct MCP mutations. request_manual_review creates a pending_review audit entry instead.

The separate process where another operator reviews, approves, and executes those requests is deliberately outside the assignment scope. Pending requests remain visible through list_manual_reviews.

MCP tools

Tool	Safety	Purpose
search_orders	Instant	Find recent orders, optionally filtered by status
get_order_timeline	Instant	View the chronological operational history of an order
diagnose_order	Instant	Detect supported stuck-order conditions from payment and operational evidence
get_order_stats	Instant	View aggregate order counts and revenue by status
resync_inventory_reservation	Confirmation required	Preview and repair a missing inventory reservation after explicit approval
request_manual_review	Manual review	Queue a high-risk operation without executing it
list_manual_reviews	Instant	View outstanding manual-review requests

MCP resource

Ops Lense exposes one operational resource:

ops://action-policy

It describes the three action categories and the rules an MCP client should follow when choosing or executing tools.

I chose a resource rather than an MCP prompt because this is stable operational policy that should be available regardless of how the user phrases their request. A dedicated prompt would add little value to this deliberately narrow workflow.

Example end-to-end workflow

A representative incident is an order where payment was captured successfully but the inventory reservation step is missing.

1. The operator asks why an order is stuck.
2. The AI uses search_orders if it needs to locate the order.
3. It calls get_order_timeline to inspect what has happened.
4. It calls diagnose_order to correlate the payment and operational state.
5. The diagnosis identifies INVENTORY_RESERVATION_MISSING and recommends resync_inventory_reservation.
6. The AI calls the tool with confirmed=false and shows the proposed remediation to the operator.
7. The operator approves it.
8. The AI calls the tool again with confirmed=true.
9. The MCP performs the remediation and writes an audit record.
10. The AI calls get_order_timeline again to verify the resulting state.

A high-risk request follows a different path. For example, if an operator asks for a refund, the MCP creates a manual-review request rather than modifying payment state. The request can then be inspected with list_manual_reviews.

This gives the demo one coherent story covering investigation → diagnosis → human confirmation → mutation → verification → escalation.

Architecture

MCP-enabled AI client
        |
        | Streamable HTTP
        v
   Ops Lense MCP
        |
        +-- Investigation tools
        +-- Diagnostic logic
        +-- Safety / action policy
        +-- Guarded actions
        |
        v
   Neon PostgreSQL
   synthetic commerce data

Technology:

• TypeScript
• Bun for local development and scripts
• Node.js 24 on Heroku
• Model Context Protocol server packages
• Express HTTP transport
• Neon PostgreSQL
• Zod input validation

The synthetic data models the minimum backend systems needed for the workflow: customers, orders, payments, inventory, fulfillment, operational events, investigation history, and action audit records.

Run locally

Prerequisites

You need:

• Bun
• a PostgreSQL database; Neon works well for the hosted demo

1. Install dependencies

bun install

2. Configure environment variables

Create a .env file in the project root:

DATABASE_URL=postgresql://YOUR_DATABASE_URL
MCP_AUTH_TOKEN=YOUR_STRONG_RANDOM_TOKEN
PORT=3000

3. Create the synthetic database

bun scripts/setup-db.ts

This command drops and recreates the assignment tables. Do not run it against a database containing data you need to keep.

4. Seed demo data

bun scripts/seed-db.ts

All seeded customers, orders, payments, inventory, and fulfillment records are synthetic.

5. Build and start the MCP server

bun run build
bun run start

bun run build compiles TypeScript into dist/. The start command then runs the compiled server with Node, matching the Heroku runtime path.

The local MCP endpoint is:

http://localhost:3000/mcp

Deploy to Heroku

The repository includes a Procfile that starts the web dyno with npm start. Heroku builds the TypeScript project and runs the compiled Node.js server.

1. Create the Heroku app

heroku create YOUR_APP_NAME

2. Configure the database

Set the PostgreSQL connection string and a strong bearer token used to protect the MCP endpoint:

heroku config:set DATABASE_URL="YOUR_DATABASE_URL" MCP_AUTH_TOKEN="YOUR_STRONG_RANDOM_TOKEN" -a YOUR_APP_NAME

Heroku provides PORT automatically, so you do not need to configure it manually.

3. Deploy

git push heroku HEAD:main

During deployment Heroku installs the Node dependencies and runs the build script. The web dyno then starts:

node dist/index.js

The hosted MCP endpoint will be:

https://YOUR_APP_NAME.herokuapp.com/mcp

If your Heroku app uses a custom domain, use that domain with /mcp instead.

4. Verify the deployment

heroku logs --tail -a YOUR_APP_NAME

You should see the MCP server start and bind to Heroku's assigned port.

The synthetic database can be initialized before deployment from your local machine using the same DATABASE_URL, or by running the setup and seed scripts as one-off Heroku commands if Bun is available in that environment. For the simplest deployment path, initialize and seed Neon locally before deploying the server.

Connect from an AI client

Ops Lense uses a remote HTTP MCP endpoint. In an MCP client that supports remote/Streamable HTTP servers, add the endpoint and bearer token:

{
  "serverUrl": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_STRONG_RANDOM_TOKEN"
  }
}

For a deployed instance, replace the local URL with the hosted MCP URL and use the same token configured as MCP_AUTH_TOKEN on the server.

After connecting, the client should discover the tools and ops://action-policy resource automatically.

You can then start naturally, for example:

Show me recent orders that may need attention.

Why is this order stuck? Investigate it and tell me what we can safely do.

Show me all actions currently waiting for manual review.

For confirmation-required operations, the AI should present the preview to the operator and obtain explicit approval before making the second tool call with confirmed=true.

Connect with MCP Inspector

MCP Inspector is useful for testing the server independently of a chat client.

With the local server running:

npx @modelcontextprotocol/inspector

In Inspector, connect to:

http://localhost:3000/mcp

You can then inspect the discovered tools/resource and invoke the workflow manually.

Verification

Type-check the project with:

npm run typecheck

Run the focused Vitest integration suite against the configured synthetic database:

npm test

The tests in tests/operations.test.ts create isolated temporary records, exercise the real tool functions against PostgreSQL, and remove those records afterward. They verify:

• captured payment with a missing reservation produces INVENTORY_RESERVATION_MISSING;
• terminal orders are not diagnosed as active inventory failures;
• confirmed=false performs no mutation;
• confirmed=true performs the bounded inventory remediation and records an audit entry;
• repeating an already completed resync is a safe no-op;
• a refund request is queued for review without changing payment state;
• duplicate pending review requests are suppressed.

The suite currently contains 8 integration tests. A successful run reports 8 passed.

These tests are intentionally focused on the workflow and safety boundaries rather than broad coverage metrics.

Key product decisions

Keep the workflow narrow

The assignment does not attempt to build a complete commerce backend. Stuck-order operations were selected because they provide a compact workflow involving multiple systems, diagnosis, remediation, safety, and verification.

Give AI useful autonomy, not unrestricted write access

Making every operation read-only would leave the operator dependent on another system to resolve even simple incidents. Allowing every mutation would create unnecessary operational risk.

The three-tier model provides a middle ground: investigation is automatic, bounded remediation requires operator confirmation, and consequential actions remain behind manual review.

Keep critical actions out of MCP execution

Refunds and similar operations could technically be represented as database mutations in this synthetic project, but doing so would demonstrate the wrong production behavior. The MCP instead creates a review request and makes the boundary explicit.

Keep the MCP surface small

Each exposed tool has a clear role in the chosen workflow. The goal is for an AI client to select tools reliably, not to maximize the number of available tools.

Scope and assumptions

Included:

• synthetic commerce data
• order investigation
• deterministic diagnosis of the supported stuck-order condition
• guarded inventory remediation
• audit logging
• manual-review queue
• remotely accessible MCP interface

Intentionally excluded:

• frontend/admin dashboard
• real customer data
• production payment or warehouse credentials
• user accounts, sessions, OAuth, and role-based access control
• direct refund execution
• manual-review approval/execution UI
• complete commerce backend
• broad returns, fraud, catalog, and customer-support workflows

The hosted assignment server uses a single bearer token to avoid exposing the MCP publicly. For a production system, identity-aware authentication, authorization/RBAC, secret rotation, stronger concurrency controls, provider-specific integrations, observability, and a complete review workflow would need to be added.

Repository structure

src/
  index.ts
  db.ts
  resources.ts
  tools/
    diagnose-order.ts
    get-stats.ts
    get-timeline.ts
    list-manual-reviews.ts
    request-manual-review.ts
    resync-inventory.ts
    search-orders.ts
scripts/
  setup-db.ts
  seed-db.ts
tests/
  operations.test.ts
vitest.config.ts

AI worklog

This section should contain the actual AI usage from the assignment before submission:

• AI coding tools and exact models used
• why each model was chosen for its task
• how the work was planned and decomposed
• responsibilities handled by AI versus the developer
• important prompts/context supplied to AI
• at least one AI suggestion that was rejected or substantially changed
• how AI-generated work was reviewed and verified
• remaining risks or unfinished work

One product decision that changed during development was the treatment of consequential operations. Rather than exposing refunds and similar critical actions as executable MCP tools, they were moved behind a manual-review queue. This preserves useful AI autonomy while keeping financially or operationally consequential decisions outside direct model execution.

Submission

The final submission should include:

• hosted MCP URL
• source repository URL
• this README
• verification/tests for the important workflow behavior
• completed AI worklog
• 4–5 minute asynchronous demo

The demo should prioritize the actual product workflow over code walkthroughs: investigate an order, diagnose it, preview a safe remediation, confirm it, verify the result, then show how a critical action is routed to manual review.