@elitedcs/ghl-mcp 3.69.0 → 3.71.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 3.71.0 — a task you can close
+
+A subscriber's Claude created a callback task on a contact and, come Monday, could not
+close it. It said so plainly: the server can create tasks but has no way to update or
+complete one, tick it off by hand. It was right. `create_contact_task` and
+`get_contact_tasks` were the whole task surface.
+
+**Three tools close the loop.** `complete_contact_task` marks a task done, or reopens it
+with `completed: false`. `update_contact_task` changes a task's title, description, due
+date, assignee or completed state, and sends only the fields you pass, so changing a due
+date never blanks the title; an update with no fields is refused before any request goes
+out. `delete_contact_task` removes a task for good and, like every delete in this server,
+asks for `confirm: "DELETE"`. All three use the routes in
+GoHighLevel's published contacts spec and were proven live before release on a throwaway
+contact in a sandbox account: create, complete, read back completed, update, reopen,
+delete, read back gone, contact removed (`docs/proofs/2026-08-26-task-lifecycle.md`).
+
+Counts: 245 tools across 51 modules (was 242). The free read-only tier is unchanged at
+111; the three new tools are writes and answer with upgrade information there. Restart
+Claude after the update to see them.
+
+## 3.70.0 — a clean validation now means something
+
+A subscriber built an Instagram-comment-to-DM workflow, ran `validate_workflow`, got
+back "0 issues, 0 warnings", published it, and watched the Create/Update Opportunity
+step do nothing: no card in the pipeline, no card on the contact, and the workflow
+carried on to the next step as if it had worked. They were right about why. The step
+had only a pipeline and a stage. GoHighLevel's own documentation lists Opportunity
+Name, Source and Status as mandatory for the combined Create/Update Opportunity step
+to create anything; with only pipeline and stage it moves a card the contact already
+has, and a brand-new lead has none. The
+validator was checking that every id existed. It never asked whether the step could
+do what its name says.
+
+**`validate_workflow` and `audit_workflows` now check what a step can do.** A
+Create/Update Opportunity step with only pipeline + stage and no opportunity in
+context comes back as a warning that says exactly that and names the fix. "In
+context" is worked out from the workflow itself: a create step earlier on the same
+path, a Find Opportunity step whose "Opportunity Found" branch the step sits in, or a
+trigger that fires on an opportunity. A step that carries an Opportunity Name and a
+Status is taken as one that creates and is left alone; a Name with no Status is
+reported as unverified with the thing to check. Before release the check ran against
+every workflow in five of our own accounts (106 workflows) and flagged none; the run
+is recorded in `docs/proofs/2026-08-26-validate-runtime-noop.md`. A path the validator
+cannot trace, or a field this version does not know, is reported as unverified rather
+than passed. `warnings_count` now includes these findings, the report says how many
+steps were checked (`actions_checked`), and `audit_workflows` lists them under
+`shape_warnings` with counts in its summary; `status` still flips only on an error,
+never on a warning. A `task_notification` step spelled with the underscore, which
+saves, validates and is skipped at runtime, is that kind of error now.
+
+**Claude now builds the right node.** GoHighLevel has separated Create Opportunity
+from Update Opportunity and is phasing the combined action out for new workflows. The
+builder knows the newer Create Opportunity node (`internal_create_opportunity`),
+validates it, normalizes it to the shape proven to create a card, and the reference
+material Claude reads before building a workflow now says which node creates a card
+and which one moves it, instead of pointing both jobs at the same node. (#57)
+
 ## 3.69.0 — the cockpit hardened, and the plan you approved is the plan that runs
 
 Two items in this release exist because someone tried to break the cockpit

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**Full GoHighLevel API access for Claude.** 242 tools across 51 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. **Multi-tenant:** one install can run the workflow builder across multiple clients' GHL accounts.
+**Full GoHighLevel API access for Claude.** 245 tools across 51 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. **Multi-tenant:** one install can run the workflow builder across multiple clients' GHL accounts.
 
 **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).
 
@@ -135,7 +135,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** — the full core toolset is now unlocked (242 tools total with the optional Workflow Builder Firebase add-on).
+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** — the full core toolset is now unlocked (245 tools total with the optional Workflow Builder Firebase add-on).
 
 ### 4. Try it
 
@@ -175,7 +175,7 @@ https://app.gohighlevel.com/v2/location/YOUR_LOCATION_ID/dashboard
 
 ## Enable the Workflow Builder
 
-The builder + cloner + validator tools (workflow builder, funnel builder, form builder, pipeline builder, workflow cloner, validate_workflow) use GHL's internal API and require Firebase credentials. Without them, the other 187 tools work fine — you just won't have workflow/funnel/form/pipeline editing. This is the flagship feature: do this step.
+The builder + cloner + validator tools (workflow builder, funnel builder, form builder, pipeline builder, workflow cloner, validate_workflow) use GHL's internal API and require Firebase credentials. Without them, the other 190 tools work fine — you just won't have workflow/funnel/form/pipeline editing. This is the flagship feature: do this step.
 
 **One-click capture (v3.49.0+, the supported path):**
 
