@elitedcs/ghl-mcp 3.33.0 → 3.34.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 3.34.0 — Headless/server deployment hardening
+
+Built for production server installs (Linux droplets, containers, MCP
+gateways). License scope, stated plainly: **one license covers every
+GoHighLevel sub-account you manage — unlimited, across multiple agency
+companies — on up to 3 of your own machines. Never metered per account.**
+Nothing in the code ever capped registered locations; the docs now say so.
+
+- **Headless seed CLI** behind an explicit sentinel (`ghl-mcp cli …`), so
+  gateway-supplied argv can never trigger a subcommand:
+  `register-location`, `register-company-firebase`, `register-agency-key`,
+  `list-locations`. Live validation identical to the interactive tools
+  (`--no-validate` for air-gapped builds), strict arg parsing, deterministic
+  exit codes (0/2/3/4), config-dir writability preflight, never prints keys.
+- **`.ghl-tokens.json` schema documented** with a pre-populatable example —
+  the registry is read at boot, so a hand-seeded file just works. Full guide
+  at `docs/HEADLESS.md` (+ new README "Server / Headless Deployment" section).
+- **Firebase scope documented:** credentials are per-COMPANY, not
+  per-sub-account — one set covers every sub-account under a company; each
+  company's token rotates and persists independently.
+- **`GHL_MCP_CONFIG_DIR`** — explicit absolute-path config-dir override so all
+  state (including auto-rotated Firebase tokens) lives on a persistent
+  mounted volume. Relative paths fail fast at boot.
+- **Node 20 supported** (`engines: >=20`, esbuild target lowered to node20).
+  Verified on real Node 20: full test suite, server boot, CLI, and Ed25519
+  attestation verification (one harmless ExperimentalWarning). The publish
+  smoke test now runs on a Node 20/22/24 matrix.
+- **Graceful shutdown** on SIGTERM/SIGINT (bounded 3s) for supervised
+  deployments.
+- **`GHL_MCP_DISABLE_UPDATE_CHECK=1`** disables the startup npm version ping
+  (air-gapped/firewalled servers).
+- Transport remains stdio by design (gateways supervise it as a child
+  process); an optional Streamable-HTTP mode is on the roadmap for the
+  server-deployment track.
+
 ## 3.33.0 — Account-wide silent-failure audit + trust hardening
 
 **`audit_workflows`** — scans EVERY workflow in the current location for

package/README.md

