@elitedcs/ghl-mcp 3.31.0 → 3.32.0

package/CHANGELOG.md

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

package/dist/index.js

@@ -31,9 +31,9 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.31.0",
+      version: "3.32.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
-      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.",
+      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"
@@ -8926,6 +8926,137 @@ function registerSnapshotTools(server2, client, registry2) {
   );
 }
 
+// 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"],
@@ -8957,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"],

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.31.0",
+  "version": "3.32.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
-  "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.",
+  "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"