@@ -269,7 +269,7 @@ Highlights (full guide: [`docs/HEADLESS.md`](docs/HEADLESS.md)):
 
 > **v3.10.0 adds Email Templates** (`list_email_templates`, `create_email_template`, `update_email_template`) — Claude can now create new HTML email templates and save content into them via the public API. Templates power both standalone marketing emails and workflow email actions. Delete + rename remain UI-only (no public-API endpoint exists).
 
-### CRM & Contacts (15 tools)
+### CRM & Contacts (18 tools)
 
 | Tool | What It Does |
 |---|---|
@@ -283,6 +283,9 @@ Highlights (full guide: [`docs/HEADLESS.md`](docs/HEADLESS.md)):
 | `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 |
+| `complete_contact_task` | Mark a task done (or reopen it) |
+| `update_contact_task` | Change a task's title, description, due date, assignee or state |
+| `delete_contact_task` | Delete a task from 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 |
@@ -798,7 +801,7 @@ Source repo is private. Contributors need an invitation from `drjerryrelth`. The
 
 ### Reducing context / token usage
 
-Every registered MCP tool's schema is shipped to the model on every message. With 242 tools that's a meaningful per-message context cost even in chats that never touch GHL. If you only use a slice of GHL Command, restrict the tool surface with `GHL_ENABLED_MODULES` and/or `GHL_ENABLED_TOOLS`:
+Every registered MCP tool's schema is shipped to the model on every message. With 245 tools that's a meaningful per-message context cost even in chats that never touch GHL. If you only use a slice of GHL Command, restrict the tool surface with `GHL_ENABLED_MODULES` and/or `GHL_ENABLED_TOOLS`:
 
 ```jsonc
 // Claude Desktop config — enable whole modules

package/dist/index.js

@@ -1118,6 +1118,35 @@ function normalizeRemoveFromWorkflowAction(action) {
   }
   return { ...action, attributes: next };
 }
+function normalizeInternalCreateOpportunityAction(action) {
+  if (action.type !== "internal_create_opportunity") return action;
+  const attrIn = action.attributes && typeof action.attributes === "object" ? action.attributes : {};
+  const fieldsIn = Array.isArray(attrIn.__customInputFields__) ? attrIn.__customInputFields__ : [];
+  let pipelineId = typeof attrIn.pipelineId === "string" ? attrIn.pipelineId : void 0;
+  const __customInputFields__ = [];
+  for (const raw of fieldsIn) {
+    const f = raw && typeof raw === "object" ? raw : {};
+    if (f.filterField === "pipelineId") {
+      if (!pipelineId && typeof f.value === "string") pipelineId = f.value;
+      continue;
+    }
+    __customInputFields__.push({
+      ...f,
+      __customInputs__: f.__customInputs__ && typeof f.__customInputs__ === "object" ? f.__customInputs__ : {},
+      dataType: typeof f.dataType === "string" ? f.dataType : "SINGLE_OPTIONS",
+      valueFieldType: typeof f.valueFieldType === "string" ? f.valueFieldType : "select"
+    });
+  }
+  const attributes = {
+    ...attrIn,
+    type: "internal_create_opportunity",
+    ...pipelineId ? { pipelineId } : {},
+    __customInputs__: attrIn.__customInputs__ && typeof attrIn.__customInputs__ === "object" ? attrIn.__customInputs__ : {},
+    __customInputFields__
+  };
+  delete attributes.workflowsActionType;
+  return { ...action, workflowsActionType: "INTERNAL", attributes };
+}
 function normalizeInternalUpdateOpportunityAction(action) {
   if (action.type !== "internal_update_opportunity") return action;
   const attrIn = action.attributes && typeof action.attributes === "object" ? action.attributes : {};
@@ -1202,6 +1231,26 @@ function validateActionChain(actions, existingIds) {
         }
         break;
       }
+      case "internal_create_opportunity": {
+        const isRoundTripped = hasId(action) && (existingIds ? existingIds.has(action.id) : true);
+        if (!isRoundTripped) {
+          const cif = Array.isArray(attr.__customInputFields__) ? attr.__customInputFields__ : [];
+          const listed = (ff) => cif.find((f) => f && f.filterField === ff);
+          const pipelineId = typeof attr.pipelineId === "string" ? attr.pipelineId : listed("pipelineId")?.value;
+          if (!isIdShaped(pipelineId)) {
+            throw new Error(
+              `Create opportunity action "${action.name}" needs a valid 'pipelineId' (an id, not a name) in attributes. Use get_pipelines / list_pipelines_full to find it.`
+            );
+          }
+          const stage = listed("pipelineStageId");
+          if (!stage || !isIdShaped(stage.value)) {
+            throw new Error(
+              `Create opportunity action "${action.name}" needs a valid pipelineStageId entry (an id, not a name) in '__customInputFields__'. Use get_pipelines / list_pipelines_full to find the IDs. (A missing or non-existent id makes GHL silently fail this action and can kill the rest.)`
+            );
+          }
+        }
+        break;
+      }
       case "remove_from_workflow":
         if (!attr.workflowId || !Array.isArray(attr.workflow_id)) throw new Error(`Remove from workflow action "${action.name}" needs BOTH 'workflowId' string AND 'workflow_id' array.`);
         break;
