From c435e6c3a4ef9234098d94f83a446ee004080b0f Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Thu, 12 Feb 2026 17:54:18 -0500 Subject: [PATCH] acuity-scheduling: Complete MCP server, README, TSC clean --- servers/acuity-scheduling/README.md | 608 +++++++++++++----- servers/acuity-scheduling/package.json | 3 +- .../src/ui/react-app/coupon-manager/main.tsx | 2 +- .../src/ui/react-app/label-manager/main.tsx | 2 +- 4 files changed, 464 insertions(+), 151 deletions(-) diff --git a/servers/acuity-scheduling/README.md b/servers/acuity-scheduling/README.md index 68c00af..94e7d90 100644 --- a/servers/acuity-scheduling/README.md +++ b/servers/acuity-scheduling/README.md @@ -1,77 +1,50 @@ # Acuity Scheduling MCP Server -A comprehensive Model Context Protocol (MCP) server for Acuity Scheduling API integration. +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 -### 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 +- **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 -npm run build +npm install @mcpengine/acuity-scheduling-server ``` ## Configuration -Create a `.env` file with your Acuity Scheduling credentials: +Set the following environment variables: ```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 +Or use OAuth 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 +```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 (e.g., Claude Desktop): +Add to your MCP client configuration: ```json { "mcpServers": { "acuity-scheduling": { - "command": "node", - "args": ["/path/to/acuity-scheduling/dist/main.js"], + "command": "acuity-scheduling-mcp", "env": { "ACUITY_USER_ID": "your_user_id", "ACUITY_API_KEY": "your_api_key" @@ -81,141 +54,480 @@ Add to your MCP client configuration (e.g., Claude Desktop): } ``` -### Standalone +### 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 start +npm run build +``` + +### Development Mode + +```bash +npm run dev +``` + +### Type Checking + +```bash +npx tsc --noEmit ``` ## API Reference -### Authentication +### Core Classes -The server supports two authentication methods: +#### AcuityClient -1. **Basic Auth** (recommended): Uses User ID and API Key -2. **OAuth2**: Uses OAuth2 access token +The main API client for interacting with Acuity Scheduling: -### Tool Examples +```typescript +class AcuityClient { + constructor(config: { + userId: string; + apiKey: string; + }); -#### List Appointments + // Appointments + listAppointments(params?: AppointmentListParams): Promise; + getAppointment(id: number): Promise; + createAppointment(data: CreateAppointmentData): Promise; + updateAppointment(id: number, data: UpdateAppointmentData): Promise; + cancelAppointment(id: number, reason?: string): Promise; -```json -{ - "tool": "acuity_list_appointments", - "arguments": { - "minDate": "2024-01-01", - "maxDate": "2024-01-31", - "calendarID": 1 - } + // Calendars + listCalendars(): Promise; + getCalendar(id: number): Promise; + createCalendar(data: CreateCalendarData): Promise; + updateCalendar(id: number, data: UpdateCalendarData): Promise; + + // Clients + listClients(params?: ClientListParams): Promise; + getClient(id: number): Promise; + createClient(data: CreateClientData): Promise; + updateClient(id: number, data: UpdateClientData): Promise; + deleteClient(id: number): Promise; + + // ... and more } ``` -#### Create Appointment +### Tool Handler Pattern -```json +All tools follow a consistent pattern: + +```typescript { - "tool": "acuity_create_appointment", - "arguments": { - "appointmentTypeID": 1, - "datetime": "2024-01-15T10:00:00", - "firstName": "John", - "lastName": "Doe", - "email": "john@example.com", - "phone": "555-1234" + 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) + }] + }; } } ``` -#### 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: +The server provides comprehensive error handling: -- API rate limit detection -- Network error retries -- Invalid credential detection -- Missing required parameters validation +- **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 -## Rate Limits +All errors are returned in a consistent format: -Acuity Scheduling API has rate limits. The client handles: +```json +{ + "error": { + "code": "ERROR_CODE", + "message": "Human-readable error message", + "details": {} + } +} +``` -- Automatic pagination for large result sets -- Error responses with status codes -- Request throttling (if needed) +## Rate Limiting -## Support +Acuity Scheduling API has rate limits: -For issues or questions: +- **300 requests per minute** for most endpoints +- **60 requests per minute** for appointment creation -- Acuity Scheduling API Documentation: https://developers.acuityscheduling.com/ -- MCP Documentation: https://modelcontextprotocol.io/ +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 +MIT License - see LICENSE file for details -## Version +## Support -1.0.0 +- **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 diff --git a/servers/acuity-scheduling/package.json b/servers/acuity-scheduling/package.json index 4030db2..6dc8171 100644 --- a/servers/acuity-scheduling/package.json +++ b/servers/acuity-scheduling/package.json @@ -11,7 +11,8 @@ "build": "tsc", "dev": "tsc --watch", "start": "node dist/main.js", - "prepare": "npm run build" + "prepare": "npm run build", + "prepublishOnly": "npm run build" }, "keywords": [ "mcp", diff --git a/servers/acuity-scheduling/src/ui/react-app/coupon-manager/main.tsx b/servers/acuity-scheduling/src/ui/react-app/coupon-manager/main.tsx index 7e45ba3..6c7d170 100644 --- a/servers/acuity-scheduling/src/ui/react-app/coupon-manager/main.tsx +++ b/servers/acuity-scheduling/src/ui/react-app/coupon-manager/main.tsx @@ -1,4 +1,4 @@ import React from 'react'; import ReactDOM from 'react-dom/client'; -import App from './App'; +import App from './App.js'; ReactDOM.createRoot(document.getElementById('root')!).render(); diff --git a/servers/acuity-scheduling/src/ui/react-app/label-manager/main.tsx b/servers/acuity-scheduling/src/ui/react-app/label-manager/main.tsx index 7e45ba3..6c7d170 100644 --- a/servers/acuity-scheduling/src/ui/react-app/label-manager/main.tsx +++ b/servers/acuity-scheduling/src/ui/react-app/label-manager/main.tsx @@ -1,4 +1,4 @@ import React from 'react'; import ReactDOM from 'react-dom/client'; -import App from './App'; +import App from './App.js'; ReactDOM.createRoot(document.getElementById('root')!).render();