conduyt-mcp 4.20.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt-mcp",
-  "version": "4.20.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

@@ -506,14 +506,9 @@
       "reason": "automation-folder organization (shipped 2026-08) \u2014 agent-relevant workflow housekeeping; typed tools wanted"
     },
     {
-      "match": "/api/v1/call-flows",
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) \u2014 agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
-    },
-    {
-      "match": "/api/v1/ring-groups",
-      "status": "planned",
-      "reason": "ring-group management (call-flows companion, shipped 2026-08-21) \u2014 agent-relevant; typed tools with the call-flow set"
+      "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-22T18:59:24.922Z",
-  "toolCount": 173,
+  "generatedAt": "2026-08-23T13:00:42.998Z",
+  "toolCount": 189,
   "totalEndpoints": 872,
   "counts": {
-    "covered": 161,
-    "excluded": 255,
-    "planned": 456,
+    "covered": 177,
+    "excluded": 256,
+    "planned": 439,
     "uncategorized": 0
   },
   "matrix": {
@@ -991,48 +991,68 @@
       "reason": "calendar/booking management beyond current appointment tools"
     },
     "GET /api/v1/call-flows": {
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "status": "covered",
+      "tools": [
+        "conduyt_list_call_flows"
+      ]
     },
     "POST /api/v1/call-flows": {
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "status": "covered",
+      "tools": [
+        "conduyt_create_call_flow"
+      ]
     },
     "GET /api/v1/call-flows/:id": {
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "status": "covered",
+      "tools": [
+        "conduyt_get_call_flow"
+      ]
     },
     "PATCH /api/v1/call-flows/:id": {
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "status": "covered",
+      "tools": [
+        "conduyt_update_call_flow"
+      ]
     },
     "DELETE /api/v1/call-flows/:id": {
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "status": "covered",
+      "tools": [
+        "conduyt_delete_call_flow"
+      ]
     },
     "POST /api/v1/call-flows/:id/publish": {
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "status": "covered",
+      "tools": [
+        "conduyt_publish_call_flow"
+      ]
     },
     "POST /api/v1/call-flows/:id/simulate": {
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "status": "covered",
+      "tools": [
+        "conduyt_simulate_call_flow"
+      ]
     },
     "POST /api/v1/call-flows/:id/unpublish": {
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "status": "covered",
+      "tools": [
+        "conduyt_unpublish_call_flow"
+      ]
     },
     "GET /api/v1/call-flows/:id/validate": {
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "status": "covered",
+      "tools": [
+        "conduyt_validate_call_flow"
+      ]
     },
     "POST /api/v1/call-flows/audio": {
-      "status": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "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": "planned",
-      "reason": "call-flow builder API (shipped 2026-08-21) — agent-relevant; typed tools follow once the canvas UI (#25) settles the surface"
+      "status": "covered",
+      "tools": [
+        "conduyt_call_flow_roster"
+      ]
     },
     "GET /api/v1/calls": {
       "status": "covered",
@@ -3030,28 +3050,40 @@
       "reason": "additional report surfaces beyond ai/insights"
     },
     "GET /api/v1/ring-groups": {
-      "status": "planned",
-      "reason": "ring-group management (call-flows companion, shipped 2026-08-21) — agent-relevant; typed tools with the call-flow set"
+      "status": "covered",
+      "tools": [
+        "conduyt_list_ring_groups"
+      ]
     },
     "POST /api/v1/ring-groups": {
-      "status": "planned",
-      "reason": "ring-group management (call-flows companion, shipped 2026-08-21) — agent-relevant; typed tools with the call-flow set"
+      "status": "covered",
+      "tools": [
+        "conduyt_create_ring_group"
+      ]
     },
     "GET /api/v1/ring-groups/:id": {
-      "status": "planned",
-      "reason": "ring-group management (call-flows companion, shipped 2026-08-21) — agent-relevant; typed tools with the call-flow set"
+      "status": "covered",
+      "tools": [
+        "conduyt_get_ring_group"
+      ]
     },
     "PATCH /api/v1/ring-groups/:id": {
-      "status": "planned",
-      "reason": "ring-group management (call-flows companion, shipped 2026-08-21) — agent-relevant; typed tools with the call-flow set"
+      "status": "covered",
+      "tools": [
+        "conduyt_update_ring_group"
+      ]
     },
     "DELETE /api/v1/ring-groups/:id": {
-      "status": "planned",
-      "reason": "ring-group management (call-flows companion, shipped 2026-08-21) — agent-relevant; typed tools with the call-flow set"
+      "status": "covered",
+      "tools": [
+        "conduyt_delete_ring_group"
+      ]
     },
     "POST /api/v1/ring-groups/release-number": {
-      "status": "planned",
-      "reason": "ring-group management (call-flows companion, shipped 2026-08-21) — agent-relevant; typed tools with the call-flow set"
+      "status": "covered",
+      "tools": [
+        "conduyt_release_ring_group_number"
+      ]
     },
     "GET /api/v1/saved-filters": {
       "status": "planned",