The server starts on http://localhost:3000 (or the PORT you set).

Endpoints

Method	Path	Description
GET	/health	Health check, returns { "status": "All Good!" }
POST	/mcp	MCP endpoint (requires a Bearer <MCP_BEARER_TOKEN> header)

Database migrations

Migrations are generated/managed with Drizzle Kit:

bunx drizzle-kit generate
bunx drizzle-kit migrate

Project structure

src/
  index.ts                 # Hono app entry: mounts auth middleware + /mcp route
  db/
    schema.ts              # Drizzle table definitions
    client.ts              # Drizzle client (postgres-js driver)
  mcp/
    server.ts              # McpServer instance, registers all tools
    refund-eligibility.ts  # Pure refund rule-engine (no DB / MCP imports)
    tools/                 # Tool implementations
    schemas/               # Zod input schemas
  middleware/
    auth.ts                # Bearer token check, runs before the MCP handler
drizzle.config.ts          # Drizzle Kit configuration

Testing the MCP server

Use the MCP Inspector to connect to http://localhost:3000/mcp, passing your bearer token as a custom header. Try every tool with a valid input and one deliberately invalid input (e.g. a bad order id, a negative refund amount) to confirm clean tool errors rather than stack traces.

Data model

Table	Purpose
orders	Core order record with customer risk score
orderItems	Line items (order → SKU)
payments	Payment / gateway state
inventory	Stock per SKU per warehouse
fulfillmentEvents	Shipment / tracking timeline
actions	Audit trail + human-in-the-loop gate for writes

Safety & security

• Refund eligibility is enforced server-side as a pure, independently testable rule engine — not left to the model's judgment.
• Two-step propose/confirm split for refunds enforces confirmation at the protocol layer rather than trusting a prompt instruction.
• confirm_refund re-validates eligibility fresh, since state can move between the propose and confirm calls.
• Idempotent execution — repeated confirm_refund on an already-executed action returns the prior result instead of re-executing.
• Double-refund prevention — propose_refund checks for an existing eligible action before creating a new one.
• Bearer token auth over the MCP endpoint (service auth, not per-user auth).
• Zod validation on every tool input rejects malformed order ids, negative amounts, and unknown SKUs.