@elitedcs/ghl-mcp 3.3.1 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 3.4.0 — health_check tool + validate_workflow expansion + smoke-test CI
+
+**175 tools across 38 modules. Bundle: 274.6 KB.**
+
+Three improvements that buyers don't have to ask for.
+
+### `health_check` tool (NEW)
+A single diagnostic that runs five probes in parallel and reports a structured pass/fail/warn list:
+
+1. **npm registry + version** — is the registry reachable? Are you on the latest version?
+2. **GHL API key** — does it validate against `/locations/search`? (catches revoked/expired keys)
+3. **Default location** — can you actually read it? Reports the location name on success.
+4. **Firebase auth** — refreshes the workflow-builder token; reports `skip` if not configured, `pass`/`fail` if it is.
+5. **Token registry** — how many sub-accounts are registered for `switch_location`?
+
+Use case: "is my install OK?" first-line troubleshooting, post-restart sanity check after credentials rotate, support back-and-forth with buyers.
+
+### `validate_workflow` expansion
+The v3.3.1 validator now also checks **form IDs**, **calendar IDs**, and **survey IDs** in trigger conditions. Coverage went from 5 → 8 reference categories:
+- Pipeline IDs
+- Pipeline Stage IDs
+- Custom Field IDs
+- User IDs
+- Workflow IDs
+- **Form IDs** (NEW — checks `form.id` in form_submission triggers)
+- **Calendar IDs** (NEW — checks `calendar.id` in appointment / customer_appointment triggers)
+- **Survey IDs** (NEW — checks `survey.id` in survey_submission triggers)
+
+### Post-publish smoke-test CI
+A new job in `.github/workflows/publish.yml` runs after npm publish: waits for registry propagation (~30s typical), then `npx`-installs the just-published version in a clean machine, spawns it with the full MCP handshake (initialize → notifications/initialized → tools/list), and asserts that `get_mcp_version` and `setup_ghl_mcp` show up in the response.
+
+Catches the kind of publish regression where the package builds locally and uploads to npm fine but fails to boot on a buyer's machine because of a missing file, bad permission, or runtime error during tool registration. Adds ~2 minutes to the release cycle, makes future buyers safer.
+
+### Tool count tidy-up
+Fixed stale "171 tools" / "165 tools" strings in `setup-tool.ts` that buyers saw in the bootstrap-mode setup message. Now correctly reports 175 (full) / 167 (without workflow builder).
+
+### Files changed
+- `src/tools/diagnostics.ts` — NEW: `registerDiagnosticTools` + `health_check`.
+- `src/workflow-builder-client.ts` — public `checkAuth()` method for Firebase probe.
+- `src/tools/validators.ts` — form/calendar/survey reference extraction + lookups.
+- `src/tools/index.ts` — registered diagnostics module.
+- `src/setup-tool.ts` — corrected tool counts (171 → 175, 165 → 167).
+- `.github/workflows/publish.yml` — added smoke-test job.
+
 ## 3.3.1 — validate_workflow + catalogue in npm package
 
 **174 tools across 37 modules. Bundle: 266.2 KB.**

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**Full GoHighLevel API access for Claude.** 174 tools across 36 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.
+**Full GoHighLevel API access for Claude.** 175 tools across 36 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.
 
 **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).
 
@@ -98,7 +98,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 166 tools are now unlocked.
+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 167 tools are now unlocked.
 
 ### 4. Try it
 
@@ -138,7 +138,7 @@ https://app.gohighlevel.com/v2/location/YOUR_LOCATION_ID/dashboard
 
 ## Enable Workflow Builder (Optional)
 
-The 8 workflow builder tools use GHL'''s internal API and require Firebase credentials. Without them, the other 166 tools work fine — you just won'''t have workflow editing.
+The 8 workflow builder tools use GHL'''s internal API and require Firebase credentials. Without them, the other 167 tools work fine — you just won'''t have workflow editing.
 
 Grab the three values from your GHL browser session, then re-run `setup_ghl_mcp` with them:
 
@@ -167,7 +167,9 @@ Re-run setup_ghl_mcp with workflow builder:
 
 ---
 
