conduyt-mcp 4.6.0 → 4.9.0

package/dist/client.js

@@ -2,7 +2,20 @@ export class ConduytClient {
     baseUrl;
     apiKey;
     constructor(config) {
-        this.baseUrl = config.apiUrl.replace(/\/+$/, "");
+        // Strip trailing slashes, then guard against a misconfigured base URL that
+        // already includes the API prefix. Every tool builds paths as `/api/v1/...`,
+        // so a base of `https://conduyt.app/api/v1` would produce
+        // `/api/v1/api/v1/...` and 404 every call. Strip a trailing `/api/v1`
+        // (optionally with a version suffix) and warn so it surfaces in logs.
+        let base = config.apiUrl.replace(/\/+$/, "");
+        const dupPrefix = /\/api\/v\d+$/i;
+        if (dupPrefix.test(base)) {
+            const stripped = base.replace(dupPrefix, "");
+            console.error(`CONDUYT_API_URL should be the bare origin (e.g. https://conduyt.app), not include the API prefix. ` +
+                `Stripping "${base.slice(stripped.length)}" so requests don't 404 as /api/v1/api/v1/...`);
+            base = stripped;
+        }
+        this.baseUrl = base;
         this.apiKey = config.apiKey;
     }
     async request(method, path, body) {

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createRequire } from "node:module";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ConduytClient } from "./client.js";
 import { registerDiscoveryTools } from "./tools/discovery.js";
@@ -12,6 +13,7 @@ import { registerAiTools } from "./tools/ai.js";
 import { registerAutomationTools } from "./tools/automations.js";
 import { registerSequenceTools } from "./tools/sequences.js";
 import { registerMessagingTools } from "./tools/messaging.js";
+import { registerCallTools } from "./tools/calls.js";
 import { registerCompanyTools } from "./tools/companies.js";
 import { registerTagTools } from "./tools/tags.js";
 import { registerCalendarTools } from "./tools/calendar.js";
@@ -23,6 +25,8 @@ import { registerCustomFieldTools } from "./tools/custom-fields.js";
 import { registerSmartListTools } from "./tools/smart-lists.js";
 import { registerUserTools } from "./tools/users.js";
 import { registerBulkTools } from "./tools/bulk.js";
+import { registerDncTools } from "./tools/dnc.js";
+import { registerSavedFilterTools } from "./tools/saved-filters.js";
 import { registerDripCampaignTools } from "./tools/drip-campaigns.js";
 import { registerScoringTools } from "./tools/scoring.js";
 import { registerProductTools } from "./tools/products.js";
@@ -43,9 +47,12 @@ if (!apiKey.startsWith("cdy_")) {
     process.exit(1);
 }
 const client = new ConduytClient({ apiUrl, apiKey });
+// Single source of truth for the version — read from package.json so the
+// runtime initialize metadata can never drift from the published package.
+const pkg = createRequire(import.meta.url)("../package.json");
 const server = new McpServer({
     name: "conduyt",
-    version: "4.3.3",
+    version: pkg.version,
 });
 registerDiscoveryTools(server, client);
 registerContactTools(server, client);
@@ -57,6 +64,7 @@ registerAiTools(server, client);
 registerAutomationTools(server, client);
 registerSequenceTools(server, client);
 registerMessagingTools(server, client);
+registerCallTools(server, client);
 registerCompanyTools(server, client);
 registerTagTools(server, client);
 registerCalendarTools(server, client);
@@ -68,6 +76,8 @@ registerCustomFieldTools(server, client);
 registerSmartListTools(server, client);
 registerUserTools(server, client);
 registerBulkTools(server, client);
+registerDncTools(server, client);
+registerSavedFilterTools(server, client);
 registerDripCampaignTools(server, client);
 registerScoringTools(server, client);
 registerProductTools(server, client);

package/dist/tools/bulk.js

@@ -103,7 +103,7 @@ export function registerBulkTools(server, client) {
         const result = await client.post("/api/v1/bulk/contacts/delete", params);
         return formatResult(result);
     });
