Calven Coffee MCP

Calven Coffee MCP provides two interfaces on top of the Calven catering endpoints:

• An MCP server for AI tools
• A local CLI for direct use

The project uses the same authenticated portal session that the Calven client uses for ordering.

Features

• Authenticate through a browser-assisted helper instead of manually copying tokens
• List suppliers and menus
• Preview an order payload without placing it
• Place and cancel orders
• Use the same validation rules in the CLI and MCP server

Install

npm install

Authenticate

Create or refresh the local session file:

npm run auth

This opens a Playwright-controlled browser, waits for portal sign-in and MFA, then writes .calven-session.json locally.

Headless mode is also available, but interactive MFA is usually more reliable in a visible browser:

npm run auth:headless

Manual fallback is still supported if needed. Use calven-session.example.json as the shape reference for the local session file.

CLI

Show help:

npm run cli -- --help

Common commands:

npm run cli -- session --json
npm run cli -- suppliers
npm run cli -- menu --supplier-name "Supplier Name"
npm run cli -- orders

Preview an order without placing it:

npm run cli -- preview \
  --supplier-name "Supplier Name" \
  --item-name "Coffee Item" \
  --option "SIZE=Regular"

Place an order:

npm run cli -- order \
  --supplier-name "Supplier Name" \
  --item-name "Coffee Item" \
  --option "SIZE=Regular"

Use a JSON file for more complex orders:

npm run cli -- order --input order.json

Example order.json:

{
  "supplierName": "Supplier Name",
  "minutesFromNow": 20,
  "items": [
    {
      "itemName": "Coffee Item",
      "options": {
        "SIZE": "Regular"
      }
    }
  ]
}

Cancel an order:

npm run cli -- cancel --supplier-name "Supplier Name" --order-id YOUR_ORDER_ID

If the saved session is missing or stale, rerun npm run auth.

MCP Server

Run the MCP server over stdio:

npm run dev

Build and run the compiled version:

npm run build
npm start

Example MCP config:

{
  "mcpServers": {
    "calven-coffee": {
      "command": "node",
      "args": ["/path/to/coffee-mcp/dist/index.js"]
    }
  }
}

Available tools:

• session_status
• list_suppliers
• get_menu
• list_my_orders
• prepare_order
• place_order
• cancel_order

Security

• Do not commit .calven-session.json
• Do not commit .playwright-calven/
• Do not commit local screenshots, dumps, or reverse-engineering artifacts
• Do not store passwords in the repo

See CONTRIBUTING.md for developer workflow and repository hygiene rules.