@elitedcs/ghl-mcp 3.62.1 → 3.64.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 3.64.0 — four silent failures fixed, four more guides open
+
+Every fix here is the same shape: a call that succeeded, returned
+plausible-looking data, and was wrong. None of them raised an error, so none of
+them were visible until a guide was written against them and run for real.
+
+- **Fix: comparing two sub-accounts reported the other one as empty.** A
+  Private Integration key only works on the sub-account it was created in, so
+  reading a second account returned 403 — which `compare_locations` caught,
+  stored as null, and counted as zero. Comparing a client account against your
+  template answered "nothing is missing". It now uses each account's own saved
+  key (the same registry `switch_location` uses), reports a section it genuinely
+  cannot read as "unavailable" rather than as zero, and returns the NAMES
+  present in one account and missing from the other — which it always claimed to
+  do but never did. Live-proven: a template that read as "0 pipelines,
+  0 workflows, 0 tags" actually holds 8, 12 and 11.
+- **Fix: filtering reviews by star rating did nothing.** The filter used a field
+  name GoHighLevel does not have, and an unknown filter field is dropped
+  silently, so asking for five-star reviews returned two-star ones. Correct
+  field and range form captured from GoHighLevel's own reputation filter.
+  Adds `minRating`/`maxRating`, so "every review under four stars" now works.
+- **Fix: `get_users` advertised `limit` and `skip`.** GoHighLevel rejects both
+  outright. Anyone who used them got an error instead of users. Removed; the
+  endpoint returns every user in one response.
+- Four more guides open in the library, each proven against a real account
+  before shipping: see and manage appointments, create forms and read
+  submissions, watch your reviews, account admin basics. 24 open, 6 still
+  being written.
+
+## 3.63.0 — the guide library grows from 3 guides to 20
+
+- **`get_user_guide` now opens a 20-guide library.** Seventeen guides were
+  written and proven live but had never shipped, so anyone running
+  `get user guide` was still getting the three-guide edition. The bundled
+  offline guide goes from 43KB to 111KB: 20 open guides, 10 still marked
+  "Available in the app" until their prompts are proven. Every prompt marked
+  "Proven live" was run against a real GoHighLevel account before it shipped.
+- Same library renders to ghlcommand.com/skills, so the in-product guide and
+  the website always match.
+- **Fix: reading appointments returned nothing.** `get_calendar_events` sent
+  ISO timestamps, but GHL's `/calendars/events` needs epoch milliseconds and
+  answers a wrong-format request with `200` and an empty array instead of an
+  error — so a calendar holding real confirmed bookings read back as "nothing
+  booked". Now converts via the timezone-aware helper free-slots already used,
+  plus an optional `timezone` parameter so a bare `YYYY-MM-DD` window resolves
+  in the sub-account's timezone (end date inclusive). Live-proven both
+  directions.
+
 ## 3.62.1 — update_pipeline works again (Bug 8)
 
 - **Fix: `update_pipeline` no longer 422s.** GHL's pipeline PUT rejects unknown

package/dist/index.js

@@ -2854,7 +2854,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.62.1",
+      version: "3.64.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.",
       main: "dist/index.js",
