@elitedcs/ghl-mcp 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 3.4.0 — health_check tool + validate_workflow expansion + smoke-test CI
+
+**175 tools across 38 modules. Bundle: 274.6 KB.**
+
+Three improvements that buyers don't have to ask for.
+
+### `health_check` tool (NEW)
+A single diagnostic that runs five probes in parallel and reports a structured pass/fail/warn list:
+
+1. **npm registry + version** — is the registry reachable? Are you on the latest version?
+2. **GHL API key** — does it validate against `/locations/search`? (catches revoked/expired keys)
+3. **Default location** — can you actually read it? Reports the location name on success.
+4. **Firebase auth** — refreshes the workflow-builder token; reports `skip` if not configured, `pass`/`fail` if it is.
+5. **Token registry** — how many sub-accounts are registered for `switch_location`?
+
+Use case: "is my install OK?" first-line troubleshooting, post-restart sanity check after credentials rotate, support back-and-forth with buyers.
+
+### `validate_workflow` expansion
+The v3.3.1 validator now also checks **form IDs**, **calendar IDs**, and **survey IDs** in trigger conditions. Coverage went from 5 → 8 reference categories:
+- Pipeline IDs
+- Pipeline Stage IDs
+- Custom Field IDs
+- User IDs
+- Workflow IDs
+- **Form IDs** (NEW — checks `form.id` in form_submission triggers)
+- **Calendar IDs** (NEW — checks `calendar.id` in appointment / customer_appointment triggers)
+- **Survey IDs** (NEW — checks `survey.id` in survey_submission triggers)
+
+### Post-publish smoke-test CI
+A new job in `.github/workflows/publish.yml` runs after npm publish: waits for registry propagation (~30s typical), then `npx`-installs the just-published version in a clean machine, spawns it with the full MCP handshake (initialize → notifications/initialized → tools/list), and asserts that `get_mcp_version` and `setup_ghl_mcp` show up in the response.
+
+Catches the kind of publish regression where the package builds locally and uploads to npm fine but fails to boot on a buyer's machine because of a missing file, bad permission, or runtime error during tool registration. Adds ~2 minutes to the release cycle, makes future buyers safer.
+
+### Tool count tidy-up
+Fixed stale "171 tools" / "165 tools" strings in `setup-tool.ts` that buyers saw in the bootstrap-mode setup message. Now correctly reports 175 (full) / 167 (without workflow builder).
+
+### Files changed
+- `src/tools/diagnostics.ts` — NEW: `registerDiagnosticTools` + `health_check`.
+- `src/workflow-builder-client.ts` — public `checkAuth()` method for Firebase probe.
+- `src/tools/validators.ts` — form/calendar/survey reference extraction + lookups.
+- `src/tools/index.ts` — registered diagnostics module.
+- `src/setup-tool.ts` — corrected tool counts (171 → 175, 165 → 167).
+- `.github/workflows/publish.yml` — added smoke-test job.
+
+## 3.3.1 — validate_workflow + catalogue in npm package
+
+**174 tools across 37 modules. Bundle: 266.2 KB.**
+
+Two small wins:
+
+### `validate_workflow` tool (NEW)
+Pre-flight ID validation for a deployed workflow. Scans every trigger and action for references to pipelines, pipeline stages, custom fields, users, and other workflows. Verifies each ID exists in the current location. Returns a structured report with `references_scanned`, `issues_count`, and a `findings[]` list naming exactly which action / trigger / field path holds an invalid reference.
+
+This catches the silent-failure bug documented in CLAUDE.md: *"Invalid IDs silently kill all subsequent actions in a workflow."* GHL doesn't surface the error anywhere — actions just stop firing. Run `validate_workflow <workflowId>` after editing, or whenever a workflow stops behaving as expected.
+
+Coverage in this release:
+- Pipeline IDs (in `internal_update_opportunity` actions + trigger conditions)
+- Pipeline Stage IDs (cross-checked against their parent pipeline's stage list)
+- Custom Field IDs (in `update_contact_field` actions)
+- User IDs (in `internal_notification.selectedUser`, `task_notification.assignedTo`, trigger conditions)
+- Workflow IDs (in `remove_from_workflow` actions + trigger `add_to_workflow` actions)
+
+Forms, calendars, and surveys are referenced in trigger conditions for specific trigger types (form_submission, customer_appointment, survey_submission) — those checks are deferred to a later release.
+
+### `templates/trigger-schemas.json` now ships in the npm package
+The 1.1 MB trigger catalogue (57 native + 434 marketplace trigger entries) was previously left out of the published package — buyers running `npx -y @elitedcs/ghl-mcp@latest` didn't receive it. Added to `package.json` `files[]` so installs always include it.
+
+### Files changed
+- `src/tools/validators.ts` — NEW: registerValidatorTools + validate_workflow.
+- `src/tools/index.ts` — wired validators into the registry.
+- `package.json` — added trigger-schemas.json to `files[]`; bumped version; tool count 173 → 174; description updated.
+- README, CLAUDE.md, CHANGELOG — synced.
+
 ## 3.3.0 — 100% native trigger coverage
 
 **173 tools across 36 modules. Bundle: 255.4 KB.**

package/README.md

@@ -1,6 +1,6 @@
 # GHL Command — GoHighLevel MCP Server
 
-**Full GoHighLevel API access for Claude.** 173 tools across 36 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.
+**Full GoHighLevel API access for Claude.** 175 tools across 36 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.
 
 **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).
 
