# campaign_chest

**AI Marketing Orchestrator Toolbox** — 35 MCP tools for end-to-end campaign automation.

Integrates Hi.Events + Cal.com + Mautic into a single curated toolset designed for LangGraph agents running the deterministic campaign pipeline:

```
Create Event (Hi.Events) → Publish → Get ticket URL
    → Create Booking Page (Cal.com) → Get booking URL
    → Inject URLs into email templates (Mautic)
    → Create segment + drip campaign → Add contacts
```

## Tool Inventory

### Hi.Events: Ticketed Events (11 tools)

| Tool | Purpose |
|------|---------|
| `hi_events_list_organizers` | Get organizer_id before creating events |
| `hi_events_list` | Check if event already exists |
| `hi_events_get` | Get event details + construct public URL |
| `hi_events_create` | Create event as DRAFT |
| `hi_events_update_settings` | Set location, timezone, support_email |
| `hi_events_create_ticket` | Create ticket type with price + quantity |
| `hi_events_create_capacity` | Set total event capacity |
| `hi_events_publish` | Publish event LIVE → URL becomes active |
| `hi_events_list_tickets` | List ticket types + IDs |
| `hi_events_get_stats` | Ticket sales, revenue, attendance rate |
| `hi_events_list_attendees` | Who registered (for Mautic contact import) |

### Cal.com: Consultation Booking (8 tools)

| Tool | Purpose |
|------|---------|
| `calcom_get_profile` | Get username + timezone for URL construction |
| `calcom_list_schedules` | Pick schedule when creating event type |
| `calcom_list_event_types` | Check existing consultation pages + get URLs |
| `calcom_get_event_type` | Get booking URL after creation |
| `calcom_create_event_type` | Create consultation booking page |
| `calcom_get_available_slots` | Show host availability to agent/user |
| `calcom_create_booking` | Programmatically create a booking |
| `calcom_list_bookings` | Monitor incoming consultation bookings |

### Mautic: Email Campaign (16 tools)

| Tool | Purpose |
|------|---------|
| `mautic_list_contacts` | Check who already exists |
| `mautic_get_contact` | Verify contact details |
| `mautic_create_contact` | Add prospect |
| `mautic_update_contact` | Update contact fields |
| `mautic_list_segments` | Check existing segments |
| `mautic_create_segment` | Create campaign audience |
| `mautic_add_to_segment` | Manual add — reliable (filter-based requires cron) |
| `mautic_list_emails` | Check existing email templates |
| `mautic_create_email` | Create email template with injected URLs |
| `mautic_update_email` | Edit email content |
| `mautic_list_campaigns` | Check existing campaigns |
| `mautic_create_campaign` | Create drip campaign with event timeline |
| `mautic_get_campaign` | Verify campaign state + published status |
| `mautic_list_campaign_contacts` | Verify contacts entered campaign |
| `mautic_send_email` | Direct send fallback (bypasses cron) |
| `mautic_add_to_campaign` | Manually push contact into campaign |

## Installation

```bash
cd /Users/ds/my-mcp-servers/campaign_chest
uv pip install -e ".[mcp]"
```

## Environment Variables

| Variable | Service | Required |
|----------|---------|----------|
| `HI_EVENTS_BASE_URL` | Hi.Events | Yes |
| `HI_EVENTS_EMAIL` | Hi.Events | Yes |
| `HI_EVENTS_PASSWORD` | Hi.Events | Yes |
| `CALCOM_BASE_URL` | Cal.com | No (default: https://api.cal.com) |
| `CALCOM_API_KEY` | Cal.com | Yes |
| `MAUTIC_BASE_URL` | Mautic | Yes |
| `MAUTIC_USERNAME` | Mautic | Yes |
| `MAUTIC_PASSWORD` | Mautic | Yes |

## Claude Desktop Config

```json
"campaign-chest": {
  "command": "uv",
  "args": ["--directory", "/Users/ds/my-mcp-servers/campaign_chest",
           "run", "--extra", "mcp", "mcp_server.py"],
  "env": {
    "HI_EVENTS_BASE_URL": "https://events.brothersbit.com/api",
    "HI_EVENTS_EMAIL": "...",
    "HI_EVENTS_PASSWORD": "...",
    "CALCOM_BASE_URL": "https://connect-api.marketfier.com",
    "CALCOM_API_KEY": "...",
    "MAUTIC_BASE_URL": "https://marketing.brothersbit.com",
    "MAUTIC_USERNAME": "...",
    "MAUTIC_PASSWORD": "..."
  }
}
```

## Key API Quirks

- **Hi.Events**: `location_details` causes 500 on event create — always use `update_settings()` separately
- **Hi.Events**: Public ticket URL: `{base_url without /api}/event/{id}/{slug}`
- **Hi.Events**: Products are returned via `/product-categories` (not `/products` which 500s)
- **Cal.com**: Slots use `start`/`end` params (NOT `startTime`/`endTime`)
- **Mautic**: Campaign `triggerMode: "date"` causes 500 — use `"immediate"` or `"interval"` only
- **Mautic**: `publishUp` format: `"YYYY-MM-DD HH:MM:SS"` (no T, no timezone offset)
- **Mautic**: Campaign events need BOTH `parent` field AND `canvasSettings.connections`
- **Mautic**: Use manual `add_to_segment()` — filter-based segments require cron to process
- **Mautic**: `emailType: "transactional"` bypasses frequency rules (right for event invitations)