@elitedcs/ghl-mcp 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 3.5.0 — `enable_workflow_builder` tool (one-call Firebase upgrade)
+
+**176 tools across 38 modules. Bundle: 278.7 KB.**
+
+A clean second-phase setup path for buyers who skipped Firebase on day one.
+
+### The friction this removes
+Before v3.5.0, a buyer who installed without Firebase (the 90% case for non-technical buyers — they get the 168 core tools and skip workflow builder until they need it) had to **re-run `setup_ghl_mcp` with all 7 fields** when they were ready to add Firebase later. Email, license key, GHL API key, location ID — all re-entered even though they were already saved.
+
+### The fix
+New tool `enable_workflow_builder` takes only the 3 Firebase fields (`ghl_user_id`, `ghl_firebase_api_key`, `ghl_firebase_refresh_token`). It reads the existing credentials file, validates the Firebase token refresh against `securetoken.googleapis.com`, merges the Firebase fields in, and writes back. Quit + restart Claude → 8 additional tools live.
+
+If Firebase validation fails, the error message names the two most common causes (rotated refresh token, mismatched API key + refresh token from different rows) and links to the DevTools capture page.
+
+### Discoverability
+- `setup_ghl_mcp`'s success message now tells buyers about `enable_workflow_builder` when Firebase wasn't provided: *"To enable Workflow Builder later (8 extra tools): run enable_workflow_builder with your three Firebase values. No need to re-enter license/API key/location ID."*
+- `health_check`'s Firebase "skip" detail mentions the tool too. Buyers running `health_check` for the first time see exactly how to add the missing piece.
+
+### Registration
+- **Non-bootstrap mode only.** Requires existing credentials — bootstrap mode buyers should run `setup_ghl_mcp` first.
+- Returns a clear error if no credentials file exists yet.
+
+### Verified end-to-end
+- Tool registers (176 total).
+- Valid Firebase credentials → 4 basic fields preserved + 3 Firebase fields added.
+- Bogus Firebase credentials → clear error message + `isError: true`.
+- Test cleanup left real credentials intact.
+
+### Files changed
+- `src/setup-tool.ts` — added `registerEnableWorkflowBuilderTool` + import `readCredentials`; updated `setup_ghl_mcp` success message to mention the new tool when Firebase isn't provided.
+- `src/index.ts` — registers `enable_workflow_builder` in non-bootstrap mode.
+- `src/tools/diagnostics.ts` — `health_check` Firebase skip message now points at `enable_workflow_builder`.
+
+## 3.4.1 — fixes from real-world testing of v3.4.0 tools
+
+**175 tools across 38 modules. Bundle: 275.2 KB.**
+
+Two bugs caught when exercising v3.4.0's `health_check` and `validate_workflow` end-to-end against a real sandbox workflow:
+
+1. **`health_check` API-key probe used the wrong endpoint.** `/locations/search` is agency-level — sub-account Private Integration keys (the kind buyers have) get 403, not 200, even when the key is fine. Fixed to use `/locations/{locationId}` which sub-account keys can call. Also added explicit handling for 403 with a clearer message ("doesn't have access to this location" vs. just "limited").
+
+2. **`validate_workflow` errored when checking workflow references.** Called `builderClient.listWorkflowsFull()`, which doesn't exist — the actual method is `listWorkflows()`. Any workflow containing a `remove_from_workflow` action or a trigger with an `add_to_workflow` reference would crash the validator. Fixed.
+
+Also: `src/index.ts` startup `validateApiKey()` had the same wrong-endpoint bug as `health_check`; fixed for consistency. Buyers will now see "API key validated" or a clear 403 message on startup instead of silent ambiguity.
+
+### Verified end-to-end
+Re-ran the spawn-handshake test against QA Test Clinic v3:
+- `health_check` returns 5/5 PASS ("All systems go.")
+- `validate_workflow` on the CLL Onboarding Form Submitted workflow correctly scans 2 references (form.id + self-referencing workflow.id), reports 0 issues, surfaces the self-reference as an informational note.
+
+### Files changed
+- `src/tools/diagnostics.ts` — endpoint fix + 403 handling
+- `src/tools/validators.ts` — method name fix
+- `src/index.ts` — same endpoint fix in startup probe
+
 ## 3.4.0 — health_check tool + validate_workflow expansion + smoke-test CI
 
 **175 tools across 38 modules. Bundle: 274.6 KB.**

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**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.
+**Full GoHighLevel API access for Claude.** 176 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 167 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 168 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 167 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 168 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,9 +167,9 @@ Re-run setup_ghl_mcp with workflow builder:
 
 ---
 
