@elitedcs/ghl-mcp 3.27.2 → 3.29.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 3.29.0 — Documents & Contracts API fix + workflow/contact bug fixes
+
+Five confirmed bugs fixed, verified live against the GHL API.
+
+**Documents & Contracts (the big one).** The document tools were hitting a
+non-existent `/documents/` path and returning 404. GHL's real Documents &
+Contracts API lives under `/proposals/*`:
+
+- `list_documents` now calls `GET /proposals/document` with real filters:
+  `status` (draft/sent/viewed/completed/declined), `paymentStatus`, `query`,
+  `dateFrom`/`dateTo`, and pagination (`limit` capped at GHL's max of 21, `skip`).
+- `get_document` resolves a document by id by scanning the list (GHL exposes no
+  public get-by-id route).
+- `send_document` now calls `POST /proposals/document/send` to dispatch an
+  existing document to its recipients.
+- `delete_document` reports honestly that GHL's public API has no delete/void
+  route (do it in the UI) instead of failing on a dead path.
+- **New:** `list_document_templates` (`GET /proposals/templates`) lists your
+  reusable contract templates.
+- **New:** `send_document_template` (`POST /proposals/templates/send`) creates
+  and sends a contract to a contact from a template.
+
+**Workflow triggers.** `get_workflow_full` and `update_workflow_actions` no
+longer crash on the Documents & Contracts trigger (`proposal_estimate_update`,
+`masterType: "internal"`). The trigger union now accepts any `masterType` so
+reads never throw, and `proposal_estimate_update` has typed support.
+
+**Workflow settings preserved.** `update_workflow_actions` previously reset
+`allowMultiple`, `stopOnResponse`, `autoMarkAsRead`,
+`removeContactFromLastStep`, and `allowMultipleOpportunity` to defaults on every
+save. It now preserves the workflow's current values, and exposes all five as
+optional parameters.
+
+**Contact search.** `search_contacts` now advances pages correctly (sends both
+`startAfter` and `startAfterId` cursors), and uses the correct sort parameters:
+`order` (asc/desc) instead of the rejected `sortOrder`, with `sortBy` limited to
+`date_added`/`date_updated`.
+
+## 3.28.0 — Tool allowlist (issue #1): cut context cost on big installs
+
+Two new optional env vars let you gate which tools register at startup so
+unused schemas never load into context. Closes [issue #1](https://github.com/drjerryrelth/ghl-command-feedback/issues/1).
+
+**New env vars (both optional, both default-empty):**
+
+- `GHL_ENABLED_MODULES` — comma-separated module names to register
+  (e.g. `contacts,conversations,locations,custom-objects`).
+- `GHL_ENABLED_TOOLS` — comma-separated tool names to register
+  (e.g. `search_contacts,get_contact,update_custom_value`).
+
+**Filter precedence:**
+
+- Neither set → every tool registers (backward compatible).
+- Modules only → tools in those modules register.
+- Tools only → those exact tool names register.
+- Both set → UNION (a tool registers if its module is enabled OR its
+  name is explicitly listed).
+
+**Always-on tools** never get filtered out, so setup and recovery still
+work even with a heavily-restricted allowlist:
+`setup_ghl_mcp`, `request_license`, `get_mcp_version`,
+`auto_capture_firebase_script`, `enable_workflow_builder`, `health_check`.
+
+**Validation + logging:**
+
+- Whitespace and commas both work as separators. Matching is case-insensitive.
+- Unrecognized names log a one-line WARNING to stderr and are ignored
+  (startup never aborts).
+- When the allowlist is active, startup logs one summary:
+  `Tool allowlist active: registered N of M tools (modules=[...]; explicit-tools=[...])`.
+- When unset, zero extra noise — existing logs are unchanged.
+
+**Motivation (from the issue):** running 25+ registered locations with
+all 212 tools registered burned tokens on every message in chats that
+didn't need GHL. Now buyers can restrict the surface to the modules
+they actually use.
+
 ## 3.27.2 — Fix license metadata: MIT → Proprietary
 
 Metadata-only release. Corrects the npm package's stated license, which

package/README.md

@@ -709,9 +709,48 @@ Source repo is private. Contributors need an invitation from `drjerryrelth`. The
 | `GHL_USER_ID` | No* | Your GHL user ID. Required for workflow builder tools. |
 | `GHL_FIREBASE_API_KEY` | No* | Firebase API key from GHL's auth system. Required for workflow builder tools. |
 | `GHL_FIREBASE_REFRESH_TOKEN` | No* | Firebase refresh token. Required for workflow builder tools. May rotate periodically. |
+| `GHL_ENABLED_MODULES` | No | Comma-separated module names to limit which tool groups register at startup (e.g. `contacts,conversations,locations`). Unset = every module registers (default). See "Reducing context / token usage" below. |
+| `GHL_ENABLED_TOOLS` | No | Comma-separated individual tool names to register (e.g. `search_contacts,get_contact,update_custom_value`). Set alongside `GHL_ENABLED_MODULES` to add specific tools on top of whole-module enables. |
 
 *Required only for the workflow builder (internal API) tools. The standard API tools work without these.
 
+### Reducing context / token usage
+
+Every registered MCP tool's schema is shipped to the model on every message. With 212 tools that's a meaningful per-message context cost even in chats that never touch GHL. If you only use a slice of GHL Command, restrict the tool surface with `GHL_ENABLED_MODULES` and/or `GHL_ENABLED_TOOLS`:
+
+```jsonc
+// Claude Desktop config — enable whole modules
+"env": {
+  "GHL_API_KEY": "pit-...",
+  "GHL_LOCATION_ID": "...",
+  "GHL_ENABLED_MODULES": "contacts,conversations,locations,custom-objects"
+}
+```
+
+```jsonc
+// Or pin to individual tools
+"env": {
+  "GHL_API_KEY": "pit-...",
+  "GHL_LOCATION_ID": "...",
+  "GHL_ENABLED_TOOLS": "search_contacts,get_contact,update_custom_value"
+}
+```
+
+Rules of the road:
+
+- **Neither set → every tool registers** (default, backward compatible — your existing config keeps working unchanged).
+- **`GHL_ENABLED_MODULES` only** → register tools in those modules.
+- **`GHL_ENABLED_TOOLS` only** → register only those exact tool names.
+- **Both set** → register the **union**: a tool registers if its module is in `GHL_ENABLED_MODULES` OR its name is in `GHL_ENABLED_TOOLS`. (Whole modules plus a few extra tools.)
+- Whitespace and commas both work as separators. Matching is case-insensitive.
+- Always-on tools register regardless of the allowlist so setup and recovery still work: `setup_ghl_mcp`, `request_license`, `get_mcp_version`, `auto_capture_firebase_script`, `enable_workflow_builder`, `health_check`.
+- Unrecognized module/tool names log a one-line WARNING to stderr and are ignored. Startup never aborts.
+- On startup with the allowlist active, the server logs one summary line: `Tool allowlist active: registered N of M tools (...)`.
+
+**Valid module names** (use these in `GHL_ENABLED_MODULES`):
+
+`contacts`, `conversations`, `opportunities`, `calendars`, `locations`, `workflows`, `funnels`, `forms`, `surveys`, `payments`, `products`, `invoices`, `campaigns`, `users`, `media`, `social-planner`, `courses`, `businesses`, `blogs`, `emails`, `trigger-links`, `custom-objects`, `associations`, `estimates`, `coupons`, `webhooks`, `documents`, `bulk-operations`, `account-export`, `template-deployer`, `workflow-builder`, `funnel-builder`, `form-builder`, `pipeline-builder`, `workflow-cloner`, `smart-lists`, `reputation`, `email-campaigns`, `email-builder`, `memberships`, `validators`, `diagnostics`, `location-switcher`
+
 ---
 
 ## Troubleshooting

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.27.2",
+      version: "3.29.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
       description: "GoHighLevel MCP Server for Claude. 212 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
@@ -682,7 +682,11 @@ var TriggerCommonSchema = import_zod3.z.object({
   origin_id: import_zod3.z.string().optional(),
   active: import_zod3.z.boolean().optional(),
   workflow_id: import_zod3.z.string().optional(),
-  masterType: import_zod3.z.literal("highlevel").optional(),
+  // Most native GHL triggers report masterType "highlevel", but some
+  // first-party features use other values (e.g. Documents & Contracts uses
+  // "internal"). Accept any string so reads never crash on the masterType
+  // discriminator and writes round-trip the original value unchanged.
+  masterType: import_zod3.z.string().optional(),
   name: import_zod3.z.string().optional(),
   actions: import_zod3.z.array(TriggerActionSchema).optional(),
   schedule_config: import_zod3.z.record(import_zod3.z.unknown()).optional(),
@@ -987,6 +991,19 @@ var CustomObjectChangedTriggerSchema = TriggerCommonSchema.extend({
 });
 var ConvAiTriggerTriggerSchema = typedTrigger("conv_ai_trigger", [], "fieldless");
 var ConvAiAutonomousTriggerTriggerSchema = typedTrigger("conv_ai_autonomous_trigger", [], "fieldless");
+var ProposalEstimateUpdateTriggerSchema = TriggerCommonSchema.extend({
+  type: import_zod3.z.literal("proposal_estimate_update"),
+  conditions: import_zod3.z.array(import_zod3.z.object({
+    operator: import_zod3.z.string().optional(),
+    field: import_zod3.z.string().optional().describe(
+      "Documents & Contracts filter. Common fields: a document/estimate status path (values like sent, viewed, signed, completed, declined) and the document/template id. Exact field paths are not fully captured \u2014 pass through whatever the GHL UI shows."
+    ),
+    value: import_zod3.z.unknown().optional(),
+    title: import_zod3.z.string().optional(),
+    type: import_zod3.z.string().optional(),
+    id: import_zod3.z.string().optional()
+  }).passthrough()).optional()
+});
 var UnknownTriggerSchema = TriggerCommonSchema.extend({
   type: import_zod3.z.string(),
   conditions: import_zod3.z.array(import_zod3.z.record(import_zod3.z.unknown())).optional()
@@ -1046,6 +1063,7 @@ var WorkflowTriggerSchema = import_zod3.z.union([
   OrderSubmissionTriggerSchema,
   ConvAiTriggerTriggerSchema,
   ConvAiAutonomousTriggerTriggerSchema,
+  ProposalEstimateUpdateTriggerSchema,
   CustomObjectCreatedTriggerSchema,
   CustomObjectChangedTriggerSchema,
   FacebookLeadGenTriggerSchema,
@@ -1635,11 +1653,14 @@ ${errorBody}`
       version: current.version,
       dataVersion: current.dataVersion ?? 1,
       timezone: current.timezone ?? "account",
-      stopOnResponse: false,
-      allowMultiple: false,
-      allowMultipleOpportunity: false,
-      autoMarkAsRead: false,
-      removeContactFromLastStep: true,
+      // Preserve the workflow's existing settings unless explicitly overridden.
+      // These were previously hardcoded, which silently reset re-enrollment
+      // (allowMultiple) and other toggles on every action update.
+      stopOnResponse: updates.stopOnResponse ?? current.stopOnResponse ?? false,
+      allowMultiple: updates.allowMultiple ?? current.allowMultiple ?? false,
+      allowMultipleOpportunity: updates.allowMultipleOpportunity ?? current.allowMultipleOpportunity ?? false,
+      autoMarkAsRead: updates.autoMarkAsRead ?? current.autoMarkAsRead ?? false,
+      removeContactFromLastStep: updates.removeContactFromLastStep ?? current.removeContactFromLastStep ?? true,
       workflowData: { templates: linkedActions },
       updatedBy: this.userId,
       // Triggers live in Firestore and are managed out-of-band; the workflow
@@ -1776,6 +1797,89 @@ ${errorBody}`
   }
 };
 
+// src/tools/tool-filter.ts
+var ALWAYS_ON_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "setup_ghl_mcp",
+  "request_license",
+  "get_mcp_version",
+  "auto_capture_firebase_script",
+  "enable_workflow_builder",
+  "health_check"
+]);
+function parseList(raw) {
+  if (raw === void 0) return null;
+  const items = raw.split(/[,\s]+/).map((x) => x.trim().toLowerCase()).filter((x) => x.length > 0);
+  return items.length > 0 ? items : null;
+}
+function parseAllowlist(env) {
+  const moduleList = parseList(env.GHL_ENABLED_MODULES);
+  const toolList = parseList(env.GHL_ENABLED_TOOLS);
+  return {
+    enabledModules: moduleList ? new Set(moduleList) : null,
+    enabledTools: toolList ? new Set(toolList) : null,
+    rawModuleInput: moduleList,
+    rawToolInput: toolList
+  };
+}
+function isAllowlistActive(config3) {
+  return config3.enabledModules !== null || config3.enabledTools !== null;
+}
+function shouldRegister(toolName, moduleName, config3) {
+  if (ALWAYS_ON_TOOL_NAMES.has(toolName)) return true;
+  if (!isAllowlistActive(config3)) return true;
+  const toolLower = toolName.toLowerCase();
+  const moduleLower = moduleName.toLowerCase();
+  const moduleEnabled = config3.enabledModules?.has(moduleLower) ?? false;
+  const toolEnabled = config3.enabledTools?.has(toolLower) ?? false;
+  return moduleEnabled || toolEnabled;
+}
+function wrapServerForModule(realServer, moduleName, config3, attemptedTools, registeredTools) {
+  return new Proxy(realServer, {
+    get(target, prop, receiver) {
+      if (prop === "tool") {
+        return (name, ...rest) => {
+          attemptedTools.add(name);
+          if (!shouldRegister(name, moduleName, config3)) {
+            return void 0;
+          }
+          registeredTools.add(name);
+          return target.tool(name, ...rest);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+function validateAndLog(config3, knownModules, attemptedTools, registeredTools, log = (m) => process.stderr.write(m)) {
+  if (!isAllowlistActive(config3)) return;
+  if (config3.rawModuleInput) {
+    const knownLower = new Set([...knownModules].map((m) => m.toLowerCase()));
+    const unknown = config3.rawModuleInput.filter((m) => !knownLower.has(m));
+    if (unknown.length > 0) {
+      log(
+        `[ghl-mcp] WARNING: GHL_ENABLED_MODULES has unrecognized name(s): ${unknown.join(", ")}. Known modules: ${[...knownModules].sort().join(", ")}.
+`
+      );
+    }
+  }
+  if (config3.rawToolInput) {
+    const attemptedLower = new Set([...attemptedTools].map((t) => t.toLowerCase()));
+    const unknown = config3.rawToolInput.filter((t) => !attemptedLower.has(t));
+    if (unknown.length > 0) {
+      log(
+        `[ghl-mcp] WARNING: GHL_ENABLED_TOOLS has unrecognized name(s): ${unknown.join(", ")}.
+`
+      );
+    }
+  }
+  const moduleSummary = config3.enabledModules && config3.enabledModules.size > 0 ? `modules=[${[...config3.enabledModules].sort().join(",")}]` : "modules=(none)";
+  const toolSummary = config3.enabledTools && config3.enabledTools.size > 0 ? `explicit-tools=[${[...config3.enabledTools].sort().join(",")}]` : "explicit-tools=(none)";
+  log(
+    `[ghl-mcp] Tool allowlist active: registered ${registeredTools.size} of ${attemptedTools.size} tools (${moduleSummary}; ${toolSummary}).
+`
+  );
+}
+
 // src/tools/contacts.ts
 var import_zod6 = require("zod");
 
@@ -1875,20 +1979,25 @@ function registerContactTools(server2, client) {
       locationId: import_zod6.z.string().optional().describe("GHL Location ID. Optional if GHL_LOCATION_ID is set in env."),
       query: import_zod6.z.string().optional().describe("Search query to filter contacts (searches name, email, phone, etc.)."),
       limit: import_zod6.z.number().optional().describe("Maximum number of contacts to return. Defaults to 20."),
-      startAfterId: import_zod6.z.string().optional().describe("Contact ID to start after, for cursor-based pagination."),
-      sortBy: import_zod6.z.string().optional().describe("Field to sort results by (e.g. 'dateAdded', 'name')."),
-      sortOrder: import_zod6.z.string().optional().describe("Sort direction: 'asc' or 'desc'.")
+      startAfter: import_zod6.z.union([import_zod6.z.number(), import_zod6.z.string()]).optional().describe("Timestamp cursor (ms epoch) from the previous page's meta.startAfter. GHL cursor pagination needs BOTH startAfter and startAfterId to advance \u2014 pass both together."),
+      startAfterId: import_zod6.z.string().optional().describe("Contact ID cursor from the previous page's meta.startAfterId. Use together with startAfter to advance pages."),
+      sortBy: import_zod6.z.enum(["date_added", "date_updated"]).optional().describe("Field to sort by. GHL only accepts snake_case 'date_added' or 'date_updated'."),
+      order: import_zod6.z.enum(["asc", "desc"]).optional().describe("Sort direction: 'asc' or 'desc'. (GHL rejects the legacy 'sortOrder' name \u2014 this maps to the 'order' query param.)")
     },
-    async ({ locationId: locationId2, query, limit, startAfterId, sortBy, sortOrder }) => {
+    async ({ locationId: locationId2, query, limit, startAfter, startAfterId, sortBy, order }) => {
       const resolvedLocationId = client.resolveLocationId(locationId2);
       const raw = await client.get("/contacts/", {
         params: {
           locationId: resolvedLocationId,
           query,
           limit: limit ?? 20,
+          // Cursor pagination requires both the timestamp and the id; the GHL
+          // nextPageUrl always carries both. Passing only startAfterId returns
+          // the same page.
+          startAfter,
           startAfterId,
           sortBy,
-          sortOrder
+          order
         }
       });
       return ContactSearchResponseSchema.parse(raw);
@@ -4831,23 +4940,35 @@ function registerWebhookTools(server2, client) {
 
 // src/tools/documents.ts
 var import_zod32 = require("zod");
+var DOC_PAGE_MAX = 21;
+var DOC_SCAN_MAX_PAGES = 200;
 function registerDocumentTools(server2, client) {
   safeTool(
     server2,
     "list_documents",
-    "List documents and contracts in a GHL location. Supports pagination.",
+    "List Documents & Contracts (sent/draft/completed agreements) in a GHL location. Filter by signature status and payment status. Backed by GET /proposals/document.",
     {
       locationId: import_zod32.z.string().optional().describe("GHL Location ID. Optional if GHL_LOCATION_ID is set in env."),
-      limit: import_zod32.z.number().optional().describe("Maximum documents to return. Defaults to 20."),
-      offset: import_zod32.z.number().optional().describe("Number of records to skip for pagination.")
-    },
-    async ({ locationId: locationId2, limit, offset }) => {
+      status: import_zod32.z.enum(["draft", "sent", "viewed", "completed", "declined", "expired", "voided"]).optional().describe("Filter by document signature status (e.g. 'sent', 'completed', 'draft'). Server-side filter."),
+      paymentStatus: import_zod32.z.string().optional().describe("Filter by payment status (e.g. 'paid', 'pending', 'no_payment')."),
+      query: import_zod32.z.string().optional().describe("Free-text search across document names/recipients."),
+      dateFrom: import_zod32.z.string().optional().describe("Only documents updated on/after this date (ISO 8601)."),
+      dateTo: import_zod32.z.string().optional().describe("Only documents updated on/before this date (ISO 8601)."),
+      limit: import_zod32.z.number().optional().describe("Max documents to return. Defaults to 20. GHL caps this at 21 per page."),
+      skip: import_zod32.z.number().optional().describe("Number of records to skip for pagination.")
+    },
+    async ({ locationId: locationId2, status, paymentStatus, query, dateFrom, dateTo, limit, skip }) => {
       const resolvedLocationId = client.resolveLocationId(locationId2);
-      return client.get(`/documents/`, {
+      return client.get(`/proposals/document`, {
         params: {
           locationId: resolvedLocationId,
-          limit: limit ?? 20,
-          offset
+          status,
+          paymentStatus,
+          query,
+          dateFrom,
+          dateTo,
+          limit: Math.min(limit ?? 20, DOC_PAGE_MAX),
+          skip
         }
       });
     }
@@ -4855,47 +4976,147 @@ function registerDocumentTools(server2, client) {
   safeTool(
     server2,
     "get_document",
-    "Retrieve a single document or contract by its ID, including signature status.",
+    "Retrieve a single Document & Contract by its ID, including signature/payment status and recipients. NOTE: GHL's public API has no get-by-id route, so this scans the documents list (GET /proposals/document) to find a match.",
     {
-      documentId: import_zod32.z.string().describe("The document ID to retrieve."),
+      documentId: import_zod32.z.string().describe("The document ID to retrieve (the document's _id)."),
       locationId: import_zod32.z.string().optional().describe("GHL Location ID. Optional if GHL_LOCATION_ID is set in env.")
     },
     async ({ documentId, locationId: locationId2 }) => {
       const resolvedLocationId = client.resolveLocationId(locationId2);
-      return client.get(`/documents/${documentId}`, {
-        params: { locationId: resolvedLocationId }
-      });
+      let skip = 0;
+      let total = Infinity;
+      let scannedAll = true;
+      for (let page = 0; page < DOC_SCAN_MAX_PAGES && skip < total; page++) {
+        const res = await client.get(`/proposals/document`, {
+          params: { locationId: resolvedLocationId, limit: DOC_PAGE_MAX, skip }
+        });
+        const docs = res?.documents ?? [];
+        if (typeof res?.total === "number") total = res.total;
+        const match = docs.find(
+          (d) => d._id === documentId || d.documentId === documentId || d.id === documentId
+        );
+        if (match) return match;
+        if (docs.length < DOC_PAGE_MAX) break;
+        skip += DOC_PAGE_MAX;
+        if (page === DOC_SCAN_MAX_PAGES - 1 && skip < total) scannedAll = false;
+      }
+      return {
+        found: false,
+        documentId,
+        message: scannedAll ? `No document with id ${documentId} found in location ${resolvedLocationId}. Use list_documents to browse available documents.` : `No document with id ${documentId} found within the first ${DOC_SCAN_MAX_PAGES * DOC_PAGE_MAX} documents scanned. This location has more; narrow the set with list_documents filters (status, query, date range).`
+      };
+    }
+  );
+  safeTool(
+    server2,
+    "send_document",
+    "Send/dispatch an EXISTING Document & Contract to the recipients already on it. To create and send a new contract to a contact, use send_document_template instead. Backed by POST /proposals/document/send.",
+    {
+      documentId: import_zod32.z.string().describe("The document ID to send."),
+      sentBy: import_zod32.z.string().optional().describe("GHL user ID of the sender (required by the API; falls back to GHL_USER_ID env)."),
+      documentName: import_zod32.z.string().optional().describe("Override the document name shown to recipients."),
+      medium: import_zod32.z.string().optional().describe("Delivery medium, e.g. 'email'. Defaults to email."),
+      ccRecipients: import_zod32.z.array(import_zod32.z.record(import_zod32.z.unknown())).optional().describe("Optional CC recipients: [{id, email, contactName, firstName, lastName, imageUrl}]."),
+      notificationSettings: import_zod32.z.record(import_zod32.z.unknown()).optional().describe("Optional sender/receiver notification settings: {sender:{fromName,fromEmail}, receive:{subject,templateId}}."),
+      locationId: import_zod32.z.string().optional().describe("GHL Location ID. Optional if GHL_LOCATION_ID is set in env.")
+    },
+    async ({ documentId, sentBy, documentName, medium, ccRecipients, notificationSettings, locationId: locationId2 }) => {
+      const resolvedLocationId = client.resolveLocationId(locationId2);
+      const resolvedSentBy = sentBy ?? process.env.GHL_USER_ID;
+      if (!resolvedSentBy) {
+        throw new Error(
+          "sentBy (sender user ID) is required. Provide it as a parameter or set GHL_USER_ID in your env."
+        );
+      }
+      const body = {
+        locationId: resolvedLocationId,
+        documentId,
+        sentBy: resolvedSentBy
+      };
+      if (documentName !== void 0) body.documentName = documentName;
+      if (medium !== void 0) body.medium = medium;
+      if (ccRecipients !== void 0) body.ccRecipients = ccRecipients;
+      if (notificationSettings !== void 0) body.notificationSettings = notificationSettings;
+      return client.post(`/proposals/document/send`, { body });
     }
   );
   safeTool(
     server2,
     "delete_document",
-    "Delete a document or contract by ID.",
+    "Delete or void a Document & Contract. NOTE: GHL's public API does NOT support deleting or voiding documents \u2014 this must be done in the GHL UI (Payments \u2192 Documents & Contracts \u2192 the document's \u22EF menu \u2192 Delete/Void). This tool reports that limitation rather than failing silently.",
     {
-      documentId: import_zod32.z.string().describe("The document ID to delete."),
+      documentId: import_zod32.z.string().describe("The document ID you intend to delete/void."),
       locationId: import_zod32.z.string().optional().describe("GHL Location ID. Optional if GHL_LOCATION_ID is set in env.")
     },
-    async ({ documentId, locationId: locationId2 }) => {
+    async ({ documentId }) => {
+      return {
+        supported: false,
+        documentId,
+        message: "GHL's public Documents & Contracts API does not expose a delete or void/recall endpoint. Delete or void this document in the GHL UI: Payments \u2192 Documents & Contracts \u2192 open the document \u2192 \u22EF menu \u2192 Delete or Void."
+      };
+    }
+  );
+  safeTool(
+    server2,
+    "list_document_templates",
+    "List Documents & Contracts TEMPLATES (the reusable contract templates you build, e.g. agreements you send to clients). Backed by GET /proposals/templates.",
+    {
+      locationId: import_zod32.z.string().optional().describe("GHL Location ID. Optional if GHL_LOCATION_ID is set in env."),
+      type: import_zod32.z.string().optional().describe("Filter by template type (e.g. 'proposal')."),
+      name: import_zod32.z.string().optional().describe("Filter by template name (partial match)."),
+      isPublicDocument: import_zod32.z.boolean().optional().describe("Filter for public templates only."),
+      userId: import_zod32.z.string().optional().describe("Filter by the user who created the template."),
+      dateFrom: import_zod32.z.string().optional().describe("Only templates updated on/after this date (ISO 8601)."),
+      dateTo: import_zod32.z.string().optional().describe("Only templates updated on/before this date (ISO 8601)."),
+      limit: import_zod32.z.number().optional().describe("Max templates to return. Defaults to 20."),
+      skip: import_zod32.z.number().optional().describe("Number of records to skip for pagination.")
+    },
+    async ({ locationId: locationId2, type, name, isPublicDocument, userId, dateFrom, dateTo, limit, skip }) => {
       const resolvedLocationId = client.resolveLocationId(locationId2);
-      return client.delete(`/documents/${documentId}`, {
-        params: { locationId: resolvedLocationId }
+      return client.get(`/proposals/templates`, {
+        params: {
+          locationId: resolvedLocationId,
+          type,
+          name,
+          isPublicDocument,
+          userId,
+          dateFrom,
+          dateTo,
+          limit: limit ?? 20,
+          skip
+        }
       });
     }
   );
   safeTool(
     server2,
-    "send_document",
-    "Send a document/contract to a contact for electronic signature.",
+    "send_document_template",
+    "Create and send a new Document & Contract to a contact from a template. This is how you send a contract to someone. Backed by POST /proposals/templates/send.",
     {
-      documentId: import_zod32.z.string().describe("The document ID to send."),
-      contactId: import_zod32.z.string().describe("The contact ID to send the document to."),
+      templateId: import_zod32.z.string().describe("The template ID to send (from list_document_templates)."),
+      contactId: import_zod32.z.string().describe("The contact ID to send the contract to."),
+      userId: import_zod32.z.string().optional().describe("GHL user ID of the sender (required by the API; falls back to GHL_USER_ID env)."),
+      sendDocument: import_zod32.z.boolean().optional().describe("If true (default), actually dispatch the document. If false, only create the draft."),
+      opportunityId: import_zod32.z.string().optional().describe("Optionally link the document to an opportunity."),
       locationId: import_zod32.z.string().optional().describe("GHL Location ID. Optional if GHL_LOCATION_ID is set in env.")
     },
-    async ({ documentId, contactId, locationId: locationId2 }) => {
+    async ({ templateId, contactId, userId, sendDocument, opportunityId, locationId: locationId2 }) => {
       const resolvedLocationId = client.resolveLocationId(locationId2);
-      return client.post(`/documents/${documentId}/send`, {
-        body: { locationId: resolvedLocationId, contactId }
-      });
+      const resolvedUserId = userId ?? process.env.GHL_USER_ID;
+      if (!resolvedUserId) {
+        throw new Error(
+          "userId (sender user ID) is required. Provide it as a parameter or set GHL_USER_ID in your env."
+        );
+      }
+      const body = {
+        templateId,
+        contactId,
+        userId: resolvedUserId,
+        locationId: resolvedLocationId
+      };
+      if (sendDocument !== void 0) body.sendDocument = sendDocument;
+      if (opportunityId !== void 0) body.opportunityId = opportunityId;
+      return client.post(`/proposals/templates/send`, { body });
     }
   );
 }
@@ -5052,15 +5273,25 @@ function registerWorkflowBuilderTools(server2, client) {
       name: import_zod33.z.string().optional().describe("New workflow name."),
       status: import_zod33.z.string().optional().describe("New status: 'draft' or 'published'."),
       actions: import_zod33.z.array(ActionSchema).optional().describe("Array of workflow actions/steps. For linear flows, provide in order \u2014 chaining is automatic."),
-      triggers: import_zod33.z.array(WorkflowTriggerSchema).optional().describe("Array of workflow triggers.")
-    },
-    async ({ workflowId, name, status, actions, triggers }) => {
+      triggers: import_zod33.z.array(WorkflowTriggerSchema).optional().describe("Array of workflow triggers."),
+      allowMultiple: import_zod33.z.boolean().optional().describe("Allow a contact to be enrolled more than once (re-enrollment). If omitted, the workflow's current value is preserved."),
+      stopOnResponse: import_zod33.z.boolean().optional().describe("Stop the workflow when the contact replies. If omitted, the current value is preserved."),
+      autoMarkAsRead: import_zod33.z.boolean().optional().describe("Auto-mark conversations as read. If omitted, the current value is preserved."),
+      removeContactFromLastStep: import_zod33.z.boolean().optional().describe("Remove the contact when they reach the last step. If omitted, the current value is preserved."),
+      allowMultipleOpportunity: import_zod33.z.boolean().optional().describe("Allow creating multiple opportunities. If omitted, the current value is preserved.")
+    },
+    async ({ workflowId, name, status, actions, triggers, allowMultiple, stopOnResponse, autoMarkAsRead, removeContactFromLastStep, allowMultipleOpportunity }) => {
       try {
         const result = await client.updateWorkflow(workflowId, {
           name,
           status,
           actions,
-          triggers
+          triggers,
+          allowMultiple,
+          stopOnResponse,
+          autoMarkAsRead,
+          removeContactFromLastStep,
+          allowMultipleOpportunity
         });
         return jsonResponse(result);
       } catch (error) {
@@ -8602,24 +8833,58 @@ var publicApiTools = [
   [registerAccountExportTools, "account-export"],
   [registerTemplateDeployerTools, "template-deployer"]
 ];
-function registerAllTools(server2, client, registry2, mcpVersion) {
-  for (const [register] of publicApiTools) {
-    register(server2, client);
+var internalApiTools = [
+  [registerWorkflowBuilderTools, "workflow-builder"],
+  [registerFunnelBuilderTools, "funnel-builder"],
+  [registerFormBuilderTools, "form-builder"],
+  [registerPipelineBuilderTools, "pipeline-builder"],
+  [registerWorkflowClonerTools, "workflow-cloner"],
+  [registerSmartListTools, "smart-lists"],
+  [registerReputationTools, "reputation"],
+  [registerEmailCampaignTools, "email-campaigns"],
+  [registerEmailBuilderInternalTools, "email-builder"],
+  [registerMembershipTools, "memberships"]
+];
+var VALIDATORS_MODULE = "validators";
+var DIAGNOSTICS_MODULE = "diagnostics";
+var LOCATION_SWITCHER_MODULE = "location-switcher";
+var KNOWN_MODULES = /* @__PURE__ */ new Set([
+  ...publicApiTools.map(([, label]) => label),
+  ...internalApiTools.map(([, label]) => label),
+  VALIDATORS_MODULE,
+  DIAGNOSTICS_MODULE,
+  LOCATION_SWITCHER_MODULE
+]);
+function registerAllTools(server2, client, registry2, mcpVersion, env = process.env) {
+  const config3 = parseAllowlist(env);
+  const attemptedTools = /* @__PURE__ */ new Set();
+  const registeredTools = /* @__PURE__ */ new Set();
+  const wrap = (moduleName) => wrapServerForModule(server2, moduleName, config3, attemptedTools, registeredTools);
+  for (const [register, moduleName] of publicApiTools) {
+    register(wrap(moduleName), client);
   }
   const builderClient = WorkflowBuilderClient.fromEnv(registry2) ?? WorkflowBuilderClient.fromFirstCompany(registry2);
-  registerWorkflowBuilderTools(server2, builderClient);
-  registerFunnelBuilderTools(server2, builderClient);
-  registerFormBuilderTools(server2, builderClient);
-  registerPipelineBuilderTools(server2, builderClient);
-  registerWorkflowClonerTools(server2, builderClient);
-  registerSmartListTools(server2, builderClient);
-  registerReputationTools(server2, builderClient);
-  registerEmailCampaignTools(server2, builderClient);
-  registerEmailBuilderInternalTools(server2, builderClient);
-  registerMembershipTools(server2, builderClient);
-  registerValidatorTools(server2, client, builderClient);
-  registerDiagnosticTools(server2, mcpVersion ?? "unknown", client, builderClient, registry2 ?? null);
-  registerLocationSwitcherTools(server2, client, builderClient, registry2, mcpVersion);
+  for (const [register, moduleName] of internalApiTools) {
+    register(wrap(moduleName), builderClient);
+  }
+  registerValidatorTools(wrap(VALIDATORS_MODULE), client, builderClient);
+  registerDiagnosticTools(
+    wrap(DIAGNOSTICS_MODULE),
+    mcpVersion ?? "unknown",
+    client,
+    builderClient,
+    registry2 ?? null
+  );
+  registerLocationSwitcherTools(
+    wrap(LOCATION_SWITCHER_MODULE),
+    client,
+    builderClient,
+    registry2,
+    mcpVersion
+  );
+  if (isAllowlistActive(config3)) {
+    validateAndLog(config3, KNOWN_MODULES, attemptedTools, registeredTools);
+  }
 }
 
 // src/attestation.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.27.2",
+  "version": "3.29.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
   "description": "GoHighLevel MCP Server for Claude. 212 tools — full CRM, automation, marketing control, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",