-    server.tool("conduyt_bulk_dnc_contacts", "Add or remove a Do-Not-Contact / litigator mark for many contacts (compliance action). The mark is keyed on each contact's phone number, so contacts without a phone are skipped. Base permission is contacts:edit; removing any mark, or adding a litigator mark, additionally requires an owner/admin role server-side (others get 403).", {
+    server.tool("conduyt_bulk_dnc_contacts", "Add or remove a Do-Not-Contact / litigator mark for many contacts (compliance action). Requires the EXPLICIT 'dnc' API-key scope — an admin must grant it deliberately in Settings > API Keys (an unrestricted key does NOT imply it; without the scope this returns 403). Writes are also bound by contact-ownership rules for limited keys. To CHECK whether a number is already blocked, use conduyt_get_contact (dnc status) or the contacts dnc-status read.", {
         contactIds: z.array(z.string()).describe("Contact UUIDs (those without a phone number are skipped)"),
         action: z.enum(["add", "remove"]).describe("Add or remove the mark"),
         tier: z.enum(["dnc", "litigator"]).describe("Which list: 'dnc' (standard do-not-contact) or 'litigator' (known litigator; admin-only to add)"),

package/dist/tools/calls.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConduytClient } from "../client.js";
+/**
+ * READ-ONLY dialer/call-history tools. Live call control (initiate, mute,
+ * hold, transfer, hangup, vm-drop, record) is deliberately NOT exposed here —
+ * those actions are human-session-only by design. These tools let an agent
+ * review the call log and inspect a single call's outcome/transcript.
+ */
+export declare function registerCallTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/calls.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { formatResult } from "../client.js";
+/**
+ * READ-ONLY dialer/call-history tools. Live call control (initiate, mute,
+ * hold, transfer, hangup, vm-drop, record) is deliberately NOT exposed here —
+ * those actions are human-session-only by design. These tools let an agent
+ * review the call log and inspect a single call's outcome/transcript.
+ */
+export function registerCallTools(server, client) {
+    server.tool("conduyt_list_calls", "List call-history records (read-only) with filters — review past inbound/outbound calls, their status, duration, and disposition. Newest first. Returns metadata only by default (NO call transcripts, NO recording/voicemail URLs — only hasRecording/hasVoicemail/hasTranscript flags), so a routine list never pulls raw transcripts into context. To read a specific call's transcript, use conduyt_get_call. Requires dialer:view.", {
+        contactId: z.string().optional().describe("Filter to calls for a single contact UUID"),
+        userId: z.string().optional().describe("Filter to calls handled by a specific user UUID"),
+        direction: z.enum(["inbound", "outbound"]).optional().describe("Filter by call direction"),
+        status: z.string().optional().describe("Filter by call status, e.g. 'completed', 'initiated', 'no-answer', 'failed'"),
+        dateFrom: z.string().optional().describe("Only calls created on/after this date (ISO 8601)"),
+        dateTo: z.string().optional().describe("Only calls created on/before this date (ISO 8601)"),
+        page: z.number().optional().describe("Page number (default 1)"),
+        per_page: z.number().optional().describe("Results per page (default 50, max 200)"),
+    }, async ({ contactId, userId, direction, status, dateFrom, dateTo, page, per_page }) => {
+        const params = new URLSearchParams();
+        // Metadata-only by design: the minimal route never loads transcriptionText
+        // (heavy @db.Text) — transcript retrieval is a deliberate conduyt_get_call.
+        params.set("minimal", "1");
+        if (contactId)
+            params.set("contact_id", contactId);
+        if (userId)
+            params.set("user_id", userId);
+        if (direction)
+            params.set("direction", direction);
+        if (status)
+            params.set("status", status);
+        if (dateFrom)
+            params.set("date_from", dateFrom);
+        if (dateTo)
+            params.set("date_to", dateTo);
+        if (page)
+            params.set("page", String(page));
+        if (per_page)
+            params.set("per_page", String(per_page));
+        const result = await client.get(`/api/v1/calls?${params}`);
+        return formatResult(result);
+    });
+    server.tool("conduyt_get_call", "Get a single call record by UUID (read-only) — direction, status, duration, disposition, notes, transcript text (if any), and the linked contact/user. Recording/voicemail URLs are withheld; hasRecording/hasVoicemail flags indicate their presence. Requires dialer:view.", {
+        id: z.string().describe("Call UUID"),
+    }, async ({ id }) => {
+        const result = await client.get(`/api/v1/calls/${encodeURIComponent(id)}`);
+        return formatResult(result);
+    });
+}

package/dist/tools/dnc.d.ts

@@ -0,0 +1,13 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConduytClient } from "../client.js";
+/**
+ * Do-Not-Call / litigator list management (compliance surface).
+ *
+ * All of these require the EXPLICIT 'dnc' API-key scope — an admin must grant
+ * it deliberately in Settings > API Keys; an unrestricted key does NOT imply
+ * it (403 without it). Limited keys are additionally bound by contact
+ * ownership rules. Entries are phone-scoped when a number is given
+ * (normalizedPhone blocks the NUMBER account-wide) and contact-scoped when
+ * only a contactId is given.
+ */
+export declare function registerDncTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/dnc.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { formatResult } from "../client.js";
+/**
+ * Do-Not-Call / litigator list management (compliance surface).
+ *
+ * All of these require the EXPLICIT 'dnc' API-key scope — an admin must grant
+ * it deliberately in Settings > API Keys; an unrestricted key does NOT imply
+ * it (403 without it). Limited keys are additionally bound by contact
+ * ownership rules. Entries are phone-scoped when a number is given
+ * (normalizedPhone blocks the NUMBER account-wide) and contact-scoped when
+ * only a contactId is given.
+ */
+export function registerDncTools(server, client) {
+    server.tool("conduyt_list_dnc", "List active Do-Not-Call / litigator entries. Filter by search (phone or contact name) or tier. Requires the explicit 'dnc' API-key scope.", {
+        search: z.string().optional().describe("Match on phone number or contact name"),
+        tier: z.enum(["dnc", "litigator"]).optional().describe("Filter to one list"),
+        page: z.number().optional().describe("Page number (default 1)"),
+        per_page: z.number().optional().describe("Results per page (default 50)"),
+    }, async ({ search, tier, page, per_page }) => {
+        const params = new URLSearchParams();
+        if (search)
+            params.set("search", search);
+        if (tier)
+            params.set("tier", tier);
+        if (page)
+            params.set("page", String(page));
+        if (per_page)
+            params.set("per_page", String(per_page));
+        const result = await client.get(`/api/v1/dnc?${params}`);
+        return formatResult(result);
+    });
+    server.tool("conduyt_add_dnc", "Add a phone number (or a contact) to the Do-Not-Call or litigator list — e.g. \"add this number to the do not call list\". Phone entries block the NUMBER account-wide across dialer/SMS. Requires the explicit 'dnc' API-key scope; adding to the litigator tier is admin-only.", {
+        phone: z.string().optional().describe("Phone number to block (E.164 preferred, e.g. +15551234567). Provide phone and/or contactId."),
+        contactId: z.string().optional().describe("Contact UUID to mark (contact-scoped block when no phone is supplied)"),
+        tier: z.enum(["dnc", "litigator"]).default("dnc").describe("Which list: 'dnc' (standard) or 'litigator' (known litigator; admin-only)"),
+        reason: z.string().optional().describe("Reason recorded for the compliance audit trail"),
+    }, async (params) => {
+        const result = await client.post("/api/v1/dnc", params);
+        return formatResult(result);
+    });
+    server.tool("conduyt_remove_dnc", "Remove (soft-delete) a Do-Not-Call / litigator entry by its entry id — unblocks the number/contact. Use conduyt_list_dnc to find the entry id first. Requires the explicit 'dnc' API-key scope.", {
+        // Strict UUID + encode: a raw string interpolated into a DELETE path
+        // could traverse (../contacts/<id>) into a different destructive
+        // endpoint — this tool must stay DNC-only regardless of key scope.
+        id: z.string().uuid().describe("DNC entry UUID (from conduyt_list_dnc)"),
+    }, async ({ id }) => {
+        const result = await client.del(`/api/v1/dnc/${encodeURIComponent(id)}`);
+        return formatResult(result);
+    });
+}

package/dist/tools/messaging.js

@@ -22,4 +22,48 @@ export function registerMessagingTools(server, client) {
         const result = await client.post("/api/v1/email/send", params);
         return formatResult(result);
     });
+    server.tool("conduyt_get_conversation", "Read the full conversation thread for one contact — the chronological SMS/email message history (both inbound replies and outbound sends), plus conversation state, unread count, and recent notes. Use this to see what a contact has replied before deciding how to follow up. Requires communications:view.", {
+        contactId: z.string().describe("Contact UUID whose conversation to read"),
+        channel: z.string().optional().describe("Filter to one channel, e.g. 'sms' or 'email' (omit for all channels)"),
+        cursor: z.string().optional().describe("Message ID for cursor pagination — returns messages OLDER than this id (for loading earlier history)"),
+        around: z.string().optional().describe("Message ID to center the window on — returns messages before and after this id"),
+        per_page: z.number().optional().describe("Messages per page (default 50, max 100)"),
+    }, async ({ contactId, channel, cursor, around, per_page }) => {
+        const params = new URLSearchParams();
+        if (channel)
+            params.set("channel", channel);
+        if (cursor)
+            params.set("cursor", cursor);
+        if (around)
+            params.set("around", around);
+        if (per_page)
+            params.set("per_page", String(per_page));
+        const qs = params.toString();
+        const result = await client.get(`/api/v1/conversations/${encodeURIComponent(contactId)}${qs ? `?${qs}` : ""}`);
+        return formatResult(result);
+    });
+    server.tool("conduyt_list_messages", "List individual messages across contacts with filters — read inbound replies and outbound sends account-wide, or scoped to one contact. Newest first. Use direction='inbound' to surface replies that need a response. Requires communications:view.", {
+        contactId: z.string().optional().describe("Filter to a single contact UUID"),
+        channel: z.string().optional().describe("Filter by channel, e.g. 'sms' or 'email'"),
+        direction: z.enum(["inbound", "outbound"]).optional().describe("Filter by direction — 'inbound' = messages from the contact, 'outbound' = messages you sent"),
+        status: z.string().optional().describe("Filter by message status, e.g. 'sent', 'delivered', 'received', 'failed', 'draft'"),
+        page: z.number().optional().describe("Page number (default 1)"),
+        per_page: z.number().optional().describe("Results per page (default 50, max 200)"),
+    }, async ({ contactId, channel, direction, status, page, per_page }) => {
+        const params = new URLSearchParams();
+        if (contactId)
+            params.set("contactId", contactId);
+        if (channel)
+            params.set("channel", channel);
+        if (direction)
+            params.set("direction", direction);
+        if (status)
+            params.set("status", status);
+        if (page)
+            params.set("page", String(page));
+        if (per_page)
+            params.set("per_page", String(per_page));
+        const result = await client.get(`/api/v1/messages?${params}`);
+        return formatResult(result);
+    });
 }

