@elitedcs/ghl-mcp 3.48.2 → 3.49.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 3.49.1 — Docs patch: one-click capture is now the primary Milestone-2 path
+
+No behavior changes; text only.
+
+- README "Enable the Workflow Builder": `capture_firebase_interactive` (log into a
+  Chrome window, zero pasting) is the supported path; the console-paste script is
+  demoted to a collapsed fallback (still the path for locked-down machines and for
+  capturing CLIENT accounts in multi-tenant). Rotation note now points at the
+  silent re-capture.
+- `enable_workflow_builder` and `auto_capture_firebase_script` tool descriptions
+  point to `capture_firebase_interactive` first.
+
+
+## 3.49.0 — One-click Workflow Builder unlock (`capture_firebase_interactive`)
+
+The buyer's whole job is now: log into GHL in a Chrome window the tool opens.
+No DevTools, no console paste, no JSON shuttling.
+
+- **New tool `capture_firebase_interactive`** (normal mode). Spawns a detached
+  helper (`dist/capture-helper.js`) that launches the buyer's own installed
+  Chrome (playwright-core channel discovery — Edge fallback, zero browser
+  downloads) into a dedicated persistent profile, waits for a GHL login, reads
+  the three Firebase values straight out of IndexedDB (same selection logic as
+  the console script), validates them against Firebase, and saves them via the
+  same path as `enable_workflow_builder`.
+- **Silent re-capture for token rotations.** The persistent profile keeps the
+  GHL session cookie, so every capture after the first tries HEADLESS first —
+  refresh-token rotation becomes "run the tool again, no window appears".
+- **Timeout-proof by design.** The helper is fully detached and communicates
+  through a state file; the tool call polls with a generous window and tells
+  the buyer to re-run if they're still mid-login. An MCP client timeout can
+  never strand the flow.
+- **Fallbacks intact.** No Chrome/Edge, closed window, or login timeout all
+  return clear instructions pointing at `auto_capture_firebase_script` (the
+  console-paste path, unchanged).
+- Tool count: 228 → 229 (177 without Firebase).
+
+
 ## 3.48.2 — Docs patch: tool-count claims corrected (the real number is 228)
 
 No behavior changes; text only, plus one new test.

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**Full GoHighLevel API access for Claude.** 228 tools across 48 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.** 229 tools across 48 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** — the full core toolset is now unlocked (228 tools total 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 (229 tools total with the optional Workflow Builder Firebase add-on).
 
 ### 4. Try it
 
@@ -156,9 +156,18 @@ https://app.gohighlevel.com/v2/location/YOUR_LOCATION_ID/dashboard
 
 ## Enable the Workflow Builder
 
-The builder + cloner + validator tools (workflow builder, funnel builder, form builder, pipeline builder, workflow cloner, validate_workflow) use GHL's internal API and require Firebase credentials. Without them, the other 176 tools work fine — you just won't have workflow/funnel/form/pipeline editing. This is the flagship feature: do this step.
+The builder + cloner + validator tools (workflow builder, funnel builder, form builder, pipeline builder, workflow cloner, validate_workflow) use GHL's internal API and require Firebase credentials. Without them, the other 177 tools work fine — you just won't have workflow/funnel/form/pipeline editing. This is the flagship feature: do this step.
 
-**One-paste capture (the supported path):**
+**One-click capture (v3.49.0+, the supported path):**
+
+1. In Claude, ask: `Run capture_firebase_interactive`. Your installed Chrome opens a dedicated window on the GHL login page (no browser download; it never touches your daily browsing profile).
+2. Log into your GHL account in that window. That's the whole job — the tool reads the three Firebase values itself, validates them against Firebase, and saves them. If the call says it's still waiting, finish logging in and run the same tool again.
+3. Restart Claude. The Firebase-gated tools are live.
+
+> Firebase refresh tokens can rotate. If workflow tools stop working after a few weeks (`health_check` shows Firebase auth: FAIL), just re-run `capture_firebase_interactive` — after your first login it re-captures silently, no window at all.
+
+<details>
+<summary><strong>Console-paste fallback</strong> (no Chrome/Edge installed, the window path fails, or you're capturing a CLIENT account for multi-tenant)</summary>
 
 1. In Claude, ask: `Run auto_capture_firebase_script`. It returns a small browser-console script.
 2. In Chrome, open a tab logged into your GHL account. Press **F12** (Windows) or **Cmd+Option+I** (Mac), click the **Console** tab, paste the script, press Enter. If Chrome blocks the paste, type `allow pasting` in the Console first, then paste again.
@@ -168,7 +177,7 @@ The builder + cloner + validator tools (workflow builder, funnel builder, form b
 
 Screenshots and the same script behind a copy button: [elitedcs.com/ghl-mcp-firebase](https://elitedcs.com/ghl-mcp-firebase)
 
-> Firebase refresh tokens can rotate. If workflow tools stop working after a few weeks (`health_check` shows Firebase auth: FAIL), re-run `auto_capture_firebase_script` for fresh values and pass them to `enable_workflow_builder` again.
+</details>
 
 <details>
 <summary><strong>Manual fallback</strong> (locked-down browsers that block console pasting or clipboard access)</summary>
@@ -736,7 +745,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 228 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 229 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/capture-helper.js

@@ -0,0 +1,288 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/interactive-capture.ts
+var fs = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var import_zod2 = require("zod");
+
+// src/credentials-store.ts
+var path = __toESM(require("path"));
+var os = __toESM(require("os"));
+var import_zod = require("zod");
+var APP_NAME = "elitedcs-ghl-mcp";
+var CredentialsSchema = import_zod.z.object({
+  license_key: import_zod.z.string().min(1),
+  email: import_zod.z.string().email(),
+  verified_at: import_zod.z.string().min(1),
+  ghl_api_key: import_zod.z.string().min(1),
+  ghl_location_id: import_zod.z.string().min(1),
+  ghl_company_id: import_zod.z.string().optional(),
+  ghl_user_id: import_zod.z.string().optional(),
+  ghl_firebase_api_key: import_zod.z.string().optional(),
+  ghl_firebase_refresh_token: import_zod.z.string().optional(),
+  // Ed25519-signed attestation from elitedcs.com/api/validate-license.
+  // v3.24.0+ writes this on every successful online validation; index.ts
+  // verifies on startup and refuses to load tools without it (closing the
+  // hand-crafted-credentials.json bypass that existed through v3.23.0).
+  // Optional in the schema only so files written by earlier versions still
+  // parse — index.ts's gate forces a re-validate when the field is missing.
+  signed_attestation: import_zod.z.string().optional()
+});
+function appDataDir() {
+  const override = process.env.GHL_MCP_CONFIG_DIR?.trim();
+  if (override) {
+    if (!path.isAbsolute(override)) {
+      throw new Error(
+        `GHL_MCP_CONFIG_DIR must be an absolute path (got "${override}"). Use e.g. /data/ghl-mcp in a container, with a volume mounted at /data.`
+      );
+    }
+    return override;
+  }
+  const home = os.homedir();
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", APP_NAME);
+  }
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+    return path.join(appData, APP_NAME);
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+  return path.join(xdg, APP_NAME);
+}
+
+// src/interactive-capture.ts
+function chromeProfileDir() {
+  return path2.join(appDataDir(), "chrome-profile");
+}
+function captureStatePath() {
+  return path2.join(appDataDir(), "interactive-capture.json");
+}
+var CaptureStateSchema = import_zod2.z.object({
+  status: import_zod2.z.enum(["waiting_login", "captured", "timeout", "error"]),
+  startedAt: import_zod2.z.string(),
+  updatedAt: import_zod2.z.string(),
+  // Present when status === "captured"
+  ghl_firebase_api_key: import_zod2.z.string().optional(),
+  ghl_user_id: import_zod2.z.string().optional(),
+  ghl_firebase_refresh_token: import_zod2.z.string().optional(),
+  account_email: import_zod2.z.string().optional(),
+  // Present when status === "error"
+  error: import_zod2.z.string().optional()
+});
+function writeCaptureState(state) {
+  const dir = appDataDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  fs.writeFileSync(captureStatePath(), JSON.stringify(state, null, 2), {
+    mode: 384
+  });
+}
+var EXTRACT_FIREBASE_PAGE_FN = `async () => {
+  const pick = (rows) => {
+    const candidates = rows.filter(r => typeof r?.fbase_key === 'string' && r.fbase_key.startsWith('firebase:authUser:AIza') && r?.value?.apiKey && r?.value?.uid && r?.value?.stsTokenManager?.refreshToken);
+    if (!candidates.length) return null;
+    const v = candidates[0].value;
+    return {
+      ghl_firebase_api_key: v.apiKey,
+      ghl_user_id: v.uid,
+      ghl_firebase_refresh_token: v.stsTokenManager.refreshToken,
+      account_email: v.email || null,
+    };
+  };
+  try {
+    let poisoned = false;
+    if (typeof indexedDB.databases === 'function') {
+      const dbs = await indexedDB.databases();
+      if (dbs.some(d => d.name === 'firebaseLocalStorageDb')) {
+        const db = await new Promise((res, rej) => {
+          const r = indexedDB.open('firebaseLocalStorageDb');
+          r.onsuccess = () => res(r.result);
+          r.onerror = () => rej(r.error);
+        });
+        if (db.objectStoreNames.contains('firebaseLocalStorage')) {
+          const tx = db.transaction('firebaseLocalStorage', 'readonly');
+          const store = tx.objectStore('firebaseLocalStorage');
+          const rows = await new Promise((res, rej) => {
+            const r = store.getAll();
+            r.onsuccess = () => res(r.result);
+            r.onerror = () => rej(r.error);
+          });
+          db.close();
+          const found = pick(rows);
+          if (found) return { found };
+        } else {
+          db.close();
+          poisoned = true;
+        }
+      }
+    }
+    const lsRows = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const k = localStorage.key(i);
+      if (k && k.startsWith('firebase:authUser:AIza')) {
+        try { lsRows.push({ fbase_key: k, value: JSON.parse(localStorage.getItem(k)) }); } catch (e) {}
+      }
+    }
+    const fromLs = pick(lsRows);
+    if (fromLs) return { found: fromLs };
+    return poisoned ? { poisoned: true } : null;
+  } catch (e) {
+    return null;
+  }
+}`;
+var HEAL_POISONED_DB_PAGE_FN = `() => new Promise((resolve) => {
+  const r = indexedDB.deleteDatabase('firebaseLocalStorageDb');
+  const t = setTimeout(() => resolve('timeout'), 5000);
+  r.onsuccess = () => { clearTimeout(t); resolve('deleted'); };
+  r.onblocked = () => { clearTimeout(t); resolve('blocked'); };
+  r.onerror = () => { clearTimeout(t); resolve('error'); };
+})`;
+var EXTRACT_FIREBASE_EXPRESSION = `(${EXTRACT_FIREBASE_PAGE_FN})()`;
+var HEAL_POISONED_DB_EXPRESSION = `(${HEAL_POISONED_DB_PAGE_FN})()`;
+var GHL_APP_URL = "https://app.gohighlevel.com/";
+var HELPER_LOGIN_TIMEOUT_MS = 5 * 60 * 1e3;
+var HEADLESS_PROBE_TIMEOUT_MS = 30 * 1e3;
+function profileExists() {
+  return fs.existsSync(chromeProfileDir());
+}
+var CAPTURED_FRESH_MS = 10 * 60 * 1e3;
+var WAITING_FRESH_MS = HELPER_LOGIN_TIMEOUT_MS + 30 * 1e3;
+
+// src/capture-helper.ts
+var now = () => (/* @__PURE__ */ new Date()).toISOString();
+function writeState(partial, startedAt) {
+  writeCaptureState({ ...partial, startedAt, updatedAt: now() });
+}
+async function launchContext(headless) {
+  const { chromium } = await import("playwright-core");
+  const channels = ["chrome", "msedge"];
+  let lastError;
+  for (const channel of channels) {
+    try {
+      return await chromium.launchPersistentContext(chromeProfileDir(), {
+        channel,
+        headless,
+        viewport: null
+      });
+    } catch (e) {
+      lastError = e;
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("No Chrome or Edge installation found");
+}
+async function pollPage(context, timeoutMs) {
+  const page = context.pages()[0] ?? await context.newPage();
+  await page.goto(GHL_APP_URL, { waitUntil: "domcontentloaded", timeout: 6e4 }).catch(() => {
+  });
+  const deadline = Date.now() + timeoutMs;
+  let healed = false;
+  while (Date.now() < deadline) {
+    try {
+      const target = context.pages().find((p) => p.url().includes("gohighlevel.com")) ?? page;
+      const result = await target.evaluate(EXTRACT_FIREBASE_EXPRESSION);
+      const found = result?.found;
+      if (found?.ghl_firebase_api_key && found.ghl_user_id && found.ghl_firebase_refresh_token) {
+        return found;
+      }
+      if (result?.poisoned && !healed) {
+        healed = true;
+        await target.evaluate(HEAL_POISONED_DB_EXPRESSION).catch(() => {
+        });
+        await target.reload({ waitUntil: "domcontentloaded", timeout: 6e4 }).catch(() => {
+        });
+      }
+    } catch {
+    }
+    if (context.pages().length === 0) return null;
+    await new Promise((r) => setTimeout(r, 2e3));
+  }
+  return null;
+}
+async function main() {
+  const startedAt = now();
+  writeState({ status: "waiting_login" }, startedAt);
+  if (profileExists()) {
+    try {
+      const ctx2 = await launchContext(true);
+      try {
+        const captured = await pollPage(ctx2, HEADLESS_PROBE_TIMEOUT_MS);
+        if (captured) {
+          writeState({ status: "captured", ...toState(captured) }, startedAt);
+          await ctx2.close();
+          return;
+        }
+      } finally {
+        await ctx2.close().catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
+  let ctx;
+  try {
+    ctx = await launchContext(false);
+  } catch (e) {
+    writeState(
+      {
+        status: "error",
+        error: "Could not launch Chrome or Edge: " + (e instanceof Error ? e.message : String(e))
+      },
+      startedAt
+    );
+    return;
+  }
+  try {
+    writeState({ status: "waiting_login" }, startedAt);
+    const captured = await pollPage(ctx, HELPER_LOGIN_TIMEOUT_MS);
+    if (captured) {
+      writeState({ status: "captured", ...toState(captured) }, startedAt);
+    } else {
+      writeState({ status: "timeout" }, startedAt);
+    }
+  } catch (e) {
+    writeState(
+      { status: "error", error: e instanceof Error ? e.message : String(e) },
+      startedAt
+    );
+  } finally {
+    await ctx.close().catch(() => {
+    });
+  }
+}
+function toState(c) {
+  return {
+    ghl_firebase_api_key: c.ghl_firebase_api_key,
+    ghl_user_id: c.ghl_user_id,
+    ghl_firebase_refresh_token: c.ghl_firebase_refresh_token,
+    ...c.account_email ? { account_email: c.account_email } : {}
+  };
+}
+main().catch((e) => {
+  writeCaptureState({
+    status: "error",
+    error: e instanceof Error ? e.message : String(e),
+    startedAt: now(),
+    updatedAt: now()
+  });
+});