@elitedcs/ghl-mcp 3.0.0

package/README.md

@@ -0,0 +1,758 @@
+# Elite DCs GHL MCP Server
+
+**Full GoHighLevel API access for Claude.** 171 tools across 35 modules — manage contacts, conversations, pipelines, calendars, funnels, workflows, invoices, custom objects, webhooks, and more. **Includes full workflow builder, funnel/page editor, form builder, pipeline builder, bulk operations, account export, and workflow cloning** — capabilities no other GHL tool offers.
+
+**v2.7.0** — Production-hardened with automatic retry/backoff, Zod-validated API responses, pre-flight workflow action validation, and type-safe tool registration. Built to share confidently.
+
+Works with **both the Claude Desktop App and Claude Code terminal** — your choice.
+
+Built by [Elite DCs, LLC](https://elitedcs.com) for the Clinic Launch Lab project and beyond.
+
+---
+
+## What Makes This Different
+
+Most GHL integrations give you read access and basic CRUD. This server goes far beyond that — it includes capabilities that **don't exist anywhere else**, built on reverse-engineered internal APIs that GHL's public API doesn't expose.
+
+| Exclusive Feature | Why It Matters |
+|---|---|
+| **Programmatic Workflow Builder** | The only tool on the market that can create, edit, and publish GHL workflows via code. GHL's public API has no workflow write endpoints — this uses their internal backend API (the same one their UI calls) to give Claude full workflow CRUD. Build entire automation sequences from a conversation. |
+| **Deep Workflow Cloning** | Clone any workflow with full UUID remapping — every action, trigger, branch, and internal reference gets new IDs. No other tool can duplicate a workflow programmatically without ID collisions. |
+| **Funnel & Page Editor** | Read and edit funnel page content — sections, elements, rows, CSS, tracking codes. Goes beyond the public API's list-only access. |
+| **Form Builder** | Full form CRUD including field management, conditional logic, and auto-responder configuration via internal API. |
+| **Pipeline Builder** | Create, edit, and delete pipelines and stages via internal API. The public API only lists pipelines — this lets Claude build them. |
+| **Template Deployment** | Deploy a complete sub-account setup (tags, custom fields, pipelines, workflows, forms) from a single template. Set up a new client in minutes instead of hours. |
+| **Multi-Sub-Account Token Registry** | Register multiple sub-accounts with their own API keys. Switch locations mid-session and the API key swaps automatically — no restart needed. |
+| **Full Account Export & Diff** | Export an entire sub-account to JSON or compare two locations side-by-side. Useful for auditing, migration, and quality control. |
+
+Everything else — CRM, conversations, calendars, invoices, bulk ops — works through GHL's official public API v2 with full read/write access.
+
+---
+
+## What It Does
+
+This MCP (Model Context Protocol) server connects Claude directly to GoHighLevel's API v2. Once installed, Claude can read and write to your GHL account — no browser, no Zapier, no middleware. Use it from the Claude Desktop App (no terminal needed) or from Claude Code in the terminal.
+
+| Capability | What Claude Can Do |
+|---|---|
+| **CRM** | Search, create, update, and delete contacts. Manage tags, notes, tasks. |
+| **Conversations** | Read message threads, send SMS/email/WhatsApp, update message status. |
+| **Pipeline** | Create and manage opportunities. Move deals through stages. |
+| **Scheduling** | Check availability, book appointments, manage calendars. |
+| **Automation** | **Full workflow builder** — create, read, edit, and publish workflows. See every action, trigger, condition, and branch. Clone workflows with deep ID remapping. |
+| **Marketing** | **Funnel/page editor** — read and edit existing funnel page content (sections, elements, CSS). **Full form builder** — read/edit all fields, conditional logic, auto-responder. |
+| **Pipelines** | **Full pipeline builder** — create, edit, delete pipelines. Add, remove, rename, reorder stages. |
+| **Bulk Ops** | Batch tag, untag, update fields, enroll in workflows, or delete contacts — all rate-limited. |
+| **Backup** | Export entire sub-account to JSON. Compare two locations side-by-side for auditing. |
+| **Multi-Location** | Switch between sub-accounts mid-session. Token registry stores per-location API keys for seamless switching. |
+| **Billing** | Create/send/void invoices, record payments, view orders and subscriptions. |
+| **Content** | Manage blog posts, social media posts, courses, media files. |
+| **Custom Objects** | Full CRUD on custom object schemas and records. Manage associations. |
+| **Estimates & Coupons** | Create/send estimates, manage promo codes. |
+| **Webhooks** | Create and manage webhook subscriptions. |
+| **Documents** | List, send, and manage documents/contracts. |
+| **Admin** | View/update sub-accounts, manage custom fields, custom values, location tags, users. |
+
+---
+
+## Quick Start
+
+Choose your path:
+
+### Path 1: Easy Install (Recommended — No Technical Knowledge Needed)
+
+**What you need first:**
+1. **Claude** — either the [Claude Desktop App](https://claude.ai/download) or [Claude Code](https://claude.ai/code) (or both!)
+2. **Node.js** — download from [nodejs.org](https://nodejs.org) (click the big green "LTS" button and run the installer)
+3. Your **license key** and **purchase email** (sent to you after purchase)
+4. Your **GHL API Key** and **Location ID** (see "Get Your GHL API Key" below)
+
+**Then just do this:**
+
+1. Open a terminal (on Mac: search "Terminal" in Spotlight) or open Claude Code
+2. Paste this line and press Enter:
+```
+cd ~/projects && git clone git@github.com:drjerryrelth/ghl-command-mcp.git && cd ghl-command-mcp && bash setup.sh
+```
+> If running from inside Claude Code, prefix the command with `!`:
+> ```
+> ! cd ~/projects && git clone git@github.com:drjerryrelth/ghl-command-mcp.git && cd ghl-command-mcp && bash setup.sh
+> ```
+
+> **Note:** This repo is private. You must have an SSH key linked to your GitHub account. See [GitHub SSH setup](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) if you haven't done this before.
+
+3. The setup wizard opens — it will:
+   - Validate your license key (from your purchase email)
+   - Ask for your GHL API key (paste it when prompted)
+   - Ask for your Location ID (paste it when prompted)
+   - Verify your credentials work
+   - Optionally enable the workflow builder (you can skip this)
+   - **Ask which Claude client(s) to register with** — Desktop App, terminal, or both
+   - Register everything for you automatically
+4. Restart the Claude app (quit fully and reopen) or restart Claude Code
+5. Try it: type `"List my contacts"` — you should see your GHL data
+
+**That's it. One command, follow the prompts, done.**
+
+---
+
+### Path 2: Manual Install (For Developers)
+
+#### Option A: Claude Code (Terminal)
+
+```bash
+git clone git@github.com:drjerryrelth/ghl-command-mcp.git
+cd ghl-command-mcp
+npm install && npm run build
+cp start-mcp.example.sh start-mcp.sh
+# Edit start-mcp.sh with your API key and Location ID
+chmod +x start-mcp.sh
+claude mcp add --scope user -t stdio ghl $(pwd)/start-mcp.sh
+```
+
+> **Why a wrapper script?** Claude Code's env injection via MCP config is unreliable. The wrapper script exports env vars directly, guaranteeing they reach the server process. MCP servers must be registered in `~/.claude.json` (via `claude mcp add`), NOT in `~/.claude/mcp.json`.
+
+#### Option B: Claude Desktop App
+
+```bash
+git clone git@github.com:drjerryrelth/ghl-command-mcp.git
+cd ghl-command-mcp
+npm install && npm run build
+```
+
+Then add the MCP server to your Claude Desktop config file:
+
+- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add a `"ghl"` entry under `"mcpServers"`:
+
+```json
+{
+  "mcpServers": {
+    "ghl": {
+      "command": "node",
+      "args": ["/full/path/to/ghl-command-mcp/dist/index.js"],
+      "env": {
+        "GHL_API_KEY": "YOUR_API_KEY_HERE",
+        "GHL_LOCATION_ID": "YOUR_LOCATION_ID_HERE"
+      }
+    }
+  }
+}
+```
+
+> **Tip:** Replace `/full/path/to/` with the actual path where you cloned the repo (e.g., `/Users/yourname/projects/ghl-command-mcp/dist/index.js`). To add workflow builder support, include `GHL_USER_ID`, `GHL_FIREBASE_API_KEY`, and `GHL_FIREBASE_REFRESH_TOKEN` in the `env` block too.
+
+Quit the Claude app fully and reopen it. The GHL tools will appear automatically.
+
+#### Option C: Both
+
+Run the Easy Install (Path 1) — the setup wizard lets you register with both clients in one step.
+
+---
+
+### Get Your GHL API Key
+
+> **CRITICAL: Sub-Account Level Only**
+>
+> Private Integrations in GHL are **scoped to individual sub-accounts**, NOT to the agency level. You must create a separate Private Integration **inside each sub-account** you want to connect. An API key created in Sub-Account A will return `403 Forbidden` if you try to use it with Sub-Account B's Location ID.
+>
+> **Your API key can only be copied ONCE** — at the moment you create the integration. After you leave that screen, the key is permanently masked and cannot be retrieved. If you lose it, you must delete the integration and create a new one (which generates a new key).
+
+1. Log into GoHighLevel
+2. **Switch into the specific sub-account** you want to connect (not the agency view)
+3. Go to **Settings** > **Integrations**
+4. Click **Private Integrations** > **Create Private Integration**
+5. Name it `Claude Code MCP`
+6. Enable all scopes/permissions you want Claude to access
+7. **Immediately copy the API Key** and paste it into your config — you will not be able to see it again
+
+### Enable Workflow Builder (Optional)
+
+The workflow builder tools use GHL's internal API and require additional Firebase credentials. Without these, the standard API tools still work — you just won't have workflow editing.
+
+**Step 1: Get your Firebase credentials from GHL**
+
+1. Log into `app.gohighlevel.com` in Chrome
+2. Press **Cmd + Option + I** (Mac) or **F12** (Windows) to open Developer Tools
+3. Go to **Application** tab → **IndexedDB** → expand **firebaseLocalStorageDb** → **firebaseLocalStorage**
+4. Click the entry — you'll see a JSON object with:
+   - `stsTokenManager.refreshToken` — this is your **Firebase Refresh Token**
+   - The `fbase_key` contains the **Firebase API Key** (the part between `firebase:authUser:` and `:[DEFAULT]`)
+5. Your **User ID** is in the `uid` field
+
+**Step 2: Add to your wrapper script**
+
+Add these to `start-mcp.sh` alongside your existing env vars:
+
+```bash
+export GHL_USER_ID="your-user-id"
+export GHL_FIREBASE_API_KEY="your-firebase-api-key"
+export GHL_FIREBASE_REFRESH_TOKEN="your-firebase-refresh-token"
+```
+
+Restart Claude Code and the workflow builder tools will be available.
+
+> **Note:** The Firebase refresh token may rotate periodically. If workflow tools stop working, re-extract the token from your browser using the steps above.
+
+### Find Your Location ID
+
+Your Location ID (sub-account ID) is in the GHL URL when you're inside a sub-account:
+
+```
+https://app.gohighlevel.com/v2/location/YOUR_LOCATION_ID/dashboard
+```
+
+### Verify It Works
+
+Restart the Claude Desktop App (quit fully and reopen) or restart Claude Code, then try:
+
+```
+"List my contacts"
+"Show my pipelines"
+"What calendars do I have?"
+```
+
+---
+
+## Tools (171)
+
+### CRM & Contacts (15 tools)
+
+| Tool | What It Does |
+|---|---|
+| `search_contacts` | Search contacts by name, email, phone, or tag |
+| `get_contact` | Get full contact details by ID |
+| `create_contact` | Create a new contact |
+| `update_contact` | Update contact fields |
+| `delete_contact` | Delete a contact |
+| `upsert_contact` | Create or update a contact (match by email/phone) |
+| `add_contact_tags` | Add tags to a contact |
+| `remove_contact_tags` | Remove tags from a contact |
+| `get_contact_tasks` | List tasks for a contact |
+| `create_contact_task` | Create a task on a contact |
+| `get_contact_notes` | List notes on a contact |
+| `create_contact_note` | Add a note to a contact |
+| `get_contact_appointments` | List a contact's appointments |
+| `add_contact_to_workflow` | Add a contact to a workflow |
+| `remove_contact_from_workflow` | Remove a contact from a workflow |
+
+### Conversations & Messaging (8 tools)
+
+| Tool | What It Does |
+|---|---|
+| `search_conversations` | Search conversation threads |
+| `get_conversation` | Get a specific conversation |
+| `create_conversation` | Start a new conversation |
+| `get_messages` | Read messages in a conversation |
+| `send_message` | Send SMS, email, or WhatsApp message |
+| `add_inbound_message` | Log an inbound message |
+| `update_message_status` | Update read/unread status |
+| `get_message` | Get a specific message |
+
+### Opportunities & Pipelines (7 tools)
+
+| Tool | What It Does |
+|---|---|
+| `search_opportunities` | Search deals across pipelines |
+| `get_opportunity` | Get opportunity details |
+| `create_opportunity` | Create a new deal |
+| `update_opportunity` | Update deal fields or move stages |
+| `delete_opportunity` | Delete a deal |
+| `update_opportunity_status` | Change opportunity status (won/lost/open) |
+| `get_pipelines` | List all pipelines and their stages |
+
+### Calendars & Scheduling (11 tools)
+
+| Tool | What It Does |
+|---|---|
+| `get_calendars` | List all calendars |
+| `get_calendar` | Get calendar details |
+| `create_calendar` | Create a new calendar |
+| `update_calendar` | Update calendar settings |
+| `delete_calendar` | Delete a calendar |
+| `get_free_slots` | Check available time slots |
+| `get_calendar_events` | List events on a calendar |
+| `get_appointment` | Get appointment details |
+| `create_appointment` | Book an appointment |
+| `update_appointment` | Update an appointment |
+| `delete_appointment` | Cancel an appointment |
+
+### Locations & Sub-Accounts (15 tools)
+
+| Tool | What It Does |
+|---|---|
+| `get_location` | Get sub-account details |
+| `update_location` | Update sub-account settings |
+| `search_locations` | Search locations |
+| `get_location_tags` | List all tags in a location |
+| `create_location_tag` | Create a new tag |
+| `update_location_tag` | Update an existing tag |
+| `delete_location_tag` | Delete a tag |
+| `get_custom_fields` | List all custom fields |
+| `create_custom_field` | Create a new custom field |
+| `update_custom_field` | Update a custom field |
+| `delete_custom_field` | Delete a custom field |
+| `get_custom_values` | List all custom values |
+| `create_custom_value` | Create a new custom value |
+| `update_custom_value` | Update a custom value |
+| `delete_custom_value` | Delete a custom value |
+
+### Custom Objects (7 tools)
+
+| Tool | What It Does |
+|---|---|
+| `list_custom_objects` | List all custom object schemas |
+| `get_custom_object` | Get a custom object schema by key |
+| `search_custom_object_records` | Search records of a custom object |
+| `get_custom_object_record` | Get a single record by ID |
+| `create_custom_object_record` | Create a new record |
+| `update_custom_object_record` | Update an existing record |
+| `delete_custom_object_record` | Delete a record |
+
+### Associations (3 tools)
+
+| Tool | What It Does |
+|---|---|
+| `list_associations` | List associations for a custom object record |
+| `create_association` | Link a record to a contact/opportunity/other record |
+| `delete_association` | Remove an association |
+
+### Invoices & Billing (8 tools)
+
+| Tool | What It Does |
+|---|---|
+| `list_invoices` | List all invoices |
+| `get_invoice` | Get invoice details |
+| `create_invoice` | Create a new invoice |
+| `update_invoice` | Update an invoice |
+| `send_invoice` | Send invoice to recipient |
+| `void_invoice` | Void an invoice |
+| `record_invoice_payment` | Record a payment against an invoice |
+| `delete_invoice` | Delete an invoice |
+
+### Estimates (6 tools)
+
+| Tool | What It Does |
+|---|---|
+| `list_estimates` | List estimates/quotes |
+| `get_estimate` | Get estimate details |
+| `create_estimate` | Create a new estimate |
+| `update_estimate` | Update an estimate |
+| `delete_estimate` | Delete an estimate |
+| `send_estimate` | Send an estimate to a contact |
+
+### Coupons (5 tools)
+
+| Tool | What It Does |
+|---|---|
+| `list_coupons` | List all coupons/promo codes |
+| `get_coupon` | Get coupon details |
+| `create_coupon` | Create a new coupon |
+| `update_coupon` | Update a coupon |
+| `delete_coupon` | Delete a coupon |
+
+### Webhooks (5 tools)
+
+| Tool | What It Does |
+|---|---|
+| `list_webhooks` | List all webhook subscriptions |
+| `get_webhook` | Get webhook details |
+| `create_webhook` | Create a new webhook |
+| `update_webhook` | Update a webhook |
+| `delete_webhook` | Delete a webhook |
+
+### Documents (4 tools)
+
+| Tool | What It Does |
+|---|---|
+| `list_documents` | List documents and contracts |
+| `get_document` | Get document details and signature status |
+| `delete_document` | Delete a document |
+| `send_document` | Send a document for e-signature |
+
+### Payments (4 tools)
+
+| Tool | What It Does |
+|---|---|
+| `get_orders` | View all orders |
+| `get_order` | Get order details |
+| `get_subscriptions` | List active subscriptions |
+| `get_transactions` | View transaction history |
+
+### Workflow Builder (6 tools) — Internal API
+
+> **This is the flagship feature.** GHL's public API has **zero** workflow write endpoints. These tools use GHL's internal backend API — the same API their own UI calls — reverse-engineered to give Claude full workflow CRUD. No other GHL integration, Zapier connector, or third-party tool can create or edit workflows programmatically. Requires additional Firebase auth setup (see "Enable Workflow Builder" in Quick Start above).
+
+| Tool | What It Does |
+|---|---|
+| `list_workflows_full` | List all workflows with full metadata, versions, and permissions |
+| `get_workflow_full` | Get complete workflow internals: every action, trigger, condition, if/else branch, email template, SMS body |
+| `create_workflow` | Create a new workflow from scratch (starts as draft) |
+| `update_workflow_actions` | Add, edit, or remove actions, triggers, and branches in an existing workflow |
+| `delete_workflow_full` | Permanently delete a workflow |
+| `publish_workflow` | Publish a draft workflow to make it active |
+
+**What you can build:** Complete automation sequences — lead nurture drip campaigns, appointment reminder sequences, onboarding flows, re-engagement workflows, internal notification chains. Tell Claude what you want and it builds the workflow action by action.
+
+**Supported action types:** `sms`, `email`, `add_contact_tag`, `remove_contact_tag`, `update_contact_field`, `wait`, `if_else`, `webhook`, `create_opportunity`, `custom_code`, `add_notes`, `internal_notification`, `task-notification`, `remove_from_workflow`, and more.
+
+**Supported trigger types:** `contact_tag`, `contact_created`, `form_submission`, `customer_reply`, `appointment`, `inbound_webhook`, `payment_received`, and more.
+
+### Pipeline Builder (5 tools) — Internal API
+
+> Also uses GHL's internal API. The public API only lists pipelines — this lets Claude create, edit, and delete pipelines and their stages.
+
+| Tool | What It Does |
+|---|---|
+| `list_pipelines_full` | List all pipelines with full stage details, positions, and display settings |
+| `get_pipeline_full` | Get a single pipeline with complete stage configuration |
+| `create_pipeline` | Create a new pipeline with stages |
+| `update_pipeline` | Update name, add/remove/rename/reorder stages |
+| `delete_pipeline` | Permanently delete a pipeline |
+
+### Bulk Operations (5 tools)
+
+| Tool | What It Does |
+|---|---|
+| `bulk_add_tags` | Add tags to multiple contacts at once (rate-limited) |
+| `bulk_remove_tags` | Remove tags from multiple contacts (rate-limited) |
+| `bulk_update_contacts` | Update the same fields on multiple contacts (rate-limited) |
+| `bulk_add_to_workflow` | Enroll multiple contacts into a workflow (rate-limited) |
+| `bulk_delete_contacts` | Delete multiple contacts (rate-limited, requires safety confirmation) |
+
+### Account Export & Comparison (2 tools)
+
+| Tool | What It Does |
+|---|---|
+| `export_account` | Full sub-account backup — contacts, pipelines, workflows, funnels, forms, fields, tags, calendars, users |
+| `compare_locations` | Side-by-side diff of two sub-accounts for auditing or migration |
+
+### Location Switcher & Token Registry (6 tools)
+
+| Tool | What It Does |
+|---|---|
+| `get_current_location` | Show which sub-account is active |
+| `switch_location` | Switch to a different sub-account mid-session (auto-swaps API key from registry) |
+| `list_available_locations` | List all accessible sub-accounts |
+| `register_location` | Add a sub-account and its API key to the token registry |
+| `unregister_location` | Remove a sub-account from the token registry |
+| `list_registered_locations` | List all sub-accounts stored in the token registry |
+
+### Workflow Cloner (1 tool)
+
+> Deep-clones a workflow with full UUID remapping. Every action, trigger, branch, and internal cross-reference gets a new unique ID. GHL has no built-in way to duplicate a workflow programmatically — this is the only tool that can.
+
+| Tool | What It Does |
+|---|---|
+| `clone_workflow` | Deep clone a workflow with new UUIDs for all actions, triggers, and references |
+
+### Template Deployer (3 tools)
+
+> Deploy a complete sub-account setup from a pre-built template — tags, custom fields, pipelines, workflows, and forms — in one step. Claude walks the user through a questionnaire, then deploys everything. Includes dry-run mode to preview changes before applying.
+
+| Tool | What It Does |
+|---|---|
+| `list_templates` | List available setup templates (clinic, med spa, dental, etc.) |
+| `get_template_questionnaire` | Get the questionnaire for a template — present to user conversationally |
+| `deploy_template` | Deploy a complete sub-account setup from a template (tags, fields, pipelines, workflows, forms). Supports dry-run mode. |
+
+### Other Modules
+
+| Module | Tools | What It Does |
+|---|---|---|
+| **Social Planner** | 5 | Create, list, delete posts, view connected accounts |
+| **Businesses** | 5 | Full CRUD on business entities |
+| **Blogs** | 5 | Posts, authors, categories, URL slugs |
+| **Funnels** (public API) | 2 | List funnels and their pages |
+| **Forms** (public API) | 2 | List forms and view submissions |
+| **Surveys** | 2 | List surveys and view submissions |
+| **Users** | 2 | List and view team members |
+| **Media** | 2 | Browse and delete media files |
+| **Campaigns** | 1 | List campaigns |
+| **Workflows** (public API) | 1 | List all workflows |
+| **Courses** | 1 | List courses |
+| **Emails** | 1 | List email campaigns |
+| **Trigger Links** | 1 | List trigger links |
+
+---
+
+## How It Works
+
+```
+┌──────────────────┐   ┌──────────────────┐
+│  Claude Desktop  │   │  Claude Code     │
+│  App (GUI)       │   │  (Terminal)      │
+└────────┬─────────┘   └────────┬─────────┘
+         │                      │
+         └──────────┬───────────┘
+                    │ MCP Protocol (stdio)
+┌───────────────────┴─────────────────────┐
+│            GHL MCP SERVER               │
+│                                         │
+│  ┌──────────┐ ┌──────────┐ ┌────────┐  │
+│  │ Contacts │ │ Calendar │ │Invoices│  │
+│  │ 15 tools │ │ 11 tools │ │8 tools │  │
+│  └────┬─────┘ └────┬─────┘ └───┬────┘  │
+│       └─────────────┼───────────┘       │
+│              ┌──────┴──────┐            │
+│              │  GHL Client │            │
+│              └──────┬──────┘            │
+├─────────────────────┼───────────────────┤
+│                     ↓                   │
+│        GoHighLevel API v2               │
+│   https://services.leadconnectorhq.com  │
+└─────────────────────────────────────────┘
+```
+
+### Architecture
+
+- **`src/index.ts`** — MCP server entry, startup API key validation, tool registration.
+- **`src/ghl-client.ts`** — HTTP client for GHL API v2. Returns `Promise<unknown>` (no generic `as T` casts). Automatic retry with exponential backoff on 429/5xx/network errors. 30-second timeout with clear error messages.
+- **`src/workflow-builder-client.ts`** — Internal API client for workflow CRUD. Firebase auth with thread-safe token refresh (promise lock), retry/backoff, Zod-validated `WorkflowFull` responses, and pre-flight `validateActionChain()` that catches common action attribute errors before GHL can silently fail.
+- **`src/api-schemas.ts`** — Zod response schemas for contacts, pipelines, and calendars. Runtime validation on the most-used API paths.
+- **`src/workflow-action-types.ts`** — Discriminated union types for all 11 documented workflow action types. Compile-time enforcement of action-specific attributes (SMS needs `body`, email needs `subject`+`html`, etc.).
+- **`src/tool-helpers.ts`** — `safeTool()` wrapper (automatic try/catch + JSON formatting for 127 tools), response helpers, error formatting.
+- **`src/token-registry.ts`** — Per-location API key storage, Zod-validated on load with corruption backup.
+- **`src/tools/index.ts`** — Type-safe registry array. Compiler catches missing tool registrations.
+- **`src/tools/*.ts`** — One file per GHL domain. Most use `safeTool()` for zero-boilerplate handlers.
+
+### Build System
+
+Uses **esbuild** for production builds (not tsc). TypeScript 5.9.3 + MCP SDK types cause tsc to run out of memory at 4GB+. esbuild bundles in ~5ms with zero memory issues.
+
+```bash
+npm run build    # esbuild → dist/index.js (~212KB)
+npm run dev      # tsc --watch (type-checking only)
+```
+
+### Data Flow
+
+```
+User prompt → Claude Code → MCP tool call → GHL Client → GHL API → JSON response → Claude Code → User
+```
+
+Every tool returns structured JSON. Claude interprets the response and presents it naturally. No data is stored locally — it's a pass-through to GHL's API.
+
+---
+
+## Project Structure
+
+```
+ghl-command-mcp/
+├── src/
+│   ├── index.ts                   # MCP server entry point + startup validation
+│   ├── ghl-client.ts              # GHL API v2 HTTP client (retry/backoff, returns unknown)
+│   ├── workflow-builder-client.ts # Internal API client (Firebase auth, Zod-validated responses)
+│   ├── workflow-action-types.ts   # Discriminated union types for workflow actions
+│   ├── api-schemas.ts             # Zod response schemas for contacts, pipelines, calendars
+│   ├── token-registry.ts          # Per-location API key storage (Zod-validated on load)
+│   ├── tool-helpers.ts            # safeTool() wrapper, response helpers, error formatting
+│   └── tools/
+│       ├── index.ts               # Type-safe tool registry (compiler-checked)
+│       ├── contacts.ts            # 15 tools — CRM & contact management
+│       ├── conversations.ts       # 8 tools — messaging (SMS, email, WhatsApp)
+│       ├── opportunities.ts       # 7 tools — pipeline & deal management
+│       ├── calendars.ts           # 11 tools — scheduling & appointments
+│       ├── locations.ts           # 15 tools — sub-accounts, custom fields/values, tags
+│       ├── invoices.ts            # 8 tools — invoicing & payment recording
+│       ├── custom-objects.ts      # 7 tools — custom object schema & record CRUD
+│       ├── estimates.ts           # 6 tools — estimates/quotes
+│       ├── social-planner.ts      # 5 tools — social media management
+│       ├── businesses.ts          # 5 tools — business entity management
+│       ├── blogs.ts               # 5 tools — blog management
+│       ├── coupons.ts             # 5 tools — promo code management
+│       ├── webhooks.ts            # 5 tools — webhook subscriptions
+│       ├── payments.ts            # 4 tools — orders, subscriptions, transactions
+│       ├── documents.ts           # 4 tools — document & contract management
+│       ├── associations.ts        # 3 tools — custom object associations
+│       ├── funnels.ts             # 2 tools — funnel & page listing
+│       ├── forms.ts               # 2 tools — forms & submissions
+│       ├── surveys.ts             # 2 tools — surveys & submissions
+│       ├── users.ts               # 2 tools — team members
+│       ├── media.ts               # 2 tools — media file management
+│       ├── campaigns.ts           # 1 tool  — campaign listing
+│       ├── workflows.ts           # 1 tool  — workflow listing
+│       ├── courses.ts             # 1 tool  — course listing
+│       ├── emails.ts              # 1 tool  — email campaign listing
+│       ├── trigger-links.ts       # 1 tool  — trigger link listing
+│       ├── workflow-builder.ts    # 6 tools — full workflow CRUD (internal API)
+│       ├── funnel-builder.ts      # 9 tools — funnel/page builder (internal API)
+│       ├── form-builder.ts        # 5 tools — form builder (internal API)
+│       ├── pipeline-builder.ts    # 5 tools — pipeline/stage builder (internal API)
+│       ├── bulk-operations.ts     # 5 tools — batch contact operations
+│       ├── account-export.ts      # 2 tools — backup & location comparison
+│       ├── workflow-cloner.ts     # 1 tool  — deep workflow cloning
+│       ├── location-switcher.ts   # 6 tools — multi-location support + token registry
+│       └── template-deployer.ts   # 3 tools — deploy sub-account from template (Zod-validated)
+├── templates/
+│   ├── clinic-medspa.json         # Clinic/Med Spa blueprint
+│   └── action-schemas.json        # Mandatory workflow action attribute schemas
+├── dist/                          # Compiled JavaScript (generated by build)
+├── setup.sh                       # One-command install + setup wizard
+├── setup-wizard.mjs               # Interactive setup wizard (@clack/prompts)
+├── start-mcp.example.sh           # Wrapper script template (copy to start-mcp.sh)
+├── package.json
+├── tsconfig.json
+├── CLAUDE.md                      # Claude Code project instructions
+├── CHANGELOG.md
+├── CONTRIBUTING.md                # Contributor guide
+├── .gitignore
+└── README.md
+```
+
+---
+
+## Known Limitations
+
+These are GHL features the MCP server **does not currently support**. In most cases, the GHL API either doesn't expose these endpoints or the feature requires browser-level interaction.
+
+| Area | What's Missing |
+|---|---|
+| **Contact deduplication** | No merge or dedup tool. `search_contacts` can find potential duplicates by name/email/phone, but merging must be done manually in the GHL UI. |
+| **Account auditing** | No one-click "find what's broken" scanner. `export_account` dumps full sub-account data and `compare_locations` diffs two accounts — Claude can analyze the output to spot issues, but it's not a turnkey audit button. |
+| **SMS/email templates** | No template CRUD. You can send messages and build email actions in workflows, but managing reusable message templates isn't supported. |
+| **Payment gateway config** | Read-only access to orders, subscriptions, and transactions. No Stripe/payment gateway setup or configuration. |
+| **Phone & call tracking** | No call tools. VoIP, call tracking, and phone number management are not available via the API. |
+| **Memberships & communities** | Not supported. GHL's membership/community features don't have public API endpoints. |
+| **Reporting & analytics** | No dashboard or reporting tools. Use `export_account` for raw data, but there are no built-in analytics queries. |
+| **Trigger links** | List only — no create, update, or delete. |
+| **Campaigns** | List only — no create, update, or delete. |
+| **Courses** | List only — no create, update, or delete. |
+| **Workflow builder auth** | Requires Firebase credentials extracted from browser DevTools. The refresh token may rotate, requiring re-extraction. |
+
+> **Contributing:** If you'd like to help close any of these gaps, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Security
+
+This MCP server is safe to share via GitHub.
+
+| Concern | How It's Handled |
+|---|---|
+| **API Keys** | Stored in environment variables or wrapper script only. Never in code, never committed. |
+| **`.env` & `start-mcp.sh`** | Gitignored. Your credentials never touch version control. |
+| **Multi-user** | Each user brings their own API key. Complete account isolation. |
+| **Scope** | The server only talks to GHL's API. No filesystem access, no shell commands, no network access beyond GHL. |
+| **Permissions** | Controlled by your GHL Private Integration scopes. Disable what you don't need. |
+
+---
+
+## Reliability & Type Safety
+
+This server has been through a rigorous, multi-pass audit for production reliability (v2.4.0–v2.7.0). Here's what's in place:
+
+| Layer | What It Does |
+|---|---|
+| **Retry with backoff** | Both HTTP clients automatically retry on 429 rate limits, 5xx server errors, and transient network failures (ECONNRESET, ETIMEDOUT). 3 retries with exponential backoff. Respects `Retry-After` headers. |
+| **Clear error messages** | Timeouts show `"Request timeout (30s): GET /path"` instead of cryptic abort errors. API errors include status code, method, path, and response body. |
+| **Zod-validated responses** | Critical API paths (contacts, pipelines, calendars, workflows) validate response structure at runtime with Zod schemas. Malformed responses throw immediately with clear errors instead of silently passing garbage. |
+| **Zod-validated config** | Token registry (`.ghl-tokens.json`) and template files are validated against Zod schemas on load. Corrupted files are backed up and reported, not silently accepted. |
+| **Pre-flight workflow validation** | `validateActionChain()` checks action attributes before sending to GHL — catches missing `body` on SMS, missing `subject`/`html` on email, missing `pipelineId`/`stageId` on create_opportunity, and more. Prevents GHL's silent failure mode where bad actions kill all subsequent steps. |
+| **Delete confirmation** | 10 high-risk destructive operations (delete_contact, delete_workflow, delete_pipeline, delete_funnel, etc.) require `confirm: "DELETE"` parameter. Prevents accidental deletion. |
+| **Thread-safe token refresh** | Firebase token refresh uses a promise-based lock — concurrent requests share one refresh instead of racing. Failed refresh clears the cache immediately instead of leaving a stale token for 55 minutes. |
+| **Startup validation** | Server validates the API key at startup (non-blocking) and logs a clear warning if it's invalid. |
+| **Type-safe registration** | Tool modules are registered via a typed array — the compiler catches missing registrations. |
+| **Honest types** | HTTP client methods return `Promise<unknown>`, not `Promise<T>`. No `as T` casts on JSON.parse. The type system never lies about response shapes. |
+
+---
+
+## Access & Collaboration
+
+This is a **private repository**. Access is by invitation only, controlled by Elite DCs, LLC.
+
+### For the Repo Owner (granting access)
+
+1. Get the person's **GitHub username** (they need a free GitHub account at [github.com](https://github.com))
+2. Go to [github.com/drjerryrelth/ghl-command-mcp/settings/access](https://github.com/drjerryrelth/ghl-command-mcp/settings/access)
+3. Click **Add people**
+4. Enter their GitHub username or email
+5. Set role:
+   - **Read** — for customers (can pull updates, cannot push)
+   - **Write** — for contributors (can push branches and open PRs)
+6. Click **Add** — they'll receive an email invitation
+
+> **Security:** Customers get **Read-only** access. Contributors get **Write** access to push branches and open PRs, but should never push directly to `main`. Use branch protection rules to enforce this.
+
+### For Contributors (first-time setup)
+
+**Step 1:** Accept the GitHub invitation from `drjerryrelth` (check your email).
+
+**Step 2:** Follow **Path 2 (Manual Install)** in the Quick Start section above. You'll need your own GHL API key.
+
+**Step 3:** Read **[CONTRIBUTING.md](CONTRIBUTING.md)** for branching conventions, how to add tools, and PR guidelines.
+
+**Step 4:** Create a branch, make your changes, and open a PR against `main`.
+
+### For Customers / Invited Users (first-time setup)
+
+**Step 1:** Accept the GitHub invitation from `drjerryrelth` (check your email).
+
+**Step 2:** Follow **Path 1 (Easy Install)** or **Path 2 (Manual Install)** in the Quick Start section above. You'll need your own GHL API key — each user connects to their own GHL account.
+
+**Step 3:** Restart Claude Code and test with `"List my contacts"`
+
+> **Note:** You have read-only access. You can clone and pull updates, but cannot push changes to the repository.
+
+### Staying Up to Date
+
+```bash
+cd ghl-command-mcp
+git pull
+npm run build
+```
+
+Then restart Claude Code. Your settings and API key stay the same.
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `GHL_API_KEY` | Yes | Your GHL Private Integration API key. **Must be created inside the sub-account you're connecting to** (not at the agency level). Can only be copied once at creation. |
+| `GHL_LOCATION_ID` | No | Default sub-account ID. **Must match the sub-account where you created the API key.** Saves you from passing it with every tool call. |
+| `GHL_USER_ID` | No* | Your GHL user ID. Required for workflow builder tools. |
+| `GHL_FIREBASE_API_KEY` | No* | Firebase API key from GHL's auth system. Required for workflow builder tools. |
+| `GHL_FIREBASE_REFRESH_TOKEN` | No* | Firebase refresh token. Required for workflow builder tools. May rotate periodically. |
+
+*Required only for the workflow builder (internal API) tools. The standard API tools work without these.
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|---|---|---|
+| MCP tools don't appear (CLI) | Server not registered | Run `claude mcp add --scope user -t stdio ghl /path/to/start-mcp.sh` |
+| MCP tools don't appear (CLI) | Wrong config file | Must be in `~/.claude.json` (via `claude mcp add`), NOT `~/.claude/mcp.json` |
+| MCP tools don't appear (Desktop App) | Config missing or wrong | Check `~/Library/Application Support/Claude/claude_desktop_config.json` has a `ghl` entry under `mcpServers` |
+| MCP tools don't appear (Desktop App) | App not restarted | Quit the Claude app completely (Cmd+Q on Mac) and reopen it |
+| MCP tools don't appear (Desktop App) | Wrong node path | Make sure `"command": "node"` works in your terminal. If not, use the full path (e.g., `/usr/local/bin/node`) |
+| `GHL_API_KEY environment variable is required` | Missing API key | Set it in `start-mcp.sh` or `.env` file |
+| `locationId is required` | Tool needs a location ID | Set `GHL_LOCATION_ID` in your env, or tell Claude which location to use |
+| `GHL API Error 401` | Invalid or expired key | Generate a new API key in GHL > Settings > Integrations |
+| `GHL API Error 403` | Key from wrong sub-account | Create a new Private Integration **inside the correct sub-account** |
+| `GHL API Error 403` (alt) | Missing permission scope | Edit your Private Integration in GHL and enable the required scope |
+| `GHL API Error 422` | Invalid request data | Check the error message for which field is wrong |
+| `GHL API Error 429` | Rate limited | Wait a moment and retry |
+
+---
+
+## About
+
+Built by **[Elite DCs, LLC](https://elitedcs.com)** — a digital marketing and automation agency specializing in GoHighLevel implementations for healthcare practices and local businesses.
+
+**Tech stack:** TypeScript, Node.js, esbuild, MCP SDK, Zod, GHL API v2, Firebase Auth
+
+**Version:** 2.3.0
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for full text.
+
+Copyright (c) 2026 Elite DCs, LLC. All rights reserved.