@elitedcs/ghl-mcp 3.31.0 → 3.33.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 3.33.0 — Account-wide silent-failure audit + trust hardening
+
+**`audit_workflows`** — scans EVERY workflow in the current location for
+references to pipelines, stages, custom fields, users, workflows, forms,
+calendars, and surveys that don't exist — the GHL bug where one bad ID silently
+kills that action and every action after it. Returns a prioritized report:
+what's broken, what couldn't be scanned, what couldn't be fully verified.
+Conservative by construction: it never reports a false break (uncertain checks
+are `unverified`, not `error`). The same engine upgrade sharpens
+`validate_workflow`: four opportunity action shapes (including the dominant
+UI-native `internal_create_opportunity`), if/else condition-node custom-field
+checks, `create_update_contact` field refs, hyphenated `task-notification`
+nodes, and custom-field trigger conditions are now covered. 18 new unit tests;
+verified live against 35 real workflows with zero false alarms.
+
+**`register_agency_key`** — new tool to store the agency-level (company-scoped)
+API key, with live validation before saving. Previously the snapshot tools
+required an agency key that no tool could register.
+
+**Trust + reliability hardening** (from the 2026-06-10 audit):
+
+- List tools now attach `_pagination` (returned / limit / total / complete +
+  an explicit INCOMPLETE note) so a single page can never silently read as the
+  full dataset: `search_contacts`, `search_opportunities`,
+  `search_conversations`, `list_invoices`, `list_workflows_full`.
+- Version is read from package.json at runtime instead of baked at build time —
+  a stale local build can no longer misreport its version.
+- `health_check` now reports a corrupted token registry as a FAIL with recovery
+  steps (previously only visible on stderr, i.e. invisible in the Desktop App).
+- Clearer guidance errors: missing locationId now points at `switch_location` /
+  `list_registered_locations`; missing agency key points at
+  `register_agency_key`.
+- Firebase token-refresh URL now percent-encodes the API key (consistency).
+- New regression tests pin that error messages never contain API keys or
+  Firebase refresh tokens.
+
+## 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/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**Full GoHighLevel API access for Claude.** 212 tools across 43 modules — manage contacts, conversations, pipelines, calendars, funnels, workflows, invoices, custom objects, webhooks, and more. **Includes full workflow builder, funnel/page editor, form builder, pipeline builder, bulk operations, account export, and workflow cloning** — capabilities no other GHL tool offers. **Multi-tenant:** one install can run the workflow builder across multiple clients' GHL accounts.
+**Full GoHighLevel API access for Claude.** 219 tools across 43 modules — manage contacts, conversations, pipelines, calendars, funnels, workflows, invoices, custom objects, webhooks, and more. **Includes full workflow builder, funnel/page editor, form builder, pipeline builder, bulk operations, account export, and workflow cloning** — capabilities no other GHL tool offers. **Multi-tenant:** one install can run the workflow builder across multiple clients' GHL accounts.
 
 **Distributed via npm as [`@elitedcs/ghl-mcp`](https://www.npmjs.com/package/@elitedcs/ghl-mcp).** Buyers install with one config block — no git, no Node.js setup, no terminal commands. Updates flow automatically (`npx @latest` re-resolves on every Claude restart).
 
@@ -116,7 +116,7 @@ Run setup_ghl_mcp to activate GHL Command:
   ghl_location_id: YOUR_LOCATION_ID
 ```
 
-Approve the tool call. Server validates your license, verifies your GHL credentials, writes them to a per-user config file. **Quit Claude one more time and reopen** — all 163 core tools are now unlocked (212 with the optional Workflow Builder Firebase add-on).
+Approve the tool call. Server validates your license, verifies your GHL credentials, writes them to a per-user config file. **Quit Claude one more time and reopen** — the full core toolset is now unlocked (219 tools total with the optional Workflow Builder Firebase add-on).
 
 ### 4. Try it
 
@@ -537,7 +537,7 @@ To unlock full builder access across multiple clients from one install:
 Uses **esbuild** for production builds (not tsc). TypeScript 5.9.3 + MCP SDK types cause tsc to run out of memory at 4GB+. esbuild bundles in ~5ms with zero memory issues.
 
 ```bash
-npm run build    # esbuild → dist/index.js (~212KB)
+npm run build    # esbuild → dist/index.js (~428KB)
 npm run dev      # tsc --watch (type-checking only)
 ```
 
@@ -716,7 +716,7 @@ Source repo is private. Contributors need an invitation from `drjerryrelth`. The
 
 ### Reducing context / token usage
 
-Every registered MCP tool's schema is shipped to the model on every message. With 212 tools that's a meaningful per-message context cost even in chats that never touch GHL. If you only use a slice of GHL Command, restrict the tool surface with `GHL_ENABLED_MODULES` and/or `GHL_ENABLED_TOOLS`:
+Every registered MCP tool's schema is shipped to the model on every message. With 219 tools that's a meaningful per-message context cost even in chats that never touch GHL. If you only use a slice of GHL Command, restrict the tool surface with `GHL_ENABLED_MODULES` and/or `GHL_ENABLED_TOOLS`:
 
 ```jsonc
 // Claude Desktop config — enable whole modules

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.33.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. 218 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
       bin: {
         "ghl-mcp": "dist/index.js"
@@ -262,7 +262,7 @@ ${errorBody}`
     const id = providedId || this.defaultLocationId;
     if (!id) {
       throw new Error(
-        "locationId is required. Provide it as a parameter or set GHL_LOCATION_ID in your .env file."
+        "locationId is required. Provide it as a parameter, run switch_location to pick a registered sub-account (list_registered_locations shows what's registered), or set GHL_LOCATION_ID in your .env file."
       );
     }
     return id;
@@ -406,6 +406,7 @@ var TokenRegistryDataSchema = import_zod2.z.object({
 });
 var TokenRegistry = class _TokenRegistry {
   data;
+  loadFailure = null;
   filePath;
   constructor(filePath) {
     if (filePath) {
@@ -454,18 +455,28 @@ var TokenRegistry = class _TokenRegistry {
         return TokenRegistryDataSchema.parse(JSON.parse(raw));
       }
     } catch (error) {
+      let backupNote = "backup also failed \u2014 the corrupted file is still at " + this.filePath;
       try {
         const backupPath = this.filePath + ".corrupted." + Date.now();
         fs2.copyFileSync(this.filePath, backupPath);
+        backupNote = `backed up to ${backupPath}`;
         process.stderr.write(`[ghl-mcp] ERROR: Token registry corrupted. Backed up to ${backupPath}
 `);
       } catch {
       }
+      this.loadFailure = `Token registry could not be loaded (${backupNote}). All sub-account registrations are unavailable this session \u2014 re-register via register_location, or restore the backup over ${this.filePath} and restart.`;
       process.stderr.write(`[ghl-mcp] Warning: Could not load token registry: ${error}
 `);
     }
     return { tokens: {} };
   }
+  /**
+   * Non-null when the registry file existed but could not be parsed at
+   * startup (we fell back to an empty registry). Surfaced by health_check.
+   */
+  getLoadFailure() {
+    return this.loadFailure;
+  }
   save() {
     const tmpPath = `${this.filePath}.tmp.${process.pid}.${(0, import_crypto.randomBytes)(8).toString("hex")}`;
     try {
@@ -503,6 +514,13 @@ var TokenRegistry = class _TokenRegistry {
   getAgencyKey() {
     return this.data.agencyKey;
   }
+  /**
+   * Store the agency/company-scoped API key (snapshots, agency-wide reads).
+   */
+  setAgencyKey(key) {
+    this.data.agencyKey = key;
+    this.save();
+  }
   /**
    * Get Firebase config
    */
@@ -1412,7 +1430,7 @@ var WorkflowBuilderClient = class _WorkflowBuilderClient {
     }
   }
   async performTokenRefresh() {
-    const url = `${FIREBASE_TOKEN_URL}?key=${this.firebaseApiKey}`;
+    const url = `${FIREBASE_TOKEN_URL}?key=${encodeURIComponent(this.firebaseApiKey)}`;
     const body = `grant_type=refresh_token&refresh_token=${encodeURIComponent(this.refreshToken)}`;
     const response = await fetch(url, {
       method: "POST",
@@ -1924,6 +1942,48 @@ function escapeRegex(str) {
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
+function paginationInfo(opts) {
+  const { returned, limit, nextHint } = opts;
+  const total = typeof opts.total === "number" ? opts.total : void 0;
+  if (total !== void 0) {
+    const complete = returned >= total;
+    return {
+      returned,
+      limit,
+      total,
+      complete,
+      ...complete ? {} : {
+        note: `INCOMPLETE: showing ${returned} of ${total} total. ${nextHint ?? "Fetch further pages before treating this as the full list."}`
+      }
+    };
+  }
+  if (returned < limit) {
+    return { returned, limit, complete: true };
+  }
+  return {
+    returned,
+    limit,
+    complete: "unknown",
+    note: `POSSIBLY INCOMPLETE: returned ${returned} which hit the limit of ${limit} \u2014 more may exist. ${nextHint ?? "Fetch further pages before treating this as the full list."}`
+  };
+}
+function annotateListResponse(raw, listKey, limit, nextHint) {
+  if (typeof raw !== "object" || raw === null) return raw;
+  const obj = raw;
+  const list = obj[listKey];
+  if (!Array.isArray(list)) return raw;
+  let total;
+  const meta = obj.meta;
+  if (typeof meta === "object" && meta !== null) {
+    const metaTotal = meta.total;
+    if (typeof metaTotal === "number") total = metaTotal;
+  }
+  if (total === void 0 && typeof obj.total === "number") total = obj.total;
+  return {
+    ...obj,
+    _pagination: paginationInfo({ returned: list.length, limit, total, nextHint })
+  };
+}
 function safeTool(server2, name, description, schema, handler) {
   server2.tool(name, description, schema, async (args) => {
     try {
@@ -2017,7 +2077,16 @@ function registerContactTools(server2, client) {
           order
         }
       });
-      return ContactSearchResponseSchema.parse(raw);
+      const parsed = ContactSearchResponseSchema.parse(raw);
+      return {
+        ...parsed,
+        _pagination: paginationInfo({
+          returned: parsed.contacts.length,
+          limit: limit ?? 20,
+          total: parsed.meta?.total,
+          nextHint: "Pass startAfter + startAfterId from this response's meta to fetch the next page (both are required to advance)."
+        })
+      };
     }
   );
   safeTool(
@@ -2308,7 +2377,7 @@ function registerConversationTools(server2, client) {
     },
     async ({ locationId: locationId2, contactId, assignedTo, query, status, limit, startAfterDate }) => {
       const resolvedLocationId = client.resolveLocationId(locationId2);
-      return await client.get("/conversations/search", {
+      const raw = await client.get("/conversations/search", {
         params: {
           locationId: resolvedLocationId,
           contactId,
@@ -2319,6 +2388,12 @@ function registerConversationTools(server2, client) {
           startAfterDate
         }
       });
+      return annotateListResponse(
+        raw,
+        "conversations",
+        limit ?? 20,
+        "Pass startAfterDate from the last conversation's dateUpdated to fetch the next page."
+      );
     }
   );
   safeTool(
@@ -2463,7 +2538,7 @@ function registerOpportunityTools(server2, client) {
     },
     async (args) => {
       const locationId2 = client.resolveLocationId(args.locationId);
-      return await client.get("/opportunities/search", {
+      const raw = await client.get("/opportunities/search", {
         params: {
           location_id: locationId2,
           pipeline_id: args.pipelineId,
@@ -2480,6 +2555,12 @@ function registerOpportunityTools(server2, client) {
           startDate: args.startDate
         }
       });
+      return annotateListResponse(
+        raw,
+        "opportunities",
+        args.limit ?? 20,
+        "Pass startAfter + startAfterId from this response's meta to fetch the next page."
+      );
     }
   );
   safeTool(
@@ -3581,7 +3662,13 @@ function registerInvoiceTools(server2, client) {
       if (startAt !== void 0) params.startAt = startAt;
       if (endAt !== void 0) params.endAt = endAt;
       if (search !== void 0) params.search = search;
-      return client.get("/invoices/", { params });
+      const raw = await client.get("/invoices/", { params });
+      return annotateListResponse(
+        raw,
+        "invoices",
+        limit ?? 10,
+        "Pass offset (current offset + limit) to fetch the next page."
+      );
     }
   );
   safeTool(
@@ -3617,8 +3704,8 @@ function registerInvoiceTools(server2, client) {
         currency: import_zod17.z.string().describe("Currency code (e.g. USD)")
       })).describe("Invoice line items"),
       discount: import_zod17.z.object({
-        type: import_zod17.z.string().optional(),
-        value: import_zod17.z.number().optional()
+        type: import_zod17.z.string().optional().describe("Discount type: 'percentage' or 'fixed'."),
+        value: import_zod17.z.number().optional().describe("Discount amount: percent (0-100) when type=percentage, currency amount when type=fixed.")
       }).optional().describe("Discount to apply"),
       termsNotes: import_zod17.z.string().optional().describe("Terms and notes for the invoice"),
       title: import_zod17.z.string().optional().describe("Invoice title")
@@ -3654,8 +3741,8 @@ function registerInvoiceTools(server2, client) {
         currency: import_zod17.z.string().describe("Currency code (e.g. USD)")
       })).optional().describe("Invoice line items"),
       discount: import_zod17.z.object({
-        type: import_zod17.z.string().optional(),
-        value: import_zod17.z.number().optional()
+        type: import_zod17.z.string().optional().describe("Discount type: 'percentage' or 'fixed'."),
+        value: import_zod17.z.number().optional().describe("Discount amount: percent (0-100) when type=percentage, currency amount when type=fixed.")
       }).optional().describe("Discount to apply"),
       termsNotes: import_zod17.z.string().optional().describe("Terms and notes for the invoice"),
       title: import_zod17.z.string().optional().describe("Invoice title")
@@ -5212,7 +5299,10 @@ function registerWorkflowBuilderTools(server2, client) {
     async ({ limit, skip }) => {
       try {
         const result = await client.listWorkflows(limit ?? 50, skip ?? 0);
-        return jsonResponse(result);
+        const hint = "Pass skip (current skip + limit) to fetch the next page.";
+        let annotated = annotateListResponse(result, "rows", limit ?? 50, hint);
+        if (annotated === result) annotated = annotateListResponse(result, "workflows", limit ?? 50, hint);
+        return jsonResponse(annotated);
       } catch (error) {
         return errorResponse(error);
       }
@@ -6822,6 +6912,60 @@ The API key could not access location ${locationId2}. Make sure:
       }
     }
   );
+  server2.tool(
+    "register_agency_key",
+    "Store the AGENCY-level (company-scoped) API key in the token registry. This key powers agency-wide tools: list_snapshots, create_snapshot_share_link, and list_available_locations across all sub-accounts. Create it at the AGENCY level in GHL (Agency Settings > Private Integrations) \u2014 it is different from a sub-account's key. The key is validated before saving.",
+    {
+      apiKey: import_zod38.z.string().describe("The agency-level Private Integration API key (starts with 'pit-'). Must be created in AGENCY settings, not inside a sub-account.")
+    },
+    async ({ apiKey: apiKey2 }) => {
+      if (!registry2) {
+        return {
+          content: [{ type: "text", text: "Token registry not available. Check .ghl-tokens.json file." }],
+          isError: true
+        };
+      }
+      const testClient = new GHLClient({ apiKey: apiKey2 });
+      try {
+        const probe = await testClient.get("/locations/search", { params: { limit: 1, skip: 0 } });
+        const locations = probe?.locations;
+        if (!Array.isArray(locations)) {
+          throw new Error(
+            "the key was accepted by GHL but the response is not an agency location-search envelope (no locations array) \u2014 refusing to store it as the agency key"
+          );
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Failed to validate the agency key: ${message}
+
+Make sure:
+1. The Private Integration was created at the AGENCY level (Agency Settings > Private Integrations), not inside a sub-account
+2. The key is correct (it can only be copied once when created)
+3. The integration has the locations scope enabled`
+            }
+          ],
+          isError: true
+        };
+      }
+      const hadKey = Boolean(registry2.getAgencyKey());
+      registry2.setAgencyKey(apiKey2);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Agency key ${hadKey ? "replaced" : "registered"}: ${apiKey2.substring(0, 12)}...
+Saved to the token registry.
+
+Agency-wide tools now available: list_snapshots, create_snapshot_share_link, and list_available_locations (across all sub-accounts).`
+          }
+        ]
+      };
+    }
+  );
   server2.tool(
     "unregister_location",
     "Remove a GHL sub-account from the token registry.",
@@ -8345,6 +8489,11 @@ ${errors.join("\n")}` : "\nNo errors!",
 
 // src/tools/validators.ts
 var import_zod47 = require("zod");