@@ -1941,7 +1990,7 @@ ${errorBody}`
        */
       buildActionChain(actions, existingIds) {
         validateActionChain(actions, existingIds);
-        const linked = actions.map(normalizeRemoveFromWorkflowAction).map(normalizeInternalUpdateOpportunityAction).map((action, i) => {
+        const linked = actions.map(normalizeRemoveFromWorkflowAction).map(normalizeInternalUpdateOpportunityAction).map(normalizeInternalCreateOpportunityAction).map((action, i) => {
           const copy = { ...action };
           if (!copy.id) {
             copy.id = crypto.randomUUID();
@@ -2683,6 +2732,15 @@ var init_contact_window = __esm({
 });
 
 // src/tools/contacts.ts
+function buildUpdateTaskBody(input) {
+  const body = {};
+  if (input.title !== void 0) body.title = input.title;
+  if (input.body !== void 0) body.body = input.body;
+  if (input.dueDate !== void 0) body.dueDate = input.dueDate;
+  if (input.completed !== void 0) body.completed = input.completed;
+  if (input.assignedTo !== void 0) body.assignedTo = input.assignedTo;
+  return Object.keys(body).length === 0 ? null : body;
+}
 function registerContactTools(server2, client) {
   safeTool(
     server2,
@@ -2963,6 +3021,57 @@ function registerContactTools(server2, client) {
       });
     }
   );
+  safeTool(
+    server2,
+    "complete_contact_task",
+    "Mark a contact's task as done (or reopen it with completed=false). Find the task ID with get_contact_tasks; create_contact_task also returns it. Use this to tick off a task created earlier.",
+    {
+      contactId: import_zod9.z.string().min(1).describe("The ID of the contact the task belongs to."),
+      taskId: import_zod9.z.string().min(1).describe("The ID of the task (from get_contact_tasks or create_contact_task)."),
+      completed: import_zod9.z.boolean().optional().describe("true (default) marks the task completed; false reopens a completed task.")
+    },
+    async ({ contactId, taskId, completed }) => {
+      return client.put(`/contacts/${contactId}/tasks/${taskId}/completed`, {
+        body: { completed: completed ?? true }
+      });
+    }
+  );
+  safeTool(
+    server2,
+    "update_contact_task",
+    "Change an existing task on a contact: title, description, due date, assignee, or completed state. Only the fields you pass are changed. To simply tick a task off, complete_contact_task is the direct route.",
+    {
+      contactId: import_zod9.z.string().min(1).describe("The ID of the contact the task belongs to."),
+      taskId: import_zod9.z.string().min(1).describe("The ID of the task to update (from get_contact_tasks)."),
+      title: import_zod9.z.string().min(1).optional().describe("New title / summary of the task (cannot be blank)."),
+      body: import_zod9.z.string().optional().describe("New detailed description of the task."),
+      dueDate: import_zod9.z.string().refine((d) => !Number.isNaN(Date.parse(d)), "dueDate must be an ISO 8601 date or date-time").optional().describe("New due date in ISO 8601 format (e.g. 2026-08-31T16:00:00.000Z)."),
+      completed: import_zod9.z.boolean().optional().describe("Set the completed state of the task."),
+      assignedTo: import_zod9.z.string().optional().describe("User ID to reassign the task to.")
+    },
+    async ({ contactId, taskId, title, body: taskBody, dueDate, completed, assignedTo }) => {
+      const reqBody = buildUpdateTaskBody({ title, body: taskBody, dueDate, completed, assignedTo });
+      if (!reqBody) {
+        throw new Error(
+          "Nothing to update: pass at least one of title, body, dueDate, completed, assignedTo."
+        );
+      }
+      return client.put(`/contacts/${contactId}/tasks/${taskId}`, { body: reqBody });
+    }
+  );
+  safeTool(
+    server2,
+    "delete_contact_task",
+    "Delete a task from a contact. Permanent. To keep the record and just close it, use complete_contact_task instead.",
+    {
+      contactId: import_zod9.z.string().min(1).describe("The ID of the contact the task belongs to."),
+      taskId: import_zod9.z.string().min(1).describe("The ID of the task to delete (from get_contact_tasks)."),
+      confirm: import_zod9.z.literal("DELETE").describe("Must pass 'DELETE' to confirm this destructive action.")
+    },
+    async ({ contactId, taskId }) => {
+      return client.delete(`/contacts/${contactId}/tasks/${taskId}`);
+    }
+  );
   safeTool(
     server2,
     "get_contact_notes",
@@ -9748,7 +9857,7 @@ Note: Firebase credentials rejected (${fb.error}).`;
       const telemetryLine = telemetryDisabled(process.env) ? "" : `
 
 ${TELEMETRY_DISCLOSURE}`;