package/dist/tools/saved-filters.d.ts

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

package/dist/tools/saved-filters.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { formatResult } from "../client.js";
+/**
+ * Personal saved filters for list pages (Velocify-style). Strictly
+ * per-user: a saved filter belongs to the API key's user and is invisible
+ * to everyone else — these are NOT Smart Views (admin-curated team/dialer
+ * buckets). A saved filter snapshots an advanced-filter payload + sort so
+ * a view can be re-applied in one step (the web app's "Saved" dropdown on
+ * All Contacts). Requires the 'saved-filters' API-key scope.
+ */
+// Filter payload — same shapes the API accepts: the canonical GROUPED
+// payload, or a legacy FLAT rule array which the API normalizes into a
+// single AND group on save. Caps mirror the API's validateAdvancedFilters
+// limits (10 groups × 20 rules) so oversized payloads fail here instead of
+// round-tripping to a 400.
+const ruleSchema = z.object({
+    field: z.string().describe("Filter field, e.g. assignedTo, source, tags, pipelineStage, dealStatus, createdAt"),
+    operator: z.string().describe("Operator valid for the field, e.g. equals, is_any_of, contains, is_empty"),
+    value: z.union([z.string(), z.array(z.string())]).optional(),
+});
+const groupSchema = z.object({
+    conjunction: z.enum(["AND", "OR"]),
+    rules: z.array(ruleSchema).max(20),
+});
+const filtersSchema = z
+    .union([z.array(groupSchema).max(10), z.array(ruleSchema).max(20)])
+    .optional()
+    .describe('Grouped filter payload (max 10 groups × 20 rules), e.g. [{"conjunction":"AND","rules":[{"field":"source","operator":"equals","value":"facebook"}]}]. A flat rule array is also accepted and saved as a single AND group. Omit for an empty filter set.');
+export function registerSavedFilterTools(server, client) {
+    server.tool("conduyt_list_saved_filters", "List YOUR saved contact filters (the web app's 'Saved' dropdown on All Contacts). Each entry has a name, the grouped filter payload, and sort. Saved filters are personal to the API key's user. Requires the 'saved-filters' scope.", {
+        entity_type: z.enum(["contact"]).optional().describe("Entity type (default 'contact')"),
+    }, async ({ entity_type }) => {
+        const params = new URLSearchParams();
+        if (entity_type)
+            params.set("entity_type", entity_type);
+        const qs = params.toString();
+        const result = await client.get(`/api/v1/saved-filters${qs ? `?${qs}` : ""}`);
+        return formatResult(result);
+    });
+    server.tool("conduyt_create_saved_filter", "Save a named contact filter for one-click re-use — e.g. \"save a filter for Heather's Facebook leads\". Names are unique per user (409 on duplicate); max 50 saved filters per user. Requires the 'saved-filters' scope.", {
+        name: z.string().min(1).max(60).describe("Display name shown in the Saved dropdown (unique per user, max 60 chars)"),
+        filters: filtersSchema,
+        sortField: z.string().optional().describe("Sort field applied with the filter (default createdAt)"),
+        sortOrder: z.enum(["asc", "desc"]).optional().describe("Sort direction (default desc)"),
+        entityType: z.enum(["contact"]).optional().describe("Entity type (default 'contact')"),
+    }, async (params) => {
+        const result = await client.post("/api/v1/saved-filters", params);
+        return formatResult(result);
+    });
+    server.tool("conduyt_update_saved_filter", "Rename a saved filter or replace its filters/sort. Owner-only — you can only update your own saved filters. Use conduyt_list_saved_filters to find the id. Requires the 'saved-filters' scope.", {
+        id: z.string().uuid().describe("Saved filter UUID (from conduyt_list_saved_filters)"),
+        name: z.string().min(1).max(60).optional().describe("New display name (unique per user)"),
+        filters: filtersSchema,
+        sortField: z.string().optional(),
+        sortOrder: z.enum(["asc", "desc"]).optional(),
+    }, async ({ id, name, filters, sortField, sortOrder }) => {
+        // Inline body (undefined fields drop out in JSON) — keeps the shape
+        // readable by the contract verifier's static parser.
+        const result = await client.patch(`/api/v1/saved-filters/${encodeURIComponent(id)}`, {
+            name,
+            filters,
+            sortField,
+            sortOrder,
+        });
+        return formatResult(result);
+    });
+    server.tool("conduyt_delete_saved_filter", "Delete one of YOUR saved filters by id. Owner-only. Requires the 'saved-filters' scope.", {
+        // Strict UUID + encode — the id is interpolated into a DELETE path and
+        // must never traverse out of the saved-filters endpoint.
+        id: z.string().uuid().describe("Saved filter UUID (from conduyt_list_saved_filters)"),
+    }, async ({ id }) => {
+        const result = await client.del(`/api/v1/saved-filters/${encodeURIComponent(id)}`);
+        return formatResult(result);
+    });
+}

