conduyt-mcp 4.78.0 → 4.80.0

package/README.md

@@ -27,6 +27,8 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 |------|-------------|
 | `conduyt_list_deals` | List deals by pipeline, stage, or assignee; rows carry `hasNextStep` and `nextAppointmentAt`. With `health_summary=true` it answers the Pipeline health strip for the same filtered set (`totalOpenDeals`, `atRiskValue`, `checks[]`, `deals`); `health_check`, `health_limit`, `health_offset`, `health_cursor` (the previous `nextCursor`, passed back unchanged) and `health_rows_only` page one check's deals (rows-only answers `{data:{deals:{check, offset, items, hasMore, nextCursor}}}`) |
 | `conduyt_pipeline_health` | Pipeline health for one pipeline or all visible active pipelines (`GET /deals/inspection`): the six checks over open deals by money at risk; `check` adds that check's deals, paged by `cursor` (or `offset`). Cursor 400s carry `health_cursor_invalid` / `_context` / `_blank` / `_needs_check`, `health_filter_conflict` |
+| `conduyt_pipeline_health_fix_deal` | Pipeline health quick fix for a deal row (`PATCH /deals/{id}` with `checkOrigin`): `stale` = `stageId` (+ `expectedStageId`), `unassigned` = `assignedTo`, `missing_close_date` = `expectedCloseDate`, `missing_contact` = `contactId`; `expectedUpdatedAt` required. Refusals verbatim, never retried: 409 `deal_changed` / `deal_check_cleared` (with the deal's current health row), uncoded 409s, 400 `health_fix_mismatch` |
+| `conduyt_pipeline_health_fix_next_action` | Pipeline health "Set next action" (`POST /tasks` with `checkOrigin` `high_value_idle` / `needs_action`, `dealId`, `expectedDealUpdatedAt`, optional `idempotencyKey` sent as the `Idempotency-Key` header). At most one non-done quick-fix task per deal; refusals verbatim, never retried: 409 `deal_changed` / `deal_has_next_action` / `deal_check_cleared`, 400 `health_fix_mismatch`, idempotency 409/503 |
 | `conduyt_get_stage_rules` / `conduyt_set_stage_rules` | Read / set one stage's rule (`requiredFields` incl. `custom:<fieldKey>`, `requiredDocuments` 0-20, lost-reason label and options, `lostReasonAllowOther`); other stages untouched; revision-aware, retried once on a 409 |
 | `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` |
@@ -55,7 +57,7 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 | `conduyt_delete_pipeline` | Delete a pipeline (move/remove its deals first) |
 | `conduyt_create_stage` | Append a stage to a pipeline (e.g. 'On Hold', 'Declined/Dead') |
 | `conduyt_update_stage` | Rename, recolor, reorder, or change won/lost flags on a stage |
-| `conduyt_delete_stage` | Delete a stage from a pipeline; `moveTo` moves its live deals to another stage first, `expectedSettingsRevision` refuses the delete when settings changed (409 `stale_settings_revision`; the answer then carries the new `settingsRevision`) |
+| `conduyt_delete_stage` | Soft-delete a stage: an EMPTY stage can always be deleted (history kept, hidden from every list, GET / PATCH then 404, no restore in v1, name reusable); `moveTo` re-homes its live deals first, `expectedSettingsRevision` refuses the delete when settings changed (409 `stale_settings_revision`; the answer then carries the new `settingsRevision`). Refusals are 409s whose message is surfaced verbatim: deals in the stage, `used by N active automation(s) (names)`, DPP status map, `pipeline_archived`, `intake_target`. A run parked before the delete fails at that step with a clear reason |
 
 ### Activities
 | Tool | Description |
@@ -342,6 +344,24 @@ The rest of team chat (sending, reactions, pins, presence, uploads) is not wrapp
 | `conduyt_reply_capture_verify` | Check DNS and promote to live once the provider confirms inbound receiving |
 | `conduyt_reply_capture_remove` | Remove capture (and finish an interrupted removal) — requires `confirm='REMOVE'`; replies to already-sent email are lost |
 
+## Error text grammar
+
+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).
+`<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
+object too large for the bound is left out and named in `_omitted`. Every HTTP refusal takes this path, including the multipart call-flow audio upload; a tool that adds its own words (a missing-scope or busy note) puts them BEFORE this text. Example:
+
+```
+Conduyt API 503: Contact merge in progress [Retry-After: 5s] {"code":"merge_in_progress"}
+```
+
 ## Setup
 
 ```bash

