OpsPilot MCP Server

An AI Operations Investigation MCP server that enables LLMs (Claude, ChatGPT, etc.) to investigate order fulfillment incidents by correlating data across independent services.

Architecture

graph TD
    User -->|prompt| LLM
    LLM -->|tool call| Tools[MCP Tools]
    Tools -->|query| Repos[Repositories]
    Repos -->|read| Scenarios[Investigation Scenarios]
    Scenarios -->|typed| Types[Domain Types]

Key principle: Scenarios are the single source of truth. Every new incident is a new scenario file. Repositories and tools automatically support new scenarios without modification.

Folder Structure

src/
├── index.ts                     # Express entry point
├── server/
│   ├── server.ts                # MCP server setup & tool registration
│   └── transport.ts             # HTTP transport layer
├── tools/
│   ├── ping.ts                  # Health check
│   ├── getOrder.ts              # Order lookup by orderId
│   ├── getPayment.ts            # Payment lookup by paymentId
│   ├── getShipment.ts           # Shipment lookup by orderId
│   ├── getInventoryReservation.ts  # Inventory lookup by orderId
│   ├── getSystemEvents.ts       # Event log by orderId
│   └── investigateOrder.ts      # Full orchestration of all domains
├── repositories/
│   ├── orderRepository.ts
│   ├── paymentRepository.ts
│   ├── shipmentRepository.ts
│   ├── inventoryRepository.ts
│   ├── eventRepository.ts
│   └── incidentRepository.ts
├── scenarios/
│   ├── index.ts                 # Registry of all scenarios
│   ├── warehouse-timeout.ts
│   ├── payment-failed.ts
│   ├── inventory-out-of-stock.ts
│   ├── courier-outage.ts
│   └── fraud-review.ts
├── types/
│   ├── order.ts
│   ├── payment.ts
│   ├── shipment.ts
│   ├── inventory.ts
│   ├── event.ts
│   └── scenario.ts
└── __tests__/
    ├── repositories.test.ts
    └── tools.test.ts

Install

npm install

Run

# Development
npm run dev

# Build & production
npm run build
npm start

Server starts on http://localhost:3000.

Connect via MCP Inspector

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

Test

npm test

Example Prompts

Once connected, you can ask the LLM:

• "What happened to order ORD-1001?"
• "Why did order ORD-1003 fail?"
• "Investigate ORD-1004 and tell me the root cause"
• "Check order ORD-1005 — is there a fraud issue?"

Example Investigations

ORD-1001 — Warehouse Timeout

• Payment captured, inventory reserved
• Shipment not created (null)
• Warehouse service timed out → retryable

ORD-1002 — Payment Failed

• Payment authorization rejected by gateway
• Inventory never reserved
• Customer needs to retry with a different card

ORD-1003 — Inventory Out of Stock

• Payment captured
• SKU unavailable in warehouse → shipment not created
• Requires restock — not retryable

ORD-1004 — Courier API Outage

• Payment captured, inventory reserved, shipment created
• Courier API repeatedly timing out → shipment stuck
• Requires logistics provider to resolve the outage

ORD-1005 — Fraud Review Pending

• Payment authorized but not captured
• Inventory reserved
• Fraud service flagged for manual review — awaiting approval

Supported Scenarios

Scenario	Root Cause Code	Severity	Retryable
Warehouse Timeout	WAREHOUSE_TIMEOUT	HIGH	Yes
Payment Failed	PAYMENT_FAILED	HIGH	Yes
Inventory Out of Stock	INVENTORY_OUT_OF_STOCK	HIGH	No
Courier Outage	COURIER_OUTAGE	CRITICAL	Yes
Fraud Review	FRAUD_REVIEW	MEDIUM	No

Future Improvements

• Additional scenario patterns (e.g., address validation failures, carrier damage claims)
• Scenario probability scoring based on event patterns
• Paginated event retrieval for high-volume orders
• Webhook-based scenario injection from external monitoring systems

Documentation

See docs/architecture.md for detailed architecture explanation and docs/investigation-flow.md for investigation workflow.