-      const finishedCount = isFree ? "111" : "242";
+      const finishedCount = isFree ? "111" : "245";
       const freeTip = isFree ? `
 
 Free tier: read-only. Write tools stay visible but answer with upgrade info instead of acting. Full version ($97/mo founding rate) upgrades in place \u2014 same install, you only swap the license key: https://ghlcommand.com` : "";
@@ -9793,7 +9902,7 @@ Free tier: read-only. Write tools stay visible but answer with upgrade info inst
 function registerEnableWorkflowBuilderTool(server2) {
   server2.tool(
     "enable_workflow_builder",
-    "Add Firebase credentials to an existing GHL Command install to unlock 55 additional tools across the internal-API modules: workflow builder (create/edit/clone/delete/publish/validate workflows, build_if_else_branch, build_goal_event, get_trigger_registry), funnel + page builder, form builder, pipeline builder, workflow cloner, smart lists, reputation, email campaigns, email templates, and memberships, plus the pre-deploy validator. On the FREE tier this same login unlocks the read-only auditor suite (audit_workflows, validate_workflow, full-detail workflow/funnel/pipeline reads). Requires you've already run setup_ghl_mcp. EASIEST PATH: run `capture_firebase_interactive` instead \u2014 a Chrome window opens, you log into GHL, zero pasting. Use THIS tool when you have JSON from `auto_capture_firebase_script` (console-paste path) to put in `firebase_paste`, or the three manual DevTools fields. Tool count goes from 187 to 242 after the next Claude restart.",
+    "Add Firebase credentials to an existing GHL Command install to unlock 55 additional tools across the internal-API modules: workflow builder (create/edit/clone/delete/publish/validate workflows, build_if_else_branch, build_goal_event, get_trigger_registry), funnel + page builder, form builder, pipeline builder, workflow cloner, smart lists, reputation, email campaigns, email templates, and memberships, plus the pre-deploy validator. On the FREE tier this same login unlocks the read-only auditor suite (audit_workflows, validate_workflow, full-detail workflow/funnel/pipeline reads). Requires you've already run setup_ghl_mcp. EASIEST PATH: run `capture_firebase_interactive` instead \u2014 a Chrome window opens, you log into GHL, zero pasting. Use THIS tool when you have JSON from `auto_capture_firebase_script` (console-paste path) to put in `firebase_paste`, or the three manual DevTools fields. Tool count goes from 190 to 245 after the next Claude restart.",
     {
       // v3.25.0: one-paste path. Tool runs `auto_capture_firebase_script` to
       // get the console script; the script returns a JSON object that pastes
@@ -12881,6 +12990,109 @@ var init_template_deployer = __esm({
 });
 
 // src/tools/validators.ts
+function traceOpportunityContext(node, byId2) {
+  let cur = node;
+  const seen = /* @__PURE__ */ new Set();
+  for (let hops = 0; hops < MAX_TRACE_HOPS; hops++) {
+    const pk = cur.parentKey;
+    if (typeof pk !== "string" || !pk) return "none";
+    if (seen.has(pk)) return "dangling";
+    seen.add(pk);
+    const parent = byId2.get(pk);
+    if (!parent) return "dangling";
+    const ptype = typeof parent.type === "string" ? parent.type : "";
+    if (OPPORTUNITY_CREATING_TYPES.has(ptype)) return "create";
+    if (ptype === "transition") {
+      const ownerId = typeof parent.parentKey === "string" ? parent.parentKey : typeof parent.parent === "string" ? parent.parent : "";
+      const owner = ownerId ? byId2.get(ownerId) : void 0;
+      if (owner && owner.type === "find_opportunity") {
+        const meta = parent.attributes?.meta ?? {};
+        const label = `${typeof parent.name === "string" ? parent.name : ""} ${typeof meta.__branchKey__ === "string" ? meta.__branchKey__ : ""}`.toLowerCase();
+        if (label.includes("opportunity not found")) return "not_found";
+        if (label.includes("opportunity found")) return "found";
+      }
+    }
+    cur = parent;
+  }
+  return "dangling";
+}
+function checkActionShapes(workflow) {
+  const findings = [];
+  const actions = Array.isArray(workflow.workflowData?.templates) ? workflow.workflowData.templates : [];
+  const triggers = Array.isArray(workflow.triggers) ? workflow.triggers : [];
+  const triggerGivesOpportunity = triggers.some((t) => typeof t.type === "string" && OPPORTUNITY_CONTEXT_TRIGGERS.has(t.type));
+  const byId2 = /* @__PURE__ */ new Map();
+  for (const a of actions) if (typeof a.id === "string") byId2.set(a.id, a);
+  for (const a of actions) {
+    const type = typeof a.type === "string" ? a.type : "unknown";
+    const name = typeof a.name === "string" ? a.name : "unnamed action";
+    const id = typeof a.id === "string" ? a.id : name;
+    const where = `action "${name}" (${type})`;
+    if (type === "task_notification") {
+      findings.push({
+        severity: "error",
+        category: "action_shape",
+        id,
+        where,
+        message: `${where} saves and validates but is SKIPPED at runtime \u2014 the type must be "task-notification" (hyphen). Re-save it with the hyphenated type.`
+      });
+      continue;
+    }
+    if (type !== "internal_update_opportunity") continue;
+    const attr = a.attributes ?? {};
+    const cif = Array.isArray(attr.__customInputFields__) ? attr.__customInputFields__ : [];
+    const keys = cif.map((f) => f && typeof f.filterField === "string" ? f.filterField : "").filter(Boolean);
+    const has = (k) => cif.some((f) => f && f.filterField === k && typeof f.value === "string" && f.value.trim() !== "");
+    if (has("name") && has("status")) continue;
+    if (has("name")) {
+      findings.push({
+        severity: "unverified",
+        category: "action_shape",
+        id,
+        where,
+        message: `${where} carries an opportunity name but no status \u2014 GoHighLevel lists Name, Source and Status as mandatory to create a card. Open the step in the GHL builder and confirm Status (and Source) are set, or use Create Opportunity (internal_create_opportunity).`
+      });
+      continue;
+    }
+    const unknown = keys.filter((k) => !KNOWN_UPDATE_OPP_FIELDS.has(k));
+    if (unknown.length) {
+      findings.push({
+        severity: "unverified",
+        category: "action_shape",
+        id,
+        where,
+        message: `${where} carries field(s) this version does not know (${unknown.join(", ")}) \u2014 could not judge whether it can create an opportunity.`
+      });
+      continue;
+    }
+    const ctx = traceOpportunityContext(a, byId2);
+    if (ctx === "create" || ctx === "found") continue;
+    if (ctx === "dangling") {
+      findings.push({
+        severity: "unverified",
+        category: "action_shape",
+        id,
+        where,
+        message: `${where} could not be traced back to the trigger (a parentKey points to a missing step) \u2014 could not judge whether an opportunity is in context.`
+      });
+      continue;
+    }
+    if (ctx === "none" && triggerGivesOpportunity) continue;
+    findings.push({
+      severity: "warning",
+      category: "action_shape",
+      id,
+      where,
+      message: `${where} cannot create an opportunity: it has only pipeline + stage${has("status") ? " + status" : ""}. It moves a card the contact already has in that pipeline; a contact without one (a new lead) gets no card and the workflow continues as if it worked. To create a card use Create Opportunity (internal_create_opportunity); to move one, put Find Opportunity before this step or trigger on the opportunity. GoHighLevel is phasing the combined Create/Update action out.`
+    });
+  }
+  return findings;
+}
+function summarizeFindings(findings) {
+  const issues = findings.filter((f) => f.severity === "error").length;
+  const warnings = findings.filter((f) => f.severity === "warning" && (f.category === "custom_field" || f.category === "action_shape")).length;
+  return { status: issues > 0 ? "issues_found" : "ok", issues_count: issues, warnings_count: warnings };
+}
 function collectMergeTagKeys(value, out) {
   if (typeof value === "string") {
     MERGE_TAG_RE.lastIndex = 0;
@@ -13294,28 +13506,29 @@ function registerValidatorTools(server2, client, builderClient) {
   }
   server2.tool(
     "validate_workflow",
-    "Pre-flight ID validation for ONE deployed GHL workflow. Scans every trigger and action for references to pipelines, pipeline stages, custom fields, users, workflows, forms, calendars, and surveys; verifies each ID exists in the current location. Use BEFORE publish_workflow when a workflow was edited, or when a published workflow stops behaving. Catches the silent-failure bug where invalid IDs make GHL skip all subsequent actions. Never reports a false break \u2014 anything it cannot fully verify is marked 'unverified', not 'error'.",
+    "Pre-flight validation for ONE deployed GHL workflow. Also flags steps that cannot do what their name says at runtime (a Create/Update Opportunity step with only pipeline + stage cannot create a card; task_notification is skipped) \u2014 read every finding with severity warning, not just issues_count. Scans every trigger and action for references to pipelines, pipeline stages, custom fields, users, workflows, forms, calendars, and surveys; verifies each ID exists in the current location. Use BEFORE publish_workflow when a workflow was edited, or when a published workflow stops behaving. Catches the silent-failure bug where invalid IDs make GHL skip all subsequent actions. Never reports a false break \u2014 anything it cannot fully verify is marked 'unverified', not 'error'.",
     { workflowId: import_zod53.z.string().describe("The workflow ID to validate.") },
     async ({ workflowId }) => {
       try {
         const workflow = await builderClient.getWorkflow(workflowId);
         if (!workflow) return errorResponse(new Error(`Workflow ${workflowId} not found`));
         const refs = [];
+        const shape = checkActionShapes(workflow);
+        const actionsChecked = Array.isArray(workflow.workflowData?.templates) ? workflow.workflowData.templates.length : 0;
         for (const t of Array.isArray(workflow.triggers) ? workflow.triggers : []) extractFromTrigger(t, refs);
         for (const a of Array.isArray(workflow.workflowData?.templates) ? workflow.workflowData.templates : []) extractFromAction(a, refs);
         if (refs.length === 0)
-          return jsonResponse({ workflowId, workflowName: workflow.name, status: "ok", references_scanned: 0, issues_count: 0, warnings_count: 0, findings: [] });
+          return jsonResponse({ workflowId, workflowName: workflow.name, ...summarizeFindings(shape), references_scanned: 0, actions_checked: actionsChecked, findings: shape });
         const needWorkflows = refs.some((r) => r.kind === "workflow");
         const catalog = needWorkflows ? await fullWorkflowCatalog(builderClient) : { ids: /* @__PURE__ */ new Set(), complete: true };
         const lookups = await fetchAndBuildLookups(client, builderClient, client.defaultLocationId, { ids: catalog.ids, complete: catalog.complete });
-        const findings = checkRefs(refs, workflowId, lookups);
+        const findings = [...shape, ...checkRefs(refs, workflowId, lookups)];
         const report = {
           workflowId,
           workflowName: workflow.name,
-          status: findings.some((f) => f.severity === "error") ? "issues_found" : "ok",
+          ...summarizeFindings(findings),
           references_scanned: refs.length,
-          issues_count: findings.filter((f) => f.severity === "error").length,
-          warnings_count: findings.filter((f) => f.severity === "warning" && f.category === "custom_field").length,
+          actions_checked: actionsChecked,
           findings
         };
         return jsonResponse(report);
@@ -13326,7 +13539,7 @@ function registerValidatorTools(server2, client, builderClient) {
   );
   server2.tool(
     "audit_workflows",
-    "Account-wide silent-failure audit: scans EVERY workflow in the current location for references to pipelines/stages/custom-fields/users/workflows/forms/calendars/surveys that don't exist \u2014 the GHL bug where one bad ID silently kills that action and all actions after it. Returns a prioritized report of what's broken, what couldn't be scanned, and what couldn't be fully verified. Conservative: never reports a false break (uncertain checks are 'unverified', not 'broken'). Read-only.",
+    "Account-wide silent-failure audit: also flags steps that cannot do what their name says (a Create/Update Opportunity step with only pipeline + stage cannot create a card) under shape_warnings \u2014 read them. Scans EVERY workflow in the current location for references to pipelines/stages/custom-fields/users/workflows/forms/calendars/surveys that don't exist \u2014 the GHL bug where one bad ID silently kills that action and all actions after it. Returns a prioritized report of what's broken, what couldn't be scanned, and what couldn't be fully verified. Conservative: never reports a false break (uncertain checks are 'unverified', not 'broken'). Read-only.",
     {},
     async () => {
       try {
@@ -13348,7 +13561,7 @@ function registerValidatorTools(server2, client, builderClient) {
               const wf = await builderClient.getWorkflow(row.id);
               const refs = auditOneWorkflow(wf, row.id, lookups);
               if (refs.length === 0) zeroRefCount++;
-              const findings = checkRefs(refs, row.id, lookups);
+              const findings = [...checkActionShapes(wf), ...checkRefs(refs, row.id, lookups)];
               results.push({ id: row.id, name: wf.name ?? row.name, status: wf.status, refs: refs.length, findings });
             } catch (e) {
               unscannable.push({ id: row.id, name: row.name, reason: e instanceof Error ? e.message : String(e) });
@@ -13359,6 +13572,8 @@ function registerValidatorTools(server2, client, builderClient) {
         const errorsTotal = withErrors.reduce((n, w) => n + w.errors.length, 0);
         const withWarnings = results.filter((r) => r.findings.some((f) => f.severity === "warning" && f.category === "custom_field")).map((r) => ({ workflowId: r.id, workflowName: r.name, status: r.status, warnings: r.findings.filter((f) => f.severity === "warning" && f.category === "custom_field") })).sort((a, b) => (a.status === "published" ? -1 : 1) - (b.status === "published" ? -1 : 1));
         const warningsTotal = withWarnings.reduce((n, w) => n + w.warnings.length, 0);
+        const withShapeWarnings = results.filter((r) => r.findings.some((f) => f.severity === "warning" && f.category === "action_shape")).map((r) => ({ workflowId: r.id, workflowName: r.name, status: r.status, warnings: r.findings.filter((f) => f.severity === "warning" && f.category === "action_shape") })).sort((a, b) => (a.status === "published" ? -1 : 1) - (b.status === "published" ? -1 : 1));
+        const shapeWarningsTotal = withShapeWarnings.reduce((n, w) => n + w.warnings.length, 0);
         const unverifiedCats = ALL_CATEGORIES.filter((c) => lookups.status[c] !== "loaded");
         const unverifiedRefs = results.reduce((n, r) => n + r.findings.filter((f) => f.severity === "unverified").length, 0);
         return jsonResponse({
@@ -13372,6 +13587,8 @@ function registerValidatorTools(server2, client, builderClient) {
             errors_total: errorsTotal,
             workflows_with_merge_field_warnings: withWarnings.length,
             merge_field_warnings_total: warningsTotal,
+            workflows_with_shape_warnings: withShapeWarnings.length,
+            shape_warnings_total: shapeWarningsTotal,
             workflows_unscannable: unscannable.length,
             workflows_zero_references: zeroRefCount,
             unverified: { categories_unloaded: unverifiedCats, references_unverified: unverifiedRefs },
@@ -13379,12 +13596,14 @@ function registerValidatorTools(server2, client, builderClient) {
           },
           workflows_with_issues: withErrors,
           merge_field_warnings: withWarnings,
+          shape_warnings: withShapeWarnings,
           unscannable,
           notes: [
             ...catalog.complete ? [] : ["Workflow catalog exceeded the pagination backstop \u2014 some workflow-id references shown as unverified."],
             ...catalog.rows.length > SCAN_CAP ? [`Only the first ${SCAN_CAP} workflows were scanned (account has ${catalog.rows.length}).`] : [],
             ...unverifiedCats.length ? [`Could not fully load: ${unverifiedCats.join(", ")} \u2014 references to those are 'unverified', not 'broken'. Re-run.`] : [],
             ...warningsTotal ? [`${warningsTotal} {{contact.X}} merge tag(s) reference a field that no longer exists \u2014 these render BLANK in the message but do NOT stop the workflow (warning, not a break). See merge_field_warnings.`] : [],
+            ...shapeWarningsTotal ? [`${shapeWarningsTotal} Create/Update Opportunity step(s) have only pipeline + stage \u2014 they cannot create a card for a new contact (see shape_warnings).`] : [],
             "workflow_goal, goto, and unrecognized condition types are not deeply checked in this version."
           ]
         });
@@ -13394,7 +13613,7 @@ function registerValidatorTools(server2, client, builderClient) {
     }
   );
 }
-var import_zod53, ALL_CATEGORIES, STANDARD_CONTACT_FIELDS, MERGE_TAG_RE;
+var import_zod53, ALL_CATEGORIES, OPPORTUNITY_CONTEXT_TRIGGERS, OPPORTUNITY_CREATING_TYPES, KNOWN_UPDATE_OPP_FIELDS, MAX_TRACE_HOPS, STANDARD_CONTACT_FIELDS, MERGE_TAG_RE;
 var init_validators = __esm({
   "src/tools/validators.ts"() {
     "use strict";
@@ -13403,6 +13622,16 @@ var init_validators = __esm({
     init_api_schemas();
     init_id_shape();
     ALL_CATEGORIES = ["pipeline", "stage", "custom_field", "user", "workflow", "form", "calendar", "survey"];
+    OPPORTUNITY_CONTEXT_TRIGGERS = /* @__PURE__ */ new Set([
+      "opportunity_status_changed",
+      "opportunity_created",
+      "opportunity_changed",
+      "pipeline_stage_updated",
+      "opportunity_decay"
+    ]);
+    OPPORTUNITY_CREATING_TYPES = /* @__PURE__ */ new Set(["internal_create_opportunity", "create_opportunity"]);
+    KNOWN_UPDATE_OPP_FIELDS = /* @__PURE__ */ new Set(["pipelineId", "pipelineStageId", "name", "status", "source", "monetaryValue"]);
+    MAX_TRACE_HOPS = 200;
     STANDARD_CONTACT_FIELDS = /* @__PURE__ */ new Set([
       "first_name",
       "firstname",
@@ -18799,9 +19028,9 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.69.0",
+      version: "3.71.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
-      description: "GoHighLevel MCP Server for Claude. 242 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, live funnel-capture verification, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
+      description: "GoHighLevel MCP Server for Claude. 245 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, live funnel-capture verification, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
       bin: {
         "ghl-mcp": "dist/index.js"

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.69.0",
+  "version": "3.71.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
-  "description": "GoHighLevel MCP Server for Claude. 242 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, live funnel-capture verification, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
+  "description": "GoHighLevel MCP Server for Claude. 245 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, live funnel-capture verification, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",
   "bin": {
     "ghl-mcp": "dist/index.js"

package/templates/action-schemas.json

@@ -106,7 +106,7 @@
         "selectedUser": "USER_ID"
       }
     },
-    "notes": "Nested 'notification' object REQUIRED. selectedUser MUST be a real user ID — GHL now REJECTS an empty string (live-verified 2026-08-06; the old 'empty = all users' behavior is gone). Use get_users to find IDs. EMAIL CHANNEL (verified live 2026-07-20, PWDJ workflow e91f28da): attributes.type is 'email' (NOT 'notification'), nested key is 'email' (NOT 'notification'), body field is 'html' (NOT 'body'), selectedUser is an ARRAY of user IDs, include attachments:[] and isCloned:false. A 'send_email' discriminator inside a 'notification' object saves but silently never sends.",
+    "notes": "Nested 'notification' object REQUIRED. selectedUser MUST be a real user ID \u2014 GHL now REJECTS an empty string (live-verified 2026-08-06; the old 'empty = all users' behavior is gone). Use get_users to find IDs. EMAIL CHANNEL (verified live 2026-07-20, PWDJ workflow e91f28da): attributes.type is 'email' (NOT 'notification'), nested key is 'email' (NOT 'notification'), body field is 'html' (NOT 'body'), selectedUser is an ARRAY of user IDs, include attachments:[] and isCloned:false. A 'send_email' discriminator inside a 'notification' object saves but silently never sends.",
     "emailChannelExample": {
       "type": "email",
       "email": {
@@ -166,6 +166,27 @@
     },
     "notes": "Requires BOTH workflowId (string) AND workflow_id (ARRAY with same ID). Also needs type: 'remove_from_workflow' inside attributes. Derived from GHL UI."
   },
+  "internal_create_opportunity": {
+    "example": {
+      "type": "internal_create_opportunity",
+      "workflowsActionType": "INTERNAL",
+      "attributes": {
+        "type": "internal_create_opportunity",
+        "pipelineId": "PIPELINE_ID",
+        "__customInputFields__": [
+          {
+            "__customInputs__": {},
+            "dataType": "SINGLE_OPTIONS",
+            "filterField": "pipelineStageId",
+            "value": "STAGE_ID",
+            "valueFieldType": "select"
+          }
+        ],
+        "__customInputs__": {}
+      }
+    },
+    "notes": "CREATES a card (GHL's newer separate 'Create Opportunity' action). This minimal shape is live-proven to create at runtime (2026-07-24): pipelineId at the ATTRIBUTES level (not inside __customInputFields__), __customInputFields__ carrying pipelineStageId, workflowsActionType:'INTERNAL' at the NODE level. UI-built nodes also carry name/status/monetaryValue entries and work \u2014 copy a working node field-for-field rather than inventing entries. Without a name entry the card is named from the contact (observed live 2026-07-24). Use THIS for 'create an opportunity for the new lead'."
+  },
   "internal_update_opportunity": {
     "example": {
       "__customInputFields__": [
@@ -185,7 +206,7 @@
       "workflowsActionType": "INTERNAL",
       "type": "internal_update_opportunity"
     },
-    "notes": "CREATABLE from scratch (re-enabled v3.41.0). The discriminator workflowsActionType:'INTERNAL' MUST sit at the NODE level, never nested in attributes \u2014 a nested copy makes GHL reject the node as 'action has a corrupted type' and silently fail the whole save. update_workflow_actions normalizes this for you (hoists workflowsActionType to the node level, scaffolds allowBackward + __customInputs__, gives each __customInputFields__ entry an __customInputs__). The shape below (workflowsActionType at the node level alongside type/name/attributes) is correct for both creating and round-tripping. Use pipeline and stage IDs (not names) \u2014 get_pipelines / list_pipelines_full to find them FIRST. CRITICAL: if the pipelineId or pipelineStageId don't exist in the target sub-account, GHL silently fails this action AND can kill subsequent actions. A synthesized node needs BOTH a pipelineId and a pipelineStageId entry; a node round-tripped via get_workflow_full keeps its id and passes through unchanged."
+    "notes": "GHL's combined 'Create/Update Opportunity'. With only pipelineId + pipelineStageId it CANNOT create a card \u2014 it moves one the contact already has; a contact with no opportunity (a new lead) gets nothing and the workflow continues as if it worked (customer report 2026-08-26). It creates only when __customInputFields__ also carry Opportunity name (GHL's doc: Name, Source, Status mandatory to create). GoHighLevel is phasing this combined action out for new workflows, so prefer internal_create_opportunity to create; use this node after find_opportunity, after a create step in the same workflow, or on an opportunity trigger. CREATABLE from scratch (re-enabled v3.41.0). The discriminator workflowsActionType:'INTERNAL' MUST sit at the NODE level, never nested in attributes \u2014 a nested copy makes GHL reject the node as 'action has a corrupted type' and silently fail the whole save. update_workflow_actions normalizes this for you (hoists workflowsActionType to the node level, scaffolds allowBackward + __customInputs__, gives each __customInputFields__ entry an __customInputs__). The shape below (workflowsActionType at the node level alongside type/name/attributes) is correct for both creating and round-tripping. Use pipeline and stage IDs (not names) \u2014 get_pipelines / list_pipelines_full to find them FIRST. CRITICAL: if the pipelineId or pipelineStageId don't exist in the target sub-account, GHL silently fails this action AND can kill subsequent actions. A synthesized node needs BOTH a pipelineId and a pipelineStageId entry; a node round-tripped via get_workflow_full keeps its id and passes through unchanged."
   },
   "_if_else_branching": {
     "notes": "if_else is a node type discriminator only. Do not send a single flat if_else action.",