package/dist/client.d.ts

@@ -28,7 +28,15 @@ export declare class ConduytApiError extends Error {
 export interface RequestOptions {
     timeoutMs?: number;
     maxResponseBytes?: number;
+    /** Extra request headers (e.g. Idempotency-Key on POST /tasks); never overrides Authorization / Content-Type. */
+    headers?: Record<string, string>;
 }
+/**
+ * Render an error body's details (everything but `error`) as ONE valid JSON object: scalars first (code, revision; a very
+ * long string is shortened inside its quotes), then nested objects whole while they fit ERROR_DETAILS_BOUND, plus the
+ * ALWAYS_WHOLE_KEYS; a nested object that does not fit is left out and named in `_omitted`. JSON is never cut mid-object.
+ */
+export declare function renderErrorDetails(body: Record<string, unknown>): string;
 export declare class ConduytClient {
     private baseUrl;
     private apiKey;
@@ -42,7 +50,13 @@ export declare class ConduytClient {
      * after (chunked responses carry no length header).
      */
     private attempt;
+    /**
+     * Error grammar (stable): `Conduyt API <status>: <message>` + optionally ` [Retry-After: <N>s]` + optionally ` <details>`,
+     * where <details> is ONE JSON object and the FINAL token (see renderErrorDetails). Parse it by trying each `{` from the left
+     * until the rest of the text is valid JSON (a server message may itself contain a brace).
+     */
     private httpError;
+    private mkHttpError;
     private retryDelayMs;
     /**
      * Retries are for idempotent GETs ONLY: transient statuses (429/502/503/

package/dist/client.js

@@ -32,6 +32,35 @@ const MAX_RETRY_AFTER_MS = 10_000;
 const isAbort = (err) => err?.name === "TimeoutError" || err?.name === "AbortError";
 /** what a timeout of a MUTATION means: the server may have applied it */
 const AMBIGUOUS = " The server may have applied it: read the current state before repeating it.";
+/** Room for the nested objects of an error body (a 409 contact_changed's `contact`, a stage-requirements list). */
+const ERROR_DETAILS_BOUND = 1000;
+/** Error-body keys that are the actionable state itself and are always rendered WHOLE: HealthFixRefusal.row (the deal's
+ *  current health row, which a caller needs to choose again). The response size cap bounds it. */
+const ALWAYS_WHOLE_KEYS = new Set(["row"]);
+/**
+ * Render an error body's details (everything but `error`) as ONE valid JSON object: scalars first (code, revision; a very
+ * long string is shortened inside its quotes), then nested objects whole while they fit ERROR_DETAILS_BOUND, plus the
+ * ALWAYS_WHOLE_KEYS; a nested object that does not fit is left out and named in `_omitted`. JSON is never cut mid-object.
+ */
+export function renderErrorDetails(body) {
+    const entries = Object.entries(body).filter(([k]) => k !== "error");
+    if (entries.length === 0)
+        return "";
+    const isScalar = (v) => v === null || typeof v !== "object";
+    const out = {};
+    for (const [k, v] of entries.filter(([, v]) => isScalar(v)))
+        out[k] = typeof v === "string" && v.length > ERROR_DETAILS_BOUND ? v.slice(0, ERROR_DETAILS_BOUND) + "...[shortened]" : v;
+    const omitted = [];
+    for (const [k, v] of entries.filter(([, v]) => !isScalar(v))) {
+        if (ALWAYS_WHOLE_KEYS.has(k) || JSON.stringify({ ...out, [k]: v }).length <= ERROR_DETAILS_BOUND)
+            out[k] = v;
+        else
+            omitted.push(k);
+    }
+    if (omitted.length > 0)
+        out._omitted = omitted;
+    return JSON.stringify(out);
+}
 export class ConduytClient {
     baseUrl;
     apiKey;
@@ -63,9 +92,10 @@ export class ConduytClient {
      * 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) {
+    async attempt(method, path, body, timeoutMs, maxResponseBytes, extraHeaders) {
         const url = `${this.baseUrl}${path}`;
         const headers = {
+            ...(extraHeaders ?? {}),
             Authorization: `Bearer ${this.apiKey}`,
             "Content-Type": "application/json",
         };
@@ -161,36 +191,40 @@ export class ConduytClient {
         }
         return { res, text };
     }
+    /**
+     * Error grammar (stable): `Conduyt API <status>: <message>` + optionally ` [Retry-After: <N>s]` + optionally ` <details>`,
+     * where <details> is ONE JSON object and the FINAL token (see renderErrorDetails). Parse it by trying each `{` from the left
+     * until the rest of the text is valid JSON (a server message may itself contain a brace).
+     */
     httpError(res, text) {
+        const retryAfterRaw = res.headers.get("retry-after");
+        const retryAfter = retryAfterRaw === null || retryAfterRaw.trim() === "" ? NaN : Number(retryAfterRaw);
+        const retryAfterOk = Number.isFinite(retryAfter) && retryAfter >= 0;
+        const raTag = retryAfterOk ? ` [Retry-After: ${retryAfter}s]` : "";
         let msg = res.statusText;
         try {
             const json = JSON.parse(text);
             if (json?.error)
                 msg = json.error;
-            // Structured error details (e.g. STAGE_REQUIREMENTS carries
-            // 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.
-            // 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)}`;
-            }
+            // Structured error details (e.g. STAGE_REQUIREMENTS carries lostReasonOptions) must reach the agent, or the
+            // refusal is unactionable. Rendered by renderErrorDetails: JSON is never cut mid-object.
+            const details = renderErrorDetails(json ?? {});
+            if (details)
+                msg = `${msg}${raTag} ${details}`;
+            else
+                msg = `${msg}${raTag}`;
+            return this.mkHttpError(res, `Conduyt API ${res.status}: ${msg}`, retryAfter, retryAfterOk);
         }
         catch {
             if (text)
                 msg = text.slice(0, 500);
+            msg = `${msg}${raTag}`;
         }
-        const retryAfterRaw = res.headers.get("retry-after");
-        const retryAfter = retryAfterRaw === null || retryAfterRaw.trim() === "" ? NaN : Number(retryAfterRaw);
+        return this.mkHttpError(res, `Conduyt API ${res.status}: ${msg}`, retryAfter, retryAfterOk);
+    }
+    mkHttpError(res, message, retryAfter, retryAfterOk) {
         return new ConduytApiError({
-            message: `Conduyt API ${res.status}: ${msg}`,
+            message,
             status: res.status,
             code: "http",
             retryable: RETRYABLE_STATUSES.has(res.status),
@@ -224,7 +258,7 @@ export class ConduytClient {
             const remaining = totalBudgetMs - (Date.now() - startedAt);
             let res = null;
             try {
-                const out = await this.attempt(method, path, body, Math.max(1, Math.min(timeoutMs, remaining)), maxResponseBytes);
+                const out = await this.attempt(method, path, body, Math.max(1, Math.min(timeoutMs, remaining)), maxResponseBytes, opts?.headers);
                 res = out.res;
                 if (out.res.ok)
                     return out.text;
@@ -282,10 +316,9 @@ export class ConduytClient {
         catch {
             json = { raw: text };
         }
-        if (!res.ok) {
-            const msg = json?.error ?? text.slice(0, 300);
-            throw new ConduytApiError({ message: `Conduyt API ${res.status}: ${msg}`, status: res.status, code: "http", retryable: res.status >= 500 });
-        }
+        // every non-2xx goes through the shared formatter: same grammar, Retry-After placement and final JSON details object
+        if (!res.ok)
+            throw this.httpError(res, text);
         return json;
     }
     post(path, body, opts) {

package/dist/tools/deals.js

@@ -112,6 +112,35 @@ export function registerDealTools(server, client) {
         const result = qs ? await client.get("/api/v1/deals/inspection?" + qs) : await client.get("/api/v1/deals/inspection");
         return formatResult(result);
     }));
+    strictInput(server.tool("conduyt_pipeline_health_fix_deal", "Pipeline health QUICK FIX for a deal row (PATCH /api/v1/deals/{id} with checkOrigin). Pass the health check the row came from, the deal's updatedAt exactly as the health row carried it (expectedUpdatedAt, REQUIRED), and ONLY that check's fix: stale = stageId (+ optional expectedStageId, the stage the move was chosen against); unassigned = assignedTo; missing_close_date = expectedCloseDate; missing_contact = contactId. Each set to a value; any other combination is refused 400 health_fix_mismatch and nothing is read or written. For the next-action checks (high_value_idle, needs_action) use conduyt_pipeline_health_fix_next_action instead. Refusals reach you verbatim (status, server message, code, and the deal's CURRENT health row) and are NEVER retried. Error text grammar: `Conduyt API <status>: <message>[ [Retry-After: Ns]][ <one JSON object, the final token>]` (see README, Error text grammar). 409 deal_changed (the deal is no longer at expectedUpdatedAt; error text carries updatedAt and the current row: read it, choose again against row.updatedAt), 409 deal_check_cleared (the deal no longer fails that check; nothing written), a 409 without a code (a stage move by another writer, a stale expectedStageId, an in-flight publication), 400 health_fix_mismatch, 404 (no such deal, or your key cannot see it). The row in a refusal is null when your key can no longer see the deal. Ordinary edits (several fields, no health context) stay on conduyt_update_deal.", {
+        dealId: z.string().uuid().describe("Deal UUID"),
+        checkOrigin: z.enum(["stale", "unassigned", "missing_close_date", "missing_contact"]).describe("The health check this edit fixes"),
+        expectedUpdatedAt: z.string().datetime({ message: "expectedUpdatedAt must be the deal's updatedAt exactly as the health row carried it (UTC, trailing Z, e.g. 2026-10-06T23:19:00.000Z)" }).describe("REQUIRED: the deal's updatedAt as the health row carried it (PipelineHealthDeal.updatedAt). A deal at another version is refused 409 deal_changed."),
+        stageId: z.string().uuid().optional().describe("stale only: the stage to move the deal to"),
+        expectedStageId: z.string().uuid().optional().describe("stale only: the stage the move was chosen against; refused 409 (nothing written) when the deal is no longer in it"),
+        assignedTo: z.string().uuid().optional().describe("unassigned only: the user (owner) UUID to assign"),
+        expectedCloseDate: z.string().optional().describe("missing_close_date only: the expected close date (ISO 8601, e.g. '2026-11-30')"),
+        contactId: z.string().uuid().optional().describe("missing_contact only: the contact UUID to link"),
+    }, async ({ dealId, checkOrigin, expectedUpdatedAt, stageId, expectedStageId, assignedTo, expectedCloseDate, contactId }) => {
+        const result = await client.patch(`/api/v1/deals/${dealId}`, { checkOrigin, expectedUpdatedAt, stageId, expectedStageId, assignedTo, expectedCloseDate, contactId });
+        return formatResult(result);
+    }));
+    strictInput(server.tool("conduyt_pipeline_health_fix_next_action", "Pipeline health QUICK FIX \"Set next action\" (POST /api/v1/tasks with checkOrigin): creates a follow-up task on a deal from the High-value idle or Needs next action row. Pass checkOrigin, dealId and expectedDealUpdatedAt (the deal's updatedAt as the health row carried it); the task is created only while, under the deal's next-action lock, the deal is still at that version, still has no next action (no open task, no appointment booked from a day ago on) and still fails the check. Send idempotencyKey (1-255 printable ASCII) so a retry after a lost response replays the first task; reuse it ONLY for the same request. Refusals reach you verbatim (status, message, code, the deal's CURRENT health row) and are NEVER retried. Error text grammar: `Conduyt API <status>: <message>[ [Retry-After: Ns]][ <one JSON object, the final token>]` (see README, Error text grammar). 409 deal_changed (read the row, choose again against row.updatedAt), 409 deal_has_next_action (This deal already has a next action booked.), 409 deal_check_cleared, 400 health_fix_mismatch (checkOrigin not high_value_idle / needs_action, or without dealId / expectedDealUpdatedAt), a 409 without a code (the contact was merged or deleted mid-request: retry against the surviving record), or an idempotency 409/503 (see the idempotencyKey notes; verify the outcome before using a new key). The database allows at most one non-done quick-fix task per deal (a second is refused 409 deal_has_next_action); ordinary tasks (conduyt_create_task) are unconstrained and may coexist with or race a quick fix.", {
+        checkOrigin: z.enum(["high_value_idle", "needs_action"]).describe("The health check this task fixes"),
+        dealId: z.string().uuid().describe("Deal UUID the task is for"),
+        expectedDealUpdatedAt: z.string().datetime({ message: "expectedDealUpdatedAt must be the deal's updatedAt exactly as the health row carried it (UTC, trailing Z)" }).describe("REQUIRED: the deal's updatedAt as the health row carried it (PipelineHealthDeal.updatedAt)"),
+        title: z.string().min(1).max(500).describe("Task title (trimmed; blank is refused)"),
+        description: z.string().max(5000).optional().describe("Task description (max 5000)"),
+        dueDate: z.string().optional().describe("Due date: a date-only YYYY-MM-DD is stored as noon UTC that day; a date-time as given"),
+        priority: z.enum(["low", "medium", "high", "urgent"]).optional().describe("Task priority (default medium)"),
+        status: z.enum(["todo", "in_progress", "done"]).optional().describe("Task status (default todo)"),
+        assignedTo: z.string().nullable().optional().describe("A member's user UUID, '@me' or '@owner'; null or omitted = unassigned (assignment rules may still assign it). Assigning to someone else needs tasks.assign."),
+        contactId: z.string().uuid().nullable().optional().describe("Contact UUID to link"),
+        idempotencyKey: z.string().regex(/^[!-~](?:[ -~]{0,253}[!-~])?$/, "idempotencyKey must be 1-255 printable ASCII characters, not blank").optional().describe("Sent as the Idempotency-Key header: one key per creation attempt, reused only to retry the SAME request (same key + same body replays the first task; same key + a different body is 422). Two distinct 409s: the original attempt is still processing (wait Retry-After, retry with the SAME key), or code idempotency_key_spent (a prior attempt failed or has an unknown outcome: verify whether it took effect BEFORE a new key). 503 idempotency_claim_held: retry with a NEW key; 503 idempotency_outcome_unknown: verify the outcome first."),
+    }, async ({ idempotencyKey, checkOrigin, dealId, expectedDealUpdatedAt, title, description, dueDate, priority, status, assignedTo, contactId }) => {
+        const result = await client.post("/api/v1/tasks", { checkOrigin, dealId, expectedDealUpdatedAt, title, description, dueDate, priority, status, assignedTo, contactId }, idempotencyKey !== undefined ? { headers: { "Idempotency-Key": idempotencyKey } } : undefined);
+        return formatResult(result);
+    }));
     server.tool("conduyt_get_deal", "Get a single deal with full details — value, currency, probability, stage, contact, expected close date, custom-field values, activities, tasks, and history. Use this to read structured custom-field data back out of a deal (e.g. for a P&L or balance-sheet model). Deal rows also carry hasNextStep and nextAppointmentAt (null unless your key can view the calendar) when the API returns them.", {
         id: z.string().describe("Deal UUID"),
     }, async ({ id }) => {

package/dist/tools/form-intakes.d.ts

@@ -11,7 +11,8 @@ import { ConduytClient } from "../client.js";
 /** What each tool's key must hold: the API names only the FIRST missing scope, so a 403 is surfaced with all of it. */
 export declare const LIST_AND_CREATE_REQUIREMENT = "the form-intakes AND contacts scopes on a write or admin tier key (a member: settings.edit, contacts.create and contacts.edit)";
 export declare const REVOKE_REQUIREMENT = "the form-intakes scope on an admin tier key (a member: settings.edit)";
-/** A 403 names the complete requirement; a busy 503 says when to retry (never replayed here: create is a mutation). */
+/** A 403 names the complete requirement; a busy 503 says when to retry (never replayed here: create is a mutation). Annotations go BEFORE the
+ *  client's message, so its details JSON object stays the final token (README, Error text grammar). */
 export declare function intakeToolError(err: unknown, requirement: string): {
     content: Array<{
         type: "text";

package/dist/tools/form-intakes.js

@@ -11,13 +11,14 @@ import { ConduytApiError, formatResult, formatToolError } from "../client.js";
 /** What each tool's key must hold: the API names only the FIRST missing scope, so a 403 is surfaced with all of it. */
 export const LIST_AND_CREATE_REQUIREMENT = "the form-intakes AND contacts scopes on a write or admin tier key (a member: settings.edit, contacts.create and contacts.edit)";
 export const REVOKE_REQUIREMENT = "the form-intakes scope on an admin tier key (a member: settings.edit)";
-/** A 403 names the complete requirement; a busy 503 says when to retry (never replayed here: create is a mutation). */
+/** A 403 names the complete requirement; a busy 503 says when to retry (never replayed here: create is a mutation). Annotations go BEFORE the
+ *  client's message, so its details JSON object stays the final token (README, Error text grammar). */
 export function intakeToolError(err, requirement) {
     if (err instanceof ConduytApiError) {
         if (err.status === 403)
-            return formatToolError(`${err.message}. This tool needs ${requirement}.`);
+            return formatToolError(`This tool needs ${requirement}. ${err.message}`);
         if (err.status === 503 && err.retryAfterSeconds !== null) {
-            return formatToolError(`busy; retry after ${err.retryAfterSeconds} s (${err.message})`);
+            return formatToolError(`busy; retry after ${err.retryAfterSeconds} s: ${err.message}`);
         }
     }
     throw err;

package/dist/tools/pipelines.js

@@ -9,7 +9,7 @@ export const ARCHIVE_ERROR_CODES = "A refusal carries a machine-readable code in
 /** above the archive route's 60 s transaction (up to 500 deal moves) plus post-commit events; the client default is 30 s */
 export const ARCHIVE_PIPELINE_TIMEOUT_MS = 75_000;
 export function registerPipelineTools(server, client) {
-    server.tool("conduyt_list_pipelines", "List all active sales pipelines with their stages. Use this to discover pipeline and stage UUIDs before creating or moving deals. Each pipeline carries color (one of the 10 palette hex colours, or null until the settings page saves one), automationOnly and sortOrder (the board-menu order); an archived pipeline's pre-archive name is archivedFromName (see conduyt_list_archived_pipelines).", {}, async () => {
+    server.tool("conduyt_list_pipelines", "List all active sales pipelines with their stages (soft-deleted stages are never included). Use this to discover pipeline and stage UUIDs before creating or moving deals. Each pipeline carries color (one of the 10 palette hex colours, or null until the settings page saves one), automationOnly and sortOrder (the board-menu order); an archived pipeline's pre-archive name is archivedFromName (see conduyt_list_archived_pipelines).", {}, async () => {
         const result = await client.get("/api/v1/pipelines");
         return formatResult(result);
     });
@@ -90,7 +90,7 @@ export function registerPipelineTools(server, client) {
         const result = await client.post("/api/v1/pipelines/reorder", { order, expectedRevision });
         return formatResult(result);
     }));
-    server.tool("conduyt_create_stage", "Add a new stage to an existing pipeline. The stage is appended after the current last stage. Use this to extend a funnel (e.g. add 'On Hold' or 'Declined/Dead').", {
+    server.tool("conduyt_create_stage", "Add a new stage to an existing pipeline. The stage is appended after the current last stage. Use this to extend a funnel (e.g. add 'On Hold' or 'Declined/Dead'). A name may be reused after the old stage of that name was deleted (deleted stages are soft-deleted and hidden).", {
         pipelineId: z.string().describe("Pipeline UUID to add the stage to"),
         name: z.string().describe("Stage name"),
         color: z.string().optional().describe("Hex color, e.g. '#3B82F6'"),
@@ -107,7 +107,7 @@ export function registerPipelineTools(server, client) {
         });
         return formatResult(result);
     });
-    server.tool("conduyt_update_stage", "Update a stage within a pipeline — rename, recolor, reorder (sortOrder), or change its won/lost/system flags.", {
+    server.tool("conduyt_update_stage", "Update a stage within a pipeline — rename, recolor, reorder (sortOrder), or change its won/lost/system flags. A soft-deleted stage (conduyt_delete_stage) answers 404.", {
         pipelineId: z.string().describe("Pipeline UUID"),
         stageId: z.string().describe("Stage UUID to update"),
         name: z.string().optional().describe("Updated stage name"),
@@ -128,7 +128,7 @@ export function registerPipelineTools(server, client) {
         const result = await client.post(`/api/v1/pipelines/${pipelineId}/stages/reorder`, { order, expectedRevision });
         return formatResult(result);
     }));
-    strictInput(server.tool("conduyt_delete_stage", "Delete a stage from a pipeline. Strict input: the guards are spelled moveTo and expectedSettingsRevision, any other spelling (move_to, expected_settings_revision, a typo) is InvalidParams and nothing is deleted. The stage must be empty (no deals) unless moveTo names another stage of the same pipeline (same won / lost setting, not a system stage): its live deals then move there and the stage is deleted in one transaction. A stage a soft-deleted deal still points at is refused. Pass expectedSettingsRevision (the settingsRevision from conduyt_get_settings_revision, read right before) to refuse the delete when settings changed since you read them; the answer is then { id, deleted: true, settingsRevision } with the revision after the delete. A refusal carries a machine-readable code in the error text and the server's message, never swallowed: stale_settings_revision (409), pipeline_archived (409), intake_target (409, enabled intake routes deals into this stage); other 409s (DPP status map, unattended-lead automations, deals that used the stage) have no code but name the cause.", {
+    strictInput(server.tool("conduyt_delete_stage", "Delete a stage from a pipeline (soft delete). Strict input: the guards are spelled moveTo and expectedSettingsRevision, any other spelling (move_to, expected_settings_revision, a typo) is InvalidParams and nothing is deleted. An EMPTY stage can always be deleted, even if deals once used it: the row is kept so deal history, activities, audit rows and reports keep its name, but the stage is hidden from every pipeline and stage list, GET / PATCH on it answer 404, there is NO restore in v1, and its name may be reused by a new stage. Its stage rule, appointment-outcome mappings and status metadata are removed with it. With moveTo (another stage of the same pipeline, same won / lost setting, not a system stage) its live deals move there and the stage is deleted in one transaction. Pass expectedSettingsRevision (the settingsRevision from conduyt_get_settings_revision, read right before) to refuse the delete when settings changed since you read them; the answer is then { id, deleted: true, settingsRevision } with the revision after the delete. A refusal is a 409 whose server message is surfaced verbatim (never swallowed, never retried): deals currently in the stage and no moveTo (\"Cannot delete stage: N deal(s) are in this stage...\"), \"Cannot delete stage: it is used by N active automation(s) (names). Change their stage or pause them first.\" (a published automation references the stage in an action, trigger, condition or wait-until), the DPP status map selects it, plus the coded refusals stale_settings_revision, pipeline_archived and intake_target (enabled intake routes deals into this stage); a moveTo that is not a valid target is a 400. Accepted window: a run parked or in flight before the delete is not tracked; at the step that targets the deleted stage it fails or is skipped with a clear reason in the execution log.", {
         pipelineId: z.string().describe("Pipeline UUID"),
         stageId: z.string().describe("Stage UUID to delete"),
         moveTo: z.string().uuid().optional().describe("Another stage of the same pipeline the live deals move to (sent as move_to)"),

package/dist/tools/tasks.js

@@ -49,7 +49,7 @@ export function registerTaskTools(server, client) {
         const result = await client.get(`/api/v1/tasks?${params}`);
         return formatResult(result);
     });
-    server.tool("conduyt_create_task", "Create a new task. Can be linked to a contact or deal and assigned to a team member.", {
+    server.tool("conduyt_create_task", "Create a new task. Can be linked to a contact or deal and assigned to a team member. This is the ORDINARY task route: ordinary tasks are unconstrained and may coexist with or race a Pipeline health quick-fix task. The database allows at most one non-done quick-fix task per deal (a second is refused 409 deal_has_next_action); to create the quick fix itself (checkOrigin + expectedDealUpdatedAt, guarded against a deal that changed) use conduyt_pipeline_health_fix_next_action. A 409 without a code means the contact was merged or deleted mid-request: retry against the surviving record. Errors reach you verbatim and are never retried.", {
         title: z.string().describe("Task title"),
         description: z.string().optional().describe("Task description"),
         dueDate: z.string().optional().describe("Due date (ISO 8601)"),
@@ -68,7 +68,7 @@ export function registerTaskTools(server, client) {
         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.", {
+    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. A 409 means nothing was written, surfaced verbatim and never retried: code deal_has_next_action (\"This deal already has a next action booked.\": re-opening or re-linking a quick-fix task would give the deal a second open one), or no code (the task changed while saving: read it again and retry).", {
         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)"),

package/package.json

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

package/scripts/coverage-matrix.json

@@ -1,6 +1,6 @@
 {
-  "generatedAt": "2026-10-09T04:00:29.593Z",
-  "toolCount": 334,
+  "generatedAt": "2026-10-09T06:41:49.430Z",
+  "toolCount": 336,
   "totalEndpoints": 1066,
   "counts": {
     "covered": 299,
@@ -2165,6 +2165,7 @@
     "PATCH /api/v1/deals/:id": {
       "status": "covered",
       "tools": [
+        "conduyt_pipeline_health_fix_deal",
         "conduyt_update_deal"
       ]
     },
@@ -4495,6 +4496,7 @@
     "POST /api/v1/tasks": {
       "status": "covered",
       "tools": [
+        "conduyt_pipeline_health_fix_next_action",
         "conduyt_create_task"
       ]
     },