conduyt-mcp 4.13.0 → 4.15.0

package/README.md

@@ -2,7 +2,7 @@
 
 MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-accessible tools. Covers the core CRM surface (contacts, deals, pipelines, custom fields, automations, messaging, and more); use `conduyt_api_catalog` to discover the full set of 500+ REST endpoints.
 
-## 161 Tools
+## 169 Tools
 
 ### Discovery
 | Tool | Description |
@@ -258,6 +258,18 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 | `conduyt_export_contact_data` | GDPR data-portability export — full portable JSON of everything held about a contact (owner/admin) |
 | `conduyt_forget_contact` | IRREVERSIBLE GDPR right-to-be-forgotten erasure — requires `confirm='FORGET'` (owner only) |
 
+### Dialer
+| Tool | Description |
+|------|-------------|
+| `conduyt_sync_local_presence` | Reconcile the Local Presence pool from Twilio (LP-named, voice, US +1, max 50) |
+
+### Lifecycle (master lead status + intake deals)
+| Tool | Description |
+|------|-------------|
+| `conduyt_get_lifecycle_settings` | Effective master statuses (defaults + customs) and intake-deals config |
+| `conduyt_update_intake_deals` | Configure automatic deal creation on live intake (webhooks, forms, bookings) |
+| `conduyt_update_master_statuses` | Set the account's custom lead lifecycle statuses |
+
 ## Setup
 
 ```bash

package/dist/index.js

@@ -35,6 +35,8 @@ import { registerDashboardTools } from "./tools/dashboard.js";
 import { registerAiExtendedTools } from "./tools/ai-extended.js";
 import { registerWorkflowSandboxTools } from "./tools/workflow-sandbox.js";
 import { registerPrivacyTools } from "./tools/privacy.js";
+import { registerAccountExportTools } from "./tools/account-exports.js";
+import { registerLifecycleTools } from "./tools/lifecycle.js";
 const apiUrl = process.env.CONDUYT_API_URL;
 const apiKey = process.env.CONDUYT_API_KEY;
 if (!apiUrl || !apiKey) {
@@ -92,5 +94,7 @@ registerDashboardTools(server, client);
 registerAiExtendedTools(server, client);
 registerWorkflowSandboxTools(server, client);
 registerPrivacyTools(server, client);
+registerAccountExportTools(server, client);
+registerLifecycleTools(server, client);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/account-exports.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConduytClient } from "../client.js";
+/**
+ * Scheduled account exports (Enterprise): settings + run history.
+ *
+ * Listing/downloading full-account export files is account-wide PII egress,
+ * so the /account-exports endpoints require the EXPLICIT 'account-exports'
+ * API-key scope (same posture as 'dnc' — an admin must grant it per key; an
+ * unrestricted key does NOT imply it). The settings endpoints ride the
+ * normal 'settings' scope. File BYTES are not fetched through MCP (a 50k-row
+ * CSV does not belong in a tool result) — tools return metadata plus the
+ * authed downloadPath for the API/CLI to retrieve.
+ */
+export declare function registerAccountExportTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/account-exports.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { formatResult } from "../client.js";
+/**
+ * Scheduled account exports (Enterprise): settings + run history.
+ *
+ * Listing/downloading full-account export files is account-wide PII egress,
+ * so the /account-exports endpoints require the EXPLICIT 'account-exports'
+ * API-key scope (same posture as 'dnc' — an admin must grant it per key; an
+ * unrestricted key does NOT imply it). The settings endpoints ride the
+ * normal 'settings' scope. File BYTES are not fetched through MCP (a 50k-row
+ * CSV does not belong in a tool result) — tools return metadata plus the
+ * authed downloadPath for the API/CLI to retrieve.
+ */
+export function registerAccountExportTools(server, client) {
+    server.tool("conduyt_scheduled_export_get_settings", "Get the account's scheduled-export configuration (enabled, frequency, entities) and whether the Enterprise feature is available on the current plan.", {}, async () => {
+        const result = await client.get("/api/v1/settings/scheduled-export");
+        return formatResult(result);
+    });
+    server.tool("conduyt_scheduled_export_update_settings", "Update scheduled-export settings. Enabling requires an Enterprise plan (403 upsell otherwise). Omitted fields keep their current values. Weekly exports run on Mondays; all exports run in the morning of the account timezone and files are kept 14 days.", {
+        enabled: z.boolean().optional().describe("Turn scheduled exports on/off"),
+        frequency: z.enum(["daily", "weekly"]).optional().describe("How often to export (weekly = Mondays)"),
+        entities: z
+            .array(z.enum(["contacts", "deals", "companies"]))
+            .min(1)
+            .optional()
+            .describe("Which entities to include"),
+    }, async (params) => {
+        const result = await client.patch("/api/v1/settings/scheduled-export", params);
+        return formatResult(result);
+    });
+    server.tool("conduyt_account_exports_list", "List recent scheduled account-export runs with per-file metadata (rows, truncation, size, expiry) and authed downloadPath for each completed file. Requires the explicit 'account-exports' API-key scope. Download the CSV bytes via the API or CLI using downloadPath — not through MCP.", {}, async () => {
+        const result = await client.get("/api/v1/account-exports");
+        return formatResult(result);
+    });
+}

package/dist/tools/calls.js

@@ -46,4 +46,8 @@ export function registerCallTools(server, client) {
         const result = await client.get(`/api/v1/calls/${encodeURIComponent(id)}`);
         return formatResult(result);
     });
+    server.tool("conduyt_sync_local_presence", "Sync the dialer's Local Presence number pool from the account's Twilio subaccount. IMPORTANT — sync only adopts numbers that meet ALL of: (1) the Twilio FriendlyName contains a standalone 'LP' (or 'LocalPres'), e.g. 'LP Miami 305'; (2) the number is voice-capable; (3) it is a US +1 E.164 number. The first 50 matches in sorted order become the pool; anything already in the pool that no longer matches is REMOVED. So buying a number is not enough — name it with the LP convention in Twilio first, then run this. Returns pool/added/removed/matched. Requires settings:edit.", {}, async () => {
+        const result = await client.post("/api/v1/dialer/local-presence/sync", {});
+        return formatResult(result);
+    });
 }

package/dist/tools/contacts.js

@@ -52,7 +52,8 @@ export function registerContactTools(server, client) {
         lastName: z.string().optional().describe("Last name"),
         phone: z.string().optional().describe("Phone number"),
         company: z.string().optional().describe("Company name"),
-        source: z.string().optional().describe("Lead source (e.g. 'website', 'referral', 'import')"),
+        source: z.string().trim().min(1).max(100).optional().describe("Lead source (e.g. 'website', 'referral', 'import') — FIRST-WRITE-WINS acquisition truth for the lead; later inbound events do not overwrite it. 1-100 chars."),
+        masterStatus: z.string().trim().min(1).max(40).optional().describe("Lifecycle status of the LEAD (master record), distinct from any deal's status: 'open' (default), 'won', 'lost', 'abandoned', 'disqualified', or an account-defined custom status. A terminal status (won/lost/abandoned/disqualified) SILENCES all outbound automations for this contact — drips, sequences, and scheduled sends stop. Use conduyt_get_lifecycle_settings to see the account's configured statuses."),
         tags: z.array(z.string()).optional().describe("Tag UUIDs to apply (tags must already exist — create them with conduyt_create_tag first)"),
         customFields: z.record(z.any()).optional().describe("Structured custom-field values keyed by field key, e.g. { lead_temperature: 'hot', budget: 50000 }. Define fields first with conduyt_create_custom_field (entity 'contact')."),
         custom_fields: z.record(z.any()).optional().describe("Alias for customFields (snake_case). Provide only one of customFields / custom_fields."),
@@ -69,6 +70,8 @@ export function registerContactTools(server, client) {
         lastName: z.string().optional().describe("Updated last name"),
         phone: z.string().optional().describe("Updated phone"),
         company: z.string().optional().describe("Updated company name"),
+        source: z.string().trim().min(1).max(100).nullable().optional().describe("Correct the lead's first-touch source (normally first-write-wins and set at creation — update only to FIX bad attribution). Pass null to clear."),
+        masterStatus: z.string().trim().min(1).max(40).optional().describe("Lifecycle status of the LEAD (master record), distinct from any deal's status: 'open' (default), 'won', 'lost', 'abandoned', 'disqualified', or an account-defined custom status. A terminal status (won/lost/abandoned/disqualified) SILENCES all outbound automations for this contact — drips, sequences, and scheduled sends stop. Use conduyt_get_lifecycle_settings to see the account's configured statuses."),
         customFields: z.record(z.any()).optional().describe("Structured custom-field values to merge, keyed by field key. Omit a key to leave it unchanged."),
         custom_fields: z.record(z.any()).optional().describe("Alias for customFields (snake_case). Provide only one of customFields / custom_fields."),
     }, async ({ id, customFields, custom_fields, ...updates }) => {

package/dist/tools/deals.js

@@ -84,6 +84,7 @@ export function registerDealTools(server, client) {
         probability: z.number().min(0).max(1).optional().describe("Win probability as a 0–1 fraction (e.g. 0.75 = 75%)"),
         expectedCloseDate: z.string().optional().describe("Expected close date (ISO 8601, e.g. '2026-09-30')"),
         assignedTo: z.string().optional().describe("Assigned user (owner) UUID"),
+        source: z.string().trim().min(1).max(500).optional().describe("Attribution source for THIS deal — the trigger that produced it (e.g. 'sms-reply', 'booking:demo', 'partner-referral'). Each deal carries its own source; the contact's source stays the first-touch acquisition truth. 1-500 chars."),
         customFields: z.record(z.any()).optional().describe("Structured custom-field values keyed by field key, e.g. { limit_of_indemnity: 5000000, commission_pct: 12.5 }. Define fields first with conduyt_create_custom_field."),
     }, async (params) => {
         const result = await client.post("/api/v1/deals", params);
@@ -102,6 +103,7 @@ export function registerDealTools(server, client) {
         probability: z.number().min(0).max(1).optional().describe("Win probability as a 0–1 fraction (e.g. 0.75 = 75%)"),
         expectedCloseDate: z.string().optional().describe("Expected close date (ISO 8601)"),
         assignedTo: z.string().optional().describe("Reassign to user (owner) UUID"),
+        source: z.string().trim().min(1).max(500).nullable().optional().describe("Attribution source for THIS deal (the trigger that produced it) — distinct from the contact's first-touch source. Pass null to clear it; a blank string is rejected. 1-500 chars."),
         customFields: z.record(z.any()).optional().describe("Structured custom-field values to merge, keyed by field key"),
     }, async ({ id, ...updates }) => {
         const result = await client.patch(`/api/v1/deals/${id}`, updates);

package/dist/tools/lifecycle.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConduytClient } from "../client.js";
+export declare function registerLifecycleTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/lifecycle.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { formatResult } from "../client.js";
+/**
+ * Lifecycle v2 settings (master lead status + intake deals). The master lead
+ * is the acquisition truth (first-write-wins source, one lifecycle status);
+ * deals are per-trigger children with their own source and owner. A terminal
+ * master status silences every outbound automation for that contact.
+ */
+const DEFAULT_MASTER_STATUSES = ["open", "won", "lost", "abandoned", "disqualified"];
+// Mirror of the API's masterStatuses validator (20 names max, 1-40 chars,
+// letters/numbers/spaces/-/_ only) so agent-generated input fails fast here
+// instead of late at the API.
+const masterStatusName = z
+    .string()
+    .trim()
+    .min(1)
+    .max(40)
+    .regex(/^[a-z0-9][a-z0-9 _-]*$/i, "letters, numbers, spaces, - and _ only");
+export function registerLifecycleTools(server, client) {
+    server.tool("conduyt_get_lifecycle_settings", "Read the account's Lifecycle v2 configuration, shaped for read-before-write: masterStatuses.effective is the full list a contact's masterStatus may take (the five built-in defaults plus the account's customs — the raw settings key stores only the customs); intakeDeals is the automatic deal-on-intake config, or null with an intakeDealsNote explaining that null can mean either not-configured or not-visible-to-your-key (the setting is admin-visible; member-tier responses omit it).", {}, async () => {
+        const result = await client.get("/api/v1/settings");
+        const raw = result?.data ?? {};
+        const customs = Array.isArray(raw.masterStatuses)
+            ? raw.masterStatuses.filter((s) => typeof s === "string")
+            : [];
+        // intakeDeals is admin-visible only: member-shaped responses omit it,
+        // and an unconfigured account also lacks it. The two are not
+        // distinguishable from here, so null is reported with a note saying so.
+        const intakeDeals = raw.intakeDeals && typeof raw.intakeDeals === "object" ? raw.intakeDeals : null;
+        const shaped = {
+            masterStatuses: {
+                defaults: DEFAULT_MASTER_STATUSES,
+                customs,
+                effective: [...DEFAULT_MASTER_STATUSES, ...customs.filter((c) => !DEFAULT_MASTER_STATUSES.includes(c.toLowerCase()))],
+            },
+            intakeDeals: intakeDeals ?? null,
+            intakeDealsNote: intakeDeals === null
+                ? "null = not configured, OR your key's role cannot read this admin-visible setting; configure/verify with an admin-tier key"
+                : undefined,
+        };
+        return formatResult({ data: shaped });
+    });
+    server.tool("conduyt_update_intake_deals", "Configure automatic deal creation on LIVE intake (inbound webhook contact upserts, public form submissions, public bookings). When enabled, each ELIGIBLE intake event mints a deal in the chosen pipeline/stage stamped with the trigger's own source. Exclusions that apply even under reInbound 'always': bulk imports never mint, staff/calendar/dialer-created appointments never mint, an exact replay of the same occurrence never mints twice, a same-source event for the same contact+pipeline within 10 minutes is treated as a delivery retry and skipped, and a contact whose masterStatus is terminal (won/lost/abandoned/disqualified) gets no new intake deals. reInbound governs contacts that already exist: 'if_no_open' (default, recommended) also skips when the contact already has an open deal in that pipeline; 'never' mints only for brand-new contacts. Requires settings:edit.", {
+        enabled: z.boolean().describe("Turn automatic intake-deal creation on or off"),
+        pipelineId: z.string().uuid().describe("Pipeline UUID the intake deals land in (conduyt_list_pipelines)"),
+        stageId: z.string().uuid().describe("Starting stage UUID within that pipeline"),
+        reInbound: z
+            .enum(["always", "if_no_open", "never"])
+            .optional()
+            .describe("Policy for contacts that already exist (default 'if_no_open')"),
+    }, async (params) => {
+        const result = await client.patch("/api/v1/settings", { intakeDeals: params });
+        return formatResult(result);
+    });
+    server.tool("conduyt_update_master_statuses", "Set the account's custom lead lifecycle statuses. The five defaults (open, won, lost, abandoned, disqualified) always exist and cannot be removed; this REPLACES the custom list on top of them (max 20 names, 1-40 chars each, letters/numbers/spaces/-/_ only). Terminal statuses stop all outbound automation for a contact. Requires settings:edit.", {
+        statuses: z
+            .array(masterStatusName)
+            .max(20)
+            .describe("Custom status names to make available alongside the defaults, e.g. ['nurturing', 'in underwriting']"),
+    }, async ({ statuses }) => {
+        const result = await client.patch("/api/v1/settings", { masterStatuses: statuses });
+        return formatResult(result);
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "conduyt-mcp",
-  "version": "4.13.0",
-  "description": "MCP server for Conduyt CRM — expose CRM operations as AI-accessible tools",
+  "version": "4.15.0",
+  "description": "MCP server for Conduyt CRM \u2014 expose CRM operations as AI-accessible tools",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -57,4 +57,4 @@
     "tsx": "^4.19.0",
     "@types/node": "^22.0.0"
   }
-}
+}

package/scripts/coverage-manifest.json

@@ -15,6 +15,11 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    {
+      "match": "GET /api/v1/account-exports/:id/files/:entity/download",
+      "status": "excluded",
+      "reason": "raw CSV bytes (up to 50k rows) do not belong in a tool result; conduyt_account_exports_list returns the authed downloadPath for API/CLI retrieval"
+    },
     {
       "match": "/api/v1/auth/",
       "status": "excluded",

package/scripts/coverage-matrix.json

@@ -1,10 +1,10 @@
 {
-  "generatedAt": "2026-07-11T13:24:45.586Z",
-  "toolCount": 162,
-  "totalEndpoints": 814,
+  "generatedAt": "2026-07-29T16:12:55.014Z",
+  "toolCount": 169,
+  "totalEndpoints": 831,
   "counts": {
-    "covered": 151,
-    "excluded": 232,
+    "covered": 157,
+    "excluded": 243,
     "planned": 431,
     "uncategorized": 0
   },
@@ -211,6 +211,16 @@
       "status": "excluded",
       "reason": "email open/click tracking pixels and redirects — recipient-facing"
     },
+    "GET /api/v1/account-exports": {
+      "status": "covered",
+      "tools": [
+        "conduyt_account_exports_list"
+      ]
+    },
+    "GET /api/v1/account-exports/:id/files/:entity/download": {
+      "status": "excluded",
+      "reason": "raw CSV bytes (up to 50k rows) do not belong in a tool result; conduyt_account_exports_list returns the authed downloadPath for API/CLI retrieval"
+    },
     "GET /api/v1/account/readiness": {
       "status": "planned",
       "reason": "account readiness/onboarding surfaces"
@@ -1177,6 +1187,10 @@
         "conduyt_export_contact_data"
       ]
     },
+    "GET /api/v1/contacts/:id/gdpr-export/files/:fileId/download": {
+      "status": "planned",
+      "reason": "contact subroutes beyond the core CRUD/search tools"
+    },
     "POST /api/v1/contacts/:id/gdpr-forget": {
       "status": "covered",
       "tools": [
@@ -1399,6 +1413,10 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    "GET /api/v1/cron/process-external-deletions": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
     "GET /api/v1/cron/process-import-side-effects": {
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
@@ -1407,6 +1425,10 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    "GET /api/v1/cron/process-outbox": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
     "GET /api/v1/cron/process-playbook-steps": {
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
@@ -1443,6 +1465,18 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    "GET /api/v1/cron/reap-qa-tenants": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
+    "GET /api/v1/cron/reconcile-document-sends": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
+    "POST /api/v1/cron/reconcile-document-sends": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
     "GET /api/v1/cron/recurring-tasks": {
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
@@ -1479,6 +1513,18 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    "GET /api/v1/cron/scheduled-account-exports": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
+    "POST /api/v1/cron/scheduled-account-exports": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
+    "GET /api/v1/cron/seat-threshold-alerts": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
     "GET /api/v1/cron/send-scheduled-emails": {
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
@@ -1491,6 +1537,14 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    "GET /api/v1/cron/sync-local-presence": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
+    "POST /api/v1/cron/sync-local-presence": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
     "GET /api/v1/cron/task-reminders": {
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
@@ -1785,6 +1839,12 @@
       "status": "excluded",
       "reason": "realtime browser dialer (WebRTC tokens, live call control) — needs a live audio session"
     },
+    "POST /api/v1/dialer/local-presence/sync": {
+      "status": "covered",
+      "tools": [
+        "conduyt_sync_local_presence"
+      ]
+    },
     "POST /api/v1/dialer/mirror-token": {
       "status": "excluded",
       "reason": "realtime browser dialer (WebRTC tokens, live call control) — needs a live audio session"
@@ -2249,6 +2309,10 @@
       "status": "planned",
       "reason": "import job monitoring/resubmission (ai-import tool covers creation)"
     },
+    "POST /api/v1/imports/upload-url": {
+      "status": "planned",
+      "reason": "import job monitoring/resubmission (ai-import tool covers creation)"
+    },
     "GET /api/v1/imports/users": {
       "status": "planned",
       "reason": "import job monitoring/resubmission (ai-import tool covers creation)"
@@ -2938,12 +3002,17 @@
       ]
     },
     "GET /api/v1/settings": {
-      "status": "planned",
-      "reason": "account settings read/update surfaces"
+      "status": "covered",
+      "tools": [
+        "conduyt_get_lifecycle_settings"
+      ]
     },
     "PATCH /api/v1/settings": {
-      "status": "planned",
-      "reason": "account settings read/update surfaces"
+      "status": "covered",
+      "tools": [
+        "conduyt_update_intake_deals",
+        "conduyt_update_master_statuses"
+      ]
     },
     "GET /api/v1/settings/ai": {
       "status": "planned",
@@ -2997,6 +3066,18 @@
       "status": "planned",
       "reason": "account settings read/update surfaces"
     },
+    "GET /api/v1/settings/scheduled-export": {
+      "status": "covered",
+      "tools": [
+        "conduyt_scheduled_export_get_settings"
+      ]
+    },
+    "PATCH /api/v1/settings/scheduled-export": {
+      "status": "covered",
+      "tools": [
+        "conduyt_scheduled_export_update_settings"
+      ]
+    },
     "GET /api/v1/settings/sms": {
       "status": "planned",
       "reason": "account settings read/update surfaces"