+var ALL_CATEGORIES = ["pipeline", "stage", "custom_field", "user", "workflow", "form", "calendar", "survey"];
+var ID_SHAPE = /^[A-Za-z0-9]{17,}$/;
+function isIdShaped(s) {
+  return typeof s === "string" && ID_SHAPE.test(s);
+}
 function extractFromTrigger(trigger, refs) {
   const triggerName = String(trigger.name ?? trigger.type ?? "unnamed trigger");
   const where = `trigger "${triggerName}"`;
@@ -8354,10 +8503,21 @@ function extractFromTrigger(trigger, refs) {
     const field = typeof c.field === "string" ? c.field : null;
     const value = c.value;
     if (!field || value === void 0 || value === null) continue;
+    const childWhere = `${where} \u2192 conditions[${i}] (field=${field})`;
+    if (field.startsWith("contact.")) {
+      const suffix = field.slice("contact.".length);
+      if (suffix === "assignedTo") {
+        for (const v of Array.isArray(value) ? value : [value]) {
+          if (isIdShaped(v)) refs.push({ kind: "user", id: v, where: childWhere });
+        }
+      } else if (isIdShaped(suffix)) {
+        refs.push({ kind: "custom_field", id: suffix, where: childWhere });
+      }
+      continue;
+    }
     const valueAsArray = Array.isArray(value) ? value : [value];
     for (const v of valueAsArray) {
       if (typeof v !== "string") continue;
-      const childWhere = `${where} \u2192 conditions[${i}] (field=${field})`;
       switch (field) {
         case "opportunity.pipelineId":
           refs.push({ kind: "pipeline", id: v, where: childWhere });
@@ -8366,7 +8526,6 @@ function extractFromTrigger(trigger, refs) {
           refs.push({ kind: "stage", id: v, where: childWhere });
           break;
         case "opportunity.assignedTo":
-        case "contact.assignedTo":
           refs.push({ kind: "user", id: v, where: childWhere });
           break;
         case "workflow.id":
@@ -8384,17 +8543,18 @@ function extractFromTrigger(trigger, refs) {
       }
     }
   }
-  const triggerActions = Array.isArray(trigger.actions) ? trigger.actions : [];
-  for (let i = 0; i < triggerActions.length; i++) {
-    const a = triggerActions[i];
-    if (a.type === "add_to_workflow" && typeof a.workflow_id === "string") {
-      refs.push({
-        kind: "workflow",
-        id: a.workflow_id,
-        where: `${where} \u2192 actions[${i}] (add_to_workflow)`
-      });
+}
+function customInputId(attr, filterFields) {
+  const arr = Array.isArray(attr.__customInputFields__) ? attr.__customInputFields__ : [];
+  for (const raw of arr) {
+    if (typeof raw !== "object" || raw === null) continue;
+    const c = raw;
+    if (typeof c.filterField === "string" && filterFields.includes(c.filterField)) {
+      if (isIdShaped(c.secondValue)) return c.secondValue;
+      if (isIdShaped(c.value)) return c.value;
     }
   }
+  return void 0;
 }
 function extractFromAction(action, refs) {
   const type = typeof action.type === "string" ? action.type : "unknown";
@@ -8402,258 +8562,267 @@ function extractFromAction(action, refs) {
   const where = `action "${name}" (${type})`;
   const attr = action.attributes ?? {};
   switch (type) {
-    case "update_contact_field": {
+    // ── Contact custom fields (only id-shaped values; standard names skipped) ──
+    case "update_contact_field":
+    case "create_update_contact": {
       const fields = Array.isArray(attr.fields) ? attr.fields : [];
       for (let i = 0; i < fields.length; i++) {
         const f = fields[i];
-        if (typeof f.field === "string") {
-          refs.push({
-            kind: "custom_field",
-            id: f.field,
-            where: `${where} \u2192 fields[${i}]`
-          });
-        }
+        if (isIdShaped(f?.field)) refs.push({ kind: "custom_field", id: f.field, where: `${where} \u2192 fields[${i}]` });
       }
       break;
     }
+    // ── User refs ──
     case "internal_notification": {
       const notif = attr.notification ?? {};
-      if (typeof notif.selectedUser === "string" && notif.selectedUser.trim() !== "") {
-        refs.push({
-          kind: "user",
-          id: notif.selectedUser,
-          where: `${where} \u2192 notification.selectedUser`
-        });
+      if (isIdShaped(notif.selectedUser))
+        refs.push({ kind: "user", id: notif.selectedUser, where: `${where} \u2192 notification.selectedUser` });
+      const sms = attr.sms ?? {};
+      const smsUsers = Array.isArray(sms.selectedUser) ? sms.selectedUser : [];
+      for (let i = 0; i < smsUsers.length; i++) {
+        if (isIdShaped(smsUsers[i])) refs.push({ kind: "user", id: smsUsers[i], where: `${where} \u2192 sms.selectedUser[${i}]` });
       }
       break;
     }
-    case "task_notification": {
-      if (typeof attr.assignedTo === "string" && attr.assignedTo.trim() !== "") {
-        refs.push({
-          kind: "user",
-          id: attr.assignedTo,
-          where: `${where} \u2192 assignedTo`
-        });
-      }
+    case "task_notification":
+    case "task-notification": {
+      if (isIdShaped(attr.assignedTo))
+        refs.push({ kind: "user", id: attr.assignedTo, where: `${where} \u2192 assignedTo` });
       break;
     }
+    // ── Workflow refs ──
     case "remove_from_workflow": {
-      if (typeof attr.workflowId === "string") {
-        refs.push({
-          kind: "workflow",
-          id: attr.workflowId,
-          where: `${where} \u2192 workflowId`
-        });
-      }
-      const workflowIdArr = Array.isArray(attr.workflow_id) ? attr.workflow_id : [];
-      for (let i = 0; i < workflowIdArr.length; i++) {
-        const v = workflowIdArr[i];
-        if (typeof v === "string") {
-          refs.push({
-            kind: "workflow",
-            id: v,
-            where: `${where} \u2192 workflow_id[${i}]`
-          });
-        }
-      }
+      if (typeof attr.workflowId === "string") refs.push({ kind: "workflow", id: attr.workflowId, where: `${where} \u2192 workflowId` });
+      const arr = Array.isArray(attr.workflow_id) ? attr.workflow_id : [];
+      for (let i = 0; i < arr.length; i++) if (typeof arr[i] === "string") refs.push({ kind: "workflow", id: arr[i], where: `${where} \u2192 workflow_id[${i}]` });
+      break;
+    }
+    // ── Opportunity refs — FOUR distinct shapes ──
+    case "internal_create_opportunity": {
+      if (isIdShaped(attr.pipelineId)) refs.push({ kind: "pipeline", id: attr.pipelineId, where: `${where} \u2192 pipelineId` });
+      const stage = customInputId(attr, ["pipelineStageId"]);
+      if (stage) refs.push({ kind: "stage", id: stage, where: `${where} \u2192 __customInputFields__.pipelineStageId` });
+      break;
+    }
+    case "create_opportunity": {
+      if (isIdShaped(attr.pipeline_id)) refs.push({ kind: "pipeline", id: attr.pipeline_id, where: `${where} \u2192 pipeline_id` });
+      if (isIdShaped(attr.pipeline_stage_id)) refs.push({ kind: "stage", id: attr.pipeline_stage_id, where: `${where} \u2192 pipeline_stage_id` });
       break;
     }
     case "internal_update_opportunity": {
-      const customInputs = Array.isArray(attr.__customInputFields__) ? attr.__customInputFields__ : [];
-      for (let i = 0; i < customInputs.length; i++) {
-        const c = customInputs[i];
-        if (typeof c.value !== "string") continue;
-        if (c.filterField === "pipelineId") {
-          refs.push({ kind: "pipeline", id: c.value, where: `${where} \u2192 __customInputFields__[${i}].pipelineId` });
-        } else if (c.filterField === "pipelineStageId") {
-          refs.push({ kind: "stage", id: c.value, where: `${where} \u2192 __customInputFields__[${i}].pipelineStageId` });
+      const pipe = customInputId(attr, ["pipelineId"]);
+      if (pipe) refs.push({ kind: "pipeline", id: pipe, where: `${where} \u2192 __customInputFields__.pipelineId` });
+      const stage = customInputId(attr, ["pipelineStageId"]);
+      if (stage) refs.push({ kind: "stage", id: stage, where: `${where} \u2192 __customInputFields__.pipelineStageId` });
+      break;
+    }
+    case "find_opportunity": {
+      const pipe = customInputId(attr, ["pipeline_id", "pipelineId"]);
+      if (pipe) refs.push({ kind: "pipeline", id: pipe, where: `${where} \u2192 __customInputFields__.pipeline_id` });
+      break;
+    }
+    // ── if_else condition node: custom-field id is conditionSubType (NOT conditionValue) ──
+    case "if_else": {
+      const branches = Array.isArray(attr.branches) ? attr.branches : [];
+      for (const b of branches) {
+        const segs = b && typeof b === "object" && Array.isArray(b.segments) ? b.segments : [];
+        for (const s of segs) {
+          const conds = s && typeof s === "object" && Array.isArray(s.conditions) ? s.conditions : [];
+          for (const raw of conds) {
+            if (typeof raw !== "object" || raw === null) continue;
+            const c = raw;
+            if (c.conditionType === "contact_detail" && c.conditionSubType !== "tags" && isIdShaped(c.conditionSubType)) {
+              refs.push({ kind: "custom_field", id: c.conditionSubType, where: `${where} \u2192 if_else condition (custom field)` });
+            }
+          }
         }
       }
       break;
     }
   }
 }
+function collectIds(envelope, listKeys) {
+  const ids = /* @__PURE__ */ new Set();
+  let arr = null;
+  if (Array.isArray(envelope)) arr = envelope;
+  else if (envelope && typeof envelope === "object") {
+    const e = envelope;
+    for (const k of listKeys) if (Array.isArray(e[k])) {
+      arr = e[k];
+      break;
+    }
+  }
+  if (arr) for (const item of arr) {
+    if (typeof item === "object" && item !== null) {
+      const o = item;
+      const id = typeof o.id === "string" ? o.id : typeof o._id === "string" ? o._id : null;
+      if (id) ids.add(id);
+    }
+  }
+  return { ids, found: arr !== null };
+}
+async function fetchAndBuildLookups(client, builderClient, locationId2, workflowExistence) {
+  const fetches = {
+    pipelines: client.get("/opportunities/pipelines", { params: { locationId: locationId2 } }),
+    customFields: client.get(`/locations/${locationId2}/customFields`),
+    users: client.get("/users/", { params: { locationId: locationId2 } }),
+    forms: client.get("/forms/", { params: { locationId: locationId2 } }),
+    calendars: client.get("/calendars/", { params: { locationId: locationId2 } }),
+    surveys: client.get("/surveys/", { params: { locationId: locationId2 } })
+  };
+  const keys = Object.keys(fetches);
+  const settled = await Promise.allSettled(Object.values(fetches));
+  const data = {};
+  const failed = /* @__PURE__ */ new Set();
+  for (let i = 0; i < keys.length; i++) {
+    if (settled[i].status === "fulfilled") data[keys[i]] = settled[i].value;
+    else {
+      data[keys[i]] = null;
+      failed.add(keys[i]);
+    }
+  }
+  const status = {
+    pipeline: "loaded",
+    stage: "loaded",
+    custom_field: "loaded",
+    user: "loaded",
+    workflow: "loaded",
+    form: "loaded",
+    calendar: "loaded",
+    survey: "loaded"
+  };
+  const pipelines = /* @__PURE__ */ new Set();
+  const stages = /* @__PURE__ */ new Set();
+  if (failed.has("pipelines")) {
+    status.pipeline = "failed";
+    status.stage = "failed";
+  } else {
+    try {
+      const parsed = PipelinesResponseSchema.parse(data.pipelines);
+      for (const p of parsed.pipelines) {
+        pipelines.add(p.id);
+        for (const s of p.stages) stages.add(s.id);
+      }
+    } catch {
+      status.pipeline = "unparseable";
+      status.stage = "unparseable";
+    }
+  }
+  function setFrom(key, cat, listKeys) {
+    if (failed.has(key)) {
+      status[cat] = "failed";
+      return /* @__PURE__ */ new Set();
+    }
+    const { ids, found } = collectIds(data[key], listKeys);
+    if (!found) status[cat] = "unparseable";
+    return ids;
+  }
+  const custom_field = setFrom("customFields", "custom_field", ["customFields"]);
+  const user = setFrom("users", "user", ["users"]);
+  const form = setFrom("forms", "form", ["forms"]);
+  const calendar = setFrom("calendars", "calendar", ["calendars"]);
+  const survey = setFrom("surveys", "survey", ["surveys"]);
+  status.workflow = workflowExistence.complete ? "loaded" : "incomplete";
+  return { pipelines, stages, custom_field, user, workflow: workflowExistence.ids, form, calendar, survey, status };
+}
+function auditOneWorkflow(workflow, selfId, lookups) {
+  const refs = [];
+  const triggers = Array.isArray(workflow.triggers) ? workflow.triggers : [];
+  for (const t of triggers) extractFromTrigger(t, refs);
+  const actions = Array.isArray(workflow.workflowData?.templates) ? workflow.workflowData.templates : [];
+  for (const a of actions) extractFromAction(a, refs);
+  return refs;
+}
+function setForCategory(lookups, kind) {
+  switch (kind) {
+    case "pipeline":
+      return lookups.pipelines;
+    case "stage":
+      return lookups.stages;
+    default:
+      return lookups[kind];
+  }
+}
+function checkRefs(refs, selfId, lookups) {
+  const findings = [];
+  for (const ref of refs) {
+    const st = lookups.status[ref.kind];
+    if (st !== "loaded") {
+      findings.push({
+        severity: "unverified",
+        category: ref.kind,
+        id: ref.id,
+        where: ref.where,
+        message: `${ref.kind} reference could not be verified \u2014 the ${ref.kind} list ${st === "incomplete" ? "is too large to fully load" : "failed to load or was unreadable"}. Re-run; not reported as broken.`
+      });
+      continue;
+    }
+    const valid = setForCategory(lookups, ref.kind).has(ref.id);
+    if (valid) {
+      if (ref.kind === "workflow" && ref.id === selfId)
+        findings.push({ severity: "warning", category: ref.kind, id: ref.id, where: ref.where, message: `${ref.kind} id "${ref.id}" is valid (self-reference).` });
+    } else {
+      findings.push({
+        severity: "error",
+        category: ref.kind,
+        id: ref.id,
+        where: ref.where,
+        message: `${ref.kind} id "${ref.id}" does not exist in this location \u2014 GHL will silently skip this action and all subsequent actions when the workflow runs.`
+      });
+    }
+  }
+  return findings;
+}
+async function fullWorkflowCatalog(builderClient) {
+  const ids = /* @__PURE__ */ new Set();
+  const rows = [];
+  const limit = 100;
+  let skip = 0;
+  let complete = true;
+  for (let page = 0; page < 50; page++) {
+    const resp = await builderClient.listWorkflows(limit, skip);
+    const found = Array.isArray(resp?.rows) || Array.isArray(resp?.workflows) || Array.isArray(resp);
+    if (!found) {
+      if (page === 0) throw new Error("Could not read the workflow list (unexpected response shape) \u2014 try again.");
+      complete = false;
+      break;
+    }
+    const arr = Array.isArray(resp?.rows) ? resp.rows : Array.isArray(resp?.workflows) ? resp.workflows : Array.isArray(resp) ? resp : [];
+    for (const w of arr) {
+      if (w && typeof w === "object") {
+        const o = w;
+        const id = typeof o._id === "string" ? o._id : typeof o.id === "string" ? o.id : null;
+        if (id) {
+          ids.add(id);
+          rows.push({ id, name: typeof o.name === "string" ? o.name : id });
+        }
+      }
+    }
+    if (arr.length < limit) break;
+    skip += limit;
+    if (page === 49) complete = false;
+  }
+  return { ids, rows, complete };
+}
 function registerValidatorTools(server2, client, builderClient) {
   if (!builderClient) return;
   server2.tool(
     "validate_workflow",
-    "Pre-flight ID validation for a deployed GHL workflow. Scans every trigger and action for references to pipelines, pipeline stages, custom fields, users, workflows, forms, calendars, and surveys; verifies each ID exists in the current location. Use this BEFORE publish_workflow when a workflow has been edited, or whenever a published workflow stops behaving as expected. Catches the silent-failure bug where invalid IDs make GHL skip all subsequent actions without warning. Returns a structured report of valid + missing references.",
-    {
-      workflowId: import_zod47.z.string().describe("The workflow ID to validate.")
-    },
+    "Pre-flight ID validation for ONE deployed GHL workflow. Scans every trigger and action for references to pipelines, pipeline stages, custom fields, users, workflows, forms, calendars, and surveys; verifies each ID exists in the current location. Use BEFORE publish_workflow when a workflow was edited, or when a published workflow stops behaving. Catches the silent-failure bug where invalid IDs make GHL skip all subsequent actions. Never reports a false break \u2014 anything it cannot fully verify is marked 'unverified', not 'error'.",
+    { workflowId: import_zod47.z.string().describe("The workflow ID to validate.") },
     async ({ workflowId }) => {
       try {
-        let collectIds2 = function(envelope, listKey) {
-          const ids = /* @__PURE__ */ new Set();
-          if (envelope && typeof envelope === "object") {
-            const e = envelope;
-            const arr = Array.isArray(e[listKey]) ? e[listKey] : Array.isArray(envelope) ? envelope : [];
-            for (const item of arr) {
-              if (typeof item === "object" && item !== null) {
-                const o = item;
-                const id = typeof o.id === "string" ? o.id : typeof o._id === "string" ? o._id : null;
-                if (id) ids.add(id);
-              }
-            }
-          }
-          return ids;
-        };
-        var collectIds = collectIds2;
         const workflow = await builderClient.getWorkflow(workflowId);
         if (!workflow) return errorResponse(new Error(`Workflow ${workflowId} not found`));
         const refs = [];
-        const triggers = Array.isArray(workflow.triggers) ? workflow.triggers : [];
-        for (const t of triggers) {
-          extractFromTrigger(t, refs);
-        }
-        const actions = workflow.workflowData?.templates ?? [];
-        for (const a of actions) {
-          extractFromAction(a, refs);
-        }
-        if (refs.length === 0) {
-          const empty = {
-            workflowId,
-            workflowName: workflow.name,
-            status: "ok",
-            references_scanned: 0,
-            issues_count: 0,
-            findings: []
-          };
-          return jsonResponse(empty);
-        }
-        const refCategories = new Set(refs.map((r) => r.kind));
-        const locationId2 = client.defaultLocationId;
-        const fetches = {};
-        if (refCategories.has("pipeline") || refCategories.has("stage")) {
-          fetches.pipelines = client.get("/opportunities/pipelines", { params: { locationId: locationId2 } });
-        }
-        if (refCategories.has("custom_field")) {
-          fetches.customFields = client.get(`/locations/${locationId2}/customFields`);
-        }
-        if (refCategories.has("user")) {
-          fetches.users = client.get("/users/", { params: { locationId: locationId2 } });
-        }
-        if (refCategories.has("workflow")) {
-          fetches.workflows = builderClient.listWorkflows(200);
-        }
-        if (refCategories.has("form")) {
-          fetches.forms = client.get("/forms/", { params: { locationId: locationId2 } });
-        }
-        if (refCategories.has("calendar")) {
-          fetches.calendars = client.get("/calendars/", { params: { locationId: locationId2 } });
-        }
-        if (refCategories.has("survey")) {
-          fetches.surveys = client.get("/surveys/", { params: { locationId: locationId2 } });
-        }
-        const results = await Promise.allSettled(Object.values(fetches));
-        const keys = Object.keys(fetches);
-        const data = {};
-        for (let i = 0; i < keys.length; i++) {
-          const r = results[i];
-          data[keys[i]] = r.status === "fulfilled" ? r.value : null;
-        }
-        const validPipelineIds = /* @__PURE__ */ new Set();
-        const validStageIds = /* @__PURE__ */ new Set();
-        const stageToPipeline = /* @__PURE__ */ new Map();
-        if (data.pipelines) {
-          try {
-            const parsed = PipelinesResponseSchema.parse(data.pipelines);
-            for (const p of parsed.pipelines) {
-              validPipelineIds.add(p.id);
-              for (const s of p.stages) {
-                validStageIds.add(s.id);
-                stageToPipeline.set(s.id, p.id);
-              }
-            }
-          } catch {
-          }
-        }
-        const validCustomFieldIds = /* @__PURE__ */ new Set();
-        if (data.customFields && typeof data.customFields === "object") {
-          const cf = data.customFields;
-          const arr = Array.isArray(cf.customFields) ? cf.customFields : Array.isArray(cf) ? cf : [];
-          for (const f of arr) {
-            if (typeof f === "object" && f !== null && typeof f.id === "string") {
-              validCustomFieldIds.add(f.id);
-            }
-          }
-        }
-        const validUserIds = /* @__PURE__ */ new Set();
-        if (data.users && typeof data.users === "object") {
-          const u = data.users;
-          const arr = Array.isArray(u.users) ? u.users : Array.isArray(u) ? u : [];
-          for (const user of arr) {
-            if (typeof user === "object" && user !== null && typeof user.id === "string") {
-              validUserIds.add(user.id);
-            }
-          }
-        }
-        const validWorkflowIds = /* @__PURE__ */ new Set();
-        if (data.workflows && typeof data.workflows === "object") {
-          const w = data.workflows;
-          const arr = Array.isArray(w.rows) ? w.rows : Array.isArray(w.workflows) ? w.workflows : Array.isArray(w) ? w : [];
-          for (const wf of arr) {
-            if (typeof wf === "object" && wf !== null) {
-              const o = wf;
-              const id = typeof o._id === "string" ? o._id : typeof o.id === "string" ? o.id : null;
-              if (id) validWorkflowIds.add(id);
-            }
-          }
-        }
-        const validFormIds = collectIds2(data.forms, "forms");
-        const validCalendarIds = collectIds2(data.calendars, "calendars");
-        const validSurveyIds = collectIds2(data.surveys, "surveys");
-        const findings = [];
-        for (const ref of refs) {
-          let valid = false;
-          let extraMsg = "";
-          switch (ref.kind) {
-            case "pipeline":
-              valid = validPipelineIds.has(ref.id);
-              break;
-            case "stage":
-              valid = validStageIds.has(ref.id);
-              break;
-            case "custom_field":
-              valid = validCustomFieldIds.has(ref.id);
-              break;
-            case "user":
-              valid = validUserIds.has(ref.id);
-              break;
-            case "workflow":
-              valid = validWorkflowIds.has(ref.id);
-              if (valid && ref.id === workflowId) {
-                extraMsg = " (self-reference)";
-              }
-              break;
-            case "form":
-              valid = validFormIds.has(ref.id);
-              break;
-            case "calendar":
-              valid = validCalendarIds.has(ref.id);
-              break;
-            case "survey":
-              valid = validSurveyIds.has(ref.id);
-              break;
-          }
-          if (!valid) {
-            findings.push({
-              severity: "error",
-              category: ref.kind,
-              id: ref.id,
-              where: ref.where,
-              message: `${ref.kind} id "${ref.id}" does not exist in this location \u2014 GHL will silently skip this action and all subsequent actions when the workflow runs.`
-            });
-          } else if (extraMsg) {
-            findings.push({
-              severity: "warning",
-              category: ref.kind,
-              id: ref.id,
-              where: ref.where,
-              message: `${ref.kind} id "${ref.id}" is valid${extraMsg}.`
-            });
-          }
-        }
+        for (const t of Array.isArray(workflow.triggers) ? workflow.triggers : []) extractFromTrigger(t, refs);
+        for (const a of Array.isArray(workflow.workflowData?.templates) ? workflow.workflowData.templates : []) extractFromAction(a, refs);
+        if (refs.length === 0)
+          return jsonResponse({ workflowId, workflowName: workflow.name, status: "ok", references_scanned: 0, issues_count: 0, findings: [] });
+        const needWorkflows = refs.some((r) => r.kind === "workflow");
+        const catalog = needWorkflows ? await fullWorkflowCatalog(builderClient) : { ids: /* @__PURE__ */ new Set(), complete: true };
+        const lookups = await fetchAndBuildLookups(client, builderClient, client.defaultLocationId, { ids: catalog.ids, complete: catalog.complete });
+        const findings = checkRefs(refs, workflowId, lookups);
         const report = {
           workflowId,
           workflowName: workflow.name,
@@ -8668,6 +8837,69 @@ function registerValidatorTools(server2, client, builderClient) {
       }
     }
   );
+  server2.tool(
+    "audit_workflows",
+    "Account-wide silent-failure audit: scans EVERY workflow in the current location for references to pipelines/stages/custom-fields/users/workflows/forms/calendars/surveys that don't exist \u2014 the GHL bug where one bad ID silently kills that action and all actions after it. Returns a prioritized report of what's broken, what couldn't be scanned, and what couldn't be fully verified. Conservative: never reports a false break (uncertain checks are 'unverified', not 'broken'). Read-only.",
+    {},
+    async () => {
+      try {
+        const locationId2 = client.defaultLocationId;
+        const catalog = await fullWorkflowCatalog(builderClient);
+        if (catalog.rows.length === 0)
+          return jsonResponse({ location_id: locationId2, summary: { workflows_total: 0, workflows_scanned: 0, status: "ok", message: "No workflows found in this location." }, workflows_with_issues: [], unscannable: [] });
+        const lookups = await fetchAndBuildLookups(client, builderClient, locationId2, { ids: catalog.ids, complete: catalog.complete });
+        const SCAN_CAP = 300;
+        const toScan = catalog.rows.slice(0, SCAN_CAP);
+        const CONCURRENCY = 6;
+        const results = [];
+        const unscannable = [];
+        let zeroRefCount = 0;
+        for (let i = 0; i < toScan.length; i += CONCURRENCY) {
+          const batch = toScan.slice(i, i + CONCURRENCY);
+          await Promise.all(batch.map(async (row) => {
+            try {
+              const wf = await builderClient.getWorkflow(row.id);
+              const refs = auditOneWorkflow(wf, row.id, lookups);
+              if (refs.length === 0) zeroRefCount++;
+              const findings = checkRefs(refs, row.id, lookups);
+              results.push({ id: row.id, name: wf.name ?? row.name, status: wf.status, refs: refs.length, findings });
+            } catch (e) {
+              unscannable.push({ id: row.id, name: row.name, reason: e instanceof Error ? e.message : String(e) });
+            }
+          }));
+        }
+        const withErrors = results.filter((r) => r.findings.some((f) => f.severity === "error")).map((r) => ({ workflowId: r.id, workflowName: r.name, status: r.status, errors: r.findings.filter((f) => f.severity === "error") })).sort((a, b) => (a.status === "published" ? -1 : 1) - (b.status === "published" ? -1 : 1));
+        const errorsTotal = withErrors.reduce((n, w) => n + w.errors.length, 0);
+        const unverifiedCats = ALL_CATEGORIES.filter((c) => lookups.status[c] !== "loaded");
+        const unverifiedRefs = results.reduce((n, r) => n + r.findings.filter((f) => f.severity === "unverified").length, 0);
+        return jsonResponse({
+          location_id: locationId2,
+          summary: {
+            workflows_total: catalog.rows.length,
+            workflows_scanned: results.length,
+            enumeration_complete: catalog.complete,
+            capped: catalog.rows.length > SCAN_CAP,
+            workflows_with_errors: withErrors.length,
+            errors_total: errorsTotal,
+            workflows_unscannable: unscannable.length,
+            workflows_zero_references: zeroRefCount,
+            unverified: { categories_unloaded: unverifiedCats, references_unverified: unverifiedRefs },
+            status: errorsTotal > 0 ? "issues_found" : "ok"
+          },
+          workflows_with_issues: withErrors,
+          unscannable,
+          notes: [
+            ...catalog.complete ? [] : ["Workflow catalog exceeded the pagination backstop \u2014 some workflow-id references shown as unverified."],
+            ...catalog.rows.length > SCAN_CAP ? [`Only the first ${SCAN_CAP} workflows were scanned (account has ${catalog.rows.length}).`] : [],
+            ...unverifiedCats.length ? [`Could not fully load: ${unverifiedCats.join(", ")} \u2014 references to those are 'unverified', not 'broken'. Re-run.`] : [],
+            "workflow_goal, goto, and unrecognized condition types are not deeply checked in this version."
+          ]
+        });
+      } catch (error) {
+        return errorResponse(error);
+      }
+    }
+  );
 }
 
 // src/version-check.ts
@@ -8770,6 +9002,10 @@ function registerDiagnosticTools(server2, installedVersion, client, builderClien
         if (!registry2) {
           return { name: "Token registry", status: "skip", detail: "Not initialized \u2014 using env-var credentials only. switch_location won't auto-swap keys between sub-accounts." };
         }
+        const loadFailure = registry2.getLoadFailure();
+        if (loadFailure) {
+          return { name: "Token registry", status: "fail", detail: loadFailure };
+        }
         const locs = registry2.listLocations();
         const companies = registry2.listCompanyFirebases();
         const companyNote = companies.length ? ` ${companies.length} company Firebase credential(s) registered for multi-tenant workflow-builder access.` : "";
@@ -8833,7 +9069,7 @@ 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."
+      "Snapshots require an agency/company-scoped API key, and none is registered. This install only has sub-account Private Integration keys. Create a Private Integration at the AGENCY level in GHL (Agency Settings > Private Integrations), then run register_agency_key with that key, and retry."
     );
   }
   const storedCompanyId = client.defaultLocationId ? registry2?.getToken(client.defaultLocationId)?.companyId : void 0;
@@ -8926,6 +9162,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 +9324,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"],
@@ -9126,7 +9495,19 @@ function registerMetaTools(server2, installedVersion) {
 }
 
 // src/index.ts
-var pkg = require_package();
+var bundledPkg = require_package();
+var pkg = (() => {
+  try {
+    const onDisk = JSON.parse(
+      fs5.readFileSync(path5.resolve(__dirname, "..", "package.json"), "utf8")
+    );
+    if (typeof onDisk.version === "string" && onDisk.version.length > 0) {
+      return { version: onDisk.version };
+    }
+  } catch {
+  }
+  return bundledPkg;
+})();
 dotenv2.config();
 process.on("unhandledRejection", (reason) => {
   process.stderr.write(`[ghl-mcp] Unhandled rejection: ${reason}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.31.0",
+  "version": "3.33.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. 218 tools — full CRM, automation, marketing control, account-wide workflow audit, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",
   "bin": {
     "ghl-mcp": "dist/index.js"