conduyt-mcp 4.19.0 → 4.21.0

package/dist/client.d.ts

@@ -60,3 +60,13 @@ export declare function formatResult(data: unknown): {
         text: string;
     }>;
 };
+/** A tool-level failure (preflight refusals, guard violations): MCP treats a
+ * result without isError as SUCCESS, so refusals must set it explicitly or
+ * clients proceed as if the call happened. */
+export declare function formatToolError(message: string): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};

package/dist/client.js

@@ -253,3 +253,12 @@ export function formatResult(data) {
         content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
     };
 }
+/** A tool-level failure (preflight refusals, guard violations): MCP treats a
+ * result without isError as SUCCESS, so refusals must set it explicitly or
+ * clients proceed as if the call happened. */
+export function formatToolError(message) {
+    return {
+        content: [{ type: "text", text: JSON.stringify({ ok: false, error: message }, null, 2) }],
+        isError: true,
+    };
+}

package/dist/index.js

@@ -38,6 +38,7 @@ import { registerPrivacyTools } from "./tools/privacy.js";
 import { registerAccountExportTools } from "./tools/account-exports.js";
 import { registerLifecycleTools } from "./tools/lifecycle.js";
 import { registerReplyCaptureTools } from "./tools/reply-capture.js";
+import { registerCallFlowTools } from "./tools/call-flows.js";
 const apiUrl = process.env.CONDUYT_API_URL;
 const apiKey = process.env.CONDUYT_API_KEY;
 if (!apiUrl || !apiKey) {
@@ -98,5 +99,6 @@ registerPrivacyTools(server, client);
 registerAccountExportTools(server, client);
 registerLifecycleTools(server, client);
 registerReplyCaptureTools(server, client);
+registerCallFlowTools(server, client);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/call-flows.d.ts

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

package/dist/tools/call-flows.js

@@ -0,0 +1,142 @@
+import { z } from "zod";
+import { formatResult, formatToolError } from "../client.js";
+/**
+ * Call flows (#25 / B11) — the IVR graphs inbound numbers execute — and
+ * ring groups, their companion routing primitive. Both surfaces are
+ * "settings"-scoped at the API-key boundary: grant the key the settings
+ * scope or these tools return 403.
+ *
+ * The flow graph (draftGraph) is a JSON node/edge document; the API is the
+ * single validator (POST /call-flows/:id/validate previews problems, and
+ * publish refuses an invalid graph), so the tools pass it through untyped
+ * and surface the API's structured errors verbatim.
+ */
+/** (p25-mcp-r3) An explicit graph must carry the parseFlowGraph minimum
+ * (string entryId + nodes array): the API silently substitutes a default
+ * entry→voicemail flow for anything unparseable, which a later publish
+ * would put live on the number. Passthrough keeps every nested field. */
+const flowGraphSchema = z
+    .object({ entryId: z.string(), nodes: z.array(z.unknown()) })
+    .passthrough();
+export function registerCallFlowTools(server, client) {
+    server.tool("conduyt_list_call_flows", "List call flows (IVR routing graphs) with their status (draft/published) and attached phone numbers.", {}, async () => {
+        const result = await client.get("/api/v1/call-flows");
+        return formatResult(result);
+    });
+    server.tool("conduyt_get_call_flow", "Get one call flow including its draft and published graphs.", {
+        id: z.string().describe("Call flow UUID"),
+    }, async ({ id }) => {
+        const result = await client.get(`/api/v1/call-flows/${id}`);
+        return formatResult(result);
+    });
+    server.tool("conduyt_create_call_flow", "Create a call flow. Starts as a DRAFT — edit the graph, validate, then publish to make it live on its number.", {
+        name: z.string().describe("Flow name"),
+        phoneNumber: z.string().optional().describe("E.164 number this flow answers (must belong to the account)"),
+        draftGraph: flowGraphSchema.optional().describe("Initial flow graph — MUST have a string entryId and a nodes array (anything else is silently replaced by a default voicemail flow server-side)"),
+    }, async (params) => {
+        const result = await client.post("/api/v1/call-flows", params);
+        return formatResult(result);
+    });
+    server.tool("conduyt_update_call_flow", "Update a call flow's DRAFT (name, number, graph). Published behavior does not change until the next publish. Replacing draftGraph REQUIRES expectedDraftRevision (the API 428s without it; a concurrent graph edit then 409s instead of being overwritten — the token is graph-specific, so live calls and publish never invalidate it).", {
+        id: z.string().describe("Call flow UUID"),
+        name: z.string().optional().describe("New name"),
+        phoneNumber: z.string().optional().describe("New E.164 number"),
+        draftGraph: flowGraphSchema.optional().describe("Replacement draft graph — MUST have a string entryId and a nodes array; REQUIRES expectedDraftRevision"),
+        expectedDraftRevision: z.number().int().min(0).optional().describe("draftRevision from your last conduyt_get_call_flow read (REQUIRED when replacing draftGraph)"),
+    }, async ({ id, ...updates }) => {
+        if (updates.draftGraph !== undefined && updates.expectedDraftRevision === undefined) {
+            return formatToolError("Replacing draftGraph requires expectedDraftRevision — call conduyt_get_call_flow first and pass its draftRevision.");
+        }
+        const result = await client.patch(`/api/v1/call-flows/${id}`, updates);
+        return formatResult(result);
+    });
+    server.tool("conduyt_delete_call_flow", "Delete a call flow. A PUBLISHED flow refuses deletion (409) — call conduyt_unpublish_call_flow first.", {
+        id: z.string().describe("Call flow UUID"),
+    }, async ({ id }) => {
+        const result = await client.del(`/api/v1/call-flows/${id}`);
+        return formatResult(result);
+    });
+    server.tool("conduyt_validate_call_flow", "Validate a call flow's draft graph WITHOUT publishing — returns structured problems (unreachable nodes, missing targets, etc.).", {
+        id: z.string().describe("Call flow UUID"),
+    }, async ({ id }) => {
+        const result = await client.get(`/api/v1/call-flows/${id}/validate`);
+        return formatResult(result);
+    });
+    server.tool("conduyt_publish_call_flow", "Publish a call flow's draft, making it live on its phone number. Refuses an invalid graph. expectedUpdatedAt is REQUIRED (the API returns 428 without it): read the flow first and pass its updatedAt — a concurrent edit then fails 409 instead of being published over.", {
+        id: z.string().describe("Call flow UUID"),
+        expectedUpdatedAt: z.string().describe("REQUIRED: updatedAt from your last conduyt_get_call_flow read (optimistic concurrency; missing → 428)"),
+    }, async ({ id, expectedUpdatedAt }) => {
+        const result = await client.post(`/api/v1/call-flows/${id}/publish`, { expectedUpdatedAt });
+        return formatResult(result);
+    });
+    server.tool("conduyt_unpublish_call_flow", "Unpublish a call flow — its number stops executing the graph (falls back to default routing).", {
+        id: z.string().describe("Call flow UUID"),
+    }, async ({ id }) => {
+        const result = await client.post(`/api/v1/call-flows/${id}/unpublish`, {});
+        return formatResult(result);
+    });
+    server.tool("conduyt_simulate_call_flow", "Answer \"if someone calls right now, who picks up?\" — simulates the DRAFT graph against LIVE member availability (DIDs, on-call state). No side effects.", {
+        id: z.string().describe("Call flow UUID"),
+    }, async ({ id }) => {
+        const result = await client.post(`/api/v1/call-flows/${id}/simulate`, {});
+        return formatResult(result);
+    });
+    server.tool("conduyt_call_flow_roster", "Get the routing roster: members with DIDs and their live availability — the people call-flow and ring-group steps can ring.", {}, async () => {
+        const result = await client.get("/api/v1/call-flows/roster");
+        return formatResult(result);
+    });
+    server.tool("conduyt_list_ring_groups", "List ring groups (simultaneous/sequential ring sets over member DIDs) with their numbers and members.", {}, async () => {
+        const result = await client.get("/api/v1/ring-groups");
+        return formatResult(result);
+    });
+    server.tool("conduyt_get_ring_group", "Get one ring group.", {
+        id: z.string().describe("Ring group UUID"),
+    }, async ({ id }) => {
+        const result = await client.get(`/api/v1/ring-groups/${id}`);
+        return formatResult(result);
+    });
+    server.tool("conduyt_create_ring_group", "Create a ring group on an account number. Without memberIds the group is created INACTIVE.", {
+        name: z.string().describe("Ring group name"),
+        phoneNumber: z.string().describe("REQUIRED: account E.164 number that rings this group"),
+        memberIds: z.array(z.string()).optional().describe("Member user UUIDs (omit → the group is created INACTIVE; memberless groups never ring)"),
+        strategy: z.string().optional().describe("Ring strategy (e.g. simultaneous, sequential)"),
+        ringSeconds: z.number().int().min(5).max(120).optional().describe("Seconds to ring before advancing/failing over (5-120)"),
+        isActive: z.boolean().optional().describe("Whether the group is active"),
+    }, async (params) => {
+        const result = await client.post("/api/v1/ring-groups", params);
+        return formatResult(result);
+    });
+    server.tool("conduyt_update_ring_group", "Update a ring group (name, number, members, strategy, ring time, active). Replacing memberIds REQUIRES expectedUpdatedAt (the API 428s without it); passing it on any update makes a concurrent edit 409 instead of being overwritten.", {
+        id: z.string().describe("Ring group UUID"),
+        name: z.string().optional().describe("New name"),
+        phoneNumber: z.string().optional().describe("New E.164 number"),
+        memberIds: z.array(z.string()).optional().describe("Replacement member user UUIDs — REQUIRES expectedUpdatedAt"),
+        strategy: z.string().optional().describe("Ring strategy"),
+        ringSeconds: z.number().int().min(5).max(120).optional().describe("Seconds to ring (5-120)"),
+        isActive: z.boolean().optional().describe("Active flag"),
+        expectedUpdatedAt: z.string().optional().describe("updatedAt from your last conduyt_get_ring_group read (REQUIRED when replacing memberIds)"),
+    }, async ({ id, ...updates }) => {
+        if (updates.memberIds !== undefined && updates.expectedUpdatedAt === undefined) {
+            // (p25-mcp-r2) isError REQUIRED: without it MCP reports success and
+            // the client proceeds although no PATCH occurred.
+            return formatToolError("Replacing memberIds requires expectedUpdatedAt — call conduyt_get_ring_group first and pass its updatedAt.");
+        }
+        const result = await client.patch(`/api/v1/ring-groups/${id}`, updates);
+        return formatResult(result);
+    });
+    server.tool("conduyt_delete_ring_group", "Delete a ring group. Its number keeps ringing default routing afterwards.", {
+        id: z.string().describe("Ring group UUID"),
+    }, async ({ id }) => {
+        const result = await client.del(`/api/v1/ring-groups/${id}`);
+        return formatResult(result);
+    });
+    server.tool("conduyt_release_ring_group_number", "Release a phone number from ring-group routing (DESTRUCTIVE). confirm must be the EXACT phone number repeated as a string. A number still referenced by an ACTIVE ring group cannot be released — delete or repoint that group first; force does NOT bypass it. force exists only for numbers whose Twilio ownership cannot be verified, and then a non-empty forceReason is required.", {
+        phoneNumber: z.string().describe("E.164 number to release"),
+        confirm: z.string().describe("EXACT repetition of phoneNumber (string) — the API rejects anything else"),
+        force: z.boolean().optional().describe("ONLY when Twilio ownership is unverifiable; requires forceReason"),
+        forceReason: z.string().optional().describe("Non-empty justification, required with force"),
+    }, async (params) => {
+        const result = await client.post("/api/v1/ring-groups/release-number", params);
+        return formatResult(result);
+    });
+}

package/dist/tools/users.js

@@ -41,6 +41,12 @@ export function registerUserTools(server, client) {
         phone: z.string().optional().describe("Updated phone"),
         role: z.enum(["member", "admin", "owner"]).optional().describe("Updated role"),
         permissions: z.array(z.string()).optional().describe("Updated permission scopes"),
+        position: z.string().nullable().optional().describe("Rep-profile position/title, merge-taggable as {{user.position}} (owner/admin only; null clears)"),
+        mobilePhone: z.string().nullable().optional().describe("Rep-profile mobile phone, merge-taggable as {{user.mobilePhone}} (owner/admin only; null clears)"),
+        custom1: z.string().nullable().optional().describe("Rep-profile custom field 1, merge-taggable as {{user.custom1}} (owner/admin only; null clears)"),
+        custom2: z.string().nullable().optional().describe("Rep-profile custom field 2, merge-taggable as {{user.custom2}} (owner/admin only; null clears)"),
+        custom3: z.string().nullable().optional().describe("Rep-profile custom field 3, merge-taggable as {{user.custom3}} (owner/admin only; null clears)"),
+        custom4: z.string().nullable().optional().describe("Rep-profile custom field 4, merge-taggable as {{user.custom4}} (owner/admin only; null clears)"),
     }, async ({ id, ...updates }) => {
         const result = await client.patch(`/api/v1/users/${id}`, updates);
         return formatResult(result);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt-mcp",
-  "version": "4.19.0",
+  "version": "4.21.0",
   "description": "MCP server for Conduyt CRM — expose CRM operations as AI-accessible tools",
   "type": "module",
   "main": "dist/index.js",

package/scripts/coverage-manifest.json

@@ -499,6 +499,16 @@
       "match": "/api/v1/webhooks",
       "status": "planned",
       "reason": "outbound webhook subscription management (distinct from the inbound /webhooks/ receivers)"
+    },
+    {
+      "match": "/api/v1/automation-folders",
+      "status": "planned",
+      "reason": "automation-folder organization (shipped 2026-08) \u2014 agent-relevant workflow housekeeping; typed tools wanted"
+    },
+    {
+      "match": "POST /api/v1/call-flows/audio",
+      "status": "excluded",
+      "reason": "multipart file upload (IVR audio) - not expressible as a text MCP tool; agents reference existing audio by id from conduyt_get_call_flow"
     }
   ]
