@elitedcs/ghl-mcp 3.28.0 → 3.29.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 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

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.28.0",
+      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
@@ -1958,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);
@@ -4914,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
         }
       });
     }
@@ -4938,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 });
     }
   );
 }
@@ -5135,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) {

package/package.json

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