conduyt-mcp 4.100.0 → 4.102.0

package/README.md

@@ -2,7 +2,7 @@
 
 MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-accessible tools. Covers the core CRM surface (contacts, deals, pipelines, custom fields, automations, messaging, and more); use `conduyt_api_catalog` to discover the full set of 600+ REST endpoints.
 
-## 299 Tools
+## 372 Tools
 
 ### Discovery
 | Tool | Description |
@@ -14,7 +14,7 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 ### Contacts
 | Tool | Description |
 |------|-------------|
-| `conduyt_list_contacts` | List and search contacts with filters |
+| `conduyt_list_contacts` | List and search contacts with filters (search, exact `email`, `tag` names, `tagId` uuids: ANY-of, repeatable up to 20, `meta.total` counts the filtered set) |
 | `conduyt_get_contact` | Get full contact details with timeline; `hasOutboundSms` = the workspace has ever provably texted the contact; `hasOutboundEmail` = the same for email; `duplicateProposals` and `heldIdentifiers` = the open possible-duplicate lines and held identifiers |
 | `conduyt_create_contact` | Create a new contact (a 409 with `existingId`, `rule`, `ruleVersion`, `matchedOn`, `reason` means the identity policy identified the incoming person with that record: confirm the identity (name, company) before updating it, a shared phone or email is not proof, and the server creates (with a passive duplicate proposal) a different person on a shared identifier; 409 `identifier_changed` / `owner_busy` and 503 `IDENTITY_INDEX_NOT_READY` are retryable, nothing written; with `callId`: the lead for a contact-less inbound call, linked in the same transaction; the server derives source "Inbound Call" and the owner) |
 | `conduyt_update_contact` | Update contact fields (incl. `assignedTo`; `keepPreviousOwnerAsCollaborator: true` with a reassignment keeps the previous owner as a read-only collaborator instead of releasing them, 400 without `assignedTo`); optional `expectedRevision` (0..2147483647) refuses a stale save with 409 `contact_changed` (code + current revision in the error) |
@@ -37,6 +37,7 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 | `conduyt_get_calling_hours` / `conduyt_update_calling_hours` | Read the window the dialer enforces (`effectiveCallingWindow`: `source`, `enabled`, `start`/`end` HH:MM, `timezone` or null = contact zone, then number area code, then account) / set `settings.callingWindow` (`enabled`, `start`, `end` always sent, `end` after `start`, `timezone` trimmed and recognised by the API (omit keeps the stored zone, null clears it); `enabled: false` needs `acknowledgeAnyHour: true`, else 400 `calling_hours_acknowledgement_required`) |
 | `conduyt_list_email_opt_outs` / `conduyt_add_email_opt_out` / `conduyt_resubscribe_email_opt_out` | The email opt-out list (owner / admin key; hash-only rows `{ id, source, reason, createdAt }`): list (`page`, `perPage` 1-100), add an address by hand (`reason` 1-200 required; 201 new row, 200 when an unsubscribe-link or Mailchimp row is promoted to manual, 409 with the existing row when already listed by hand) and take an address off (`{ removed }`) |
 | `conduyt_get_my_profile` | Read the caller's own identity (`GET /users/me`, same as `/auth/me`): `data.user` incl. `ringtone` (the incoming-ring slug, null = Conduyt Default), `data.account`, role, permissions, `apiKey`, `accounts`. Editing the profile is a signed-in person's action and is not exposed to API keys |
