@elitedcs/ghl-mcp 3.75.0 → 3.77.0

package/guide/guide.html

@@ -4,7 +4,7 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>GHL Command — User Guide</title>
-<!-- guides-hash: a867c296d4cc8d65 -->
+<!-- guides-hash: 2bcfa41ad790fe7c -->
 <style>
 /* Deliberately light in every environment, including a dark-mode OS. This is a
    reference document people read at length, print, and save to PDF, and a page
@@ -226,7 +226,7 @@ body.app.reading #indexview{display:none}
   <p class="eyebrow">GHL Command</p>
   <h1>What do you want to get done?</h1>
   <p class="sub">Every guide is a job, in plain English: open one, copy a prompt, paste it to Claude. A job is not a button, so one guide usually puts a dozen of GHL Command's tools to work at once. Every prompt marked "Proven live" was run against a real GoHighLevel account before it shipped.</p>
-  <div class="badges"><span class="badge on">30 guides</span><span class="badge">10 categories</span><span class="badge">Updates with the product</span></div>
+  <div class="badges"><span class="badge on">31 guides</span><span class="badge">10 categories</span><span class="badge">Updates with the product</span></div>
 </div></section>
 <div class="shell">
 <main>
@@ -243,7 +243,8 @@ body.app.reading #indexview{display:none}
 <a class="card pub" href="#g-audit-your-workflows" data-k="audit workflows broken silent failure check review existing validate not sending nothing happens"><h3>Audit your workflows</h3><p>Find silent failures and dead ends in existing workflows before your client does.</p><div class="meta"><span class="pill free">Free plan</span><span class="time">~2 minutes</span><span class="open">Open guide &#8594;</span></div></a>
 <a class="card pub" href="#g-branch-on-tags-and-fields" data-k="if else branch condition vip tag field split two paths different message"><h3>Branch on tags and fields</h3><p>If they are a VIP, send this. Otherwise, send that. Built correctly the first time.</p><div class="meta"><span class="pill full">Full license</span><span class="time">~5 minutes</span><span class="open">Open guide &#8594;</span></div></a>
 <a class="card pub" href="#g-build-nurture-sequence" data-k="nurture sequence drip texts emails follow up workflow build quiet hours sending window contact hours"><h3>Build a nurture sequence</h3><p>A follow-up machine that texts, emails, waits, and stops the second someone replies.</p><div class="meta"><span class="pill full">Full license</span><span class="time">~15 minutes</span><span class="open">Open guide &#8594;</span></div></a>
-<a class="card pub" href="#g-send-data-to-other-apps" data-k="webhook zapier make integromat slack google sheets api send data integration notify push connect n8n other app"><h3>Send GHL data to another app</h3><p>Push contacts into Slack, Sheets, Zapier, Make or your own software the moment something happens in GHL.</p><div class="meta"><span class="pill full">Full license</span><span class="time">~2 minutes</span><span class="open">Open guide &#8594;</span></div></a></div></div>
+<a class="card pub" href="#g-send-data-to-other-apps" data-k="webhook zapier make integromat slack google sheets api send data integration notify push connect n8n other app"><h3>Send GHL data to another app</h3><p>Push contacts into Slack, Sheets, Zapier, Make or your own software the moment something happens in GHL.</p><div class="meta"><span class="pill full">Full license</span><span class="time">~2 minutes</span><span class="open">Open guide &#8594;</span></div></a>
+<a class="card pub" href="#g-workflows-that-will-not-save" data-k="cannot save will not save invalid uuid action validation failed step id legacy snapshot day days wait unit notification recipient 400 rejected edit workflow parked mid-sequence"><h3>When a workflow runs fine but will not save</h3><p>Understand the error that names steps you never touched, and fix it without dropping anyone mid-sequence.</p><div class="meta"><span class="pill free">Free plan</span><span class="time">~3 minutes</span><span class="open">Open guide &#8594;</span></div></a></div></div>
 <div class="catsec" id="cat-pipelines-and-sales"><h2>Pipelines and sales</h2><div class="cards"><a class="card pub" href="#g-documents-and-contracts" data-k="documents contracts proposals signature send sign agreement esign template"><h3>Documents and contracts</h3><p>Proposals and contracts sent for signature and tracked from Claude.</p><div class="meta"><span class="pill full">Full license</span><span class="time">~5 minutes</span><span class="open">Open guide &#8594;</span></div></a>
 <a class="card pub" href="#g-invoices-and-payments" data-k="invoice bill billing payment paid product price coupon promo code discount transactions orders revenue estimate"><h3>Bill a client and see what you were paid</h3><p>Products, invoices, coupons, and the money reads, without opening the billing screen.</p><div class="meta"><span class="pill full">Full license</span><span class="time">~5 minutes</span><span class="open">Open guide &#8594;</span></div></a>
 <a class="card pub" href="#g-stand-up-a-pipeline" data-k="pipeline stages create new client setup opportunity sales process deal stages"><h3>Stand up a pipeline</h3><p>Stages, fields, and tags for a new client in one conversation.</p><div class="meta"><span class="pill full">Full license</span><span class="time">~10 minutes</span><span class="open">Open guide &#8594;</span></div></a>
@@ -2135,6 +2136,61 @@ Then give me the three things you would look at first if this were your account.
   <p class="gfoot">Works in Claude Desktop and Claude Code. Stuck? Email support@ghlcommand.com and a human answers.</p>
   </main></div>
 </section>
+
+<section class="gpage" id="g-workflows-that-will-not-save">
+  <div class="hero"><div class="hero-in">
+    <p class="eyebrow">GHL Command User Guide</p>
+    <h1>When a workflow runs fine but will not save</h1>
+    <p class="sub">Understand the error that names steps you never touched, and fix it without dropping anyone mid-sequence.</p>
+    <div class="badges"><span class="badge on">Free plan</span><span class="badge">~3 minutes</span><span class="badge">Automations</span></div>
+  </div></div>
+  <div class="shell"><main class="gview">
+  <a class="back" href="#top">&#8592; All guides</a>
+  <div class="gsec"><h2>What you'll get</h2>
+<ul>
+<li>Plain English for the error that says <code>Action validation failed</code> and then lists steps you did not touch.</li>
+<li>The reason your workflow runs perfectly and still refuses to save.</li>
+<li>What GHL Command does about it automatically, what it refuses to do, and why refusing is the right answer.</li>
+</ul>
+</div>
+<div class="gsec"><h2>The short version</h2>
+<p class="gpara">Your workflow is not broken. It runs. Contacts move through it and messages go out exactly as they should.</p>
+<p class="gpara">What is broken is your ability to <b>edit</b> it. GoHighLevel tightened what it accepts when a workflow is saved, and older workflows store shapes that no longer pass. Change one step, hit save, and GHL rejects the whole thing and names three other steps as the problem. That is why the error looks unrelated to what you just did.</p>
+<p class="gpara">This affects workflows built from older snapshots and templates. On one real account, 20 of 43 workflows were in this state and the account looked completely healthy from inside GHL.</p>
+</div>
+<div class="gsec"><h2>Say this</h2>
+<div class="prompt"><q>Audit my workflows and tell me which ones cannot be saved.</q><button class="copy" type="button">Copy</button></div>
+<div class="prompt"><q>Why does this workflow fail with &quot;Action validation failed&quot; when I try to edit it?</q><button class="copy" type="button">Copy</button></div>
+<div class="prompt"><q>Is anyone part-way through this workflow right now?</q><button class="copy" type="button">Copy</button></div>
+</div>
+<div class="gsec"><h2>What the audit tells you now</h2>
+<p class="gpara">Run an audit and you may see warnings that did not exist before. They are <b>warnings, not errors</b>, and the difference matters:</p>
+<div style="overflow-x:auto"><table class="wrongtbl"><tr><th>Warning</th><th>What it means</th><th>What to do</th></tr><tr><td>Step id that GHL now rejects</td><td>The workflow <b>runs fine</b>. You cannot edit it until the ids are renewed.</td><td>See &quot;Renewing the ids&quot; below. Do not rush it.</td></tr><tr><td>Singular wait unit (&quot;day&quot; or &quot;minute&quot;)</td><td>Same: runs fine, blocks saving.</td><td>Nothing. This is corrected automatically the next time the workflow is saved.</td></tr><tr><td>Notification with no recipient</td><td>The opposite problem: it <b>saves fine and runs</b>, and quietly notifies nobody.</td><td>Pick a person to notify, or set it to notify everyone.</td></tr><tr><td>Social step with no connected account</td><td>Also runs and quietly does nothing.</td><td>Connect the account in Settings → Integrations.</td></tr></table></div>
+<p class="gpara">Read those two groups carefully, because the advice is opposite. The first two mean *&quot;it works, you just cannot change it.&quot;* The last two mean *&quot;it looks fine and is doing nothing.&quot;*</p>
+</div>
+<div class="gsec"><h2>Renewing the ids, and the one thing that can go wrong</h2>
+<p class="gpara">Fixing the id problem means giving every step a new identifier. Here is the part nobody tells you:</p>
+<p class="gpara"><b>A contact part-way through a workflow is attached to the step they are waiting on.</b> Somebody sitting at &quot;wait 3 days&quot; is held there by that step's id. Renew the id and that contact is dropped out of the sequence, silently and permanently, with no way to put them back. GoHighLevel has no way to place a contact back at step seven.</p>
+<p class="gpara">So GHL Command will not do it while anyone is waiting. If you ask it to change a step that has someone parked on it, it refuses, tells you how many people are affected, and writes nothing.</p>
+<p class="gpara">That is deliberate. A refused edit costs you a wait. A dropped lead costs you the lead.</p>
+<p class="gpara"><b>What it will still do:</b> every other step in that workflow can be edited, renewed, added or removed. You can repair the whole workflow around the person who is waiting.</p>
+<p class="gpara"><b>What counts as &quot;their step&quot;:</b> the step they are standing on, and any step it depends on. Some steps wait on another step rather than containing it: a goal that waits for a particular email to be opened is holding a reference to that email step. Change the email and the person waiting on the goal is affected, even though you never touched the goal. Those steps are protected too.</p>
+<p class="gpara"><b>When to do it:</b> when nobody is mid-sequence. For a nurture, that is usually after the last person has finished it. For a template or a brand-new account, it is safe immediately, because nobody is in it yet.</p>
+</div>
+<div class="gsec"><h2>Good to know</h2>
+<ul>
+<li>Running the workflow is never affected. If you change nothing, nothing breaks. There is no rush.</li>
+<li>A workflow can show enrolments and still have nobody waiting: those are people who have already finished. Only people mid-sequence matter.</li>
+<li>This works fully on the Free plan. Making the repairs needs the full license.</li>
+<li>If a workflow was built from a snapshot or a template, assume it is affected until the audit says otherwise. That is where these come from.</li>
+</ul>
+</div>
+<div class="gsec"><h2>Where people go wrong</h2>
+<div style="overflow-x:auto"><table class="wrongtbl"><tr><th>What happened</th><th>The fix</th></tr><tr><td>&quot;The error named three steps I never touched, so I assumed I broke something else.&quot;</td><td>You did not. GoHighLevel rejects the whole workflow at once and reports every step it does not like, including the ones you left alone.</td></tr><tr><td>&quot;The audit said 'ok' before, so I thought the account was clean.&quot;</td><td>Older versions could not see this at all. Re-run the audit: these warnings are new.</td></tr><tr><td>&quot;I renewed the ids on a live nurture and people stopped receiving messages.&quot;</td><td>They were dropped at the step they were waiting on. This is exactly why the product now refuses. Check who is waiting before you repair.</td></tr><tr><td>&quot;It refused to let me rename a step.&quot;</td><td>If someone is parked on that step, even a rename is refused. It is cautious on purpose. Wait until they have moved on.</td></tr><tr><td>&quot;I want to force it through anyway.&quot;</td><td>For an EDIT there is no override, and that is intentional. There is no way to put a dropped contact back, so the product will not offer you a button that loses them.</td></tr><tr><td>&quot;I need to delete the whole workflow and people are in it.&quot;</td><td>Deleting is different: you cannot delete a workflow and keep the people inside it, so this one is your call rather than a refusal. The first attempt tells you how many are part-way through; run it again naming that number and it proceeds. Nothing is deleted until you do.</td></tr></table></div>
+</div>
+  <p class="gfoot">Works in Claude Desktop and Claude Code. Stuck? Email support@ghlcommand.com and a human answers.</p>
+  </main></div>
+</section>
 <footer class="foot"><div class="foot-in">
   <span>GHL Command runs your GoHighLevel account from Claude. This guide library ships with every install, free or paid, and grows with the product.</span>
   <a href="https://ghlcommand.com/skills/">Web version</a><a href="https://ghlcommand.com">ghlcommand.com</a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.75.0",
+  "version": "3.77.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
   "description": "GoHighLevel MCP Server for Claude. 248 tools — 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",

package/templates/action-schemas.json

@@ -92,7 +92,7 @@
       "convertToMultipath": false,
       "transitions": []
     },
-    "notes": "startAfter.type: 'minutes', 'hour', or 'days' — NOT consistently singular, and 'day' is rejected with 400 INVALID_FIELD_VALUE on a workflow that has a real action before the wait (live-verified 2026-08-29). ALL 5 fields required (type, startAfter, isHybridAction, hybridActionType, transitions). Derived from working GHL UI-built workflows."
+    "notes": "startAfter.type: 'minutes', 'hour', or 'days' \u2014 NOT consistently singular, and 'day' is rejected with 400 INVALID_FIELD_VALUE on a workflow that has a real action before the wait (live-verified 2026-08-29). ALL 5 fields required (type, startAfter, isHybridAction, hybridActionType, transitions). Derived from working GHL UI-built workflows."
   },
   "internal_notification": {
     "example": {
@@ -106,7 +106,7 @@
         "selectedUser": "USER_ID"
       }
     },
-    "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.",
+    "notes": "Nested 'notification' object REQUIRED. \u26a0\ufe0f READ THE userType FIRST \u2014 the empty-string rule is SCOPED TO IT, and reading it unscoped makes this entry look like it contradicts intake-to-build/executor.ts. It does not. (a) userType:'user' \u2192 selectedUser MUST be a real user ID; an EMPTY STRING IS REJECTED (live-verified 2026-08-06; the old 'empty = all users' behaviour is gone). Use get_users. (b) userType:'all' \u2192 selectedUser:'' is the CORRECT and live-proven placeholder shape, not a defect; executor.ts:660-688 emits it deliberately when no staff member is resolvable yet, and executor.test.ts:1281-1289 pins it. Never flag (b) as missing a recipient. The ONLY broken combination is userType:'user' with a blank selectedUser. 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": {
@@ -153,19 +153,30 @@
       "type": "task-notification",
       "__customInputs__": {}
     },
-    "notes": "dueDate is days from now as string. assignedTo is a user ID."
+    "notes": "dueDate is days from now as string. assignedTo is a user ID. \u26a0\ufe0f THE TYPE MUST BE HYPHENATED. The underscore form `task_notification` SAVES, VALIDATES and PUBLISHES and is then SILENTLY SKIPPED AT RUNTIME \u2014 no task is ever created and no error is shown anywhere (live-verified 2026-06-12 on the GHL Command sale alert). If you searched this file for `task_notification` and found nothing, that empty result IS the bug: the key here is `task-notification`."
   },
   "assign_user": {
     "example": {
       "type": "assign_user",
-      "user_list": ["USER_ID"],
+      "user_list": [
+        "USER_ID"
+      ],
       "only_unassigned_contact": false,
       "traffic_split": "equally",
-      "traffic_weightage": { "USER_ID": 1 },
-      "traffic_index": [{ "id": "USER_ID", "indexes": [1] }],
+      "traffic_weightage": {
+        "USER_ID": 1
+      },
+      "traffic_index": [
+        {
+          "id": "USER_ID",
+          "indexes": [
+            1
+          ]
+        }
+      ],
       "total_index": 1
     },
-    "notes": "[PROVEN LIVE 2026-08-27 on the MCP Testing sandbox: a scratch workflow carrying both a single-user and a two-user round-robin assign_user node saved, read back with every attribute intact (user_list, only_unassigned_contact, traffic_split, traffic_weightage, traffic_index, total_index) and both real user ids present, and PUBLISHED — GHL's own builder validator accepted it, which is the check that requires a non-empty user_list and verifies each id against the location's users. Scratch workflow deleted; the account was left byte-identical.] 'Assign to user' — the listed users become the contact owner. Linear actions-category node like add_contact_tag. user_list is REQUIRED and non-empty (GHL's builder validator: 'user_list_required'; every id is checked against the location's users — a dead id silently never assigns). Multiple users = round-robin; the equal-split bookkeeping the builder saves is weightage {id:1 each}, traffic_index [{id, indexes:[1..weight]}] with globally sequential indexes, total_index = sum of weights — single user: weightage {id:1}, index [{id, indexes:[1]}], total 1. only_unassigned_contact false always (re)assigns; true skips contacts that already have an owner. traffic_split 'unevenly' + custom weights and customUserList (custom-value mode) exist in the builder but are NOT built by us. LIVE TEST TO CLOSE: build one workflow with this node on a sandbox (MCP Testing), publish, run a test contact through, read back with get_workflow_full + get_contact — confirm the node persists byte-for-byte and the contact's assignedTo/owner becomes USER_ID; then remove this UNVERIFIED label."
+    "notes": "[PROVEN LIVE 2026-08-27 on the MCP Testing sandbox: a scratch workflow carrying both a single-user and a two-user round-robin assign_user node saved, read back with every attribute intact (user_list, only_unassigned_contact, traffic_split, traffic_weightage, traffic_index, total_index) and both real user ids present, and PUBLISHED \u2014 GHL's own builder validator accepted it, which is the check that requires a non-empty user_list and verifies each id against the location's users. Scratch workflow deleted; the account was left byte-identical.] 'Assign to user' \u2014 the listed users become the contact owner. Linear actions-category node like add_contact_tag. user_list is REQUIRED and non-empty (GHL's builder validator: 'user_list_required'; every id is checked against the location's users \u2014 a dead id silently never assigns). Multiple users = round-robin; the equal-split bookkeeping the builder saves is weightage {id:1 each}, traffic_index [{id, indexes:[1..weight]}] with globally sequential indexes, total_index = sum of weights \u2014 single user: weightage {id:1}, index [{id, indexes:[1]}], total 1. only_unassigned_contact false always (re)assigns; true skips contacts that already have an owner. traffic_split 'unevenly' + custom weights and customUserList (custom-value mode) exist in the builder but are NOT built by us. LIVE TEST TO CLOSE: build one workflow with this node on a sandbox (MCP Testing), publish, run a test contact through, read back with get_workflow_full + get_contact \u2014 confirm the node persists byte-for-byte and the contact's assignedTo/owner becomes USER_ID; then remove this UNVERIFIED label."
   },
   "remove_from_workflow": {
     "example": {
@@ -426,5 +437,17 @@
     "nurture_sequence": "Use linear workflow with stopOnResponse:true. Create separate 'exit workflows' triggered by tags (appointment-booked, do-not-contact) that use remove_from_workflow to pull contacts out. Do NOT use inline if/else gates at every step \u2014 this creates too many actions and can freeze GHL.",
     "exit_workflow": "Small 3-4 step workflow: remove_from_workflow \u2192 note \u2192 tag \u2192 notify. Triggered by a tag being added to the contact.",
     "max_actions": "Keep workflows under 40 actions. GHL's UI renderer struggles with larger workflows. Split into multiple connected workflows if needed."
+  },
+  "add_to_workflow": {
+    "example": {
+      "type": "add_to_workflow",
+      "name": "Add to: <Target Workflow Name>",
+      "attributes": {
+        "input_trigger_params": false,
+        "type": "add_to_workflow",
+        "workflow_id": "TARGET_WORKFLOW_ID"
+      }
+    },
+    "notes": "COPIED FROM A LIVE PUBLISHED NODE on a real account (read-only, 2026-09-01) \u2014 not derived from docs. \u26a0\ufe0f THIS IS NOT THE SAME SHAPE AS remove_from_workflow, which is the adjacent action and the easy mistake: remove needs BOTH `workflowId` (camelCase string) AND `workflow_id` (ARRAY). add needs NEITHER \u2014 `workflow_id` is snake_case and a SINGULAR STRING, there is no `workflowId` and no `workflowName`. `input_trigger_params: false` is present in the working node; purpose unknown, carry it. \u26a0\ufe0f KNOWN DIVERGENCE, UNRESOLVED: src/intake-to-build/executor.ts:806 emits the REMOVE shape under the ADD type (camelCase workflowId + workflowName + workflow_id as an ARRAY, no input_trigger_params). Whether GHL accepts and FIRES that variant is [UNVERIFIED] \u2014 a shape that saves and validates is not evidence it runs (cf. task_notification, wait unit \"day\", internal_notification \"inapp\"). Prove it on a sandbox before trusting either form."
   }
-}
+}