@elitedcs/ghl-mcp 3.38.0 → 3.39.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.38.0",
+      version: "3.39.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",
@@ -9625,8 +9625,8 @@ var import_zod53 = require("zod");
 var QUESTION_SET_VERSION = "0.1";
 var INTAKE_FIELD_NAME_PREFIX = "Intake: ";
 function deriveFieldKey(fieldName) {
-  const slug2 = fieldName.toLowerCase().replace(/[^a-z0-9 ]+/g, "").replace(/ /g, "_");
-  return `contact.${slug2}`;
+  const slug3 = fieldName.toLowerCase().replace(/[^a-z0-9 ]+/g, "").replace(/ /g, "_");
+  return `contact.${slug3}`;
 }
 function intakeFieldName(label) {
   return `${INTAKE_FIELD_NAME_PREFIX}${label}`;
@@ -10225,6 +10225,101 @@ function buildIntakeFormData(opts) {
   };
 }
 
+// src/intake-to-build/plan-form.ts
+function slug2(s) {
+  return s.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).join("_");
+}
+function humanizeKey(key) {
+  return key.split(/[^a-z0-9]+/i).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function buildPlanStandardField(key, required) {
+  const isEmail = key === "email";
+  const isPhone = key === "phone";
+  const label = humanizeKey(key);
+  const base = {
+    fieldWidthPercentage: 100,
+    hiddenFieldQueryKey: key,
+    label,
+    placeholder: label,
+    required,
+    standard: true,
+    tag: key,
+    type: isEmail ? "email" : "text",
+    typeLabel: isEmail ? "Email" : isPhone ? "Phone" : "Text"
+  };
+  if (isPhone) base.enableCountryPicker = false;
+  return base;
+}
+function buildPlanCustomField(record, required, locationId2, position) {
+  const type = formFieldType(record.dataType);
+  const field = {
+    Id: record.id,
+    id: record.id,
+    tag: record.id,
+    active: false,
+    allowCustomOption: false,
+    customFieldLabel: record.name,
+    dataType: record.dataType,
+    dateAdded: record.dateAdded ?? "",
+    description: "",
+    documentType: "field",
+    edit: false,
+    fieldKey: record.fieldKey,
+    fieldWidthPercentage: 100,
+    fieldsCount: 0,
+    hiddenFieldQueryKey: slug2(record.name),
+    label: record.name,
+    locationId: locationId2,
+    model: record.model ?? "contact",
+    name: record.name,
+    parentId: record.parentId ?? "",
+    placeholder: "",
+    position,
+    required,
+    showInForms: true,
+    standard: false,
+    type
+  };
+  const options = record.picklistOptions ?? void 0;
+  if (type === "single_options" || type === "multiple_options" || type === "checkbox") {
+    field.picklistOptions = options ? [...options] : [];
+  }
+  if (type === "multiple_options") {
+    field.calculatedOptions = (options ?? []).map((label) => ({ calculatedValue: "", label }));
+    field.category = "choiceElements";
+    field.typeLabel = "Multi Dropdown";
+  }
+  if (type === "phone") field.enableCountryPicker = false;
+  return field;
+}
+function buildPlanFormData(fields, locationId2) {
+  const out = [];
+  let position = 0;
+  for (const f of fields) {
+    if (f.kind === "standard") {
+      out.push(buildPlanStandardField(f.key, f.required));
+    } else {
+      out.push(buildPlanCustomField(f.record, f.required, locationId2, position += 50));
+    }
+  }
+  out.push(buildSubmitButton("Submit"));
+  return {
+    autoResponder: false,
+    emailNotifications: false,
+    form: {
+      fields: out,
+      formLabelVisible: true,
+      formAction: {
+        actionType: "2",
+        headerImageSrc: "",
+        mobileHeaderImageSrc: "",
+        redirectUrl: "",
+        thankyouText: "<p style='text-align:center;margin:0;'>Thanks! We received your submission.</p>"
+      }
+    }
+  };
+}
+
 // src/intake-to-build/brief.ts
 var import_zod51 = require("zod");
 var BRIEF_SCHEMA_VERSION = "0.1";
@@ -10777,6 +10872,26 @@ function checkRefIntegrity(plan, defined) {
   for (const b of plan.buildOrder ?? []) checkMaybeWildcard(b, "buildOrder");
   return { errors, scanned };
 }
+var KNOWN_STANDARD_FORM_KEYS = /* @__PURE__ */ new Set([
+  "first_name",
+  "last_name",
+  "name",
+  "full_name",
+  "email",
+  "phone",
+  "address1",
+  "address",
+  "city",
+  "state",
+  "postal_code",
+  "country",
+  "website",
+  "organization",
+  "company_name",
+  "date_of_birth",
+  "contact_source",
+  "source"
+]);
 function validateBuildPlan(input) {
   const parsed = buildPlanSchema.safeParse(input);
   if (!parsed.success) {
@@ -10806,7 +10921,39 @@ function validateBuildPlan(input) {
       seen.add(key);
     }
   }
+  const nameGroups = [
+    ["pipelines", (plan.pipelines ?? []).map((x) => ({ ref: x.ref, name: x.name }))],
+    ["customFields", (plan.customFields ?? []).map((x) => ({ ref: x.ref, name: x.name }))],
+    ["tags", (plan.tags ?? []).map((x) => ({ ref: x.ref, name: x.name }))],
+    ["customValues", (plan.customValues ?? []).map((x) => ({ ref: x.ref, name: x.name }))],
+    ["calendars", (plan.calendars ?? []).map((x) => ({ ref: x.ref, name: x.name }))],
+    ["forms", (plan.forms ?? []).map((x) => ({ ref: x.ref, name: x.name }))],
+    ["funnels", (plan.funnels ?? []).map((x) => ({ ref: x.ref, name: x.name }))]
+  ];
+  for (const [type, objs] of nameGroups) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const o of objs) {
+      const key = o.name.trim().toLowerCase();
+      const prev = seen.get(key);
+      if (prev) {
+        allErrors.push(
+          `${type} "${o.ref}" and "${prev}" share the name "${o.name}" \u2014 names must be unique within a type (the executor binds same-named objects by name, so duplicates would collapse onto one real id)`
+        );
+      } else {
+        seen.set(key, o.ref);
+      }
+    }
+  }
   const warnings = [];
