# Acuity Scheduling MCP Server

A comprehensive Model Context Protocol (MCP) server for Acuity Scheduling, providing full API integration with 59 tools and 12 interactive React applications.

## Features

### 🛠️ 59 MCP Tools

Complete CRUD operations across all Acuity Scheduling domains:

- **Appointments** (6 tools): List, get, create, update, cancel, reschedule
- **Calendars** (2 tools): List, get
- **Appointment Types** (5 tools): List, get, create, update, delete
- **Clients** (5 tools): List, get, create, update, delete
- **Availability** (2 tools): Get available dates and times
- **Blocks** (5 tools): List, get, create, update, delete (block out time)
- **Products** (5 tools): List, get, create, update, delete
- **Certificates** (4 tools): List, get, create, delete (gift certificates)
- **Coupons** (5 tools): List, get, create, update, delete
- **Forms** (5 tools): List, get, create, update, delete (intake forms)
- **Labels** (5 tools): List, get, create, update, delete
- **Packages** (5 tools): List, get, create, update, delete
- **Subscriptions** (5 tools): List, get, create, update, delete

### 🎨 12 React Applications

Modern, dark-themed UI applications:

1. **Appointment Calendar** - View and manage daily/weekly appointments
2. **Appointment Detail** - Detailed view of individual appointments
3. **Client Directory** - Browse and search all clients
4. **Client Detail** - Complete client profile with appointment history
5. **Availability Manager** - Manage available time slots and blocks
6. **Product Catalog** - View and manage products/services
7. **Certificate Viewer** - Manage gift certificates
8. **Coupon Manager** - Create and track discount coupons
9. **Form Builder** - Design and manage intake forms
10. **Analytics Dashboard** - Business insights and metrics
11. **Booking Flow** - End-to-end appointment booking experience
12. **Schedule Overview** - Weekly schedule summary and revenue tracking

## Installation

```bash
npm install
```

## Configuration

Set the following environment variables:

```bash
export ACUITY_USER_ID="your_acuity_user_id"
export ACUITY_API_KEY="your_acuity_api_key"
```

You can find your User ID and API Key in your Acuity Scheduling account under:
**Business Settings → Integrations → API**

## Usage

### As MCP Server

Build and start the server:

```bash
npm run build
npm start
```

### With Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "acuity": {
      "command": "node",
      "args": ["/path/to/acuity-scheduling-mcp-server/dist/main.js"],
      "env": {
        "ACUITY_USER_ID": "your_user_id",
        "ACUITY_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Development

Watch mode for TypeScript:

```bash
npm run dev
```

Type checking without building:

```bash
npm run typecheck
```

### Running React Apps

Each React app can be run independently using Vite:

```bash
cd src/ui/react-app/src/apps/appointment-calendar
npm install
npm run dev
```

## Architecture

### API Client

The `AcuityClient` class (`src/clients/acuity.ts`) handles:
- Basic Authentication (userId + API key)
- Request/response handling
- Error handling
- Pagination support

### Tools

Each domain has its own tool file in `src/tools/`:
- Standardized input schemas
- Proper error handling
- Type-safe operations

### Type System

Complete TypeScript definitions in `src/types/index.ts` covering:
- Request/response types
- API entities
- Client configuration

## API Reference

### Example Tool Calls

**List appointments:**
```typescript
{
  "name": "acuity_list_appointments",
  "arguments": {
    "minDate": "2024-01-01",
    "maxDate": "2024-01-31",
    "max": 100
  }
}
```

**Create appointment:**
```typescript
{
  "name": "acuity_create_appointment",
  "arguments": {
    "appointmentTypeID": 123,
    "datetime": "2024-01-15T14:00:00",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "555-1234"
  }
}
```

**Get availability:**
```typescript
{
  "name": "acuity_get_availability_dates",
  "arguments": {
    "appointmentTypeID": 123,
    "month": "2024-01",
    "timezone": "America/New_York"
  }
}
```

## Tech Stack

- **Server**: TypeScript, Node.js, MCP SDK
- **UI**: React 18, TypeScript, Vite, Tailwind CSS
- **API**: Acuity Scheduling REST API v1

## License

MIT

## Support

For issues or questions:
- Acuity API Docs: https://developers.acuityscheduling.com/
- MCP Docs: https://modelcontextprotocol.io/

---

Built with ❤️ for the Model Context Protocol