-## Tools (174)
+## Tools (175)
+
+> **v3.4.0 adds `health_check`** — one diagnostic that reports npm registry + version, GHL API key validity, default location reachability, Firebase auth status, and token registry in a single structured report. Plus `validate_workflow` (v3.3.1) now covers form, calendar, and survey IDs in addition to pipelines/stages/custom-fields/users/workflows.
 
 ### CRM & Contacts (15 tools)
 
@@ -411,11 +413,12 @@ Re-run setup_ghl_mcp with workflow builder:
 | `get_template_questionnaire` | Get the questionnaire for a template — present to user conversationally |
 | `deploy_template` | Deploy a complete sub-account setup from a template (tags, fields, pipelines, workflows, forms). Supports dry-run mode. |
 
-### Meta (1 tool)
+### Meta & Diagnostics (2 tools)
 
 | Tool | What It Does |
 |---|---|
 | `get_mcp_version` | Check installed version against the latest published to npm. Confirms an upgrade landed after restarting Claude. Available even before GHL credentials are configured. |
+| `health_check` | Run a full health check: npm registry + version status, GHL API key validity, default location reachability, Firebase auth status, token registry presence. Use when something feels broken. |
 
 ### Other Modules
 

package/dist/index.js

@@ -31,8 +31,8 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.3.1",
-      description: "GoHighLevel MCP Server for Claude. 174 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
+      version: "3.4.0",
+      description: "GoHighLevel MCP Server for Claude. 175 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
       main: "dist/index.js",
       bin: {
         "ghl-mcp": "dist/index.js"
@@ -869,6 +869,19 @@ var WorkflowBuilderClient = class _WorkflowBuilderClient {
   getApiKey() {
     return this.apiKey;
   }
+  /**
+   * Probe Firebase auth by refreshing the ID token. Used by the health_check
+   * diagnostic tool. Does not touch GHL backend — just exchanges the refresh
+   * token at securetoken.googleapis.com.
+   */
+  async checkAuth() {
+    try {
+      await this.getIdToken();
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
   /**
    * Create from environment variables, with optional token registry fallback
    */
@@ -5960,6 +5973,15 @@ function extractFromTrigger(trigger, refs) {
         case "workflow.id":
           refs.push({ kind: "workflow", id: v, where: childWhere });
           break;
+        case "form.id":
+          refs.push({ kind: "form", id: v, where: childWhere });
+          break;
+        case "calendar.id":
+          refs.push({ kind: "calendar", id: v, where: childWhere });
+          break;
+        case "survey.id":
+          refs.push({ kind: "survey", id: v, where: childWhere });
+          break;
       }
     }
   }
@@ -6056,12 +6078,28 @@ 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, and other workflows; 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.",
+    "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_zod40.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 = [];
@@ -6099,6 +6137,15 @@ function registerValidatorTools(server2, client, builderClient) {
         if (refCategories.has("workflow")) {
           fetches.workflows = builderClient.listWorkflowsFull();
         }
+        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 = {};
@@ -6154,6 +6201,9 @@ function registerValidatorTools(server2, client, builderClient) {
             }
           }
         }
+        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;
@@ -6177,6 +6227,15 @@ function registerValidatorTools(server2, client, builderClient) {
                 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({
@@ -6212,6 +6271,133 @@ function registerValidatorTools(server2, client, builderClient) {
   );
 }
 
+// src/version-check.ts
+var REGISTRY_URL = "https://registry.npmjs.org/@elitedcs/ghl-mcp/latest";
+async function fetchLatestVersion(timeoutMs = 5e3) {
+  try {
+    const response = await fetch(REGISTRY_URL, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok) return null;
+    const body = await response.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+async function getVersionStatus(installed) {
+  const latest = await fetchLatestVersion();
+  if (latest === null) {
+    return { installed, latest: null, upToDate: null, fetchError: "Could not reach npm registry" };
+  }
+  return { installed, latest, upToDate: installed === latest };
+}
+
+// src/tools/diagnostics.ts
+function registerDiagnosticTools(server2, installedVersion, client, builderClient, registry2) {
+  server2.tool(
+    "health_check",
+    "Run a full health check of the GHL Command MCP install. Reports on: npm registry + version status, GHL API key validity, default location reachability, Firebase auth status (workflow builder), and token registry. Returns a structured pass/fail/warn list with detail per check. Use this when something feels broken or after credentials change.",
+    {},
+    async () => {
+      const checks = [];
+      const versionPromise = getVersionStatus(installedVersion);
+      const apiKeyPromise = (async () => {
+        try {
+          const response = await fetch("https://services.leadconnectorhq.com/locations/search", {
+            method: "GET",
+            headers: {
+              Authorization: `Bearer ${client.getApiKey()}`,
+              "Content-Type": "application/json",
+              Accept: "application/json",
+              Version: "2021-07-28"
+            },
+            signal: AbortSignal.timeout(8e3)
+          });
+          if (response.status === 401) {
+            return { name: "GHL API key", status: "fail", detail: `401 Unauthorized \u2014 key ${client.getApiKeyPrefix()} is invalid or revoked. Run setup_ghl_mcp with a fresh key.` };
+          }
+          if (!response.ok) {
+            return { name: "GHL API key", status: "warn", detail: `HTTP ${response.status} from /locations/search \u2014 key may be limited or GHL is having issues.` };
+          }
+          return { name: "GHL API key", status: "pass", detail: `Valid (key ${client.getApiKeyPrefix()}).` };
+        } catch (error) {
+          return { name: "GHL API key", status: "warn", detail: `Network error: ${error instanceof Error ? error.message : String(error)}. Server starts anyway; tool calls will report errors when invoked.` };
+        }
+      })();
+      const locationPromise = (async () => {
+        const locId = client.defaultLocationId;
+        if (!locId) {
+          return { name: "Default location", status: "warn", detail: "No default location set. Tools that don't accept locationId arg will fail." };
+        }
+        try {
+          const result = await client.get(`/locations/${locId}`);
+          const loc = result.location ?? result;
+          return { name: "Default location", status: "pass", detail: `${loc?.name ?? "Unknown"} (${locId}) reachable.` };
+        } catch (error) {
+          return { name: "Default location", status: "fail", detail: `Could not read location ${locId}: ${error instanceof Error ? error.message : String(error)}` };
+        }
+      })();
+      const firebasePromise = (async () => {
+        if (!builderClient) {
+          return { name: "Firebase auth (workflow builder)", status: "skip", detail: "Not configured. Workflow builder tools (8 of 174) require ghl_user_id, ghl_firebase_api_key, ghl_firebase_refresh_token. Other 166 tools work fine without." };
+        }
+        const result = await builderClient.checkAuth();
+        if (result.ok) {
+          return { name: "Firebase auth (workflow builder)", status: "pass", detail: "ID token refresh succeeded. Workflow builder tools are usable." };
+        }
+        return { name: "Firebase auth (workflow builder)", status: "fail", detail: `Token refresh failed: ${result.error}. Re-capture Firebase values from GHL DevTools and re-run setup_ghl_mcp.` };
+      })();
+      const registryCheck = (() => {
+        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 locs = registry2.listLocations();
+        if (locs.length === 0) {
+          return { name: "Token registry", status: "warn", detail: "Initialized but empty \u2014 register sub-accounts via register_location for cross-account switching." };
+        }
+        return { name: "Token registry", status: "pass", detail: `${locs.length} sub-account(s) registered.` };
+      })();
+      const [versionStatus, apiKeyCheck, locationCheck, firebaseCheck] = await Promise.all([
+        versionPromise,
+        apiKeyPromise,
+        locationPromise,
+        firebasePromise
+      ]);
+      let versionCheck;
+      if (versionStatus.latest === null) {
+        versionCheck = { name: "npm registry + version", status: "warn", detail: `Installed v${versionStatus.installed}. Could not reach npm registry to check for updates: ${versionStatus.fetchError ?? "unknown"}.` };
+      } else if (versionStatus.upToDate) {
+        versionCheck = { name: "npm registry + version", status: "pass", detail: `Up to date at v${versionStatus.installed}.` };
+      } else {
+        versionCheck = { name: "npm registry + version", status: "warn", detail: `Installed v${versionStatus.installed} but latest is v${versionStatus.latest}. Quit Claude (Cmd+Q) and reopen to upgrade.` };
+      }
+      checks.push(versionCheck, apiKeyCheck, locationCheck, firebaseCheck, registryCheck);
+      const symbols = { pass: "\u2713", fail: "\u2717", warn: "!", skip: "\u2014" };
+      const lines = [];
+      lines.push("GHL Command \u2014 Health Check");
+      lines.push("\u2501".repeat(50));
+      for (const c of checks) {
+        lines.push(`${symbols[c.status]} ${c.name.padEnd(35)} ${c.status.toUpperCase()}`);
+        lines.push(`  ${c.detail}`);
+      }
+      lines.push("\u2501".repeat(50));
+      const fails = checks.filter((c) => c.status === "fail").length;
+      const warns = checks.filter((c) => c.status === "warn").length;
+      if (fails === 0 && warns === 0) {
+        lines.push("All systems go.");
+      } else {
+        const parts = [];
+        if (fails > 0) parts.push(`${fails} failure(s)`);
+        if (warns > 0) parts.push(`${warns} warning(s)`);
+        lines.push(parts.join(", ") + " \u2014 see details above.");
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+
 // src/tools/index.ts
 var publicApiTools = [
   [registerContactTools, "contacts"],
@@ -6255,6 +6441,7 @@ function registerAllTools(server2, client, registry2, mcpVersion) {
   registerPipelineBuilderTools(server2, builderClient);
   registerWorkflowClonerTools(server2, builderClient);
   registerValidatorTools(server2, client, builderClient);
+  registerDiagnosticTools(server2, mcpVersion ?? "unknown", client, builderClient, registry2 ?? null);
   registerLocationSwitcherTools(server2, client, builderClient, registry2, mcpVersion);
 }
 
@@ -6392,7 +6579,7 @@ async function validateFirebase(firebaseKey, refreshToken) {
 function registerSetupTool(server2) {
   server2.tool(
     "setup_ghl_mcp",
-    "First-run setup for GHL Command MCP. Validates your license and GHL credentials, then writes them to a per-user credentials file. Restart Claude after this completes to load all 171 tools.",
+    "First-run setup for GHL Command MCP. Validates your license and GHL credentials, then writes them to a per-user credentials file. Restart Claude after this completes to load all 175 tools.",
     {
       email: import_zod42.z.string().email().describe("Email used at purchase."),
       license_key: import_zod42.z.string().min(20).describe("License key from your purchase email."),
@@ -6447,7 +6634,7 @@ Note: Firebase credentials rejected (${fb.error}). Saved without Workflow Builde
         ghl_firebase_api_key: workflowBuilderEnabled ? args.ghl_firebase_api_key?.trim() : void 0,
         ghl_firebase_refresh_token: workflowBuilderEnabled ? args.ghl_firebase_refresh_token?.trim() : void 0
       });
-      const toolCount = workflowBuilderEnabled ? "171" : "165";
+      const toolCount = workflowBuilderEnabled ? "175" : "167";
       const wfLine = workflowBuilderEnabled ? "Workflow Builder: enabled." : "Workflow Builder: not configured (optional).";
       return {
         content: [{
@@ -6472,29 +6659,6 @@ Note: Firebase credentials rejected (${fb.error}). Saved without Workflow Builde
   );
 }
 
-// src/version-check.ts
-var REGISTRY_URL = "https://registry.npmjs.org/@elitedcs/ghl-mcp/latest";
-async function fetchLatestVersion(timeoutMs = 5e3) {
-  try {
-    const response = await fetch(REGISTRY_URL, {
-      headers: { Accept: "application/json" },
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    if (!response.ok) return null;
-    const body = await response.json();
-    return typeof body.version === "string" ? body.version : null;
-  } catch {
-    return null;
-  }
-}
-async function getVersionStatus(installed) {
-  const latest = await fetchLatestVersion();
-  if (latest === null) {
-    return { installed, latest: null, upToDate: null, fetchError: "Could not reach npm registry" };
-  }
-  return { installed, latest, upToDate: installed === latest };
-}
-
 // src/tools/meta.ts
 function registerMetaTools(server2, installedVersion) {
   server2.tool(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.3.1",
-  "description": "GoHighLevel MCP Server for Claude. 174 tools — full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
+  "version": "3.4.0",
+  "description": "GoHighLevel MCP Server for Claude. 175 tools — full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
   "main": "dist/index.js",
   "bin": {
     "ghl-mcp": "dist/index.js"