@elitedcs/ghl-mcp 3.57.0 → 3.59.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 3.59.0 — One-command install: `npx -y @elitedcs/ghl-mcp cli install`
+
+The old install step said "Edit Config, paste this block." Edit Config opens a
+folder, not a text box — and the block was a complete config object, so anyone
+who already had other MCP servers and followed the instruction literally wiped
+them. A real buyer hit exactly that this week.
+
+This release replaces the hand-edit with one command:
+
+    npx -y @elitedcs/ghl-mcp cli install
+
+It finds Claude Desktop's settings file (including the Microsoft Store build's
+relocated path on Windows), adds GHL Command **alongside** whatever servers are
+already there, and saves a verified backup before touching anything. If the
+file has a formatting problem — often caused by our own old instructions — it
+repairs what it can and preserves the original in the backup. If the file can't
+be read at all, it writes a fresh working config and keeps the original so
+nothing is ever lost.
+
+Safety properties, all tested (33 new tests):
+
+- **Never writes without a verified backup** of an existing file, and aborts if
+  the backup can't be confirmed byte-for-byte.
+- **Never fights Claude for the file**: writes are atomic, lock errors retry
+  briefly then stop with plain instructions, and if anything else modifies the
+  file mid-run it stops rather than overwrite the newer change.
+- **Never guesses between multiple config files** — it stops and asks.
+- **Never touches** symlinked configs pointing somewhere unexpected, UTF-16
+  files, or files whose content it can read but not safely restructure.
+- `--dry-run` previews every decision without writing; `--print-only` emits the
+  merged JSON for locked-down machines.
+
+Also in this release: the license-failure message now points at ghlcommand.com
+(and mentions the free tier) instead of a retired page, and `setup_ghl_mcp`'s
+description finally includes a URL for people who reach it without a license.
+
+## 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,

package/README.md

@@ -89,7 +89,24 @@ This MCP (Model Context Protocol) server connects Claude directly to GoHighLevel
 
 ### 2. Install in Claude Desktop App
 
-Open Claude Desktop. Click **Claude** menu (top-left) → **Settings...** → **Developer** → **Edit Config**. Paste this block (or merge into your existing `mcpServers` if you have other MCP servers):
+One command in any terminal (Terminal on Mac, PowerShell on Windows):
+
+```
+npx -y @elitedcs/ghl-mcp cli install
+```
+
+It finds Claude Desktop's settings file, adds GHL Command **alongside any MCP servers you already have** (nothing gets overwritten), and saves a backup first. If the file has a formatting problem, it repairs it. Then **quit Claude completely** — Cmd+Q on Mac; on Windows right-click the Claude icon by the clock and choose Quit — and reopen.
+
+> **Claude Code (terminal) instead?** One command:
+> ```
+> claude mcp add --scope user -t stdio ghl -- npx -y @elitedcs/ghl-mcp@latest
+> ```
+> Then restart Claude Code.
+
+<details>
+<summary>Prefer to edit the config by hand?</summary>
+
+Open Claude Desktop → **Settings...** → **Developer** → **Edit Config**. That opens a **folder**, not a text box — open `claude_desktop_config.json` from it in a text editor. If the file is empty, paste this whole block:
 
 ```json
 {
@@ -102,13 +119,9 @@ Open Claude Desktop. Click **Claude** menu (top-left) → **Settings...** → **
 }
 ```
 
-Save the file. **Quit Claude completely** (Cmd+Q on Mac) and reopen.
+If it already has other tools in it, do **not** paste over them — add only the `"ghl": { ... }` entry inside your existing `"mcpServers"` object. Save, then fully quit and reopen Claude. (Unsure? Run `npx -y @elitedcs/ghl-mcp cli install --dry-run` to preview exactly what would change, or `--print-only` to get the merged file printed for you.)
 
-> **Claude Code (terminal) instead?** One command:
-> ```
-> claude mcp add --scope user -t stdio ghl -- npx -y @elitedcs/ghl-mcp@latest
-> ```
-> Then restart Claude Code.
+</details>
 
 ### 3. Activate
 
@@ -690,6 +703,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: