@elitedcs/ghl-mcp 3.30.0 → 3.32.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 3.32.0 — Account-health summary + phone reads
+
+Three read tools. The composite is the second roadmap build and the first
+"how's the account doing" answer (GHL has no public reporting API, confirmed by
+probe — so this composes existing reads).
+
+- **`get_account_health_summary`** — one call returns, for a location: total
+  contacts + NEW contacts in a window (default 30d), total opportunities + counts
+  by status (open/won/lost/abandoned), total conversations, and phone-number
+  count.
+- **`list_phone_numbers`** — provisioned LC Phone numbers (sid, number, label).
+- **`list_number_pools`** — configured number pools.
+
+**Honesty by construction.** Every metric is explicitly labeled `scope`
+(`all_time` vs `window`, with start/end on windowed ones) so an all-time number
+can never be read as a recent one. Any metric that can't be read returns
+`{status:"unavailable", reason}` — never a misleading `0`. Each sub-read is
+isolated, so one failure degrades only its own section, not the whole summary.
+
+**Scope (verified against the live API):** windowed *new contacts* use the
+`/contacts/search` `dateAdded` range filter; opportunity status counts use
+filtered `meta.total`. Conversations are all-time only (the API's
+`startAfterDate` is a cursor, not a count filter). Revenue (transactions are
+403 for sub-account tokens) and appointments (no location-wide events endpoint)
+are intentionally excluded.
+
+## 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.32.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. 217 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,246 @@ 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/phone.ts
+var import_zod49 = require("zod");
+var PhoneNumberSchema = import_zod49.z.object({ sid: import_zod49.z.string(), value: import_zod49.z.string(), title: import_zod49.z.string().optional() }).passthrough();
+var NumbersResponseSchema = import_zod49.z.object({ phoneNumbers: import_zod49.z.array(PhoneNumberSchema) }).passthrough();
+var PoolsResponseSchema = import_zod49.z.object({ pools: import_zod49.z.array(import_zod49.z.object({}).passthrough()) }).passthrough();
+function registerPhoneTools(server2, client) {
+  safeTool(
+    server2,
+    "list_phone_numbers",
+    "List the LC Phone numbers provisioned for a location (sid, number, label). Read-only. Use to verify or count purchased numbers (e.g. provisioning step 11). Number purchase is not exposed (billable write).",
+    {
+      locationId: import_zod49.z.string().optional().describe("Defaults to the active location.")
+    },
+    async ({ locationId: locationId2 }) => {
+      const loc = client.resolveLocationId(locationId2);
+      const raw = await client.get("/phone-system/numbers/", { params: { locationId: loc } });
+      const parsed = NumbersResponseSchema.parse(raw);
+      return {
+        locationId: loc,
+        count: parsed.phoneNumbers.length,
+        phoneNumbers: parsed.phoneNumbers.map((n) => ({ sid: n.sid, number: n.value, label: n.title }))
+      };
+    }
+  );
+  safeTool(
+    server2,
+    "list_number_pools",
+    "List LC Phone number pools configured for a location. Read-only.",
+    {
+      locationId: import_zod49.z.string().optional().describe("Defaults to the active location.")
+    },
+    async ({ locationId: locationId2 }) => {
+      const loc = client.resolveLocationId(locationId2);
+      const raw = await client.get("/phone-system/number-pools/", { params: { locationId: loc } });
+      const parsed = PoolsResponseSchema.parse(raw);
+      return { locationId: loc, count: parsed.pools.length, pools: parsed.pools };
+    }
+  );
+}
+
+// src/tools/account-health.ts
+var import_zod50 = require("zod");
+var MetaTotalSchema = import_zod50.z.object({ meta: import_zod50.z.object({ total: import_zod50.z.number() }).passthrough() }).passthrough();
+var TotalSchema = import_zod50.z.object({ total: import_zod50.z.number() }).passthrough();
+var NumbersSchema = import_zod50.z.object({ phoneNumbers: import_zod50.z.array(import_zod50.z.unknown()) }).passthrough();
+var OPP_STATUSES = ["open", "won", "lost", "abandoned"];
+async function section(scope, fn) {
+  try {
+    return { ...await fn(), scope, status: "ok" };
+  } catch (e) {
+    return { status: "unavailable", scope, reason: errorMessage(e) };
+  }
+}
+function registerAccountHealthTools(server2, client) {
+  safeTool(
+    server2,
+    "get_account_health_summary",
+    "Account-health summary for a location, composed from existing reads (GHL has no reporting API). Returns: total contacts + NEW contacts in the window; total opportunities + counts by status (open/won/lost/abandoned); total conversations; phone-number count. Every metric is explicitly labeled all_time vs window (with start/end) \u2014 windowed and all-time numbers are never conflated. Sections that can't be read return status:'unavailable' (never a misleading 0). Revenue and appointments are intentionally excluded (not reachable / too costly via the public API).",
+    {
+      locationId: import_zod50.z.string().optional().describe("Defaults to the active location."),
+      windowDays: import_zod50.z.number().int().positive().max(365).optional().describe("Lookback window in days for windowed metrics (new contacts). Default 30.")
+    },
+    async ({ locationId: locationId2, windowDays }) => {
+      const loc = client.resolveLocationId(locationId2);
+      const days = windowDays ?? 30;
+      const end = Date.now();
+      const start = end - days * 864e5;
+      const startISO = new Date(start).toISOString();
+      const endISO = new Date(end).toISOString();
+      const [
+        contactsAllTime,
+        contactsNewInWindow,
+        opportunitiesTotal,
+        opportunitiesByStatus,
+        conversations,
+        phoneNumbers
+      ] = await Promise.all([
+        section("all_time", async () => {
+          const raw = await client.get("/contacts/", { params: { locationId: loc, limit: 1 } });
+          return { total: MetaTotalSchema.parse(raw).meta.total };
+        }),
+        section("window", async () => {
+          const raw = await client.post("/contacts/search", {
+            body: {
+              locationId: loc,
+              pageLimit: 1,
+              filters: [{ field: "dateAdded", operator: "range", value: { gte: start, lte: end } }]
+            }
+          });
+          return { start: startISO, end: endISO, total: TotalSchema.parse(raw).total };
+        }),
+        // Overall opp total in its OWN section so a failed per-status query can't
+        // blank a count we already have.
+        section("all_time", async () => {
+          const raw = await client.get("/opportunities/search", { params: { location_id: loc, limit: 1 } });
+          return { total: MetaTotalSchema.parse(raw).meta.total };
+        }),
+        section("all_time", async () => {
+          const counts = await Promise.all(
+            OPP_STATUSES.map(async (s) => {
+              const raw = await client.get("/opportunities/search", {
+                params: { location_id: loc, status: s, limit: 1 }
+              });
+              return [s, MetaTotalSchema.parse(raw).meta.total];
+            })
+          );
+          return { byStatus: Object.fromEntries(counts) };
+        }),
+        section("all_time", async () => {
+          const raw = await client.get("/conversations/search", { params: { locationId: loc, limit: 1 } });
+          return { total: TotalSchema.parse(raw).total };
+        }),
+        section("all_time", async () => {
+          const raw = await client.get("/phone-system/numbers/", { params: { locationId: loc } });
+          return { count: NumbersSchema.parse(raw).phoneNumbers.length };
+        })
+      ]);
+      const sections = {
+        contactsAllTime,
+        contactsNewInWindow,
+        opportunitiesTotal,
+        opportunitiesByStatus,
+        conversations,
+        phoneNumbers
+      };
+      const unavailable = Object.entries(sections).filter(([, v]) => v.status === "unavailable").map(([k]) => k);
+      return { locationId: loc, requestedWindow: { days, start: startISO, end: endISO }, sections, unavailable };
+    }
+  );
+}
+
 // src/tools/index.ts
 var publicApiTools = [
   [registerContactTools, "contacts"],
@@ -8848,7 +9088,9 @@ var publicApiTools = [
   [registerDocumentTools, "documents"],
   [registerBulkOperationTools, "bulk-operations"],
   [registerAccountExportTools, "account-export"],
-  [registerTemplateDeployerTools, "template-deployer"]
+  [registerTemplateDeployerTools, "template-deployer"],
+  [registerPhoneTools, "phone"],
+  [registerAccountHealthTools, "account-health"]
 ];
 var internalApiTools = [
   [registerWorkflowBuilderTools, "workflow-builder"],
@@ -8865,12 +9107,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 +9136,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.32.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. 217 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"