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

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
+- **46 MCP Tools** for complete Acuity Scheduling API coverage
-
+- **14 Interactive React Apps** for visual interfaces
-- **Appointments** (8 tools): List, get, create, update, cancel, reschedule, list types, get type
+- Full TypeScript implementation with type safety
-- **Availability** (4 tools): Get dates, get times, get classes, check availability
+- Zod schema validation for all inputs
-- **Clients** (5 tools): List, get, create, update, delete
+- Comprehensive error handling
-- **Calendars** (4 tools): List, get, create, update
+- OAuth and API key authentication support
-- **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 install @mcpengine/acuity-scheduling-server
-npm run build
 ```
 
 ## 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
+```bash
-2. Go to Business Settings → Integrations → API
+ACUITY_CLIENT_ID=your_client_id
-3. Enable API access and copy your User ID and API Key
+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",
+      "command": "acuity-scheduling-mcp",
-      "args": ["/path/to/acuity-scheduling/dist/main.js"],
       "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
+The main API client for interacting with Acuity Scheduling:
-2. **OAuth2**: Uses OAuth2 access token
 
-### 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
+  // Calendars
-{
+  listCalendars(): Promise<Calendar[]>;
-  "tool": "acuity_list_appointments",
+  getCalendar(id: number): Promise<Calendar>;
-  "arguments": {
+  createCalendar(data: CreateCalendarData): Promise<Calendar>;
-    "minDate": "2024-01-01",
+  updateCalendar(id: number, data: UpdateCalendarData): Promise<Calendar>;
-    "maxDate": "2024-01-31",
+
-    "calendarID": 1
+  // 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",
+  description: string;
-  "arguments": {
+  inputSchema: ZodSchema;
-    "appointmentTypeID": 1,
+  handler: async (args: any) => {
-    "datetime": "2024-01-15T10:00:00",
+    // Process request
-    "firstName": "John",
+    const result = await client.methodCall(args);
-    "lastName": "Doe",
+    
-    "email": "john@example.com",
+    // Return MCP-formatted response
-    "phone": "555-1234"
+    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
+- **Authentication Errors** - Invalid credentials or expired tokens
-- Network error retries
+- **Validation Errors** - Invalid input parameters
-- Invalid credential detection
+- **Rate Limiting** - API quota exceeded
-- Missing required parameters validation
+- **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
+## Rate Limiting
-- Error responses with status codes
-- Request throttling (if needed)
 
-## 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/
+The server automatically handles rate limiting with exponential backoff.
-- MCP Documentation: https://modelcontextprotocol.io/
+
+## 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

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

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

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