npm - @elitedcs/ghl-mcp - Versions diffs - 3.0.0 → 3.0.3 - Mend

@elitedcs/ghl-mcp 3.0.0 → 3.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,12 +1,14 @@
-# Elite DCs GHL MCP Server
+# GHL Command — GoHighLevel MCP Server
 **Full GoHighLevel API access for Claude.** 171 tools across 35 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.
-**v2.7.0** — Production-hardened with automatic retry/backoff, Zod-validated API responses, pre-flight workflow action validation, and type-safe tool registration. Built to share confidently.
+**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).
 Works with **both the Claude Desktop App and Claude Code terminal** — your choice.
-Built by [Elite DCs, LLC](https://elitedcs.com) for the Clinic Launch Lab project and beyond.
+**License required.** Buy at [elitedcs.com/ghl-mcp-server](https://elitedcs.com/ghl-mcp-server) — one-time $297, three-machine activation, no subscription.
+Built by [Elite DCs, LLC](https://elitedcs.com).
 ---
@@ -55,110 +57,68 @@ This MCP (Model Context Protocol) server connects Claude directly to GoHighLevel
 ---
-## Quick Start
+## Quick Start (5 minutes)
-Choose your path:
+### 1. Buy a license
-### Path 1: Easy Install (Recommended — No Technical Knowledge Needed)
+[elitedcs.com/ghl-mcp-server](https://elitedcs.com/ghl-mcp-server) — one-time $297. License key arrives by email within 1-2 minutes.
-**What you need first:**
-1. **Claude** — either the [Claude Desktop App](https://claude.ai/download) or [Claude Code](https://claude.ai/code) (or both!)
-2. **Node.js** — download from [nodejs.org](https://nodejs.org) (click the big green "LTS" button and run the installer)
-3. Your **license key** and **purchase email** (sent to you after purchase)
-4. Your **GHL API Key** and **Location ID** (see "Get Your GHL API Key" below)
+### 2. Install in Claude Desktop App
-**Then just do this:**
+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):
-1. Open a terminal (on Mac: search "Terminal" in Spotlight) or open Claude Code
-2. Paste this line and press Enter:
-```
-cd ~/projects && git clone git@github.com:drjerryrelth/ghl-command-mcp.git && cd ghl-command-mcp && bash setup.sh
+```json
+{
+  "mcpServers": {
+    "ghl": {
+      "command": "npx",
+      "args": ["-y", "@elitedcs/ghl-mcp@latest"]
+    }
+  }
+}
 ```
-> If running from inside Claude Code, prefix the command with `!`:
-> ```
-> ! cd ~/projects && git clone git@github.com:drjerryrelth/ghl-command-mcp.git && cd ghl-command-mcp && bash setup.sh
-> ```
-> **Note:** This repo is private. You must have an SSH key linked to your GitHub account. See [GitHub SSH setup](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) if you haven't done this before.
-3. The setup wizard opens — it will:
-   - Validate your license key (from your purchase email)
-   - Ask for your GHL API key (paste it when prompted)
-   - Ask for your Location ID (paste it when prompted)
-   - Verify your credentials work
-   - Optionally enable the workflow builder (you can skip this)
-   - **Ask which Claude client(s) to register with** — Desktop App, terminal, or both
-   - Register everything for you automatically
-4. Restart the Claude app (quit fully and reopen) or restart Claude Code
-5. Try it: type `"List my contacts"` — you should see your GHL data
+Save the file. **Quit Claude completely** (Cmd+Q on Mac) and reopen.
-**That's it. One command, follow the prompts, done.**
----
+> **Claude Code (terminal) instead?** One command:
+> ```
+> claude mcp add --scope user -t stdio ghl -- npx -y @elitedcs/ghl-mcp@latest
+> ```
+> Then restart Claude Code.
-### Path 2: Manual Install (For Developers)
+### 3. Activate
-#### Option A: Claude Code (Terminal)
+After restart, GHL Command is loaded but locked. Type this in Claude (replace the four placeholders with your real values):
-```bash
-git clone git@github.com:drjerryrelth/ghl-command-mcp.git
-cd ghl-command-mcp
-npm install && npm run build
-cp start-mcp.example.sh start-mcp.sh
-# Edit start-mcp.sh with your API key and Location ID
-chmod +x start-mcp.sh
-claude mcp add --scope user -t stdio ghl $(pwd)/start-mcp.sh
 ```
-> **Why a wrapper script?** Claude Code's env injection via MCP config is unreliable. The wrapper script exports env vars directly, guaranteeing they reach the server process. MCP servers must be registered in `~/.claude.json` (via `claude mcp add`), NOT in `~/.claude/mcp.json`.
-#### Option B: Claude Desktop App
-```bash
-git clone git@github.com:drjerryrelth/ghl-command-mcp.git
-cd ghl-command-mcp
-npm install && npm run build
+Run setup_ghl_mcp to activate GHL Command:
+  email: YOUR_PURCHASE_EMAIL
+  license_key: YOUR_LICENSE_KEY
+  ghl_api_key: YOUR_GHL_API_KEY
+  ghl_location_id: YOUR_LOCATION_ID
 ```
-Then add the MCP server to your Claude Desktop config file:
-- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+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 165 tools are now unlocked.
-Add a `"ghl"` entry under `"mcpServers"`:
+### 4. Try it
-```json
-{
-  "mcpServers": {
-    "ghl": {
-      "command": "node",
-      "args": ["/full/path/to/ghl-command-mcp/dist/index.js"],
-      "env": {
-        "GHL_API_KEY": "YOUR_API_KEY_HERE",
-        "GHL_LOCATION_ID": "YOUR_LOCATION_ID_HERE"
-      }
-    }
-  }
-}
+```
+"List my GHL contacts"
+"Show my pipelines"
+"What calendars do I have?"
 ```
-> **Tip:** Replace `/full/path/to/` with the actual path where you cloned the repo (e.g., `/Users/yourname/projects/ghl-command-mcp/dist/index.js`). To add workflow builder support, include `GHL_USER_ID`, `GHL_FIREBASE_API_KEY`, and `GHL_FIREBASE_REFRESH_TOKEN` in the `env` block too.
-Quit the Claude app fully and reopen it. The GHL tools will appear automatically.
-#### Option C: Both
-Run the Easy Install (Path 1) — the setup wizard lets you register with both clients in one step.
+Full step-by-step setup with screenshots: [elitedcs.com/ghl-mcp-setup-guide.html](https://elitedcs.com/ghl-mcp-setup-guide.html)
 ---
-### Get Your GHL API Key
+## Get Your GHL API Key
 > **CRITICAL: Sub-Account Level Only**
 >
 > Private Integrations in GHL are **scoped to individual sub-accounts**, NOT to the agency level. You must create a separate Private Integration **inside each sub-account** you want to connect. An API key created in Sub-Account A will return `403 Forbidden` if you try to use it with Sub-Account B's Location ID.
 >
-> **Your API key can only be copied ONCE** — at the moment you create the integration. After you leave that screen, the key is permanently masked and cannot be retrieved. If you lose it, you must delete the integration and create a new one (which generates a new key).
+> **Your API key can only be copied ONCE** — at the moment you create the integration. After you leave that screen, the key is permanently masked and cannot be retrieved. If you lose it, you must delete the integration and create a new one.
 1. Log into GoHighLevel
 2. **Switch into the specific sub-account** you want to connect (not the agency view)
@@ -166,54 +126,35 @@ Run the Easy Install (Path 1) — the setup wizard lets you register with both c
 4. Click **Private Integrations** > **Create Private Integration**
 5. Name it `Claude Code MCP`
 6. Enable all scopes/permissions you want Claude to access
-7. **Immediately copy the API Key** and paste it into your config — you will not be able to see it again
-### Enable Workflow Builder (Optional)
-The workflow builder tools use GHL's internal API and require additional Firebase credentials. Without these, the standard API tools still work — you just won't have workflow editing.
-**Step 1: Get your Firebase credentials from GHL**
-1. Log into `app.gohighlevel.com` in Chrome
-2. Press **Cmd + Option + I** (Mac) or **F12** (Windows) to open Developer Tools
-3. Go to **Application** tab → **IndexedDB** → expand **firebaseLocalStorageDb** → **firebaseLocalStorage**
-4. Click the entry — you'll see a JSON object with:
-   - `stsTokenManager.refreshToken` — this is your **Firebase Refresh Token**
-   - The `fbase_key` contains the **Firebase API Key** (the part between `firebase:authUser:` and `:[DEFAULT]`)
-5. Your **User ID** is in the `uid` field
-**Step 2: Add to your wrapper script**
+7. **Immediately copy the API Key** and pass it to `setup_ghl_mcp` as `ghl_api_key` — you will not be able to see it again
-Add these to `start-mcp.sh` alongside your existing env vars:
+## Find Your Location ID
-```bash
-export GHL_USER_ID="your-user-id"
-export GHL_FIREBASE_API_KEY="your-firebase-api-key"
-export GHL_FIREBASE_REFRESH_TOKEN="your-firebase-refresh-token"
-```
-Restart Claude Code and the workflow builder tools will be available.
-> **Note:** The Firebase refresh token may rotate periodically. If workflow tools stop working, re-extract the token from your browser using the steps above.
-### Find Your Location ID
-Your Location ID (sub-account ID) is in the GHL URL when you're inside a sub-account:
+Your Location ID (sub-account ID) is in the GHL URL when you'''re inside a sub-account:
 ```
 https://app.gohighlevel.com/v2/location/YOUR_LOCATION_ID/dashboard
 ```
-### Verify It Works
+## Enable Workflow Builder (Optional)
-Restart the Claude Desktop App (quit fully and reopen) or restart Claude Code, then try:
+The 6 workflow builder tools use GHL'''s internal API and require Firebase credentials. Without them, the other 165 tools work fine — you just won'''t have workflow editing.
+**The easy way:** [elitedcs.com/ghl-mcp-firebase](https://elitedcs.com/ghl-mcp-firebase) — drag the bookmarklet, click it inside GHL, your three values appear automatically. Then re-run `setup_ghl_mcp` with the extra fields:
 ```
-"List my contacts"
-"Show my pipelines"
-"What calendars do I have?"
+Re-run setup_ghl_mcp with workflow builder:
+  email: YOUR_PURCHASE_EMAIL
+  license_key: YOUR_LICENSE_KEY
+  ghl_api_key: YOUR_GHL_API_KEY
+  ghl_location_id: YOUR_LOCATION_ID
+  ghl_user_id: FROM_FIREBASE_CAPTURE
+  ghl_firebase_api_key: FROM_FIREBASE_CAPTURE
+  ghl_firebase_refresh_token: FROM_FIREBASE_CAPTURE
 ```
+> Firebase refresh tokens can rotate. If workflow tools stop working after a few weeks, run the capture again and re-run setup_ghl_mcp with the fresh values.
 ---
 ## Tools (171)
@@ -589,17 +530,18 @@ ghl-command-mcp/
 ├── templates/
 │   ├── clinic-medspa.json         # Clinic/Med Spa blueprint
 │   └── action-schemas.json        # Mandatory workflow action attribute schemas
-├── dist/                          # Compiled JavaScript (generated by build)
-├── setup.sh                       # One-command install + setup wizard
-├── setup-wizard.mjs               # Interactive setup wizard (@clack/prompts)
-├── start-mcp.example.sh           # Wrapper script template (copy to start-mcp.sh)
-├── package.json
+├── dist/                          # Compiled JavaScript (npm-published bundle)
+├── bin/ghl-mcp.js                 # npm bin entry point
+├── .github/workflows/publish.yml  # GitHub Actions npm-publish workflow
+├── package.json                   # @elitedcs/ghl-mcp
 ├── tsconfig.json
 ├── CLAUDE.md                      # Claude Code project instructions
 ├── CHANGELOG.md
 ├── CONTRIBUTING.md                # Contributor guide
 ├── .gitignore
 └── README.md
+# Legacy (kept for self-hosted dev workflows; buyers don't need these):
+# setup.sh, setup-wizard.mjs, start-mcp.example.sh
 ```
 ---
@@ -632,10 +574,10 @@ This MCP server is safe to share via GitHub.
 | Concern | How It's Handled |
 |---|---|
-| **API Keys** | Stored in environment variables or wrapper script only. Never in code, never committed. |
-| **`.env` & `start-mcp.sh`** | Gitignored. Your credentials never touch version control. |
-| **Multi-user** | Each user brings their own API key. Complete account isolation. |
-| **Scope** | The server only talks to GHL's API. No filesystem access, no shell commands, no network access beyond GHL. |
+| **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. |
+| **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. |
 | **Permissions** | Controlled by your GHL Private Integration scopes. Disable what you don't need. |
 ---
@@ -659,52 +601,29 @@ This server has been through a rigorous, multi-pass audit for production reliabi
 ---
-## Access & Collaboration
-This is a **private repository**. Access is by invitation only, controlled by Elite DCs, LLC.
-### For the Repo Owner (granting access)
-1. Get the person's **GitHub username** (they need a free GitHub account at [github.com](https://github.com))
-2. Go to [github.com/drjerryrelth/ghl-command-mcp/settings/access](https://github.com/drjerryrelth/ghl-command-mcp/settings/access)
-3. Click **Add people**
-4. Enter their GitHub username or email
-5. Set role:
-   - **Read** — for customers (can pull updates, cannot push)
-   - **Write** — for contributors (can push branches and open PRs)
-6. Click **Add** — they'll receive an email invitation
-> **Security:** Customers get **Read-only** access. Contributors get **Write** access to push branches and open PRs, but should never push directly to `main`. Use branch protection rules to enforce this.
-### For Contributors (first-time setup)
-**Step 1:** Accept the GitHub invitation from `drjerryrelth` (check your email).
+## Updates
-**Step 2:** Follow **Path 2 (Manual Install)** in the Quick Start section above. You'll need your own GHL API key.
+**Automatic.** Every Claude restart, `npx -y @elitedcs/ghl-mcp@latest` re-resolves the latest published version. When v3.0.1 ships, every buyer is on it next time they reopen Claude. Zero action required.
-**Step 3:** Read **[CONTRIBUTING.md](CONTRIBUTING.md)** for branching conventions, how to add tools, and PR guidelines.
+To pin a specific version (e.g. for stability), change `@latest` to `@3.0.0` in your MCP config.
-**Step 4:** Create a branch, make your changes, and open a PR against `main`.
-### For Customers / Invited Users (first-time setup)
-**Step 1:** Accept the GitHub invitation from `drjerryrelth` (check your email).
-**Step 2:** Follow **Path 1 (Easy Install)** or **Path 2 (Manual Install)** in the Quick Start section above. You'll need your own GHL API key — each user connects to their own GHL account.
-**Step 3:** Restart Claude Code and test with `"List my contacts"`
+---
-> **Note:** You have read-only access. You can clone and pull updates, but cannot push changes to the repository.
+## Contributing
-### Staying Up to Date
+Source repo is private. Contributors need an invitation from `drjerryrelth`. The npm-published artifact is open; the build/source pipeline is not.
-```bash
-cd ghl-command-mcp
-git pull
-npm run build
-```
+**For contributors with repo access:**
-Then restart Claude Code. Your settings and API key stay the same.
+1. Clone the repo, run `npm install`
+2. For dev work, set env vars in your shell or a wrapper script (env vars take priority over the credentials file — your dev workflow won't conflict with a buyer install on the same machine):
+   ```bash
+   export GHL_API_KEY=pit-your-dev-key
+   export GHL_LOCATION_ID=your-test-location
+   node dist/index.js
+   ```
+3. Read **[CONTRIBUTING.md](CONTRIBUTING.md)** for branching conventions, how to add tools, and PR guidelines.
+4. Create a branch, run `npm run build`, test against a sandbox sub-account, open a PR against `main`.
 ---
@@ -726,12 +645,12 @@ Then restart Claude Code. Your settings and API key stay the same.
 | Error | Cause | Fix |
 |---|---|---|
-| MCP tools don't appear (CLI) | Server not registered | Run `claude mcp add --scope user -t stdio ghl /path/to/start-mcp.sh` |
-| MCP tools don't appear (CLI) | Wrong config file | Must be in `~/.claude.json` (via `claude mcp add`), NOT `~/.claude/mcp.json` |
-| MCP tools don't appear (Desktop App) | Config missing or wrong | Check `~/Library/Application Support/Claude/claude_desktop_config.json` has a `ghl` entry under `mcpServers` |
+| Only `setup_ghl_mcp` shows up; no other tools | Bootstrap mode — credentials not yet activated | Run `setup_ghl_mcp` with all four required fields, then restart Claude |
+| MCP tools don't appear (CLI) | Server not registered | Run `claude mcp add --scope user -t stdio ghl -- npx -y @elitedcs/ghl-mcp@latest` |
+| MCP tools don't appear (Desktop App) | Config missing or wrong | Check `~/Library/Application Support/Claude/claude_desktop_config.json` has a `ghl` entry under `mcpServers` (see Quick Start above for the exact block) |
 | MCP tools don't appear (Desktop App) | App not restarted | Quit the Claude app completely (Cmd+Q on Mac) and reopen it |
-| MCP tools don't appear (Desktop App) | Wrong node path | Make sure `"command": "node"` works in your terminal. If not, use the full path (e.g., `/usr/local/bin/node`) |
-| `GHL_API_KEY environment variable is required` | Missing API key | Set it in `start-mcp.sh` or `.env` file |
+| `License key not found` | Wrong email or license_key | Both must match exactly what we have on file. Check spam for the welcome email. |
+| `License key already activated on 3 devices` | Activation limit hit | Email `support@cliniclaunchlab.com` to reset |
 | `locationId is required` | Tool needs a location ID | Set `GHL_LOCATION_ID` in your env, or tell Claude which location to use |
 | `GHL API Error 401` | Invalid or expired key | Generate a new API key in GHL > Settings > Integrations |
 | `GHL API Error 403` | Key from wrong sub-account | Create a new Private Integration **inside the correct sub-account** |

package/dist/index.js CHANGED Viewed

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.0.0",
+      version: "3.0.3",
       description: "GoHighLevel MCP Server for Claude. 171 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
       main: "dist/index.js",
       bin: {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.0.0",
+  "version": "3.0.3",
   "description": "GoHighLevel MCP Server for Claude. 171 tools — full CRM, automation, marketing control, and the only programmatic GHL workflow builder.",
   "main": "dist/index.js",
   "bin": {