@elitedcs/ghl-mcp 3.67.0 → 3.69.0

package/CHANGELOG.md

@@ -1,5 +1,143 @@
 # Changelog
 
+## 3.69.0 — the cockpit hardened, and the plan you approved is the plan that runs
+
+Two items in this release exist because someone tried to break the cockpit
+before a customer did.
+
+**The cockpit refuses writes it did not ask for.** Command OS runs a small web
+server on your own machine. It only ever listened on 127.0.0.1, which keeps the
+internet out. It did not keep out a web page you happened to have open in another
+tab, which can post to localhost without asking and without showing you anything.
+Every route that changes something now checks three things before it acts: the
+request came to a host we serve, from an origin we serve (or from no browser at
+all), with a JSON body that a foreign page cannot send without a preflight we
+refuse. Tested against the real exploit shapes, including a plain HTML form with
+no JavaScript. (#17)
+
+**An approval is a decision, and decisions do not sync inbound.** The shared board
+mirrors a client's progress into their own sub-account so every seat sees the
+same thing. Progress still merges, last write wins. The human approve gate never
+moves because of anything read back from the client's CRM: their staff, a VA, or
+an ordinary "set custom value" workflow step cannot tick your safety checkbox.
+(#29)
+
+**Headless installs stopped burning an install slot on every restart.** An
+env-var install with no credentials file minted a fresh device id each boot and
+locked itself out after three. It now keeps a stable id. Existing installs keep
+their slot. (#33)
+
+**The plan you approved is the plan that runs.** `apply_build_plan` saves the
+approved plan on execute and a re-run reuses it with `useSavedPlan`; a new plan
+needs `replaceSavedPlan` and operator approval. A differently named plan while
+one is saved is refused, with the two valid moves named. Why: a re-run that
+re-authored the plan created a second pipeline beside the first. The handoff
+compares what was built against the saved plan. (#45, #51, #55)
+
+**`verify_funnel` is a write and leaves the free tier.** It submits the funnel's
+form with a test contact and can fire your automations, so it belongs with the
+writes. Free read-only count 112 → 111; the total is still 242 tools across 51
+modules. (#52)
+
+**Command OS, from two timed client builds.**
+- Spec sheets and an inspector for every module: promise, routes, writes,
+  verification, with an optional `note` on a step and `needs` on a verification.
+  The inspector fails a sheet that lies. (#35, #51)
+- A hard tool boundary for headless stage runs: a stage reaches exactly the
+  tools it declares, enforced by a computed deny list. The build stage carries
+  the plan guide in its prompt and runs on a 25-minute / 40-turn budget. (#45)
+- The review reads intake answers by contact id, tag, or form name, no more
+  search-index lag. (#45)
+- An already-open page notices a running stage and a finished stage on its own;
+  no manual reload, and a second seat sees the same. The page never refreshes
+  while you are typing. (#37, #46)
+- The handoff document is a designed web page with a print-to-PDF view: a client
+  copy and an operator copy, complete sentences, your agency's branding, a real
+  footer with page numbers, and unconfirmed items are never written as done.
+  (#36–#44, #47, #48)
+- Intake: multi-choice questions are checkboxes and save as a list; the
+  prefilled form is keyed the way the form reads it (two answers were silently
+  dropped before); values a link cannot carry are listed for the operator to set
+  by hand. "Is your sending email / domain set up?" is now "Is your sending
+  domain set up?" because browser autofill kept filling it with saved addresses;
+  existing installs keep the old field. (#51)
+- The verify stage may list funnels first and says plainly that the funnel check
+  submits one test contact. The intake stage may rename questions to the
+  agency's wording. (#51)
+
+The second-build fixes are unit-tested and were live-probed on the sandbox form.
+The third timed build, the proof that they hold together, has not run yet.
+
+**Smaller.** `get_courses` called a route GHL does not have, and the workflow
+builder is now actually watched by the health check (#34). The upgrade nudge no
+longer points at an older version than the one you run (#16, #19). Dependencies:
+zod 4, TypeScript 7, dotenv 17 and the Actions bumps, each built and tested
+before merging (#21–#27). CI: the automated checks were made trustworthy (#18);
+the GHL drift canary says plainly when it is not configured and carries the
+server's own reason instead of a guess (#30), and no longer logs a cache-save
+failure it cannot avoid (#32); each canary now has its own licence secrets after
+the two collided (#54).
+
+## 3.68.0 — the checkup
+
+A subscriber asked the question this release is named after: "I'd love for you to
+check my GHL Command to make sure I am using it all and it's all working. Or tell
+me how to check it? Like a checkup from the neckup."
+
+`health_check` already answered half of that, the install half: is the license
+valid, is the key good, is the account reachable. It never answered either of the
+questions people actually have.
+
+Say "run a checkup" and you get three sections.
+
+**Connection** is the old health check, unchanged, folded in so there is one
+thing to run rather than two.
+
+**What still works** is new, and it is the part that matters. Every capability
+area gets one real read against your account, right now: contacts, pipelines,
+calendars, workflows, funnels, forms, invoices, social, phone, the lot. The whole
+section turns on a distinction nothing else in the product made: a clean read
+returning nothing means the feature works and you own none of these, while a 404
+means GoHighLevel changed something. Those two look identical from the outside
+and mean opposite things, so they are never merged. A permission gap and a rate
+limit each get their own verdict too, because each has a different fix, and a
+rate limit has none.
+
+**What you are not using yet** is worked out from what your account contains, not
+from any record of what you have clicked. Nothing about your usage is collected
+or transmitted, which was true before and stays true. Every line ends with the
+exact sentence to paste back.
+
+It is read-only end to end, it works on the free tier, and it is safe to run on a
+live client account.
+
+Two things the first live runs changed, both worth knowing.
+
+GoHighLevel's `/users/` route answers 401 to a perfectly valid key about one call
+in six. Measured, not guessed: two rejections in twelve back-to-back reads, while
+`/contacts/` was clean twelve out of twelve. A single-shot probe would therefore
+tell a paying customer their API key lacks permission roughly every sixth
+checkup. So no failure is reported until it survives three separate reads. Only
+failures retry, so a healthy account pays nothing for it.
+
+And an expired browser login was briefly reported as "Workflow Builder BROKEN,
+send this to support". It is neither broken nor ours, and it has a sixty-second
+fix. A report that cries wolf gets ignored, so token expiry, rate limits, server
+errors and anything else that says nothing about GoHighLevel now say exactly
+that instead of raising an alarm.
+
+**The other half of this release does not ship to anyone.** `scripts/ghl-drift-canary.mjs`
+runs on a schedule against our own test sub-account, boots the real server the
+way Claude does, calls the same `run_checkup` tool, and compares every capability
+against a committed baseline. Nothing watched GoHighLevel before this. The test
+suite mocks the API, so a route they move breaks a shipped tool with every test
+still green, and the first signal was always a support email. Now a capability
+that worked yesterday and fails today opens an alert issue. It also reports its
+own blind spots, because a probe baselined in a broken state can never alert
+again and a canary that quietly shrinks is worse than none.
+
+New tool: `run_checkup`. 242 tools, 51 modules.
+
 ## 3.67.0 — the offboarding kit
 
 Every agency has an onboarding checklist. Almost none have an offboarding one, so

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**Full GoHighLevel API access for Claude.** 241 tools across 50 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.** 242 tools across 51 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).
 
@@ -135,7 +135,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 (241 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 (242 tools total with the optional Workflow Builder Firebase add-on).
 
 ### 4. Try it
 
@@ -175,7 +175,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 186 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 187 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):**
 
@@ -798,7 +798,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 241 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 242 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