@@ -7643,7 +7643,7 @@ 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.`);
+    throw new Error(`Ambiguous numeric date "${value}" \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) {
@@ -7658,7 +7658,7 @@ function toEpochMillis(value, opts = {}) {
   }
   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.`);
+  throw new Error(`Invalid date "${value}" \u2014 use YYYY-MM-DD, a full ISO datetime, or epoch milliseconds.`);
 }
 function buildFreeSlotsParams(args) {
   const params = {
@@ -7669,6 +7669,16 @@ function buildFreeSlotsParams(args) {
   if (args.userId !== void 0) params.userId = args.userId;
   return params;
 }
+function buildCalendarEventsParams(args) {
+  const params = {
+    locationId: args.locationId,
+    startTime: toEpochMillis(args.startTime, { timeZone: args.timezone }),
+    endTime: toEpochMillis(args.endTime, { endOfDay: true, timeZone: args.timezone })
+  };
+  if (args.calendarId !== void 0) params.calendarId = args.calendarId;
+  if (args.userId !== void 0) params.userId = args.userId;
+  return params;
+}
 function registerCalendarTools(server2, client) {
   safeTool(
     server2,
@@ -7789,20 +7799,25 @@ function registerCalendarTools(server2, client) {
     "List calendar events for a location within a time range",
     {
       locationId: import_zod12.z.string().optional().describe("Location ID (falls back to GHL_LOCATION_ID env var)"),
-      startTime: import_zod12.z.string().describe("Start time in ISO format"),
-      endTime: import_zod12.z.string().describe("End time in ISO format"),
+      startTime: import_zod12.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 needs epoch ms here; the tool converts for you."
+      ),
+      endTime: import_zod12.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 that day, inclusive, in `timezone`."
+      ),
+      timezone: import_zod12.z.string().optional().describe("IANA timezone (e.g. America/Phoenix) used to resolve bare YYYY-MM-DD dates. Defaults to UTC."),
       calendarId: import_zod12.z.string().optional().describe("Filter by calendar ID"),
       userId: import_zod12.z.string().optional().describe("Filter by user ID")
     },
-    async ({ locationId: locationId2, startTime, endTime, calendarId, userId }) => {
-      const resolvedLocationId = client.resolveLocationId(locationId2);
-      const params = {
-        locationId: resolvedLocationId,
+    async ({ locationId: locationId2, startTime, endTime, timezone, calendarId, userId }) => {
+      const params = buildCalendarEventsParams({
+        locationId: client.resolveLocationId(locationId2),
         startTime,
-        endTime
-      };
-      if (calendarId !== void 0) params.calendarId = calendarId;
-      if (userId !== void 0) params.userId = userId;
+        endTime,
+        timezone,
+        calendarId,
+        userId
+      });
       return await client.get("/calendars/events", { params });
     }
   );
@@ -8817,18 +8832,17 @@ function registerUserTools(server2, client) {
   safeTool(
     server2,
     "get_users",
-    "List users for a location",
+    "List every user on a location, with their role and permissions. Returns them all in one response \u2014 GHL's users endpoint takes no paging parameters.",
     {
-      locationId: import_zod22.z.string().optional().describe("GHL Location ID (optional if GHL_LOCATION_ID is set)"),
-      limit: import_zod22.z.number().optional().describe("Max number of users to return"),
-      skip: import_zod22.z.number().optional().describe("Number of users to skip")
+      locationId: import_zod22.z.string().optional().describe("GHL Location ID (optional if GHL_LOCATION_ID is set)")
     },
-    async ({ locationId: locationId2, limit, skip }) => {
+    // No limit/skip: GHL rejects them outright with 422 "property limit should
+    // not exist". They were advertised on this tool for months, so anyone who
+    // took the schema at its word got an error instead of a page of users
+    // (live-verified 2026-08-08).
+    async ({ locationId: locationId2 }) => {
       const resolvedLocationId = client.resolveLocationId(locationId2);
-      const params = { locationId: resolvedLocationId };
-      if (limit !== void 0) params.limit = limit;
-      if (skip !== void 0) params.skip = skip;
-      return client.get("/users/", { params });
+      return client.get("/users/", { params: { locationId: resolvedLocationId } });
     }
   );
   safeTool(
@@ -13323,7 +13337,7 @@ var import_zod46 = require("zod");
 function delay2(ms) {
   return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
-function registerAccountExportTools(server2, client) {
+function registerAccountExportTools(server2, client, registry2) {
   const builderClient = WorkflowBuilderClient.fromEnv();
   server2.tool(
     "export_account",
@@ -13456,7 +13470,7 @@ function registerAccountExportTools(server2, client) {
   );
   server2.tool(
     "compare_locations",
-    "Compare two GHL sub-accounts side by side \u2014 shows differences in pipelines, workflows, custom fields, tags, forms, and funnels. Useful for ensuring consistency across locations or auditing before/after changes.",
+    "Compare two GHL sub-accounts side by side. For pipelines, workflows, custom fields, tags and forms it returns the count on each side plus the NAMES present in one account and missing from the other, so a setup gap reads directly. If a section cannot be read (commonly the API key has no access to the second location), that section is reported as unavailable with the reason \u2014 never as a count of zero.",
     {
       locationA: import_zod46.z.string().describe("First Location ID."),
       locationB: import_zod46.z.string().describe("Second Location ID.")
@@ -13468,66 +13482,57 @@ function registerAccountExportTools(server2, client) {
           locationA,
           locationB
         };
-        const fetchData = async (locId) => {
-          const data = {};
-          try {
-            data.location = await client.get(`/locations/${locId}`);
-          } catch {
-            data.location = null;
-          }
-          await delay2(100);
+        const SECTIONS = ["pipelines", "workflows", "customFields", "tags", "forms"];
+        const namesFrom = (payload) => {
+          const list = Array.isArray(payload) ? payload : payload && typeof payload === "object" ? Object.values(payload).find(Array.isArray) : void 0;
+          if (!Array.isArray(list)) return [];
+          return list.map(
+            (item) => item && typeof item === "object" ? String(item.name ?? item.id ?? "") : String(item)
+          ).filter(Boolean);
+        };
+        const read = async (fn) => {
           try {
-            data.pipelines = await client.get("/opportunities/pipelines", { params: { locationId: locId } });
-          } catch {
-            data.pipelines = null;
+            return { names: namesFrom(await fn()) };
+          } catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
           }
+        };
+        const fetchData = async (locId) => {
+          const data = {};
+          data.pipelines = await read(() => client.get("/opportunities/pipelines", { params: { locationId: locId } }));
           await delay2(100);
-          try {
-            data.workflows = await client.get("/workflows/", { params: { locationId: locId } });
-          } catch {
-            data.workflows = null;
-          }
+          data.workflows = await read(() => client.get("/workflows/", { params: { locationId: locId } }));
           await delay2(100);
-          try {
-            data.customFields = await client.get("/locations/" + locId + "/customFields");
-          } catch {
-            data.customFields = null;
-          }
+          data.customFields = await read(() => client.get(`/locations/${locId}/customFields`));
           await delay2(100);
-          try {
-            data.tags = await client.get("/locations/" + locId + "/tags");
-          } catch {
-            data.tags = null;
-          }
+          data.tags = await read(() => client.get(`/locations/${locId}/tags`));
           await delay2(100);
-          try {
-            data.forms = await client.get("/forms/", { params: { locationId: locId } });
-          } catch {
-            data.forms = null;
-          }
+          data.forms = await read(() => client.get("/forms/", { params: { locationId: locId } }));
           return data;
         };
-        const [dataA, dataB] = await Promise.all([fetchData(locationA), fetchData(locationB)]);
-        const count = (obj, key) => {
-          if (!obj || !obj[key]) return 0;
-          const v = obj[key];
-          if (Array.isArray(v)) return v.length;
-          if (v && typeof v === "object" && !Array.isArray(v)) {
-            for (const nested of Object.values(v)) {
-              if (Array.isArray(nested)) return nested.length;
-            }
+        const originalKey = client.getApiKey();
+        const usedRegisteredKey = [];
+        const fetchWithOwnKey = async (locId) => {
+          const token = registry2?.getToken(locId);
+          if (token?.apiKey && token.apiKey !== originalKey) {
+            client.setApiKey(token.apiKey);
+            usedRegisteredKey.push(locId);
+          }
+          try {
+            return await fetchData(locId);
+          } finally {
+            client.setApiKey(originalKey);
           }
-          return "?";
-        };
-        diff.comparison = {
-          pipelines: { A: count(dataA, "pipelines"), B: count(dataB, "pipelines") },
-          workflows: { A: count(dataA, "workflows"), B: count(dataB, "workflows") },
-          customFields: { A: count(dataA, "customFields"), B: count(dataB, "customFields") },
-          tags: { A: count(dataA, "tags"), B: count(dataB, "tags") },
-          forms: { A: count(dataA, "forms"), B: count(dataB, "forms") }
         };
-        diff.locationA_data = dataA;
-        diff.locationB_data = dataB;
+        const dataA = await fetchWithOwnKey(locationA);
+        const dataB = await fetchWithOwnKey(locationB);
+        const { comparison, unavailable } = buildLocationComparison(dataA, dataB, SECTIONS);
+        diff.comparison = comparison;
+        if (usedRegisteredKey.length) diff.usedRegisteredKeyFor = usedRegisteredKey;
+        if (unavailable.length) {
+          diff.unavailable = unavailable;
+          diff.warning = "Some sections could not be read. Those sections are marked unavailable \u2014 do NOT read them as empty. A Private Integration key only works on the sub-account it was created in, so register each account's own key (register_location) before comparing them.";
+        }
         return jsonResponse(diff);
       } catch (error) {
         return errorResponse(error);
@@ -13535,6 +13540,35 @@ function registerAccountExportTools(server2, client) {
     }
   );
 }
+function buildLocationComparison(dataA, dataB, sections) {
+  const unavailable = [];
+  const comparison = {};
+  for (const key of sections) {
+    const a = dataA[key] ?? { error: "not read" };
+    const b = dataB[key] ?? { error: "not read" };
+    if ("error" in a) unavailable.push(`locationA.${key}: ${a.error}`);
+    if ("error" in b) unavailable.push(`locationB.${key}: ${b.error}`);
+    if ("error" in a || "error" in b) {
+      comparison[key] = {
+        A: "error" in a ? "unavailable" : a.names.length,
+        B: "error" in b ? "unavailable" : b.names.length,
+        comparable: false,
+        note: "One side could not be read, so no gap can be reported for this section."
+      };
+      continue;
+    }
+    const setA = new Set(a.names);
+    const setB = new Set(b.names);
+    comparison[key] = {
+      A: a.names.length,
+      B: b.names.length,
+      comparable: true,
+      onlyInA: a.names.filter((n) => !setB.has(n)),
+      onlyInB: b.names.filter((n) => !setA.has(n))
+    };
+  }
+  return { comparison, unavailable };
+}
 
 // src/tools/workflow-cloner.ts
 var import_zod47 = require("zod");
@@ -13811,17 +13845,22 @@ ${text2}`);
   safeTool(
     server2,
     "list_reviews",
-    "List the reviews a location has received (Google, Facebook, etc.) with rating, author, text, reply status, and source. Supports paging and an optional rating filter. NOTE: location is resolved through nested filter params internally \u2014 a flat locationId is what caused the long-standing 'No Location Found' error, now fixed. Responding to a review is not yet available via API. Requires Firebase auth.",
+    "List the reviews a location has received (Google, Facebook, etc.) with rating, author, text, reply status, sentiment score, and source. Filter by an exact star rating or a range \u2014 'everything under 4 stars' is minRating 1 + maxRating 3. NOTE: location is resolved through nested filter params internally \u2014 a flat locationId is what caused the long-standing 'No Location Found' error, now fixed. Responding to a review is not yet available via API. Requires Firebase auth.",
     {
       locationId: import_zod49.z.string().optional().describe("Location ID. Falls back to the active builder client's location."),
       pageNumber: import_zod49.z.number().optional().describe("1-based page number. Defaults to 1."),
       pageSize: import_zod49.z.number().optional().describe("Results per page. Defaults to 10."),
-      rating: import_zod49.z.number().optional().describe("Optional: only return reviews with this star rating (1-5)."),
+      rating: import_zod49.z.number().min(1).max(5).optional().describe("Exact star rating (1-5). Takes precedence over minRating/maxRating."),
+      minRating: import_zod49.z.number().min(1).max(5).optional().describe("Lowest star rating to include (1-5), inclusive."),
+      maxRating: import_zod49.z.number().min(1).max(5).optional().describe("Highest star rating to include (1-5), inclusive. For 'under 4 stars', pass 3."),
       includeDeleted: import_zod49.z.boolean().optional().describe("Include deleted reviews. Defaults to false.")
     },
-    async ({ locationId: locationId2, pageNumber, pageSize, rating, includeDeleted }) => {
+    async ({ locationId: locationId2, pageNumber, pageSize, rating, minRating, maxRating, includeDeleted }) => {
       const loc = locationId2 ?? client.locationId;
-      return reputationRequest("GET", buildReviewsQuery(loc, { pageNumber, pageSize, rating, includeDeleted }));
+      return reputationRequest(
+        "GET",
+        buildReviewsQuery(loc, { pageNumber, pageSize, rating, minRating, maxRating, includeDeleted })
+      );
     }
   );
 }
