@elitedcs/ghl-mcp 3.32.0 → 3.34.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # 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
+references to pipelines, stages, custom fields, users, workflows, forms,
+calendars, and surveys that don't exist — the GHL bug where one bad ID silently
+kills that action and every action after it. Returns a prioritized report:
+what's broken, what couldn't be scanned, what couldn't be fully verified.
+Conservative by construction: it never reports a false break (uncertain checks
+are `unverified`, not `error`). The same engine upgrade sharpens
+`validate_workflow`: four opportunity action shapes (including the dominant
+UI-native `internal_create_opportunity`), if/else condition-node custom-field
+checks, `create_update_contact` field refs, hyphenated `task-notification`
+nodes, and custom-field trigger conditions are now covered. 18 new unit tests;
+verified live against 35 real workflows with zero false alarms.
+
+**`register_agency_key`** — new tool to store the agency-level (company-scoped)
+API key, with live validation before saving. Previously the snapshot tools
+required an agency key that no tool could register.
+
+**Trust + reliability hardening** (from the 2026-06-10 audit):
+
+- List tools now attach `_pagination` (returned / limit / total / complete +
+  an explicit INCOMPLETE note) so a single page can never silently read as the
+  full dataset: `search_contacts`, `search_opportunities`,
+  `search_conversations`, `list_invoices`, `list_workflows_full`.
+- Version is read from package.json at runtime instead of baked at build time —
+  a stale local build can no longer misreport its version.
+- `health_check` now reports a corrupted token registry as a FAIL with recovery
+  steps (previously only visible on stderr, i.e. invisible in the Desktop App).
+- Clearer guidance errors: missing locationId now points at `switch_location` /
+  `list_registered_locations`; missing agency key points at
+  `register_agency_key`.
+- Firebase token-refresh URL now percent-encodes the API key (consistency).
+- New regression tests pin that error messages never contain API keys or
+  Firebase refresh tokens.
+
 ## 3.32.0 — Account-health summary + phone reads
 
 Three read tools. The composite is the second roadmap build and the first

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**Full GoHighLevel API access for Claude.** 212 tools across 43 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.** 219 tools across 43 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).
 
@@ -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.
 
 ---
 
@@ -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** — all 163 core tools are now unlocked (212 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 (219 tools total with the optional Workflow Builder Firebase add-on).
 
 ### 4. Try it
 
@@ -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).
 
@@ -537,7 +555,7 @@ To unlock full builder access across multiple clients from one install:
 Uses **esbuild** for production builds (not tsc). TypeScript 5.9.3 + MCP SDK types cause tsc to run out of memory at 4GB+. esbuild bundles in ~5ms with zero memory issues.
 
 ```bash
-npm run build    # esbuild → dist/index.js (~212KB)
+npm run build    # esbuild → dist/index.js (~428KB)
 npm run dev      # tsc --watch (type-checking only)
 ```
 
@@ -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. |
 
 ---
@@ -716,7 +734,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 212 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 219 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
@@ -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
 
 ---