@elitedcs/ghl-mcp 3.64.1 → 3.65.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 3.65.0 — nine calls that reported success and did the wrong thing
+
+Found while building a 139-requirement home-care front office end to end. Every
+fix below has the same shape: the call succeeds, the response reads correctly,
+and something quietly did not happen. None raised an error. Four were findable
+only by firing the system and watching, not by reading settings back.
+
+**Three of these were damaging live accounts.**
+
+- **Fix: saving a calendar wiped its own settings.** Updating one field on a
+  calendar sent only that field, and GoHighLevel treated the omissions as
+  deletions — slot duration, slot interval, buffers and the entire open-hours
+  grid were erased. The call returned 200 and the calendar looked fine in the
+  list. Calendar updates now read the existing record first and merge; if that
+  read fails the update refuses rather than falling back to a write that would
+  clobber.
+- **Fix: saving a workflow silently deleted its quiet hours.** The update never
+  sent the sending-window field, so any workflow with contact-hour restrictions
+  lost them on the next save, with no warning. For anyone using quiet hours for
+  TCPA compliance, the protection disappeared the first time the workflow was
+  touched.
+- **Fix: every smart-list tool pointed at the wrong service.** All five called an
+  endpoint that does not serve contact smart lists, so they never worked.
+
+Silent no-ops:
+
+- **Fix: appointment triggers ignored the calendar you chose** and fired for every
+  calendar in the account. A caregiver interview booking would start the family
+  consultation sequence.
+- **Fix: reply triggers fired on every inbound message**, because the conditions
+  were emitted empty.
+- **Fix: moving a deal to a new stage did nothing** unless the workflow had first
+  looked the opportunity up. The step reported success at every save. Now caught
+  before the build runs.
+
+New:
+
+- **`create_contact_smart_list`, `get_contact_smart_list`, `delete_contact_smart_list`.**
+  238 tools total, 110 free.
+- **Calendar per-day limits and minimum booking notice** are now reachable
+  (`appointmentPerDay`, `allowBookingAfter`, `allowBookingAfterUnit`).
+- **Workflow quiet hours** can now be set through the tool — a sending window
+  with days, applied per workflow.
+- **Four trigger builders**: calendar-scoped appointments, reply-intent routing,
+  call status, and phone-number validation failures.
+
 ## 3.64.1 — three more calls that failed quietly
 
 - **Fix: client pricing was mangled on the way into a build plan.** The Blueprint

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**Full GoHighLevel API access for Claude.** 235 tools across 50 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.** 238 tools across 50 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).
 
