@elitedcs/ghl-mcp 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+## 3.2.0 — Deep trigger typing
+
+**173 tools across 36 modules. Bundle: 248.4 KB.**
+
+v3.1.0 made all 57 native trigger types READ cleanly via a permissive fallback. v3.2.0 deeply types 9 more of the most common ones — `form_submission`, `opportunity_created`, `opportunity_changed`, `opportunity_status_changed`, `payment_received`, `inbound_webhook`, `mailgun_email_event`, `note_add`, `task_added` — bringing typed coverage from **4 / 57 (7%) to 13 / 57 (23%)**.
+
+For Claude that means: when you ask it to read, build, or edit a workflow using one of these triggers, it now knows the discriminated trigger type AND the field paths each one supports (e.g., `opportunity.pipelineId`, `opportunity.monetaryValue`, `form.id`, `mailgun.event`, etc.). Less guessing, fewer rejected payloads.
+
+### Shared trigger-schema module
+- `src/trigger-schemas.ts` (NEW): single source of truth for `WorkflowTriggerSchema`. Both the read path (`workflow-builder-client.ts`) and the write path (`tools/workflow-builder.ts`) now import from this module instead of duplicating definitions.
+- Bundle shrank from 249.7 KB → 248.4 KB thanks to the dedup.
+
+### Field paths documented per trigger
+- Each typed trigger's `field` is `z.string()` with a `.describe()` listing the known field paths (extracted from `templates/trigger-schemas.json`, captured 2026-05-14). Permissive enough that new GHL fields don't crash reads, structured enough that the LLM knows what fields exist.
+
+### Coverage delta
+| State | Typed | Reachable-but-untyped | Total |
+|---|---:|---:|---:|
+| Before v3.1.0 | 4 | 0 (reads crashed) | 57 |
+| v3.1.0 | 4 | 53 | 57 |
+| v3.2.0 | **13** | **44** | 57 |
+
+### Round-trip verified
+- Real `form_submission` workflow from QA Test Clinic v3 parses cleanly through the new typed variant.
+- 8 synthetic typed-trigger samples match their respective variants and are correctly rejected by sibling variants (discrimination works as expected).
+
+### Files changed
+- `src/trigger-schemas.ts` — NEW: 13 typed trigger variants + `UnknownTriggerSchema` fallback in a single module.
+- `src/workflow-builder-client.ts` — removed inline trigger schemas, imports from shared module.
+- `src/tools/workflow-builder.ts` — removed inline trigger schemas, imports from shared module.
+
+## 3.1.1 — Auto-update visibility
+
+**173 tools across 36 modules. Bundle: 249.7 KB.**
+
+The v3.0 install email promises the MCP auto-updates on Claude restart, and it does. But the old `checkForUpdates()` only worked for local git-checkout dev installs — for buyers running `npx -y @elitedcs/ghl-mcp@latest` it silently returned. This release makes the upgrade visible and verifiable.
+
+### `checkForUpdates` rewritten for the npm install path
+- Queries `registry.npmjs.org/@elitedcs/ghl-mcp/latest` instead of running `git fetch`.
+- Writes a clear stderr line when a newer version is available: `Update available: vX → vY. Fully quit Claude (Cmd+Q on Mac) and reopen to upgrade.`
+- 5 s timeout, non-blocking.
+
+### `get_mcp_version` tool (NEW)
+- Returns installed version, latest published version on npm, and the one-line restart instruction if not current.
+- Registered in BOTH bootstrap and normal modes — buyers without configured GHL credentials can still verify their MCP version.
+- Use case: "Hey Claude, check your version" → instant confirmation an upgrade landed.
+
+### Version baked into `get_current_location`
+- Adds `MCP version: vX.Y.Z` line to the response so the version surfaces naturally on the first GHL tool call of a session, no separate query needed.
+
+### Files changed
+- `src/index.ts` — replaced git-based update check with npm registry check; registers meta tools in both modes; threads version into `registerAllTools`.
+- `src/version-check.ts` — NEW: shared `fetchLatestVersion()` + `getVersionStatus()` used by startup banner and the tool.
+- `src/tools/meta.ts` — NEW: `get_mcp_version` tool.
+- `src/tools/index.ts` — `registerAllTools` accepts optional `mcpVersion` and threads it to the location switcher.
+- `src/tools/location-switcher.ts` — appends `MCP version: vX.Y.Z` to `get_current_location` response.
+
+## 3.1.0 — Workflow trigger read-side coverage
+
+**172 tools across 35 modules.**
+
+GHL ships 57 native trigger types. The MCP previously typed only 4 (`customer_reply`, `appointment`, `contact_tag`, `pipeline_stage_updated`). Workflows using any of the other 53 — `form_submission`, `payment_received`, `opportunity_*`, `inbound_webhook`, etc. — threw Zod errors on `get_workflow_full`. This release unlocks all of them on the read side.
+
+### Permissive `WorkflowTriggerSchema`
+- `z.union` of the 4 typed variants plus an `UnknownTriggerSchema` fallback that accepts any string-keyed `type` and a `conditions` array of arbitrary records.
+- Write side is unchanged — typed triggers still get their typed conditions; unknown triggers pass through untouched on save.
+- Defined in BOTH `src/workflow-builder-client.ts` and `src/tools/workflow-builder.ts` (read path + tool input schema).
+
+### `get_trigger_registry` tool (NEW)
+- Calls GHL's marketplace endpoint `/marketplace/core/search/module?type=triggers` and returns ~85 third-party apps (Zoom, WooCommerce, Shopify, Monday, etc.) with their available triggers and `customVars`.
+- Use case: discovering which marketplace triggers a sub-account can wire into workflows.
+- `installedOnly` flag defaults to false (full catalogue).
+
+### `templates/trigger-schemas.json` reference (dev-side)
+- Full catalogue: 57 native trigger types + 85 marketplace apps + 434 marketplace trigger entries, captured from the workflow-builder JS bundle + the marketplace API.
+- Not shipped to npm consumers (excluded from `package.json` `files[]`) — kept in-repo as the source of truth for future typed-trigger work.
+
+### Coverage delta
+- Before: 4 / 57 native trigger types typed (7%).
+- After: 4 typed + 53 reachable via the permissive fallback (100% read coverage).
+
 ## 2.7.0 — Complete Type Safety (Boris Cherny A+)
 
 **171 tools across 35 modules. Bundle: 214KB.**

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel 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.
+**Full GoHighLevel API access for Claude.** 173 tools across 36 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.
 
 **Distributed via npm as [`@elitedcs/ghl-mcp`](https://www.npmjs.com/package/@elitedcs/ghl-mcp).** Buyers install with one config block — no git, no Node.js setup, no terminal commands. Updates flow automatically (`npx @latest` re-resolves on every Claude restart).
 
@@ -98,7 +98,7 @@ Run setup_ghl_mcp to activate GHL Command:
   ghl_location_id: YOUR_LOCATION_ID
 ```
 
-Approve the tool call. Server validates your license, verifies your GHL credentials, writes them to a per-user config file. **Quit Claude one more time and reopen** — all 165 tools are now unlocked.
+Approve the tool call. Server validates your license, verifies your GHL credentials, writes them to a per-user config file. **Quit Claude one more time and reopen** — all 166 tools are now unlocked.
 
 ### 4. Try it
 
@@ -138,9 +138,19 @@ https://app.gohighlevel.com/v2/location/YOUR_LOCATION_ID/dashboard
 
 ## Enable Workflow Builder (Optional)
 
-The 6 workflow builder tools use GHL'''s internal API and require Firebase credentials. Without them, the other 165 tools work fine — you just won'''t have workflow editing.
+The 7 workflow builder tools use GHL'''s internal API and require Firebase credentials. Without them, the other 166 tools work fine — you just won'''t have workflow editing.
 
-**The easy way:** [elitedcs.com/ghl-mcp-firebase](https://elitedcs.com/ghl-mcp-firebase) — drag the bookmarklet, click it inside GHL, your three values appear automatically. Then re-run `setup_ghl_mcp` with the extra fields:
+Grab the three values from your GHL browser session, then re-run `setup_ghl_mcp` with them:
+
+1. Open `app.gohighlevel.com` in Chrome (or any Chromium browser), log in.
+2. Open DevTools (Cmd+Opt+I on Mac, F12 on Windows) → **Application** tab → **IndexedDB** in the left panel.
+3. Expand: `firebaseLocalStorageDb` → `firebaseLocalStorage`.
+4. Find the row whose key starts with `firebase:authUser:`.
+5. The part between `authUser:` and `:[DEFAULT]` is your **ghl_firebase_api_key** (starts with `AIza`).
+6. Inside that row's value object: `uid` is your **ghl_user_id**.
+7. Inside `value.stsTokenManager.refreshToken` is your **ghl_firebase_refresh_token**.
+
+Then in Claude:
 
 ```
 Re-run setup_ghl_mcp with workflow builder:
@@ -148,16 +158,16 @@ Re-run setup_ghl_mcp with workflow builder:
   license_key: YOUR_LICENSE_KEY
   ghl_api_key: YOUR_GHL_API_KEY
   ghl_location_id: YOUR_LOCATION_ID
-  ghl_user_id: FROM_FIREBASE_CAPTURE
-  ghl_firebase_api_key: FROM_FIREBASE_CAPTURE
-  ghl_firebase_refresh_token: FROM_FIREBASE_CAPTURE
+  ghl_user_id: FROM_STEP_6
+  ghl_firebase_api_key: FROM_STEP_5
+  ghl_firebase_refresh_token: FROM_STEP_7
 ```
 
-> Firebase refresh tokens can rotate. If workflow tools stop working after a few weeks, run the capture again and re-run setup_ghl_mcp with the fresh values.
+> Firebase refresh tokens can rotate. If workflow tools stop working after a few weeks, repeat steps 1–7 and re-run setup_ghl_mcp with fresh values.
 
 ---
 
-## Tools (171)
+## Tools (173)
 
 ### CRM & Contacts (15 tools)
 
@@ -322,7 +332,7 @@ Re-run setup_ghl_mcp with workflow builder:
 | `get_subscriptions` | List active subscriptions |
 | `get_transactions` | View transaction history |
 
-### Workflow Builder (6 tools) — Internal API
+### Workflow Builder (7 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).
 
@@ -334,12 +344,13 @@ Re-run setup_ghl_mcp with workflow builder:
 | `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 |
+| `get_trigger_registry` | Discover GHL's marketplace trigger apps (Zoom, WooCommerce, Shopify, etc.) and their available trigger templates |
 
 **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.
+**Supported trigger types:** All 57 native GHL trigger types read cleanly. **13 are deeply typed** with documented field paths (contact_tag, customer_reply, appointment, pipeline_stage_updated, form_submission, opportunity_created, opportunity_changed, opportunity_status_changed, payment_received, inbound_webhook, mailgun_email_event, note_add, task_added). The other 44 pass through a permissive schema so workflows never fail to read regardless of trigger type. Plus 434 marketplace trigger entries across 85 third-party apps — query them via `get_trigger_registry`.
 
 ### Pipeline Builder (5 tools) — Internal API
 
@@ -399,6 +410,12 @@ Re-run setup_ghl_mcp with workflow builder:
 | `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. |
 
+### Meta (1 tool)
+
+| Tool | What It Does |
+|---|---|
+| `get_mcp_version` | Check installed version against the latest published to npm. Confirms an upgrade landed after restarting Claude. Available even before GHL credentials are configured. |
+
 ### Other Modules
 
 | Module | Tools | What It Does |