@elitedcs/ghl-mcp 3.34.3 → 3.34.4

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 3.34.4 — Audit catches blank-render merge tags + honest guard on Update-Opportunity
+
+- **`audit_workflows` / `validate_workflow` now flag dead `{{contact.X}}` merge tags.**
+  A custom field deleted or renamed while still referenced by a `{{contact.x}}`
+  merge tag in message copy (sms body, email html/subject, notes, notifications)
+  renders **blank** at send time. Unlike a dead structured id — which silently
+  skips the action and everything after it — this only produces an empty value, so
+  it is reported as a **warning**, never an error, and never flips a workflow to
+  "broken". Validated by custom-field key (`fieldKey`), with a generous standard-
+  field allowlist and nested-path skipping (`{{contact.attributionSource.x}}`) so
+  it never cries wolf on `{{contact.first_name}}` and friends; goes `unverified`
+  (not warned) if the custom-field list fails to load. Surfaced in a new
+  `merge_field_warnings` section + `warnings_count`. (10 regression tests; verified
+  against real GHL `fieldKey` shapes.)
+- **`update_workflow_actions`: honest fail-fast on `internal_update_opportunity`.**
+  GHL's builder rejects a *synthesized* move/update-opportunity node with "action
+  has a corrupted type" and fails the entire save with a cryptic error. The builder
+  now detects a freshly-built one and throws a clear, actionable message up front
+  (build that one step in the GHL UI, or round-trip an existing one via
+  `get_workflow_full` — those keep their node id and pass through untouched). No
+  more one-bad-node-nukes-the-whole-save surprise. Tool + schema docs updated to
+  state the limitation plainly.
+
 ## 3.34.3 — Audit catches dead workflow hand-offs + get_social_posts 422 fix
 
 - **`audit_workflows` / `validate_workflow` now scan `add_to_workflow` targets.**

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.34.3",
+      version: "3.34.4",
       mcpName: "io.github.drjerryrelth/ghl-command",
       description: "GoHighLevel MCP Server for Claude. 218 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