+| `conduyt_create_file_upload_intent` / `conduyt_finalize_file_upload` / `conduyt_create_chat_upload_intent` / `conduyt_finalize_chat_upload` / `conduyt_upload_local_file` / `conduyt_upload_chat_attachment` | Direct-to-storage uploads (#565): intent (`POST /files/upload/intent`, `POST /chat/channels/{id}/upload/intent`; `fileName`, `size`, optional `contentType`) returns a signed PUT URL, the bytes go straight to storage, finalize (`.../finalize`, `{ uploadId }`) settles it. CRM files up to 50 MB (key scope `files`), Team Chat attachments up to 10 MB (key scope `chat`). `conduyt_upload_local_file` / `conduyt_upload_chat_attachment` do all three steps for a local path and refuse an over-cap or empty file before any call (413 wording `File is too large (12 MB). Maximum allowed: 10 MB.`). Finalize refusals, verbatim: 400 `upload_id_required`, 404 `upload_not_found`, 409 `upload_incomplete` (bytes never PUT), 409 `upload_in_progress`, 413 `file_too_large`, 422 `upload_size_mismatch`, 400/415 `file_rejected`, 429, 503 `uploads_unavailable`; finalize allows 120 s. Only a finalize 409 `upload_in_progress` is repeated (at most 4 total attempts) |
 | `conduyt_create_short_link` | Make (or reuse) the workspace's Conduyt short link for a public link-shortener address the Message check flagged (`POST /short-links`, body `{ url }`; key needs the `messages` scope, member needs communications.create). Not shortenable: our own host, merge fields, `mailto:`/`tel:`/`sms:`, or any address the Message check does not flag as a link shortener (400 `not_shortenable`). Other errors verbatim, never retried: 400 `invalid_body`, 403 `forbidden`, 413 `body_too_large`, 429 `rate_limited` (with Retry-After), 503 `short_link_unavailable` (nothing changed) |
 | `conduyt_get_deal_card_fields` / `conduyt_set_deal_card_fields` | Read / replace the kanban card fields (1-8, built-ins or `custom:<fieldKey>`) |
 | `conduyt_get_settings_revision` | The account `settingsRevision` (plus stored stage rules and rot days): pass it as `expectedSettingsRevision` to `conduyt_archive_pipeline` / `conduyt_delete_stage` so a stale one is refused 409 `stale_settings_revision` |
@@ -397,7 +398,7 @@ A refused call (HTTP 4xx/5xx) fails the tool with this text, stable across tools
 Conduyt API <status>: <server message>[ [Retry-After: <N>s]][ <details>]
 ```
 
-`[Retry-After: Ns]` appears only when the server sent the header (shown, never acted on: a mutation is never retried).
+`[Retry-After: Ns]` appears only when the server sent the header (shown, never acted on: a mutation is never retried; the one exception is the finalize POST of the upload convenience tools `conduyt_upload_local_file` and `conduyt_upload_chat_attachment`: on a 409 `upload_in_progress` only, at most 4 total attempts, the Retry-After is honoured (capped at 10 s, 5 s when absent or unreadable); finalize is idempotent on the server for the same upload id, so a repeat cannot double-finalize).
 `<details>` appears only when the body had more than `error`: it is ONE JSON object and the FINAL token. To extract it, try
 each `{` from the left until the rest of the text parses as JSON (a server message may itself contain a brace). The object
 carries scalars first (`code`, revision), then nested objects whole; `HealthFixRefusal.row` is always whole, any other nested

package/dist/client.d.ts

@@ -12,7 +12,7 @@ export declare class ConduytApiError extends Error {
     readonly code: "http" | "timeout" | "response_too_large" | "network";
     readonly retryable: boolean;
     /** The response's Retry-After, in seconds, when it sent one (a busy 503 / a 429): surfaced to the agent, never used
-     *  to replay a mutation. */
+     *  to replay a mutation. Exception (finalize of the convenience upload tools/commands only): on a 409 upload_in_progress the finalize POST is repeated, at most 4 total attempts, the Retry-After honoured and capped at 10 s, 5 s when absent or unreadable. */
     readonly retryAfterSeconds: number | null;
     constructor(opts: {
         message: string;

package/dist/client.js

@@ -11,7 +11,7 @@ export class ConduytApiError extends Error {
     code;
     retryable;
     /** The response's Retry-After, in seconds, when it sent one (a busy 503 / a 429): surfaced to the agent, never used
-     *  to replay a mutation. */
+     *  to replay a mutation. Exception (finalize of the convenience upload tools/commands only): on a 409 upload_in_progress the finalize POST is repeated, at most 4 total attempts, the Retry-After honoured and capped at 10 s, 5 s when absent or unreadable. */
     retryAfterSeconds;
     constructor(opts) {
         super(opts.message, opts.cause !== undefined ? { cause: opts.cause } : undefined);

package/dist/register-all.js

@@ -33,6 +33,7 @@ import { registerBatchOperationTools } from "./tools/batch-operations.js";
 import { registerDncTools } from "./tools/dnc.js";
 import { registerEmailOptOutTools } from "./tools/email-opt-out.js";
 import { registerShortLinkTools } from "./tools/short-links.js";
+import { registerDirectUploadTools } from "./tools/direct-uploads.js";
 import { registerMyProfileTools } from "./tools/my-profile.js";
 import { registerSavedFilterTools } from "./tools/saved-filters.js";
 import { registerDripCampaignTools } from "./tools/drip-campaigns.js";
@@ -94,6 +95,7 @@ export function registerAllTools(server, client) {
     registerDncTools(server, client);
     registerEmailOptOutTools(server, client);
     registerShortLinkTools(server, client);
+    registerDirectUploadTools(server, client);
     registerMyProfileTools(server, client);
     registerSavedFilterTools(server, client);
     registerDripCampaignTools(server, client);

package/dist/tool-annotations.js

@@ -222,6 +222,12 @@ export const TOOL_ANNOTATIONS = {
     conduyt_add_email_opt_out: update("Add Email Opt-Out"), // a repeat is refused 409 (already listed by hand) before any write, so it lands on the same state; adding a block is protective
     conduyt_resubscribe_email_opt_out: destroy("Resubscribe Email Address"), // consent change: removing the row re-enables every customer-facing email to the address
     conduyt_get_my_profile: ro("Get My Profile"),
+    conduyt_create_file_upload_intent: create("Create File Upload Intent"), // mints a pending upload record and a signed PUT target; each call is a new upload id
+    conduyt_finalize_file_upload: update("Finalize File Upload"), // finalizing the same upload again answers the same body
+    conduyt_create_chat_upload_intent: create("Create Chat Upload Intent"),
+    conduyt_finalize_chat_upload: update("Finalize Chat Upload"), // finalizing again answers the same body
+    conduyt_upload_local_file: create("Upload Local File"), // reads a local file and PUTs it to the signed storage URL; each call stores a new file
+    conduyt_upload_chat_attachment: create("Upload Chat Attachment"),
     conduyt_create_short_link: update("Create Short Link"), // one link per account and target: a repeat returns the same link (idempotent), nothing existing is changed
     conduyt_list_saved_filters: ro("List Saved Filters"),
     conduyt_create_saved_filter: create("Create Saved Filter"),

package/dist/tools/contacts.d.ts

@@ -20,4 +20,6 @@ export declare const LOSER_ORDER_NOTE = "losers are merged in the order given: f
 export declare const MERGE_PREVIEW_MAX = 50;
 export declare const MERGE_PREVIEW_TTL_MS: number;
 export declare const EMAIL_LOOKUP_NOTE = "Exact email lookup: one address, or up to 20 distinct addresses in an array. Each is trimmed and lower-cased and matches the contact's primary email OR any secondary email slot (email_2 and up); it is an exact match, not a substring search (use `search` for partial text). Combines with every other filter (AND) inside your account and visibility. An empty or invalid address, or more than 20 distinct addresses, is a 400. On a workspace whose identifier index is still being built, the lookup answers 422 when the stored spellings of the requested addresses exceed its stored-spelling bind budget (a count of spellings, not of contacts; other filters do not help); ask support to complete the identifier backfill. Send addresses once; duplicates collapse.";
+export declare const TAG_FILTER_NOTE = "Filter by tag NAME: one name, or up to 20 distinct names in an array (the contact carries ANY of them). Names match case-insensitively within your account. Cannot be combined with tagId (400). To filter by tag id use tagId.";
+export declare const TAG_ID_FILTER_NOTE = "Filter by tag ID (uuid): one id, or up to 20 distinct ids in an array (the contact carries ANY of them). A malformed id or more than 20 ids is a 400; an id that is not a tag of your account matches nothing; a merged-away tag id follows its alias to the live tag. Cannot be combined with tag (400). The returned total (meta.total) counts the filtered set, so tagId with per_page=1 is a cheap count of the contacts holding a tag.";
 export declare function registerContactTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/contacts.js

@@ -70,27 +70,35 @@ function createMergePreviewStore() {
 /** (API ?email=, app main 318adf38d) exact lookup of one address; the API trims and lower-cases, so a stray space is harmless */
 const EMAIL_LOOKUP_ONE = z.string().trim().min(1).max(254);
 export const EMAIL_LOOKUP_NOTE = "Exact email lookup: one address, or up to 20 distinct addresses in an array. Each is trimmed and lower-cased and matches the contact's primary email OR any secondary email slot (email_2 and up); it is an exact match, not a substring search (use `search` for partial text). Combines with every other filter (AND) inside your account and visibility. An empty or invalid address, or more than 20 distinct addresses, is a 400. On a workspace whose identifier index is still being built, the lookup answers 422 when the stored spellings of the requested addresses exceed its stored-spelling bind budget (a count of spellings, not of contacts; other filters do not help); ask support to complete the identifier backfill. Send addresses once; duplicates collapse.";
+/** (API ?tag= / ?tagId=, #506) both are repeatable and capped at 20 distinct values; the API reads every occurrence (ANY-of) and refuses tagId together with tag */
+const TAG_FILTER_MAX = 20;
+export const TAG_FILTER_NOTE = "Filter by tag NAME: one name, or up to 20 distinct names in an array (the contact carries ANY of them). Names match case-insensitively within your account. Cannot be combined with tagId (400). To filter by tag id use tagId.";
+export const TAG_ID_FILTER_NOTE = "Filter by tag ID (uuid): one id, or up to 20 distinct ids in an array (the contact carries ANY of them). A malformed id or more than 20 ids is a 400; an id that is not a tag of your account matches nothing; a merged-away tag id follows its alias to the live tag. Cannot be combined with tag (400). The returned total (meta.total) counts the filtered set, so tagId with per_page=1 is a cheap count of the contacts holding a tag.";
 export function registerContactTools(server, client) {
     const mergePreviews = createMergePreviewStore();
-    server.tool("conduyt_list_contacts", "List and search contacts with filtering. To find the contact(s) holding a known email address, pass `email` (exact match on the primary or any secondary email); `search` is a substring search. 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).", {
+    server.tool("conduyt_list_contacts", "List and search contacts with filtering. To find the contact(s) holding a known email address, pass `email` (exact match on the primary or any secondary email); `search` is a substring search. To list the contacts carrying a tag (or any of several tags), pass `tagId` (uuid) or `tag` (name); meta.total is the count of that filtered set. 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"),
         email: z.union([EMAIL_LOOKUP_ONE, z.array(EMAIL_LOOKUP_ONE).min(1).max(20)]).optional().describe(EMAIL_LOOKUP_NOTE),
-        tag: z.string().optional().describe("Filter by tag name"),
+        tag: z.union([z.string().trim().min(1), z.array(z.string().trim().min(1)).min(1).max(TAG_FILTER_MAX)]).optional().describe(TAG_FILTER_NOTE),
+        tagId: z.union([z.string().trim().uuid(), z.array(z.string().trim().uuid()).min(1).max(TAG_FILTER_MAX)]).optional().describe(TAG_ID_FILTER_NOTE),
         source: z.string().optional().describe("Filter by source (e.g. 'signup', 'import', 'manual')"),
         assignedTo: z.string().optional().describe("Filter by assigned user ID"),
         masterStatus: z.array(z.string().trim().min(1).max(40)).max(20).optional().describe("Only contacts whose LEAD (master) status is one of these: 'open', 'won', 'lost', 'abandoned', 'disqualified' or an account custom status. Unknown values are a 400."),
         excludeMasterStatus: z.array(z.string().trim().min(1).max(40)).max(20).optional().describe("Hide contacts whose lead status is one of these — e.g. ['won','lost','abandoned','disqualified'] is the 'Active' view. Naming a status in both lists is a 400."),
         page: z.number().optional().describe("Page number (default 1)"),
         per_page: z.number().optional().describe("Results per page (default 25, max 100)"),
-    }, async ({ search, email, tag, source, assignedTo, masterStatus, excludeMasterStatus, page, per_page }) => {
+    }, async ({ search, email, tag, tagId, source, assignedTo, masterStatus, excludeMasterStatus, page, per_page }) => {
         const params = new URLSearchParams();
         if (search)
             params.set("search", search);
         // repeated `email` params, one per address (the API reads every occurrence); an omitted or empty array sends none
         for (const address of email === undefined ? [] : Array.isArray(email) ? email : [email])
             params.append("email", address);
-        if (tag)
-            params.set("tag", tag);
+        // repeated `tag` / `tagId` params, one per value (the API reads every occurrence and refuses the two together)
+        for (const name of tag === undefined ? [] : Array.isArray(tag) ? tag : [tag])
+            params.append("tag", name);
+        for (const id of tagId === undefined ? [] : Array.isArray(tagId) ? tagId : [tagId])
+            params.append("tagId", id);
         if (source)
             params.set("source", source);
         if (assignedTo)

package/dist/tools/direct-uploads.d.ts

@@ -0,0 +1,41 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConduytClient } from "../client.js";
+/**
+ * Direct-to-storage uploads (#565; app routes POST /api/v1/files/upload/intent + /finalize and
+ * POST /api/v1/chat/channels/{id}/upload/intent + /finalize). The bytes go straight to the signed storage URL; the API never
+ * carries the file. The four routes are exposed one to one, plus ONE convenience tool per surface that runs the whole flow
+ * (intent, PUT the bytes of a local file, finalize). Every API call is sent once: a refusal reaches the agent verbatim.
+ * The only repeat is finalize on 409 upload_in_progress, which the API documents as retryable (finalizing again answers the
+ * same body), and only inside the convenience tools.
+ */
+/** the app's caps (lib/file-upload-policy.ts CRM_FILE_MAX_BYTES, lib/chat-upload-policy.ts CHAT_UPLOAD_MAX_BYTES) */
+export declare const FILE_UPLOAD_MAX_BYTES: number;
+export declare const CHAT_UPLOAD_MAX_BYTES: number;
+export declare const tooLargeMessage: (size: number, max: number) => string;
+/** both app finalize routes set maxDuration = 120 (finalize reads the staged object back and rewrites it), above the client's 30 s default */
+export declare const FINALIZE_TIMEOUT_MS = 120000;
+/** finalize retry on 409 upload_in_progress: exactly `attempts` calls; between them the refusal's Retry-After (capped at maxDelayMs)
+ *  or, when it sent none or an unreadable one, delayMs. `sleep` is module state so tests can spy on the scheduled delay. */
+export declare const finalizeRetry: {
+    attempts: number;
+    delayMs: number;
+    maxDelayMs: number;
+    sleep: (ms: number) => Promise<unknown>;
+};
+/** the milliseconds to wait before finalizing again; pure */
+export declare function finalizeWaitMs(err: unknown): number;
+/** Everything the end-to-end tools do after the argument checks; exported for the tests. */
+export declare function runDirectUpload(client: ConduytClient, o: {
+    intentPath: string;
+    finalizePath: string;
+    maxBytes: number;
+    filePath: string;
+    fileName?: string;
+    contentType?: string;
+}): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+export declare function registerDirectUploadTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/direct-uploads.js

@@ -0,0 +1,113 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { z } from "zod";
+import { formatResult, formatToolError } from "../client.js";
+import { strictInput } from "./strict.js";
+/**
+ * Direct-to-storage uploads (#565; app routes POST /api/v1/files/upload/intent + /finalize and
+ * POST /api/v1/chat/channels/{id}/upload/intent + /finalize). The bytes go straight to the signed storage URL; the API never
+ * carries the file. The four routes are exposed one to one, plus ONE convenience tool per surface that runs the whole flow
+ * (intent, PUT the bytes of a local file, finalize). Every API call is sent once: a refusal reaches the agent verbatim.
+ * The only repeat is finalize on 409 upload_in_progress, which the API documents as retryable (finalizing again answers the
+ * same body), and only inside the convenience tools.
+ */
+/** the app's caps (lib/file-upload-policy.ts CRM_FILE_MAX_BYTES, lib/chat-upload-policy.ts CHAT_UPLOAD_MAX_BYTES) */
+export const FILE_UPLOAD_MAX_BYTES = 50 * 1024 * 1024;
+export const CHAT_UPLOAD_MAX_BYTES = 10 * 1024 * 1024;
+/** the app's own wording (lib/direct-upload.ts mb()) so a client-side refusal reads the same as the server's 413 */
+const mb = (bytes) => `${Math.round((bytes / 1024 / 1024) * 10) / 10} MB`;
+export const tooLargeMessage = (size, max) => `File is too large (${mb(size)}). Maximum allowed: ${mb(max)}.`;
+/** both app finalize routes set maxDuration = 120 (finalize reads the staged object back and rewrites it), above the client's 30 s default */
+export const FINALIZE_TIMEOUT_MS = 120_000;
+/** finalize retry on 409 upload_in_progress: exactly `attempts` calls; between them the refusal's Retry-After (capped at maxDelayMs)
+ *  or, when it sent none or an unreadable one, delayMs. `sleep` is module state so tests can spy on the scheduled delay. */
+export const finalizeRetry = {
+    attempts: 4,
+    delayMs: 5000,
+    maxDelayMs: 10_000,
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+};
+/** the milliseconds to wait before finalizing again; pure */
+export function finalizeWaitMs(err) {
+    const ra = err?.retryAfterSeconds;
+    return typeof ra === "number" && Number.isFinite(ra) && ra >= 0 ? Math.min(ra * 1000, finalizeRetry.maxDelayMs) : finalizeRetry.delayMs;
+}
+const unwrap = (r) => (r && typeof r === "object" && "data" in r ? r.data : r);
+const FILE_SCOPE = "an API key needs the 'files' scope and the member files.create";
+const CHAT_SCOPE = "an API key needs the 'chat' scope and the member communications.create and membership of the channel";
+const INTENT_ERRORS = "Errors, surfaced verbatim and never retried: 400 file_name_required / file_type_not_allowed / file_size_required / file_empty; 413 file_too_large; 429 (rate limited, Retry-After in the error); 503 uploads_unavailable (nothing changed).";
+const FINALIZE_ERRORS = "Errors, surfaced verbatim: 400 upload_id_required; 404 upload_not_found (malformed, unknown, expired or someone else's upload: upload again); 409 upload_incomplete (the bytes were never PUT, or not all of them: upload again; not retried); 409 upload_in_progress (still being saved: finalize again, same body); 413 file_too_large (the stored object is over the cap); 422 upload_size_mismatch (the stored size is not the declared one: upload again); 400/415 file_rejected (the content check refused the bytes; the status and message are the check's); 429 (rate limited, Retry-After in the error); 503 uploads_unavailable (try again shortly). Finalize allows 120 seconds.";
+/** Everything the end-to-end tools do after the argument checks; exported for the tests. */
+export async function runDirectUpload(client, o) {
+    const abs = resolve(o.filePath);
+    let st;
+    try {
+        st = await stat(abs);
+    }
+    catch {
+        return formatToolError(`Cannot read '${o.filePath}': no such file. Nothing was uploaded.`);
+    }
+    if (!st.isFile())
+        return formatToolError(`'${o.filePath}' is not a regular file. Nothing was uploaded.`);
+    // the size cap is checked BEFORE the intent call, with the server's wording
+    if (st.size === 0)
+        return formatToolError("The file is empty.");
+    if (st.size > o.maxBytes)
+        return formatToolError(tooLargeMessage(st.size, o.maxBytes));
+    const body = { fileName: o.fileName ?? basename(abs), size: st.size };
+    if (o.contentType !== undefined)
+        body.contentType = o.contentType;
+    const intent = unwrap(await client.post(o.intentPath, body));
+    // the bytes go to the signed URL as-is: NO Authorization header (the URL is the credential), exactly the declared length and type
+    let put;
+    try {
+        put = await fetch(intent.uploadUrl, {
+            method: intent.method || "PUT",
+            headers: { "Content-Type": intent.contentType, "Content-Length": String(st.size) },
+            body: Readable.toWeb(createReadStream(abs)),
+            duplex: "half",
+            signal: AbortSignal.timeout(Math.max(1, intent.expiresIn) * 1000),
+        });
+    }
+    catch (err) {
+        return formatToolError(`Storage upload failed before finalize (${err?.message ?? String(err)}). Nothing was saved; call this tool again (the upload id ${intent.uploadId} is abandoned).`);
+    }
+    if (!put.ok) {
+        return formatToolError(`Storage refused the upload (HTTP ${put.status}). Nothing was saved; call this tool again (the upload id ${intent.uploadId} is abandoned).`);
+    }
+    for (let attempt = 1;; attempt++) {
+        try {
+            return formatResult(await client.post(o.finalizePath, { uploadId: intent.uploadId }, { timeoutMs: FINALIZE_TIMEOUT_MS }));
+        }
+        catch (err) {
+            const inProgress = err?.status === 409 && /upload_in_progress/.test(err.message);
+            if (!inProgress || attempt >= finalizeRetry.attempts)
+                throw err;
+            await finalizeRetry.sleep(finalizeWaitMs(err));
+        }
+    }
+}
+export function registerDirectUploadTools(server, client) {
+    const fileNameField = z.string().min(1).describe("File name with its extension, e.g. contract.pdf (the extension decides the allowed type)");
+    const contentTypeField = z.string().optional().describe("MIME type; omit to let the API infer it from the file name");
+    const sizeField = z.number().int().positive().describe("Exact size of the file in bytes");
+    const uploadIdField = z.string().uuid().describe("uploadId from the intent call, after its bytes were PUT");
+    const channelField = z.string().uuid().describe("Team Chat channel UUID (you must be a member)");
+    strictInput(server.tool("conduyt_create_file_upload_intent", `Step 1 of a direct-to-storage CRM file upload, up to 50 MB (POST /api/v1/files/upload/intent; ${FILE_SCOPE}). Answers 201 { uploadId, uploadUrl, method: "PUT", contentType, size, expiresIn, maxBytes }: PUT exactly 'size' bytes to uploadUrl with Content-Type: contentType within expiresIn seconds (no Authorization header), then call conduyt_finalize_file_upload. This tool does not move bytes; to upload a local file in one step use conduyt_upload_local_file. ${INTENT_ERRORS}`, { fileName: fileNameField, contentType: contentTypeField, size: sizeField }, async ({ fileName, contentType, size }) => formatResult(await client.post("/api/v1/files/upload/intent", { fileName, contentType, size }))));
+    strictInput(server.tool("conduyt_finalize_file_upload", `Step 3 of a direct-to-storage CRM file upload (POST /api/v1/files/upload/finalize; ${FILE_SCOPE}). The stored object must be present and exactly the declared size; its bytes are judged by content, then settled. Answers 201 { uploadId, filename, size, contentType}, the same body as the multipart upload; the uploadId is then attached with POST /api/v1/files { entityType, entityId, uploadId }. Finalizing the same upload again answers the same body. ${FINALIZE_ERRORS}`, { uploadId: uploadIdField }, async ({ uploadId }) => formatResult(await client.post("/api/v1/files/upload/finalize", { uploadId }, { timeoutMs: FINALIZE_TIMEOUT_MS }))));
+    strictInput(server.tool("conduyt_create_chat_upload_intent", `Step 1 of a direct-to-storage Team Chat attachment, up to 10 MB (POST /api/v1/chat/channels/{id}/upload/intent; ${CHAT_SCOPE}). Answers 201 { uploadId, uploadUrl, method: "PUT", contentType, size, expiresIn, maxBytes }: PUT exactly 'size' bytes to uploadUrl with Content-Type: contentType within expiresIn seconds (no Authorization header), then call conduyt_finalize_chat_upload. This tool does not move bytes; to upload a local file in one step use conduyt_upload_chat_attachment. A deal channel is 404 for a key without the deals scope; a non-member gets 403. ${INTENT_ERRORS}`, { channelId: channelField, fileName: fileNameField, contentType: contentTypeField, size: sizeField }, async ({ channelId, fileName, contentType, size }) => formatResult(await client.post(`/api/v1/chat/channels/${channelId}/upload/intent`, { fileName, contentType, size }))));
+    strictInput(server.tool("conduyt_finalize_chat_upload", `Step 3 of a direct-to-storage Team Chat attachment (POST /api/v1/chat/channels/{id}/upload/finalize; ${CHAT_SCOPE}). Answers 201 { url, name, size, type }, the same body as the multipart upload: send it in a message's metadata.attachments. A message that claims an attachment that was never finalized is refused 409 attachment_unavailable. Finalizing again answers the same body. ${FINALIZE_ERRORS}`, { channelId: channelField, uploadId: uploadIdField }, async ({ channelId, uploadId }) => formatResult(await client.post(`/api/v1/chat/channels/${channelId}/upload/finalize`, { uploadId }, { timeoutMs: FINALIZE_TIMEOUT_MS }))));
+    strictInput(server.tool("conduyt_upload_local_file", `Upload a file from the machine this server runs on, end to end, as a CRM file (up to 50 MB): checks the size here first, then intent (POST /api/v1/files/upload/intent), PUT of the bytes to the signed URL, finalize (POST /api/v1/files/upload/finalize). ${FILE_SCOPE}. Answers { uploadId, filename, size, contentType }; attach it with POST /api/v1/files { entityType, entityId, uploadId }. A file over the cap is refused here with the API's wording ("File is too large (60 MB). Maximum allowed: 50 MB.") before any call is made; an empty file likewise ("The file is empty."). API refusals are surfaced verbatim and not retried; a storage failure leaves nothing saved, call the tool again. Only a 409 upload_in_progress on finalize is repeated (at most 4 total attempts, waiting the Retry-After, capped at 10 seconds, else 5 seconds). Finalize refusals: ${FINALIZE_ERRORS}`, {
+        filePath: z.string().min(1).describe("Path of the local file to upload"),
+        fileName: z.string().min(1).optional().describe("Name to store it under; default: the file's own name"),
+        contentType: contentTypeField,
+    }, async ({ filePath, fileName, contentType }) => runDirectUpload(client, { intentPath: "/api/v1/files/upload/intent", finalizePath: "/api/v1/files/upload/finalize", maxBytes: FILE_UPLOAD_MAX_BYTES, filePath, fileName, contentType })));
+    strictInput(server.tool("conduyt_upload_chat_attachment", `Upload a file from the machine this server runs on, end to end, as a Team Chat attachment (up to 10 MB): checks the size here first, then intent (POST /api/v1/chat/channels/{id}/upload/intent), PUT of the bytes, finalize (.../upload/finalize). ${CHAT_SCOPE}. Answers { url, name, size, type }: send it in a message's metadata.attachments. A file over the cap is refused here with the API's wording ("File is too large (12 MB). Maximum allowed: 10 MB.") before any call is made; an empty file likewise ("The file is empty."). API refusals are surfaced verbatim and not retried; a storage failure leaves nothing saved, call the tool again. Only a 409 upload_in_progress on finalize is repeated (at most 4 total attempts, waiting the Retry-After, capped at 10 seconds, else 5 seconds). Finalize refusals: ${FINALIZE_ERRORS}`, {
+        channelId: channelField,
+        filePath: z.string().min(1).describe("Path of the local file to upload"),
+        fileName: z.string().min(1).optional().describe("Name to store it under; default: the file's own name"),
+        contentType: contentTypeField,
+    }, async ({ channelId, filePath, fileName, contentType }) => runDirectUpload(client, { intentPath: `/api/v1/chat/channels/${channelId}/upload/intent`, finalizePath: `/api/v1/chat/channels/${channelId}/upload/finalize`, maxBytes: CHAT_UPLOAD_MAX_BYTES, filePath, fileName, contentType })));
+}

package/dist/tools/short-links.js

@@ -8,7 +8,7 @@ import { strictInput } from "./strict.js";
  * Retry-After) reaches the agent as the first answer and is never replayed here.
  */
 export function registerShortLinkTools(server, client) {
-    strictInput(server.tool("conduyt_create_short_link", "Make (or reuse) this workspace's Conduyt short link for a public link-shortener address that the Message check flagged (POST /api/v1/short-links; an API key needs the 'messages' scope, an sms key is accepted, and the member needs communications.create): put the returned short link in the message in place of the flagged address. The short link redirects to the address exactly as given; there is one link per workspace and address, so a repeat returns the same link. Shortenable: a web link the link check would fetch and the Message check flagged as a public link shortener. NOT shortenable (400 not_shortenable, before any work): an address on our own host (unsubscribe, one-time booking and file links, click tracking), an address with a merge field, mailto:, tel: or sms: addresses, one of our own short links, or any address the Message check does not flag as a link shortener. Answers 200 { data: { url: the short link, target: the address given } }. Errors, surfaced verbatim and never retried: 400 invalid_body (url missing, not a string or an unknown key) / not_shortenable; 403 forbidden; 413 body_too_large; 429 rate_limited (30 per minute per workspace and member; the Retry-After seconds are in the error); 503 short_link_unavailable (the link could not be made; nothing changed, try again later).", {
-        url: z.string().min(1).describe("The flagged public link-shortener address to replace, e.g. https://bit.ly/abc123 (sent exactly as given; the redirect goes to this address)"),
+    strictInput(server.tool("conduyt_create_short_link", "Make (or reuse) this workspace's Conduyt short link for a public link-shortener address that the Message check flagged (POST /api/v1/short-links; an API key needs the 'messages' scope, an sms key is accepted, and the member needs communications.create): put the returned short link in the message in place of the flagged address. The short link redirects to the address exactly as given; there is one link per workspace and address, so a repeat returns the same link. Shortenable: a web link of at most 2,048 characters that the link check would fetch and the Message check flagged as a public link shortener. NOT shortenable (400 not_shortenable, before any work): an address on our own host (unsubscribe, one-time booking and file links, click tracking), an address with a merge field, mailto:, tel: or sms: addresses, one of our own short links, or any address the Message check does not flag as a link shortener. Answers 200 { data: { url: the short link, target: the address given } }. Errors, surfaced verbatim and never retried: 400 invalid_body (url missing, not a string or an unknown key) / not_shortenable; 403 forbidden; 413 body_too_large; 429 rate_limited (30 per minute per workspace and member; the Retry-After seconds are in the error); 503 short_link_unavailable (the link could not be made; nothing changed, try again later).", {
+        url: z.string().describe("The flagged public link-shortener address to replace, e.g. https://bit.ly/abc123 (at most 2,048 characters; sent exactly as given, an empty or over-long value reaches the route and is its 400; the redirect goes to this address)"),
     }, async ({ url }) => formatResult(await client.post("/api/v1/short-links", { url }))));
 }

package/package.json

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

@@ -123,7 +123,7 @@
     {
       "match": "/api/v1/files",
       "status": "planned",
-      "reason": "file listing/metadata is agent-useful; upload stays browser-side"
+      "reason": "file listing/metadata is agent-useful; the direct-upload routes (POST /files/upload/intent and /finalize) are covered, the multipart upload stays browser-side"
     },
     {
       "match": "GET /api/v1/chat/messages/",

package/scripts/coverage-matrix.json

@@ -1,11 +1,11 @@
 {
-  "generatedAt": "2026-10-25T09:09:54.777Z",
-  "toolCount": 366,
-  "totalEndpoints": 1107,
+  "generatedAt": "2026-10-28T11:47:07.866Z",
+  "toolCount": 372,
+  "totalEndpoints": 1115,
   "counts": {
-    "covered": 322,
-    "excluded": 331,
-    "planned": 454,
+    "covered": 326,
+    "excluded": 334,
+    "planned": 455,
     "uncategorized": 0
   },
   "matrix": {
@@ -269,6 +269,10 @@
       "status": "excluded",
       "reason": "raw CSV bytes (up to 50k rows) do not belong in a tool result; conduyt_account_exports_list returns the authed downloadPath for API/CLI retrieval"
     },
+    "POST /api/v1/account/company-name": {
+      "status": "planned",
+      "reason": "account readiness/onboarding surfaces"
+    },
     "GET /api/v1/account/readiness": {
       "status": "planned",
       "reason": "account readiness/onboarding surfaces"
@@ -501,6 +505,10 @@
       "status": "excluded",
       "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
     },
+    "POST /api/v1/auth/google": {
+      "status": "excluded",
+      "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
+    },
     "GET /api/v1/auth/google/callback": {
       "status": "excluded",
       "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
@@ -545,6 +553,10 @@
       "status": "excluded",
       "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
     },
+    "POST /api/v1/auth/microsoft": {
+      "status": "excluded",
+      "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
+    },
     "GET /api/v1/auth/microsoft/callback": {
       "status": "excluded",
       "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
@@ -593,6 +605,10 @@
       "status": "excluded",
       "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
     },
+    "POST /api/v1/auth/signup-events": {
+      "status": "excluded",
+      "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
+    },
     "POST /api/v1/auth/switch-account": {
       "status": "excluded",
       "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
@@ -1346,6 +1362,18 @@
       "status": "planned",
       "reason": "team chat read/post for agents"
     },
+    "POST /api/v1/chat/channels/:id/upload/finalize": {
+      "status": "covered",
+      "tools": [
+        "conduyt_finalize_chat_upload"
+      ]
+    },
+    "POST /api/v1/chat/channels/:id/upload/intent": {
+      "status": "covered",
+      "tools": [
+        "conduyt_create_chat_upload_intent"
+      ]
+    },
     "GET /api/v1/chat/floor": {
       "status": "planned",
       "reason": "team chat read/post for agents"
@@ -2914,23 +2942,35 @@
     },
     "GET /api/v1/files": {
       "status": "planned",
-      "reason": "file listing/metadata is agent-useful; upload stays browser-side"
+      "reason": "file listing/metadata is agent-useful; the direct-upload routes (POST /files/upload/intent and /finalize) are covered, the multipart upload stays browser-side"
     },
     "POST /api/v1/files": {
       "status": "planned",
-      "reason": "file listing/metadata is agent-useful; upload stays browser-side"
+      "reason": "file listing/metadata is agent-useful; the direct-upload routes (POST /files/upload/intent and /finalize) are covered, the multipart upload stays browser-side"
     },
     "DELETE /api/v1/files": {
       "status": "planned",
-      "reason": "file listing/metadata is agent-useful; upload stays browser-side"
+      "reason": "file listing/metadata is agent-useful; the direct-upload routes (POST /files/upload/intent and /finalize) are covered, the multipart upload stays browser-side"
     },
     "GET /api/v1/files/:id/download": {
       "status": "planned",
-      "reason": "file listing/metadata is agent-useful; upload stays browser-side"
+      "reason": "file listing/metadata is agent-useful; the direct-upload routes (POST /files/upload/intent and /finalize) are covered, the multipart upload stays browser-side"
     },
     "POST /api/v1/files/upload": {
       "status": "planned",
-      "reason": "file listing/metadata is agent-useful; upload stays browser-side"
+      "reason": "file listing/metadata is agent-useful; the direct-upload routes (POST /files/upload/intent and /finalize) are covered, the multipart upload stays browser-side"
+    },
+    "POST /api/v1/files/upload/finalize": {
+      "status": "covered",
+      "tools": [
+        "conduyt_finalize_file_upload"
+      ]
+    },
+    "POST /api/v1/files/upload/intent": {
+      "status": "covered",
+      "tools": [
+        "conduyt_create_file_upload_intent"
+      ]
     },
     "GET /api/v1/generated-documents": {
       "status": "planned",