@elitedcs/ghl-mcp 3.49.1 → 3.52.0

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## 3.52.0 — Fix: `update_page_content` now actually writes page content
+
+`update_page_content` was a silent no-op — it POSTed the page envelope to GHL's
+prebuilt-section template-sync route (`/funnels/builder/prebuilt-section/sync/changes`),
+which accepts the request, ignores `pageData`, returns `{"prebuiltSectionTemplates":[]}`,
+and persists nothing (the page stayed at version 1 with no `pageDataDownloadUrl`).
+Present since v3.7.0 — this capability had never worked. Reported by a customer
+(v3.47 + v3.50, custom MCP client) and reproduced.
+
+- **Re-pointed to GHL's real builder autosave endpoint**
+  `POST /funnels/builder/autosave/{pageId}`, captured live from the page builder
+  2026-07-09. The server uploads the page to Firebase Storage, bumps the version,
+  and regenerates the preview snapshot, returning the new `pageDataUrl` /
+  `pageDataDownloadUrl`. Verified end-to-end: a from-scratch API write bumps the
+  version and the content round-trips through `get_page_content`.
+- **Body shape** is `{funnelId, pageVersion, pageData: {…envelope, pageVersion,
+  pageType, manualSave, integrations}}`. The tool auto-resolves `funnelId` and the
+  current `pageVersion` from the page metadata (both optional to pass), computes
+  the `integrations` element-type counts from the content, and sends the builder
+  origin/referer + `Version` header the endpoint's IAM check requires.
+- `update_page_content` gains an optional `funnelId` arg (auto-resolved when
+  omitted). No tool-count change.
+
+## 3.51.0 — Agency sub-account provisioning (`create_sub_account` / `delete_sub_account`)
+
+The missing first step of fully programmatic client provisioning: create the
+sub-account itself (optionally loading a snapshot at creation), then Blueprint
+builds inside it and verify_funnel proves it.
+
+- **`create_sub_account`** — agency-API location create with optional
+  `snapshot_id` (see `list_snapshots`), prospect/owner info, address, timezone.
+  Probes whether the agency key can operate the new location's data plane and
+  auto-registers it in the token registry when it can (switch_location works
+  immediately). Non-idempotent create is retry-suppressed. Requires an
+  agency-level key with the locations.write scope; the error path says exactly
+  that when the scope is missing.
+- **`delete_sub_account`** — agency-API location delete, confirm-gated,
+  refuses the currently active location, cleans the token registry entry.
+- **Tool counts corrected: the real full count is 232 (180 core), free tier
+  106 (88).** A live tools/list dump exposed that `get_mcp_version` registers
+  outside the counted registry in both modes — every prior claim (229, 231,
+  free 105/87) was one short. The drift-guard constant now documents all four
+  normal-mode extras.
+- **Test-isolation fix: the suite can never clobber a real install again.**
+  credentials-store's atomicity tests wrote fixture credentials to the REAL
+  per-user credentials.json (no GHL_MCP_CONFIG_DIR override) — any dev running
+  the suite silently broke their own install on next restart. Tests now run in
+  a temp dir AND writeCredentials refuses to run under vitest without an
+  override.
+
+
+## 3.50.0 — FREE read-only tier
+
+A free license (`ghlcommand.com/free`, key by email, no card) now runs the same
+npm package in read-only mode on the user's own GHL account.
+
+- **Tier gating in the tool registry** (`tool-filter.ts`, second axis alongside
+  the env allowlist). Free tier: every read-only tool works for real — all
+  `get_*`/`list_*`/`search_*` plus `audit_workflows`, `validate_workflow`,
+  `get_account_health_summary`, `compare_locations`, `verify_funnel`,
+  `check_blog_slug`, `workflow_builder_status`. That's **105 usable tools with
+  the Firebase login (87 before it)**, enumerated from the registry by the
+  drift-guard test. Write tools still register with full schemas but their
+  handlers return a clean upgrade message (checkout link, same-key upgrade
+  note) — never a stack trace, never a half-executed write. Excluded from free
+  by design: `export_account`, the whole Blueprint (`intake-to-build`) module,
+  and the multi-location registry writes (`register_location`,
+  `register_agency_key`, `switch_location`, …) — free is 1 location, 1 machine.
+- **Tier is cryptographically bound.** The license server now signs `tier`
+  inside the Ed25519 attestation payload; the MCP derives the session tier ONLY
+  from a verified attestation (legacy attestations without the field = 'full').
+  Hand-editing credentials.json cannot unlock writes. Old MCP versions ignore
+  the extra payload field — fully backward compatible.
+- **Firebase capture stays available on free** (`capture_firebase_interactive`,
+  `enable_workflow_builder`, `auto_capture_firebase_script`): the one-time GHL
+  login is what powers the read-only auditor suite. Builder writes stay gated.
+- **setup_ghl_mcp / request_license** are tier-aware: free installs see the
+  read-only counts and the auditor-unlock next step; request_license now offers
+  the free tier (`ghlcommand.com/free`) alongside purchase.
+- **Drift guard extended** (`tool-count.test.ts`): free-tier counts (105/87)
+  are computed from the registry and asserted against README + setup-tool copy;
+  a classification change breaks the build until the claims are re-synced. The
+  ghlcommand.com `/free` page and the key-delivery email carry the same number —
+  re-sync those manually when this test moves (different repos).
+- Server side (elite-dcs/website + Supabase, deployed separately): `licenses.status`
+  gains `'free'`; `register_device` returns the row status; `validate-license`
+  returns + signs `tier`; the Stripe webhook upgrades a free row IN PLACE on
+  purchase (same key, installs 1→3, `source: stripe_97mo_from_free`) — proven
+  against a live throwaway row and a mocked-fetch webhook harness. New
+  `/api/free-license` provisioning endpoint (signup → row → key email → 3NA51
+  tag `ghl-command-free-tier`).
+
 ## 3.49.1 — Docs patch: one-click capture is now the primary Milestone-2 path
 
 No behavior changes; text only.

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**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.
+**Full GoHighLevel API access for Claude.** 232 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).
 
