# Deliverect Commerce MCP Server

MCP server exposing the Deliverect Commerce API for voice/AI assistant integration (Siri, Google Gemini, in-app voice control). Features seamless cross-service integration with Spoonity for applying loyalty rewards during checkout.

## Quick Start

```bash
npm install
npm run build

DELIVERECT_CHANNEL_LINK_ID=<channel_link_id> \
DELIVERECT_ACCOUNT_ID=<account_id> \
SPOONITY_API_URL=https://api.spoonity.com \
node dist/index.js
```

## Configuration

| Env Var | Required | Default | Description |
|---------|----------|---------|-------------|
| `DELIVERECT_CHANNEL_LINK_ID` | ✅ | — | Channel link ID for the ordering channel |
| `DELIVERECT_ACCOUNT_ID` | ❌ | — | Account ID for payment gateway lookups |
| `DELIVERECT_API_URL` | ❌ | `https://commerce-api.deliverect.com` | Commerce API base URL |
| `DELIVERECT_META_URL` | ❌ | `https://api.deliverect.com` | Meta API base URL |
| `SPOONITY_API_URL` | ❌ | `https://api.spoonity.com` | Spoonity API for rewards integration |

## Tools (19)

### Stores
| Tool | Description |
|------|-------------|
| `list_stores` | All ordering locations |
| `get_store` | Single store details |
| `check_store_open` | Open/closed status check |

### Menu
| Tool | Description |
|------|-------------|
| `get_menus` | Full menu: categories, products, modifiers |

### Basket
| Tool | Description |
|------|-------------|
| `create_basket` | Start a new order |
| `add_to_basket` | Update items |
| `get_basket` | Current cart state |
| `validate_basket` | Pre-checkout validation |
| `set_tip` | Apply tip (flat/percentage) |
| `apply_discount` | Promo code |
| `set_fulfillment` | Pickup/delivery settings |
| `set_customer` | Customer details |

### Delivery
| Tool | Description |
|------|-------------|
| `check_delivery` | Delivery availability + fee |

### Checkout
| Tool | Description |
|------|-------------|
| `checkout` | Submit order |
| `get_order_status` | Track order |
| `get_upsell` | Recommended add-ons |

### Rewards Integration (Spoonity)
| Tool | Description |
|------|-------------|
| `get_rewards_for_checkout` | Available rewards + wallet balance |
| `apply_rewards` | Apply rewards/Quick Pay to basket |
| `complete_redemption` | Finalize redemption after checkout |

## Prompts

| Prompt | Description |
|--------|-------------|
| `quick_order` | Quickly order a specific item |
| `browse_menu` | Explore menu and build an order |
| `reorder_last` | Recreate a previous order |
| `order_with_rewards` | Order + apply Spoonity rewards |

## Order Flow

```
1. list_stores → Find a store
2. check_store_open → Verify availability
3. get_menus → Browse the menu
4. create_basket → Start order with items
5. set_tip → Add tip (optional)
6. get_rewards_for_checkout → Check rewards (optional)
7. apply_rewards → Apply discounts (optional)
8. set_customer → Customer info
9. validate_basket → Pre-flight check
10. checkout → Submit order
11. get_order_status → Track order
12. complete_redemption → Finalize rewards (if applied)
```

## Claude Desktop Config

```json
{
  "mcpServers": {
    "deliverect": {
      "command": "node",
      "args": ["/path/to/deliverect-mcp-server/dist/index.js"],
      "env": {
        "DELIVERECT_CHANNEL_LINK_ID": "<channel_link_id>",
        "DELIVERECT_ACCOUNT_ID": "<account_id>",
        "SPOONITY_API_URL": "https://api.spoonity.com"
      }
    }
  }
}
```

## Cross-Service Architecture

This server works alongside the **Spoonity Consumer MCP Server**:

```
Voice Assistant → "Order a coffee and use my rewards"
  ├── Spoonity MCP: get_balance, get_rewards
  ├── Deliverect MCP: list_stores → get_menus → create_basket
  ├── Deliverect MCP: get_rewards_for_checkout (uses Spoonity session)
  ├── Deliverect MCP: apply_rewards → checkout
  └── Deliverect MCP: complete_redemption
```

---

*Spoonity Product Team — March 2026*