@elitedcs/ghl-mcp 3.56.0 → 3.58.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # Changelog
 
+## 3.58.0 — Anonymous install stats, so we can find out where installs get stuck
+
+Most people who install GHL Command never get it working, and until now there
+was no way to tell whether that was 50 people or 1,200. This release adds a
+small, anonymous count of install and startup events so the gap can be measured
+and fixed. It is the first release that sends anything off your machine, so the
+disclosure ships in the same version as the feature, not the one after.
+
+**Turn it off with either of these and no network call is made at all:**
+
+    GHL_TELEMETRY=0
+    DO_NOT_TRACK=1
+
+Run `health_check` to see whether it is on and to confirm an opt-out took effect.
+
+- **Exactly twelve fields, and the server rejects anything else.** A random
+  device id, the event name, package version, Node major, platform, three
+  automation flags (CI / TTY / container), your licence tier, seconds since this
+  machine first ran GHL Command, a failure reason code, and a timestamp. The
+  endpoint refuses a payload carrying an unknown field rather than quietly
+  dropping it, and the database enforces the same list a second time — so the
+  shape cannot drift without both being changed deliberately.
+- **Never sent:** your licence key, email, GHL API key, location ID, contact or
+  client data, hostname, usernames, file paths, or raw error text. Nothing about
+  your GoHighLevel account or your clients' accounts leaves your machine. The
+  failure reason is one of eleven fixed labels, never a server message, because
+  those can name a sub-account.
+- **Separate identity from your licence.** The telemetry device id is generated
+  independently and shares no code with the licence fingerprint, so it cannot
+  affect activation or consume an install slot. A consequence worth stating: a
+  telemetry row cannot be linked back to a customer.
+- **It cannot slow you down.** Sending is fire-and-forget with a 2-second
+  timeout, never awaited, and every failure is swallowed. Identity and
+  environment are resolved once per process, so a tool call performs no disk
+  access at all.
+- `health_check` gains an "Anonymous usage stats" row reporting ON or OFF.
+
+## 3.57.0 — Clone Site: copy a live page for a client, with the guardrails built in
+
+A second bundled skill. Point Claude at any live URL and get a working,
+rebranded copy for a client — same layout, images, video and CSS, with the
+new business's details in place of the original's. It installs itself like
+Blueprint; there is nothing to download and no new tools to learn.
+
+Cloning normally fails because the model *regenerates* the page instead of
+copying it, and you get a worse version of what you pointed at. This skill
+runs real scripts: they download the bytes, swap the strings, and verify the
+result. Nothing is retyped from memory.
+
+- **The rights question is step 0 and cannot be skipped.** Before anything is
+  copied, the skill asks who owns the page — you, your client (authorized),
+  written permission, or none — and records the answer in the run report and
+  in the final report header. It does not verify ownership; the declaration is
+  yours to make. The mirror script refuses to run without it.
+- **"None" gets a real lane, not a refusal.** It extracts the page's actual
+  design system — palette, CSS variables, font stack and type scale, spacing
+  rhythm, radii, shadows, breakpoints, and the section skeleton as shape — so
+  the rebuild starts from the real design instead of a from-memory redraw. No
+  bytes, images, video or copy are copied in that lane.
+- **Substitution that doesn't leak the old brand.** Derives the bare brand word,
+  every phone format, the address as a unit (not just the city), and domain and
+  email variants; runs across JS bundles as well as HTML and CSS, because
+  compiled sites keep contact details only in the bundle. Asset filenames are
+  protected from rewriting. Dry-run counts first, a zero-check after, and a
+  NEAR MISS warning when one of your facts is *almost* right.
+- **Catches the leak a string search cannot see.** A brand mark is usually
+  two-tone — `GHL <span style="color:#D4AF37;">Command</span>` — which reads as
+  the old brand on screen while that string appears nowhere in the file. Every
+  literal check calls it clean. Clone Site renders the page to text while
+  keeping a map back to source offsets, so it reports exactly which occurrences
+  are split by markup, shows the markup, and fails the zero-check until they are
+  hand-edited. Found on a real page, in the header and the footer, after a
+  file-level rebrand had already "passed."
+- **Asset capture from all four places** — HTML, CSS `url()`, CDN URLs in JS
+  bundles, and root-relative paths inside JS bundles (the one that silently
+  breaks images). Oversized files are reported for object storage, never
+  hot-linked back to the original owner's CDN.
+- **A mandatory pre-launch REVIEW REQUIRED report** on every run: form endpoints,
+  webhooks, payment links and publishable keys, booking embeds, analytics and ad
+  pixels (MUST REPOINT); names, addresses, testimonials and likenesses; and
+  inherited claims with regulated health/efficacy language flagged separately.
+  Nothing is auto-deleted — findings go to a human.
+- **Verification by content-type, not status code**, because static hosts answer
+  200 with the page shell for assets that don't exist. It retries once before
+  calling anything broken (a CDN rollout can answer a single request with HTML),
+  and separates references the *source* page was already serving badly from
+  breakage the clone caused.
+- Reports are written outside the deployable folder, so a rights declaration and
+  a liability list can never be published with the site.
+
+Everything below was found by running the tool against real production sites
+rather than test fixtures, and every one of them shipped a fix:
+
+- **Whole-site cloning.** A one-page mirror inherits the original's entire
+  navigation, so every menu item 404s the moment a client clicks it.
+  `--crawl --depth N --max-pages N` follows the site's own navigation, writes
+  each page at its own path, and rewrites links between your pages as
+  root-relative so the nav works locally and after deploy — while canonical and
+  og:url keep their host so the rebrand can point them at the client's domain.
+  The skill asks how deep to go rather than assuming. Real numbers: a 36-page
+  contractor site came to 2,104 files and 935 MB at depth 2.
+- **Assets that only exist at runtime.** Page-builders publish an asset base
+  path and concatenate chunk filenames onto it in JavaScript, so those files
+  appear in no attribute, stylesheet or string literal. Six missing Elementor
+  chunks meant no section background was painted at all: the hero rendered blank
+  and its white headline was invisible on white, while every file-level check
+  reported success. New `repair.mjs` plus a mandatory render-and-repair loop
+  fetches whatever the running page asks for and cannot find.
+- **Media hidden in escaped JSON.** Background slideshows and galleries store
+  image URLs inside entity-encoded, backslash-escaped JSON attributes. Those are
+  now extracted and localised, escaping preserved.
+- **Brand marks split across tags.** `GHL <span style="color:#D4AF37">Command</span>`
+  reads as the old brand on screen while that string exists nowhere in the file.
+  Detected exactly via a rendered-text-to-source offset map; the zero-check now
+  fails until they are hand-edited instead of reporting a false clean.
+- **HTML-entity brand forms.** A brand containing `&` is stored as `&amp;`. On
+  one page the plain token matched twice and the encoded form 56 times.
+- **Brand baked into image pixels.** Logos and graphics carrying the old phone
+  number or web address are flagged — substitution cannot edit artwork, and the
+  logo is the most visible way a clone gives itself away.
+- **New audit rules from real pages:** contractor and professional licence
+  numbers (the highest-severity item on any trades or medical clone), consumer
+  financing links, review widgets that load the original's reviews at runtime,
+  and internal links with no page in the clone.
+- **Bare-word derivation is now cautioned**, because a brand beginning with a
+  place name ("Arizona AC & Heating") would otherwise rewrite ordinary sentences.
+- **Style lane returns the brand's palette, not the framework's.** Plugin CSS
+  repeats neutral greys hundreds of times while the real brand colours appear
+  twice; vendor stylesheets are now separated, accents are attributed to their
+  source file, declared colour tokens are surfaced first, and CSS variables are
+  resolved so the type scale comes back as real pixel values.
+- **The style lane's deliverable is a page, not a document.** Its rebuild is now
+  five explicit steps, including a media step and a leak check against the
+  original page.
+
 ## 3.56.0 — Security off-switches: any tool can be disabled; sub-account create/delete is opt-in
 
 Shaped directly by subscriber feedback: some teams keep account-level

