mcpengine/servers/acuity-scheduling/README.md

# Acuity Scheduling MCP Server

A Model Context Protocol (MCP) server implementation for Acuity Scheduling API integration. This server provides comprehensive access to appointment scheduling, calendar management, client data, and more through the MCP protocol.

## Features

- **46 MCP Tools** for complete Acuity Scheduling API coverage
- **14 Interactive React Apps** for visual interfaces
- Full TypeScript implementation with type safety
- Zod schema validation for all inputs
- Comprehensive error handling
- OAuth and API key authentication support

## Installation

```bash
npm install @mcpengine/acuity-scheduling-server
```

## Configuration

Set the following environment variables:

```bash
ACUITY_USER_ID=your_user_id
ACUITY_API_KEY=your_api_key
```

Or use OAuth credentials:

```bash
ACUITY_CLIENT_ID=your_client_id
ACUITY_CLIENT_SECRET=your_client_secret
ACUITY_ACCESS_TOKEN=your_access_token
```

## Usage

### As MCP Server

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "acuity-scheduling": {
      "command": "acuity-scheduling-mcp",
      "env": {
        "ACUITY_USER_ID": "your_user_id",
        "ACUITY_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Programmatic Usage

```typescript
import { AcuitySchedulingServer } from '@mcpengine/acuity-scheduling-server';

const server = new AcuitySchedulingServer({
  userId: 'your_user_id',
  apiKey: 'your_api_key'
});

await server.start();
```

## Available Tools

The server provides 46 MCP tools organized into the following categories:

### Appointments (6 tools)

1. **acuity_list_appointments** - List appointments with optional filters
   - Supports date ranges, calendar filtering, and canceled appointments
   
2. **acuity_get_appointment** - Get detailed information for a specific appointment
   - Returns full appointment data including client details
   
3. **acuity_create_appointment** - Create a new appointment
   - Validates appointment type, datetime, and client information
   
4. **acuity_update_appointment** - Update an existing appointment
   - Modify appointment details, notes, or status
   
5. **acuity_cancel_appointment** - Cancel an appointment
   - Optional cancellation reason and email notification
   
6. **acuity_reschedule_appointment** - Reschedule an appointment to a new time
   - Updates datetime while preserving other appointment details

### Availability (5 tools)

7. **acuity_check_availability** - Check general availability
   - Returns available time slots across all calendars
   
8. **acuity_get_availability_dates** - Get dates with available slots
   - Filter by appointment type and calendar
   
9. **acuity_get_availability_times** - Get specific time slots for a date
   - Returns bookable times with timezone support
   
10. **acuity_get_availability_classes** - Get available class times
    - For group appointments and recurring classes
    
11. **acuity_list_appointment_types** - List all appointment types
    - Returns types with duration, price, and availability settings

### Blocked Time (3 tools)

12. **acuity_list_blocks** - List blocked time slots
    - View all calendar blocks with notes and recurrence
    
13. **acuity_create_block** - Create a new blocked time slot
    - Block specific dates/times with optional notes
    
14. **acuity_delete_block** - Remove a blocked time slot
    - Free up previously blocked calendar time

### Calendars (4 tools)

15. **acuity_list_calendars** - List all calendars
    - Returns calendar details, timezone, and availability
    
16. **acuity_get_calendar** - Get specific calendar details
    - Detailed information for a single calendar
    
17. **acuity_create_calendar** - Create a new calendar
    - Set up new scheduling calendar with settings
    
18. **acuity_update_calendar** - Update calendar settings
    - Modify name, timezone, and availability rules

### Clients (5 tools)

19. **acuity_list_clients** - List all clients
    - Paginated client directory with search
    
20. **acuity_get_client** - Get specific client details
    - Full client profile with appointment history
    
21. **acuity_create_client** - Add a new client
    - Create client with contact and custom field data
    
22. **acuity_update_client** - Update client information
    - Modify client details, notes, and custom fields
    
23. **acuity_delete_client** - Remove a client
    - Permanently delete client record

### Coupons (5 tools)

24. **acuity_list_coupons** - List all coupons
    - View active and expired discount codes
    
25. **acuity_get_coupon** - Get coupon details
    - Returns usage stats and restrictions
    
26. **acuity_create_coupon** - Create a new coupon
    - Set discount amount, expiration, and limits
    
27. **acuity_update_coupon** - Modify coupon settings
    - Update discount, dates, or usage limits
    
28. **acuity_delete_coupon** - Remove a coupon
    - Deactivate discount code

### Forms (3 tools)

29. **acuity_list_forms** - List intake forms
    - Returns all form templates
    
30. **acuity_get_form_fields** - Get form field definitions
    - Field types, labels, and validation rules
    
31. **acuity_get_intake_form_responses** - Get completed form responses
    - Client-submitted form data for appointments

### Labels (5 tools)

32. **acuity_list_labels** - List all appointment labels
    - Categorization tags for appointments
    
33. **acuity_create_label** - Create a new label
    - Define custom appointment categories
    
34. **acuity_delete_label** - Remove a label
    - Delete unused label definitions
    
35. **acuity_add_label_to_appointment** - Tag an appointment
    - Apply label to appointment for organization
    
36. **acuity_remove_label_from_appointment** - Remove appointment tag
    - Untag an appointment

### Products (5 tools)

37. **acuity_list_products** - List all products
    - Returns products, packages, and subscriptions
    
38. **acuity_get_product** - Get product details
    - Detailed product information and pricing
    
39. **acuity_list_packages** - List service packages
    - Multi-session package offerings
    
40. **acuity_list_subscriptions** - List subscription plans
    - Recurring service subscriptions
    
41. **acuity_list_gift_certificates** - List gift certificates
    - Active and redeemed gift certificates

### Addons (1 tool)

42. **acuity_list_addons** - List appointment addons
    - Optional services that can be added to bookings

### Webhooks (5 tools)

43. **acuity_list_webhooks** - List all webhooks
    - View configured webhook endpoints
    
44. **acuity_create_webhook** - Create a new webhook
    - Set up event notifications to external URLs
    
45. **acuity_delete_webhook** - Remove a webhook
    - Stop sending event notifications
    
46. **acuity_get_appointment_type** - Get appointment type details
    - Detailed configuration for a specific type

## React Apps

The server includes 14 interactive React applications for visual interfaces:

### 1. Appointment Dashboard
**Path:** `src/ui/react-app/appointment-dashboard/`

A comprehensive dashboard displaying upcoming appointments, statistics, and quick actions. Features:
- Today's appointments list
- Weekly appointment count
- Revenue tracking
- Quick filters by status and calendar
- Real-time updates

### 2. Appointment Detail
**Path:** `src/ui/react-app/appointment-detail/`

Detailed appointment view and management interface. Features:
- Full appointment information display
- Client contact details
- Form responses viewer
- Reschedule interface
- Cancel with reason
- Add/edit appointment notes
- Label management

### 3. Appointment Grid
**Path:** `src/ui/react-app/appointment-grid/`

Calendar-style grid view of all appointments. Features:
- Week/month view toggle
- Color-coded by appointment type
- Drag-to-reschedule
- Filter by calendar, status, and client
- Export to CSV
- Print-friendly layout

### 4. Availability Calendar
**Path:** `src/ui/react-app/availability-calendar/`

Visual availability checker and calendar manager. Features:
- Month calendar with availability indicators
- Time slot picker for specific dates
- Appointment type selector
- Multiple calendar view
- Real-time availability updates
- Timezone support

### 5. Blocked Time Manager
**Path:** `src/ui/react-app/blocked-time-manager/`

Interface for managing calendar blocks and unavailable times. Features:
- List all blocked time slots
- Create new blocks with date/time range
- Add notes to blocks
- Delete existing blocks
- Recurring block support

### 6. Booking Flow
**Path:** `src/ui/react-app/booking-flow/`

Customer-facing booking interface. Features:
- 3-step booking process
- Service selection with descriptions
- Available time slot display
- Client information form
- Confirmation screen
- Email notifications

### 7. Calendar Manager
**Path:** `src/ui/react-app/calendar-manager/`

Calendar configuration and management. Features:
- List all calendars
- View calendar details and settings
- Toggle calendar active/inactive
- Edit calendar name and timezone
- Availability rules display

### 8. Client Detail
**Path:** `src/ui/react-app/client-detail/`

Comprehensive client profile viewer. Features:
- Full contact information
- Appointment history
- Custom field data
- Notes and tags
- Edit client details
- Appointment statistics

### 9. Client Directory
**Path:** `src/ui/react-app/client-directory/`

Searchable client list and management. Features:
- Paginated client list
- Search by name, email, or phone
- Quick actions (view, edit, delete)
- Appointment count per client
- Export client list
- Bulk operations

### 10. Coupon Manager
**Path:** `src/ui/react-app/coupon-manager/`

Discount code management interface. Features:
- List active and expired coupons
- Create new discount codes
- Edit coupon details
- Usage statistics
- Expiration management
- Delete unused coupons

### 11. Form Responses
**Path:** `src/ui/react-app/form-responses/`

Intake form response viewer. Features:
- List all form submissions
- Filter by appointment or client
- View individual responses
- Export responses to CSV
- Form field mapping

### 12. Label Manager
**Path:** `src/ui/react-app/label-manager/`

Appointment label organization. Features:
- Create custom labels
- Edit label names and colors
- Delete unused labels
- View label usage statistics
- Apply labels to appointments

### 13. Product Catalog
**Path:** `src/ui/react-app/product-catalog/`

Product and package display. Features:
- List all products and packages
- View pricing and descriptions
- Package session details
- Subscription plan information
- Gift certificate management

### 14. Schedule Overview
**Path:** `src/ui/react-app/schedule-overview/`

High-level schedule summary and analytics. Features:
- Next 7 days overview
- Daily appointment breakdown
- Calendar utilization stats
- Grouped by date display
- Quick navigation

## Development

### Build

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Type Checking

```bash
npx tsc --noEmit
```

## API Reference

### Core Classes

#### AcuityClient

The main API client for interacting with Acuity Scheduling:

```typescript
class AcuityClient {
  constructor(config: {
    userId: string;
    apiKey: string;
  });

  // Appointments
  listAppointments(params?: AppointmentListParams): Promise<Appointment[]>;
  getAppointment(id: number): Promise<Appointment>;
  createAppointment(data: CreateAppointmentData): Promise<Appointment>;
  updateAppointment(id: number, data: UpdateAppointmentData): Promise<Appointment>;
  cancelAppointment(id: number, reason?: string): Promise<void>;

  // Calendars
  listCalendars(): Promise<Calendar[]>;
  getCalendar(id: number): Promise<Calendar>;
  createCalendar(data: CreateCalendarData): Promise<Calendar>;
  updateCalendar(id: number, data: UpdateCalendarData): Promise<Calendar>;

  // Clients
  listClients(params?: ClientListParams): Promise<Client[]>;
  getClient(id: number): Promise<Client>;
  createClient(data: CreateClientData): Promise<Client>;
  updateClient(id: number, data: UpdateClientData): Promise<Client>;
  deleteClient(id: number): Promise<void>;

  // ... and more
}
```

### Tool Handler Pattern

All tools follow a consistent pattern:

```typescript
{
  description: string;
  inputSchema: ZodSchema;
  handler: async (args: any) => {
    // Process request
    const result = await client.methodCall(args);
    
    // Return MCP-formatted response
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };
  }
}
```

## Error Handling

The server provides comprehensive error handling:

- **Authentication Errors** - Invalid credentials or expired tokens
- **Validation Errors** - Invalid input parameters
- **Rate Limiting** - API quota exceeded
- **Network Errors** - Connection failures
- **Business Logic Errors** - Booking conflicts, invalid operations

All errors are returned in a consistent format:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}
```

## Rate Limiting

Acuity Scheduling API has rate limits:

- **300 requests per minute** for most endpoints
- **60 requests per minute** for appointment creation

The server automatically handles rate limiting with exponential backoff.

## Testing

```bash
npm test
```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

## License

MIT License - see LICENSE file for details

## Support

- **Documentation:** https://developers.acuityscheduling.com/
- **Issues:** https://github.com/mcpengine/servers/issues
- **Email:** support@mcpengine.dev

## Changelog

### 1.0.0 (2024-02-12)

- Initial release
- 46 MCP tools covering full Acuity Scheduling API
- 14 interactive React applications
- Full TypeScript support
- Comprehensive documentation
- Production-ready error handling