@elitedcs/ghl-mcp 3.34.8 → 3.34.10

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 3.34.10 — `get_free_slots` accepts ISO dates; `update_form` name fallback for fresh forms
+
+Two small fixes that close rough edges found while live-verifying v3.34.9 through
+the MCP tools. Neither changes a proven capability; both have trivial workarounds.
+
+- **`get_free_slots` now accepts ISO dates (its documented input) — not just epoch
+  milliseconds.** GHL's `GET /calendars/{id}/free-slots` requires `startDate` /
+  `endDate` as epoch **milliseconds** and 422s (`startDate must be a number…`) on an
+  ISO date, yet the tool's own schema documented `YYYY-MM-DD` and forwarded it
+  unconverted — so the documented input always failed. The tool now accepts a bare
+  `YYYY-MM-DD` (taken as start-of-day for `startDate`, end-of-day for `endDate`, in
+  the supplied `timezone`, default UTC), a full ISO datetime (`Date.parse`), or an
+  already-numeric epoch-millis value (passed through, back-compat) and converts to
+  the epoch ms GHL needs. Logic extracted to `buildFreeSlotsParams` / `toEpochMillis`
+  with tests (incl. the live Phoenix anchor `2026-06-15 → 1781506800000`).
+- **`update_form` no longer throws on the natural `create_form` → `update_form`
+  sequence.** When `name` is omitted, `update_form` reads the current name to
+  preserve it. A form freshly created by `create_form` has no `name` in its builder
+  doc until its first save, so that read returned none and the call threw
+  (`Could not resolve current form name`). It now falls back to the public forms list
+  (which carries the name) and only errors — with actionable guidance to pass `name`
+  — if both sources come up empty. The form-builder tools now also receive the public
+  `GHLClient` for this lookup (it already had Firebase auth for the builder routes).
+  Helpers `pickFormName` / `findFormNameInList` extracted, with tests.
+
+## 3.34.9 — Calendar availability: create_calendar / update_calendar now set `openHours`
+
+Closes the on-camera "assign availability hours" gap. `create_calendar` and
+`update_calendar` previously exposed no availability parameter, so every calendar
+was created with `openHours: {}` and a caller could not set business hours through
+the MCP — the calendar only offered GHL's default window.
+
+- **New `openHours` (and `availabilityType`) params on `create_calendar` and
+  `update_calendar`.** `openHours` is an array of `{daysOfTheWeek:[0-6], hours:
+  [{openHour,openMinute,closeHour,closeMinute}]}` (0=Sun … 6=Sat, 24-hour clock).
+  When `openHours` is supplied the builder also sends `availabilityType: 0`
+  (standard weekly hours) — the exact payload GHL honors — unless the caller
+  overrides it.
+- **Multi-day blocks are auto-expanded to one block per day.** GHL's CREATE
+  endpoint 422s (`openHours.0.must be a valid day of week`) on a block listing more
+  than one weekday. Single-day-per-block is GHL's own canonical form (what it reads
+  back) and is accepted by both create and update. The builder accepts the natural
+  compact form (`daysOfTheWeek:[1,2,3,4,5]`) and expands it to per-day blocks. Logic
+  extracted to `buildCreateCalendarBody` / `buildUpdateCalendarBody` /
+  `expandOpenHours`, with tests.
+
+**Corrects the 3.34.8 note.** The earlier guess — that round-robin availability
+comes only from the user's working hours and not a calendar `openHours` field — was
+wrong. Pinned live on a real sub-account, the full model is:
+
+- `openHours` **does** drive availability. Setting it changes `/free-slots`
+  immediately (a Wed-only 13:00–15:00 window collapsed slots to Wednesdays
+  13:00–14:30; a Mon–Fri 9–6 window produced exactly 09:00–17:30 each weekday).
+- On **event / simple** calendars `openHours` is the sole source — every configured
+  day/time becomes bookable (a Sat 10–1 window booked Saturdays).
+- On **round_robin** "OptimizeForAvailability" calendars the bookable slots are the
+  **intersection** of `openHours` and each assigned user's working hours, so a day
+  only opens if a team member is also available then (the same Sat 10–1 window
+  produced zero slots when the lone user had no Saturday availability). To open a day
+  on round_robin, set the user's availability too (UI-gated), or use an event-type
+  calendar where `openHours` alone controls. The tool descriptions state this.
+
+Write-verified live: created calendars with hours through the builders, read the
+hours back, and confirmed `/free-slots` returned exactly the configured days/times;
+all throwaways deleted. Suite 289 pass / 1 skip.
+
 ## 3.34.8 — create_opportunity + get_funnel_pages no longer 422 on omitted required params
 
 Two real defects found during a full end-to-end build test on a live sub-account

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.8",
+      version: "3.34.10",
       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",