package/README.md

@@ -12,7 +12,7 @@ Works with **both the Claude Desktop App and Claude Code terminal** — your cho
 
 **How this differs from HighLevel's official MCP.** HighLevel ships an official Anthropic MCP that reads and writes your CRM (contacts, conversations, calendars, opportunities, payments, social) over the public API — it's free and it's good; use it for that. What it *cannot* do, because the public API doesn't expose it: **build or edit workflows, build funnels/landing pages, or build forms.** That's exactly what GHL Command does — the programmatic Workflow Builder, funnel/page builder, form builder, deep workflow cloning, the silent-failure `audit_workflows`, and Blueprint (build a whole client account from one intake — ships as a guided skill that **installs itself automatically** with this package; nothing to download), all on GHL's internal APIs. **Official MCP = read/write your CRM. GHL Command = build and fix it.** They stack fine together.
 
-**Bundled skills (install automatically).** The package ships guided skills that teach Claude complete multi-step workflows on top of the raw tools. On every start the server installs/updates them into your `~/.claude/skills/` (never overwriting files you've edited — your version wins and is reported). Current skills: **Blueprint** — turn one client intake into a complete reviewed GHL account build. Verify or repair any time by asking Claude to `run install_skills`, then fully restart Claude so new skills load.
+**Bundled skills (install automatically).** The package ships guided skills that teach Claude complete multi-step workflows on top of the raw tools. On every start the server installs/updates them into your `~/.claude/skills/` (never overwriting files you've edited — your version wins and is reported). Current skills: **Blueprint** — turn one client intake into a complete reviewed GHL account build; **Clone Site** — point at a live URL and get a rebranded, deploy-ready copy for a client, with a recorded rights declaration, a style-only lane when you have no rights, and a mandatory pre-launch report of every lead/booking/payment destination, borrowed testimonial and inherited claim still belonging to the original owner. Verify or repair any time by asking Claude to `run install_skills`, then fully restart Claude so new skills load.
 
 Built by [Elite DCs, LLC](https://elitedcs.com).
 
@@ -690,6 +690,40 @@ This MCP server is safe to share via GitHub.
 
 ---
 
+## Anonymous Usage Stats
+
+GHL Command sends a small, anonymous count of install and startup events so we can see where installs get stuck. Most people who install this never get it working, and we couldn't tell whether that was 50 people or 1,200 — this is how we find out and fix it.
+
+**Turn it off with either of these — no network call is made at all:**
+
+```bash
+GHL_TELEMETRY=0     # or the cross-tool standard:
+DO_NOT_TRACK=1
+```
+
+Run `health_check` any time to see whether it's on and confirm an opt-out took effect.
+
+**Exactly what is sent** — twelve fields, nothing else, ever:
+
+| Field | Example | What it is |
+|---|---|---|
+| `device_id` | `e09eb5cd…` | A random number generated on your machine. Not derived from your hostname, username, or hardware. |
+| `event` | `client_connected` | One of seven: connected, started unlicensed, entered a key, setup failed, setup succeeded, license valid, first tool call. |
+| `pkg_version` | `3.57.0` | Which version you're running. |
+| `node_major` | `24` | Node.js major version. |
+| `platform` | `darwin` | mac, linux, or windows. |
+| `is_ci`, `is_tty`, `is_container` | `false` | Whether this is an automated environment. |
+| `licensed_tier` | `none` | none, free, or full. |
+| `elapsed_s` | `12` | Seconds since this machine first ran GHL Command. |
+| `reason_code` | `ghl_key_wrong_location` | If setup failed, which of eleven fixed labels. Never a raw error message. |
+| `ts` | `2026-08-04T03:31:08Z` | When it happened. |
+
+**Never sent:** your license key, email, GHL API key, location ID, contact or client data, hostname, usernames, file paths, IP-derived location, or raw error text. Nothing about your GHL account or your clients' accounts ever leaves your machine.
+
+The receiving endpoint **rejects** any payload containing a field not on that list rather than quietly dropping it, and the database enforces the same list a second time — so the shape can't drift without both being changed deliberately.
+
+---
+
 ## Reliability & Type Safety
 
 This server has been through a rigorous, multi-pass audit for production reliability (v2.4.0–v2.7.0). Here's what's in place: