# blvd-mcp

MCP server for Boulevard salon/spa operations. Monitor shift utilization, manage calendar blocks, and control services through Claude or any MCP client.

## Features

- **Location Management** - List all locations, get staff members
- **Shift Utilization** - Analyze how busy shifts are, find capacity bottlenecks
- **Timeblock Management** - Create/delete calendar blocks (lunch, training, BTB)
- **Appointment Queries** - Get appointments by location and date range
- **Service Control** - List, activate, and deactivate services business-wide

## Quick Start

```bash
git clone https://github.com/austinntowns/blvd-mcp.git
cd blvd-mcp
npm install
cp .env.example .env
# Edit .env with your Boulevard credentials
npm run dev
```

Open http://localhost:3000/inspector to test.

## Configuration

### Environment Variables

```bash
BLVD_API_KEY=your_api_key        # Required
BLVD_API_SECRET=your_api_secret  # Required
BLVD_BUSINESS_ID=your_business_id # Required
```

### Getting Boulevard Credentials

1. Go to Boulevard Developer Portal (dashboard.boulevard.io)
2. Create an **Admin API** key (not Client API)
3. Get your **Business ID** from account settings

### Add to Claude Code

Add to `~/.mcp.json`:

```json
{
  "mcpServers": {
    "blvd": {
      "url": "http://localhost:3000/sse"
    }
  }
}
```

Or run as a command:

```json
{
  "mcpServers": {
    "blvd": {
      "command": "npx",
      "args": ["tsx", "/path/to/blvd-mcp/index.ts"],
      "env": {
        "BLVD_API_KEY": "your-key",
        "BLVD_API_SECRET": "your-secret",
        "BLVD_BUSINESS_ID": "your-business-id"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `list-locations` | Get all Boulevard locations |
| `get-staff` | Get staff members for a location |
| `get-shift-utilization` | Analyze shift utilization over date range |
| `get-busy-shifts` | Find high-utilization shifts (capacity bottlenecks) |
| `list-timeblocks` | List blocked time for a location |
| `create-timeblock` | Create a calendar block |
| `delete-timeblock` | Remove a calendar block |
| `get-appointments` | Get appointments by location/date |
| `list-services` | List all services |
| `get-service` | Get service details |
| `activate-service` | Activate service at all locations |
| `deactivate-service` | Deactivate service at all locations |

## Utilization Calculation

```
utilization = booked_minutes / available_minutes
```

Available minutes = shift duration minus lunch and DNB (Do Not Book) blocks.

## License

MIT