jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcpengine/servers/acuity-scheduling/README.md

14 KiB
Raw Blame History

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

npm install @mcpengine/acuity-scheduling-server

Configuration

Set the following environment variables:

ACUITY_USER_ID=your_user_id
ACUITY_API_KEY=your_api_key

Or use OAuth credentials:

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:

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

Programmatic Usage

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)

  1. acuity_check_availability - Check general availability

    • Returns available time slots across all calendars

  2. acuity_get_availability_dates - Get dates with available slots

    • Filter by appointment type and calendar

  3. acuity_get_availability_times - Get specific time slots for a date

    • Returns bookable times with timezone support

  4. acuity_get_availability_classes - Get available class times

    • For group appointments and recurring classes

  5. acuity_list_appointment_types - List all appointment types

    • Returns types with duration, price, and availability settings

Blocked Time (3 tools)

  1. acuity_list_blocks - List blocked time slots

    • View all calendar blocks with notes and recurrence

  2. acuity_create_block - Create a new blocked time slot

    • Block specific dates/times with optional notes

  3. acuity_delete_block - Remove a blocked time slot

    • Free up previously blocked calendar time

Calendars (4 tools)

  1. acuity_list_calendars - List all calendars

    • Returns calendar details, timezone, and availability

  2. acuity_get_calendar - Get specific calendar details

    • Detailed information for a single calendar

  3. acuity_create_calendar - Create a new calendar

    • Set up new scheduling calendar with settings

  4. acuity_update_calendar - Update calendar settings

    • Modify name, timezone, and availability rules

Clients (5 tools)

  1. acuity_list_clients - List all clients

    • Paginated client directory with search

  2. acuity_get_client - Get specific client details

    • Full client profile with appointment history

  3. acuity_create_client - Add a new client

    • Create client with contact and custom field data

  4. acuity_update_client - Update client information

    • Modify client details, notes, and custom fields

  5. acuity_delete_client - Remove a client

    • Permanently delete client record

Coupons (5 tools)

  1. acuity_list_coupons - List all coupons

    • View active and expired discount codes

  2. acuity_get_coupon - Get coupon details

    • Returns usage stats and restrictions

  3. acuity_create_coupon - Create a new coupon

    • Set discount amount, expiration, and limits

  4. acuity_update_coupon - Modify coupon settings

    • Update discount, dates, or usage limits

  5. acuity_delete_coupon - Remove a coupon

    • Deactivate discount code

Forms (3 tools)

  1. acuity_list_forms - List intake forms

    • Returns all form templates

  2. acuity_get_form_fields - Get form field definitions

    • Field types, labels, and validation rules

  3. acuity_get_intake_form_responses - Get completed form responses

    • Client-submitted form data for appointments

Labels (5 tools)

  1. acuity_list_labels - List all appointment labels

    • Categorization tags for appointments

  2. acuity_create_label - Create a new label

    • Define custom appointment categories

  3. acuity_delete_label - Remove a label

    • Delete unused label definitions

  4. acuity_add_label_to_appointment - Tag an appointment

    • Apply label to appointment for organization

  5. acuity_remove_label_from_appointment - Remove appointment tag

    • Untag an appointment

Products (5 tools)

  1. acuity_list_products - List all products

    • Returns products, packages, and subscriptions

  2. acuity_get_product - Get product details

    • Detailed product information and pricing

  3. acuity_list_packages - List service packages

    • Multi-session package offerings

  4. acuity_list_subscriptions - List subscription plans

    • Recurring service subscriptions

  5. acuity_list_gift_certificates - List gift certificates

    • Active and redeemed gift certificates

Addons (1 tool)

  1. acuity_list_addons - List appointment addons
    • Optional services that can be added to bookings

Webhooks (5 tools)

  1. acuity_list_webhooks - List all webhooks

    • View configured webhook endpoints

  2. acuity_create_webhook - Create a new webhook

    • Set up event notifications to external URLs

  3. acuity_delete_webhook - Remove a webhook

    • Stop sending event notifications

  4. 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

npm run build

Development Mode

npm run dev

Type Checking

npx tsc --noEmit

API Reference

Core Classes

AcuityClient

The main API client for interacting with Acuity Scheduling:

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:

{
  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:

{
  "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

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

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