@@ -1206,9 +1206,15 @@ function validateActionChain(actions) {
       case "wait":
         if (!attr.startAfter) throw new Error(`Wait action "${action.name}" missing required 'startAfter' in attributes.`);
         break;
-      case "internal_update_opportunity":
+      case "internal_update_opportunity": {
+        if (!hasId(action)) {
+          throw new Error(
+            `Action "${action.name}" (internal_update_opportunity / "Update Opportunity" / move-to-stage) cannot be created via the API yet: GHL's workflow builder rejects a synthesized node with "action has a corrupted type", which silently fails the whole save. Build this one step in the GHL UI (Workflow > add action > Update Opportunity), or pass through an existing one read via get_workflow_full (it keeps its id). Every other action type in this call works.`
+          );
+        }
         if (!Array.isArray(attr.__customInputFields__)) throw new Error(`Internal update opportunity action "${action.name}" missing '__customInputFields__' array.`);
         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;
@@ -5394,7 +5400,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, 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.",
+    "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. NOTE: internal_update_opportunity (GHL's 'Update Opportunity' / move-to-stage action) cannot be created fresh through this API \u2014 GHL's builder rejects a synthesized node with 'action has a corrupted type' and fails the whole save; add that single step in the GHL UI, or pass through one already read via get_workflow_full (it keeps its node id). 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_zod33.z.string().describe("The workflow ID to update."),
       name: import_zod33.z.string().optional().describe("New workflow name."),
@@ -8514,6 +8520,96 @@ var ID_SHAPE = /^[A-Za-z0-9]{17,}$/;
 function isIdShaped(s) {
   return typeof s === "string" && ID_SHAPE.test(s);
 }
+var STANDARD_CONTACT_FIELDS = /* @__PURE__ */ new Set([
+  "first_name",
+  "firstname",
+  "last_name",
+  "lastname",
+  "name",
+  "full_name",
+  "fullname",
+  "nickname",
+  "email",
+  "email_lower_case",
+  "phone",
+  "phone_raw",
+  "phone_number",
+  "company_name",
+  "companyname",
+  "business_name",
+  "organization",
+  "address1",
+  "address",
+  "full_address",
+  "street_address",
+  "city",
+  "state",
+  "province",
+  "country",
+  "postal_code",
+  "postalcode",
+  "zip",
+  "zip_code",
+  "timezone",
+  "time_zone",
+  "date_of_birth",
+  "dateofbirth",
+  "dob",
+  "birthday",
+  "source",
+  "contact_source",
+  "type",
+  "contact_type",
+  "id",
+  "contact_id",
+  "contactid",
+  "tags",
+  "dnd",
+  "dnd_status",
+  "assigned_to",
+  "assignedto",
+  "owner",
+  "contact_owner",
+  "created_by",
+  "updated_by",
+  "date_created",
+  "date_updated",
+  "date_added",
+  "created_at",
+  "updated_at",
+  "last_updated",
+  "last_activity",
+  "last_activity_date",
+  "website",
+  "url",
+  "gender",
+  "rating",
+  "additional_emails",
+  "additional_phones",
+  "attributionsource",
+  "attribution_source"
+]);
+var MERGE_TAG_RE = /\{\{\s*contact\.([^}|\s]+)/gi;
+function collectMergeTagKeys(value, out) {
+  if (typeof value === "string") {
+    MERGE_TAG_RE.lastIndex = 0;
+    let m;
+    while ((m = MERGE_TAG_RE.exec(value)) !== null) {
+      const raw = m[1];
+      if (!raw || raw.includes(".")) continue;
+      const key = raw.toLowerCase();
+      if (STANDARD_CONTACT_FIELDS.has(key)) continue;
+      out.add(key);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const v of value) collectMergeTagKeys(v, out);
+    return;
+  }
+  if (value && typeof value === "object")
+    for (const v of Object.values(value)) collectMergeTagKeys(v, out);
+}
 function extractFromTrigger(trigger, refs) {
   const triggerName = String(trigger.name ?? trigger.type ?? "unnamed trigger");
   const where = `trigger "${triggerName}"`;
@@ -8668,6 +8764,28 @@ function extractFromAction(action, refs) {
       break;
     }
   }
+  const mergeKeys = /* @__PURE__ */ new Set();
+  collectMergeTagKeys(attr, mergeKeys);
+  for (const key of mergeKeys)
+    refs.push({ kind: "custom_field", id: key, where: `${where} \u2192 merge tag {{contact.${key}}}`, byKey: true });
+}
+function collectCustomFieldKeys(envelope) {
+  const keys = /* @__PURE__ */ new Set();
+  let arr = null;
+  if (Array.isArray(envelope)) arr = envelope;
+  else if (envelope && typeof envelope === "object" && Array.isArray(envelope.customFields))
+    arr = envelope.customFields;
+  if (arr) for (const item of arr) {
+    if (!item || typeof item !== "object") continue;
+    const o = item;
+    for (const raw of [o.fieldKey, o.key]) {
+      if (typeof raw !== "string") continue;
+      let k = raw.toLowerCase();
+      if (k.startsWith("contact.")) k = k.slice("contact.".length);
+      if (k) keys.add(k);
+    }
+  }
+  return keys;
 }
 function collectIds(envelope, listKeys) {
   const ids = /* @__PURE__ */ new Set();
@@ -8746,12 +8864,13 @@ async function fetchAndBuildLookups(client, builderClient, locationId2, workflow
     return ids;
   }
   const custom_field = setFrom("customFields", "custom_field", ["customFields"]);
+  const custom_field_keys = failed.has("customFields") ? /* @__PURE__ */ new Set() : collectCustomFieldKeys(data.customFields);
   const user = setFrom("users", "user", ["users"]);
   const form = setFrom("forms", "form", ["forms"]);
   const calendar = setFrom("calendars", "calendar", ["calendars"]);
   const survey = setFrom("surveys", "survey", ["surveys"]);
   status.workflow = workflowExistence.complete ? "loaded" : "incomplete";
-  return { pipelines, stages, custom_field, user, workflow: workflowExistence.ids, form, calendar, survey, status };
+  return { pipelines, stages, custom_field, custom_field_keys, user, workflow: workflowExistence.ids, form, calendar, survey, status };
 }
 function auditOneWorkflow(workflow, selfId, lookups) {
   const refs = [];
@@ -8775,6 +8894,26 @@ function checkRefs(refs, selfId, lookups) {
   const findings = [];
   for (const ref of refs) {
     const st = lookups.status[ref.kind];
+    if (ref.byKey && ref.kind === "custom_field") {
+      if (st !== "loaded") {
+        findings.push({
+          severity: "unverified",
+          category: "custom_field",
+          id: ref.id,
+          where: ref.where,
+          message: `merge tag {{contact.${ref.id}}} could not be verified \u2014 the custom field list ${st === "incomplete" ? "is too large to fully load" : "failed to load or was unreadable"}. Re-run; not reported as broken.`
+        });
+      } else if (!lookups.custom_field_keys.has(ref.id)) {
+        findings.push({
+          severity: "warning",
+          category: "custom_field",
+          id: ref.id,
+          where: ref.where,
+          message: `merge tag {{contact.${ref.id}}} matches no standard field or custom field in this location \u2014 it will render blank. If "${ref.id}" was a custom field it was likely deleted or renamed; if it is a standard field this audit does not recognize, you can ignore this.`
+        });
+      }
+      continue;
+    }
     if (st !== "loaded") {
       findings.push({
         severity: "unverified",
@@ -8846,7 +8985,7 @@ function registerValidatorTools(server2, client, builderClient) {
         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, findings: [] });
+          return jsonResponse({ workflowId, workflowName: workflow.name, status: "ok", references_scanned: 0, issues_count: 0, warnings_count: 0, findings: [] });
         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 });
@@ -8857,6 +8996,7 @@ function registerValidatorTools(server2, client, builderClient) {
           status: findings.some((f) => f.severity === "error") ? "issues_found" : "ok",
           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,
           findings
         };
         return jsonResponse(report);
@@ -8898,6 +9038,8 @@ function registerValidatorTools(server2, client, builderClient) {
         }
         const withErrors = results.filter((r) => r.findings.some((f) => f.severity === "error")).map((r) => ({ workflowId: r.id, workflowName: r.name, status: r.status, errors: r.findings.filter((f) => f.severity === "error") })).sort((a, b) => (a.status === "published" ? -1 : 1) - (b.status === "published" ? -1 : 1));
         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 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({
@@ -8909,17 +9051,21 @@ function registerValidatorTools(server2, client, builderClient) {
             capped: catalog.rows.length > SCAN_CAP,
             workflows_with_errors: withErrors.length,
             errors_total: errorsTotal,
+            workflows_with_merge_field_warnings: withWarnings.length,
+            merge_field_warnings_total: warningsTotal,
             workflows_unscannable: unscannable.length,
             workflows_zero_references: zeroRefCount,
             unverified: { categories_unloaded: unverifiedCats, references_unverified: unverifiedRefs },
             status: errorsTotal > 0 ? "issues_found" : "ok"
           },
           workflows_with_issues: withErrors,
+          merge_field_warnings: withWarnings,
           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.`] : [],
             "workflow_goal, goto, and unrecognized condition types are not deeply checked in this version."
           ]
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.34.3",
+  "version": "3.34.4",
   "mcpName": "io.github.drjerryrelth/ghl-command",
   "description": "GoHighLevel MCP Server for Claude. 218 tools — full CRM, automation, marketing control, account-wide workflow audit, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",

package/templates/action-schemas.json

@@ -165,7 +165,7 @@
       "workflowsActionType": "INTERNAL",
       "type": "internal_update_opportunity"
     },
-    "notes": "Use action type internal_update_opportunity. Use pipeline and stage IDs (not names). Use get_pipelines or list_pipelines_full to find IDs FIRST. CRITICAL: If the pipelineId or stageId don't exist in the target sub-account, GHL silently fails this action AND can kill subsequent actions in the workflow. Always verify IDs exist before deploying."
+    "notes": "CANNOT CREATE FRESH VIA THIS API: GHL's builder rejects a synthesized internal_update_opportunity node with 'action has a corrupted type' and fails the whole save. Build this step in the GHL UI, or round-trip one read via get_workflow_full (it keeps its node id). The shape below is correct for READING / round-tripping. Use pipeline and stage IDs (not names). Use get_pipelines or list_pipelines_full to find IDs FIRST. CRITICAL: If the pipelineId or stageId don't exist in the target sub-account, GHL silently fails this action AND can kill subsequent actions in the workflow. Always verify IDs exist before deploying."
   },
 
   "_if_else_branching": {