@elitedcs/ghl-mcp 3.44.0 → 3.45.0

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.44.0",
+      version: "3.45.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
       description: "GoHighLevel MCP Server for Claude. 218 tools \u2014 full CRM, automation, marketing control, account-wide workflow audit, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
@@ -43,6 +43,8 @@ var require_package = __commonJS({
         "templates/action-schemas.json",
         "templates/clinic-medspa.json",
         "templates/trigger-schemas.json",
+        "templates/external-funnel/cloudflare-worker.js",
+        "templates/external-funnel/README.md",
         "README.md",
         "CHANGELOG.md"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.44.0",
+  "version": "3.45.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
   "description": "GoHighLevel MCP Server for Claude. 218 tools — full CRM, automation, marketing control, account-wide workflow audit, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",
@@ -12,6 +12,8 @@
     "templates/action-schemas.json",
     "templates/clinic-medspa.json",
     "templates/trigger-schemas.json",
+    "templates/external-funnel/cloudflare-worker.js",
+    "templates/external-funnel/README.md",
     "README.md",
     "CHANGELOG.md"
   ],

package/templates/external-funnel/README.md

@@ -0,0 +1,72 @@
+# External-Funnel Lead Bridge (power-user, self-hosted)
+
+When a Blueprint funnel is `target: "external"`, GHL Command does **not** build or
+host the site — you do, on your own Cloudflare/Vercel account, and wire its form
+back to your GHL sub-account with this lead bridge. **GHL Command never holds your
+keys, deploys for you, or touches your accounts.** This is a technically-capable,
+self-serve path — not a novice one.
+
+## What you need (capability check — be honest before you start)
+- Your own **Cloudflare** (or Vercel) account + the CLI (`wrangler` / `vercel`).
+- A **GHL Private Integration token** (Settings → Private Integrations) scoped to
+  `contacts.write` for the target sub-account. You'll store it as a host secret.
+- Comfort with a one-time command-line deploy and editing a config file.
+- (Optional) a custom **domain** + DNS access to point it at the site.
+
+If any of that isn't you, choose `target: "ghl"` instead — Blueprint builds the
+funnel inside GHL with no setup on your part.
+
+## The pieces
+1. **Your site** — generated by the Blueprint skill (frontend-design) or your own;
+   hosted on Cloudflare Pages / Vercel. Its form POSTs JSON to the bridge.
+2. **The lead bridge** — `cloudflare-worker.js` here (Vercel variant is analogous:
+   same logic in an `api/lead.js` handler; read config from `process.env`).
+3. **Your GHL sub-account** — already built by `apply_build_plan`: the custom
+   fields, the trigger tag, and the speed-to-lead workflow. The bridge feeds it.
+4. **Booking** — link your site's "book" button straight to the GHL calendar's
+   public URL (no bridge needed).
+
+## Wiring values (from `apply_build_plan`)
+The executor returns what you plug into the Worker config + form:
+- `GHL_LOCATION_ID` — the sub-account id.
+- `TRIGGER_TAG` — the tag that starts your workflow.
+- the custom **field IDs** your form's `custom` object should send (`{ "<fieldId>": value }` — GHL's upsert keys custom fields by id, not name).
+- the calendar **booking URL** for the site's CTA.
+
+## Deploy (Cloudflare)
+1. `npm i -g wrangler && wrangler login`
+2. `wrangler secret put GHL_PIT`  ← paste your token (secret; never in code/repo)
+3. Set `[vars]` in `wrangler.toml`: `GHL_LOCATION_ID`, `TRIGGER_TAG`,
+   `ALLOWED_ORIGIN` (your funnel domain — locks CORS), optional `RE_ENROLL`.
+4. (Optional) Turnstile: add the widget to your form, `wrangler secret put
+   TURNSTILE_SECRET`.
+5. `wrangler deploy` → point your form at the Worker URL.
+
+## Safety built in
+- **Secret stays server-side** — the token lives only as a Cloudflare secret, never
+  in the browser.
+- **Spam gate** — honeypot field (`_hp`) + Cloudflare Turnstile. **Strongly enable
+  Turnstile in production:** this is a public, unauthenticated endpoint, and the
+  honeypot only filters naive browser bots — without Turnstile, any scripted client
+  can post directly. Turnstile is the real abuse gate.
+- **Dedup** — uses `/contacts/upsert` (by email/phone), so repeat submits update,
+  never duplicate.
+- **Fail-closed** — if GHL can't be reached, the form gets an error (so the lead is
+  retried), not a silent success that drops it. Logs to `wrangler tail`.
+- **Origin check** — `ALLOWED_ORIGIN` limits browser cross-origin access and is
+  required (no wildcard). NOTE: this is **not** authentication — it does not block
+  `curl` or server-side clients (they send no/forged Origin). Use Turnstile for that.
+
+## Re-enrollment caveat
+GHL's Contact-Tag trigger fires on a tag **transition**, so re-adding a tag a
+contact already has won't re-fire the workflow. For speed-to-lead that's usually
+what you want. If you need returning submitters re-enrolled, set `RE_ENROLL=true`
+(the Worker removes + re-adds the tag) AND enable re-enrollment on the workflow.
+Confirm the behavior on your account before relying on it.
+
+## Compliance
+If your workflow sends SMS/email, your external form MUST collect explicit consent
+(a checkbox + clear copy). Define a **consent custom field** in your Blueprint plan
+and send its value in `custom` (keyed by that field's id) like any other field, so
+the consent is recorded on the contact. You own CAN-SPAM/TCPA compliance for an
+externally-captured lead.

package/templates/external-funnel/cloudflare-worker.js

@@ -0,0 +1,171 @@
+/**
+ * GHL Command — External-Funnel Lead Bridge (Cloudflare Worker)
+ * ============================================================================
+ * Receives a POST from YOUR externally-hosted funnel/site form and pushes the
+ * lead into YOUR GoHighLevel sub-account: it upserts the contact (dedup by
+ * email/phone) and adds the trigger tag that fires your speed-to-lead workflow
+ * (the one GHL Command Blueprint built for you).
+ *
+ * This is the "wired to GHL via webhooks" piece. It runs in YOUR Cloudflare
+ * account with YOUR GHL token. GHL Command never sees it, deploys it, or holds
+ * your keys — this is a power-user, self-hosted path.
+ *
+ * ─── SETUP (one time) ───────────────────────────────────────────────────────
+ * 1. Install Wrangler:           npm i -g wrangler   (then `wrangler login`)
+ * 2. Put your GHL token as a SECRET (never in code/vars):
+ *                                wrangler secret put GHL_PIT
+ *    (Use a GHL Private Integration token scoped to contacts.write for the
+ *     target sub-account. Treat it like a password — if it leaks, rotate it in
+ *     GHL > Settings > Private Integrations.)
+ * 3. Set the non-secret config in wrangler.toml [vars]:
+ *      GHL_LOCATION_ID = "your sub-account id"          (from get_current_location)
+ *      TRIGGER_TAG     = "the tag that starts your workflow"  (e.g. "new-lead")
+ *      ALLOWED_ORIGIN  = "https://your-funnel-domain.com"     (CORS lock)
+ *      TURNSTILE_SECRET (optional) — set as a SECRET if you enable Turnstile
+ *      RE_ENROLL       = "false"   (see "Re-enrollment" below)
+ * 4. Deploy:                      wrangler deploy
+ * 5. Point your form's submit at the Worker URL (POST JSON).
+ *
+ * ─── FORM CONTRACT ──────────────────────────────────────────────────────────
+ * POST application/json. Standard keys map to GHL standard fields; `custom` is an
+ * object keyed by GHL custom-field ID (from apply_build_plan's wiring bundle) →
+ * value. Consent is just a custom field (include one in your plan if you trigger
+ * SMS/email — see the README compliance note).
+ *   { "first_name","last_name","email","phone",
+ *     "custom": { "<ghlCustomFieldId>":"Botox", "<consentFieldId>":"yes", ... },
+ *     "_hp": "" }                            // honeypot — bots fill it, humans don't
+ *
+ * ─── Re-enrollment caveat (READ) ────────────────────────────────────────────
+ * GHL's "Contact Tag" trigger fires on a tag TRANSITION (not-present → present).
+ * Re-adding a tag a contact ALREADY has does NOT re-fire the workflow. For
+ * speed-to-lead that's usually correct (don't re-spam someone already in your
+ * pipeline). If you DO need returning submitters re-enrolled, set RE_ENROLL=true
+ * (this Worker removes then re-adds the tag to force a transition) AND enable
+ * re-enrollment on the workflow in GHL. [Confirm the exact behavior on your
+ * account before relying on it.]
+ * ============================================================================
+ */
+
+const GHL_BASE = "https://services.leadconnectorhq.com";
+const GHL_VERSION = "2021-07-28";
+
+export default {
+  async fetch(request, env) {
+    // Server must be configured with the funnel's origin.
+    if (!env.ALLOWED_ORIGIN) return json({ error: "server misconfigured: set ALLOWED_ORIGIN" }, 500, {});
+    // Browser cross-origin lock: block a mismatched Origin. NOTE: this is NOT a
+    // security boundary — a non-browser client (curl/server script) sends no/forged
+    // Origin and bypasses CORS entirely. Real abuse protection = Turnstile (below).
+    const origin = request.headers.get("Origin");
+    if (origin && origin !== env.ALLOWED_ORIGIN) return json({ error: "forbidden origin" }, 403, {});
+    const cors = corsHeaders(env);
+    if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: cors });
+    if (request.method !== "POST") return json({ error: "POST only" }, 405, cors);
+
+    let data;
+    try { data = await request.json(); } catch { return json({ error: "invalid JSON" }, 400, cors); }
+
+    // 1. Spam gate — honeypot first (free), then Turnstile if configured.
+    if (typeof data._hp === "string" && data._hp.trim() !== "") {
+      return json({ ok: true }, 200, cors); // silently accept + drop the bot
+    }
+    if (env.TURNSTILE_SECRET) {
+      const ok = await verifyTurnstile(data.cf_turnstile_token, env.TURNSTILE_SECRET, request);
+      if (!ok) return json({ error: "captcha failed" }, 403, cors);
+    }
+
+    // 2. Minimal validation — need at least an email or phone to dedup on.
+    const email = clean(data.email);
+    const phone = clean(data.phone);
+    if (!email && !phone) return json({ error: "email or phone required" }, 422, cors);
+
+    // 3. Build the GHL upsert body. customFields are { id, value } where id is the
+    //    GHL custom-field ID (from apply_build_plan's wiring bundle) — this is the
+    //    shape GHL's v2 /contacts/upsert + this product's upsert_contact use. The
+    //    form's `custom` object is keyed by those ids. (Consent is just another
+    //    custom field — include a consent field in your plan and send it here.)
+    const customFields = Object.entries(data.custom || {})
+      .filter(([, v]) => v !== undefined && v !== null && v !== "")
+      .map(([id, value]) => ({ id, value }));
+
+    const body = {
+      locationId: env.GHL_LOCATION_ID,
+      ...(email ? { email } : {}),
+      ...(phone ? { phone } : {}),
+      ...(clean(data.first_name) ? { firstName: clean(data.first_name) } : {}),
+      ...(clean(data.last_name) ? { lastName: clean(data.last_name) } : {}),
+      tags: [env.TRIGGER_TAG],
+      customFields,
+      source: "external-funnel",
+    };
+
+    // 4. Upsert with bounded retry/backoff (429/5xx/network). Fail-CLOSED: if the
+    //    lead can't be written, tell the user so it can be retried — never a
+    //    silent green that drops a paying lead.
+    try {
+      const upserted = await ghlFetch(`${GHL_BASE}/contacts/upsert`, "POST", body, env.GHL_PIT);
+      const contactId = upserted?.contact?.id || upserted?.id;
+      // Optional: force re-enrollment for a returning contact (tag transition).
+      // The remove is best-effort (the tag may not be present); the re-ADD MUST
+      // succeed (it's what re-fires the workflow) — let its failure propagate so
+      // we don't report success when re-enrollment silently failed.
+      if (env.RE_ENROLL === "true" && contactId) {
+        await ghlFetch(`${GHL_BASE}/contacts/${contactId}/tags`, "DELETE", { tags: [env.TRIGGER_TAG] }, env.GHL_PIT).catch(() => {});
+        await ghlFetch(`${GHL_BASE}/contacts/${contactId}/tags`, "POST", { tags: [env.TRIGGER_TAG] }, env.GHL_PIT);
+      }
+      return json({ ok: true, contactId }, 200, cors);
+    } catch (err) {
+      console.error("lead-bridge upsert failed", String(err)); // shows in `wrangler tail`
+      return json({ error: "lead delivery failed — please try again" }, 502, cors);
+    }
+  },
+};
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+function corsHeaders(env) {
+  return {
+    "Access-Control-Allow-Origin": env.ALLOWED_ORIGIN, // required + validated above; no "*" fallback
+    "Access-Control-Allow-Methods": "POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type",
+  };
+}
+function json(obj, status, cors) {
+  return new Response(JSON.stringify(obj), { status, headers: { "Content-Type": "application/json", ...(cors || {}) } });
+}
+function clean(v) { return typeof v === "string" ? v.trim() : ""; }
+
+async function ghlFetch(url, method, body, pit, attempt = 1) {
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${pit}`,
+      Version: GHL_VERSION,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: method === "GET" ? undefined : JSON.stringify(body),
+  });
+  if (res.status === 429 || res.status >= 500) {
+    if (attempt < 4) {
+      await sleep(250 * attempt);
+      return ghlFetch(url, method, body, pit, attempt + 1);
+    }
+  }
+  const text = await res.text();
+  if (!res.ok) throw new Error(`GHL ${res.status}: ${text.slice(0, 200)}`);
+  try { return JSON.parse(text); } catch { return {}; }
+}
+
+async function verifyTurnstile(token, secret, request) {
+  if (!token) return false;
+  const form = new FormData();
+  form.append("secret", secret);
+  form.append("response", token);
+  const ip = request.headers.get("CF-Connecting-IP");
+  if (ip) form.append("remoteip", ip);
+  const r = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", { method: "POST", body: form });
+  const out = await r.json().catch(() => ({ success: false }));
+  return out.success === true;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));