@elitedcs/ghl-mcp 3.5.1 → 3.6.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 3.6.0 — `build_goal_event` (closes Don-e's last open complaint)
+
+**177 tools across 38 modules. Bundle: 281.9 KB.**
+
+Goal-event support, end-to-end. Don-e flagged on May 4 that the MCP couldn't read or edit goal events. v3.1.0's permissive schema fixed the read side. v3.6.0 fixes the build side.
+
+### `build_goal_event` tool (NEW)
+A high-level helper that emits a correctly-shaped `workflow_goal` node — same pattern as `build_if_else_branch`. Takes a goal condition, optional extras, and an action mode (exit / continue / goto). Returns a single node JSON ready to insert into your actions array.
+
+Example:
+```
+build_goal_event(
+  goal_condition: "review_request_clicked",
+  extras: { reviewTypes: ["sms", "email"], reviewLinkId: "" },
+  action: "exit",
+)
+```
+
+### Goal events explained
+Goal events sit inline in the workflow's action chain — they're NOT branching nodes. The previous action's `next` points to the goal node, and the goal node itself has no `next`. When the goal condition fires during workflow execution (e.g., a contact clicks a review request link), the configured action runs:
+- `exit` — terminates this workflow path (verified)
+- `continue` — passes through to a downstream node (schema accepts but not yet captured from UI)
+- `goto` — jumps to a specific action node (requires `target_node_id`)
+
+### Verified end-to-end
+- Built a goal-event node via `build_goal_event` matching Jerry's UI-built sample. **13 of 13 structural checks passed.**
+- Saved it to a fresh workflow in MCP Testing, read back via `get_workflow_full`. **5 of 5 persistence checks passed** — GHL accepted the shape and round-tripped it cleanly.
+- Test workflow cleaned up via `delete_workflow_full`.
+
+### Schema updates
+- `src/workflow-action-types.ts` — added `WorkflowGoalAttributes` interface + `workflow_goal` variant in the discriminated union (was previously caught by the catch-all fallback)
+- `templates/action-schemas.json` — added a `workflow_goal` entry with the canonical shape, notes, and a pointer to the builder
+- `update_workflow_actions` description updated to mention `workflow_goal` + `build_goal_event`
+
+### Honest scoping
+Only one `goal_condition` value is currently verified end-to-end: `review_request_clicked`. GHL's UI exposes others (tag-based, appointment-based, etc.) — those pass through the builder via the permissive `goal_condition: string` parameter but haven't been captured as specific cases. A future patch can add named helpers / enum values per goal_condition type when more samples are captured.
+
+### Files changed
+- `src/tools/workflow-builder.ts` — `build_goal_event` tool; `update_workflow_actions` description refresh
+- `src/workflow-action-types.ts` — new `WorkflowGoalAttributes` + union variant
+- `templates/action-schemas.json` — `workflow_goal` reference entry
+
 ## 3.5.1 — doc-string accuracy
 
 **176 tools across 38 modules. Bundle: 278.7 KB.**

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**Full GoHighLevel API access for Claude.** 176 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.
+**Full GoHighLevel API access for Claude.** 177 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 168 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 169 tools are now unlocked.
 
 ### 4. Try it
 
@@ -138,7 +138,7 @@ https://app.gohighlevel.com/v2/location/YOUR_LOCATION_ID/dashboard
 
 ## Enable Workflow Builder (Optional)
 
-The 8 workflow builder tools use GHL'''s internal API and require Firebase credentials. Without them, the other 168 tools work fine — you just won'''t have workflow editing.
+The 9 workflow builder tools use GHL'''s internal API and require Firebase credentials. Without them, the other 168 tools work fine — you just won'''t have workflow editing.
 
 Grab the three values from your GHL browser session, then re-run `setup_ghl_mcp` with them:
 
@@ -167,9 +167,9 @@ Re-run setup_ghl_mcp with workflow builder:
 
 ---
 
-## Tools (176)
+## Tools (177)
 
-> **v3.5.0 adds `enable_workflow_builder`** — a one-call upgrade path for adding Firebase credentials to an existing install. Buyers who skip Firebase on day one can now add it later without re-entering license / API key / location ID. Reads existing credentials, validates Firebase, merges, writes back.
+> **v3.6.0 adds `build_goal_event`** — a high-level helper that emits a correctly-shaped GHL workflow goal-event node. Goal events sit inline in the action chain and terminate (or jump) the workflow when their condition fires. Closes Don-e's last open complaint from May 4 — Claude can now both READ and BUILD goal events end-to-end.
 
 ### CRM & Contacts (15 tools)
 
@@ -334,7 +334,7 @@ Re-run setup_ghl_mcp with workflow builder:
 | `get_subscriptions` | List active subscriptions |
 | `get_transactions` | View transaction history |
 
-### Workflow Builder (8 tools) — Internal API
+### Workflow Builder (9 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).
 
@@ -348,10 +348,11 @@ Re-run setup_ghl_mcp with workflow builder:
 | `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 |
 | `validate_workflow` | Pre-flight validation: scans every action and trigger for references to pipelines, stages, custom fields, users, and other workflows; verifies each ID exists. Catches the silent-failure bug where invalid IDs make GHL skip subsequent actions |
+| `build_goal_event` | Build a correctly-shaped goal-event node. Goals sit inline in the action chain — when the goal condition fires (e.g., review_request_clicked), the configured action runs (default: exit the workflow). Returns a `workflow_goal` node ready to wire into your actions array |
 
-**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.
+**What you can build:** Complete automation sequences — lead nurture drip campaigns, appointment reminder sequences, onboarding flows, re-engagement workflows, internal notification chains, **conditional exit workflows with goal events**. 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 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`, **`workflow_goal`**, and more.
 
 **Supported trigger types:** **All 57 native GHL trigger types are deeply typed** with their own Zod variant. 42 have full field-path documentation (`opportunity_*`, `form_submission`, `contact_changed`, `survey_submission`, `birthday_reminder`, `mailgun_email_event`, and 36 others). 4 have partial docs, 2 are fieldless by design, 9 have type-only discrimination pending field-path capture. A permissive fallback handles any future trigger types GHL ships, so reads never crash. Plus 434 marketplace trigger entries across 85 third-party apps — query them via `get_trigger_registry`.
 
@@ -419,7 +420,7 @@ Re-run setup_ghl_mcp with workflow builder:
 |---|---|
 | `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. |
 | `health_check` | Run a full health check: npm registry + version status, GHL API key validity, default location reachability, Firebase auth status, token registry presence. Use when something feels broken. |
-| `enable_workflow_builder` | Add Firebase credentials to an existing install to unlock the 8 workflow builder tools. No need to re-enter license / API key / location ID. Run this any time after the basic setup, on the buyer's schedule. |
+| `enable_workflow_builder` | Add Firebase credentials to an existing install to unlock the 9 workflow builder tools. No need to re-enter license / API key / location ID. Run this any time after the basic setup, on the buyer's schedule. |
 
 ### Other Modules
 

package/dist/index.js

@@ -31,8 +31,8 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.5.1",
-      description: "GoHighLevel MCP Server for Claude. 176 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
+      version: "3.6.0",
+      description: "GoHighLevel MCP Server for Claude. 177 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
       main: "dist/index.js",
       bin: {
         "ghl-mcp": "dist/index.js"
@@ -4137,7 +4137,7 @@ function registerWorkflowBuilderTools(server2, client) {
   );
   server2.tool(
     "update_workflow_actions",
-    "Update a workflow's actions (steps), triggers, name, or status. IMPORTANT: Call get_workflow_full first to see the current state before updating. Handles version tracking automatically. Uses the internal builder API (requires Firebase auth). Action types: sms, email, add_contact_tag, remove_contact_tag, wait, webhook, internal_update_opportunity, custom_code, update_contact_field, add_notes, internal_notification, task_notification, remove_from_workflow, add_to_workflow, goto, transition. For if/else, call build_if_else_branch and include its returned nodes; if_else is a node discriminator, not a standalone action. Trigger types: customer_reply, appointment, contact_tag, and pipeline_stage_updated have typed validation. Any other GHL trigger type (form_submitted, opportunity_created, payment_received, inbound_webhook, etc.) passes through with a permissive schema \u2014 the payload reaches GHL untouched.",
+    "Update a workflow's actions (steps), triggers, name, or status. IMPORTANT: Call get_workflow_full first to see the current state before updating. Handles version tracking automatically. Uses the internal builder API (requires Firebase auth). Action types: sms, email, add_contact_tag, remove_contact_tag, wait, webhook, internal_update_opportunity, custom_code, update_contact_field, add_notes, internal_notification, task_notification, remove_from_workflow, add_to_workflow, goto, transition, workflow_goal. For if/else, call build_if_else_branch and include its returned nodes; if_else is a node discriminator, not a standalone action. For goal events (exit-on-condition nodes), call build_goal_event to get a correctly-shaped workflow_goal node \u2014 wire it in by setting the prior action's `next` to the goal node's id. Trigger types: all 57 native GHL trigger types have typed validation; any unknown trigger type passes through via a permissive fallback so reads never crash.",
     {
       workflowId: import_zod31.z.string().describe("The workflow ID to update."),
       name: import_zod31.z.string().optional().describe("New workflow name."),
@@ -4298,6 +4298,53 @@ function registerWorkflowBuilderTools(server2, client) {
       }
     }
   );
+  server2.tool(
+    "build_goal_event",
+    "Build a correctly-shaped GHL workflow goal-event node. Goal events sit inline in the action chain \u2014 when the goal condition fires during workflow execution, the configured action runs (default: exit the workflow). The previous action's `next` should point to the goal node's id; the goal node itself does not have a `next`. Verified goal_condition value (Jerry's UI sample): 'review_request_clicked' with extras { reviewTypes: ['sms', 'email'], reviewLinkId: '' }. Other goal_condition values that GHL ships are passed through verbatim \u2014 the catalogue of all goal conditions has not been fully captured yet, but the schema accepts any string value.",
+    {
+      goal_condition: import_zod31.z.string().describe("The goal-condition identifier \u2014 what the goal is watching for. Verified value: 'review_request_clicked'. Other goal_condition strings that GHL's UI exposes (e.g., tag-related, appointment-related) pass through unchanged."),
+      extras: import_zod31.z.record(import_zod31.z.unknown()).optional().describe("Goal-condition-specific config. Example for review_request_clicked: { reviewTypes: ['sms', 'email'], reviewLinkId: '' }. Pass an empty object {} or omit if the goal_condition has no extras."),
+      action: import_zod31.z.enum(["exit", "continue", "goto"]).default("exit").describe("What happens when the goal fires. 'exit' terminates the workflow path (verified). 'continue' and 'goto' are GHL UI options; 'goto' likely needs an extra targetNodeId field, not yet captured."),
+      target_node_id: import_zod31.z.string().optional().describe("Required when action === 'goto'. The action node id to jump to."),
+      name: import_zod31.z.string().default("Goal").describe("Display name in the GHL UI."),
+      op: import_zod31.z.enum(["or", "and"]).default("or").describe("Top-level boolean operator across segments. Default 'or'."),
+      inner_op: import_zod31.z.enum(["or", "and"]).default("or").describe("Boolean operator across conditions within a single segment. Default 'or'.")
+    },
+    async ({ goal_condition, extras, action, target_node_id, name, op, inner_op }) => {
+      try {
+        if (action === "goto" && !target_node_id) {
+          throw new Error("action='goto' requires target_node_id to identify which workflow action to jump to.");
+        }
+        const nodeId = crypto.randomUUID();
+        const conditionId = crypto.randomUUID();
+        const attributes = {
+          op,
+          segments: [{
+            op: inner_op,
+            conditions: [{
+              goal_condition,
+              extras: extras ?? {},
+              id: conditionId
+            }]
+          }],
+          type: "workflow_goal",
+          action
+        };
+        if (action === "goto" && target_node_id) {
+          attributes.targetNodeId = target_node_id;
+        }
+        const goalNode = {
+          id: nodeId,
+          name,
+          type: "workflow_goal",
+          attributes
+        };
+        return jsonResponse(goalNode);
+      } catch (error) {
+        return errorResponse(error);
+      }
+    }
+  );
   server2.tool(
     "delete_workflow_full",
     "Permanently delete a workflow. IRREVERSIBLE.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.5.1",
-  "description": "GoHighLevel MCP Server for Claude. 176 tools — full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
+  "version": "3.6.0",
+  "description": "GoHighLevel MCP Server for Claude. 177 tools — full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
   "main": "dist/index.js",
   "bin": {
     "ghl-mcp": "dist/index.js"

package/templates/action-schemas.json

@@ -247,6 +247,33 @@
     "branch_notes": "Branch nodes need BOTH parentKey AND parent (same value). Sibling arrays cross-reference the other branch. Condition node next points to [YES, NO]. Branch node next is a string to the first child when non-empty. CAUTION: Complex branching (>2 if/else in one workflow) can freeze GHL's UI renderer. Use separate exit workflows for nurture sequences instead."
   },
 
+  "workflow_goal": {
+    "example": {
+      "id": "<UUID>",
+      "name": "Goal",
+      "type": "workflow_goal",
+      "attributes": {
+        "op": "or",
+        "segments": [
+          {
+            "op": "or",
+            "conditions": [
+              {
+                "goal_condition": "review_request_clicked",
+                "extras": { "reviewTypes": ["sms", "email"], "reviewLinkId": "" },
+                "id": "<UUID>"
+              }
+            ]
+          }
+        ],
+        "type": "workflow_goal",
+        "action": "exit"
+      }
+    },
+    "notes": "Goal-event nodes sit inline in the action chain — when the goal condition fires during workflow execution, the configured action runs (default: 'exit' terminates the workflow path). The previous action's `next` should point to the goal node's id; the goal node itself does NOT have a `next` field. Use build_goal_event to construct the node — it handles UUID generation and the nested op/segments/conditions shape. Verified goal_condition value: 'review_request_clicked' (with extras { reviewTypes: ['sms', 'email'], reviewLinkId: '' }). Other goal_condition strings from GHL's UI pass through verbatim; the full catalogue of goal conditions has not been captured yet.",
+    "build_helper": "build_goal_event(goal_condition, extras?, action='exit', target_node_id?, name='Goal', op='or', inner_op='or')"
+  },
+
   "_trigger_patterns": {
     "real_shape": {
       "id": "<UUID>",