conduyt-mcp 4.76.0 → 4.78.0

package/README.md

@@ -17,7 +17,9 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 | `conduyt_list_contacts` | List and search contacts with filters |
 | `conduyt_get_contact` | Get full contact details with timeline |
 | `conduyt_create_contact` | Create a new contact |
-| `conduyt_update_contact` | Update contact fields |
+| `conduyt_update_contact` | Update contact fields; optional `expectedRevision` (0..2147483647) refuses a stale save with 409 `contact_changed` (code + current revision in the error) |
+| `conduyt_add_contact_collaborator` | Add a team member as a collaborator (`POST /contacts/{id}/collaborators`); optional `expectedRevision`, 409 `contact_changed` |
+| `conduyt_remove_contact_collaborator` | Remove a collaborator (`DELETE /contacts/{id}/collaborators`, body); optional `expectedRevision`, 409 `contact_changed`, 404 when not a collaborator |
 | `conduyt_add_tags` | Add tags to a contact |
 
 ### Deals
@@ -195,9 +197,19 @@ The Mailchimp OAuth connect and callback are browser-only: connect Mailchimp in
 ### Notifications
 | Tool | Description |
 |------|-------------|
-| `conduyt_list_notifications` | List notifications for current user |
+| `conduyt_list_notifications` | List notifications for current user; `meta.latestByType` is `{type: {latest, count}}` over the last 24 h (newest createdAt + row count per type, read state ignored) next to `unreadCount` / `unreadByType` |
 | `conduyt_create_notification` | Send in-app + push notification to a team member |
 
+### Team Chat
+| Tool | Description |
+|------|-------------|
+| `conduyt_list_chat_channels` | `GET /chat/channels`: your channels; also CREATES your memberships in the auto channels the first time |
+| `conduyt_get_chat_unread` | `GET /chat/unread`: per channel `{ channelId, unread, soundUnread, newestSeq, latestSeq }`; may list an auto channel you have not opened yet (no membership row) |
+| `conduyt_list_chat_messages` | List a channel's messages, newest first; every message carries `seq` (commit-ordered position in the channel); does not move the read marker; on a 403 "Not a member of this channel" it calls `GET /chat/channels` once and retries once |
+| `conduyt_mark_chat_read` | Acknowledge read up to one message (`readUpTo` = message UUID; the marker only moves forward, an older or foreign message is a no-op; same one-retry membership bootstrap) |
+
+The rest of team chat (sending, reactions, pins, presence, uploads) is not wrapped yet; `GET /chat/messages/{messageId}/location` is a UI deep-link helper and deliberately not wrapped.
+
 ### Custom Fields
 | Tool | Description |
 |------|-------------|

package/dist/client.d.ts