+  for (const fm of plan.forms ?? []) {
+    for (const fl of fm.fields) {
+      if (fl.type === "standard" && !KNOWN_STANDARD_FORM_KEYS.has(fl.key.trim().toLowerCase())) {
+        warnings.push(
+          `forms "${fm.ref}" standard field key "${fl.key}" is not a recognized GHL standard contact field \u2014 GHL may not save it; if this is custom data, define a custom field and reference it with a custom fieldRef`
+        );
+      }
+    }
+  }
   for (const p of plan.pipelines ?? []) {
     const positions = p.stages.map((s) => s.position).sort((a, b) => a - b);
     const expected = positions.every((pos, idx) => pos === idx);
@@ -11465,6 +11612,61 @@ async function executeBackbone(plan, deps, opts = {}) {
     idMap[cal.ref] = verified.id;
     built.push({ ref: cal.ref, type: "calendar", name: cal.name, status: "created", realId: verified.id });
   }
+  let cfRecords;
+  for (const form of plan.forms ?? []) {
+    let forms;
+    try {
+      forms = await deps.listForms();
+    } catch (e) {
+      return halt(form.ref, "form", `could not read existing forms: ${msg(e)}`);
+    }
+    const matches = forms.filter((f) => norm2(f.name) === norm2(form.name));
+    if (matches.length > 1) {
+      return halt(form.ref, "form", `${matches.length} existing forms are named "${form.name}" \u2014 ambiguous, cannot safely bind ${form.ref}. Resolve the duplicate in GHL, then re-run.`);
+    }
+    if (matches.length === 1) {
+      idMap[form.ref] = matches[0].id;
+      built.push({ ref: form.ref, type: "form", name: form.name, status: "existing", realId: matches[0].id });
+      continue;
+    }
+    if (!cfRecords) {
+      try {
+        cfRecords = await deps.listCustomFieldRecords();
+      } catch (e) {
+        return halt(form.ref, "form", `could not read custom fields to resolve form refs: ${msg(e)}`);
+      }
+    }
+    const byId = new Map(cfRecords.map((r) => [r.id, r]));
+    const resolved = [];
+    let fieldHalt2;
+    for (const ff of form.fields) {
+      if (ff.type === "standard") {
+        resolved.push({ kind: "standard", key: ff.key, required: ff.required ?? false });
+        continue;
+      }
+      const realId = idMap[ff.fieldRef];
+      if (!realId) {
+        fieldHalt2 = halt(form.ref, "form", `form "${form.name}" references ${ff.fieldRef} but that custom field was not built/resolved \u2014 cannot build the form`);
+        break;
+      }
+      const rec = byId.get(realId);
+      if (!rec) {
+        fieldHalt2 = halt(form.ref, "form", `custom field ${ff.fieldRef} (id ${realId}) not found in this account when building form "${form.name}"`);
+        break;
+      }
+      resolved.push({ kind: "custom", record: rec, required: ff.required ?? false });
+    }
+    if (fieldHalt2) return fieldHalt2;
+    let formId;
+    try {
+      formId = await deps.createForm(form.name, resolved);
+    } catch (e) {
+      return halt(form.ref, "form", `create failed: ${msg(e)}`);
+    }
+    if (!formId) return halt(form.ref, "form", "form create returned no id");
+    idMap[form.ref] = formId;
+    built.push({ ref: form.ref, type: "form", name: form.name, status: "created", realId: formId });
+  }
   return { ok: true, idMap, built, manual, deferred: deferredSections(plan) };
 }
 async function buildSimple(objects, type, list, create, nameOf, pollForNew, idMap, built) {
@@ -11501,7 +11703,6 @@ async function buildSimple(objects, type, list, create, nameOf, pollForNew, idMa
 }
 function deferredSections(plan) {
   const out = [];
-  if (plan.forms?.length) out.push({ section: "forms", count: plan.forms.length });
   if (plan.funnels?.length) out.push({ section: "funnels", count: plan.funnels.length });
   if (plan.workflows?.length) out.push({ section: "workflows", count: plan.workflows.length });
   return out;
@@ -11700,6 +11901,64 @@ ${text2.slice(0, 300)}`);
         locationId2
       );
       await client.post("/calendars/", { body, noRetry: true });
+    },
+    // Paginate the form list: a single limit:100 page would miss the target (or
+    // an orphan) form on accounts with many forms, breaking NEVER-CLOBBER (the
+    // executor would create a duplicate). Mirrors the update_form name-lookup scan.
+    listForms: async () => {
+      const out = [];
+      const pageSize = 100;
+      const maxForms = 5e3;
+      for (let skip = 0; skip < maxForms; skip += pageSize) {
+        const page = pickObjects(await client.get("/forms/", { params: { locationId: locationId2, limit: pageSize, skip } }), ["forms"]);
+        out.push(...page);
+        if (page.length < pageSize) break;
+      }
+      return out;
+    },
+    listCustomFieldRecords: async () => parseCustomFields(await client.get(`/locations/${locationId2}/customFields`)),
+    createForm: async (name, fields) => {
+      const formData = buildPlanFormData(fields, locationId2);
+      const createResult = await formApiRequest(builderClient, "POST", `/?locationId=${locationId2}`, {
+        name,
+        locationId: locationId2,
+        formData: { form: { fields: [], formLabelVisible: true } }
+      });
+      const formId = extractFormId(createResult);
+      if (!formId) {
+        throw new Error(`create_form returned no id: ${JSON.stringify(createResult).slice(0, 200)}`);
+      }
+      try {
+        for (let attempt = 1; ; attempt++) {
+          try {
+            await formApiRequest(builderClient, "POST", `/${formId}?locationId=${locationId2}`, { name, formData });
+            break;
+          } catch (saveErr) {
+            if (isFormNotYetPropagated(saveErr) && attempt < 6) {
+              await sleep2(700 * attempt);
+              continue;
+            }
+            throw saveErr;
+          }
+        }
+        let persisted = 0;
+        for (let attempt = 1; attempt <= 6; attempt++) {
+          const verify = await formApiRequest(builderClient, "GET", `/${formId}?locationId=${locationId2}`);
+          persisted = countFormFields(verify);
+          if (persisted > 0) break;
+          if (attempt < 6) await sleep2(700 * attempt);
+        }
+        if (persisted === 0) {
+          throw new Error(`form "${name}" was created (${formId}) but no fields persisted after save (read-after-write); not binding`);
+        }
+        return formId;
+      } catch (err) {
+        try {
+          await formApiRequest(builderClient, "DELETE", `/${formId}?locationId=${locationId2}`);
+        } catch {
+        }
+        throw err;
+      }
     }
   };
 }
@@ -11758,7 +12017,7 @@ function registerIntakeToBuildTools(server2, client, builderClient) {
   );
   server2.tool(
     "apply_build_plan",
-    `Take an APPROVED Blueprint \xA75 build plan + the CURRENT confirmed sub-account and build it. mode:"dry_run" (default) writes NOTHING \u2014 it resolves refs, expands each workflow's logical actions to native GHL JSON, runs the NEVER-CLOBBER existing-asset scan, and returns a two-part report. Run it FIRST. mode:"execute" performs LIVE writes for the CRM backbone (pipelines+stages, custom fields, tags, custom values) AND calendars: never clobbers (same-named objects are bound to their existing id, never modified), verifies each create by read-back before resolving its ref, halts on the first failure returning the partial idMap, and is idempotent (re-run = no-op). Staff-requiring calendars (round_robin etc.) auto-build only when you are the sole account user (auto-assigns you as the team member); with 0 or 2+ users they're surfaced as a manual step, not auto-staffed to a guess. Forms/funnels/workflows are surfaced as manual next steps, not auto-built yet. Always confirms the active location and validates the plan before any write.`,
+    `Take an APPROVED Blueprint \xA75 build plan + the CURRENT confirmed sub-account and build it. mode:"dry_run" (default) writes NOTHING \u2014 it resolves refs, expands each workflow's logical actions to native GHL JSON, runs the NEVER-CLOBBER existing-asset scan, and returns a two-part report. Run it FIRST. mode:"execute" performs LIVE writes for the CRM backbone (pipelines+stages, custom fields, tags, custom values), calendars, AND forms: never clobbers (same-named objects are bound to their existing id, never modified), verifies each create by read-back before resolving its ref, halts on the first failure returning the partial idMap, and is idempotent (re-run = no-op). Staff-requiring calendars (round_robin etc.) auto-build only when you are the sole account user (auto-assigns you as the team member); with 0 or 2+ users they're surfaced as a manual step, not auto-staffed to a guess. Forms build with their standard + custom fields (custom fieldRefs resolve to the real fields created earlier in the run). Funnels/workflows are surfaced as manual next steps, not auto-built yet. Always confirms the active location and validates the plan before any write.`,
     {
       plan: import_zod53.z.record(import_zod53.z.unknown()).describe("The approved \xA75 Build Plan object."),
       mode: import_zod53.z.enum(["dry_run", "execute"]).optional().describe("dry_run (default) = resolve/expand/scan/report, no writes. execute = live writes (not yet enabled)."),
@@ -11851,7 +12110,7 @@ function registerIntakeToBuildTools(server2, client, builderClient) {
             manual: exec.manual,
             idMap: exec.idMap,
             deferred: exec.deferred,
-            deferredNote: "execute builds the CRM backbone (pipelines, custom fields, tags, custom values) and calendars live. Staff-requiring calendars (round_robin etc.) auto-build only when you are the sole user; otherwise they're listed under manual steps. Forms/funnels/workflows are planned but NOT auto-built yet \u2014 create them via the GHL UI or the dedicated tools, in this order: forms \u2192 funnels \u2192 workflows.",
+            deferredNote: "execute builds the CRM backbone (pipelines, custom fields, tags, custom values), calendars, and forms live. Staff-requiring calendars (round_robin etc.) auto-build only when you are the sole user; otherwise they're listed under manual steps. Funnels/workflows are planned but NOT auto-built yet \u2014 create them via the GHL UI or the dedicated tools, in this order: funnels \u2192 workflows.",
             nextManualSteps: [...calendarManualLines, ...manualLines, ...handoffLines],
             summary: exec.ok ? `Built ${exec.built.filter((b) => b.status === "created").length} new object(s), bound ${exec.built.filter((b) => b.status === "existing").length} existing.${exec.manual.length ? ` ${exec.manual.length} calendar(s) need manual staff assignment.` : ""}${exec.deferred.length ? " Deferred: " + exec.deferred.map((d) => `${d.count} ${d.section}`).join(", ") + " (manual)." : ""}` : `HALTED at ${exec.halted?.atRef} (${exec.halted?.reason}). ${exec.built.length} object(s) were created before the halt \u2014 see idMap to resume or clean up. NEVER-CLOBBER means a re-run will bind those, not duplicate them.`
           });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.38.0",
+  "version": "3.39.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",