@@ -98,7 +98,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 166 tools are now unlocked.
+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 167 tools are now unlocked.
 
 ### 4. Try it
 
@@ -138,7 +138,7 @@ https://app.gohighlevel.com/v2/location/YOUR_LOCATION_ID/dashboard
 
 ## Enable Workflow Builder (Optional)
 
-The 7 workflow builder tools use GHL'''s internal API and require Firebase credentials. Without them, the other 166 tools work fine — you just won'''t have workflow editing.
+The 8 workflow builder tools use GHL'''s internal API and require Firebase credentials. Without them, the other 167 tools work fine — you just won'''t have workflow editing.
 
 Grab the three values from your GHL browser session, then re-run `setup_ghl_mcp` with them:
 
@@ -167,7 +167,9 @@ Re-run setup_ghl_mcp with workflow builder:
 
 ---
 
-## Tools (173)
+## Tools (175)
+
+> **v3.4.0 adds `health_check`** — one diagnostic that reports npm registry + version, GHL API key validity, default location reachability, Firebase auth status, and token registry in a single structured report. Plus `validate_workflow` (v3.3.1) now covers form, calendar, and survey IDs in addition to pipelines/stages/custom-fields/users/workflows.
 
 ### CRM & Contacts (15 tools)
 
@@ -332,7 +334,7 @@ Re-run setup_ghl_mcp with workflow builder:
 | `get_subscriptions` | List active subscriptions |
 | `get_transactions` | View transaction history |
 
-### Workflow Builder (7 tools) — Internal API
+### Workflow Builder (8 tools) — Internal API
 
 > **This is the flagship feature.** GHL's public API has **zero** workflow write endpoints. These tools use GHL's internal backend API — the same API their own UI calls — reverse-engineered to give Claude full workflow CRUD. No other GHL integration, Zapier connector, or third-party tool can create or edit workflows programmatically. Requires additional Firebase auth setup (see "Enable Workflow Builder" in Quick Start above).
 
@@ -345,6 +347,7 @@ Re-run setup_ghl_mcp with workflow builder:
 | `delete_workflow_full` | Permanently delete a workflow |
 | `publish_workflow` | Publish a draft workflow to make it active |
 | `get_trigger_registry` | Discover GHL's marketplace trigger apps (Zoom, WooCommerce, Shopify, etc.) and their available trigger templates |
+| `validate_workflow` | Pre-flight validation: scans every action and trigger for references to pipelines, stages, custom fields, users, and other workflows; verifies each ID exists. Catches the silent-failure bug where invalid IDs make GHL skip subsequent actions |
 
 **What you can build:** Complete automation sequences — lead nurture drip campaigns, appointment reminder sequences, onboarding flows, re-engagement workflows, internal notification chains. Tell Claude what you want and it builds the workflow action by action.
 
@@ -410,11 +413,12 @@ Re-run setup_ghl_mcp with workflow builder:
 | `get_template_questionnaire` | Get the questionnaire for a template — present to user conversationally |
 | `deploy_template` | Deploy a complete sub-account setup from a template (tags, fields, pipelines, workflows, forms). Supports dry-run mode. |
 
-### Meta (1 tool)
+### Meta & Diagnostics (2 tools)
 
 | Tool | What It Does |
 |---|---|
 | `get_mcp_version` | Check installed version against the latest published to npm. Confirms an upgrade landed after restarting Claude. Available even before GHL credentials are configured. |
+| `health_check` | Run a full health check: npm registry + version status, GHL API key validity, default location reachability, Firebase auth status, token registry presence. Use when something feels broken. |
 
 ### Other Modules