@elitedcs/ghl-mcp 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,320 @@
+# Changelog
+
+## 2.7.0 — Complete Type Safety (Boris Cherny A+)
+
+**171 tools across 35 modules. Bundle: 214KB.**
+
+Closes every remaining type safety issue from the Boris Cherny audit. Zero escape hatches, runtime-validated API responses on critical paths, type-safe tool registration, and defensive property access everywhere.
+
+### account-export.ts — no more unsafe casts
+- Replaced `contacts as Record<string, unknown> & { meta?: ... }` with defensive runtime checks (`typeof`, `Array.isArray`) before property access.
+- `count()` helper uses `Object.values()` instead of indexing a cast object.
+- Switched to `jsonResponse`/`errorResponse` helpers.
+
+### Type-safe tool registration
+- `src/tools/index.ts` now uses a typed `ReadonlyArray<[ToolRegistrar, string]>` registry. The compiler verifies every function reference exists — adding an import without a registry entry or vice versa is a compile error.
+- Builder tools (Firebase auth) registered separately with explicit `WorkflowBuilderClient` parameter.
+
+### WorkflowFull — no more escape hatch
+- Removed `[key: string]: unknown` index signature from `WorkflowFull` interface. Replaced with explicit optional fields (`stopOnResponse`, `allowMultiple`, etc.) for all properties accessed in the codebase.
+
+### API response validation on critical paths
+- New `src/api-schemas.ts` — Zod schemas with `.passthrough()` for contacts, pipelines, and calendars.
+- `search_contacts` validates response against `ContactSearchResponseSchema`.
+- `get_contact` validates against `ContactResponseSchema`.
+- `get_pipelines` validates against `PipelinesResponseSchema`.
+- `get_calendars` validates against `CalendarsResponseSchema`.
+- Schema violations throw at the tool level with clear error messages instead of silently passing malformed data.
+
+### Startup update check
+- Server runs a non-blocking `git fetch` on startup and warns via stderr if a newer version is available on the remote.
+- Version is now read from `package.json` at build time instead of hardcoded — startup shows `v2.7.0 connected`.
+
+### Files changed
+- `src/index.ts` — dynamic version from package.json, background update check
+- `src/tools/account-export.ts` — defensive type access, response helpers
+- `src/tools/index.ts` — typed registry array
+- `src/workflow-builder-client.ts` — removed `[key: string]: unknown`
+- `src/api-schemas.ts` — NEW: Zod response schemas
+- `src/tools/contacts.ts` — output validation on search + get
+- `src/tools/opportunities.ts` — output validation on get_pipelines
+- `src/tools/calendars.ts` — output validation on get_calendars
+
+## 2.6.0 — A+ Type Safety
+
+**171 tools across 35 modules. Bundle: 210KB.**
+
+Eliminated all generic `as T` type casts from both HTTP clients, added Zod runtime validation on API responses and template files, added pre-flight workflow action validation, and documented pagination strategies across all tools.
+
+### Honest types — no more `as T` casts
+
+- `GHLClient.request()` and all HTTP methods (`get`, `post`, `put`, `patch`, `delete`) now return `Promise<unknown>` instead of `Promise<T>`. No more `JSON.parse(text) as T` — the type system no longer lies about response shapes.
+- `WorkflowBuilderClient.request()` — same treatment. Returns `Promise<unknown>`.
+- `getWorkflow()` and `createWorkflow()` now validate responses against a `WorkflowFullSchema` (Zod) before returning typed `WorkflowFull`. Runtime-validated, not compile-time-assumed.
+- `location-switcher.ts` — replaced `client.get<LocationResponse>(...)` with honest `Record<string, unknown>` + defensive property access.
+
+### Template Zod validation
+
+- `template-deployer.ts` now validates template JSON against `TemplateSchema` on load — catches malformed templates with clear error messages instead of crashing mid-deploy.
+- `resolveObj()` is now generic `<T>(obj: T): T` — preserves input types through string replacement, eliminating 5 downstream `as Record<string, unknown>` casts.
+- Template structure (tags, customFields, pipelines, workflows, calendars) is now a single Zod source of truth.
+
+### Workflow action validation
+
+- `validateActionChain()` — pre-flight validation before sending actions to GHL. Checks: SMS needs `body` + `attachments`, email needs `subject` + `html` + `trackingOptions`, tags need `tags[]`, wait needs `startAfter`, create_opportunity needs `pipelineId` + `stageId`, remove_from_workflow needs both `workflowId` and `workflow_id[]`.
+- `hasId()` type guard — replaces `as string` casts on action ID filtering with proper TypeScript narrowing.
+- Removed `!` non-null assertion on `action.next` assignment — replaced with explicit null check.
+
+### Pagination documentation
+
+- 11 tools now include pagination strategy in their descriptions (offset-based, page-based, or cursor-based).
+- Updated: get_funnels, get_funnel_pages, get_orders, get_subscriptions, get_transactions, list_invoices, get_blog_posts, get_form_submissions, get_survey_submissions, get_form_submissions_full, list_available_locations.
+
+### Files changed
+
+- `src/ghl-client.ts` — removed all generic `<T>`, returns `Promise<unknown>`
+- `src/workflow-builder-client.ts` — removed generics, added `WorkflowFullSchema`, `hasId()`, `validateActionChain()`
+- `src/tools/location-switcher.ts` — removed `<LocationResponse>` generic, honest casts
+- `src/tools/template-deployer.ts` — added `TemplateSchema`, generic `resolveObj<T>`, removed 6 unsafe casts
+- 8 tool files — pagination documentation updates
+
+## 2.5.0 — Type Safety & Boilerplate Overhaul
+
+**171 tools across 35 modules. Bundle: 206KB (down from 246KB).**
+
+Boris Cherny-style type safety audit and overhaul. Eliminated ~40KB of duplicated boilerplate, added runtime validation, guarded destructive operations, and introduced typed workflow action schemas.
+
+### `safeTool()` wrapper — eliminates boilerplate (Phase A)
+
+- New `safeTool()` higher-order function in `tool-helpers.ts` — wraps tool handlers with automatic try/catch and JSON response formatting
+- Converted 25 tool modules (~120 tools) from manual try/catch/JSON.stringify to `safeTool()` — handlers now just return data
+- Net reduction: ~1000 lines of duplicated error handling eliminated
+- Files skipped (complex handlers): bulk-operations, template-deployer, location-switcher, account-export, workflow-cloner, builder modules
+
+### Zod-validated token registry (Phase B)
+
+- `token-registry.ts` now validates `.ghl-tokens.json` against a Zod schema on load
+- Types derived from schemas (`z.infer<>`) instead of manual interfaces — single source of truth
+- Malformed registry files fail with a clear validation error instead of silent type-assertion cast
+
+### Delete confirmation guards (Phase C)
+
+- 10 destructive delete operations now require `confirm: "DELETE"` parameter, matching existing `bulk_delete_contacts` pattern
+- Guarded: `delete_contact`, `delete_opportunity`, `delete_calendar`, `delete_appointment`, `delete_business`, `delete_workflow_full`, `delete_pipeline`, `delete_form`, `delete_funnel`, `delete_funnel_page`
+- Low-risk deletes (media, webhooks, social posts, coupons, tags, etc.) left unguarded
+
+### Discriminated union for WorkflowAction (Phase D)
+
+- New `src/workflow-action-types.ts` — typed attribute interfaces for all 11 documented action types (sms, email, wait, add_contact_tag, remove_contact_tag, internal_notification, update_contact_field, add_notes, task_notification, remove_from_workflow, create_opportunity)
+- `WorkflowAction` is now a discriminated union on `type` with a `string` fallback for unknown types
+- Compile-time enforcement that SMS actions have `body` + `attachments`, emails have `subject` + `html` + `trackingOptions`, etc.
+
+### Files Changed
+
+- `src/tool-helpers.ts` — Added `safeTool()` wrapper with MCP SDK type imports
+- `src/token-registry.ts` — Zod schema validation, types derived from schemas
+- `src/workflow-action-types.ts` — NEW: discriminated union type definitions
+- `src/workflow-builder-client.ts` — Imports WorkflowAction from new types file
+- 25 tool modules converted to `safeTool()` pattern
+- 8 tool files updated with delete confirmation guards
+
+## 2.4.0 — Reliability & Consistency Audit
+
+**171 tools across 35 modules.**
+
+Full audit and hardening pass — every tool reviewed for reliability, error handling, and LLM usability.
+
+### Reliability Fixes
+
+- **Retry with exponential backoff** — Both `ghl-client.ts` and `workflow-builder-client.ts` now retry on 429 rate limits, 5xx server errors, and transient network errors (ECONNRESET, ETIMEDOUT). 3 retries with 500ms base delay. Respects `Retry-After` header.
+- **Clear timeout errors** — Request timeouts now throw `"Request timeout (30s): GET /path"` instead of cryptic `AbortError`.
+- **Firebase token refresh lock** — Concurrent requests now share a single token refresh instead of racing. Eliminates duplicate Firebase calls and potential token corruption.
+- **Firebase cache clear on failure** — If token refresh fails, the stale cache is cleared immediately instead of persisting for 55 minutes of cascading failures.
+- **Startup API key validation** — Server validates the API key at startup (non-blocking) and logs a clear warning if it returns 401.
+- **Token registry corruption backup** — If `.ghl-tokens.json` is corrupted, it's backed up as `.ghl-tokens.json.corrupted.<timestamp>` before falling back to empty.
+
+### Consistency Fixes (LLM Usability)
+
+- **Standardized locationId handling** — All 13 affected tool files now use consistent `.optional()` locationId with `resolveLocationId()` fallback. Removed 25 instances of incorrect `await` on the synchronous `resolveLocationId()` method.
+- **Fixed tools missing resolveLocationId()** — `users.ts`, `businesses.ts`, `courses.ts`, `social-planner.ts` now properly resolve locationId from env var fallback instead of passing raw (possibly undefined) values.
+- **Hidden altId/altType from LLM** — `media.ts` tools now accept `locationId` and map to `altId`/`altType` internally, matching the pattern used by invoices, estimates, coupons, and payments.
+- **Improved builder tool descriptions** — All `_full` builder tools now mention "Requires Firebase auth" and clarify when to use them vs public API versions. `update_workflow_actions` now says "Call get_workflow_full first". `create_workflow` shows the explicit 3-step flow.
+- **Complete action/trigger type lists** — `update_workflow_actions` description now lists all supported action and trigger types instead of "etc."
+
+### Files Changed
+
+- `src/ghl-client.ts` — Retry/backoff, timeout error handling
+- `src/workflow-builder-client.ts` — Retry/backoff, timeout, token refresh lock + cache clear
+- `src/token-registry.ts` — Corruption backup on load failure
+- `src/index.ts` — Startup API key validation
+- `src/tools/blogs.ts` — locationId optional + remove await
+- `src/tools/campaigns.ts` — locationId optional + remove await
+- `src/tools/emails.ts` — locationId optional + remove await
+- `src/tools/forms.ts` — locationId optional + remove await
+- `src/tools/funnels.ts` — locationId optional + remove await
+- `src/tools/invoices.ts` — locationId optional + remove await
+- `src/tools/payments.ts` — locationId optional + remove await
+- `src/tools/surveys.ts` — locationId optional + remove await
+- `src/tools/trigger-links.ts` — locationId optional + remove await
+- `src/tools/users.ts` — locationId optional + add resolveLocationId
+- `src/tools/businesses.ts` — locationId optional + add resolveLocationId
+- `src/tools/courses.ts` — locationId optional + add resolveLocationId
+- `src/tools/social-planner.ts` — locationId optional + add resolveLocationId
+- `src/tools/media.ts` — Replace altId/altType with locationId
+- `src/tools/workflow-builder.ts` — Improved tool descriptions
+
+## 2.3.0 — Multi-Sub-Account Token Registry
+
+**171 tools across 35 modules.**
+
+### New: Token Registry
+
+- **`src/token-registry.ts`** — Per-location API key storage for seamless multi-sub-account access
+- Stores API keys in `.ghl-tokens.json` (gitignored) — no server restart needed to switch locations
+- Also stores Firebase credentials and agency-level API key
+
+### New: Location Registry Tools (3 tools)
+
+- `register_location` — Add a sub-account and its API key to the token registry
+- `unregister_location` — Remove a sub-account from the token registry
+- `list_registered_locations` — List all sub-accounts stored in the token registry
+
+### Improved: Location Switcher
+
+- `switch_location` now automatically swaps the API key from the token registry when switching sub-accounts
+- `get_current_location` now shows token registry status
+
+### Documentation
+
+- Updated README tool count from 167 → 171 and version from 2.2.0 → 2.3.0
+- Added **Known Limitations** section to README — documents what the MCP can't do (contact merge, templates, calls, analytics, etc.)
+- Added **CONTRIBUTING.md** — dev setup, branching, PR guidelines, how to add tools
+- Updated **Access & Collaboration** section with contributor (Write) role alongside customer (Read) role
+- Updated project structure tree with `token-registry.ts`, `action-schemas.json`, `CONTRIBUTING.md`
+- Updated CLAUDE.md architecture section and build notes for token registry
+- Generated website update prompt at `templates/website-update-2026-04-01.md`
+
+## 2.2.0 — Builder Suite + Power Tools
+
+**164 tools across 34 modules.**
+
+### New: Funnel/Page Builder (9 tools)
+- `list_funnels_full`, `get_page_full`, `get_page_content` — read full page builder data (sections, elements, CSS, tracking codes)
+- `create_funnel`, `update_funnel`, `delete_funnel` — funnel CRUD
+- `create_funnel_page`, `update_page_content`, `delete_funnel_page` — page CRUD
+
+### New: Form Builder (5 tools)
+- `get_form_full` — read all fields, conditional logic, auto-responder, email notifications
+- `create_form`, `update_form`, `delete_form` — form CRUD
+- `get_form_submissions_full` — full submission data via internal API
+
+### New: Pipeline Builder (5 tools)
+- `list_pipelines_full`, `get_pipeline_full` — full stage details via internal API
+- `create_pipeline`, `update_pipeline`, `delete_pipeline` — pipeline/stage CRUD
+
+### New: Bulk Operations (5 tools)
+- `bulk_add_tags`, `bulk_remove_tags` — batch tag management
+- `bulk_update_contacts` — batch field updates
+- `bulk_add_to_workflow` — batch workflow enrollment
+- `bulk_delete_contacts` — batch deletion with safety confirmation
+- All operations rate-limited with success/failure reporting
+
+### New: Account Export & Comparison (2 tools)
+- `export_account` — full sub-account backup to JSON
+- `compare_locations` — side-by-side diff of two sub-accounts
+
+### New: Workflow Cloner (1 tool)
+- `clone_workflow` — deep clone with UUID remapping for all actions, triggers, and references
+
+### New: Location Switcher (3 tools)
+- `get_current_location`, `switch_location`, `list_available_locations`
+- Switch between sub-accounts mid-session without restarting
+
+### Fixes
+- Added `source: WEB_USER` header (required by funnel/form internal endpoints)
+- Made `buildHeaders()` public on WorkflowBuilderClient for reuse by builder modules
+
+## 2.1.0 — Workflow Builder (Internal API)
+
+**134 tools across 27 modules.**
+
+### New: Full Workflow CRUD
+
+- **WorkflowBuilderClient** — authenticates via Firebase refresh token to access GHL's internal backend API (`backend.leadconnectorhq.com`)
+- 6 new MCP tools for complete workflow management:
+  - `list_workflows_full` — list with full metadata and permissions
+  - `get_workflow_full` — read every action, trigger, condition, if/else branch, email template, SMS body
+  - `create_workflow` — create new workflows (start as draft)
+  - `update_workflow_actions` — add, edit, remove actions/triggers/branches
+  - `delete_workflow_full` — permanently delete workflows
+  - `publish_workflow` — publish drafts to make them active
+- Supports all GHL action types: sms, email, add_contact_tag, wait, if_else, webhook, custom_code, and more
+- Supports all GHL trigger types: contact_tag, form_submission, appointment, inbound_webhook, and more
+- Automatic version tracking for safe concurrent editing
+- Graceful degradation — if Firebase env vars not set, standard tools still work
+
+### New Environment Variables (Optional)
+
+- `GHL_USER_ID` — required for workflow builder
+- `GHL_FIREBASE_API_KEY` — Firebase API key from GHL auth
+- `GHL_FIREBASE_REFRESH_TOKEN` — Firebase refresh token (may rotate)
+
+## 2.0.0 — CommonJS Rebuild
+
+**128 tools across 26 modules.**
+
+### Breaking Changes
+
+- Converted from ESM to CommonJS — removed `"type": "module"` from package.json
+- Build system switched from `tsc` to `esbuild` — tsc OOMs on TS 5.9.3 with MCP SDK types
+- MCP registration now uses `claude mcp add --scope user` (registers in `~/.claude.json`, NOT `~/.claude/mcp.json`)
+
+### New Modules (6)
+
+- **Custom Objects** (7 tools) — List schemas, CRUD records
+- **Associations** (3 tools) — Link custom object records to contacts/opportunities/other records
+- **Estimates** (6 tools) — Create, update, delete, send quotes/estimates
+- **Coupons** (5 tools) — Create and manage promo codes
+- **Webhooks** (5 tools) — CRUD webhook subscriptions
+- **Documents** (4 tools) — List, get, delete, send documents for signature
+
+### Improvements
+
+- Added `dotenv` for `.env` fallback (wrapper script is primary env source)
+- Improved error handling: `unhandledRejection` handler, stderr logging
+- API key is now optional — server starts gracefully and reports auth errors per-tool
+- Added `start-mcp.sh` wrapper script for reliable env var injection
+
+## 1.0.0 — Initial Release
+
+**98 tools across 20 modules.**
+
+### Modules
+
+- **Contacts** (15 tools) — Full CRM: search, create, update, delete, tags, notes, tasks, appointments, workflow management
+- **Conversations** (8 tools) — Messaging: search threads, send SMS/email/WhatsApp, manage message status
+- **Opportunities** (7 tools) — Pipeline: create/update/delete deals, move through stages, manage status
+- **Calendars** (11 tools) — Scheduling: manage calendars, check availability, book/update/cancel appointments
+- **Locations** (15 tools) — Admin: sub-account settings, custom fields, custom values, location tags
+- **Invoices** (8 tools) — Billing: create, send, void, record payments
+- **Social Planner** (5 tools) — Social media: create, list, delete posts, view connected accounts
+- **Businesses** (5 tools) — Business entities: full CRUD
+- **Blogs** (5 tools) — Blog management: posts, authors, categories, URL slugs
+- **Payments** (4 tools) — Orders, subscriptions, transaction history
+- **Funnels** (2 tools) — List funnels and pages
+- **Forms** (2 tools) — List forms, view submissions
+- **Surveys** (2 tools) — List surveys, view submissions
+- **Users** (2 tools) — Team member management
+- **Media** (2 tools) — Media file browsing and deletion
+- **Campaigns** (1 tool) — Campaign listing
+- **Workflows** (1 tool) — Workflow listing
+- **Courses** (1 tool) — Course listing
+- **Emails** (1 tool) — Email campaign listing
+- **Trigger Links** (1 tool) — Trigger link listing
+
+### Infrastructure
+
+- MCP server with stdio transport
+- GHL API v2 HTTP client with auth, versioning, and error handling
+- Zod schema validation on all tool inputs
+- One-command setup script (`setup.sh`)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elite DCs, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.