# @striderlabs/mcp-wingstop

An MCP (Model Context Protocol) server for Wingstop — find nearby locations, browse the wing menu with all 13 flavors, build your order, apply coupons, check out, and view Wing Club rewards using Playwright browser automation.

## Features

- **Find Locations** — Locate nearby Wingstop restaurants with address, hours, distance, and delivery availability
- **Browse Menu** — Full menu by category: wings, tenders, combos, sides, drinks, and dips — with flavors and prices
- **Order Management** — Create orders, add items with flavor selections, remove items
- **Coupons** — Apply promo codes for discounts
- **Checkout** — Review and submit orders for pickup or delivery
- **Wing Club Rewards** — Check points balance, tier status, and available reward offers

## Installation

```bash
npm install @striderlabs/mcp-wingstop
npx playwright install chromium
```

## Usage

### As an MCP server (Claude Desktop / Cursor / etc.)

Add to your MCP client config (e.g. `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "wingstop": {
      "command": "npx",
      "args": ["-y", "@striderlabs/mcp-wingstop"]
    }
  }
}
```

### Run directly

```bash
npx @striderlabs/mcp-wingstop
```

## Tools

### `find_locations`
Find nearby Wingstop locations.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `location` | string | Yes | Address, city, or ZIP code |

**Example:**
```json
{ "location": "Dallas, TX" }
```

---

### `get_menu`
Browse the Wingstop menu with prices and flavors.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category` | string | No | Filter by category: `wings`, `tenders`, `combos`, `sides`, `drinks`, `dips` |

**Example:**
```json
{ "category": "wings" }
```

---

### `create_order`
Start a new order at a selected Wingstop location.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `locationId` | string | Yes | Location ID from `find_locations` |
| `locationName` | string | Yes | Location name/address |
| `orderType` | string | No | `"pickup"` or `"delivery"` (default: `"pickup"`) |

**Example:**
```json
{
  "locationId": "ws_loc_001",
  "locationName": "Wingstop - 123 Main St",
  "orderType": "pickup"
}
```

---

### `add_item`
Add a menu item to the current order.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `menuItemId` | string | Yes | Item ID from `get_menu` |
| `name` | string | Yes | Display name |
| `price` | number | Yes | Price per item (USD) |
| `quantity` | number | No | Quantity (default: 1) |
| `flavor` | string | No | Wing flavor (e.g. `"Lemon Pepper"`, `"Mango Habanero"`) |
| `size` | string | No | Size (e.g. `"6-piece"`, `"10-piece"`) |
| `customizations` | object | No | Extra key-value customizations |

**Example:**
```json
{
  "menuItemId": "classic-wings-10",
  "name": "10-Piece Classic Wings",
  "price": 14.99,
  "quantity": 1,
  "flavor": "Lemon Pepper",
  "size": "10-piece"
}
```

---

### `remove_item`
Remove an item from the current order.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `itemId` | string | Yes | Order item ID (shown in `add_item` response) |

---

### `apply_coupon`
Apply a promo code to the current order.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `code` | string | Yes | Coupon or promo code |

**Example:**
```json
{ "code": "WINGFAN10" }
```

---

### `checkout`
Submit the order for pickup or delivery.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `customerName` | string | Yes | Customer name |
| `phone` | string | No | Phone number |
| `pickupTime` | string | No | Pickup time (default: `"ASAP"`) |
| `deliveryAddress` | string | No | Delivery address (required for delivery) |
| `notes` | string | No | Special instructions |

**Example:**
```json
{
  "customerName": "Alex Smith",
  "phone": "555-123-4567",
  "pickupTime": "6:30 PM"
}
```

> **Note:** Full order placement requires authentication with Wingstop. The server generates an order ID and summary — complete payment at wingstop.com or in the Wingstop app.

---

### `get_rewards`
Check Wing Club rewards balance and offers.

**Input:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `includeOffers` | boolean | No | Include reward offers (default: `true`) |

---

## Supported Flavors

Wingstop's 13 signature flavors:

| Flavor | Heat Level |
|--------|-----------|
| Lemon Pepper | None |
| Garlic Parmesan | None |
| Hickory Smoked BBQ | None |
| Hawaiian | Mild |
| Mild | Mild |
| Butter Garlic | None |
| Cajun | Medium |
| Louisiana Rub | Medium |
| Cajun Garlic | Medium |
| Original Hot | Hot |
| Spicy Korean Q | Hot |
| Mango Habanero | Extra Hot |
| Atomic | Extra Hot |

## Session Persistence

The server saves browser cookies to `~/.wingstop-mcp-cookies.json` for persistent sessions across restarts. If you're logged in to Wingstop in the automated browser, your session will be preserved.

## How It Works

The server uses [Playwright](https://playwright.dev/) to automate a headless Chromium browser with stealth settings, navigating wingstop.com to fetch live location data, menu items, and rewards information. A comprehensive static fallback dataset is used when live scraping is unavailable.

Order state is maintained in-memory for the duration of the MCP session.

## Development

```bash
git clone https://github.com/markswendsen-code/mcp-wingstop
cd mcp-wingstop
npm install
npx playwright install chromium
npm run dev      # watch mode
npm run build    # production build
```

## License

MIT