@@ -8,6 +8,8 @@ Works with **both the Claude Desktop App and Claude Code terminal** — your cho
 
 **License required.** Get it at [ghlcommand.com](https://ghlcommand.com?utm_source=npm&utm_medium=readme) — $97/mo, covering UNLIMITED GoHighLevel sub-accounts on up to 3 machines (never billed per account). **30-day time-back guarantee**: save 5+ hours on one client build or your first month back.
 
+**Try it FREE (read-only tier).** Grab an instant free key at [ghlcommand.com/free](https://ghlcommand.com/free?utm_source=npm&utm_medium=readme) — 106 read-only tools on your own GHL account (88 before the one-login auditor unlock): the account-wide workflow audit (`audit_workflows` finds the silently broken references GHL never warns you about), account health, and every read across contacts, pipelines, funnels, and workflows. Write tools stay visible and answer with upgrade info. Buying later with the same email upgrades your key in place — 1 machine on free, 3 when you upgrade.
+
 Built by [Elite DCs, LLC](https://elitedcs.com).
 
 ---
@@ -116,7 +118,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 (229 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 (232 tools total with the optional Workflow Builder Firebase add-on).
 
 ### 4. Try it
 
@@ -156,7 +158,7 @@ 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 177 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 180 tools work fine — you just won't have workflow/funnel/form/pipeline editing. This is the flagship feature: do this step.
 
 **One-click capture (v3.49.0+, the supported path):**
 
@@ -745,7 +747,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 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`:
+Every registered MCP tool's schema is shipped to the model on every message. With 232 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.49.1",
+      version: "3.52.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
-      description: "GoHighLevel MCP Server for Claude. 229 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, live funnel-capture verification, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
+      description: "GoHighLevel MCP Server for Claude. 232 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, live funnel-capture verification, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
       bin: {
         "ghl-mcp": "dist/index.js"
@@ -370,6 +370,11 @@ function foldCredentialsIntoEnv(creds, env = process.env) {
   }
 }
 function writeCredentials(creds) {
+  if (process.env.VITEST && !process.env.GHL_MCP_CONFIG_DIR) {
+    throw new Error(
+      "writeCredentials under vitest without GHL_MCP_CONFIG_DIR \u2014 set it to a temp dir in the test (see interactive-capture.test.ts) so the real credentials.json is never touched."
+    );
+  }
   ensureAppDataDir();
   const file = credentialsPath();
   const tmp = `${file}.tmp.${process.pid}.${Date.now()}`;
@@ -1947,6 +1952,47 @@ var ALWAYS_ON_TOOL_NAMES = /* @__PURE__ */ new Set([
   "enable_workflow_builder",
   "health_check"
 ]);
+var FREE_TIER_EXTRA_READ_TOOLS = /* @__PURE__ */ new Set([
+  "audit_workflows",
+  // account-wide silent-failure audit — the free tier's wow moment
+  "validate_workflow",
+  // single-workflow pre-flight validation (read-only)
+  "compare_locations",
+  // cross-location config diff (reads only)
+  "verify_funnel",
+  // live funnel QA (reads + public URL probes)
+  "check_blog_slug",
+  // slug availability lookup
+  "workflow_builder_status"
+  // no-Firebase fallback diagnostic (pure status read)
+]);
+var FREE_TIER_EXCLUDED_TOOLS = /* @__PURE__ */ new Set([
+  "export_account"
+  // full-account export is a paid capability
+]);
+var FREE_TIER_EXCLUDED_MODULES = /* @__PURE__ */ new Set([
+  "intake-to-build"
+  // Blueprint lane is paid end-to-end
+]);
+var READ_PREFIXES = ["get_", "list_", "search_"];
+function isFreeTierTool(toolName, moduleName) {
+  if (ALWAYS_ON_TOOL_NAMES.has(toolName)) return true;
+  if (FREE_TIER_EXCLUDED_MODULES.has(moduleName.toLowerCase())) return false;
+  if (FREE_TIER_EXCLUDED_TOOLS.has(toolName)) return false;
+  if (FREE_TIER_EXTRA_READ_TOOLS.has(toolName)) return true;
+  return READ_PREFIXES.some((p) => toolName.startsWith(p));
+}
+var FREE_TIER_DESC_SUFFIX = " [PAID TIER \u2014 this free license is read-only; calling this returns upgrade info, it will NOT perform the action.]";
+function freeTierUpgradeMessage(toolName) {
+  return [
+    `\`${toolName}\` needs the full GHL Command license \u2014 your free key is the read-only tier.`,
+    "",
+    "Free tier (what you have): every read \u2014 audits, account health, pipelines, contacts, conversations, funnels, workflows \u2014 on your own account.",
+    "Full tier ($97/mo founding rate): Claude actually builds and fixes things \u2014 workflows, funnels, forms, pipelines, campaigns \u2014 plus the Workflow Builder, multi-location, and 3-machine activation.",
+    "",
+    "Upgrade at https://ghlcommand.com with the SAME email you used for the free key \u2014 your license upgrades in place (no reinstall, same key). Then fully restart Claude and this tool goes live."
+  ].join("\n");
+}
 function parseList(raw) {
   if (raw === void 0) return null;
   const items = raw.split(/[,\s]+/).map((x) => x.trim().toLowerCase()).filter((x) => x.length > 0);
@@ -1974,7 +2020,7 @@ function shouldRegister(toolName, moduleName, config3) {
   const toolEnabled = config3.enabledTools?.has(toolLower) ?? false;
   return moduleEnabled || toolEnabled;
 }
-function wrapServerForModule(realServer, moduleName, config3, attemptedTools, registeredTools) {
+function wrapServerForModule(realServer, moduleName, config3, attemptedTools, registeredTools, tier = "full", gatedTools) {
   return new Proxy(realServer, {
     get(target, prop, receiver) {
       if (prop === "tool") {
@@ -1984,7 +2030,21 @@ function wrapServerForModule(realServer, moduleName, config3, attemptedTools, re
             return void 0;
           }
           registeredTools.add(name);
-          return target.tool(name, ...rest);
+          let args = rest;
+          if (tier === "free" && !isFreeTierTool(name, moduleName)) {
+            gatedTools?.add(name);
+            args = [...rest];
+            const last = args.length - 1;
+            if (last >= 0 && typeof args[last] === "function") {
+              args[last] = async () => ({
+                content: [{ type: "text", text: freeTierUpgradeMessage(name) }]
+              });
+            }
+            if (typeof args[0] === "string") {
+              args[0] = args[0] + FREE_TIER_DESC_SUFFIX;
+            }
+          }
+          return target.tool(name, ...args);
         };
       }
       return Reflect.get(target, prop, receiver);
@@ -6115,22 +6175,85 @@ ${text2}`);
       }
     }
   );
+  function toCamel(meta) {
+    return meta.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+  }
+  function computeIntegrations(pageData) {
+    const counts = {};
+    let videoBackground = false;
+    const sections = Array.isArray(pageData.sections) ? pageData.sections : [];
+    for (const sec of sections) {
+      const bg = sec.metaData?.extra?.bgImage?.value;
+      if (bg && bg.mediaType === "video" && bg.videoUrl) videoBackground = true;
+      const elements = Array.isArray(sec.elements) ? sec.elements : [];
+      for (const el of elements) {
+        if (el.type !== "element") continue;
+        const meta = typeof el.meta === "string" ? el.meta : null;
+        if (!meta) continue;
+        const key = toCamel(meta);
+        counts[key] = (counts[key] ?? 0) + 1;
+      }
+    }
+    const popupsList = pageData.popupsList;
+    const popup = Array.isArray(popupsList) && popupsList.length > 0;
+    return {
+      videoBackground,
+      blogMeta: { selectedBlogCategories: [], categoryNavigationList: [] },
+      ...counts,
+      popup
+    };
+  }
+  async function autosaveRequest(pageId, body) {
+    const headers = await client.buildHeaders();
+    headers.Origin = "https://page-builder.leadconnectorhq.com";
+    headers.Referer = "https://page-builder.leadconnectorhq.com/";
+    const url = `https://backend.leadconnectorhq.com/funnels/builder/autosave/${pageId}`;
+    const response = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+    if (!response.ok) {
+      throw new Error(`Funnel API Error ${response.status}: POST /builder/autosave/${pageId}
+${await response.text()}`);
+    }
+    const text = await response.text();
+    if (!text) return {};
+    try {
+      return JSON.parse(text);
+    } catch {
+      return JSON.parse(text.replace(/[\x00-\x1F\x7F]/g, ""));
+    }
+  }
   server2.tool(
     "update_page_content",
-    "Update a page's builder content \u2014 sections, elements, settings, pageStyles, trackingCode, popups, popupsList, fontsForPreview. Use get_page_content first to see the current structure, modify it, then pass the full 8-field envelope here. GHL's UI fires three POSTs to this endpoint per save (one collaborative-edit broadcast + two commits); for MCP use, one POST with write=true is enough.",
+    "Update a funnel/website page's builder content \u2014 sections, elements, settings, pageStyles, trackingCode, popups, popupsList, fontsForPreview. Use get_page_content first to see the current structure, modify it, then pass the full envelope here. Writes via GHL's builder autosave: the server uploads the page to storage, bumps the version, and regenerates the preview snapshot, then returns the new pageDataUrl. The funnelId and current version are resolved automatically from the page. Saves as a draft unless isPublished is true.",
     {
       pageId: import_zod34.z.string().describe("The page ID to update."),
-      content: import_zod34.z.record(import_zod34.z.unknown()).describe("The full page content JSON. Expected fields: sections, settings, general, pageStyles, trackingCode, popups, popupsList, fontsForPreview."),
-      isPublished: import_zod34.z.boolean().optional().describe("Whether the page should be marked published after the save. Defaults to false (draft).")
+      content: import_zod34.z.record(import_zod34.z.unknown()).describe("The full page content JSON \u2014 the 8-field envelope: sections, settings, general, pageStyles, trackingCode, fontsForPreview, popups, popupsList. Start from get_page_content and modify it."),
+      funnelId: import_zod34.z.string().optional().describe("Funnel ID that owns the page. Optional \u2014 auto-resolved from the page metadata if omitted."),
+      isPublished: import_zod34.z.boolean().optional().describe("Mark the page published after the save. Defaults to false (draft).")
     },
-    async ({ pageId, content, isPublished }) => {
+    async ({ pageId, content, funnelId, isPublished }) => {
       try {
-        const result = await funnelRequest("POST", `/builder/prebuilt-section/sync/changes`, {
-          locationId: client.locationId,
-          pageId,
-          pageData: content,
-          write: true,
-          isPublished: isPublished ?? false
+        let meta = {};
+        try {
+          meta = await funnelRequest("GET", `/page/${pageId}?locationId=${client.locationId}`);
+        } catch (metaErr) {
+          if (!funnelId) throw metaErr;
+        }
+        const resolvedFunnelId = funnelId ?? (typeof meta.funnelId === "string" ? meta.funnelId : void 0);
+        if (!resolvedFunnelId) {
+          throw new Error(`Could not resolve funnelId for page ${pageId}. Pass funnelId explicitly.`);
+        }
+        const pageVersion = typeof meta.pageVersion === "number" ? meta.pageVersion : typeof meta.version === "number" ? meta.version : 1;
+        const pageData = {
+          ...content,
+          pageVersion,
+          pageType: isPublished ? "published" : "draft",
+          manualSave: true,
+          integrations: computeIntegrations(content)
+        };
+        const result = await autosaveRequest(pageId, {
+          funnelId: resolvedFunnelId,
+          pageVersion,
+          pageData
         });
         return jsonResponse(result);
       } catch (error) {
@@ -7146,6 +7269,7 @@ async function validateLicense(email, licenseKey) {
     return {
       ok: true,
       installs: `${data.installs_used}/${data.installs_max}`,
+      tier: data.tier === "free" ? "free" : data.tier === "full" ? "full" : void 0,
       signedAttestation: typeof data.signed_attestation === "string" ? data.signed_attestation : void 0
     };
   }
@@ -7198,7 +7322,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 229 tools (177 if you skip the optional Firebase fields; add Firebase later with enable_workflow_builder).",
+    "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 232 tools (180 if you skip the optional Firebase fields; add Firebase later with enable_workflow_builder).",
     {
       email: import_zod39.z.string().email().describe("Email used at purchase."),
       license_key: import_zod39.z.string().min(20).describe("License key from your purchase email."),
@@ -7279,24 +7403,27 @@ Note: Firebase credentials rejected (${fb.error}). Saved without Workflow Builde
         // verified on every MCP startup. Closes the hand-crafted creds bypass.
         signed_attestation: lic.signedAttestation
       });
-      const toolCount = workflowBuilderEnabled ? "229" : "177";
+      const isFree = lic.tier === "free";
+      const toolCount = isFree ? workflowBuilderEnabled ? "106" : "88" : workflowBuilderEnabled ? "232" : "180";
       const wfLine = workflowBuilderEnabled ? "Workflow Builder: enabled." : "Workflow Builder: not configured (optional).";
-      const wfTip = workflowBuilderEnabled ? "" : "\nTo enable Workflow Builder later (49 extra Firebase-gated tools): run enable_workflow_builder with your three Firebase values. No need to re-enter license/API key/location ID.";
+      const wfTip = workflowBuilderEnabled ? "" : isFree ? `
+Unlock the account auditor next (the free tier's best tool): say "Unlock the Workflow Builder" \u2014 one browser login enables audit_workflows, validate_workflow, and the full-detail reads.` : "\nTo enable Workflow Builder later (52 extra Firebase-gated tools): run enable_workflow_builder with your three Firebase values. No need to re-enter license/API key/location ID.";
+      const freeTip = isFree ? "\n\nFree tier: 106 read-only tools (88 before the one-login auditor unlock). Write tools stay visible but answer with upgrade info instead of acting. Full version ($97/mo founding rate, same key upgrades in place): https://ghlcommand.com" : "";
       return {
         content: [{
           type: "text",
           text: [
             `Setup complete!`,
             ``,
-            `License: verified (installs ${lic.installs}).`,
+            `License: verified (installs ${lic.installs})${isFree ? " \u2014 FREE read-only tier" : ""}.`,
             `GHL: connected to "${ghl.locationName}".`,
             wfLine,
             ``,
             `Credentials saved to: ${credentialsPath()}`,
             ``,
-            `**Restart Claude (quit fully and reopen) to load all ${toolCount} tools.**`,
+            `**Restart Claude (quit fully and reopen) to load all ${toolCount} ${isFree ? "read-only " : ""}tools.**`,
             ``,
-            `After restart, try: "List my GHL contacts" or "Show my pipelines".${wfTip}`,
+            `After restart, try: "List my GHL contacts" or "Show my pipelines".${wfTip}${freeTip}`,
             workflowBuilderNote
           ].join("\n")
         }]
@@ -7307,7 +7434,7 @@ 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 52 additional tools across the internal-API modules: workflow builder (create/edit/clone/delete/publish/validate workflows, build_if_else_branch, build_goal_event, get_trigger_registry), funnel + page builder, form builder, pipeline builder, workflow cloner, smart lists, reputation, email campaigns, email templates, and memberships, plus the pre-deploy validator. Requires you've already run setup_ghl_mcp. EASIEST PATH: run `capture_firebase_interactive` instead \u2014 a Chrome window opens, you log into GHL, zero pasting. Use THIS tool when you have JSON from `auto_capture_firebase_script` (console-paste path) to put in `firebase_paste`, or the three manual DevTools fields. Tool count goes from 177 to 229 after the next Claude restart.",
+    "Add Firebase credentials to an existing GHL Command install to unlock 52 additional tools across the internal-API modules: workflow builder (create/edit/clone/delete/publish/validate workflows, build_if_else_branch, build_goal_event, get_trigger_registry), funnel + page builder, form builder, pipeline builder, workflow cloner, smart lists, reputation, email campaigns, email templates, and memberships, plus the pre-deploy validator. On the FREE tier this same login unlocks the read-only auditor suite (audit_workflows, validate_workflow, full-detail workflow/funnel/pipeline reads). Requires you've already run setup_ghl_mcp. EASIEST PATH: run `capture_firebase_interactive` instead \u2014 a Chrome window opens, you log into GHL, zero pasting. Use THIS tool when you have JSON from `auto_capture_firebase_script` (console-paste path) to put in `firebase_paste`, or the three manual DevTools fields. Tool count goes from 180 to 232 after the next Claude restart.",
     {
       // v3.25.0: one-paste path. Tool runs `auto_capture_firebase_script` to
       // get the console script; the script returns a JSON object that pastes
@@ -7388,7 +7515,7 @@ DevTools steps: https://elitedcs.com/ghl-mcp-firebase`
             "",
             "**You MUST restart Claude before using any workflow-builder tool.** Quit Claude completely (Cmd+Q on Mac, full exit on Windows) and reopen. Without a restart, the workflow builder tools will keep using the OLD Firebase auth from before this call and fail with 401 errors \u2014 even though this tool reported success.",
             "",
-            'After restart, all 229 tools load. Try: "List my workflows in full detail" or "Validate workflow <id>".',
+            'After restart, all 232 tools load. Try: "List my workflows in full detail" or "Validate workflow <id>".',
             "",
             "Note: Firebase refresh tokens rotate every few weeks. If workflow tools stop working in a few weeks (run `health_check` to confirm Firebase auth: FAIL), run `auto_capture_firebase_script` for fresh values and re-run this tool with the new firebase_paste."
           ].join("\n")
@@ -7437,7 +7564,7 @@ function registerFirebaseCaptureScriptTool(server2) {
 function registerInteractiveCaptureTool(server2) {
   server2.tool(
     "capture_firebase_interactive",
-    "One-click Workflow Builder unlock (EASIEST PATH \u2014 try this before auto_capture_firebase_script). Opens a Chrome window where you just log into GHL; the MCP captures the Firebase credentials itself and saves them. No DevTools, no pasting. Re-run the same tool if the first call says it's still waiting for your login. After the first successful run, future re-captures (refresh-token rotations) happen silently with no window at all. Falls back cleanly: if no Chrome/Edge is installed, use auto_capture_firebase_script instead.",
+    "One-click Workflow Builder unlock (EASIEST PATH \u2014 try this before auto_capture_firebase_script). Also the unlock for the FREE tier's account auditor (audit_workflows, validate_workflow) \u2014 same one-time login. Opens a Chrome window where you just log into GHL; the MCP captures the Firebase credentials itself and saves them. No DevTools, no pasting. Re-run the same tool if the first call says it's still waiting for your login. After the first successful run, future re-captures (refresh-token rotations) happen silently with no window at all. Falls back cleanly: if no Chrome/Edge is installed, use auto_capture_firebase_script instead.",
     {},
     async () => {
       const existing = readCredentials();
@@ -7484,7 +7611,7 @@ The login in the capture window may belong to the wrong GHL account, or the sess
               "",
               "**You MUST restart Claude before using any workflow-builder tool.** Quit Claude completely (Cmd+Q on Mac, full exit on Windows) and reopen.",
               "",
-              'After restart, all 229 tools load. Try: "List my workflows in full detail".',
+              'After restart, all 232 tools load. Try: "List my workflows in full detail".',
               "",
               "Future token rotations re-capture silently \u2014 if workflow tools ever 401, just run capture_firebase_interactive again; no window should appear."
             ].join("\n")
@@ -7568,7 +7695,7 @@ ${fallbackNote}`
 function registerLeadCaptureTool(server2) {
   server2.tool(
     "request_license",
-    "Get a GHL Command license. Use this if you installed from npm but don't have a license yet (or setup_ghl_mcp says your license is missing/invalid). GHL Command is $97/mo \u2014 every sub-account you manage, 3-machine activation, includes the only programmatic GHL workflow builder. Leave your email and we'll send the purchase link + setup help; the tool also returns where to buy right now.",
+    "Get a GHL Command license. Use this if you installed from npm but don't have a license yet (or setup_ghl_mcp says your license is missing/invalid). GHL Command is $97/mo \u2014 every sub-account you manage, 3-machine activation, includes the only programmatic GHL workflow builder. There's also a FREE read-only tier (account audits + all reads on your own account) \u2014 instant key at https://ghlcommand.com/free. Leave your email and we'll send the purchase link + setup help; the tool also returns where to buy right now.",
     {
       email: import_zod39.z.string().email().describe("Your email \u2014 where to send the purchase link and setup help."),
       name: import_zod39.z.string().optional().describe("Your name (optional).")
@@ -7592,6 +7719,7 @@ function registerLeadCaptureTool(server2) {
               "GHL Command is $97/mo: every sub-account you manage, 3 machines, including the only programmatic GHL workflow builder. Cancel anytime.",
               "",
               `Buy now: ${url}`,
+              "Want to try it first? FREE read-only tier (account audits + every read tool on your own account): https://ghlcommand.com/free",
               "Your license key arrives by email within a couple minutes. Then run setup_ghl_mcp with your email + key."
             ].join("\n")
           }]
@@ -8120,6 +8248,143 @@ ${lines.join("\n")}
       }
     }
   );
+  server2.tool(
+    "create_sub_account",
+    "Create a NEW GHL sub-account (location) under the agency, optionally loading a snapshot at creation \u2014 the first step of fully programmatic client provisioning (create \u2192 Blueprint build \u2192 verify_funnel). Requires an agency-level API key with the locations.write scope (add via register_agency_key). After creating, this probes whether the agency key can operate the new location and auto-registers it in the token registry when it can (switch_location then works immediately); if the probe fails, create a Private Integration Token inside the new sub-account and run register_location. Company Firebase (register_company_firebase) covers the internal-API builder tools in the new location either way.",
+    {
+      name: import_zod40.z.string().min(1).describe("Business / sub-account name."),
+      snapshot_id: import_zod40.z.string().optional().describe("Snapshot ID to load at creation (see list_snapshots)."),
+      company_id: import_zod40.z.string().optional().describe("Agency company ID. Defaults to the active location's registered companyId."),
+      first_name: import_zod40.z.string().optional().describe("Prospect/owner first name."),
+      last_name: import_zod40.z.string().optional().describe("Prospect/owner last name."),
+      email: import_zod40.z.string().email().optional().describe("Prospect/owner email."),
+      phone: import_zod40.z.string().optional().describe("Business phone (E.164, e.g. +15551234567)."),
+      address: import_zod40.z.string().optional().describe("Street address."),
+      city: import_zod40.z.string().optional(),
+      state: import_zod40.z.string().optional(),
+      postal_code: import_zod40.z.string().optional(),
+      country: import_zod40.z.string().optional().describe("Two-letter country code. Defaults to US."),
+      website: import_zod40.z.string().optional(),
+      timezone: import_zod40.z.string().optional().describe("IANA timezone, e.g. America/Los_Angeles."),
+      auto_register: import_zod40.z.boolean().optional().describe("Probe the new location with the agency key and add it to the token registry on success. Default true.")
+    },
+    async (args) => {
+      const agencyKey = registry2?.getAgencyKey();
+      if (!agencyKey) {
+        return {
+          content: [{ type: "text", text: "No agency key registered. Run register_agency_key with an agency-level Private Integration key (it needs the locations.write scope to create sub-accounts)." }],
+          isError: true
+        };
+      }
+      const companyId = args.company_id || (client.defaultLocationId ? registry2?.getToken(client.defaultLocationId)?.companyId : void 0) || process.env.GHL_COMPANY_ID;
+      if (!companyId) {
+        return {
+          content: [{ type: "text", text: "Couldn't resolve the agency company ID \u2014 pass company_id explicitly (the GHL agency/company ID, not a location ID)." }],
+          isError: true
+        };
+      }
+      try {
+        const agencyClient = new GHLClient({ apiKey: agencyKey });
+        const prospect = args.first_name || args.last_name || args.email ? { prospectInfo: { ...args.first_name && { firstName: args.first_name }, ...args.last_name && { lastName: args.last_name }, ...args.email && { email: args.email } } } : {};
+        const body = {
+          name: args.name,
+          companyId,
+          country: args.country || "US",
+          ...args.snapshot_id && { snapshotId: args.snapshot_id },
+          ...args.phone && { phone: args.phone },
+          ...args.address && { address: args.address },
+          ...args.city && { city: args.city },
+          ...args.state && { state: args.state },
+          ...args.postal_code && { postalCode: args.postal_code },
+          ...args.website && { website: args.website },
+          ...args.timezone && { timezone: args.timezone },
+          ...prospect
+        };
+        const created = await agencyClient.post("/locations/", { body, noRetry: true });
+        const loc = created.location ?? created;
+        const locationId2 = loc.id || loc._id;
+        if (!locationId2) {
+          return {
+            content: [{ type: "text", text: `Sub-account create returned no location id. Raw response:
+${JSON.stringify(created, null, 2)}` }],
+            isError: true
+          };
+        }
+        let probeOk = false;
+        let probeNote = "";
+        try {
+          await agencyClient.get("/contacts/", { params: { locationId: locationId2, limit: 1 } });
+          probeOk = true;
+        } catch (e) {
+          probeNote = e instanceof Error ? e.message : String(e);
+        }
+        let registered = false;
+        if (probeOk && args.auto_register !== false && registry2) {
+          registry2.registerLocation(locationId2, args.name, agencyKey, companyId);
+          registered = true;
+        }
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `Sub-account created: "${args.name}"`,
+              `Location ID: ${locationId2}`,
+              args.snapshot_id ? `Snapshot ${args.snapshot_id} is loading (GHL applies snapshots asynchronously \u2014 assets appear over the next minute or two).` : "No snapshot loaded.",
+              probeOk ? registered ? "Agency key CAN operate this location \u2014 added to the token registry. Run switch_location to start building in it." : "Agency key CAN operate this location (auto_register was off \u2014 run register_location to add it)." : `Agency key can NOT read this location's data (${probeNote.slice(0, 120)}). Create a Private Integration Token inside the new sub-account, then run register_location. The company Firebase still covers the workflow/funnel/form builder tools there.`
+            ].join("\n")
+          }]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const scopeHint = /401|403|scope|unauthorized/i.test(message) ? "\n\nThis usually means the registered agency key lacks the locations.write scope. Edit the agency Private Integration in GHL (Agency Settings \u2192 Private Integrations) and enable it." : "";
+        return {
+          content: [{ type: "text", text: `Error creating sub-account: ${message}${scopeHint}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "delete_sub_account",
+    "Permanently delete a GHL sub-account (location) via the agency API. IRREVERSIBLE \u2014 every contact, workflow, funnel, and setting inside the sub-account is destroyed. Refuses to delete the currently active location. Also removes the location from the token registry. Requires an agency-level key with locations.write.",
+    {
+      location_id: import_zod40.z.string().min(1).describe("The location ID to delete."),
+      confirm: import_zod40.z.literal("DELETE").describe("Must pass 'DELETE' to confirm this destructive action."),
+      delete_twilio: import_zod40.z.boolean().optional().describe("Also delete the location's Twilio sub-account. Default false.")
+    },
+    async ({ location_id, delete_twilio }) => {
+      const agencyKey = registry2?.getAgencyKey();
+      if (!agencyKey) {
+        return {
+          content: [{ type: "text", text: "No agency key registered. Run register_agency_key first." }],
+          isError: true
+        };
+      }
+      if (client.defaultLocationId === location_id) {
+        return {
+          content: [{ type: "text", text: `Refusing to delete the currently ACTIVE location (${location_id}). switch_location to a different sub-account first.` }],
+          isError: true
+        };
+      }
+      try {
+        const agencyClient = new GHLClient({ apiKey: agencyKey });
+        await agencyClient.delete(`/locations/${location_id}`, { params: { deleteTwilioAccount: delete_twilio ?? false } });
+        const wasRegistered = registry2?.removeLocation(location_id) ?? false;
+        return {
+          content: [{
+            type: "text",
+            text: `Sub-account ${location_id} permanently deleted.${wasRegistered ? " Removed from the token registry." : ""}`
+          }]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Error deleting sub-account: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
 }
 
 // src/tools/bulk-operations.ts
@@ -13986,11 +14251,12 @@ var KNOWN_MODULES = /* @__PURE__ */ new Set([
   LOCATION_SWITCHER_MODULE,
   SNAPSHOTS_MODULE
 ]);
-function registerAllTools(server2, client, registry2, mcpVersion, env = process.env) {
+function registerAllTools(server2, client, registry2, mcpVersion, env = process.env, tier = "full") {
   const config3 = parseAllowlist(env);
   const attemptedTools = /* @__PURE__ */ new Set();
   const registeredTools = /* @__PURE__ */ new Set();
-  const wrap = (moduleName) => wrapServerForModule(server2, moduleName, config3, attemptedTools, registeredTools);
+  const gatedTools = /* @__PURE__ */ new Set();
+  const wrap = (moduleName) => wrapServerForModule(server2, moduleName, config3, attemptedTools, registeredTools, tier, gatedTools);
   for (const [register, moduleName] of publicApiTools) {
     register(wrap(moduleName), client);
   }
@@ -14020,6 +14286,13 @@ function registerAllTools(server2, client, registry2, mcpVersion, env = process.
   if (isAllowlistActive(config3)) {
     validateAndLog(config3, KNOWN_MODULES, attemptedTools, registeredTools);
   }
+  if (tier === "free") {
+    process.stderr.write(
+      `[ghl-mcp] FREE tier: ${registeredTools.size - gatedTools.size} read-only tools live; ${gatedTools.size} write tools answer with upgrade info. Full version: https://ghlcommand.com
+`
+    );
+  }
+  return { registeredTools, gatedTools };
 }
 
 // src/attestation.ts
@@ -14027,6 +14300,9 @@ var import_node_crypto = require("node:crypto");
 var ATTESTATION_PUBLIC_KEY_B64 = "8KJo8V3Z7ngeToIQfOXpKdlr/EA34hXJVEIpW0A7wqs=";
 var ATTESTATION_VERSION = 1;
 var ATTESTATION_GRACE_DAYS = 14;
+function tierFromPayload(payload) {
+  return payload?.tier === "free" ? "free" : "full";
+}
 function deviceFingerprint2() {
   const os3 = require("node:os");
   const crypto4 = require("node:crypto");
@@ -14051,6 +14327,20 @@ async function getPublicKey() {
   );
   return cachedPublicKey;
 }
+function parseAttestationPayload(token) {
+  try {
+    const dot = token.indexOf(".");
+    if (dot <= 0 || dot === token.length - 1) return null;
+    const payloadJson = new TextDecoder().decode(base64urlDecode(token.slice(0, dot)));
+    const payload = JSON.parse(payloadJson);
+    if (typeof payload.v !== "number" || typeof payload.email !== "string" || typeof payload.license_key !== "string" || typeof payload.device_fingerprint !== "string" || typeof payload.installs_max !== "number" || typeof payload.issued_at !== "string" || typeof payload.expires_at !== "string") {
+      return null;
+    }
+    return payload;
+  } catch {
+    return null;
+  }
+}
 async function verifyAttestation(token, bindings, now = /* @__PURE__ */ new Date()) {
   if (typeof token !== "string" || !token) return { ok: false, reason: "malformed" };
   const dot = token.indexOf(".");
@@ -14538,6 +14828,8 @@ function renewAttestationInBackground(creds) {
 async function resolveAccessAndRegister() {
   let licenseVerified = false;
   let attestationStatus = "no-creds";
+  let sessionTier = "full";
+  const tierFromDisk = () => tierFromPayload(parseAttestationPayload(readCredentials()?.signed_attestation ?? ""));
   if (fileCreds?.email && fileCreds?.license_key && fileCreds.signed_attestation) {
     const verify = await verifyAttestation(fileCreds.signed_attestation, {
       email: fileCreds.email,
@@ -14546,6 +14838,7 @@ async function resolveAccessAndRegister() {
     if (verify.ok) {
       licenseVerified = true;
       attestationStatus = verify.reason;
+      sessionTier = tierFromPayload(verify.payload);
       void renewAttestationInBackground(fileCreds);
     } else {
       process.stderr.write(`[ghl-mcp] Stored attestation rejected: ${verify.reason}. Re-validating online.
@@ -14554,6 +14847,7 @@ async function resolveAccessAndRegister() {
       if (renewed === "renewed") {
         licenseVerified = true;
         attestationStatus = "renewed-after-tamper";
+        sessionTier = tierFromDisk();
       } else if (renewed === "renewed-unsigned" && Date.now() < TRANSITIONAL_ATTESTATION_DEADLINE) {
         licenseVerified = true;
         attestationStatus = "renewed-after-tamper";
@@ -14567,6 +14861,7 @@ async function resolveAccessAndRegister() {
     if (renewed === "renewed") {
       licenseVerified = true;
       attestationStatus = "renewed-from-legacy";
+      sessionTier = tierFromDisk();
     } else if (renewed === "renewed-unsigned" && Date.now() < TRANSITIONAL_ATTESTATION_DEADLINE) {
       licenseVerified = true;
       attestationStatus = "renewed-from-legacy";
@@ -14591,6 +14886,7 @@ async function resolveAccessAndRegister() {
       if (lic.ok && acceptUnsigned) {
         licenseVerified = true;
         attestationStatus = "renewed";
+        sessionTier = lic.signedAttestation ? tierFromPayload(parseAttestationPayload(lic.signedAttestation)) : lic.tier === "free" ? "free" : "full";
         try {
           writeCredentials({
             license_key: licKey,
@@ -14618,7 +14914,7 @@ async function resolveAccessAndRegister() {
     }
   }
   if (licenseVerified) {
-    process.stderr.write(`[ghl-mcp] License gate: ${attestationStatus}.
+    process.stderr.write(`[ghl-mcp] License gate: ${attestationStatus}${sessionTier === "free" ? " (FREE read-only tier)" : ""}.
 `);
   }
   inBootstrapMode = !apiKey || !locationId || !licenseVerified;
@@ -14634,7 +14930,7 @@ async function resolveAccessAndRegister() {
     registerFirebaseCaptureScriptTool(server);
   } else {
     const client = new GHLClient({ apiKey, locationId });
-    registerAllTools(server, client, registry, pkg.version);
+    registerAllTools(server, client, registry, pkg.version, process.env, sessionTier);
     registerEnableWorkflowBuilderTool(server);
     registerFirebaseCaptureScriptTool(server);
     registerInteractiveCaptureTool(server);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.49.1",
+  "version": "3.52.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
-  "description": "GoHighLevel MCP Server for Claude. 229 tools — full CRM, automation, marketing control, account-wide workflow audit, live funnel-capture verification, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
+  "description": "GoHighLevel MCP Server for Claude. 232 tools — full CRM, automation, marketing control, account-wide workflow audit, live funnel-capture verification, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",
   "bin": {
     "ghl-mcp": "dist/index.js"