@elitedcs/ghl-mcp 3.29.0 → 3.31.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 3.31.0 — Snapshots: list + share-link (agency tooling)
+
+Two new agency-level tools, the first build toward removing manual steps from the
+client-provisioning runbook (snapshot selection + handoff for new sub-accounts).
+
+- **`list_snapshots`** — list the agency's snapshots (`id`, `name`, `type`) so you
+  can pick the right one by name. Read-only.
+- **`create_snapshot_share_link`** — mint a load/share link for a snapshot
+  (`gohighlevel.com/?share=…`) to import it into a sub-account. Requires an explicit
+  `share_type` (`link`, `permanent_link`, `agency_link`, `location_link`,
+  `marketplace_link`).
+
+Both use the agency/company-scoped key (`getAgencyKey()`), not a sub-account PIT —
+snapshots are an agency resource. The tools resolve `companyId` with strict rules
+(explicit param > active location's company; mismatch is rejected, not guessed) so
+a multi-tenant install can't list the wrong agency's snapshots, and they fail with
+an actionable message when no agency key is registered.
+
+**Notes / limits (verified against the live API):**
+- Creating a sub-account from a snapshot is NOT exposed: `POST /locations/` returns
+  401 for PIT auth. Snapshot *apply* stays a guided GHL-UI step.
+- `create_snapshot_share_link` is not idempotent (each call mints a new link, no
+  revoke API — remove in the UI). The HTTP client gained an internal `noRetry`
+  option so a lost-response retry can't silently create a duplicate.
+
+## 3.30.0 — Workflow trigger stays active after edit/publish (Bug 7)
+
+Editing a trigger on a published workflow via `update_workflow_actions` silently
+disabled it (`active` flipped to `false`), and there was no MCP path to turn it
+back on. Any contract/tag/form trigger you edited stopped firing.
+
+**Root cause.** The internal trigger-write helper hardcoded `status: "draft"` on
+every trigger POST/PUT. GHL derives a trigger's stored `active` flag from that
+write-time `status`. Verified live against the sandbox:
+
+- `status:"published"` → `active:true`
+- `status:"draft"` → `active:false` (and so do `"active"`, `"live"`, and
+  omitting `status` entirely)
+
+So every trigger edit re-drafted the trigger, and nothing flipped it back —
+`publish_workflow` didn't either, because it sent no triggers at all.
+
+**Fix.** Trigger writes now mirror the workflow's own published/draft state:
+
+- `update_workflow_actions` on a published workflow writes its triggers as
+  `published`, so editing a trigger condition keeps it live.
+- `publish_workflow` now re-syncs the workflow's triggers, so a draft →
+  published transition (including the documented create → add-trigger →
+  publish flow) activates them.
+
+Action-chain linking and the workflow-setting preservation from 3.29.0 are
+unchanged.
+
 ## 3.29.0 — Documents & Contracts API fix + workflow/contact bug fixes
 
 Five confirmed bugs fixed, verified live against the GHL API.

package/dist/index.js

@@ -31,9 +31,9 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.29.0",
+      version: "3.31.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.",
+      description: "GoHighLevel MCP Server for Claude. 214 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
       bin: {
         "ghl-mcp": "dist/index.js"
@@ -203,7 +203,7 @@ var GHLClient = class {
       if (error instanceof Error && error.name === "AbortError") {
         throw new Error(`Request timeout (30s): ${method} ${path6}`);
       }
-      if (attempt < MAX_RETRIES) {
+      if (!options.noRetry && attempt < MAX_RETRIES) {
         const delay4 = computeRetryDelay(null, attempt, BASE_DELAY_MS);
         process.stderr.write(`[ghl-mcp] Network error on ${method} ${path6}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay4}ms
 `);
@@ -214,7 +214,7 @@ var GHLClient = class {
     } finally {
       clearTimeout(timeout);
     }
-    if ((response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
+    if (!options.noRetry && (response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
       const delay4 = computeRetryDelay(response.headers.get("Retry-After"), attempt, BASE_DELAY_MS);
       process.stderr.write(`[ghl-mcp] ${response.status} on ${method} ${path6}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay4}ms
 `);
@@ -1636,8 +1636,9 @@ ${errorBody}`
    */
   async updateWorkflow(workflowId, updates) {
     const current = await this.getWorkflow(workflowId);
+    const effectiveStatus = updates.status ?? current.status;
     if (updates.triggers !== void 0) {
-      await this.syncTriggers(workflowId, current.triggers || [], updates.triggers);
+      await this.syncTriggers(workflowId, current.triggers || [], updates.triggers, effectiveStatus);
     }
     const currentActions = current.workflowData?.templates || [];
     const newActions = updates.actions ?? currentActions;
@@ -1649,7 +1650,7 @@ ${errorBody}`
     const body = {
       name: updates.name ?? current.name,
       isRestoreRequest: true,
-      status: updates.status ?? current.status,
+      status: effectiveStatus,
       version: current.version,
       dataVersion: current.dataVersion ?? 1,
       timezone: current.timezone ?? "account",
@@ -1682,16 +1683,30 @@ ${errorBody}`
     return this.request("DELETE", `/${this.locationId}/${workflowId}`);
   }
   /**
-   * Publish a draft workflow
+   * Publish a draft workflow.
+   *
+   * Publishing must also re-activate the workflow's triggers. GHL stores a
+   * trigger's `active` flag based on the write-time `status`, so triggers
+   * created/edited while the workflow was a draft are written as "draft"
+   * (active:false). Re-syncing them here under the now-"published" status
+   * flips them live — otherwise a freshly published workflow's triggers never
+   * fire (and the create → update_workflow_actions → publish_workflow flow
+   * would leave new triggers inactive).
    */
   async publishWorkflow(workflowId) {
-    return this.updateWorkflow(workflowId, { status: "published" });
+    const current = await this.getWorkflow(workflowId);
+    return this.updateWorkflow(workflowId, {
+      status: "published",
+      triggers: current.triggers ?? []
+    });
   }
   /**
    * Create a workflow trigger. GHL generates the Firestore id and returns it.
+   * `workflowStatus` is the owning workflow's published/draft state; it
+   * determines whether the new trigger is written live or as a draft.
    */
-  async createTrigger(workflowId, trigger) {
-    const payload = this.buildTriggerPayload(workflowId, trigger);
+  async createTrigger(workflowId, trigger, workflowStatus) {
+    const payload = this.buildTriggerPayload(workflowId, trigger, workflowStatus);
     const raw = await this.request("POST", `/${this.locationId}/trigger`, payload);
     if (isRecord(raw) && typeof raw.id === "string") {
       return raw.id;
@@ -1699,10 +1714,11 @@ ${errorBody}`
     throw new Error(`Trigger creation did not return an id. Response: ${JSON.stringify(raw)}`);
   }
   /**
-   * Update an existing workflow trigger.
+   * Update an existing workflow trigger. `workflowStatus` is the owning
+   * workflow's published/draft state (see buildTriggerPayload).
    */
-  async updateTrigger(workflowId, trigger) {
-    const payload = this.buildTriggerPayload(workflowId, trigger);
+  async updateTrigger(workflowId, trigger, workflowStatus) {
+    const payload = this.buildTriggerPayload(workflowId, trigger, workflowStatus);
     return this.request("PUT", `/${this.locationId}/trigger/${trigger.id}`, payload);
   }
   /**
@@ -1716,7 +1732,7 @@ ${errorBody}`
    * Triggers without an id are created; triggers present in current but
    * missing from desired are deleted; triggers in both are updated in place.
    */
-  async syncTriggers(workflowId, current, desired) {
+  async syncTriggers(workflowId, current, desired, workflowStatus) {
     const currentById = /* @__PURE__ */ new Map();
     for (const t of current) {
       if (typeof t.id === "string") currentById.set(t.id, t);
@@ -1732,9 +1748,9 @@ ${errorBody}`
     }
     for (const trigger of desired) {
       if (hasTriggerId(trigger) && currentById.has(trigger.id)) {
-        await this.updateTrigger(workflowId, trigger);
+        await this.updateTrigger(workflowId, trigger, workflowStatus);
       } else {
-        await this.createTrigger(workflowId, trigger);
+        await this.createTrigger(workflowId, trigger, workflowStatus);
       }
     }
   }
@@ -1742,7 +1758,8 @@ ${errorBody}`
    * Shape a trigger for the POST/PUT trigger endpoints, matching what the
    * GHL UI sends. Missing fields are filled from the client's context.
    */
-  buildTriggerPayload(workflowId, trigger) {
+  buildTriggerPayload(workflowId, trigger, workflowStatus) {
+    const isPublished = workflowStatus === "published";
     return {
       ...trigger,
       workflowId,
@@ -1752,8 +1769,8 @@ ${errorBody}`
       belongs_to: "workflow",
       actions: trigger.actions ?? [{ workflow_id: workflowId, type: "add_to_workflow" }],
       schedule_config: trigger.schedule_config ?? {},
-      active: trigger.active ?? true,
-      status: "draft"
+      active: isPublished,
+      status: isPublished ? "published" : "draft"
     };
   }
   /**
@@ -8800,6 +8817,115 @@ function registerDiagnosticTools(server2, installedVersion, client, builderClien
   );
 }
 
+// src/tools/snapshots.ts
+var import_zod48 = require("zod");
+var SnapshotSchema = import_zod48.z.object({ id: import_zod48.z.string(), name: import_zod48.z.string(), type: import_zod48.z.string() }).passthrough();
+var SnapshotsResponseSchema = import_zod48.z.object({ snapshots: import_zod48.z.array(SnapshotSchema) }).passthrough();
+var ShareLinkResponseSchema = import_zod48.z.object({ id: import_zod48.z.string(), shareLink: import_zod48.z.string() }).passthrough();
+var SHARE_TYPES = [
+  "link",
+  "permanent_link",
+  "agency_link",
+  "location_link",
+  "marketplace_link"
+];
+function resolveSnapshotAuth(client, registry2, companyIdParam) {
+  const agencyKey = registry2?.getAgencyKey();
+  if (!agencyKey) {
+    throw new Error(
+      "Snapshots require an agency/company-scoped API key, and none is registered. This install only has sub-account Private Integration keys. Add the agency key (created at the AGENCY level in GHL Settings > Integrations) to the token registry, then retry."
+    );
+  }
+  const storedCompanyId = client.defaultLocationId ? registry2?.getToken(client.defaultLocationId)?.companyId : void 0;
+  const param = companyIdParam?.trim() || void 0;
+  if (param && storedCompanyId && param !== storedCompanyId) {
+    throw new Error(
+      `companyId mismatch: you passed ${param}, but the active location belongs to company ${storedCompanyId}. Refusing to guess. Switch to a location in the intended company, or pass the matching companyId.`
+    );
+  }
+  const companyId = param ?? storedCompanyId;
+  if (!companyId) {
+    throw new Error(
+      "Could not determine the companyId for this snapshot call. The active location has no stored company. Pass companyId explicitly, or run register_location / switch_location for the active location so its company is recorded."
+    );
+  }
+  return { agencyClient: new GHLClient({ apiKey: agencyKey }), companyId };
+}
+function explainSnapshotError(error, companyId) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("401") || message.includes("Unauthorized") || message.includes("403")) {
+    throw new Error(
+      `${message}
+
+The agency key is scoped to a single company and may not cover company ${companyId}. Snapshots only list for the agency that owns the key. Use a companyId belonging to the agency key, or register that agency's own key.`
+    );
+  }
+  throw error instanceof Error ? error : new Error(message);
+}
+function registerSnapshotTools(server2, client, registry2) {
+  safeTool(
+    server2,
+    "list_snapshots",
+    "List the agency's GHL snapshots (id, name, type) so you can pick the right one by name before applying it to a sub-account. Reads the agency/company-scoped key (not a sub-account PIT). companyId defaults to the active location's company; pass it explicitly to target a different company you have the agency key for. Read-only.",
+    {
+      companyId: import_zod48.z.string().optional().describe(
+        "Agency/company ID whose snapshots to list. Defaults to the active location's company. Must match the company your agency key is scoped to."
+      )
+    },
+    async ({ companyId }) => {
+      const { agencyClient, companyId: resolved } = resolveSnapshotAuth(client, registry2, companyId);
+      let raw;
+      try {
+        raw = await agencyClient.get("/snapshots/", { params: { companyId: resolved } });
+      } catch (error) {
+        explainSnapshotError(error, resolved);
+      }
+      const parsed = SnapshotsResponseSchema.parse(raw);
+      return {
+        companyId: resolved,
+        count: parsed.snapshots.length,
+        snapshots: parsed.snapshots
+      };
+    }
+  );
+  safeTool(
+    server2,
+    "create_snapshot_share_link",
+    "Create a shareable load link for one of the agency's snapshots (returns a gohighlevel.com/?share=... URL to import the snapshot into a sub-account). Uses the agency/company-scoped key. WARNING: this is NOT idempotent \u2014 each call mints a NEW link, and there is no API to list or revoke links (revoke in the GHL UI under the snapshot's share settings). Pick share_type deliberately. Use list_snapshots first to get the snapshot id.",
+    {
+      snapshot_id: import_zod48.z.string().describe("The snapshot id to share (from list_snapshots)."),
+      share_type: import_zod48.z.enum(SHARE_TYPES).describe(
+        "Share link type. 'link' = standard share link; 'permanent_link' = non-expiring; 'agency_link' = share to agencies; 'location_link' = load into a sub-account/location; 'marketplace_link' = marketplace listing. No default \u2014 choose intentionally."
+      ),
+      companyId: import_zod48.z.string().optional().describe(
+        "Agency/company ID that owns the snapshot. Defaults to the active location's company. Must match the company your agency key is scoped to."
+      )
+    },
+    async ({ snapshot_id, share_type, companyId }) => {
+      const { agencyClient, companyId: resolved } = resolveSnapshotAuth(client, registry2, companyId);
+      let raw;
+      try {
+        raw = await agencyClient.post("/snapshots/share/link", {
+          params: { companyId: resolved },
+          body: { snapshot_id, share_type },
+          noRetry: true
+        });
+      } catch (error) {
+        explainSnapshotError(error, resolved);
+      }
+      const parsed = ShareLinkResponseSchema.parse(raw);
+      return {
+        companyId: resolved,
+        snapshot_id,
+        share_type,
+        id: parsed.id,
+        shareLink: parsed.shareLink,
+        _note: "A new share link was created. There is no API to revoke it \u2014 remove it in the GHL UI (snapshot share settings) if needed."
+      };
+    }
+  );
+}
+
 // src/tools/index.ts
 var publicApiTools = [
   [registerContactTools, "contacts"],
@@ -8848,12 +8974,14 @@ var internalApiTools = [
 var VALIDATORS_MODULE = "validators";
 var DIAGNOSTICS_MODULE = "diagnostics";
 var LOCATION_SWITCHER_MODULE = "location-switcher";
+var SNAPSHOTS_MODULE = "snapshots";
 var KNOWN_MODULES = /* @__PURE__ */ new Set([
   ...publicApiTools.map(([, label]) => label),
   ...internalApiTools.map(([, label]) => label),
   VALIDATORS_MODULE,
   DIAGNOSTICS_MODULE,
-  LOCATION_SWITCHER_MODULE
+  LOCATION_SWITCHER_MODULE,
+  SNAPSHOTS_MODULE
 ]);
 function registerAllTools(server2, client, registry2, mcpVersion, env = process.env) {
   const config3 = parseAllowlist(env);
@@ -8875,6 +9003,7 @@ function registerAllTools(server2, client, registry2, mcpVersion, env = process.
     builderClient,
     registry2 ?? null
   );
+  registerSnapshotTools(wrap(SNAPSHOTS_MODULE), client, registry2);
   registerLocationSwitcherTools(
     wrap(LOCATION_SWITCHER_MODULE),
     client,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.29.0",
+  "version": "3.31.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.",
+  "description": "GoHighLevel MCP Server for Claude. 214 tools — full CRM, automation, marketing control, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",
   "bin": {
     "ghl-mcp": "dist/index.js"