@@ -26,7 +26,7 @@ Built by [Elite DCs, LLC](https://elitedcs.com).
 > "Thank you, Jerry. You're a star."
 > — Frankie B.
 
-27 releases on npm since launch (v3.6.0 → v3.27.0). Bugs get fixed in days, not quarters.
+30+ releases on npm since launch (v3.6.0 → v3.34.0). Bugs get fixed in days, not quarters.
 
 ---
 
@@ -217,7 +217,25 @@ To unlock full builder access across multiple clients from one install:
 
 ---
 
-## Tools (190)
+## Server / Headless Deployment
+
+GHL Command runs headless — Linux droplet, container, or behind an MCP gateway (MetaMCP, etc.). **One license covers every GoHighLevel sub-account you manage, on up to 3 of your own machines. No per-account fees.** A server counts as one machine; restarts never consume extra activations.
+
+Highlights (full guide: [`docs/HEADLESS.md`](docs/HEADLESS.md)):
+
+- **Scriptable multi-account setup** — pre-seed the documented `.ghl-tokens.json`, or use the CLI in a Dockerfile/entrypoint:
+  ```bash
+  npx -y @elitedcs/ghl-mcp cli register-location --location-id XXXX --api-key pit-... --name "Account"
+  npx -y @elitedcs/ghl-mcp cli register-company-firebase --company-id YYYY --refresh-token ... --user-id ...
+  npx -y @elitedcs/ghl-mcp cli register-agency-key --api-key pit-...
+  ```
+- **Persistent config dir** — set `GHL_MCP_CONFIG_DIR=/data/ghl-mcp` (absolute path) on a mounted volume so auto-rotated Firebase tokens survive container restarts.
+- **Firebase is per-company, not per-sub-account** — one credential set covers all sub-accounts under a company.
+- **Node 20+**, graceful SIGTERM shutdown, `GHL_MCP_DISABLE_UPDATE_CHECK=1` for air-gapped boxes. Transport is stdio (your gateway supervises it as a child process); an HTTP serve mode is on the roadmap.
+
+---
+
+## Tools
 
 > **v3.10.0 adds Email Templates** (`list_email_templates`, `create_email_template`, `update_email_template`) — Claude can now create new HTML email templates and save content into them via the public API. Templates power both standalone marketing emails and workflow email actions. Delete + rename remain UI-only (no public-API endpoint exists).
 
@@ -648,9 +666,9 @@ This MCP server is safe to share via GitHub.
 | Concern | How It's Handled |
 |---|---|
 | **API Keys** | Stored in a per-user credentials file (`~/Library/Application Support/elitedcs-ghl-mcp/credentials.json` on Mac) at chmod 0600. Never in code, never committed. |
-| **License validation** | One-time check at `setup_ghl_mcp` against elitedcs.com license server. After activation, no further phone-home. |
+| **License validation** | Checked at `setup_ghl_mcp` against the elitedcs.com license server, then cached as a signed attestation (~30 days). The server renews the attestation in the background as expiry approaches — never per-request, and your GHL keys are never sent to us. |
 | **Multi-user** | Each user brings their own license key + GHL API key. Complete account isolation. |
-| **Scope** | The server only talks to GHL's API and (once, at setup) the elitedcs.com license server. No filesystem access beyond the credentials file, no shell commands. |
+| **Scope** | The server only talks to GHL's API, the elitedcs.com license server (setup + periodic attestation renewal), and npm's registry (startup version banner — `GHL_MCP_DISABLE_UPDATE_CHECK=1` to disable). No filesystem access beyond its config dir, no shell commands. |
 | **Permissions** | Controlled by your GHL Private Integration scopes. Disable what you don't need. |
 
 ---
@@ -778,7 +796,7 @@ Built by **[Elite DCs, LLC](https://elitedcs.com)** — a digital marketing and
 
 **Tech stack:** TypeScript, Node.js, esbuild, MCP SDK, Zod, GHL API v2, Firebase Auth
 
-**Version:** 2.3.0
+**Version:** 3.34.0
 
 ---
 

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.33.0",
+      version: "3.34.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
       description: "GoHighLevel MCP Server for Claude. 218 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
@@ -47,7 +47,7 @@ var require_package = __commonJS({
         "CHANGELOG.md"
       ],
       scripts: {
-        build: "esbuild src/index.ts --bundle --platform=node --target=node22 --format=cjs --outfile=dist/index.js --packages=external",
+        build: "esbuild src/index.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/index.js --packages=external",
         setup: "node setup-wizard.mjs",
         start: "node dist/index.js",
         dev: "tsc --watch",
@@ -85,7 +85,7 @@ var require_package = __commonJS({
         access: "public"
       },
       engines: {
-        node: ">=22"
+        node: ">=20"
       },
       dependencies: {
         "@modelcontextprotocol/sdk": "^1.12.1",
@@ -106,8 +106,8 @@ var require_package = __commonJS({
 
 // src/index.ts
 var dotenv2 = __toESM(require("dotenv"));
-var path5 = __toESM(require("path"));
-var fs5 = __toESM(require("fs"));
+var path6 = __toESM(require("path"));
+var fs6 = __toESM(require("fs"));
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
@@ -171,8 +171,8 @@ var GHLClient = class {
       Version: version || GHL_API_VERSION
     };
   }
-  buildUrl(path6, params) {
-    const url = new URL(path6, GHL_BASE_URL);
+  buildUrl(path7, params) {
+    const url = new URL(path7, GHL_BASE_URL);
     if (params) {
       for (const [key, value] of Object.entries(params)) {
         if (value !== void 0 && value !== null) {
@@ -182,8 +182,8 @@ var GHLClient = class {
     }
     return url.toString();
   }
-  async request(method, path6, options = {}, attempt = 0) {
-    const url = this.buildUrl(path6, options.params);
+  async request(method, path7, options = {}, attempt = 0) {
+    const url = this.buildUrl(path7, options.params);
     const headers = this.buildHeaders(options.version);
     const fetchOptions = {
       method,
@@ -201,14 +201,14 @@ var GHLClient = class {
     } catch (error) {
       clearTimeout(timeout);
       if (error instanceof Error && error.name === "AbortError") {
-        throw new Error(`Request timeout (30s): ${method} ${path6}`);
+        throw new Error(`Request timeout (30s): ${method} ${path7}`);
       }
       if (!options.noRetry && attempt < MAX_RETRIES) {
         const delay4 = computeRetryDelay(null, attempt, BASE_DELAY_MS);
-        process.stderr.write(`[ghl-mcp] Network error on ${method} ${path6}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay4}ms
+        process.stderr.write(`[ghl-mcp] Network error on ${method} ${path7}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay4}ms
 `);
         await new Promise((r) => setTimeout(r, delay4));
-        return this.request(method, path6, options, attempt + 1);
+        return this.request(method, path7, options, attempt + 1);
       }
       throw error;
     } finally {
@@ -216,10 +216,10 @@ var GHLClient = class {
     }
     if (!options.noRetry && (response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
       const delay4 = computeRetryDelay(response.headers.get("Retry-After"), attempt, BASE_DELAY_MS);
-      process.stderr.write(`[ghl-mcp] ${response.status} on ${method} ${path6}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay4}ms
+      process.stderr.write(`[ghl-mcp] ${response.status} on ${method} ${path7}, retry ${attempt + 1}/${MAX_RETRIES} in ${delay4}ms
 `);
       await new Promise((r) => setTimeout(r, delay4));
-      return this.request(method, path6, options, attempt + 1);
+      return this.request(method, path7, options, attempt + 1);
     }
     if (!response.ok) {
       let errorBody = "";
@@ -228,7 +228,7 @@ var GHLClient = class {
       } catch {
       }
       throw new Error(
-        `GHL API Error ${response.status} ${response.statusText}: ${method} ${path6}
+        `GHL API Error ${response.status} ${response.statusText}: ${method} ${path7}
 ${errorBody}`
       );
     }
@@ -240,20 +240,20 @@ ${errorBody}`
       return { message: text };
     }
   }
-  async get(path6, options) {
-    return this.request("GET", path6, options);
+  async get(path7, options) {
+    return this.request("GET", path7, options);
   }
-  async post(path6, options) {
-    return this.request("POST", path6, options);
+  async post(path7, options) {
+    return this.request("POST", path7, options);
   }
-  async put(path6, options) {
-    return this.request("PUT", path6, options);
+  async put(path7, options) {
+    return this.request("PUT", path7, options);
   }
-  async patch(path6, options) {
-    return this.request("PATCH", path6, options);
+  async patch(path7, options) {
+    return this.request("PATCH", path7, options);
   }
-  async delete(path6, options) {
-    return this.request("DELETE", path6, options);
+  async delete(path7, options) {
+    return this.request("DELETE", path7, options);
   }
   /**
    * Helper: resolves locationId from args or falls back to default
@@ -300,6 +300,15 @@ var CredentialsSchema = import_zod.z.object({
   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);
@@ -407,6 +416,7 @@ var TokenRegistryDataSchema = import_zod2.z.object({
 var TokenRegistry = class _TokenRegistry {
   data;
   loadFailure = null;
+  lastSaveError = null;
   filePath;
   constructor(filePath) {
     if (filePath) {
@@ -493,15 +503,25 @@ var TokenRegistry = class _TokenRegistry {
         fs2.chmodSync(this.filePath, 384);
       } catch {
       }
+      this.lastSaveError = null;
     } catch (error) {
       try {
         fs2.unlinkSync(tmpPath);
       } catch {
       }
+      this.lastSaveError = error instanceof Error ? error.message : String(error);
       process.stderr.write(`[ghl-mcp] Warning: Could not save token registry: ${error}
 `);
     }
   }
+  /**
+   * Non-null when the MOST RECENT save() failed (cleared by a later success).
+   * The seed CLI checks this after every write to turn the server's
+   * warn-and-continue policy into a hard exit code.
+   */
+  getLastSaveError() {
+    return this.lastSaveError;
+  }
   /**
    * Get the API key for a specific location
    */
@@ -4368,16 +4388,16 @@ function registerEmailTools(server2, client) {
 function registerEmailBuilderInternalTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function builderRequest(method, path6, body) {
+  async function builderRequest(method, path7, body) {
     const headers = await client.buildHeaders();
-    const response = await fetch(`${EMAIL_BUILDER_BASE}${path6}`, {
+    const response = await fetch(`${EMAIL_BUILDER_BASE}${path7}`, {
       method,
       headers,
       body: body ? JSON.stringify(body) : void 0
     });
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Email Builder API Error ${response.status}: ${method} /emails/builder${path6}
+      throw new Error(`Email Builder API Error ${response.status}: ${method} /emails/builder${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -5634,23 +5654,23 @@ var import_zod34 = require("zod");
 function registerFunnelBuilderTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function internalGet(path6) {
-    return client.request("GET", path6);
+  async function internalGet(path7) {
+    return client.request("GET", path7);
   }
-  async function internalPost(path6, body) {
-    return client.request("POST", path6, body);
+  async function internalPost(path7, body) {
+    return client.request("POST", path7, body);
   }
-  async function internalPut(path6, body) {
-    return client.request("PUT", path6, body);
+  async function internalPut(path7, body) {
+    return client.request("PUT", path7, body);
   }
-  async function internalDelete(path6) {
-    return client.request("DELETE", path6);
+  async function internalDelete(path7) {
+    return client.request("DELETE", path7);
   }
-  async function funnelRequest(method, path6, body) {
+  async function funnelRequest(method, path7, body) {
     const headers = await client.buildHeaders();
     headers.Origin = "https://app.gohighlevel.com";
     headers.Referer = "https://app.gohighlevel.com/";
-    const url = `https://backend.leadconnectorhq.com/funnels${path6}`;
+    const url = `https://backend.leadconnectorhq.com/funnels${path7}`;
     const options = { method, headers };
     if (body && (method === "POST" || method === "PUT")) {
       options.body = JSON.stringify(body);
@@ -5658,7 +5678,7 @@ function registerFunnelBuilderTools(server2, builderClient) {
     const response = await fetch(url, options);
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Funnel API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Funnel API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -5950,9 +5970,9 @@ function buildUpdateFormBody(name, formData) {
 function registerFormBuilderTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function formRequest(method, path6, body) {
+  async function formRequest(method, path7, body) {
     const headers = await client.buildHeaders();
-    const url = `https://backend.leadconnectorhq.com/forms${path6}`;
+    const url = `https://backend.leadconnectorhq.com/forms${path7}`;
     const options = { method, headers };
     if (body && (method === "POST" || method === "PUT")) {
       options.body = JSON.stringify(body);
@@ -5960,7 +5980,7 @@ function registerFormBuilderTools(server2, builderClient) {
     const response = await fetch(url, options);
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Form API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Form API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -6074,10 +6094,10 @@ ${text2}`);
     },
     async ({ formId, limit, skip }) => {
       try {
-        let path6 = `/submissions?locationId=${client.locationId}&limit=${limit ?? 20}`;
-        if (formId) path6 += `&formId=${formId}`;
-        if (skip) path6 += `&skip=${skip}`;
-        const result = await formRequest("GET", path6);
+        let path7 = `/submissions?locationId=${client.locationId}&limit=${limit ?? 20}`;
+        if (formId) path7 += `&formId=${formId}`;
+        if (skip) path7 += `&skip=${skip}`;
+        const result = await formRequest("GET", path7);
         return {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
@@ -6093,9 +6113,9 @@ var import_zod36 = require("zod");
 function registerPipelineBuilderTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function pipelineRequest(method, path6, body) {
+  async function pipelineRequest(method, path7, body) {
     const headers = await client.buildHeaders();
-    const url = `https://backend.leadconnectorhq.com/opportunities/pipelines${path6}`;
+    const url = `https://backend.leadconnectorhq.com/opportunities/pipelines${path7}`;
     const options = { method, headers };
     if (body && (method === "POST" || method === "PUT" || method === "PATCH")) {
       options.body = JSON.stringify(body);
@@ -6103,7 +6123,7 @@ function registerPipelineBuilderTools(server2, builderClient) {
     const response = await fetch(url, options);
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Pipeline API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Pipeline API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -7665,9 +7685,9 @@ var OBJECT_KEYS = ["contacts", "opportunity"];
 function registerSmartListTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function smartListRequest(method, path6, body) {
+  async function smartListRequest(method, path7, body) {
     const headers = await client.buildHeaders();
-    const url = `${SMARTLIST_BASE}${path6}`;
+    const url = `${SMARTLIST_BASE}${path7}`;
     const options = { method, headers };
     if (body && (method === "POST" || method === "PUT")) {
       options.body = JSON.stringify(body);
@@ -7675,7 +7695,7 @@ function registerSmartListTools(server2, builderClient) {
     const response = await fetch(url, options);
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Smart Lists API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Smart Lists API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -7807,12 +7827,12 @@ var REPUTATION_BASE = "https://backend.leadconnectorhq.com/reputation";
 function registerReputationTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function reputationRequest(method, path6) {
+  async function reputationRequest(method, path7) {
     const headers = await client.buildHeaders();
-    const response = await fetch(`${REPUTATION_BASE}${path6}`, { method, headers });
+    const response = await fetch(`${REPUTATION_BASE}${path7}`, { method, headers });
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Reputation API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Reputation API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -7927,16 +7947,16 @@ var MEMBERSHIP_BASE = "https://backend.leadconnectorhq.com/membership";
 function registerMembershipTools(server2, builderClient) {
   const client = builderClient;
   if (!client) return;
-  async function membershipRequest(path6, method = "GET", body) {
+  async function membershipRequest(path7, method = "GET", body) {
     const headers = await client.buildHeaders();
-    const response = await fetch(`${MEMBERSHIP_BASE}${path6}`, {
+    const response = await fetch(`${MEMBERSHIP_BASE}${path7}`, {
       method,
       headers,
       body: body ? JSON.stringify(body) : void 0
     });
     if (!response.ok) {
       const text2 = await response.text();
-      throw new Error(`Membership API Error ${response.status}: ${method} ${path6}
+      throw new Error(`Membership API Error ${response.status}: ${method} ${path7}
 ${text2}`);
     }
     const text = await response.text();
@@ -9494,12 +9514,298 @@ function registerMetaTools(server2, installedVersion) {
   );
 }
 
+// src/cli.ts
+var import_node_util = require("node:util");
+var fs5 = __toESM(require("fs"));
+var path5 = __toESM(require("path"));
+var import_crypto2 = require("crypto");
+var EXIT_OK = 0;
+var EXIT_USAGE = 2;
+var EXIT_VALIDATION = 3;
+var EXIT_FS = 4;
+var USAGE = `Usage: ghl-mcp cli <subcommand> [options]
+
+Subcommands:
+  register-location          Add a sub-account's Private Integration key
+      --location-id <id>     GHL Location ID (required)
+      --api-key <pit-...>    The sub-account's Private Integration key (required)
+      --name <name>          Friendly name (required)
+      --company-id <id>      Owning company ID (optional; auto-resolved when validating)
+      --no-validate          Skip the live GHL check (air-gapped; local-admin-only)
+
+  register-company-firebase  Add a company's workflow-builder (Firebase) credentials
+      --company-id <id>      GHL company/agency ID (required; self-corrects to the
+                             token's real company when validating)
+      --refresh-token <tok>  Firebase refresh token (required)
+      --user-id <uid>        Firebase user ID (required)
+      --api-key <AIza...>    Firebase API key (optional if the home install has one)
+      --name <name>          Friendly company name (optional)
+      --no-validate          Skip the live token-mint check
+
+  register-agency-key        Store the AGENCY-level API key (snapshots, agency reads)
+      --api-key <pit-...>    Agency-level Private Integration key (required)
+      --no-validate          Skip the live agency-scope check
+
+  list-locations             Print registered locations / companies (never prints keys)
+
+Exit codes: 0 ok, 2 usage, 3 validation failed, 4 filesystem write failed.
+Seed while the MCP server is stopped, or restart it afterwards.`;
+function errLine(msg) {
+  process.stderr.write(msg + "\n");
+}
+function preflightWritable() {
+  try {
+    const dir = ensureAppDataDir();
+    const probe = path5.join(dir, `.write-probe.${process.pid}.${(0, import_crypto2.randomBytes)(4).toString("hex")}`);
+    fs5.writeFileSync(probe, "ok");
+    fs5.unlinkSync(probe);
+    return true;
+  } catch (error) {
+    errLine(`Config dir is not writable: ${error instanceof Error ? error.message : String(error)}`);
+    errLine(`Config dir resolves to the parent of: ${tokenRegistryPath()}`);
+    errLine("If you set GHL_MCP_CONFIG_DIR, make sure it is an absolute path on a writable volume.");
+    return false;
+  }
+}
+function restartReminder() {
+  errLine("Note: if the MCP server is currently running, restart it to pick up this change");
+  errLine("(registry writes are last-writer-wins across processes \u2014 seed stopped, or restart after).");
+}
+function confirmSaved(registry2) {
+  const err = registry2.getLastSaveError();
+  if (err) {
+    errLine(`Failed to write registry: ${err}`);
+    return false;
+  }
+  return true;
+}
+function parse(argv, options, required) {
+  let parsed;
+  try {
+    parsed = (0, import_node_util.parseArgs)({ args: argv, options, strict: true, allowPositionals: false });
+  } catch (error) {
+    return { usageError: error instanceof Error ? error.message : String(error) };
+  }
+  for (const key of required) {
+    const v = parsed.values[key];
+    if (typeof v !== "string" || v.trim() === "") {
+      return { usageError: `Missing required option: --${key}` };
+    }
+  }
+  return parsed;
+}
+async function cmdRegisterLocation(argv, registry2) {
+  const p = parse(
+    argv,
+    {
+      "location-id": { type: "string" },
+      "api-key": { type: "string" },
+      name: { type: "string" },
+      "company-id": { type: "string" },
+      "no-validate": { type: "boolean" }
+    },
+    ["location-id", "api-key", "name"]
+  );
+  if ("usageError" in p) {
+    errLine(p.usageError);
+    errLine(USAGE);
+    return EXIT_USAGE;
+  }
+  const locationId2 = p.values["location-id"].trim();
+  const apiKey2 = p.values["api-key"].trim();
+  let name = p.values.name.trim();
+  let companyId = p.values["company-id"]?.trim() || void 0;
+  if (!p.values["no-validate"]) {
+    const client = new GHLClient({ apiKey: apiKey2, locationId: locationId2 });
+    try {
+      const result = await client.get(`/locations/${locationId2}`);
+      const loc = result.location ?? result;
+      if (typeof loc?.name === "string" && loc.name) name = loc.name;
+      if (!companyId && typeof loc?.companyId === "string") companyId = loc.companyId;
+    } catch (error) {
+      errLine(`Validation failed: ${error instanceof Error ? error.message : String(error)}`);
+      errLine("The key must be a Private Integration created INSIDE this sub-account, and the");
+      errLine("Location ID must match. Use --no-validate only if this machine cannot reach GHL.");
+      return EXIT_VALIDATION;
+    }
+  }
+  if (!preflightWritable()) return EXIT_FS;
+  try {
+    registry2.registerLocation(locationId2, name, apiKey2, companyId);
+  } catch (error) {
+    errLine(`Failed to write registry: ${error instanceof Error ? error.message : String(error)}`);
+    return EXIT_FS;
+  }
+  if (!confirmSaved(registry2)) return EXIT_FS;
+  process.stdout.write(
+    `Registered location: ${name} (${locationId2})${companyId ? ` company ${companyId}` : ""} \u2192 ${tokenRegistryPath()}
+`
+  );
+  restartReminder();
+  return EXIT_OK;
+}
+async function cmdRegisterCompanyFirebase(argv, registry2) {
+  const p = parse(
+    argv,
+    {
+      "company-id": { type: "string" },
+      "refresh-token": { type: "string" },
+      "user-id": { type: "string" },
+      "api-key": { type: "string" },
+      name: { type: "string" },
+      "no-validate": { type: "boolean" }
+    },
+    ["company-id", "refresh-token", "user-id"]
+  );
+  if ("usageError" in p) {
+    errLine(p.usageError);
+    errLine(USAGE);
+    return EXIT_USAGE;
+  }
+  const typedCompanyId = p.values["company-id"].trim();
+  const refreshToken = p.values["refresh-token"].trim();
+  const userId = p.values["user-id"].trim();
+  const name = p.values.name?.trim();
+  const apiKey2 = p.values["api-key"]?.trim() || process.env.GHL_FIREBASE_API_KEY || registry2.getFirebase()?.apiKey;
+  if (!apiKey2) {
+    errLine("No Firebase API key available. Pass --api-key (starts with 'AIza'), or seed the home");
+    errLine("Firebase first (the key is identical across GHL accounts).");
+    return EXIT_USAGE;
+  }
+  let canonicalCompanyId = typedCompanyId;
+  if (!p.values["no-validate"]) {
+    const fb = await validateFirebase(apiKey2, refreshToken);
+    if (!fb.ok) {
+      errLine(`Firebase credentials rejected: ${fb.error}`);
+      errLine("Capture fresh values from a browser session logged into THIS company's GHL:");
+      errLine("https://elitedcs.com/ghl-mcp-firebase");
+      return EXIT_VALIDATION;
+    }
+    if (fb.companyId && fb.companyId !== typedCompanyId) {
+      canonicalCompanyId = fb.companyId;
+      errLine(
+        `Note: stored under company ${fb.companyId} (the ID this token actually authenticates as), not ${typedCompanyId}.`
+      );
+    }
+  } else {
+    errLine("Warning: --no-validate stores the typed company ID verbatim. If workflow-builder calls");
+    errLine("401 after seeding, re-run WITHOUT --no-validate so the ID self-corrects from the token.");
+  }
+  if (!preflightWritable()) return EXIT_FS;
+  try {
+    registry2.setCompanyFirebase(canonicalCompanyId, {
+      apiKey: apiKey2,
+      refreshToken,
+      userId,
+      ...name ? { name } : {}
+    });
+  } catch (error) {
+    errLine(`Failed to write registry: ${error instanceof Error ? error.message : String(error)}`);
+    return EXIT_FS;
+  }
+  if (!confirmSaved(registry2)) return EXIT_FS;
+  process.stdout.write(
+    `Registered company Firebase: ${name ?? canonicalCompanyId} (${canonicalCompanyId}) \u2192 ${tokenRegistryPath()}
+`
+  );
+  restartReminder();
+  return EXIT_OK;
+}
+async function cmdRegisterAgencyKey(argv, registry2) {
+  const p = parse(
+    argv,
+    { "api-key": { type: "string" }, "no-validate": { type: "boolean" } },
+    ["api-key"]
+  );
+  if ("usageError" in p) {
+    errLine(p.usageError);
+    errLine(USAGE);
+    return EXIT_USAGE;
+  }
+  const apiKey2 = p.values["api-key"].trim();
+  if (!p.values["no-validate"]) {
+    const client = new GHLClient({ apiKey: apiKey2 });
+    try {
+      const probe = await client.get("/locations/search", { params: { limit: 1, skip: 0 } });
+      const locations = probe?.locations;
+      if (!Array.isArray(locations)) {
+        throw new Error("response is not an agency location-search envelope (no locations array)");
+      }
+    } catch (error) {
+      errLine(`Validation failed: ${error instanceof Error ? error.message : String(error)}`);
+      errLine("The key must be a Private Integration created at the AGENCY level (Agency Settings >");
+      errLine("Private Integrations), with the locations scope enabled.");
+      return EXIT_VALIDATION;
+    }
+  }
+  if (!preflightWritable()) return EXIT_FS;
+  try {
+    registry2.setAgencyKey(apiKey2);
+  } catch (error) {
+    errLine(`Failed to write registry: ${error instanceof Error ? error.message : String(error)}`);
+    return EXIT_FS;
+  }
+  if (!confirmSaved(registry2)) return EXIT_FS;
+  process.stdout.write(`Registered agency key: ${apiKey2.substring(0, 12)}... \u2192 ${tokenRegistryPath()}
+`);
+  restartReminder();
+  return EXIT_OK;
+}
+function cmdListLocations(registry2) {
+  const locs = registry2.listLocations();
+  const companies = registry2.listCompanyFirebases();
+  const out = {
+    registryPath: tokenRegistryPath(),
+    locations: locs,
+    agencyKey: registry2.getAgencyKey() ? "registered" : "not registered",
+    homeFirebase: registry2.getFirebase() ? "registered" : "not registered",
+    // names/ids ONLY — no keys, tokens, or user ids (design contract).
+    companyFirebases: companies.map(({ companyId, name }) => ({ companyId, ...name ? { name } : {} }))
+  };
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  return EXIT_OK;
+}
+async function runCli(subcommand, argv) {
+  let registry2;
+  try {
+    registry2 = new TokenRegistry();
+  } catch (error) {
+    errLine(error instanceof Error ? error.message : String(error));
+    return EXIT_USAGE;
+  }
+  const loadFailure = registry2.getLoadFailure();
+  if (loadFailure) {
+    errLine(loadFailure);
+    return EXIT_FS;
+  }
+  switch (subcommand) {
+    case "register-location":
+      return cmdRegisterLocation(argv, registry2);
+    case "register-company-firebase":
+      return cmdRegisterCompanyFirebase(argv, registry2);
+    case "register-agency-key":
+      return cmdRegisterAgencyKey(argv, registry2);
+    case "list-locations":
+      return cmdListLocations(registry2);
+    case void 0:
+    case "help":
+    case "--help":
+    case "-h":
+      process.stdout.write(USAGE + "\n");
+      return subcommand === void 0 ? EXIT_USAGE : EXIT_OK;
+    default:
+      errLine(`Unknown subcommand: ${subcommand}`);
+      errLine(USAGE);
+      return EXIT_USAGE;
+  }
+}
+
 // src/index.ts
 var bundledPkg = require_package();
 var pkg = (() => {
   try {
     const onDisk = JSON.parse(
-      fs5.readFileSync(path5.resolve(__dirname, "..", "package.json"), "utf8")
+      fs6.readFileSync(path6.resolve(__dirname, "..", "package.json"), "utf8")
     );
     if (typeof onDisk.version === "string" && onDisk.version.length > 0) {
       return { version: onDisk.version };
@@ -9509,25 +9815,35 @@ var pkg = (() => {
   return bundledPkg;
 })();
 dotenv2.config();
+{
+  const configDirOverride = process.env.GHL_MCP_CONFIG_DIR?.trim();
+  if (configDirOverride && !path6.isAbsolute(configDirOverride)) {
+    process.stderr.write(
+      `[ghl-mcp] GHL_MCP_CONFIG_DIR must be an absolute path (got "${configDirOverride}"). Use e.g. /data/ghl-mcp in a container, with a volume mounted at /data.
+`
+    );
+    process.exit(2);
+  }
+}
 process.on("unhandledRejection", (reason) => {
   process.stderr.write(`[ghl-mcp] Unhandled rejection: ${reason}
 `);
 });
 function hardenSecretFilePerms() {
-  const repoDir = path5.resolve(__dirname, "..");
+  const repoDir = path6.resolve(__dirname, "..");
   const candidates = [
-    { file: path5.join(repoDir, "start-mcp.sh"), mode: 448 },
+    { file: path6.join(repoDir, "start-mcp.sh"), mode: 448 },
     // Legacy registry location (pre-migration); new location lives in app-data.
-    { file: path5.join(repoDir, ".ghl-tokens.json"), mode: 384 },
+    { file: path6.join(repoDir, ".ghl-tokens.json"), mode: 384 },
     { file: tokenRegistryPath(), mode: 384 }
   ];
   for (const { file, mode } of candidates) {
     let current;
     try {
-      if (!fs5.existsSync(file)) continue;
-      current = fs5.statSync(file).mode & 511;
+      if (!fs6.existsSync(file)) continue;
+      current = fs6.statSync(file).mode & 511;
       if (current !== mode) {
-        fs5.chmodSync(file, mode);
+        fs6.chmodSync(file, mode);
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
@@ -9741,9 +10057,28 @@ async function checkForUpdates() {
   }
 }
 async function main() {
+  if (process.argv[2] === "cli") {
+    process.exit(await runCli(process.argv[3], process.argv.slice(4)));
+  }
   await resolveAccessAndRegister();
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    process.stderr.write(`[ghl-mcp] ${signal} received \u2014 shutting down.
+`);
+    const deadline = setTimeout(() => process.exit(0), 3e3);
+    deadline.unref();
+    try {
+      await server.close();
+    } catch {
+    }
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+  process.on("SIGINT", () => void shutdown("SIGINT"));
   if (inBootstrapMode) {
     process.stderr.write(`[ghl-mcp] v${pkg.version} connected (bootstrap mode \u2014 only setup_ghl_mcp available).
 `);
@@ -9752,7 +10087,9 @@ async function main() {
     process.stderr.write(`[ghl-mcp] v${pkg.version} connected. Token registry: ${locCount} location(s).
 `);
     validateApiKey();
-    checkForUpdates();
+    if (process.env.GHL_MCP_DISABLE_UPDATE_CHECK !== "1") {
+      checkForUpdates();
+    }
   }
 }
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.33.0",
+  "version": "3.34.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
   "description": "GoHighLevel MCP Server for Claude. 218 tools — full CRM, automation, marketing control, account-wide workflow audit, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",
@@ -16,7 +16,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --target=node22 --format=cjs --outfile=dist/index.js --packages=external",
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/index.js --packages=external",
     "setup": "node setup-wizard.mjs",
     "start": "node dist/index.js",
     "dev": "tsc --watch",
@@ -54,7 +54,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",