@@ -2727,6 +2727,113 @@ var CalendarTeamMemberSchema = import_zod9.z.object({
   selected: import_zod9.z.boolean().describe("Whether this user is currently active on the calendar (true to enable)."),
   locationConfigurations: import_zod9.z.array(TeamMemberLocationConfigSchema).min(1).describe("At least one meeting-location config. Typical shape: [{kind:'custom', position:0, location:''}].")
 }).strict();
+var OpenHoursWindowSchema = import_zod9.z.object({
+  openHour: import_zod9.z.number().int().min(0).max(23).describe("Opening hour on a 24-hour clock (0-23)."),
+  openMinute: import_zod9.z.number().int().min(0).max(59).describe("Opening minute (0-59)."),
+  closeHour: import_zod9.z.number().int().min(0).max(23).describe("Closing hour on a 24-hour clock (0-23)."),
+  closeMinute: import_zod9.z.number().int().min(0).max(59).describe("Closing minute (0-59).")
+}).strict();
+var OpenHoursBlockSchema = import_zod9.z.object({
+  daysOfTheWeek: import_zod9.z.array(import_zod9.z.number().int().min(0).max(6)).min(1).describe("Weekdays this block applies to. 0=Sunday, 1=Monday, \u2026 6=Saturday."),
+  hours: import_zod9.z.array(OpenHoursWindowSchema).min(1).describe("One or more open time windows that apply to these days.")
+}).strict();
+function expandOpenHours(blocks) {
+  const out = [];
+  for (const block of blocks) {
+    for (const day of block.daysOfTheWeek) {
+      out.push({ daysOfTheWeek: [day], hours: block.hours });
+    }
+  }
+  return out;
+}
+function applyCalendarFields(body, args) {
+  if (args.description !== void 0) body.description = args.description;
+  if (args.slug !== void 0) body.slug = args.slug;
+  if (args.widgetSlug !== void 0) body.widgetSlug = args.widgetSlug;
+  if (args.calendarType !== void 0) body.calendarType = args.calendarType;
+  if (args.teamMembers !== void 0) body.teamMembers = args.teamMembers;
+  if (args.eventTitle !== void 0) body.eventTitle = args.eventTitle;
+  if (args.eventColor !== void 0) body.eventColor = args.eventColor;
+  if (args.slotDuration !== void 0) body.slotDuration = args.slotDuration;
+  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.openHours !== void 0) {
+    body.openHours = expandOpenHours(args.openHours);
+    body.availabilityType = args.availabilityType ?? 0;
+  } else if (args.availabilityType !== void 0) {
+    body.availabilityType = args.availabilityType;
+  }
+}
+function buildCreateCalendarBody(args, resolvedLocationId) {
+  const body = {
+    locationId: resolvedLocationId,
+    name: args.name
+  };
+  applyCalendarFields(body, args);
+  return body;
+}
+function buildUpdateCalendarBody(args) {
+  const body = {};
+  if (args.name !== void 0) body.name = args.name;
+  applyCalendarFields(body, args);
+  return body;
+}
+function tzOffsetMillis(utcMillis, timeZone) {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hourCycle: "h23",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit"
+  });
+  const parts = dtf.formatToParts(new Date(utcMillis));
+  const get = (type) => Number(parts.find((p) => p.type === type)?.value);
+  const asUTC = Date.UTC(get("year"), get("month") - 1, get("day"), get("hour"), get("minute"), get("second"));
+  return asUTC - utcMillis;
+}
+function zonedStartOfDayMillis(year, month, day, timeZone) {
+  const utcGuess = Date.UTC(year, month - 1, day, 0, 0, 0, 0);
+  if (!timeZone) return utcGuess;
+  return utcGuess - tzOffsetMillis(utcGuess, timeZone);
+}
+function zonedDayBoundaryMillis(year, month, day, endOfDay, timeZone) {
+  if (endOfDay) return zonedStartOfDayMillis(year, month, day + 1, timeZone) - 1;
+  return zonedStartOfDayMillis(year, month, day, timeZone);
+}
+function toEpochMillis(value, opts = {}) {
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) {
+    if (trimmed.length === 13) return trimmed;
+    throw new Error(`Ambiguous numeric date "${value}" for free-slots \u2014 pass epoch MILLISECONDS (13 digits), a YYYY-MM-DD date, or a full ISO datetime.`);
+  }
+  const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
+  if (dateOnly) {
+    const millis = zonedDayBoundaryMillis(
+      Number(dateOnly[1]),
+      Number(dateOnly[2]),
+      Number(dateOnly[3]),
+      Boolean(opts.endOfDay),
+      opts.timeZone
+    );
+    return String(millis);
+  }
+  const parsed = Date.parse(trimmed);
+  if (!Number.isNaN(parsed)) return String(parsed);
+  throw new Error(`Invalid date "${value}" for free-slots \u2014 use YYYY-MM-DD, a full ISO datetime, or epoch milliseconds.`);
+}
+function buildFreeSlotsParams(args) {
+  const params = {
+    startDate: toEpochMillis(args.startDate, { timeZone: args.timezone }),
+    endDate: toEpochMillis(args.endDate, { endOfDay: true, timeZone: args.timezone })
+  };
+  if (args.timezone !== void 0) params.timezone = args.timezone;
+  if (args.userId !== void 0) params.userId = args.userId;
+  return params;
+}
 function registerCalendarTools(server2, client) {
   safeTool(
     server2,
@@ -2771,25 +2878,15 @@ function registerCalendarTools(server2, client) {
       slotDuration: import_zod9.z.number().optional().describe("Slot duration in minutes"),
       slotBuffer: import_zod9.z.number().optional().describe("Buffer time between slots in minutes"),
       slotInterval: import_zod9.z.number().optional().describe("Slot interval in minutes"),
-      appointmentPerSlot: import_zod9.z.number().optional().describe("Max appointments per slot")
+      appointmentPerSlot: import_zod9.z.number().optional().describe("Max appointments per slot"),
+      openHours: import_zod9.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."
+      ),
+      availabilityType: import_zod9.z.number().int().optional().describe("Availability mode. 0 = standard weekly hours (from openHours); auto-set when you pass openHours. Leave unset otherwise.")
     },
-    async ({ locationId: locationId2, name, description, slug, widgetSlug, calendarType, teamMembers, eventTitle, eventColor, slotDuration, slotBuffer, slotInterval, appointmentPerSlot }) => {
-      const resolvedLocationId = client.resolveLocationId(locationId2);
-      const body = {
-        locationId: resolvedLocationId,
-        name
-      };
-      if (description !== void 0) body.description = description;
-      if (slug !== void 0) body.slug = slug;
-      if (widgetSlug !== void 0) body.widgetSlug = widgetSlug;
-      if (calendarType !== void 0) body.calendarType = calendarType;
-      if (teamMembers !== void 0) body.teamMembers = teamMembers;
-      if (eventTitle !== void 0) body.eventTitle = eventTitle;
-      if (eventColor !== void 0) body.eventColor = eventColor;
-      if (slotDuration !== void 0) body.slotDuration = slotDuration;
-      if (slotBuffer !== void 0) body.slotBuffer = slotBuffer;
-      if (slotInterval !== void 0) body.slotInterval = slotInterval;
-      if (appointmentPerSlot !== void 0) body.appointmentPerSlot = appointmentPerSlot;
+    async (args) => {
+      const resolvedLocationId = client.resolveLocationId(args.locationId);
+      const body = buildCreateCalendarBody(args, resolvedLocationId);
       return await client.post("/calendars/", { body });
     }
   );
@@ -2810,23 +2907,15 @@ function registerCalendarTools(server2, client) {
       slotDuration: import_zod9.z.number().optional().describe("Slot duration in minutes"),
       slotBuffer: import_zod9.z.number().optional().describe("Buffer time between slots in minutes"),
       slotInterval: import_zod9.z.number().optional().describe("Slot interval in minutes"),
-      appointmentPerSlot: import_zod9.z.number().optional().describe("Max appointments per slot")
+      appointmentPerSlot: import_zod9.z.number().optional().describe("Max appointments per slot"),
+      openHours: import_zod9.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_zod9.z.number().int().optional().describe("Availability mode. 0 = standard weekly hours (from openHours); auto-set when you pass openHours. Leave unset otherwise.")
     },
-    async ({ calendarId, name, description, slug, widgetSlug, calendarType, teamMembers, eventTitle, eventColor, slotDuration, slotBuffer, slotInterval, appointmentPerSlot }) => {
-      const body = {};
-      if (name !== void 0) body.name = name;
-      if (description !== void 0) body.description = description;
-      if (slug !== void 0) body.slug = slug;
-      if (widgetSlug !== void 0) body.widgetSlug = widgetSlug;
-      if (calendarType !== void 0) body.calendarType = calendarType;
-      if (teamMembers !== void 0) body.teamMembers = teamMembers;
-      if (eventTitle !== void 0) body.eventTitle = eventTitle;
-      if (eventColor !== void 0) body.eventColor = eventColor;
-      if (slotDuration !== void 0) body.slotDuration = slotDuration;
-      if (slotBuffer !== void 0) body.slotBuffer = slotBuffer;
-      if (slotInterval !== void 0) body.slotInterval = slotInterval;
-      if (appointmentPerSlot !== void 0) body.appointmentPerSlot = appointmentPerSlot;
-      return await client.put(`/calendars/${calendarId}`, { body });
+    async (args) => {
+      const body = buildUpdateCalendarBody(args);
+      return await client.put(`/calendars/${args.calendarId}`, { body });
     }
   );
   safeTool(
@@ -2847,15 +2936,13 @@ function registerCalendarTools(server2, client) {
     "Get available free slots for a calendar",
     {
       calendarId: import_zod9.z.string().describe("The calendar ID"),
-      startDate: import_zod9.z.string().describe("Start date in ISO format (YYYY-MM-DD)"),
-      endDate: import_zod9.z.string().describe("End date in ISO format (YYYY-MM-DD)"),
+      startDate: import_zod9.z.string().describe("Start of the window. Accepts a date (YYYY-MM-DD), a full ISO datetime, or epoch milliseconds. A bare date is taken as start-of-day in `timezone` (UTC if unset). GHL's API needs epoch ms; the tool converts for you."),
+      endDate: import_zod9.z.string().describe("End of the window. Accepts a date (YYYY-MM-DD), a full ISO datetime, or epoch milliseconds. A bare date is taken as end-of-day in `timezone` (UTC if unset)."),
       timezone: import_zod9.z.string().optional().describe("Timezone (e.g. America/New_York)"),
       userId: import_zod9.z.string().optional().describe("Filter by user ID")
     },
     async ({ calendarId, startDate, endDate, timezone, userId }) => {
-      const params = { startDate, endDate };
-      if (timezone !== void 0) params.timezone = timezone;
-      if (userId !== void 0) params.userId = userId;
+      const params = buildFreeSlotsParams({ startDate, endDate, timezone, userId });
       return await client.get(`/calendars/${calendarId}/free-slots`, {
         params
       });
@@ -5973,13 +6060,34 @@ ${text2}`);
 
 // src/tools/form-builder.ts
 var import_zod35 = require("zod");
+function pickFormName(builderForm) {
+  if (builderForm && typeof builderForm === "object" && "form" in builderForm) {
+    const name = builderForm.form?.name;
+    if (typeof name === "string" && name.length > 0) return name;
+  }
+  return void 0;
+}
+function findFormNameInList(list, formId) {
+  const forms = list?.forms;
+  if (Array.isArray(forms)) {
+    for (const f of forms) {
+      if (f && typeof f === "object") {
+        const entry = f;
+        if ((entry.id === formId || entry._id === formId) && typeof entry.name === "string" && entry.name.length > 0) {
+          return entry.name;
+        }
+      }
+    }
+  }
+  return void 0;
+}
 function buildUpdateFormPath(formId, locationId2) {
   return `/${formId}?locationId=${locationId2}`;
 }
 function buildUpdateFormBody(name, formData) {
   return { name, formData };
 }
-function registerFormBuilderTools(server2, builderClient) {
+function registerFormBuilderTools(server2, builderClient, publicClient) {
   const client = builderClient;
   if (!client) return;
   async function formRequest(method, path7, body) {
@@ -6033,11 +6141,28 @@ ${text2}`);
         let resolvedName = name;
         if (resolvedName === void 0) {
           const current = await formRequest("GET", `/${formId}?locationId=${client.locationId}`);
-          const currentName = typeof current === "object" && current !== null && "form" in current ? current.form?.name : void 0;
-          if (typeof currentName !== "string") {
-            throw new Error(`Could not resolve current form name for ${formId} (GET /forms/${formId} returned no string name).`);
+          resolvedName = pickFormName(current);
+          if (resolvedName === void 0 && publicClient) {
+            try {
+              const pageSize = 100;
+              const maxForms = 5e3;
+              for (let skip = 0; skip < maxForms; skip += pageSize) {
+                const list = await publicClient.get("/forms/", {
+                  params: { locationId: client.locationId, limit: pageSize, skip }
+                });
+                resolvedName = findFormNameInList(list, formId);
+                if (resolvedName !== void 0) break;
+                const forms = list?.forms;
+                if (!Array.isArray(forms) || forms.length < pageSize) break;
+              }
+            } catch {
+            }
+          }
+          if (resolvedName === void 0) {
+            throw new Error(
+              `Could not resolve the current name for form ${formId}. Pass the \`name\` argument explicitly \u2014 a form created via create_form has no builder-doc name until its first save.`
+            );
           }
-          resolvedName = currentName;
         }
         const result = await formRequest(
           "POST",
@@ -9511,7 +9636,6 @@ var publicApiTools = [
 var internalApiTools = [
   [registerWorkflowBuilderTools, "workflow-builder"],
   [registerFunnelBuilderTools, "funnel-builder"],
-  [registerFormBuilderTools, "form-builder"],
   [registerPipelineBuilderTools, "pipeline-builder"],
   [registerWorkflowClonerTools, "workflow-cloner"],
   [registerSmartListTools, "smart-lists"],
@@ -9524,9 +9648,11 @@ var VALIDATORS_MODULE = "validators";
 var DIAGNOSTICS_MODULE = "diagnostics";
 var LOCATION_SWITCHER_MODULE = "location-switcher";
 var SNAPSHOTS_MODULE = "snapshots";
+var FORM_BUILDER_MODULE = "form-builder";
 var KNOWN_MODULES = /* @__PURE__ */ new Set([
   ...publicApiTools.map(([, label]) => label),
   ...internalApiTools.map(([, label]) => label),
+  FORM_BUILDER_MODULE,
   VALIDATORS_MODULE,
   DIAGNOSTICS_MODULE,
   LOCATION_SWITCHER_MODULE,
@@ -9544,6 +9670,7 @@ function registerAllTools(server2, client, registry2, mcpVersion, env = process.
   for (const [register, moduleName] of internalApiTools) {
     register(wrap(moduleName), builderClient);
   }
+  registerFormBuilderTools(wrap(FORM_BUILDER_MODULE), builderClient, client);
   registerValidatorTools(wrap(VALIDATORS_MODULE), client, builderClient);
   registerDiagnosticTools(
     wrap(DIAGNOSTICS_MODULE),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.34.8",
+  "version": "3.34.10",
   "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",