# @striderlabs/mcp-drizly

A Model Context Protocol (MCP) connector for Drizly alcohol delivery. Enables AI assistants to search products, manage carts, check availability, and place orders on Drizly (drizly.com).

## Features

- **Product Search** - Search beer, wine, spirits by name, type, or brand with price and ABV filters
- **Product Details** - Get detailed info including ABV, origin, ratings, and descriptions
- **Category Browsing** - Browse by category (wine type, spirit type, etc.)
- **Availability Check** - Check if products are available for delivery to an address
- **Store Discovery** - Find available stores/retailers for a delivery address
- **Cart Management** - Add items, view cart, and update quantities
- **Order Placement** - Complete checkout and place orders
- **Order History** - View past and current orders
- **Order Tracking** - Track real-time order status and delivery estimates
- **Recommendations** - Get personalized product recommendations

## Requirements

- Node.js >= 18.0.0
- Playwright (for browser automation)

## Installation

```bash
npm install @striderlabs/mcp-drizly
```

Install Playwright browsers:

```bash
npx playwright install chromium
```

## Configuration

Add to your MCP client configuration (e.g., Claude Desktop `claude_desktop_config.json`):

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

Or if installed globally:

```json
{
  "mcpServers": {
    "drizly": {
      "command": "mcp-drizly"
    }
  }
}
```

## Available Tools

### `search_products`
Search for alcohol products by name, brand, or type.

**Parameters:**
- `query` (required) - Search query string
- `category` - Filter by category: `beer`, `wine`, `spirits`, `cider`, `hard-seltzer`
- `minPrice` / `maxPrice` - Price range filter
- `minAbv` / `maxAbv` - ABV percentage filter
- `address` - Delivery address for availability filtering

**Example:**
```json
{
  "query": "IPA beer",
  "category": "beer",
  "maxPrice": 20
}
```

### `get_product_details`
Get detailed product information.

**Parameters:**
- `productId` (required) - Product ID or URL slug from Drizly

**Example:**
```json
{
  "productId": "dogfish-head-60-minute-ipa"
}
```

### `browse_categories`
Browse products by category and subcategory.

**Parameters:**
- `category` - Main category: `beer`, `wine`, `spirits`, `cider`, `hard-seltzer`, `cocktails-mixers`
- `subcategory` - Subcategory (e.g., `IPA`, `Chardonnay`, `Bourbon`)

**Example:**
```json
{
  "category": "wine",
  "subcategory": "Chardonnay"
}
```

### `check_availability`
Check if a product is available for delivery.

**Parameters:**
- `productId` (required) - Product to check
- `address` (required) - Delivery address

**Example:**
```json
{
  "productId": "corona-extra-beer",
  "address": "123 Main St, Boston, MA 02101"
}
```

### `add_to_cart`
Add a product to the shopping cart.

**Parameters:**
- `productId` (required) - Product ID
- `name` (required) - Product name
- `quantity` (required) - Quantity (minimum 1)
- `price` (required) - Price per unit
- `imageUrl` - Optional product image URL

**Example:**
```json
{
  "productId": "corona-extra-12pk",
  "name": "Corona Extra 12-Pack",
  "quantity": 2,
  "price": 15.99
}
```

### `get_cart`
View current cart contents and totals.

**Returns:** Cart items, subtotal, delivery fee, and total.

### `update_cart`
Update item quantity or remove from cart.

**Parameters:**
- `productId` (required) - Product to update
- `quantity` (required) - New quantity (0 removes item)

**Example:**
```json
{
  "productId": "corona-extra-12pk",
  "quantity": 3
}
```

### `get_stores`
Find stores available for delivery to an address.

**Parameters:**
- `address` (required) - Delivery address

**Example:**
```json
{
  "address": "456 Park Ave, New York, NY 10022"
}
```

### `place_order`
Place an order for cart items.

**Parameters:**
- `deliveryAddress` (required) - Full delivery address
- `cardLastFour` - Last 4 digits of payment card
- `savePayment` - Whether to save payment method

**Example:**
```json
{
  "deliveryAddress": "123 Main St, Apt 4B, Boston, MA 02101",
  "cardLastFour": "4242"
}
```

### `get_orders`
View all past and current orders.

### `track_order`
Track an order's current status.

**Parameters:**
- `orderId` (required) - Order ID (format: `DRZ-XXXXXXXXXX`)

**Example:**
```json
{
  "orderId": "DRZ-1234567890"
}
```

### `get_recommendations`
Get personalized product recommendations.

**Parameters:**
- `categories` - Preferred categories array
- `minPrice` / `maxPrice` - Price range for recommendations
- `previousOrders` - Previous order IDs for personalization

**Example:**
```json
{
  "categories": ["wine"],
  "maxPrice": 30
}
```

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev
```

## Architecture

The connector uses two main components:

- **`src/index.ts`** - MCP server that defines tools and handles requests
- **`src/browser.ts`** - Browser automation layer using Playwright to interact with Drizly's website

The browser automation handles:
- Age verification gates
- Product search and navigation
- Cart management (stored in memory)
- Order simulation

## Important Notes

- **Age Verification**: Drizly requires users to be 21+. Ensure compliance with local laws.
- **Cart State**: Cart data is stored in memory and will reset when the server restarts.
- **Availability**: Product availability depends on your delivery location and connected retailers.
- **Playwright**: Browser automation requires Playwright with Chromium installed.

## License

MIT