-}
+}

package/scripts/coverage-matrix.json

@@ -1,11 +1,11 @@
 {
-  "generatedAt": "2026-08-06T22:46:04.536Z",
-  "toolCount": 173,
-  "totalEndpoints": 842,
+  "generatedAt": "2026-08-23T13:00:42.998Z",
+  "toolCount": 189,
+  "totalEndpoints": 872,
   "counts": {
-    "covered": 161,
-    "excluded": 248,
-    "planned": 433,
+    "covered": 177,
+    "excluded": 256,
+    "planned": 439,
     "uncategorized": 0
   },
   "matrix": {
@@ -395,6 +395,10 @@
       "status": "planned",
       "reason": "API key admin beyond self-check"
     },
+    "GET /api/v1/api-keys/:id": {
+      "status": "planned",
+      "reason": "API key admin beyond self-check"
+    },
     "PATCH /api/v1/api-keys/:id": {
       "status": "planned",
       "reason": "API key admin beyond self-check"
@@ -533,6 +537,22 @@
       "status": "planned",
       "reason": "execution inspection"
     },
+    "GET /api/v1/automation-folders": {
+      "status": "planned",
+      "reason": "automation-folder organization (shipped 2026-08) — agent-relevant workflow housekeeping; typed tools wanted"
+    },
+    "POST /api/v1/automation-folders": {
+      "status": "planned",
+      "reason": "automation-folder organization (shipped 2026-08) — agent-relevant workflow housekeeping; typed tools wanted"
+    },
+    "PATCH /api/v1/automation-folders/:id": {
+      "status": "planned",
+      "reason": "automation-folder organization (shipped 2026-08) — agent-relevant workflow housekeeping; typed tools wanted"
+    },
+    "DELETE /api/v1/automation-folders/:id": {
+      "status": "planned",
+      "reason": "automation-folder organization (shipped 2026-08) — agent-relevant workflow housekeeping; typed tools wanted"
+    },
     "GET /api/v1/automations": {
       "status": "covered",
       "tools": [
@@ -970,6 +990,70 @@
       "status": "planned",
       "reason": "calendar/booking management beyond current appointment tools"
     },
+    "GET /api/v1/call-flows": {
+      "status": "covered",
+      "tools": [
+        "conduyt_list_call_flows"
+      ]
+    },
+    "POST /api/v1/call-flows": {
+      "status": "covered",
+      "tools": [
+        "conduyt_create_call_flow"
+      ]
+    },
+    "GET /api/v1/call-flows/:id": {
+      "status": "covered",
+      "tools": [
+        "conduyt_get_call_flow"
+      ]
+    },
+    "PATCH /api/v1/call-flows/:id": {
+      "status": "covered",
+      "tools": [
+        "conduyt_update_call_flow"
+      ]
+    },
+    "DELETE /api/v1/call-flows/:id": {
+      "status": "covered",
+      "tools": [
+        "conduyt_delete_call_flow"
+      ]
+    },
+    "POST /api/v1/call-flows/:id/publish": {
+      "status": "covered",
+      "tools": [
+        "conduyt_publish_call_flow"
+      ]
+    },
+    "POST /api/v1/call-flows/:id/simulate": {
+      "status": "covered",
+      "tools": [
+        "conduyt_simulate_call_flow"
+      ]
+    },
+    "POST /api/v1/call-flows/:id/unpublish": {
+      "status": "covered",
+      "tools": [
+        "conduyt_unpublish_call_flow"
+      ]
+    },
+    "GET /api/v1/call-flows/:id/validate": {
+      "status": "covered",
+      "tools": [
+        "conduyt_validate_call_flow"
+      ]
+    },
+    "POST /api/v1/call-flows/audio": {
+      "status": "excluded",
+      "reason": "multipart file upload (IVR audio) - not expressible as a text MCP tool; agents reference existing audio by id from conduyt_get_call_flow"
+    },
+    "GET /api/v1/call-flows/roster": {
+      "status": "covered",
+      "tools": [
+        "conduyt_call_flow_roster"
+      ]
+    },
     "GET /api/v1/calls": {
       "status": "covered",
       "tools": [
@@ -1381,6 +1465,10 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    "GET /api/v1/cron/process-automation-redispatch": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
     "GET /api/v1/cron/process-batches": {
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
@@ -1389,6 +1477,10 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    "GET /api/v1/cron/process-call-lifecycle-intents": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
     "GET /api/v1/cron/process-consent-outbox": {
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
@@ -1489,6 +1581,10 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    "GET /api/v1/cron/reap-stale-group-calls": {
+      "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"
@@ -1501,6 +1597,10 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    "GET /api/v1/cron/recover-booking-side-effects": {
+      "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"
@@ -1513,6 +1613,10 @@
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
     },
+    "GET /api/v1/cron/reply-capture-drain": {
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
     "GET /api/v1/cron/resume-imports": {
       "status": "excluded",
       "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
@@ -2377,6 +2481,10 @@
       "status": "planned",
       "reason": "integration management"
     },
+    "POST /api/v1/integrations/dpp/ingest": {
+      "status": "planned",
+      "reason": "integration management"
+    },
     "GET /api/v1/integrations/health": {
       "status": "planned",
       "reason": "integration management"
@@ -2941,6 +3049,42 @@
       "status": "planned",
       "reason": "additional report surfaces beyond ai/insights"
     },
+    "GET /api/v1/ring-groups": {
+      "status": "covered",
+      "tools": [
+        "conduyt_list_ring_groups"
+      ]
+    },
+    "POST /api/v1/ring-groups": {
+      "status": "covered",
+      "tools": [
+        "conduyt_create_ring_group"
+      ]
+    },
+    "GET /api/v1/ring-groups/:id": {
+      "status": "covered",
+      "tools": [
+        "conduyt_get_ring_group"
+      ]
+    },
+    "PATCH /api/v1/ring-groups/:id": {
+      "status": "covered",
+      "tools": [
+        "conduyt_update_ring_group"
+      ]
+    },
+    "DELETE /api/v1/ring-groups/:id": {
+      "status": "covered",
+      "tools": [
+        "conduyt_delete_ring_group"
+      ]
+    },
+    "POST /api/v1/ring-groups/release-number": {
+      "status": "covered",
+      "tools": [
+        "conduyt_release_ring_group_number"
+      ]
+    },
     "GET /api/v1/saved-filters": {
       "status": "planned",
       "reason": "saved filter management"
@@ -3643,6 +3787,10 @@
       "status": "excluded",
       "reason": "inbound provider callback receivers (Twilio/Resend/etc.), not client-callable"
     },
+    "POST /api/v1/webhooks/voice/flow-step": {
+      "status": "excluded",
+      "reason": "inbound provider callback receivers (Twilio/Resend/etc.), not client-callable"
+    },
     "POST /api/v1/webhooks/voice/inbound": {
       "status": "excluded",
       "reason": "inbound provider callback receivers (Twilio/Resend/etc.), not client-callable"
@@ -3651,6 +3799,10 @@
       "status": "excluded",
       "reason": "inbound provider callback receivers (Twilio/Resend/etc.), not client-callable"
     },
+    "POST /api/v1/webhooks/voice/ring-group-step": {
+      "status": "excluded",
+      "reason": "inbound provider callback receivers (Twilio/Resend/etc.), not client-callable"
+    },
     "POST /api/v1/webhooks/voice/status": {
       "status": "excluded",
       "reason": "inbound provider callback receivers (Twilio/Resend/etc.), not client-callable"