conduyt-mcp 4.11.0 → 4.13.0

package/dist/client.d.ts

@@ -1,15 +1,58 @@
 import type { ConduytConfig } from "./types.js";
+/**
+ * Structured API error (SOL-017). `code` distinguishes transport-level
+ * failures (timeout / response_too_large / network) from HTTP failures
+ * (code "http", status set). `retryable` reflects whether the FAILURE class
+ * is transient — the client itself only ever retries idempotent GETs.
+ * The message keeps the legacy "Conduyt API <status>: <msg>" shape so
+ * existing tool-level catch blocks keep working.
+ */
+export declare class ConduytApiError extends Error {
+    readonly status: number | null;
+    readonly code: "http" | "timeout" | "response_too_large" | "network";
+    readonly retryable: boolean;
+    constructor(opts: {
+        message: string;
+        status?: number | null;
+        code: ConduytApiError["code"];
+        retryable: boolean;
+        cause?: unknown;
+    });
+}
+/** Per-call overrides for legitimately long/large operations (GDPR export,
+ *  AI chat) — everything else rides the bounded defaults. */
+export interface RequestOptions {
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+}
 export declare class ConduytClient {
     private baseUrl;
     private apiKey;
+    private timeoutMs;
+    private maxResponseBytes;
+    private retryBaseMs;
     constructor(config: ConduytConfig);
-    request(method: string, path: string, body?: unknown): Promise<unknown>;
-    requestText(method: string, path: string, body?: unknown): Promise<string>;
-    get(path: string): Promise<unknown>;
-    post(path: string, body: unknown): Promise<unknown>;
-    postText(path: string, body: unknown): Promise<string>;
-    patch(path: string, body: unknown): Promise<unknown>;
-    del(path: string): Promise<unknown>;
+    /**
+     * One bounded HTTP attempt: deadline via AbortSignal, size cap enforced
+     * from Content-Length before the body is read AND from the actual bytes
+     * after (chunked responses carry no length header).
+     */
+    private attempt;
+    private httpError;
+    private retryDelayMs;
+    /**
+     * Retries are for idempotent GETs ONLY: transient statuses (429/502/503/
+     * 504), timeouts, and network errors. Mutations are never replayed — the
+     * server may have applied the write before the failure surfaced.
+     */
+    private requestRaw;
+    request(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<unknown>;
+    requestText(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<string>;
+    get(path: string, opts?: RequestOptions): Promise<unknown>;
+    post(path: string, body: unknown, opts?: RequestOptions): Promise<unknown>;
+    postText(path: string, body: unknown, opts?: RequestOptions): Promise<string>;
+    patch(path: string, body: unknown, opts?: RequestOptions): Promise<unknown>;
+    del(path: string, opts?: RequestOptions): Promise<unknown>;
 }
 export declare function formatResult(data: unknown): {
     content: Array<{

package/dist/client.js

@@ -1,6 +1,36 @@
+/**
+ * Structured API error (SOL-017). `code` distinguishes transport-level
+ * failures (timeout / response_too_large / network) from HTTP failures
+ * (code "http", status set). `retryable` reflects whether the FAILURE class
+ * is transient — the client itself only ever retries idempotent GETs.
+ * The message keeps the legacy "Conduyt API <status>: <msg>" shape so
+ * existing tool-level catch blocks keep working.
+ */
+export class ConduytApiError extends Error {
+    status;
+    code;
+    retryable;
+    constructor(opts) {
+        super(opts.message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.name = "ConduytApiError";
+        this.status = opts.status ?? null;
+        this.code = opts.code;
+        this.retryable = opts.retryable;
+    }
+}
+/** Bounded defaults; each overridable via config / env (see src/index.ts). */
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 5_000_000;
+const DEFAULT_RETRY_BASE_MS = 500;
+const MAX_GET_RETRIES = 2;
+const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+const MAX_RETRY_AFTER_MS = 10_000;
 export class ConduytClient {
     baseUrl;
     apiKey;
+    timeoutMs;
+    maxResponseBytes;
+    retryBaseMs;
     constructor(config) {
         // Strip trailing slashes, then guard against a misconfigured base URL that
         // already includes the API prefix. Every tool builds paths as `/api/v1/...`,
@@ -17,65 +47,197 @@ export class ConduytClient {
         }
         this.baseUrl = base;
         this.apiKey = config.apiKey;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxResponseBytes = config.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+        this.retryBaseMs = config.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
     }
-    async request(method, path, body) {
+    /**
+     * One bounded HTTP attempt: deadline via AbortSignal, size cap enforced
+     * from Content-Length before the body is read AND from the actual bytes
+     * after (chunked responses carry no length header).
+     */
+    async attempt(method, path, body, timeoutMs, maxResponseBytes) {
         const url = `${this.baseUrl}${path}`;
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
             "Content-Type": "application/json",
         };
-        const res = await fetch(url, {
-            method,
-            headers,
-            body: body ? JSON.stringify(body) : undefined,
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers,
+                body: body != null ? JSON.stringify(body) : undefined,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            if (err?.name === "TimeoutError" || err?.name === "AbortError") {
+                throw new ConduytApiError({
+                    message: `Conduyt API timeout: no response within ${timeoutMs}ms for ${method} ${path}`,
+                    code: "timeout",
+                    retryable: true,
+                    cause: err,
+                });
+            }
+            throw new ConduytApiError({
+                message: `Conduyt API network error for ${method} ${path}: ${err?.message ?? String(err)}`,
+                code: "network",
+                retryable: true,
+                cause: err,
+            });
+        }
+        const tooLarge = (bytes) => new ConduytApiError({
+            message: `Conduyt API response too large (${bytes} bytes > ${maxResponseBytes} cap) for ${method} ${path}. Narrow the query or paginate.`,
+            status: res.status,
+            code: "response_too_large",
+            retryable: false,
         });
-        const json = await res.json().catch(() => null);
-        if (!res.ok) {
-            const msg = json?.error || res.statusText;
-            throw new Error(`Conduyt API ${res.status}: ${msg}`);
+        // Declared-size fast path (uncompressed responses)...
+        const declared = Number(res.headers.get("content-length") || 0);
+        if (declared > maxResponseBytes)
+            throw tooLarge(declared);
+        // ...then a STREAMED byte-accurate read: chunked/compressed responses
+        // carry no usable length header, and reading the whole body before
+        // checking would defeat the memory bound. The read stops (and the
+        // stream is cancelled) the moment the cap is crossed.
+        let text = "";
+        if (res.body) {
+            const reader = res.body.getReader();
+            const chunks = [];
+            let bytes = 0;
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    bytes += value.byteLength;
+                    if (bytes > maxResponseBytes) {
+                        await reader.cancel().catch(() => { });
+                        throw tooLarge(bytes);
+                    }
+                    chunks.push(value);
+                }
+            }
+            catch (err) {
+                if (err instanceof ConduytApiError)
+                    throw err;
+                throw new ConduytApiError({
+                    message: `Conduyt API network error reading response for ${method} ${path}: ${err?.message ?? String(err)}`,
+                    code: "network",
+                    retryable: true,
+                    cause: err,
+                });
+            }
+            const buf = new Uint8Array(bytes);
+            let off = 0;
+            for (const c of chunks) {
+                buf.set(c, off);
+                off += c.byteLength;
+            }
+            text = new TextDecoder().decode(buf);
         }
-        return json;
+        else {
+            text = await res.text().catch(() => "");
+            if (text.length > maxResponseBytes)
+                throw tooLarge(text.length);
+        }
+        return { res, text };
     }
-    async requestText(method, path, body) {
-        const url = `${this.baseUrl}${path}`;
-        const headers = {
-            Authorization: `Bearer ${this.apiKey}`,
-            "Content-Type": "application/json",
-        };
-        const res = await fetch(url, {
-            method,
-            headers,
-            body: body !== undefined ? JSON.stringify(body) : undefined,
+    httpError(res, text) {
+        let msg = res.statusText;
+        try {
+            const json = JSON.parse(text);
+            if (json?.error)
+                msg = json.error;
+        }
+        catch {
+            if (text)
+                msg = text.slice(0, 500);
+        }
+        return new ConduytApiError({
+            message: `Conduyt API ${res.status}: ${msg}`,
+            status: res.status,
+            code: "http",
+            retryable: RETRYABLE_STATUSES.has(res.status),
         });
-        const text = await res.text().catch(() => "");
-        if (!res.ok) {
-            let msg = res.statusText;
+    }
+    retryDelayMs(res, attemptIndex) {
+        const retryAfter = Number(res?.headers.get("retry-after"));
+        if (Number.isFinite(retryAfter) && retryAfter >= 0) {
+            return Math.min(retryAfter * 1000, MAX_RETRY_AFTER_MS);
+        }
+        return Math.min(this.retryBaseMs * 2 ** attemptIndex, MAX_RETRY_AFTER_MS);
+    }
+    /**
+     * Retries are for idempotent GETs ONLY: transient statuses (429/502/503/
+     * 504), timeouts, and network errors. Mutations are never replayed — the
+     * server may have applied the write before the failure surfaced.
+     */
+    async requestRaw(method, path, body, opts) {
+        const timeoutMs = opts?.timeoutMs ?? this.timeoutMs;
+        const maxResponseBytes = opts?.maxResponseBytes ?? this.maxResponseBytes;
+        const canRetry = method === "GET";
+        const attempts = canRetry ? MAX_GET_RETRIES + 1 : 1;
+        // TOTAL time budget across every attempt + backoff: 1.5x the per-call
+        // deadline. Without it, 3 stacked attempt timeouts + backoffs could hold
+        // an agent turn ~110s while the caller believed the bound was 30s.
+        const totalBudgetMs = Math.ceil(timeoutMs * 1.5);
+        const startedAt = Date.now();
+        let lastError = null;
+        for (let i = 0; i < attempts; i++) {
+            const remaining = totalBudgetMs - (Date.now() - startedAt);
+            let res = null;
             try {
-                const json = JSON.parse(text);
-                msg = json.error || msg;
+                const out = await this.attempt(method, path, body, Math.max(1, Math.min(timeoutMs, remaining)), maxResponseBytes);
+                res = out.res;
+                if (out.res.ok)
+                    return out.text;
+                lastError = this.httpError(out.res, out.text);
             }
-            catch {
-                if (text)
-                    msg = text;
+            catch (err) {
+                if (!(err instanceof ConduytApiError))
+                    throw err;
+                if (err.code === "response_too_large")
+                    throw err;
+                lastError = err;
             }
-            throw new Error(`Conduyt API ${res.status}: ${msg}`);
+            const isLast = i === attempts - 1;
+            if (!canRetry || isLast || !lastError.retryable)
+                throw lastError;
+            const delay = this.retryDelayMs(res, i);
+            if (Date.now() - startedAt + delay >= totalBudgetMs)
+                throw lastError;
+            await new Promise((r) => setTimeout(r, delay));
+        }
+        throw lastError;
+    }
+    async request(method, path, body, opts) {
+        const text = await this.requestRaw(method, path, body, opts);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
         }
-        return text;
     }
-    get(path) {
-        return this.request("GET", path);
+    async requestText(method, path, body, opts) {
+        return this.requestRaw(method, path, body, opts);
+    }
+    get(path, opts) {
+        return this.request("GET", path, undefined, opts);
     }
-    post(path, body) {
-        return this.request("POST", path, body);
+    post(path, body, opts) {
+        return this.request("POST", path, body, opts);
     }
-    postText(path, body) {
-        return this.requestText("POST", path, body);
+    postText(path, body, opts) {
+        return this.requestText("POST", path, body, opts);
     }
-    patch(path, body) {
-        return this.request("PATCH", path, body);
+    patch(path, body, opts) {
+        return this.request("PATCH", path, body, opts);
     }
-    del(path) {
-        return this.request("DELETE", path);
+    del(path, opts) {
+        return this.request("DELETE", path, undefined, opts);
     }
 }
 export function formatResult(data) {

package/dist/index.js

@@ -47,7 +47,12 @@ if (!apiKey.startsWith("cdy_")) {
     console.error("CONDUYT_API_KEY must start with 'cdy_' — generate one at Settings > API Keys in Conduyt.");
     process.exit(1);
 }
-const client = new ConduytClient({ apiUrl, apiKey });
+// Operational bounds (SOL-017): every HTTP call gets a deadline, a
+// response-size cap, and conservative GET-only retries. Overridable via env
+// for constrained runtimes.
+const timeoutMs = Number(process.env.CONDUYT_TIMEOUT_MS) || undefined;
+const maxResponseBytes = Number(process.env.CONDUYT_MAX_RESPONSE_BYTES) || undefined;
+const client = new ConduytClient({ apiUrl, apiKey, timeoutMs, maxResponseBytes });
 // 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");

package/dist/tools/ai-extended.js

@@ -93,7 +93,8 @@ export function registerAiExtendedTools(server, client) {
             .optional()
             .describe("Pin the chat to a specific record for grounded answers"),
     }, async (params) => {
-        const streamText = await client.postText("/api/v1/ai/chat", params);
+        // A grounded multi-turn reply can stream well past the 30s default.
+        const streamText = await client.postText("/api/v1/ai/chat", params, { timeoutMs: 120_000 });
         const reply = parseSseText(streamText);
         return formatResult({ reply });
     });

package/dist/tools/bulk.js

@@ -50,7 +50,15 @@ export function registerBulkTools(server, client) {
             qp.set("created_to", params.created_to);
         if (params.min_score)
             qp.set("min_score", String(params.min_score));
-        const result = await client.get(`/api/v1/contacts/export?${qp}`);
+        // Full-book exports routinely exceed the 5MB default cap and the 30s
+        // deadline — widened, but bounded at 25MB: the payload is re-serialized
+        // into the tool result, so an unbounded budget would just move the
+        // failure into memory/model-context. Past 25MB the structured
+        // response_too_large error tells the agent to narrow the filters.
+        const result = await client.get(`/api/v1/contacts/export?${qp}`, {
+            timeoutMs: 120_000,
+            maxResponseBytes: 25_000_000,
+        });
         return formatResult(result);
     });
     server.tool("conduyt_export_deals", "Export deals as JSON with filtering by status, pipeline, or search term.", {
@@ -65,7 +73,11 @@ export function registerBulkTools(server, client) {
             qp.set("status", params.status);
         if (params.pipeline)
             qp.set("pipeline", params.pipeline);
-        const result = await client.get(`/api/v1/deals/export?${qp}`);
+        // Same widened-but-bounded budget as the contacts export.
+        const result = await client.get(`/api/v1/deals/export?${qp}`, {
+            timeoutMs: 120_000,
+            maxResponseBytes: 25_000_000,
+        });
         return formatResult(result);
     });
     server.tool("conduyt_bulk_tag_contacts", "Add one tag to many contacts in a single call. Requires contacts:edit.", {

package/dist/tools/discovery.js

@@ -1,7 +1,9 @@
+import { createRequire } from "node:module";
 import { z } from "zod";
 import { formatResult } from "../client.js";
+const requireJson = createRequire(import.meta.url);
 export function registerDiscoveryTools(server, client) {
-    server.tool("conduyt_api_catalog", "Discover all Conduyt CRM API endpoints across 90+ domains, with full request and response schemas. Call this first to learn what the CRM can do — the response carries the exact, current endpoint counts.", {}, async () => {
+    server.tool("conduyt_api_catalog", "Discover all Conduyt CRM API endpoints across 90+ domains, with full request and response schemas. Call this first to learn what the CRM can do — the response carries the exact, current endpoint counts. NOTE: the catalog is the full REST surface; not every endpoint has a dedicated MCP tool. Call conduyt_mcp_coverage to see exactly which endpoints are callable through MCP tools versus API-only.", {}, async () => {
         const result = await client.get("/api/v1/schema/api-catalog");
         return formatResult(result);
     });
@@ -22,4 +24,27 @@ export function registerDiscoveryTools(server, client) {
         const result = await client.get(`/api/v1/search?${params}`);
         return formatResult(result);
     });
+    server.tool("conduyt_mcp_coverage", "The REST-to-MCP coverage matrix: which of the catalog's API endpoints are callable through MCP tools (and by which tool), which are deliberately excluded (with reasons — e.g. interactive-only auth/billing, inbound webhook receivers, realtime browser surfaces), and which are planned but not yet wrapped. Use this to know up front whether a capability you discovered in conduyt_api_catalog is executable here, instead of failing mid-task. Ships with the package and matches this release's tools exactly.", {
+        status: z
+            .enum(["covered", "excluded", "planned"])
+            .optional()
+            .describe("Only return endpoints with this coverage status"),
+        pathPrefix: z.string().optional().describe("Only return endpoints whose path starts with this prefix (e.g. /api/v1/contacts)"),
+    }, async ({ status, pathPrefix }) => {
+        // Pinned at build/publish time by scripts/verify-coverage.mjs (the
+        // prepublish gate fails if any endpoint lacks a designation).
+        const matrix = requireJson("../../scripts/coverage-matrix.json");
+        let entries = Object.entries(matrix.matrix);
+        if (status)
+            entries = entries.filter(([, v]) => v.status === status);
+        if (pathPrefix)
+            entries = entries.filter(([k]) => k.split(" ")[1]?.startsWith(pathPrefix));
+        return formatResult({
+            generatedAt: matrix.generatedAt,
+            toolCount: matrix.toolCount,
+            totalEndpoints: matrix.totalEndpoints,
+            counts: matrix.counts,
+            endpoints: Object.fromEntries(entries),
+        });
+    });
 }

package/dist/tools/privacy.js

@@ -14,7 +14,9 @@ export function registerPrivacyTools(server, client) {
         // into a different subroute. Keep this export-only regardless of key role.
         id: z.string().uuid().describe("Contact UUID to export"),
     }, async ({ id }) => {
-        const result = await client.get(`/api/v1/contacts/${encodeURIComponent(id)}/gdpr-export`);
+        // A full portable export is legitimately big and slow on large
+        // tenants — wider per-call budget than the 30s/5MB defaults.
+        const result = await client.get(`/api/v1/contacts/${encodeURIComponent(id)}/gdpr-export`, { timeoutMs: 120_000, maxResponseBytes: 25_000_000 });
         return formatResult(result);
     });
     server.tool("conduyt_forget_contact", "IRREVERSIBLE GDPR right-to-be-forgotten erasure: permanently anonymizes the contact and erases their personal data EVERYWHERE it appears — messages, notes, deals, files, automations, and exports — across the whole account. Suppression/consent tombstones are kept so they are not re-contacted. THERE IS NO UNDO. Requires an owner API key (the API enforces this) and an explicit confirm='FORGET'. On a large tenant this can legitimately take tens of seconds. A 409 is retryable (a concurrent merge or in-flight automation) — retry once.", {
@@ -25,7 +27,9 @@ export function registerPrivacyTools(server, client) {
             .literal("FORGET")
             .describe("Must be exactly the string 'FORGET'. This is a hard safety gate for an irreversible erasure — do not supply it unless the erasure is intended."),
     }, async ({ id, confirm }) => {
-        const result = await client.post(`/api/v1/contacts/${encodeURIComponent(id)}/gdpr-forget`, { confirm });
+        // The tool doc promises "can take tens of seconds" on large tenants
+        // — the erasure must not be aborted by the 30s default deadline.
+        const result = await client.post(`/api/v1/contacts/${encodeURIComponent(id)}/gdpr-forget`, { confirm }, { timeoutMs: 300_000 });
         return formatResult(result);
     });
 }

package/dist/types.d.ts

@@ -1,6 +1,12 @@
 export interface ConduytConfig {
     apiUrl: string;
     apiKey: string;
+    /** Per-call HTTP deadline in ms (default 30_000). Env: CONDUYT_TIMEOUT_MS. */
+    timeoutMs?: number;
+    /** Response body cap in bytes (default 5_000_000). Env: CONDUYT_MAX_RESPONSE_BYTES. */
+    maxResponseBytes?: number;
+    /** Base backoff in ms for GET retries (default 500; tests use 1). */
+    retryBaseMs?: number;
 }
 export interface ApiResponse<T = unknown> {
     data?: T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt-mcp",
-  "version": "4.11.0",
+  "version": "4.13.0",
   "description": "MCP server for Conduyt CRM — expose CRM operations as AI-accessible tools",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,8 @@
   },
   "files": [
     "dist",
+    "scripts/coverage-matrix.json",
+    "scripts/coverage-manifest.json",
     "README.md",
     ".env.example"
   ],
@@ -20,8 +22,10 @@
     "start": "tsx src/index.ts",
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run check:version && npm run build && ENFORCE=1 node scripts/verify-contracts.mjs",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "prepublishOnly": "npm run check:version && npm run test && npm run build && ENFORCE=1 node scripts/verify-contracts.mjs && ENFORCE=1 node scripts/verify-coverage.mjs",
     "audit:contracts": "node scripts/verify-contracts.mjs",
+    "audit:coverage": "node scripts/verify-coverage.mjs",
     "contracts:refresh": "node scripts/refresh-contracts.mjs",
     "check:version": "node scripts/check-version-sync.mjs"
   },