-## Tools (175)
+## Tools (176)
 
-> **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.
+> **v3.5.0 adds `enable_workflow_builder`** — a one-call upgrade path for adding Firebase credentials to an existing install. Buyers who skip Firebase on day one can now add it later without re-entering license / API key / location ID. Reads existing credentials, validates Firebase, merges, writes back.
 
 ### CRM & Contacts (15 tools)
 
@@ -413,12 +413,13 @@ 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 & Diagnostics (2 tools)
+### Setup & Diagnostics (3 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. |
+| `enable_workflow_builder` | Add Firebase credentials to an existing install to unlock the 8 workflow builder tools. No need to re-enter license / API key / location ID. Run this any time after the basic setup, on the buyer's schedule. |
 
 ### 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.4.0",
-      description: "GoHighLevel MCP Server for Claude. 175 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
+      version: "3.5.0",
+      description: "GoHighLevel MCP Server for Claude. 176 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
       main: "dist/index.js",
       bin: {
         "ghl-mcp": "dist/index.js"
@@ -6135,7 +6135,7 @@ function registerValidatorTools(server2, client, builderClient) {
           fetches.users = client.get("/users/", { params: { locationId: locationId2 } });
         }
         if (refCategories.has("workflow")) {
-          fetches.workflows = builderClient.listWorkflowsFull();
+          fetches.workflows = builderClient.listWorkflows(200);
         }
         if (refCategories.has("form")) {
           fetches.forms = client.get("/forms/", { params: { locationId: locationId2 } });
@@ -6304,8 +6304,12 @@ function registerDiagnosticTools(server2, installedVersion, client, builderClien
       const checks = [];
       const versionPromise = getVersionStatus(installedVersion);
       const apiKeyPromise = (async () => {
+        const locId = client.defaultLocationId;
+        if (!locId) {
+          return { name: "GHL API key", status: "warn", detail: `Can't validate without a default location ID. Set GHL_LOCATION_ID or run setup_ghl_mcp.` };
+        }
         try {
-          const response = await fetch("https://services.leadconnectorhq.com/locations/search", {
+          const response = await fetch(`https://services.leadconnectorhq.com/locations/${locId}`, {
             method: "GET",
             headers: {
               Authorization: `Bearer ${client.getApiKey()}`,
@@ -6318,8 +6322,11 @@ function registerDiagnosticTools(server2, installedVersion, client, builderClien
           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.status === 403) {
+            return { name: "GHL API key", status: "fail", detail: `403 Forbidden \u2014 key ${client.getApiKeyPrefix()} doesn't have access to location ${locId}. The key may belong to a different sub-account.` };
+          }
           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: "warn", detail: `HTTP ${response.status} reading /locations/${locId} \u2014 key may be limited or GHL is having issues.` };
           }
           return { name: "GHL API key", status: "pass", detail: `Valid (key ${client.getApiKeyPrefix()}).` };
         } catch (error) {
@@ -6341,7 +6348,7 @@ function registerDiagnosticTools(server2, installedVersion, client, builderClien
       })();
       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." };
+          return { name: "Firebase auth (workflow builder)", status: "skip", detail: "Not configured. The 8 workflow builder tools need Firebase credentials. The other 168 tools work fine without. To add it: run enable_workflow_builder with the three Firebase values from your GHL browser session (see elitedcs.com/ghl-mcp-firebase for DevTools steps)." };
         }
         const result = await builderClient.checkAuth();
         if (result.ok) {
@@ -6634,8 +6641,9 @@ 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 ? "175" : "167";
+      const toolCount = workflowBuilderEnabled ? "176" : "168";
       const wfLine = workflowBuilderEnabled ? "Workflow Builder: enabled." : "Workflow Builder: not configured (optional).";
+      const wfTip = workflowBuilderEnabled ? "" : "\nTo enable Workflow Builder later (8 extra tools): run enable_workflow_builder with your three Firebase values. No need to re-enter license/API key/location ID.";
       return {
         content: [{
           type: "text",
@@ -6650,7 +6658,7 @@ Note: Firebase credentials rejected (${fb.error}). Saved without Workflow Builde
             ``,
             `**Restart Claude (quit fully and reopen) to load all ${toolCount} tools.**`,
             ``,
-            `After restart, try: "List my GHL contacts" or "Show my pipelines".`,
+            `After restart, try: "List my GHL contacts" or "Show my pipelines".${wfTip}`,
             workflowBuilderNote
           ].join("\n")
         }]
@@ -6658,6 +6666,67 @@ Note: Firebase credentials rejected (${fb.error}). Saved without Workflow Builde
     }
   );
 }
+function registerEnableWorkflowBuilderTool(server2) {
+  server2.tool(
+    "enable_workflow_builder",
+    "Add Firebase credentials to an existing GHL Command install to unlock the 8 workflow builder tools (create/edit/clone/delete/publish workflows, validate_workflow, get_trigger_registry). Requires you've already run setup_ghl_mcp. Capture the three Firebase values from your GHL browser session \u2014 see elitedcs.com/ghl-mcp-firebase for step-by-step DevTools instructions. Tool count goes from 168 to 176 after the next Claude restart.",
+    {
+      ghl_user_id: import_zod42.z.string().min(10).describe("Firebase User ID (uid). DevTools \u2192 Application \u2192 IndexedDB \u2192 firebaseLocalStorageDb \u2192 firebaseLocalStorage \u2192 the value.uid field of the firebase:authUser row."),
+      ghl_firebase_api_key: import_zod42.z.string().min(10).describe("Firebase API Key starting with 'AIza'. The string between 'firebase:authUser:' and ':[DEFAULT]' in the row's Key column."),
+      ghl_firebase_refresh_token: import_zod42.z.string().min(10).describe("Firebase refresh token. value.stsTokenManager.refreshToken in the firebase:authUser row.")
+    },
+    async (args) => {
+      const existing = readCredentials();
+      if (!existing) {
+        return {
+          content: [{
+            type: "text",
+            text: "No existing credentials found at " + credentialsPath() + ".\n\nRun setup_ghl_mcp first to register your license and basic GHL credentials, then come back to this tool to add Workflow Builder."
+          }],
+          isError: true
+        };
+      }
+      const fb = await validateFirebase(args.ghl_firebase_api_key.trim(), args.ghl_firebase_refresh_token.trim());
+      if (!fb.ok) {
+        return {
+          content: [{
+            type: "text",
+            text: `Firebase credentials rejected: ${fb.error}
+
+Common causes:
+  - The refresh token has rotated (they rotate every few weeks). Re-extract from your GHL browser tab.
+  - The Firebase API Key doesn't match the refresh token's project. Both must come from the SAME firebase:authUser row.
+
+DevTools steps: https://elitedcs.com/ghl-mcp-firebase`
+          }],
+          isError: true
+        };
+      }
+      writeCredentials({
+        ...existing,
+        ghl_user_id: args.ghl_user_id.trim(),
+        ghl_firebase_api_key: args.ghl_firebase_api_key.trim(),
+        ghl_firebase_refresh_token: args.ghl_firebase_refresh_token.trim()
+      });
+      return {
+        content: [{
+          type: "text",
+          text: [
+            "Workflow Builder enabled!",
+            "",
+            "Firebase credentials verified and saved.",
+            "",
+            "**Restart Claude (quit fully and reopen) to load the 8 additional workflow builder tools (176 total).**",
+            "",
+            'After restart, try: "List my workflows in full detail" or "Validate workflow <id>".',
+            "",
+            "Note: Firebase refresh tokens rotate every few weeks. If workflow tools stop working, re-run enable_workflow_builder with fresh values from a current GHL browser session."
+          ].join("\n")
+        }]
+      };
+    }
+  );
+}
 
 // src/tools/meta.ts
 function registerMetaTools(server2, installedVersion) {
@@ -6761,15 +6830,16 @@ if (inBootstrapMode) {
 } else {
   const client = new GHLClient({ apiKey, locationId });
   registerAllTools(server, client, registry, pkg.version);
+  registerEnableWorkflowBuilderTool(server);
   if (fileCreds && !process.env.GHL_API_KEY) {
     process.stderr.write(`[ghl-mcp] Loaded credentials from ${credentialsPath()}
 `);
   }
 }
 async function validateApiKey() {
-  if (!apiKey) return;
+  if (!apiKey || !locationId) return;
   try {
-    const response = await fetch("https://services.leadconnectorhq.com/locations/search", {
+    const response = await fetch(`https://services.leadconnectorhq.com/locations/${locationId}`, {
       method: "GET",
       headers: {
         Authorization: `Bearer ${apiKey}`,
@@ -6781,6 +6851,9 @@ async function validateApiKey() {
     });
     if (response.status === 401) {
       process.stderr.write("[ghl-mcp] WARNING: API key is invalid (401 Unauthorized). Tools will fail.\n");
+    } else if (response.status === 403) {
+      process.stderr.write(`[ghl-mcp] WARNING: API key doesn't have access to location ${locationId} (403 Forbidden).
+`);
     } else if (response.ok) {
       process.stderr.write("[ghl-mcp] API key validated.\n");
     }

package/package.json

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