@@ -13832,10 +13871,17 @@ function buildReviewsQuery(locationId2, opts = {}) {
     `filterParams[deleted][0][value]=${opts.includeDeleted ? "true" : "false"}`,
     `filterParams[deleted][0][condition]=eq`
   ];
+  const bounds = [];
   if (opts.rating !== void 0) {
-    q2.push(`filterParams[rating][0][value]=${opts.rating}`);
-    q2.push(`filterParams[rating][0][condition]=eq`);
+    bounds.push([opts.rating, "gte"], [opts.rating, "lte"]);
+  } else {
+    if (opts.minRating !== void 0) bounds.push([opts.minRating, "gte"]);
+    if (opts.maxRating !== void 0) bounds.push([opts.maxRating, "lte"]);
   }
+  bounds.forEach(([value, condition], i) => {
+    q2.push(`filterParams[starRating][${i}][value]=${value}`);
+    q2.push(`filterParams[starRating][${i}][condition]=${condition}`);
+  });
   q2.push(`sortParams[dateAdded]=-1`);
   q2.push(`pageNumber=${opts.pageNumber ?? 1}`);
   q2.push(`pageSize=${opts.pageSize ?? 10}`);
@@ -18717,7 +18763,6 @@ var publicApiTools = [
   [registerWebhookTools, "webhooks"],
   [registerDocumentTools, "documents"],
   [registerBulkOperationTools, "bulk-operations"],
-  [registerAccountExportTools, "account-export"],
   [registerTemplateDeployerTools, "template-deployer"],
   [registerPhoneTools, "phone"],
   [registerAccountHealthTools, "account-health"]
@@ -18738,6 +18783,7 @@ var VALIDATORS_MODULE = "validators";
 var DIAGNOSTICS_MODULE = "diagnostics";
 var LOCATION_SWITCHER_MODULE = "location-switcher";
 var SNAPSHOTS_MODULE = "snapshots";
+var ACCOUNT_EXPORT_MODULE = "account-export";
 var FORM_BUILDER_MODULE = "form-builder";
 var INTAKE_TO_BUILD_MODULE = "intake-to-build";
 var FUNNEL_QA_MODULE = "funnel-qa";
@@ -18752,7 +18798,8 @@ var KNOWN_MODULES = /* @__PURE__ */ new Set([
   VALIDATORS_MODULE,
   DIAGNOSTICS_MODULE,
   LOCATION_SWITCHER_MODULE,
-  SNAPSHOTS_MODULE
+  SNAPSHOTS_MODULE,
+  ACCOUNT_EXPORT_MODULE
 ]);
 function registerAllTools(server2, client, registry2, mcpVersion, env = process.env, tier = "full", outOfBand) {
   const config3 = parseAllowlist(env);
@@ -18781,6 +18828,7 @@ function registerAllTools(server2, client, registry2, mcpVersion, env = process.
     () => buildGatingReport(config3, KNOWN_MODULES, attemptedTools, registeredTools, outOfBand)
   );
   registerSnapshotTools(wrap(SNAPSHOTS_MODULE), client, registry2);
+  registerAccountExportTools(wrap(ACCOUNT_EXPORT_MODULE), client, registry2);
   registerLocationSwitcherTools(
     wrap(LOCATION_SWITCHER_MODULE),
     client,