@elitedcs/ghl-mcp 3.30.0 → 3.31.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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

package/dist/index.js

@@ -31,9 +31,9 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.30.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
 `);
@@ -8817,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"],
@@ -8865,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);
@@ -8892,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.30.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"