@elitedcs/ghl-mcp 3.19.1 → 3.23.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 3.23.0 — `update_calendar` can assign team members again (Henry fix, part 2)
+
+**Critical fix. Tool count unchanged (212 across 43 modules). The `teamMembers` parameter is back on `update_calendar` — and actually persists this time — with a typed schema that surfaces GHL's strict validation up front.**
+
+Reported by Henry Boulton, 2026-05-26.
+
+**Root cause.** Same UI-vs-API pattern we hit in v3.22.0 (forms) and v3.15.0 (email templates). v3.21.0's diagnosis ("GHL silently drops `teamMembers` on PUT, no public-API path exists") was based on testing against an Event calendar — that calendar TYPE doesn't have team members, so GHL accepts the call and ignores the field. On round-robin and class-booking calendars the field is meaningful, and PUT validates it strictly: `priority` must be exactly `0`, `0.5`, or `1` (anything else 422s), `locationConfigurations` needs at least one entry, and `userId` / `selected` / `isPrimary` must be present. Henry's original attempt likely either targeted the wrong calendar type or passed a non-enum priority.
+
+**Fix.** `teamMembers` is back on `update_calendar`, typed via an exported `CalendarTeamMemberSchema` that mirrors GHL's validation:
+
+- `priority` constrained to `z.union([z.literal(0), z.literal(0.5), z.literal(1)])` — invalid values fail at the MCP layer with a clear error instead of an opaque GHL 422.
+- `locationConfigurations` requires `min(1)` and a non-negative integer `position`.
+- Tool description spells out that team-member assignment only applies to calendar types that support it (round_robin, class_booking); on Event calendars the field is silently ignored by GHL — that's the type, not us.
+
+End-to-end verification 2026-05-26 against MCP Testing: create round_robin → assign user → update via PUT (priority 0.5 → 1, location string change) → GET back the new shape → cleanup.
+
+Five new tests in `src/tools/tool-payloads.test.ts` lock the schema in.
+
+## 3.22.0 — `update_form` works again (Henry fix)
+
+**Critical fix. Tool count unchanged (212 across 43 modules). The `update_form` tool, which v3.21.0 marked "currently unavailable," is back — wired to the live save endpoint and verified end-to-end against MCP Testing.**
+
+Reported by Henry Boulton, 2026-05-26.
+
+**Root cause.** v3.21.0's diagnosis was half right and half wrong. The half that was right: the v2 form builder UI does run in a cross-origin iframe (`leadgen-apps-form-survey-builder.leadconnectorhq.com`) and the UI does read form state through Firestore — top-frame network capture only sees a Firestore `Listen` channel, never a REST save. That's exactly what made the route look gone. The half that was wrong: we concluded the REST save route therefore *didn't exist* and the tool needed a Firestore-client integration. It does exist. The new UI just doesn't drive it. Same UI-vs-API divergence we saw with email templates in v3.15.0 ([reference_email_template_firestore](https://github.com/drjerryrelth/ghl-command-mcp/blob/main/CHANGELOG.md#3150)) — the REST routes survive even when the editor moves to Firestore.
+
+**Fix.** `update_form` now calls `POST /forms/{formId}?locationId={loc}` with body exactly `{name, formData}`. Verified shape constraints (server rejects everything else with 422 "property X should not exist"):
+
+- `locationId` belongs in the query string only — putting it in the body fails.
+- `name` and `formData` are both required together — one without the other 422s.
+- `_id`, `deleted`, `productType`, `dateAdded`, `dateUpdated`, `source`, `updatedBy`, `version`, `updatedAt`, `versionHistory` must not appear in the body — `get_form_full` → pass through fails, so callers should pass only the `formData` they want to write.
+
+If `name` is omitted, the tool pre-fetches the current form (one extra GET) so the existing name is preserved. Body and path are factored into pure `buildUpdateFormBody` / `buildUpdateFormPath` helpers and locked in by `src/tools/tool-payloads.test.ts` (3 new tests) — a refactor can't silently regress the tool back to v3.21.0's "unavailable" state.
+
+End-to-end verification 2026-05-26: read form (version 5) → mutate first field's `placeholder` → save (201) → re-read (placeholder persisted) → restore. MCP Testing sandbox left clean.
+
+## 3.21.0 — Workflow Builder now loads for npm-install buyers (Henry + Ryan fix)
+
+**Critical fix. Tool count unchanged (212 across 43 modules), but for `npx`-install buyers the 49 Firebase-gated tools (workflow builder, funnel builder, form builder, pipeline builder, smart lists, reputation, email campaigns, memberships, email-builder internal, plus the pre-deploy validator) now actually register after `enable_workflow_builder` — previously they stayed "Not configured" no matter how many times you restarted.**
+
+Reported independently by Henry Boulton and Ryan Thomas, 2026-05-26.
+
+**Root cause.** Index startup folded `GHL_USER_ID` + the Firebase trio from `credentials.json` into `process.env`, but never folded `GHL_API_KEY` or `GHL_LOCATION_ID`. `WorkflowBuilderClient.fromEnv()` reads all five directly from `process.env`, so for the recommended `npx -y @elitedcs/ghl-mcp@latest` install path — where no env vars are set anywhere — `fromEnv()` returned `null` and every Firebase-gated tool was skipped. Wrapper-script installs (e.g. `start-mcp.sh`) were unaffected because they exported all the vars manually. Henry's workaround of passing the values as `--env` flags on `claude mcp add` "fixed" it by route, which is why this looked like a credentials-file persistence bug.
+
+**Fix.** All credentials-file values now fold into `process.env` at startup (env still wins when already set, so wrapper-script + headless paths are unchanged). Pulled the fold into a single `foldCredentialsIntoEnv()` helper with regression tests that lock in all five Firebase-gated fields.
+
+Also in this release:
+
+- **`create_form`** now uses the correct path. GHL silently retired `POST /forms?locationId=…` (returns 404); the working path is `POST /forms/?locationId=…` (trailing slash). Verified against MCP Testing.
+- **`update_form`** is honestly marked unavailable, with the actual root cause documented for the first time: the GHL form builder runs in a cross-origin iframe (`leadgen-apps-form-survey-builder.leadconnectorhq.com`) and writes saves **directly to Firestore via the Firebase JS SDK** — `firestore.googleapis.com/.../databases/(default)` against the `highlevel-backend` project — rather than any REST endpoint. That's why every REST probe returns 404 or "Form does not exist or is deleted." Wiring this up needs a Firestore-client integration (separate from the workflow-builder's REST-over-Firebase-token pattern). Tracked for a focused future release. Workaround: `delete_form` + `create_form` (both work).
+- **`update_calendar`** removed `teamMembers` from the input. GHL's public API silently drops the field on PUT (200 OK, nothing persists) across every shape and API version we tested. The tool description now tells the caller to set the assignee in the GHL UI instead of returning a fake success.
+
+## 3.20.0 — License gate for headless / env-var installs
+
+**Security + headless support. No tool changes (212 across 43 modules).**
+
+Closes a gap where setting `GHL_API_KEY` + `GHL_LOCATION_ID` via environment variables loaded the full tool set **without ever validating a license**. The server now requires a verified license before exposing the full tools:
+
+- A `credentials.json` written by `setup_ghl_mcp` carries `verified_at` (validated at setup) and is trusted as before — **no change for normal Desktop/Claude Code installs.**
+- The env-var / headless path must now supply `GHL_LICENSE_EMAIL` + `GHL_LICENSE_KEY`. These are validated once at boot and the verified result is cached to `credentials.json`, so there's no per-restart phone-home and device activations aren't re-counted on a stable machine.
+- Without a verified license, the server stays in bootstrap mode (only `setup_ghl_mcp`, `request_license`, `get_mcp_version`) with a clear message.
+
+This makes headless/server installs first-class: set `GHL_LICENSE_EMAIL`, `GHL_LICENSE_KEY`, `GHL_API_KEY`, `GHL_LOCATION_ID` (plus the Firebase vars for the workflow builder) and the server boots into the full tool set.
+
 ## 3.19.1 — MCP registry prep + README UTM tracking
 
 - Added `mcpName` (`io.github.drjerryrelth/ghl-command`) to package.json so the package can be published to the official MCP registry (many directories pull from it).

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.19.1",
+      version: "3.23.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
       description: "GoHighLevel MCP Server for Claude. 212 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
@@ -60,9 +60,15 @@ var require_package = __commonJS({
         "model-context-protocol",
         "gohighlevel",
         "ghl",
+        "gohighlevel-mcp",
+        "ghl-automation",
         "crm",
         "claude",
-        "anthropic"
+        "anthropic",
+        "workflow-builder",
+        "marketing-automation",
+        "ai-agent",
+        "agency"
       ],
       author: "Elite DCs, LLC",
       license: "MIT",
@@ -326,6 +332,23 @@ function readCredentials() {
     return null;
   }
 }
+function foldCredentialsIntoEnv(creds, env = process.env) {
+  if (!creds) return;
+  const mappings = [
+    ["ghl_api_key", "GHL_API_KEY"],
+    ["ghl_location_id", "GHL_LOCATION_ID"],
+    ["ghl_user_id", "GHL_USER_ID"],
+    ["ghl_firebase_api_key", "GHL_FIREBASE_API_KEY"],
+    ["ghl_firebase_refresh_token", "GHL_FIREBASE_REFRESH_TOKEN"],
+    ["ghl_company_id", "GHL_COMPANY_ID"]
+  ];
+  for (const [credKey, envKey] of mappings) {
+    const value = creds[credKey];
+    if (value && !env[envKey]) {
+      env[envKey] = value;
+    }
+  }
+}
 function writeCredentials(creds) {
   ensureAppDataDir();
   const file = credentialsPath();
@@ -2364,6 +2387,18 @@ function registerOpportunityTools(server2, client) {
 
 // src/tools/calendars.ts
 var import_zod9 = require("zod");
+var TeamMemberLocationConfigSchema = import_zod9.z.object({
+  kind: import_zod9.z.string().describe("Meeting location kind. Common values: 'custom', 'zoom_conference', 'google_meet'."),
+  position: import_zod9.z.number().int().nonnegative().describe("Position index for ordering (0-based)."),
+  location: import_zod9.z.string().optional().describe("Display string for the meeting location (URL or address). Optional for kind='custom'.")
+});
+var CalendarTeamMemberSchema = import_zod9.z.object({
+  userId: import_zod9.z.string().describe("GHL user ID to assign. Must exist in this sub-account."),
+  priority: import_zod9.z.union([import_zod9.z.literal(0), import_zod9.z.literal(0.5), import_zod9.z.literal(1)]).describe("Booking priority. Exactly 0, 0.5, or 1 (anything else 422s from GHL). Higher = preferred for round-robin."),
+  isPrimary: import_zod9.z.boolean().describe("Whether this user is the primary assignee."),
+  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:''}].")
+});
 function registerCalendarTools(server2, client) {
   safeTool(
     server2,
@@ -2433,7 +2468,7 @@ function registerCalendarTools(server2, client) {
   safeTool(
     server2,
     "update_calendar",
-    "Update an existing calendar",
+    "Update an existing calendar's settings. Supports name, description, slug, event title/color, slot durations, capacity, AND team-member assignment via `teamMembers`. Team members only apply to calendar types that use them (round_robin, class_booking, etc.) \u2014 on event calendars GHL accepts the call but silently ignores the field. priority MUST be 0, 0.5, or 1.",
     {
       calendarId: import_zod9.z.string().describe("The calendar ID to update"),
       name: import_zod9.z.string().optional().describe("Calendar name"),
@@ -2441,7 +2476,7 @@ function registerCalendarTools(server2, client) {
       slug: import_zod9.z.string().optional().describe("Calendar slug"),
       widgetSlug: import_zod9.z.string().optional().describe("Widget slug for embedding"),
       calendarType: import_zod9.z.string().optional().describe("Calendar type"),
-      teamMembers: import_zod9.z.array(import_zod9.z.record(import_zod9.z.unknown())).optional().describe("Array of team member objects"),
+      teamMembers: import_zod9.z.array(CalendarTeamMemberSchema).optional().describe("Replace the calendar's team-member assignments. Pass [] to clear (round-robin calendars require at least one). Use get_calendar to inspect the current shape first."),
       eventTitle: import_zod9.z.string().optional().describe("Default event title"),
       eventColor: import_zod9.z.string().optional().describe("Event color hex code"),
       slotDuration: import_zod9.z.number().optional().describe("Slot duration in minutes"),
@@ -5476,6 +5511,12 @@ ${text2}`);
 
 // src/tools/form-builder.ts
 var import_zod35 = require("zod");
+function buildUpdateFormPath(formId, locationId2) {
+  return `/${formId}?locationId=${locationId2}`;
+}
+function buildUpdateFormBody(name, formData) {
+  return { name, formData };
+}
 function registerFormBuilderTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
@@ -5519,17 +5560,28 @@ ${text2}`);
   );
   server2.tool(
     "update_form",
-    "Update a form's structure \u2014 fields, labels, conditional logic, auto-responder, email notifications, styling. Use get_form_full first to see the current structure, modify the formData object, and pass it here.",
+    "Update a form's structure \u2014 fields, labels, conditional logic, auto-responder, email notifications, styling. Use get_form_full first to read the current form, modify the formData object, then pass it here. If name is omitted, the current name is preserved (one extra GET).",
     {
       formId: import_zod35.z.string().describe("The form ID to update."),
       formData: import_zod35.z.record(import_zod35.z.unknown()).describe("The updated formData object containing form fields, settings, autoResponder config, etc."),
-      name: import_zod35.z.string().optional().describe("Updated form name.")
+      name: import_zod35.z.string().optional().describe("Updated form name. If omitted, the current name is preserved.")
     },
     async ({ formId, formData, name }) => {
       try {
-        const body = { formData, locationId: client.locationId };
-        if (name !== void 0) body.name = name;
-        const result = await formRequest("PUT", `/${formId}?locationId=${client.locationId}`, body);
+        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 = currentName;
+        }
+        const result = await formRequest(
+          "POST",
+          buildUpdateFormPath(formId, client.locationId),
+          buildUpdateFormBody(resolvedName, formData)
+        );
         return {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
@@ -5546,7 +5598,7 @@ ${text2}`);
     },
     async ({ name }) => {
       try {
-        const result = await formRequest("POST", `?locationId=${client.locationId}`, {
+        const result = await formRequest("POST", `/?locationId=${client.locationId}`, {
           name,
           locationId: client.locationId,
           formData: {
@@ -8297,18 +8349,7 @@ var registry = new TokenRegistry();
 var fileCreds = readCredentials();
 var locationId = process.env.GHL_LOCATION_ID || fileCreds?.ghl_location_id || void 0;
 var apiKey = process.env.GHL_API_KEY || fileCreds?.ghl_api_key || void 0;
-if (fileCreds?.ghl_user_id && !process.env.GHL_USER_ID) {
-  process.env.GHL_USER_ID = fileCreds.ghl_user_id;
-}
-if (fileCreds?.ghl_firebase_api_key && !process.env.GHL_FIREBASE_API_KEY) {
-  process.env.GHL_FIREBASE_API_KEY = fileCreds.ghl_firebase_api_key;
-}
-if (fileCreds?.ghl_firebase_refresh_token && !process.env.GHL_FIREBASE_REFRESH_TOKEN) {
-  process.env.GHL_FIREBASE_REFRESH_TOKEN = fileCreds.ghl_firebase_refresh_token;
-}
-if (fileCreds?.ghl_company_id && !process.env.GHL_COMPANY_ID) {
-  process.env.GHL_COMPANY_ID = fileCreds.ghl_company_id;
-}
+foldCredentialsIntoEnv(fileCreds);
 if (locationId && registry.hasTokens()) {
   const token = registry.getToken(locationId);
   if (token) {
@@ -8321,24 +8362,60 @@ var server = new import_mcp.McpServer({
   name: "elite-dcs-ghl",
   version: pkg.version
 });
-var inBootstrapMode = !apiKey || !locationId;
 registerMetaTools(server, pkg.version);
-if (inBootstrapMode) {
-  process.stderr.write(
-    `[ghl-mcp] Bootstrap mode: no credentials found.
-[ghl-mcp] Looked for env vars (GHL_API_KEY, GHL_LOCATION_ID) and credentials file (${credentialsPath()}).
+var inBootstrapMode = true;
+async function resolveAccessAndRegister() {
+  let licenseVerified = Boolean(fileCreds?.verified_at && fileCreds?.license_key);
+  if (!licenseVerified && apiKey && locationId) {
+    const licEmail = (process.env.GHL_LICENSE_EMAIL || fileCreds?.email)?.trim();
+    const licKey = (process.env.GHL_LICENSE_KEY || fileCreds?.license_key)?.trim();
+    if (licEmail && licKey) {
+      const lic = await validateLicense(licEmail, licKey);
+      if (lic.ok) {
+        licenseVerified = true;
+        try {
+          writeCredentials({
+            license_key: licKey,
+            email: licEmail,
+            verified_at: (/* @__PURE__ */ new Date()).toISOString(),
+            ghl_api_key: apiKey,
+            ghl_location_id: locationId,
+            ...process.env.GHL_COMPANY_ID ? { ghl_company_id: process.env.GHL_COMPANY_ID } : {},
+            ...process.env.GHL_USER_ID ? { ghl_user_id: process.env.GHL_USER_ID } : {},
+            ...process.env.GHL_FIREBASE_API_KEY ? { ghl_firebase_api_key: process.env.GHL_FIREBASE_API_KEY } : {},
+            ...process.env.GHL_FIREBASE_REFRESH_TOKEN ? { ghl_firebase_refresh_token: process.env.GHL_FIREBASE_REFRESH_TOKEN } : {}
+          });
+          process.stderr.write("[ghl-mcp] License validated and cached.\n");
+        } catch {
+        }
+      } else {
+        process.stderr.write(`[ghl-mcp] License check failed: ${lic.error}
+`);
+      }
+    } else {
+      process.stderr.write(
+        "[ghl-mcp] No verified license. For a headless/server install set GHL_LICENSE_EMAIL + GHL_LICENSE_KEY alongside GHL_API_KEY + GHL_LOCATION_ID; otherwise run setup_ghl_mcp.\n"
+      );
+    }
+  }
+  inBootstrapMode = !apiKey || !locationId || !licenseVerified;
+  if (inBootstrapMode) {
+    process.stderr.write(
+      `[ghl-mcp] Bootstrap mode.
+[ghl-mcp] Need a valid license plus GHL_API_KEY + GHL_LOCATION_ID (env vars or credentials file at ${credentialsPath()}).
 [ghl-mcp] Only setup_ghl_mcp, request_license, and get_mcp_version are available. Run setup_ghl_mcp with your license + GHL credentials \u2014 or request_license if you don't have a license yet.
 `
-  );
-  registerSetupTool(server);
-  registerLeadCaptureTool(server);
-} else {
-  const client = new GHLClient({ apiKey, locationId });
-  registerAllTools(server, client, registry, pkg.version);
-  registerEnableWorkflowBuilderTool(server);
-  if (fileCreds && !process.env.GHL_API_KEY) {
-    process.stderr.write(`[ghl-mcp] Loaded credentials from ${credentialsPath()}
+    );
+    registerSetupTool(server);
+    registerLeadCaptureTool(server);
+  } else {
+    const client = new GHLClient({ apiKey, locationId });
+    registerAllTools(server, client, registry, pkg.version);
+    registerEnableWorkflowBuilderTool(server);
+    if (fileCreds && !process.env.GHL_API_KEY) {
+      process.stderr.write(`[ghl-mcp] Loaded credentials from ${credentialsPath()}
 `);
+    }
   }
 }
 async function validateApiKey() {
@@ -8375,6 +8452,7 @@ async function checkForUpdates() {
   }
 }
 async function main() {
+  await resolveAccessAndRegister();
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   if (inBootstrapMode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.19.1",
+  "version": "3.23.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
   "description": "GoHighLevel MCP Server for Claude. 212 tools — full CRM, automation, marketing control, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",
@@ -29,9 +29,15 @@
     "model-context-protocol",
     "gohighlevel",
     "ghl",
+    "gohighlevel-mcp",
+    "ghl-automation",
     "crm",
     "claude",
-    "anthropic"
+    "anthropic",
+    "workflow-builder",
+    "marketing-automation",
+    "ai-agent",
+    "agency"
   ],
   "author": "Elite DCs, LLC",
   "license": "MIT",