@@ -8,7 +8,7 @@ Works with **both the Claude Desktop App and Claude Code terminal** — your cho
 
 **License required.** Get it at [ghlcommand.com](https://ghlcommand.com?utm_source=npm&utm_medium=readme) — $97/mo, covering UNLIMITED GoHighLevel sub-accounts on up to 3 machines (never billed per account). **30-day time-back guarantee**: save 5+ hours on one client build or your first month back.
 
-**Try it FREE (read-only tier).** Grab an instant free key at [ghlcommand.com/free](https://ghlcommand.com/free?utm_source=npm&utm_medium=readme) — 109 read-only tools on your own GHL account once the two-step install is finished (the same install as the paid tier — upgrading later is just a license swap): the account-wide workflow audit (`audit_workflows` finds the silently broken references GHL never warns you about), account health, and every read across contacts, pipelines, funnels, and workflows. Write tools stay visible and answer with upgrade info. Buying later with the same email upgrades your key in place — 1 machine on free, 3 when you upgrade.
+**Try it FREE (read-only tier).** Grab an instant free key at [ghlcommand.com/free](https://ghlcommand.com/free?utm_source=npm&utm_medium=readme) — 110 read-only tools on your own GHL account once the two-step install is finished (the same install as the paid tier — upgrading later is just a license swap): the account-wide workflow audit (`audit_workflows` finds the silently broken references GHL never warns you about), account health, and every read across contacts, pipelines, funnels, and workflows. Write tools stay visible and answer with upgrade info. Buying later with the same email upgrades your key in place — 1 machine on free, 3 when you upgrade.
 
 **How this differs from HighLevel's official MCP.** HighLevel ships an official Anthropic MCP that reads and writes your CRM (contacts, conversations, calendars, opportunities, payments, social) over the public API — it's free and it's good; use it for that. What it *cannot* do, because the public API doesn't expose it: **build or edit workflows, build funnels/landing pages, or build forms.** That's exactly what GHL Command does — the programmatic Workflow Builder, funnel/page builder, form builder, deep workflow cloning, the silent-failure `audit_workflows`, and Blueprint (build a whole client account from one intake — ships as a guided skill that **installs itself automatically** with this package; nothing to download), all on GHL's internal APIs. **Official MCP = read/write your CRM. GHL Command = build and fix it.** They stack fine together.
 
@@ -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 (235 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 (238 tools total with the optional Workflow Builder Firebase add-on).
 
 ### 4. Try it
 
@@ -518,7 +518,7 @@ Highlights (full guide: [`docs/HEADLESS.md`](docs/HEADLESS.md)):
 |---|---|
 | `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 52 additional Firebase-gated tools (workflow builder, funnel builder, form builder, pipeline builder, workflow cloner, smart lists, reputation, email campaigns, email templates, memberships, validate_workflow). 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 55 additional Firebase-gated tools (workflow builder, funnel builder, form builder, pipeline builder, workflow cloner, smart lists, reputation, email campaigns, email templates, memberships, validate_workflow). 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
 
@@ -798,7 +798,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 235 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 238 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

@@ -1648,7 +1648,7 @@ Note: Firebase credentials rejected (${fb.error}).`;
       const telemetryLine = telemetryDisabled(process.env) ? "" : `
 
 ${TELEMETRY_DISCLOSURE}`;
-      const finishedCount = isFree ? "109" : "235";
+      const finishedCount = isFree ? "110" : "238";
       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` : "";
@@ -1693,7 +1693,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 52 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 183 to 235 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 183 to 238 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
@@ -1774,7 +1774,7 @@ DevTools steps: https://elitedcs.com/ghl-mcp-firebase`
             "",
             "**You MUST restart Claude before using any workflow-builder tool.** Quit Claude completely (Cmd+Q on Mac, full exit on Windows) and reopen. Without a restart, the workflow builder tools will keep using the OLD Firebase auth from before this call and fail with 401 errors \u2014 even though this tool reported success.",
             "",
-            'After restart, all 235 tools load. Try: "List my workflows in full detail" or "Validate workflow <id>".',
+            'After restart, all 238 tools load. Try: "List my workflows in full detail" or "Validate workflow <id>".',
             "",
             "Note: Firebase refresh tokens rotate every few weeks. If workflow tools stop working in a few weeks (run `health_check` to confirm Firebase auth: FAIL), run `auto_capture_firebase_script` for fresh values and re-run this tool with the new firebase_paste."
           ].join("\n")
@@ -1870,7 +1870,7 @@ The login in the capture window may belong to the wrong GHL account, or the sess
               "",
               "**You MUST restart Claude before using any workflow-builder tool.** Quit Claude completely (Cmd+Q on Mac, full exit on Windows) and reopen.",
               "",
-              'After restart, all 235 tools load. Try: "List my workflows in full detail".',
+              'After restart, all 238 tools load. Try: "List my workflows in full detail".',
               "",
               "Future token rotations re-capture silently \u2014 if workflow tools ever 401, just run capture_firebase_interactive again; no window should appear."
             ].join("\n")
@@ -2854,9 +2854,9 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.64.1",
+      version: "3.65.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
-      description: "GoHighLevel MCP Server for Claude. 235 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. 238 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"
@@ -6271,6 +6271,9 @@ ${errorBody}`
       allowMultipleOpportunity: updates.allowMultipleOpportunity ?? current.allowMultipleOpportunity ?? false,
       autoMarkAsRead: updates.autoMarkAsRead ?? current.autoMarkAsRead ?? false,
       removeContactFromLastStep: updates.removeContactFromLastStep ?? current.removeContactFromLastStep ?? true,
+      // Preserve unless explicitly set (including an explicit null to clear).
+      // `?? ` would be wrong here — null is a meaningful value.
+      window: updates.window !== void 0 ? updates.window : current.window ?? null,
       workflowData: { templates: linkedActions },
       updatedBy: this.userId,
       // Triggers live in Firestore and are managed out-of-band; the workflow
@@ -7593,6 +7596,9 @@ function applyCalendarFields(body, args) {
   if (args.slotBuffer !== void 0) body.slotBuffer = args.slotBuffer;
   if (args.slotInterval !== void 0) body.slotInterval = args.slotInterval;
   if (args.appointmentPerSlot !== void 0) body.appointmentPerSlot = args.appointmentPerSlot;
+  if (args.appointmentPerDay !== void 0) body.appointmentPerDay = args.appointmentPerDay;
+  if (args.allowBookingAfter !== void 0) body.allowBookingAfter = args.allowBookingAfter;
+  if (args.allowBookingAfterUnit !== void 0) body.allowBookingAfterUnit = args.allowBookingAfterUnit;
   if (args.openHours !== void 0) {
     body.openHours = expandOpenHours(args.openHours);
     body.availabilityType = args.availabilityType ?? 0;
@@ -7614,6 +7620,30 @@ function buildUpdateCalendarBody(args) {
   applyCalendarFields(body, args);
   return body;
 }
+var MERGE_PRESERVED_FIELDS = [
+  "slotDuration",
+  "slotInterval",
+  "slotBuffer",
+  "appointmentPerSlot",
+  "appointmentPerDay",
+  "allowBookingAfter",
+  "allowBookingAfterUnit",
+  "availabilityType"
+];
+function mergeCalendarUpdate(existing, args) {
+  if (!existing) return args;
+  const merged = { ...args };
+  for (const key of MERGE_PRESERVED_FIELDS) {
+    if (merged[key] === void 0 && existing[key] !== void 0 && existing[key] !== "") {
+      merged[key] = existing[key];
+    }
+  }
+  if (merged.openHours === void 0) {
+    const hours = existing.openHours;
+    if (Array.isArray(hours) && hours.length > 0) merged.openHours = hours;
+  }
+  return merged;
+}
 function tzOffsetMillis(utcMillis, timeZone) {
   const dtf = new Intl.DateTimeFormat("en-US", {
     timeZone,
@@ -7724,6 +7754,9 @@ function registerCalendarTools(server2, client) {
       slotBuffer: import_zod12.z.number().optional().describe("Buffer time between slots in minutes"),
       slotInterval: import_zod12.z.number().optional().describe("Slot interval in minutes"),
       appointmentPerSlot: import_zod12.z.number().optional().describe("Max appointments per slot"),
+      appointmentPerDay: import_zod12.z.number().optional().describe("Max appointments bookable per DAY on this calendar (the daily ceiling, distinct from appointmentPerSlot). Without it the day's capacity is whatever the open hours allow."),
+      allowBookingAfter: import_zod12.z.number().optional().describe("Minimum advance notice before a slot can be booked, in allowBookingAfterUnit. E.g. 24 with unit 'hours' blocks same-day and short-notice bookings."),
+      allowBookingAfterUnit: import_zod12.z.string().optional().describe("Unit for allowBookingAfter: 'minutes' | 'hours' | 'days'. Send alongside allowBookingAfter."),
       openHours: import_zod12.z.array(OpenHoursBlockSchema).optional().describe(
         "Weekly business hours that make slots bookable (the 'assign availability hours' step). Each entry maps weekdays (0=Sun \u2026 6=Sat) to one or more open windows on a 24-hour clock; multi-day entries are auto-expanded to GHL's required one-block-per-day form. Example Mon-Fri 9-6 + Sat 10-1: [{daysOfTheWeek:[1,2,3,4,5],hours:[{openHour:9,openMinute:0,closeHour:18,closeMinute:0}]},{daysOfTheWeek:[6],hours:[{openHour:10,openMinute:0,closeHour:13,closeMinute:0}]}]. Behavior (verified live): on event/simple calendars these hours are the sole source of availability. On round_robin calendars the bookable slots are the INTERSECTION of these hours and each assigned user's working hours, so a day only opens if a team member is also available then (e.g. a Saturday window needs a user with Saturday availability). Omit to use GHL's defaults."
       ),
@@ -7753,13 +7786,26 @@ function registerCalendarTools(server2, client) {
       slotBuffer: import_zod12.z.number().optional().describe("Buffer time between slots in minutes"),
       slotInterval: import_zod12.z.number().optional().describe("Slot interval in minutes"),
       appointmentPerSlot: import_zod12.z.number().optional().describe("Max appointments per slot"),
+      appointmentPerDay: import_zod12.z.number().optional().describe("Max appointments bookable per DAY on this calendar (the daily ceiling, distinct from appointmentPerSlot)."),
+      allowBookingAfter: import_zod12.z.number().optional().describe("Minimum advance notice before a slot can be booked, in allowBookingAfterUnit. E.g. 24 with unit 'hours' blocks same-day and short-notice bookings."),
+      allowBookingAfterUnit: import_zod12.z.string().optional().describe("Unit for allowBookingAfter: 'minutes' | 'hours' | 'days'. Send alongside allowBookingAfter."),
       openHours: import_zod12.z.array(OpenHoursBlockSchema).optional().describe(
         "Weekly business hours that make slots bookable. Each entry maps weekdays (0=Sun \u2026 6=Sat) to one or more open windows on a 24-hour clock; multi-day entries are auto-expanded to GHL's required one-block-per-day form (e.g. [{daysOfTheWeek:[1,2,3,4,5],hours:[{openHour:9,openMinute:0,closeHour:18,closeMinute:0}]}] = Mon-Fri 9am-6pm). Replaces the calendar's existing hours. Behavior (verified live): event/simple calendars use these hours directly; round_robin calendars intersect them with each assigned user's working hours (a day only opens if a team member is available then)."
       ),
       availabilityType: import_zod12.z.number().int().optional().describe("Availability mode. 0 = standard weekly hours (from openHours); auto-set when you pass openHours. Leave unset otherwise.")
     },
     async (args) => {
-      const body = buildUpdateCalendarBody(args);
+      let existing;
+      try {
+        const current = await client.get(`/calendars/${args.calendarId}`);
+        const cal = current?.calendar ?? current;
+        if (cal && typeof cal === "object") existing = cal;
+      } catch (e) {
+        throw new Error(
+          `update_calendar: could not read calendar ${args.calendarId} before updating it (${e instanceof Error ? e.message : String(e)}). Refusing to write: GHL's calendar update does not merge, so a partial write here would silently reset this calendar's slot length, buffer and availability hours.`
+        );
+      }
+      const body = buildUpdateCalendarBody(mergeCalendarUpdate(existing, args));
       return await client.put(`/calendars/${args.calendarId}`, { body });
     }
   );
@@ -10380,9 +10426,17 @@ function registerWorkflowBuilderTools(server2, client) {
       stopOnResponse: import_zod36.z.boolean().optional().describe("Stop the workflow when the contact replies. If omitted, the current value is preserved."),
       autoMarkAsRead: import_zod36.z.boolean().optional().describe("Auto-mark conversations as read. If omitted, the current value is preserved."),
       removeContactFromLastStep: import_zod36.z.boolean().optional().describe("Remove the contact when they reach the last step. If omitted, the current value is preserved."),
-      allowMultipleOpportunity: import_zod36.z.boolean().optional().describe("Allow creating multiple opportunities. If omitted, the current value is preserved.")
+      allowMultipleOpportunity: import_zod36.z.boolean().optional().describe("Allow creating multiple opportunities. If omitted, the current value is preserved."),
+      window: import_zod36.z.object({
+        condition: import_zod36.z.string().describe('Usually "when" \u2014 run only DURING the window.'),
+        start: import_zod36.z.string().describe('Start of the window, 24-hour "HH:MM" (e.g. "08:00").'),
+        end: import_zod36.z.string().describe('End of the window, 24-hour "HH:MM" (e.g. "21:00").'),
+        days: import_zod36.z.array(import_zod36.z.number().int().min(0).max(6)).describe("Days the window applies to. 0=Sunday \u2026 6=Saturday.")
+      }).nullable().optional().describe(
+        `EXECUTION WINDOW \u2014 the hours this workflow is allowed to run. This is where quiet hours / TCPA contact-hour restrictions are enforced: there is NO time-of-day setting inside the Voice AI or Conversation AI builders, so a "never text before 8am or after 9pm" rule has to live here, on every workflow that sends SMS. Example: {condition:"when", start:"08:00", end:"21:00", days:[0,1,2,3,4,5,6]}. Pass null to clear. OMIT to preserve the workflow's existing window (it was previously dropped from the payload entirely, so saving a workflow silently wiped its window).`
+      )
     },
