mcpengine/servers/acuity-scheduling/README.md

# Acuity Scheduling MCP Server

A comprehensive Model Context Protocol (MCP) server for Acuity Scheduling API integration.

## Features

### 40+ Tools Across 10 Categories

- **Appointments** (8 tools): List, get, create, update, cancel, reschedule, list types, get type
- **Availability** (4 tools): Get dates, get times, get classes, check availability
- **Clients** (5 tools): List, get, create, update, delete
- **Calendars** (4 tools): List, get, create, update
- **Products** (6 tools): List products by type (add-ons, packages, subscriptions, gift certificates)
- **Forms** (3 tools): List forms, get fields, get intake form responses
- **Labels** (5 tools): List, create, delete, add to appointment, remove from appointment
- **Webhooks** (3 tools): List, create, delete
- **Coupons** (5 tools): List, get, create, update, delete
- **Blocks** (3 tools): List, create, delete time blocks

### 14 Interactive MCP Apps

1. **Appointment Dashboard** - Overview dashboard with stats and upcoming appointments
2. **Appointment Detail** - Detailed view of individual appointments
3. **Appointment Grid** - Filterable table view of all appointments
4. **Availability Calendar** - Interactive calendar showing available time slots
5. **Client Directory** - Searchable directory of all clients
6. **Client Detail** - Comprehensive client profiles with appointment history
7. **Calendar Manager** - Manage staff calendars and settings
8. **Product Catalog** - Browse products, packages, and add-ons
9. **Form Responses** - View and manage intake form submissions
10. **Label Manager** - Create and manage appointment labels
11. **Coupon Manager** - Create and track promotional coupons
12. **Booking Flow** - Interactive multi-step booking interface
13. **Schedule Overview** - Week-view schedule across all calendars
14. **Blocked Time Manager** - Manage blocked time slots and staff availability

## Installation

```bash
npm install
npm run build
```

## Configuration

Create a `.env` file with your Acuity Scheduling credentials:

```bash
# Required
ACUITY_USER_ID=your_user_id
ACUITY_API_KEY=your_api_key

# Optional (for OAuth2)
ACUITY_OAUTH2_TOKEN=your_oauth2_token
```

### Getting API Credentials

1. Log in to your Acuity Scheduling account
2. Go to Business Settings → Integrations → API
3. Enable API access and copy your User ID and API Key

## Usage

### As MCP Server

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

```json
{
  "mcpServers": {
    "acuity-scheduling": {
      "command": "node",
      "args": ["/path/to/acuity-scheduling/dist/main.js"],
      "env": {
        "ACUITY_USER_ID": "your_user_id",
        "ACUITY_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Standalone

```bash
npm start
```

## API Reference

### Authentication

The server supports two authentication methods:

1. **Basic Auth** (recommended): Uses User ID and API Key
2. **OAuth2**: Uses OAuth2 access token

### Tool Examples

#### List Appointments

```json
{
  "tool": "acuity_list_appointments",
  "arguments": {
    "minDate": "2024-01-01",
    "maxDate": "2024-01-31",
    "calendarID": 1
  }
}
```

#### Create Appointment

```json
{
  "tool": "acuity_create_appointment",
  "arguments": {
    "appointmentTypeID": 1,
    "datetime": "2024-01-15T10:00:00",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "555-1234"
  }
}
```

#### Get Availability

```json
{
  "tool": "acuity_get_availability_times",
  "arguments": {
    "appointmentTypeID": 1,
    "date": "2024-01-15"
  }
}
```

## MCP Apps

Access interactive apps through MCP resources:

- `acuity://apps/appointment-dashboard`
- `acuity://apps/availability-calendar`
- `acuity://apps/client-directory`
- And 11 more...

Each app provides a rich, interactive UI for managing different aspects of your Acuity Scheduling account.

## Architecture

```
src/
├── clients/
│   └── acuity.ts          # API client with auth & pagination
├── tools/
│   ├── appointments-tools.ts
│   ├── availability-tools.ts
│   ├── clients-tools.ts
│   ├── calendars-tools.ts
│   ├── products-tools.ts
│   ├── forms-tools.ts
│   ├── labels-tools.ts
│   ├── webhooks-tools.ts
│   ├── coupons-tools.ts
│   └── blocks-tools.ts
├── types/
│   └── index.ts           # TypeScript type definitions
├── ui/
│   └── react-app/         # 14 interactive MCP apps
├── server.ts              # MCP server implementation
└── main.ts                # Entry point
```

## Development

```bash
# Build
npm run build

# Watch mode
npm run dev

# Run server
npm start
```

## Error Handling

The server includes comprehensive error handling:

- API rate limit detection
- Network error retries
- Invalid credential detection
- Missing required parameters validation

## Rate Limits

Acuity Scheduling API has rate limits. The client handles:

- Automatic pagination for large result sets
- Error responses with status codes
- Request throttling (if needed)

## Support

For issues or questions:

- Acuity Scheduling API Documentation: https://developers.acuityscheduling.com/
- MCP Documentation: https://modelcontextprotocol.io/

## License

MIT

## Version

1.0.0