jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

acuity-scheduling: Complete MCP server, README, TSC clean

Browse Source
This commit is contained in:
Jake Shore 2026-02-12 17:54:18 -05:00
parent 049d1fa718
commit c435e6c3a4
4 changed files with 464 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

608
servers/acuity-scheduling/README.md
View File

@ -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<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>;
```json
{
"tool": "acuity_list_appointments",
"arguments": {
"minDate": "2024-01-01",
"maxDate": "2024-01-31",
"calendarID": 1
}
// 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
}
```
#### 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

3
servers/acuity-scheduling/package.json
View File

@ -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",

2
servers/acuity-scheduling/src/ui/react-app/coupon-manager/main.tsx
View File

@ -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(<React.StrictMode><App /></React.StrictMode>);

2
servers/acuity-scheduling/src/ui/react-app/label-manager/main.tsx
View File

@ -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(<React.StrictMode><App /></React.StrictMode>);