@@ -60,7 +60,8 @@ export declare class ConduytClient {
     postText(path: string, body: unknown, opts?: RequestOptions): Promise<string>;
     patch(path: string, body: unknown, opts?: RequestOptions): Promise<unknown>;
     put(path: string, body: unknown, opts?: RequestOptions): Promise<unknown>;
-    del(path: string, opts?: RequestOptions): Promise<unknown>;
+    /** `body` is for the few DELETE routes that take one (contact collaborators with an expectedRevision pin). */
+    del(path: string, opts?: RequestOptions, body?: unknown): Promise<unknown>;
 }
 export declare function formatResult(data: unknown): {
     content: Array<{

package/dist/client.js

@@ -171,7 +171,14 @@ export class ConduytClient {
             // lostReasonOptions) must reach the agent, or a "must be one of the
             // configured options" error is unactionable. Bounded so a pathological
             // body can't bloat the message.
-            const details = Object.fromEntries(Object.entries(json ?? {}).filter(([k]) => k !== "error"));
+            // Scalars first (code, revision), nested objects last (a 409 contact_changed carries the whole current
+            // `contact`): the bound below may cut a large object, never the code or the current revision.
+            const isScalar = (v) => v === null || typeof v !== "object";
+            const entries = Object.entries(json ?? {}).filter(([k]) => k !== "error");
+            const details = Object.fromEntries([
+                ...entries.filter(([, v]) => isScalar(v)),
+                ...entries.filter(([, v]) => !isScalar(v)),
+            ]);
             if (Object.keys(details).length > 0) {
                 msg = `${msg} ${JSON.stringify(details).slice(0, 1000)}`;
             }
@@ -293,8 +300,9 @@ export class ConduytClient {
     put(path, body, opts) {
         return this.request("PUT", path, body, opts);
     }
-    del(path, opts) {
-        return this.request("DELETE", path, undefined, opts);
+    /** `body` is for the few DELETE routes that take one (contact collaborators with an expectedRevision pin). */
+    del(path, opts, body) {
+        return this.request("DELETE", path, body, opts);
     }
 }
 export function formatResult(data) {

package/dist/index.js

@@ -26,6 +26,7 @@ import { registerBoardSettingsTools } from "./tools/board-settings.js";
 import { registerMailchimpTools } from "./tools/mailchimp.js";
 import { registerStatusMetadataTools } from "./tools/status-metadata.js";
 import { registerNotificationTools } from "./tools/notifications.js";
+import { registerChatTools } from "./tools/chat.js";
 import { registerCustomFieldTools } from "./tools/custom-fields.js";
 import { registerSmartListTools } from "./tools/smart-lists.js";
 import { registerUserTools } from "./tools/users.js";
@@ -102,6 +103,7 @@ registerBoardSettingsTools(server, client);
 registerMailchimpTools(server, client);
 registerStatusMetadataTools(server, client);
 registerNotificationTools(server, client);
+registerChatTools(server, client);
 registerCustomFieldTools(server, client);
 registerSmartListTools(server, client);
 registerUserTools(server, client);

package/dist/tools/chat.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConduytClient } from "../client.js";
+/** The messages route's membership refusal (403 "Not a member of this channel"); any other 403 (a permission) is NOT this. */
+export declare function isMembershipRefusal(err: unknown): boolean;
+/** Team chat read side (app 10-09, live sha 3869c79ba): the unread vector, messages carrying `seq`, and the read acknowledgement. */
+export declare function registerChatTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/chat.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { ConduytApiError, formatResult } from "../client.js";
+import { strictInput } from "./strict.js";
+/** The messages route's membership refusal (403 "Not a member of this channel"); any other 403 (a permission) is NOT this. */
+export function isMembershipRefusal(err) {
+    return err instanceof Error && /\b403\b/.test(err.message) && /Not a member of this channel/.test(err.message)
+        && (!(err instanceof ConduytApiError) || err.status === 403);
+}
+/**
+ * GET /chat/unread lists the AUTO channels even when the caller has no membership row yet, while the messages route answers
+ * 403 without one; GET /chat/channels is what lazily creates it. So on that one refusal: call GET /chat/channels ONCE, retry
+ * the read ONCE. Bounded: a second refusal, or a 403 for any other reason, reaches the caller untouched.
+ */
+async function withMembershipBootstrap(client, read) {
+    try {
+        return await read();
+    }
+    catch (err) {
+        if (!isMembershipRefusal(err))
+            throw err;
+        await client.get("/api/v1/chat/channels");
+        return read();
+    }
+}
+/** Team chat read side (app 10-09, live sha 3869c79ba): the unread vector, messages carrying `seq`, and the read acknowledgement. */
+export function registerChatTools(server, client) {
+    strictInput(server.tool("conduyt_list_chat_channels", "List the team chat channels the API key's user belongs to (GET /api/v1/chat/channels): id, name, kind, members, last message, counts. SIDE EFFECT: it also creates the caller's memberships in the account's AUTO channels (needs-a-hand, new-leads, wins) the first time, so a user who never opened Team Chat can read them. conduyt_list_chat_messages and conduyt_mark_chat_read already do this once for you when a channel listed by conduyt_get_chat_unread answers 403 'Not a member of this channel'; call this tool directly to discover channel ids.", {}, async () => {
+        const result = await client.get("/api/v1/chat/channels");
+        return formatResult(result);
+    }));
+    strictInput(server.tool("conduyt_get_chat_unread", "Team chat unread vector for the API key's user (GET /api/v1/chat/unread): one row per channel the user is a member of, { channelId, unread, soundUnread, newestSeq, latestSeq }. unread is the badge count (auto channels are 0 by design); soundUnread counts unread messages in every channel, auto ones included; newestSeq is the seq of the channel's newest message not written by the user (null = none, panic cards left out); latestSeq is the same including panic cards. Read-only: no writes, never creates a membership, so a row can be an AUTO channel the caller has not opened yet (no membership row: reading it first answers 403, which conduyt_list_chat_messages / conduyt_mark_chat_read recover from by calling conduyt_list_chat_channels once and retrying once). Use it to decide which channel to read next, then conduyt_list_chat_messages.", {}, async () => {
+        const result = await client.get("/api/v1/chat/unread");
+        return formatResult(result);
+    }));
+    strictInput(server.tool("conduyt_list_chat_messages", "List messages in a team chat channel (GET /api/v1/chat/channels/{id}/messages), newest first, paged by cursor. The caller must be a channel member (else 403). Every message carries seq, its commit-ordered position inside the channel (a total order: the list and the cursor follow it). Read-only: this tool does not move the read marker. On a 403 'Not a member of this channel' it calls GET /chat/channels once (which creates the caller's auto-channel memberships) and retries ONCE; a second refusal, or a 403 for any other reason, is returned as is; acknowledge with conduyt_mark_chat_read.", {
+        channelId: z.string().uuid().describe("Channel UUID"),
+        limit: z.number().int().min(1).max(100).optional().describe("Messages per page (1-100, default 50)"),
+        cursor: z.string().uuid().optional().describe("nextCursor from the previous page (a message UUID)"),
+    }, async ({ channelId, limit, cursor }) => {
+        const params = new URLSearchParams();
+        if (limit !== undefined)
+            params.set("limit", String(limit));
+        if (cursor !== undefined)
+            params.set("cursor", cursor);
+        const result = await withMembershipBootstrap(client, () => client.get(`/api/v1/chat/channels/${channelId}/messages?${params}`));
+        return formatResult(result);
+    }));
+    strictInput(server.tool("conduyt_mark_chat_read", "Acknowledge team chat as read up to one message (GET /api/v1/chat/channels/{id}/messages?readUpTo=<messageId>&limit=1; the API takes the acknowledgement as a query on the message list). readUpTo is the UUID of a message you were served (its seq becomes your read marker); take it from conduyt_list_chat_messages. The marker only moves FORWARD, never to 'now': an older (stale) message is a no-op, and a message that is not in this channel moves nothing (the call still succeeds, so re-check conduyt_get_chat_unread). A malformed id is a 400. On a 403 'Not a member of this channel' it calls GET /chat/channels once (creating the caller's auto-channel memberships) and retries ONCE; a second refusal, or a 403 for any other reason, is returned as is. The response is the newest message of the channel (limit 1), not a confirmation of the move.", {
+        channelId: z.string().uuid().describe("Channel UUID"),
+        readUpTo: z.string().uuid().describe("UUID of the newest message you have seen in this channel"),
+    }, async ({ channelId, readUpTo }) => {
+        const result = await withMembershipBootstrap(client, () => client.get(`/api/v1/chat/channels/${channelId}/messages?limit=1&readUpTo=${readUpTo}`));
+        return formatResult(result);
+    }));
+}

package/dist/tools/contacts.d.ts

@@ -1,3 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ConduytClient } from "../client.js";
+/** The contact save revision pin (catalog bounds: integer 0..2147483647). */
+export declare const CONTACT_REVISION_MAX = 2147483647;
 export declare function registerContactTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/contacts.js

@@ -1,5 +1,10 @@
 import { z } from "zod";
 import { formatResult } from "../client.js";
+import { strictInput } from "./strict.js";
+/** The contact save revision pin (catalog bounds: integer 0..2147483647). */
+export const CONTACT_REVISION_MAX = 2147483647;
+const CONTACT_CHANGED = "A stale pin is refused with 409 and code contact_changed (nothing written): the error text carries `code`, the contact's CURRENT `revision` and the current `contact`; reload, decide, and call again with that revision (never retry the same pin). A malformed expectedRevision is a 400; only an omitted field means unpinned.";
+const expectedRevision = () => z.number().int().min(0).max(CONTACT_REVISION_MAX).optional().describe("Optimistic-concurrency pin: the contact `revision` as you last read it (conduyt_get_contact / conduyt_list_contacts / a previous change). Omit for last-write-wins per field.");
 /**
  * Accept BOTH the canonical `customFields` and the REST-style `custom_fields`
  * spelling and return the canonical value to send to the API. The MCP SDK
@@ -16,7 +21,7 @@ function resolveCustomFields(camel, snake) {
     return camel !== undefined ? camel : snake;
 }
 export function registerContactTools(server, client) {
-    server.tool("conduyt_list_contacts", "List and search contacts with filtering. Returns paginated results with name, email, phone, tags, source, and assignee.", {
+    server.tool("conduyt_list_contacts", "List and search contacts with filtering. Returns paginated results with name, email, phone, tags, source, and assignee. Each row carries `revision` (integer save revision; pass it back as expectedRevision on conduyt_update_contact or the collaborator tools).", {
         search: z.string().optional().describe("Search by name, email, or phone number"),
         tag: z.string().optional().describe("Filter by tag name"),
         source: z.string().optional().describe("Filter by source (e.g. 'signup', 'import', 'manual')"),
@@ -46,7 +51,7 @@ export function registerContactTools(server, client) {
         const result = await client.get(`/api/v1/contacts?${params}`);
         return formatResult(result);
     });
-    server.tool("conduyt_get_contact", "Get a single contact with full details — profile, tags, custom fields, timeline, deals, and activity history.", {
+    server.tool("conduyt_get_contact", "Get a single contact with full details — profile, tags, custom fields, timeline, deals, and activity history. Includes `revision` (integer save revision): pass it as expectedRevision on conduyt_update_contact or the collaborator tools so a newer change is never overwritten.", {
         id: z.string().describe("Contact UUID"),
     }, async ({ id }) => {
         const result = await client.get(`/api/v1/contacts/${id}`);
@@ -70,7 +75,7 @@ export function registerContactTools(server, client) {
         const result = await client.post("/api/v1/contacts", body);
         return formatResult(result);
     });
-    server.tool("conduyt_update_contact", "Update an existing contact's fields — name, email, phone, company, custom fields. customFields merge into existing values (omit a key to leave it unchanged).", {
+    strictInput(server.tool("conduyt_update_contact", "Update an existing contact's fields — name, email, phone, company, custom fields. customFields merge into existing values (omit a key to leave it unchanged). Pass expectedRevision (the contact's `revision` as you read it) to refuse the save when the contact changed since. " + CONTACT_CHANGED, {
         id: z.string().describe("Contact UUID"),
         email: z.string().optional().describe("Updated email"),
         firstName: z.string().optional().describe("Updated first name"),
@@ -82,12 +87,29 @@ export function registerContactTools(server, client) {
         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."),
+        expectedRevision: expectedRevision(),
     }, async ({ id, customFields, custom_fields, ...updates }) => {
         const cf = resolveCustomFields(customFields, custom_fields);
         const body = cf !== undefined ? { ...updates, customFields: cf } : updates;
         const result = await client.patch(`/api/v1/contacts/${id}`, body);
         return formatResult(result);
-    });
+    }));
+    strictInput(server.tool("conduyt_add_contact_collaborator", "Add a team member as a collaborator on a contact (POST /api/v1/contacts/{id}/collaborators; needs edit authority over the contact). Answers { added, revision } where revision is the contact's NEW revision. Pass expectedRevision to refuse the change when the contact changed since you read it. " + CONTACT_CHANGED + " 409 without a code: the user is already a collaborator; 404: no such contact for you or no edit authority; 413: body over 16 KB.", {
+        contactId: z.string().uuid().describe("Contact UUID"),
+        userId: z.string().min(1).describe("The team member to add"),
+        expectedRevision: expectedRevision(),
+    }, async ({ contactId, userId, expectedRevision }) => {
+        const result = await client.post(`/api/v1/contacts/${encodeURIComponent(contactId)}/collaborators`, { userId, expectedRevision });
+        return formatResult(result);
+    }));
+    strictInput(server.tool("conduyt_remove_contact_collaborator", "Remove a collaborator from a contact (DELETE /api/v1/contacts/{id}/collaborators with a body; needs edit authority). Answers { removed, revision } where revision is the contact's NEW revision. Pass expectedRevision to refuse the change when the contact changed since you read it. " + CONTACT_CHANGED + " 404 also when the user is not a collaborator of the contact; 409 without a code: the user is still the assignee of a deal or hosts an appointment on this contact; 413: body over 16 KB.", {
+        contactId: z.string().uuid().describe("Contact UUID"),
+        userId: z.string().min(1).describe("The team member to remove"),
+        expectedRevision: expectedRevision(),
+    }, async ({ contactId, userId, expectedRevision }) => {
+        const result = await client.del(`/api/v1/contacts/${encodeURIComponent(contactId)}/collaborators`, undefined, { userId, expectedRevision });
+        return formatResult(result);
+    }));
     server.tool("conduyt_delete_contact", "Delete a contact by UUID (soft-delete — the contact is removed from lists/searches but the row is retained for audit, and its deals are unaffected). Use this to clean up test or duplicate contacts. There is no undelete endpoint, so treat it as irreversible via the API.", {
         // .uuid() so a malformed id with slashes can't form a different DELETE
         // subroute (e.g. /contacts/:id/tags/:tagId); encode the segment too.

package/dist/tools/notifications.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { formatResult } from "../client.js";
 export function registerNotificationTools(server, client) {
-    server.tool("conduyt_list_notifications", "List notifications for the current user (determined by API key's associated user).", {
+    server.tool("conduyt_list_notifications", "List notifications for the current user (determined by API key's associated user). The response meta carries page, per_page, total, unreadCount, unreadByType ({type: count}) and latestByType ({type: {latest, count}}: per type over the last 24 hours, the newest createdAt as an ISO string and the row count, read state ignored; a poller sees a type advance when latest moves or count rises).", {
         page: z.number().optional().describe("Page number (default 1)"),
         per_page: z.number().optional().describe("Results per page"),
     }, async ({ page, per_page }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt-mcp",
-  "version": "4.76.0",
+  "version": "4.78.0",
   "mcpName": "com.conduyt/mcp",
   "description": "MCP server for Conduyt CRM — expose CRM operations as AI-accessible tools",
   "type": "module",

package/scripts/coverage-manifest.json

@@ -115,6 +115,11 @@
       "status": "planned",
       "reason": "file listing/metadata is agent-useful; upload stays browser-side"
     },
+    {
+      "match": "GET /api/v1/chat/messages/",
+      "status": "excluded",
+      "reason": "UI-only deep-link helper (resolves a message to its channel/position for the app's router); not an agent surface"
+    },
     {
       "match": "/api/v1/chat",
       "status": "planned",

package/scripts/coverage-matrix.json

@@ -1,11 +1,11 @@
 {
-  "generatedAt": "2026-10-09T01:29:38.747Z",
-  "toolCount": 328,
-  "totalEndpoints": 1064,
+  "generatedAt": "2026-10-09T04:00:29.593Z",
+  "toolCount": 334,
+  "totalEndpoints": 1066,
   "counts": {
-    "covered": 294,
-    "excluded": 318,
-    "planned": 452,
+    "covered": 299,
+    "excluded": 319,
+    "planned": 448,
     "uncategorized": 0
   },
   "matrix": {
@@ -1235,8 +1235,10 @@
       "reason": "team chat read/post for agents"
     },
     "GET /api/v1/chat/channels": {
-      "status": "planned",
-      "reason": "team chat read/post for agents"
+      "status": "covered",
+      "tools": [
+        "conduyt_list_chat_channels"
+      ]
     },
     "POST /api/v1/chat/channels": {
       "status": "planned",
@@ -1251,8 +1253,11 @@
       "reason": "team chat read/post for agents"
     },
     "GET /api/v1/chat/channels/:id/messages": {
-      "status": "planned",
-      "reason": "team chat read/post for agents"
+      "status": "covered",
+      "tools": [
+        "conduyt_list_chat_messages",
+        "conduyt_mark_chat_read"
+      ]
     },
     "POST /api/v1/chat/channels/:id/messages": {
       "status": "planned",
@@ -1318,6 +1323,10 @@
       "status": "planned",
       "reason": "team chat read/post for agents"
     },
+    "GET /api/v1/chat/messages/:messageId/location": {
+      "status": "excluded",
+      "reason": "UI-only deep-link helper (resolves a message to its channel/position for the app's router); not an agent surface"
+    },
     "GET /api/v1/chat/presence": {
       "status": "planned",
       "reason": "team chat read/post for agents"
@@ -1326,6 +1335,12 @@
       "status": "planned",
       "reason": "team chat read/post for agents"
     },
+    "GET /api/v1/chat/unread": {
+      "status": "covered",
+      "tools": [
+        "conduyt_get_chat_unread"
+      ]
+    },
     "GET /api/v1/companies": {
       "status": "covered",
       "tools": [
@@ -1450,12 +1465,16 @@
       "reason": "contact subroutes beyond the core CRUD/search tools"
     },
     "POST /api/v1/contacts/:id/collaborators": {
-      "status": "planned",
-      "reason": "contact subroutes beyond the core CRUD/search tools"
+      "status": "covered",
+      "tools": [
+        "conduyt_add_contact_collaborator"
+      ]
     },
     "DELETE /api/v1/contacts/:id/collaborators": {
-      "status": "planned",
-      "reason": "contact subroutes beyond the core CRUD/search tools"
+      "status": "covered",
+      "tools": [
+        "conduyt_remove_contact_collaborator"
+      ]
     },
     "GET /api/v1/contacts/:id/dnc": {
       "status": "planned",