-    async ({ workflowId, name, status, actions, triggers, allowMultiple, stopOnResponse, autoMarkAsRead, removeContactFromLastStep, allowMultipleOpportunity }) => {
+    async ({ workflowId, name, status, actions, triggers, allowMultiple, stopOnResponse, autoMarkAsRead, removeContactFromLastStep, allowMultipleOpportunity, window }) => {
       try {
         const result = await client.updateWorkflow(workflowId, {
           name,
@@ -10393,7 +10447,8 @@ function registerWorkflowBuilderTools(server2, client) {
           stopOnResponse,
           autoMarkAsRead,
           removeContactFromLastStep,
-          allowMultipleOpportunity
+          allowMultipleOpportunity,
+          window
         });
         return jsonResponse(result);
       } catch (error) {
@@ -13681,6 +13736,33 @@ function registerWorkflowClonerTools(server2, builderClient) {
 var import_zod48 = require("zod");
 var SMARTLIST_BASE = "https://backend.leadconnectorhq.com/lists/dynamic";
 var OBJECT_KEYS = ["contacts", "opportunity"];
+var CONTACT_SMARTLIST_BASE = "https://services.leadconnectorhq.com/contacts/smartlist";
+var CONTACT_SMARTLIST_DELETE = "https://api.leadconnectorhq.com/smartlist/delete";
+var DEFAULT_CONTACT_SMARTLIST_COLUMNS = [
+  { key: "name", value: "name", order: 0 },
+  { key: "phone", value: "phone", order: 1 },
+  { key: "email", value: "email", order: 2 },
+  { key: "companyName", value: "companyName", order: 3 },
+  { key: "dateAdded", value: "dateAdded", order: 4 },
+  { key: "lastActivity", value: "lastActivity", order: 5 },
+  { key: "tags", value: "tags", order: 6 }
+];
+function buildContactTagFilter(tagNames) {
+  return { field: "tags", operator: "eq", value: tagNames, options: { minimumMatch: "all" } };
+}
+function buildContactSmartListBody(args) {
+  return {
+    columns: args.columns ?? DEFAULT_CONTACT_SMARTLIST_COLUMNS,
+    filterSpecs: {
+      filters: [{ group: "OR", filters: [{ group: "AND", filters: args.filters }] }],
+      page: 1,
+      limit: args.limit ?? 20
+    },
+    listName: args.listName,
+    sortSpecs: [],
+    locationId: args.locationId
+  };
+}
 function registerSmartListTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
@@ -13714,6 +13796,19 @@ ${text2}`);
     async ({ objectKey, query, limit, startAfter, locationId: locationId2 }) => {
       try {
         const loc = locationId2 ?? client.locationId;
+        if (objectKey === "contacts") {
+          const headers = await client.buildHeaders();
+          const p = new URLSearchParams({
+            locationId: loc,
+            userId: client.getUserId(),
+            globals: "true",
+            transform: "true"
+          });
+          const res = await fetch(`${CONTACT_SMARTLIST_BASE}/search?${p.toString()}`, { headers });
+          if (!res.ok) throw new Error(`Smart Lists API Error ${res.status}: GET /contacts/smartlist/search
+${await res.text()}`);
+          return jsonResponse(JSON.parse(await res.text() || "{}"));
+        }
         const params = new URLSearchParams({ objectKey });
         if (query) params.set("query", query);
         if (limit !== void 0) params.set("limit", String(limit));
@@ -13725,6 +13820,74 @@ ${text2}`);
       }
     }
   );
+  server2.tool(
+    "create_contact_smart_list",
+    "Create a CONTACT smart list (saved filter over contacts) with working filters \u2014 the owner-exception views a dashboard needs. Uses GHL's contacts/smartlist service and its captured OR-of-AND filter envelope. `tagFilters` is the common case: each entry is a list of tag names the contact must ALL carry. For anything else pass `rawFilters` (leaf objects: {field, operator, value, options}). NOTE: create_smart_list (the older tool) targets the opportunity-list service and cannot express contact filters.",
+    {
+      name: import_zod48.z.string().describe("Display name for the smart list."),
+      tagFilters: import_zod48.z.array(import_zod48.z.array(import_zod48.z.string())).optional().describe('Tag conditions. Each inner array is one filter requiring ALL those tags, e.g. [["escalated"]] for "has the escalated tag".'),
+      rawFilters: import_zod48.z.array(import_zod48.z.record(import_zod48.z.unknown())).optional().describe("Advanced: raw filter leaves {field, operator, value, options}. Combined with tagFilters into one AND group."),
+      locationId: import_zod48.z.string().optional().describe("Location ID. Falls back to the active builder client's location.")
+    },
+    async ({ name, tagFilters, rawFilters, locationId: locationId2 }) => {
+      try {
+        const loc = locationId2 ?? client.locationId;
+        const filters = [
+          ...(tagFilters ?? []).map((tags) => buildContactTagFilter(tags)),
+          ...rawFilters ?? []
+        ];
+        const body = buildContactSmartListBody({ listName: name, locationId: loc, filters });
+        const headers = await client.buildHeaders();
+        const res = await fetch(CONTACT_SMARTLIST_BASE, { method: "POST", headers, body: JSON.stringify(body) });
+        if (!res.ok) throw new Error(`Smart Lists API Error ${res.status}: POST /contacts/smartlist
+${await res.text()}`);
+        return jsonResponse(JSON.parse(await res.text() || "{}"));
+      } catch (error) {
+        return errorResponse(error);
+      }
+    }
+  );
+  server2.tool(
+    "get_contact_smart_list",
+    "Get a CONTACT smart list by id INCLUDING its filterSpecs. Use this to verify a contact smart list's filters after creating it \u2014 get_smart_list targets the opportunity-list service and returns the record without any filters, which reads as 'no filters set'.",
+    {
+      listId: import_zod48.z.string().describe("The contact smart list id.")
+    },
+    async ({ listId }) => {
+      try {
+        const headers = await client.buildHeaders();
+        const res = await fetch(`${CONTACT_SMARTLIST_BASE}/${listId}?transform=true`, { headers });
+        if (!res.ok) throw new Error(`Smart Lists API Error ${res.status}: GET /contacts/smartlist/${listId}
+${await res.text()}`);
+        return jsonResponse(JSON.parse(await res.text() || "{}"));
+      } catch (error) {
+        return errorResponse(error);
+      }
+    }
+  );
+  server2.tool(
+    "delete_contact_smart_list",
+    "Delete a CONTACT smart list by id.",
+    {
+      listId: import_zod48.z.string().describe("The contact smart list id."),
+      confirm: import_zod48.z.literal("DELETE").describe('Type "DELETE" to confirm.')
+    },
+    async ({ listId }) => {
+      try {
+        const headers = await client.buildHeaders();
+        const res = await fetch(CONTACT_SMARTLIST_DELETE, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ smartlist_id: listId })
+        });
+        if (!res.ok) throw new Error(`Smart Lists API Error ${res.status}: POST /smartlist/delete
+${await res.text()}`);
+        return jsonResponse(JSON.parse(await res.text() || "{}"));
+      } catch (error) {
+        return errorResponse(error);
+      }
+    }
+  );
   server2.tool(
     "get_smart_list",
     "Get a single smart list by ID with its full configuration: filters, columns, permissions, and metadata. The filters array is what defines who/what is in the list.",
@@ -16320,6 +16483,8 @@ var findOpportunitySchema = import_zod58.z.object({
 });
 var actionSchema = import_zod58.z.discriminatedUnion("type", [...branchActionOptions, findOpportunitySchema]);
 var APPOINTMENT_STATUSES = ["new", "confirmed", "showed", "noshow", "cancelled", "invalid"];
+var CALL_STATUSES = ["busy", "canceled", "voicemail", "no-answer", "completed"];
+var NUMBER_VALIDATION_STATES = ["not_valid", "sms_incapable"];
 var triggerSchema = import_zod58.z.object({
   type: import_zod58.z.string(),
   formRef: nsRef("form").optional(),
@@ -16328,7 +16493,34 @@ var triggerSchema = import_zod58.z.object({
   pipelineRef: nsRef("pipeline").optional(),
   stageRef: nsRef("stage").optional(),
   // Required for a native `appointment` trigger (the status it fires on).
-  appointmentStatus: import_zod58.z.enum(APPOINTMENT_STATUSES).optional()
+  appointmentStatus: import_zod58.z.enum(APPOINTMENT_STATUSES).optional(),
+  // ── customer_reply scoping ──────────────────────────────────────
+  // A bare customer_reply trigger fires on EVERY inbound reply from EVERY
+  // contact. That is almost never what a plan means: "alert the owner when a
+  // referral partner replies" must not fire for a family's reply. GHL's
+  // ContactReplyFilter supports both of these (see templates/trigger-schemas.json):
+  //   hasTagRef   → contact.tags / index-of-true  (only replies from contacts
+  //                 carrying this tag)
+  //   replyIntent → message.body / matches_intent (GHL classifies the reply as
+  //                 a positive or negative response; the option values are
+  //                 "schedule-yes" and "schedule-no")
+  // Both optional and additive — omitting them keeps the long-standing
+  // fires-on-any-reply baseline.
+  hasTagRef: nsRef("tag").optional(),
+  replyIntent: import_zod58.z.enum(["positive", "negative"]).optional(),
+  // ── call_status scoping (missed-call text-back) ─────────────────
+  // GHL's call_status trigger fires on a completed call attempt. The states it
+  // exposes are exactly what a "missed call" means operationally. Required for
+  // a call_status trigger — without them the trigger would fire on EVERY call
+  // including answered ones, so the executor refuses rather than guess.
+  callStatuses: import_zod58.z.array(import_zod58.z.enum(CALL_STATUSES)).optional(),
+  callDirection: import_zod58.z.enum(["inbound", "outbound"]).optional(),
+  // ── validation_error (GHL UI: "Number validation") ──────────────
+  // Fires after a phone number passes or fails a validation check. The UI shows
+  // "Not valid" / "SMS incapable"; the WIRE values are snake_case. Required for
+  // a validation_error trigger — without them the executor refuses rather than
+  // guess which failure states to fire on.
+  numberValidation: import_zod58.z.array(import_zod58.z.enum(NUMBER_VALIDATION_STATES)).optional()
 });
 var workflowSchema = import_zod58.z.object({
   ref: nsRef("workflow"),
@@ -16447,6 +16639,7 @@ function checkRefIntegrity(plan, defined) {
       const t = w.trigger;
       check(t.formRef, "form", `workflows[${w.ref}].trigger.formRef`);
       check(t.tagRef, "tag", `workflows[${w.ref}].trigger.tagRef`);
+      check(t.hasTagRef, "tag", `workflows[${w.ref}].trigger.hasTagRef`);
       check(t.calendarRef, "calendar", `workflows[${w.ref}].trigger.calendarRef`);
       check(t.pipelineRef, "pipeline", `workflows[${w.ref}].trigger.pipelineRef`);
       check(t.stageRef, "stage", `workflows[${w.ref}].trigger.stageRef`);
@@ -16609,6 +16802,21 @@ function validateBuildPlan(input) {
       );
     }
   }
+  for (const wf of plan.workflows ?? []) {
+    let seenFind = false;
+    for (const a of wf.actions) {
+      if (a.type === "find_opportunity") {
+        seenFind = true;
+        continue;
+      }
+      if (a.type === "update_opportunity" && !seenFind) {
+        warnings.push(
+          `workflow "${wf.ref}" has an update_opportunity ("move to stage") with no find_opportunity before it \u2014 GHL updates the opportunity currently in workflow context, so with nothing loaded this action SILENTLY DOES NOTHING and the workflow carries on as if it worked. Put the move inside a find_opportunity "found" branch.`
+        );
+        break;
+      }
+    }
+  }
   const MAX_NODES = 40;
   for (const wf of plan.workflows ?? []) {
     let nodeCount = 0;
@@ -17158,18 +17366,87 @@ function expandTrigger(trigger, idx, idMap) {
     case "appointment": {
       const status = trigger.appointmentStatus;
       if (!status) return manual(`Set this workflow's appointment trigger in the GHL UI: ${triggerPlainEnglish(trigger, idx)} (the plan trigger has no appointmentStatus to fire on, e.g. confirmed / noshow).`);
+      const conditions = [
+        { operator: "==", field: "appointment.eventType", value: "normal", title: "Event Type", type: "select" },
+        { operator: "==", field: "appointment.status", value: status, title: "Appointment status is", type: "select" }
+      ];
+      const pending = [];
+      if (trigger.calendarRef) {
+        const calendarId = resolveId(trigger.calendarRef, idMap);
+        if (isPending(calendarId)) pending.push(trigger.calendarRef);
+        conditions.unshift({
+          operator: "==",
+          field: "calendar.id",
+          value: calendarId,
+          title: "In calendar",
+          type: "select"
+        });
+      }
       return native({
         name: `Appointment Status \u2014 ${status}`,
         type: "appointment",
+        conditions
+      }, pending);
+    }
+    case "call_status": {
+      const statuses = trigger.callStatuses;
+      if (!statuses || statuses.length === 0) {
+        return manual(
+          `Set this workflow's call trigger in the GHL UI and choose which call outcomes it fires on (e.g. no-answer, busy, voicemail for a missed call). Blueprint will not build it without them: an unscoped call trigger fires on EVERY call, answered ones included.`
+        );
+      }
+      const callConditions = [
+        { operator: "contains-any", field: "call_status", value: statuses, title: "Call Status" }
+      ];
+      if (trigger.callDirection) {
+        callConditions.push({
+          operator: "==",
+          field: "message.direction",
+          value: trigger.callDirection,
+          title: "Call Direction",
+          type: "select"
+        });
+      }
+      return native({ name: "Call Status", type: "call_status", conditions: callConditions });
+    }
+    case "validation_error": {
+      const states = trigger.numberValidation;
+      if (!states || states.length === 0) {
+        return manual(
+          `Set this workflow's "Number validation" trigger in the GHL UI and choose which states it fires on (Not valid / SMS incapable). Blueprint will not build it without them rather than guess which failures matter.`
+        );
+      }
+      return native({
+        name: "Number Validation",
+        type: "validation_error",
         conditions: [
-          { operator: "==", field: "appointment.eventType", value: "normal", title: "Event Type", type: "select" },
-          { operator: "==", field: "appointment.status", value: status, title: "Appointment status is", type: "select" }
+          { operator: "contains-any", field: "contact.phoneInfo", value: states, title: "Number is", type: "multiselect" }
         ]
       });
     }
     case "customer_reply":
     case "contact_replied": {
-      return native({ name: "Customer Replied", type: "customer_reply", conditions: [] });
+      const replyConditions = [];
+      if (trigger.hasTagRef) {
+        const tagName = idx.tagName.get(trigger.hasTagRef) ?? trigger.hasTagRef;
+        replyConditions.push({
+          operator: "index-of-true",
+          field: "contact.tags",
+          value: tagName,
+          title: "Has Tag",
+          type: "select"
+        });
+      }
+      if (trigger.replyIntent) {
+        replyConditions.push({
+          operator: "matches_intent",
+          field: "message.body",
+          value: trigger.replyIntent === "positive" ? "schedule-yes" : "schedule-no",
+          title: "Intent type",
+          type: "select"
+        });
+      }
+      return native({ name: "Customer Replied", type: "customer_reply", conditions: replyConditions });
     }
     case "pipeline_stage_updated": {
       if (!trigger.pipelineRef || !trigger.stageRef) return manual("Set this workflow's pipeline-stage trigger in the GHL UI (the plan trigger needs both a pipeline and a stage).");

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.64.1",
+  "version": "3.65.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
-  "description": "GoHighLevel MCP Server for Claude. 235 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.",
+  "description": "GoHighLevel MCP Server for Claude. 238 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

@@ -1,17 +1,17 @@
 {
   "_description": "AUTHORITATIVE REFERENCE: Correct GHL workflow action attribute schemas. Derived from real working workflows built in GHL UI. ALL sessions MUST use these exact formats.",
-  "_version": "2.0 — 2026-03-24",
+  "_version": "2.0 \u2014 2026-03-24",
   "_critical_rules": [
-    "NEVER use 'body' for emails — use 'html' with HTML markup",
-    "NEVER use 'tagName' — use 'tags' array",
-    "NEVER use 'duration' for waits — use startAfter object",
-    "NEVER use singular min units — real GHL uses 'minutes'",
+    "NEVER use 'body' for emails \u2014 use 'html' with HTML markup",
+    "NEVER use 'tagName' \u2014 use 'tags' array",
+    "NEVER use 'duration' for waits \u2014 use startAfter object",
+    "NEVER use singular min units \u2014 real GHL uses 'minutes'",
     "ALWAYS include 'attachments: []' on SMS actions",
     "ALWAYS include 'trackingOptions' on email actions",
     "ALWAYS include all 5 fields on wait actions (type, startAfter, isHybridAction, hybridActionType, transitions)",
     "ALWAYS use 'parent' AND 'parentKey' on branch nodes",
     "ALWAYS use 'sibling' arrays on branch-yes and branch-no nodes",
-    "NEVER use if_else as a single flat action — it is only valid on condition-node, branch-yes, and branch-no nodes",
+    "NEVER use if_else as a single flat action \u2014 it is only valid on condition-node, branch-yes, and branch-no nodes",
     "ALWAYS include workflow_id ARRAY in remove_from_workflow (not just workflowId string)",
     "For linear workflows, the buildActionChain needs BOTH next (forward) and parentKey (backward) on every action",
     "Keep workflows under 40 actions to avoid GHL UI renderer freezes",
@@ -48,10 +48,9 @@
         "hasTrackingLinks": false,
         "hasUtmTracking": false,
         "hasTags": false
-      },
-      "cc": "{{contact.sales_rep_email}}"
+      }
     },
-    "notes": "Use 'html' NOT 'body'. Content MUST be HTML with <p> tags. Subject supports merge fields. trackingOptions is REQUIRED. RECIPIENT: there is NO 'to' field — the email action ALWAYS sends to the enrolled contact (UI reads 'Send an email to the contact'). To copy a third party use attributes.cc (plain string, accepts merge fields e.g. {{contact.sales_rep_email}}); 'bcc' presumably mirrors it but is NOT live-verified. Never build a 'send to a third party' node expecting a To field — it silently mails the contact instead. (cc shape live-captured 2026-08-08, CLL.)"
+    "notes": "Use 'html' NOT 'body'. Content MUST be HTML with <p> tags. Subject supports merge fields. trackingOptions is REQUIRED."
   },
   "wait": {
     "example_1hour": {
@@ -107,7 +106,20 @@
         "selectedUser": ""
       }
     },
-    "notes": "Nested 'notification' object REQUIRED. selectedUser empty string for all users, or specific user ID."
+    "notes": "Nested 'notification' object REQUIRED. selectedUser empty string for all users, or specific user ID. 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": {
+        "isCloned": false,
+        "html": "<p style=\"margin:0px;\">We received a new Collector story.</p>",
+        "subject": "New Painting Collector Story Received",
+        "selectedUser": [
+          "<userId>"
+        ],
+        "userType": "user",
+        "attachments": []
+      }
+    }
   },
   "update_contact_field": {
     "example": {
@@ -173,7 +185,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 — 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) — 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": "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.",
@@ -297,7 +309,7 @@
         "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.",
+    "notes": "Goal-event nodes sit inline in the action chain \u2014 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 \u2014 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": {
@@ -378,8 +390,8 @@
     "notes": "Workflow GET requests must include ?includeTriggers=true or triggers silently disappear. Each trigger type has type-specific condition fields."
   },
   "_workflow_design_patterns": {
-    "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 — this creates too many actions and can freeze GHL.",
-    "exit_workflow": "Small 3-4 step workflow: remove_from_workflow → note → tag → notify. Triggered by a tag being added to the contact.",
+    "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."
   }
-}
+}