package/dist/tools/tasks.js

@@ -62,4 +62,36 @@ export function registerTaskTools(server, client) {
         const result = await client.post("/api/v1/tasks", params);
         return formatResult(result);
     });
+    server.tool("conduyt_get_task", "Get a single task by UUID with full details — title, description, due date, status, priority, and the linked assignee, creator, contact, and deal.", {
+        id: z.string().uuid().describe("Task UUID"),
+    }, async ({ id }) => {
+        const result = await client.get(`/api/v1/tasks/${encodeURIComponent(id)}`);
+        return formatResult(result);
+    });
+    server.tool("conduyt_update_task", "Update an existing task's fields. Only the fields you provide are changed; omit a field to leave it as-is. To mark a task done, prefer conduyt_complete_task. Requires tasks:edit.", {
+        id: z.string().uuid().describe("Task UUID to update"),
+        title: z.string().optional().describe("Updated task title"),
+        description: z.string().optional().describe("Updated description (pass an empty string to clear it)"),
+        dueDate: z.string().optional().describe("Updated due date (ISO 8601, e.g. '2026-07-15' or a full timestamp)"),
+        priority: z.enum(["low", "medium", "high", "urgent"]).optional().describe("Updated priority"),
+        status: z.enum(["todo", "in_progress", "done"]).optional().describe("Updated status. Setting 'done' auto-stamps completedAt and fires task.completed side effects."),
+        assignedTo: z.string().nullable().optional().describe("Reassign to a user UUID. Magic strings supported: '@me' (the caller), '@owner' (the account owner). Pass null to unassign."),
+        contactId: z.string().nullable().optional().describe("Link to a contact UUID (null to unlink)"),
+        dealId: z.string().nullable().optional().describe("Link to a deal UUID (null to unlink)"),
+    }, async ({ id, ...updates }) => {
+        const result = await client.patch(`/api/v1/tasks/${id}`, updates);
+        return formatResult(result);
+    });
+    server.tool("conduyt_complete_task", "Mark a task done (the idiomatic 'complete' action). Sets status to 'done', which the server stamps with completedAt and dispatches task.completed automations/webhooks. Requires tasks:edit.", {
+        id: z.string().uuid().describe("Task UUID to mark done"),
+    }, async ({ id }) => {
+        const result = await client.patch(`/api/v1/tasks/${encodeURIComponent(id)}`, { status: "done" });
+        return formatResult(result);
+    });
+    server.tool("conduyt_delete_task", "Delete a task by UUID (hard delete — the task row is removed and a task_deleted activity is logged for audit). There is no undelete endpoint, so treat it as irreversible via the API. Requires tasks:delete.", {
+        id: z.string().uuid().describe("Task UUID to delete"),
+    }, async ({ id }) => {
+        const result = await client.del(`/api/v1/tasks/${encodeURIComponent(id)}`);
+        return formatResult(result);
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt-mcp",
-  "version": "4.6.0",
+  "version": "4.9.0",
   "description": "MCP server for Conduyt CRM — expose CRM operations as AI-accessible tools",
   "type": "module",
   "main": "dist/index.js",
@@ -20,9 +20,10 @@
     "start": "tsx src/index.ts",
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build && ENFORCE=1 node scripts/verify-contracts.mjs",
+    "prepublishOnly": "npm run check:version && npm run build && ENFORCE=1 node scripts/verify-contracts.mjs",
     "audit:contracts": "node scripts/verify-contracts.mjs",
-    "contracts:refresh": "node scripts/refresh-contracts.mjs"
+    "contracts:refresh": "node scripts/refresh-contracts.mjs",
+    "check:version": "node scripts/check-version-sync.mjs"
   },
   "keywords": [
     "mcp",