conduyt-mcp 4.97.0 → 4.98.0

package/README.md

@@ -17,7 +17,7 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 | `conduyt_list_contacts` | List and search contacts with filters |
 | `conduyt_get_contact` | Get full contact details with timeline; `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; optional `expectedRevision` (0..2147483647) refuses a stale save with 409 `contact_changed` (code + current revision in the error) |
+| `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) |
 | `conduyt_merge_contacts` | DESTRUCTIVE: merge duplicates into a survivor (`POST /contacts/merge`, owner/admin); the losers are deleted. Two steps: without `confirmImpact` a preview (`counts`, `guardCounts`, `identifierOverflow`, `blockers`); with `confirmImpact: true` plus the preview's `expectedCounts`, `expectedGuardCounts` (and `expectedIdentifiers`) the merge; the confirm is sent only against a preview this server returned in the last 10 minutes (else refused locally); the server pins the record counts, guard counts and identifier plan, not other field edits made after the preview; 75 s timeout. Moved counts 409, 503 `merge_contacts_busy` / `merge_budget_exhausted` + Retry-After surfaced verbatim, never retried |
 | `conduyt_list_duplicate_proposals` | List a contact's possible duplicates (`GET /contacts/{id}/duplicate-proposals`): open and not-sure proposals (`id`, `status`, `rule`, `other`, `raisedHere`) and the identifiers held from it (value-free); a record you cannot view has no id; keyset paged with `cursor` / `limit` (default 50) and `held_cursor` / `held_limit` (default 20), answers `total`, `nextCursor`, the held twins and membership revisions (re-read page one when a later page answers another revision) |
 | `conduyt_list_import_duplicate_proposals` | The duplicate proposals one import raised on the records it created (`GET /imports/{id}/duplicate-proposals`, contacts:view): every status, oldest first, `page` / `per_page` (default 50), `{ rows, meta }`; a record you cannot view is "A contact you cannot view" with no id |
@@ -33,13 +33,15 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 | `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`, `entryByAutomationOnly`: only an automation can move or create a deal into the stage, every other entry is refused 422 `stage_automation_only`; `conduyt_list_pipelines` shows it on each stage); other stages untouched; revision-aware, retried once on a 409 |
+| `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`, `entryByAutomationOnly`: only an automation can move or create a deal into the stage, every other entry is refused 422 `stage_automation_only`; `conduyt_list_pipelines` shows it on each stage; `closesOtherOpenDeals` (+ `closesOtherOpenDealsReason`, 1-200 characters): a deal entering the stage marks the contact's other open deals lost; `assignsContactOwner`: the entering deal's owner becomes the contact owner, the previous contact owner stays a collaborator); other stages untouched; revision-aware, retried once on a 409 |
+| `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_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` |
 | `conduyt_get_pipeline_rot_days` / `conduyt_set_pipeline_rot_days` | Read / set the stale-in-stage threshold per pipeline (`pipelineRotDays`, 1-90 days); only the pipelines sent change; revision-aware, retried once on a 409 |
 | `conduyt_get_deal` | Get deal details with history, including custom-field values |
 | `conduyt_create_deal` | Create a deal with full attributes — currency (e.g. GBP), probability, priority, expected close date, contact/company, and structured custom-field values |
-| `conduyt_update_deal` | Move stage, change value/currency, set probability or close date, reassign, mark won/lost, or write custom-field values; optional `expectedUpdatedAt` pins the `updatedAt` you read, and a stale pin returns 409 `deal_changed` with the current `updatedAt` and writes nothing |
+| `conduyt_update_deal` | Move stage, change value/currency, set probability or close date, reassign (`keepPreviousOwnerAsCollaborator: true` keeps the previous owner as a read-only collaborator of the contact; 400 without `assignedTo` or with a contact change), mark won/lost, or write custom-field values; optional `expectedUpdatedAt` pins the `updatedAt` you read, and a stale pin returns 409 `deal_changed` with the current `updatedAt` and writes nothing |
 | `conduyt_import_deals` | Bulk-import deals (pipeline/stage by name, contact by email) via the canonical import engine — dedupes, side-effect-free, owner/admin only |
 
 ### Tasks

package/dist/register-all.js

@@ -11,7 +11,7 @@ import { registerSequenceTools } from "./tools/sequences.js";
 import { registerMessagingTools } from "./tools/messaging.js";
 import { registerMessageCheckSettingsTools } from "./tools/message-check-settings.js";
 import { registerCallTools } from "./tools/calls.js";
-import { registerDialerSettingsTools } from "./tools/dialer-settings.js";
+import { registerDialerSettingsTools, registerCallingHoursTools } from "./tools/dialer-settings.js";
 import { registerCompanyTools } from "./tools/companies.js";
 import { registerTagTools } from "./tools/tags.js";
 import { registerCalendarTools } from "./tools/calendar.js";
@@ -31,6 +31,7 @@ import { registerUserTools } from "./tools/users.js";
 import { registerBulkTools } from "./tools/bulk.js";
 import { registerBatchOperationTools } from "./tools/batch-operations.js";
 import { registerDncTools } from "./tools/dnc.js";
+import { registerEmailOptOutTools } from "./tools/email-opt-out.js";
 import { registerSavedFilterTools } from "./tools/saved-filters.js";
 import { registerDripCampaignTools } from "./tools/drip-campaigns.js";
 import { registerScoringTools } from "./tools/scoring.js";
@@ -69,6 +70,7 @@ export function registerAllTools(server, client) {
     registerMessageCheckSettingsTools(server, client);
     registerCallTools(server, client);
     registerDialerSettingsTools(server, client);
+    registerCallingHoursTools(server, client);
     registerCompanyTools(server, client);
     registerTagTools(server, client);
     registerCalendarTools(server, client);
@@ -88,6 +90,7 @@ export function registerAllTools(server, client) {
     registerBulkTools(server, client);
     registerBatchOperationTools(server, client);
     registerDncTools(server, client);
+    registerEmailOptOutTools(server, client);
     registerSavedFilterTools(server, client);
     registerDripCampaignTools(server, client);
     registerScoringTools(server, client);

package/dist/tool-annotations.js

@@ -105,6 +105,8 @@ export const TOOL_ANNOTATIONS = {
     conduyt_sync_local_presence: row("Sync Local Presence", false, false, false), // every call writes lastSyncedAt (local-presence-sync.ts:225)
     conduyt_get_dialer_settings: ro("Get Dialer Settings"),
     conduyt_update_dialer_settings: update("Update Dialer Settings"),
+    conduyt_get_calling_hours: ro("Get Calling Hours"),
+    conduyt_update_calling_hours: destroy("Update Calling Hours"), // enabled:false (with acknowledgeAnyHour) switches the calling-time check off, which re-enables outreach at any hour: a compliance change like the DNC removals; a repeat saves the same window
     conduyt_get_call_recording_settings: ro("Get Call Recording Settings"),
     conduyt_update_call_recording_settings: update("Update Call Recording Settings"),
     conduyt_list_companies: ro("List Companies"),
@@ -216,6 +218,9 @@ export const TOOL_ANNOTATIONS = {
     conduyt_list_dnc: ro("List DNC"),
     conduyt_add_dnc: update("Add DNC"),
     conduyt_remove_dnc: destroy("Remove DNC"),
+    conduyt_list_email_opt_outs: ro("List Email Opt-Outs"),
+    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_list_saved_filters: ro("List Saved Filters"),
     conduyt_create_saved_filter: create("Create Saved Filter"),
     conduyt_update_saved_filter: update("Update Saved Filter"),

package/dist/tools/automations.d.ts

@@ -1,7 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ConduytClient } from "../client.js";
 /** (card ownership per lane, app 10-08/09) the action options an agent can set; the catalog does not carry action config, so this is the one place they are documented */
-export declare const CARD_OWNERSHIP_ACTIONS_NOTE = " Card ownership per lane: assign_to_user config {userId | userIds (round robin) | groupId, mode (single | round_robin | trigger_host), target|applyTo: contact|deal|both, overwriteExisting, laneSource, lanePipelineId, laneStageId}: laneSource names a card lane (the Deal.source its Auto-Create step wrote, e.g. 'GSM', max 500 chars) and makes the deal leg assign the contact's newest OPEN card from that lane (inside lanePipelineId when set) instead of the run's deal; when the contact has none and lanePipelineId is set, the card is created there (laneStageId, else the pipeline's first stage) already owned by the user; lanePipelineId or laneStageId without laneSource, or laneStageId without lanePipelineId, is refused; a lane never applies to an 'Assign to: contact' step. assign_to_user mode 'trigger_host' assigns to the appointment's booked host (appointment.booked runs only; fails closed when the run has no host). create_deal config {pipelineId (required), stageId, dealName, dealValue, allowDuplicates, status, source, assignedTo, assigneeMode, leaveUnassigned}: leaveUnassigned true leaves the card unassigned when no assignee is set (default false: the card goes to the lead's owner). assigneeMode 'trigger_host' assigns the card to the appointment's booked host (appointment.booked runs only; wins over assignedTo; fails closed when the run has no host, creating nothing). The condition field 'Booked host' (trigger.hostUserId) exists on appointment.booked, whose payload now carries hostUserId. close_other_open_deals config {lostReason (required)}: closes the contact's OTHER open cards as lost with that reason, keeping the run's own card (each moves to its pipeline's lost stage with the usual stage-change effects; cards already won/lost, in the DPP Post-Close pipeline or in a pipeline with no lost stage are skipped; a re-run closes nothing twice); it needs the run's own deal, so use a deal trigger or a find_opportunity step first.";
+export declare const CARD_OWNERSHIP_ACTIONS_NOTE = " Card ownership per lane: assign_to_user config {userId | userIds (round robin) | groupId, mode (single | round_robin | trigger_host), target|applyTo: contact|deal|both, overwriteExisting, previousOwner, laneSource, lanePipelineId, laneStageId}: laneSource names a card lane (the Deal.source its Auto-Create step wrote, e.g. 'GSM', max 500 chars) and makes the deal leg assign the contact's newest OPEN card from that lane (inside lanePipelineId when set) instead of the run's deal; when the contact has none and lanePipelineId is set, the card is created there (laneStageId, else the pipeline's first stage) already owned by the user; lanePipelineId or laneStageId without laneSource, or laneStageId without lanePipelineId, is refused; a lane never applies to an 'Assign to: contact' step. assign_to_user mode 'trigger_host' assigns to the appointment's booked host (appointment.booked runs only; fails closed when the run has no host). previousOwner (release | keep_as_collaborator; default release) says what happens to the previous owner when the step changes an owner: release means they lose the lead unless something else explains their access (e.g. another open card of theirs), keep_as_collaborator keeps them as a collaborator of the contact (they still see the lead and its cards, read-only); any other value is refused, and keep_as_collaborator is refused on a step with a card lane (laneSource) unless it assigns the contact only (validate and publish answer a field error on action.config.previousOwner). create_deal config {pipelineId (required), stageId, dealName, dealValue, allowDuplicates, status, source, assignedTo, assigneeMode, leaveUnassigned}: leaveUnassigned true leaves the card unassigned when no assignee is set (default false: the card goes to the lead's owner). assigneeMode 'trigger_host' assigns the card to the appointment's booked host (appointment.booked runs only; wins over assignedTo; fails closed when the run has no host, creating nothing). The condition field 'Booked host' (trigger.hostUserId) exists on appointment.booked, whose payload now carries hostUserId. close_other_open_deals config {lostReason (required)}: closes the contact's OTHER open cards as lost with that reason, keeping the run's own card (each moves to its pipeline's lost stage with the usual stage-change effects; cards already won/lost, in the DPP Post-Close pipeline or in a pipeline with no lost stage are skipped; a re-run closes nothing twice); it needs the run's own deal, so use a deal trigger or a find_opportunity step first.";
 /** (deal nodes, app 10-13) find_opportunity v2, link_appointment_to_deal, update_deal_field systemField source; the catalog does not carry action config */
 export declare const DEAL_NODES_ACTIONS_NOTE = " Deal nodes: find_opportunity config {version: 2, pipelineIds (ordered; the first pipeline holding a match wins; empty = every pipeline), status (open default | won | lost | abandoned | any), excludeSources (lead sources never matched, case-insensitive), excludeCreatedByAutomationIds (automations whose create_deal cards are skipped; cards created from 2026-10-13 on), matchField {fieldKey, value} (searches the WHOLE WORKSPACE, any contact, for the card whose deal custom field equals the value, merge fields allowed e.g. {{trigger.oes}}; a card is found when its field holds the searched value (trimmed) as the same text exactly (no case folding); a value written with separators such as dashes or spaces also matches its digits as text; it matches a stored number only when the value (or those digits) is a plain number with no leading zero and at most 15 significant digits that a number holds exactly (007 is text and does not match the number 7; a 16-digit value, 1e-400 or 3e-324 is text only); booleans and differently formatted stored values never match; status, pipelines and exclusions still apply; exactly one match is found, several are ambiguous and take not found; a found card becomes the run's contact when the run has none; the field must exist; an empty rendered value finds nothing), resolution}: searches the run's contact's cards; FOUND makes the card the run's deal and follows nextIfTrue (else next), NOT FOUND is a normal outcome that follows nextIfFalse (else next) and leaves the run's existing deal unchanged (a later deal step on the false branch still acts on the deal the run already had); without version 2 the step keeps the original single-pipeline lookup (a miss fails the step). Prerequisite: a version 2 find needs step cursors on this workspace, and publishing refuses (find_needs_step_cursors) with \"Find opportunity needs step cursors on this workspace; ask support\"; every version 2 find must hold its own live step cursor or it hard-stops the run without selecting or routing. A version 2 find cannot be retried on its own: retrying a failed one alone answers 409, so re-trigger the automation for the contact. An automation definition that touches deals needs the `deals` scope on an API key: without it the write answers 403. link_appointment_to_deal config {stageId, pipelineId (needs stageId), lostReason}: in an appointment-triggered run, links the trigger's appointment to the run's deal (its appointment fields follow it; a newer booking is never displaced; the appointment must be the deal's contact's), then optionally moves the card; it needs an appointment trigger and the run's deal (find_opportunity first, or a booking made with a deal id). update_deal_field config {systemField: \"source\", value, overwriteExisting}: sets the deal's own lead source instead of a custom field (a value only, trimmed, at most 500 characters; overwriteExisting false writes only while the source is the Unknown label).";
 /** (#124, automation unknown keys / types) the refusal codes the write paths answer; surfaced verbatim by the client (details JSON object last), never retried */

package/dist/tools/automations.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { formatResult, formatToolError } from "../client.js";
 /** (card ownership per lane, app 10-08/09) the action options an agent can set; the catalog does not carry action config, so this is the one place they are documented */
-export const CARD_OWNERSHIP_ACTIONS_NOTE = " Card ownership per lane: assign_to_user config {userId | userIds (round robin) | groupId, mode (single | round_robin | trigger_host), target|applyTo: contact|deal|both, overwriteExisting, laneSource, lanePipelineId, laneStageId}: laneSource names a card lane (the Deal.source its Auto-Create step wrote, e.g. 'GSM', max 500 chars) and makes the deal leg assign the contact's newest OPEN card from that lane (inside lanePipelineId when set) instead of the run's deal; when the contact has none and lanePipelineId is set, the card is created there (laneStageId, else the pipeline's first stage) already owned by the user; lanePipelineId or laneStageId without laneSource, or laneStageId without lanePipelineId, is refused; a lane never applies to an 'Assign to: contact' step. assign_to_user mode 'trigger_host' assigns to the appointment's booked host (appointment.booked runs only; fails closed when the run has no host). create_deal config {pipelineId (required), stageId, dealName, dealValue, allowDuplicates, status, source, assignedTo, assigneeMode, leaveUnassigned}: leaveUnassigned true leaves the card unassigned when no assignee is set (default false: the card goes to the lead's owner). assigneeMode 'trigger_host' assigns the card to the appointment's booked host (appointment.booked runs only; wins over assignedTo; fails closed when the run has no host, creating nothing). The condition field 'Booked host' (trigger.hostUserId) exists on appointment.booked, whose payload now carries hostUserId. close_other_open_deals config {lostReason (required)}: closes the contact's OTHER open cards as lost with that reason, keeping the run's own card (each moves to its pipeline's lost stage with the usual stage-change effects; cards already won/lost, in the DPP Post-Close pipeline or in a pipeline with no lost stage are skipped; a re-run closes nothing twice); it needs the run's own deal, so use a deal trigger or a find_opportunity step first.";
+export const CARD_OWNERSHIP_ACTIONS_NOTE = " Card ownership per lane: assign_to_user config {userId | userIds (round robin) | groupId, mode (single | round_robin | trigger_host), target|applyTo: contact|deal|both, overwriteExisting, previousOwner, laneSource, lanePipelineId, laneStageId}: laneSource names a card lane (the Deal.source its Auto-Create step wrote, e.g. 'GSM', max 500 chars) and makes the deal leg assign the contact's newest OPEN card from that lane (inside lanePipelineId when set) instead of the run's deal; when the contact has none and lanePipelineId is set, the card is created there (laneStageId, else the pipeline's first stage) already owned by the user; lanePipelineId or laneStageId without laneSource, or laneStageId without lanePipelineId, is refused; a lane never applies to an 'Assign to: contact' step. assign_to_user mode 'trigger_host' assigns to the appointment's booked host (appointment.booked runs only; fails closed when the run has no host). previousOwner (release | keep_as_collaborator; default release) says what happens to the previous owner when the step changes an owner: release means they lose the lead unless something else explains their access (e.g. another open card of theirs), keep_as_collaborator keeps them as a collaborator of the contact (they still see the lead and its cards, read-only); any other value is refused, and keep_as_collaborator is refused on a step with a card lane (laneSource) unless it assigns the contact only (validate and publish answer a field error on action.config.previousOwner). create_deal config {pipelineId (required), stageId, dealName, dealValue, allowDuplicates, status, source, assignedTo, assigneeMode, leaveUnassigned}: leaveUnassigned true leaves the card unassigned when no assignee is set (default false: the card goes to the lead's owner). assigneeMode 'trigger_host' assigns the card to the appointment's booked host (appointment.booked runs only; wins over assignedTo; fails closed when the run has no host, creating nothing). The condition field 'Booked host' (trigger.hostUserId) exists on appointment.booked, whose payload now carries hostUserId. close_other_open_deals config {lostReason (required)}: closes the contact's OTHER open cards as lost with that reason, keeping the run's own card (each moves to its pipeline's lost stage with the usual stage-change effects; cards already won/lost, in the DPP Post-Close pipeline or in a pipeline with no lost stage are skipped; a re-run closes nothing twice); it needs the run's own deal, so use a deal trigger or a find_opportunity step first.";
 /** (deal nodes, app 10-13) find_opportunity v2, link_appointment_to_deal, update_deal_field systemField source; the catalog does not carry action config */
 export const DEAL_NODES_ACTIONS_NOTE = " Deal nodes: find_opportunity config {version: 2, pipelineIds (ordered; the first pipeline holding a match wins; empty = every pipeline), status (open default | won | lost | abandoned | any), excludeSources (lead sources never matched, case-insensitive), excludeCreatedByAutomationIds (automations whose create_deal cards are skipped; cards created from 2026-10-13 on), matchField {fieldKey, value} (searches the WHOLE WORKSPACE, any contact, for the card whose deal custom field equals the value, merge fields allowed e.g. {{trigger.oes}}; a card is found when its field holds the searched value (trimmed) as the same text exactly (no case folding); a value written with separators such as dashes or spaces also matches its digits as text; it matches a stored number only when the value (or those digits) is a plain number with no leading zero and at most 15 significant digits that a number holds exactly (007 is text and does not match the number 7; a 16-digit value, 1e-400 or 3e-324 is text only); booleans and differently formatted stored values never match; status, pipelines and exclusions still apply; exactly one match is found, several are ambiguous and take not found; a found card becomes the run's contact when the run has none; the field must exist; an empty rendered value finds nothing), resolution}: searches the run's contact's cards; FOUND makes the card the run's deal and follows nextIfTrue (else next), NOT FOUND is a normal outcome that follows nextIfFalse (else next) and leaves the run's existing deal unchanged (a later deal step on the false branch still acts on the deal the run already had); without version 2 the step keeps the original single-pipeline lookup (a miss fails the step). Prerequisite: a version 2 find needs step cursors on this workspace, and publishing refuses (find_needs_step_cursors) with \"Find opportunity needs step cursors on this workspace; ask support\"; every version 2 find must hold its own live step cursor or it hard-stops the run without selecting or routing. A version 2 find cannot be retried on its own: retrying a failed one alone answers 409, so re-trigger the automation for the contact. An automation definition that touches deals needs the `deals` scope on an API key: without it the write answers 403. link_appointment_to_deal config {stageId, pipelineId (needs stageId), lostReason}: in an appointment-triggered run, links the trigger's appointment to the run's deal (its appointment fields follow it; a newer booking is never displaced; the appointment must be the deal's contact's), then optionally moves the card; it needs an appointment trigger and the run's deal (find_opportunity first, or a booking made with a deal id). update_deal_field config {systemField: \"source\", value, overwriteExisting}: sets the deal's own lead source instead of a custom field (a value only, trimmed, at most 500 characters; overwriteExisting false writes only while the source is the Unknown label).";
 /** (#124, automation unknown keys / types) the refusal codes the write paths answer; surfaced verbatim by the client (details JSON object last), never retried */

package/dist/tools/board-settings.d.ts

@@ -11,6 +11,7 @@ export declare const DEAL_CARD_FIELDS: readonly ["value", "contact", "phones", "
 export declare const MAX_DEAL_CARD_FIELDS = 8;
 export declare const MAX_STAGE_REQUIRED_FIELDS = 25;
 export declare const MAX_STAGE_REQUIRED_DOCUMENTS = 20;
+export declare const MAX_CLOSES_OTHERS_REASON_LENGTH = 200;
 export declare const MIN_PIPELINE_ROT_DAYS = 1;
 export declare const MAX_PIPELINE_ROT_DAYS = 90;
 export declare function registerBoardSettingsTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/board-settings.js

@@ -14,7 +14,8 @@ export const MAX_DEAL_CARD_FIELDS = 8;
 export const MAX_STAGE_REQUIRED_FIELDS = 25;
 export const MAX_STAGE_REQUIRED_DOCUMENTS = 20;
 const CUSTOM_FIELD_RE = /^custom:[a-zA-Z_][a-zA-Z0-9_]*$/;
-const RULE_KEYS = ["requiredFields", "requiredDocuments", "lostReasonLabel", "lostReasonOptions", "lostReasonAllowOther", "entryByAutomationOnly"];
+const RULE_KEYS = ["requiredFields", "requiredDocuments", "lostReasonLabel", "lostReasonOptions", "lostReasonAllowOther", "entryByAutomationOnly", "closesOtherOpenDeals", "closesOtherOpenDealsReason", "assignsContactOwner"];
+export const MAX_CLOSES_OTHERS_REASON_LENGTH = 200;
 export const MIN_PIPELINE_ROT_DAYS = 1;
 export const MAX_PIPELINE_ROT_DAYS = 90;
 const requiredField = z.union([
@@ -27,7 +28,7 @@ const cardField = z.union([
 ]);
 const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 export function registerBoardSettingsTools(server, client) {
-    strictInput(server.tool("conduyt_get_stage_rules", "Read the per-stage rules (settings.pipelineStageRules) as { pipelineId: { stageId: { requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther, entryByAutomationOnly } } }, optionally for one pipeline or one stage. A deal may enter a stage only when its requiredFields are filled (built-ins value, expectedCloseDate, contactId, assignedTo, lostReason, or custom:<fieldKey> for a deal custom field) and it has at least requiredDocuments documents attached. entryByAutomationOnly: true (absent = off) means only an automation run can move or create a deal INTO the stage; every other entry, admins and API keys included, is refused 422 stage_automation_only (moving out stays free). Set one stage with conduyt_set_stage_rules. Pipelines your key cannot see are left out.", {
+    strictInput(server.tool("conduyt_get_stage_rules", "Read the per-stage rules (settings.pipelineStageRules) as { pipelineId: { stageId: { requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther, entryByAutomationOnly, closesOtherOpenDeals, closesOtherOpenDealsReason, assignsContactOwner } } }, optionally for one pipeline or one stage. A deal may enter a stage only when its requiredFields are filled (built-ins value, expectedCloseDate, contactId, assignedTo, lostReason, or custom:<fieldKey> for a deal custom field) and it has at least requiredDocuments documents attached. entryByAutomationOnly: true (absent = off) means only an automation run can move or create a deal INTO the stage; every other entry, admins and API keys included, is refused 422 stage_automation_only (moving out stays free). What ENTERING the stage does (each absent = off): closesOtherOpenDeals: true marks every OTHER open deal card of the same contact, in any pipeline, lost (with closesOtherOpenDealsReason, or \"Closed automatically: another card reached <stage>\"); assignsContactOwner: true makes the owner of the entering card the contact's owner (the previous contact owner stays as a collaborator). Set one stage with conduyt_set_stage_rules. Pipelines your key cannot see are left out.", {
         pipelineId: z.string().uuid().optional().describe("Only this pipeline's stage rules"),
         stageId: z.string().uuid().optional().describe("Only this stage's rule (needs pipelineId)"),
     }, async ({ pipelineId, stageId }) => {
@@ -42,7 +43,7 @@ export function registerBoardSettingsTools(server, client) {
         }
         return formatResult({ data: { pipelineStageRules: out } });
     }));
-    strictInput(server.tool("conduyt_set_stage_rules", "Set the rule of ONE stage (settings.pipelineStageRules[pipelineId][stageId]; admin key, settings:edit). Only the fields you pass change: they are merged into that stage's current rule, and every other stage and pipeline is left exactly as stored. requiredFields REPLACES the stage's list (max 25 entries; built-ins value, expectedCloseDate, contactId, assignedTo, lostReason, or custom:<fieldKey> for one of the account's DEAL custom fields; [] clears it); requiredDocuments is the number of documents that must be attached before a deal may enter the stage (integer 0-20); lostReasonLabel (1-60 chars) and lostReasonOptions (max 50, trimmed and de-duplicated by the API) configure the stage's lost-reason prompt; lostReasonAllowOther (boolean) lets the rep also pick \"Other\" and type the reason (stored as the reason text; only takes effect while the stage has lost-reason options); entryByAutomationOnly (boolean) is \"Entry by automation only\": true means only an automation run can move or create a deal INTO the stage, and every route entry (deal update, create, bulk edit/update, inbound deals webhook, appointment outcome, public contact route, admins and API keys included) is refused 422 stage_automation_only with the message \"Only an automation can move a deal into <stage>\" (moving out stays free; for a manual correction set it false, move the deal, set it true again; it cannot be the starting stage of automatic intake deals). Read-merge-write with the settings revision; if another save lands first it is re-read and retried once, then the conflict is returned with the current settings. An unknown custom field key, pipeline or stage is refused by the API.", {
+    strictInput(server.tool("conduyt_set_stage_rules", "Set the rule of ONE stage (settings.pipelineStageRules[pipelineId][stageId]; admin key, settings:edit). Only the fields you pass change: they are merged into that stage's current rule, and every other stage and pipeline is left exactly as stored. requiredFields REPLACES the stage's list (max 25 entries; built-ins value, expectedCloseDate, contactId, assignedTo, lostReason, or custom:<fieldKey> for one of the account's DEAL custom fields; [] clears it); requiredDocuments is the number of documents that must be attached before a deal may enter the stage (integer 0-20); lostReasonLabel (1-60 chars) and lostReasonOptions (max 50, trimmed and de-duplicated by the API) configure the stage's lost-reason prompt; lostReasonAllowOther (boolean) lets the rep also pick \"Other\" and type the reason (stored as the reason text; only takes effect while the stage has lost-reason options); entryByAutomationOnly (boolean) is \"Entry by automation only\": true means only an automation run can move or create a deal INTO the stage, and every route entry (deal update, create, bulk edit/update, inbound deals webhook, appointment outcome, public contact route, admins and API keys included) is refused 422 stage_automation_only with the message \"Only an automation can move a deal into <stage>\" (moving out stays free; for a manual correction set it false, move the deal, set it true again; it cannot be the starting stage of automatic intake deals); closesOtherOpenDeals (boolean) is \"Close the contact's other open deal cards\": true means a deal that ENTERS this stage (moved in or created in it, by any writer) marks every OTHER open deal of the same contact, in any pipeline, lost, each moving to its own pipeline's lost stage with closesOtherOpenDealsReason (emitting deal.stage_changed / deal.lost; the entering deal is never touched; closed cards can be reopened); closesOtherOpenDealsReason (string, trimmed, 1-200 characters) is the lost reason written on those cards (absent = \"Closed automatically: another card reached <stage name>\"); assignsContactOwner (boolean) is \"Card owner becomes the contact owner\": true means the owner of a deal that enters this stage becomes its contact's owner (only an active member; a deal with no owner changes nothing) and the previous contact owner stays on the contact as a collaborator. Both switches are per stage, never \"every Won stage\"; send false to turn one off. Read-merge-write with the settings revision; if another save lands first it is re-read and retried once, then the conflict is returned with the current settings. An unknown custom field key, pipeline or stage is refused by the API.", {
         pipelineId: z.string().uuid().describe("Pipeline UUID"),
         stageId: z.string().uuid().describe("Stage UUID within that pipeline"),
         requiredFields: z.array(requiredField).max(MAX_STAGE_REQUIRED_FIELDS).optional().describe("Fields a deal must have filled to enter the stage: value, expectedCloseDate, contactId, assignedTo, lostReason, or custom:<deal custom field key>. Replaces the list."),
@@ -51,10 +52,13 @@ export function registerBoardSettingsTools(server, client) {
         lostReasonOptions: z.array(z.string()).max(50).optional().describe("Dropdown options of the lost-reason prompt (replaces the list)"),
         lostReasonAllowOther: z.boolean().optional().describe("The rep may pick 'Other' and type the reason (stored as the reason text). Needs lost-reason options to take effect."),
         entryByAutomationOnly: z.boolean().optional().describe("Entry by automation only: when true, only an automation run can move or create a deal INTO this stage; every API / UI entry (admins and API keys included) is refused 422 stage_automation_only. Moving a deal out stays free. To make a manual correction, turn it off, move the deal, turn it back on."),
+        closesOtherOpenDeals: z.boolean().optional().describe("Close the contact's other open deal cards: when true, a deal that enters this stage (moved in or created in it) marks every OTHER open deal of the same contact, in any pipeline, lost (each moves to its pipeline's lost stage with closesOtherOpenDealsReason). The entering deal is never touched; closed cards can be reopened."),
+        closesOtherOpenDealsReason: z.string().trim().min(1).max(MAX_CLOSES_OTHERS_REASON_LENGTH).optional().describe("The lost reason written on the cards closed by closesOtherOpenDeals (1-200 characters). Absent = \"Closed automatically: another card reached <stage name>\"."),
+        assignsContactOwner: z.boolean().optional().describe("Card owner becomes the contact owner: when true, the owner of a deal that enters this stage becomes its contact's owner (only an active member; a deal with no owner changes nothing). The previous contact owner stays on the contact as a collaborator."),
     }, async ({ pipelineId, stageId, ...given }) => {
         const change = Object.fromEntries(Object.entries(given).filter(([, v]) => v !== undefined));
         if (Object.keys(change).length === 0) {
-            throw new Error("Nothing to set. Pass at least one of requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther, entryByAutomationOnly.");
+            throw new Error("Nothing to set. Pass at least one of requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther, entryByAutomationOnly, closesOtherOpenDeals, closesOtherOpenDealsReason, assignsContactOwner.");
         }
         return patchGeneralSettingsMerged(client, (settings) => {
             const rules = isObj(settings.pipelineStageRules) ? settings.pipelineStageRules : {};

package/dist/tools/contacts.d.ts

@@ -3,6 +3,8 @@ import { ConduytClient } from "../client.js";
 /** The contact save revision pin (catalog bounds: integer 0..2147483647). */
 /** Create-from-call rule: the server derives the lead's source ("Inbound Call") and its owner (the rep who took the call), so a
  *  create that carries callId must not carry either field. Refused here, after every field is merged, with the rule named. */
+/** (#361) the API's 400 text for keepPreviousOwnerAsCollaborator sent without a new owner */
+export declare const KEEP_PREVIOUS_OWNER_NEEDS_ASSIGNEE = "keepPreviousOwnerAsCollaborator needs assignedTo (the new owner) in the same request";
 export declare const CALL_DERIVED_REFUSAL = "callId cannot be combined with source or assignedTo: for a lead created from a call the server derives both (source is 'Inbound Call', the owner is the rep who took the call). Omit them.";
 export declare const callDerivedFieldsConflict: (v: {
     callId?: unknown;

package/dist/tools/contacts.js

@@ -4,6 +4,8 @@ import { strictInput } from "./strict.js";
 /** The contact save revision pin (catalog bounds: integer 0..2147483647). */
 /** Create-from-call rule: the server derives the lead's source ("Inbound Call") and its owner (the rep who took the call), so a
  *  create that carries callId must not carry either field. Refused here, after every field is merged, with the rule named. */
+/** (#361) the API's 400 text for keepPreviousOwnerAsCollaborator sent without a new owner */
+export const KEEP_PREVIOUS_OWNER_NEEDS_ASSIGNEE = "keepPreviousOwnerAsCollaborator needs assignedTo (the new owner) in the same request";
 export const CALL_DERIVED_REFUSAL = "callId cannot be combined with source or assignedTo: for a lead created from a call the server derives both (source is 'Inbound Call', the owner is the rep who took the call). Omit them.";
 export const callDerivedFieldsConflict = (v) => v.callId !== undefined && (v.source !== undefined || v.assignedTo !== undefined);
 /** Identity rules v2 (board #69, app main 61bf61876): what a create answers when the email or phone already belongs to a record. */
@@ -140,7 +142,7 @@ export function registerContactTools(server, client) {
         created.inputSchema = Object.assign(base.superRefine((v, ctx) => { if (callDerivedFieldsConflict(v))
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: CALL_DERIVED_REFUSAL, path: ["callId"] }); }), { shape: base.shape });
     }
-    strictInput(server.tool("conduyt_update_contact", "Update an existing contact's fields — name, email, phone, company, custom fields. customFields merge into existing values (omit a key to leave it unchanged). Pass expectedRevision (the contact's `revision` as you read it) to refuse the save when the contact changed since." + INVALID_NUMBER_REFUSALS + " " + CONTACT_CHANGED + " " + IDENTITY_SAVE_RETRY, {
+    strictInput(server.tool("conduyt_update_contact", "Update an existing contact's fields — name, email, phone, company, owner (assignedTo), custom fields. A reassignment releases the previous owner unless keepPreviousOwnerAsCollaborator is true, which keeps them as a collaborator (read-only access to the lead and its cards). customFields merge into existing values (omit a key to leave it unchanged). Pass expectedRevision (the contact's `revision` as you read it) to refuse the save when the contact changed since." + INVALID_NUMBER_REFUSALS + " " + CONTACT_CHANGED + " " + IDENTITY_SAVE_RETRY, {
         id: z.string().describe("Contact UUID"),
         email: z.string().optional().describe("Updated email"),
         firstName: z.string().optional().describe("Updated first name"),
@@ -148,6 +150,8 @@ export function registerContactTools(server, client) {
         phone: z.string().optional().describe("Updated phone"),
         timezone: z.string().nullable().optional().describe("IANA timezone override (e.g. America/Denver); pass null to clear the override and re-derive from ZIP → area code → state"),
         company: z.string().optional().describe("Updated company name"),
+        assignedTo: z.string().trim().min(1).max(100).nullable().optional().describe("Reassign the lead: the new owner's user ID; null unassigns. The previous owner is released (they lose the lead unless something else explains their access) unless keepPreviousOwnerAsCollaborator is true."),
+        keepPreviousOwnerAsCollaborator: z.boolean().optional().describe("With assignedTo set to another user: keep the previous owner as a collaborator of this contact (read-only access to the lead and its cards) instead of releasing them. Default false. Refused 400 without assignedTo in the same request."),
         source: z.string().trim().min(1).max(100).nullable().optional().describe("Correct the lead's first-touch source (normally first-write-wins and set at creation — update only to FIX bad attribution). Pass null to clear."),
         masterStatus: z.string().trim().min(1).max(40).optional().describe("Lifecycle status of the LEAD (master record), distinct from any deal's status: 'open' (default), 'won', 'lost', 'abandoned', 'disqualified', or an account-defined custom status. A terminal status (won/lost/abandoned/disqualified) SILENCES all outbound automations for this contact — drips, sequences, and scheduled sends stop. Use conduyt_get_lifecycle_settings to see the account's configured statuses."),
         customFields: z.record(z.any()).optional().describe("Structured custom-field values to merge, keyed by field key. Omit a key to leave it unchanged."),
@@ -155,6 +159,10 @@ export function registerContactTools(server, client) {
         expectedRevision: expectedRevision(),
     }, async ({ id, customFields, custom_fields, ...updates }) => {
         const cf = resolveCustomFields(customFields, custom_fields);
+        // (#361) the API's own 400, raised before the request: the flag rides a reassignment to a user only
+        if (updates.keepPreviousOwnerAsCollaborator === true && !(typeof updates.assignedTo === "string" && updates.assignedTo)) {
+            throw new Error(KEEP_PREVIOUS_OWNER_NEEDS_ASSIGNEE);
+        }
         const body = cf !== undefined ? { ...updates, customFields: cf } : updates;
         const result = await client.patch(`/api/v1/contacts/${id}`, body);
         return formatResult(result);

package/dist/tools/deals.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { formatResult } from "../client.js";
 import { strictInput } from "./strict.js";
+import { KEEP_PREVIOUS_OWNER_NEEDS_ASSIGNEE } from "./contacts.js";
 /** The six Pipeline health checks (GET /deals health_check, GET /deals/inspection check). */
 export const PIPELINE_HEALTH_CHECKS = ["high_value_idle", "stale", "unassigned", "needs_action", "missing_close_date", "missing_contact"];
 const healthCheckSchema = z.enum(PIPELINE_HEALTH_CHECKS);
@@ -218,7 +219,7 @@ export function registerDealTools(server, client) {
         const result = await client.post("/api/v1/deals", params);
         return formatResult(result);
     });
-    server.tool("conduyt_update_deal", "Update a deal — move stage, change value/currency, set probability or expected close date, reassign, mark won/lost, or write structured custom-field values. customFields are merged into existing values (omit a key to leave it unchanged). A stage set to \"Entry by automation only\" refuses every entry here: 422 code stage_automation_only, message \"Only an automation can move a deal into <stage>\" (admins and API keys included; moving out is free).", {
+    server.tool("conduyt_update_deal", "Update a deal — move stage, change value/currency, set probability or expected close date, reassign (assignedTo: the previous owner is released unless they own another open card of the lead, or keepPreviousOwnerAsCollaborator is true, which keeps them as a read-only collaborator of the contact; the flag is refused 400 without assignedTo and 400 together with a contact change), mark won/lost, or write structured custom-field values. customFields are merged into existing values (omit a key to leave it unchanged). A stage set to \"Entry by automation only\" refuses every entry here: 422 code stage_automation_only, message \"Only an automation can move a deal into <stage>\" (admins and API keys included; moving out is free).", {
         id: z.string().describe("Deal UUID"),
         title: z.string().optional().describe("Updated title"),
         stageId: z.string().optional().describe("Move to a new stage UUID"),
@@ -231,11 +232,16 @@ export function registerDealTools(server, client) {
         probability: z.number().min(0).max(1).optional().describe("Win probability as a 0–1 fraction (e.g. 0.75 = 75%)"),
         expectedCloseDate: z.string().optional().describe("Expected close date (ISO 8601)"),
         assignedTo: z.string().optional().describe("Reassign to user (owner) UUID"),
+        keepPreviousOwnerAsCollaborator: z.boolean().optional().describe("With assignedTo set to another user: keep the previous owner as a collaborator of the deal's contact (read-only access to the lead and its cards) instead of releasing them. Default false: the previous owner is released unless they own another open card of the lead. Refused 400 without assignedTo in the same request, and 400 together with a contact change (contactId)."),
         source: z.string().trim().min(1).max(500).optional().describe("Attribution source for THIS deal (the trigger that produced it) — distinct from the contact's first-touch source. Every deal keeps a source (#129): it can be changed, never cleared (null/blank are rejected). 1-500 chars."),
         lostReason: z.string().optional().describe("Reason for a lost/disqualified deal. Some stages REQUIRE this on entry (the move fails with code STAGE_REQUIREMENTS listing lostReasonOptions when the stage has a configured dropdown — resend with one of those exact values)."),
         customFields: z.record(z.any()).optional().describe("Structured custom-field values to merge, keyed by field key (send null for a key to clear it; keys you omit keep their current values)"),
         expectedUpdatedAt: z.string().datetime({ message: "expectedUpdatedAt must be the deal's updatedAt exactly as the API returned it (UTC, trailing Z, e.g. 2026-10-06T23:19:00.000Z)" }).optional().describe("Optional: the deal's updatedAt from your last read, ISO 8601 exactly as returned (e.g. 2026-10-06T23:19:00.000Z). If the deal changed since, the update is refused (409, code deal_changed, with the current updatedAt) and nothing is written — read the deal again and retry. Omit for last-write-wins per field."),
     }, async ({ id, ...updates }) => {
+        // (#361) the API's own 400, raised before the request: the flag rides a reassignment to a user only
+        if (updates.keepPreviousOwnerAsCollaborator === true && !(typeof updates.assignedTo === "string" && updates.assignedTo)) {
+            throw new Error(KEEP_PREVIOUS_OWNER_NEEDS_ASSIGNEE);
+        }
         const result = await client.patch(`/api/v1/deals/${id}`, updates);
         return formatResult(result);
     });

package/dist/tools/dialer-settings.d.ts

@@ -28,4 +28,17 @@ export declare const wrapupAutoReleaseSecondsSchema: z.ZodEffects<z.ZodNumber, n
  * follows. Read needs the dialer scope; update needs the settings scope (admin). (#95/#96, 2026-09-16)
  */
 export declare function registerDialerSettingsTools(server: McpServer, client: ConduytClient): void;
+/** HH:MM, 24 hour: the same pattern the settings route validates callingWindow.start / end with */
+export declare const CALLING_TIME: RegExp;
+export declare const CALLING_HOURS_ACK_MESSAGE = "Switching calling hours off requires acknowledgeAnyHour: true (calls at any hour; your team is responsible for calling-time rules)";
+export declare const CALLING_HOURS_ORDER_MESSAGE = "callingWindow.end must be after callingWindow.start";
+/**
+ * The dialer's calling hours (#307; settings.callingWindow, PATCH /api/v1/settings, the Calling hours card). Read through
+ * GET /api/v1/settings, which answers every caller (members too) with `effectiveCallingWindow`, the window the dialer
+ * enforces as one sanitized object. The tools mirror the route's callingWindow schema (strict object; enabled, start and
+ * end required; end after start; switching off needs acknowledgeAnyHour: true) so a bad value fails here with the API's
+ * message; the API stays the authority and its refusals (400 with code calling_hours_acknowledgement_required, 409 stale
+ * settings revision, 403) are surfaced as it sends them.
+ */
+export declare function registerCallingHoursTools(server: McpServer, client: ConduytClient): void;
 export {};

package/dist/tools/dialer-settings.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { formatResult } from "../client.js";
 import { patchGeneralSettings } from "./lifecycle.js";
+import { strictInput } from "./strict.js";
 /** the two lines a workspace records calls on: its Twilio lines (settings.recording) and its iPhone line (settings.projectBlueRecording) */
 const RECORDING_KEY = { twilio: "recording", iphone: "projectBlueRecording" };
 const isOn = (v) => v === "inbound" || v === "outbound" || v === "both";
@@ -105,3 +106,40 @@ export function registerDialerSettingsTools(server, client) {
         return patchGeneralSettings(client, { [RECORDING_KEY[which]]: policy });
     });
 }
+/** HH:MM, 24 hour: the same pattern the settings route validates callingWindow.start / end with */
+export const CALLING_TIME = /^([01]\d|2[0-3]):[0-5]\d$/;
+export const CALLING_HOURS_ACK_MESSAGE = "Switching calling hours off requires acknowledgeAnyHour: true (calls at any hour; your team is responsible for calling-time rules)";
+export const CALLING_HOURS_ORDER_MESSAGE = "callingWindow.end must be after callingWindow.start";
+/**
+ * The dialer's calling hours (#307; settings.callingWindow, PATCH /api/v1/settings, the Calling hours card). Read through
+ * GET /api/v1/settings, which answers every caller (members too) with `effectiveCallingWindow`, the window the dialer
+ * enforces as one sanitized object. The tools mirror the route's callingWindow schema (strict object; enabled, start and
+ * end required; end after start; switching off needs acknowledgeAnyHour: true) so a bad value fails here with the API's
+ * message; the API stays the authority and its refusals (400 with code calling_hours_acknowledgement_required, 409 stale
+ * settings revision, 403) are surfaced as it sends them.
+ */
+export function registerCallingHoursTools(server, client) {
+    server.tool("conduyt_get_calling_hours", "Read the window the dialer enforces for calls (settings.callingWindow, the Calling hours card; any key may read it, settings:view is not needed): effectiveCallingWindow { source ('callingWindow' = saved from the card or the API, a legacy source name = an older saved shape still read, 'default' = never saved, which means 09:00-17:00), enabled (false = the check is off, calls are allowed at any hour), start and end as HH:MM 24 hour, timezone (the IANA zone the hours are judged in, or null = follow the contact's own zone, then the called number's area code, then the account's) }. Calls outside the window are refused with code calling_window. Change it with conduyt_update_calling_hours.", {}, async () => {
+        const result = (await client.get("/api/v1/settings"));
+        return formatResult({ data: { effectiveCallingWindow: result?.data?.effectiveCallingWindow ?? null } });
+    });
+    strictInput(server.tool("conduyt_update_calling_hours", "Set the dialer's calling hours (settings.callingWindow via PATCH /api/v1/settings; admin key, settings:edit). enabled, start and end are always sent together (the API replaces the saved window): start / end are HH:MM 24 hour and end must be after start; timezone is an IANA zone such as America/Chicago the hours are judged in; it is sent trimmed and otherwise as given, and the API recognises it (it also accepts compatibility spellings such as AKST), so an unknown zone comes back as the API's 400. OMITTING timezone keeps the stored zone (the API merges the window); timezone: null clears it, and then the hours follow the contact's zone, then the called number's area code, then the account's. enabled: false switches the calling-hours check OFF (calls at any hour) and then needs acknowledgeAnyHour: true, meaning your team owns the calling-time rules; the acknowledgement is not stored and the change is written to the audit log. Without it the API refuses 400 calling_hours_acknowledgement_required. The first save over an older saved shape (callingHours, dialer.*, voice.*) moves it into callingWindow. Read the current value with conduyt_get_calling_hours first. A stale settings revision is handed back as a conflict with the current settings.", {
+        enabled: z.boolean().describe("false switches the calling-hours check off; it then needs acknowledgeAnyHour: true"),
+        start: z.string().regex(CALLING_TIME, "start must be HH:MM, 24 hour").describe("HH:MM, 24 hour"),
+        end: z.string().regex(CALLING_TIME, "end must be HH:MM, 24 hour").describe("HH:MM, 24 hour; must be after start"),
+        timezone: z.string().nullable().optional().describe("IANA zone the hours are judged in (trimmed, recognised by the API). Omit: the stored zone is kept. null: clears it, so the hours follow the contact's zone, then the number's area code, then the account's."),
+        acknowledgeAnyHour: z.boolean().optional().describe("Required true when enabled is false: the tenant allows calls at any hour and owns the calling-time rules. Not stored; written to the audit log."),
+    }, async ({ enabled, start, end, timezone, acknowledgeAnyHour }) => {
+        const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
+        if (!(start < end))
+            return fail(CALLING_HOURS_ORDER_MESSAGE);
+        if (enabled === false && acknowledgeAnyHour !== true)
+            return fail(CALLING_HOURS_ACK_MESSAGE);
+        const callingWindow = { enabled, start, end };
+        if (timezone !== undefined)
+            callingWindow.timezone = timezone === null ? null : timezone.trim();
+        if (acknowledgeAnyHour !== undefined)
+            callingWindow.acknowledgeAnyHour = acknowledgeAnyHour;
+        return patchGeneralSettings(client, { callingWindow });
+    }));
+}

package/dist/tools/email-opt-out.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConduytClient } from "../client.js";
+/**
+ * The workspace's email opt-out list (#191; app routes /api/v1/email/opt-out-list and /resubscribe). The list is hash-only:
+ * the API never stores or returns an address, a row is { id, source, reason, createdAt }. All three routes are owner / admin
+ * only. The validators below mirror the route's own (bareEmailAddress + EMAIL_SHAPE, 320 characters, reason 1-200, source
+ * "manual" only) so a bad value fails here with the API's message; the API stays the authority and its refusals
+ * (400, 403, 409 with the existing row) are surfaced verbatim and never retried.
+ */
+export declare const EMAIL_OPT_OUT_REASON_MAX = 200;
+export declare const EMAIL_INVALID_MESSAGE = "email must be a valid email address";
+/** the route's check (bareEmailAddress: "Name <a@b.com>" reads as a@b.com, trimmed, lowercased): throws the API's own 400 text.
+ *  The address is sent as given; the API normalizes it the same way. */
+export declare function assertOptOutEmail(raw: string): string;
+export declare function registerEmailOptOutTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/email-opt-out.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { formatResult } from "../client.js";
+import { strictInput } from "./strict.js";
+/**
+ * The workspace's email opt-out list (#191; app routes /api/v1/email/opt-out-list and /resubscribe). The list is hash-only:
+ * the API never stores or returns an address, a row is { id, source, reason, createdAt }. All three routes are owner / admin
+ * only. The validators below mirror the route's own (bareEmailAddress + EMAIL_SHAPE, 320 characters, reason 1-200, source
+ * "manual" only) so a bad value fails here with the API's message; the API stays the authority and its refusals
+ * (400, 403, 409 with the existing row) are surfaced verbatim and never retried.
+ */
+export const EMAIL_OPT_OUT_REASON_MAX = 200;
+const EMAIL_SHAPE = /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/;
+export const EMAIL_INVALID_MESSAGE = "email must be a valid email address";
+/** the route's check (bareEmailAddress: "Name <a@b.com>" reads as a@b.com, trimmed, lowercased): throws the API's own 400 text.
+ *  The address is sent as given; the API normalizes it the same way. */
+export function assertOptOutEmail(raw) {
+    const match = /<([^>]+)>/.exec(raw);
+    const email = (match ? match[1] : raw).trim().toLowerCase();
+    if (!email || email.length > 320 || !EMAIL_SHAPE.test(email))
+        throw new Error(EMAIL_INVALID_MESSAGE);
+    return raw;
+}
+export function registerEmailOptOutTools(server, client) {
+    strictInput(server.tool("conduyt_list_email_opt_outs", "List the workspace's email opt-out list (GET /api/v1/email/opt-out-list; owner / admin key), newest first. The list is hash-only, so no address is returned: each row is { id, source, reason, createdAt } where source says how the address got there ('manual' = added by hand with conduyt_add_email_opt_out; other values are an unsubscribe link, an address-confirmed unsubscribe or a Mailchimp sync) and reason is the note recorded. Paged: page (default 1) and perPage (1-100, default 25); the answer carries meta { page, perPage, total, totalPages }. Every customer-facing email send (campaigns, sequences, one-off, automation, transactional and booking mail) refuses a listed address. 403 for a non-admin key is surfaced verbatim.", {
+        page: z.number().int().min(1).optional().describe("Page number (default 1)"),
+        perPage: z.number().int().min(1).max(100).optional().describe("Rows per page, 1-100 (default 25)"),
+    }, async ({ page, perPage }) => {
+        const params = new URLSearchParams();
+        if (page !== undefined)
+            params.set("page", String(page));
+        if (perPage !== undefined)
+            params.set("perPage", String(perPage));
+        // two literal paths: the coverage gate derives the route from a literal, and an unpaged call carries no "?"
+        return formatResult(params.toString() ? await client.get(`/api/v1/email/opt-out-list?${params}`) : await client.get("/api/v1/email/opt-out-list"));
+    }));
+    strictInput(server.tool("conduyt_add_email_opt_out", "Put an email address on the workspace's opt-out list by hand (POST /api/v1/email/opt-out-list; owner / admin key): the email twin of conduyt_add_dnc, for a vendor or customer 'do not email' request that has no contact. The address is trimmed and lowercased exactly as the readers do, so every customer-facing send refuses it at once (campaigns, sequences, one-off and automation emails, transactional and booking mail); staff and platform mail is not affected. reason is REQUIRED (1-200 characters) and goes into the audit trail with the address hash, never the address itself. Answers: 201 with the new row { id, source: 'manual', reason, createdAt }; 200 with the row when the address was already listed by another source (unsubscribe link, Mailchimp): it is PROMOTED in place to a manual row; 409 with the existing row when it is already listed by hand (nothing written). 400 invalid address, reason missing or over 200 characters, or source other than 'manual'. All refusals are surfaced verbatim and never retried. Take an address off again with conduyt_resubscribe_email_opt_out.", {
+        email: z.string().min(1).describe("The address to block, e.g. person@example.com (trimmed and lowercased by the API, 320 characters at most)"),
+        reason: z.string().trim().min(1, "reason is required").max(EMAIL_OPT_OUT_REASON_MAX, `reason must be ${EMAIL_OPT_OUT_REASON_MAX} characters or fewer`).describe("Why it is listed (1-200 characters), kept in the audit trail"),
+        source: z.literal("manual").optional().describe("Optional; 'manual' is the only accepted value"),
+    }, async ({ email, reason, source }) => {
+        // an undefined source drops out of the JSON body
+        return formatResult(await client.post("/api/v1/email/opt-out-list", { email: assertOptOutEmail(email), reason, source }));
+    }));
+    strictInput(server.tool("conduyt_resubscribe_email_opt_out", "Take an email address off the workspace's opt-out list (POST /api/v1/email/opt-out-list/resubscribe; owner / admin key, audited with the address hash only): the address is sendable again. Use it only when the address's owner has confirmed they want email again. Answers { removed: boolean } (false = the address was not on the list). A contact's OWN email opt-out flag is not touched here: clear that on the contact. 400 invalid address and 403 for a non-admin key are surfaced verbatim and never retried.", {
+        email: z.string().min(1).describe("The address to take off the list"),
+    }, async ({ email }) => formatResult(await client.post("/api/v1/email/opt-out-list/resubscribe", { email: assertOptOutEmail(email) }))));
+}

package/package.json

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

@@ -5,6 +5,11 @@
     "planned": "callable in principle; a typed tool is wanted but not built yet"
   },
   "rules": [
+    {
+      "match": "POST /api/v1/short-links",
+      "status": "planned",
+      "reason": "composer short-links route; the tri-surface rule owes it a real conduyt_* tool, board #466 (MCP/CLI parity for the composer short-links route)"
+    },
     {
       "match": "GET /api/v1/call-flows/functions/:id",
       "status": "planned",

package/scripts/coverage-matrix.json

@@ -1,10 +1,10 @@
 {
-  "generatedAt": "2026-10-23T19:52:32.945Z",
-  "toolCount": 359,
-  "totalEndpoints": 1103,
+  "generatedAt": "2026-10-25T02:48:35.925Z",
+  "toolCount": 364,
+  "totalEndpoints": 1107,
   "counts": {
-    "covered": 317,
-    "excluded": 329,
+    "covered": 320,
+    "excluded": 330,
     "planned": 457,
     "uncategorized": 0
   },
@@ -2766,9 +2766,23 @@
       "status": "planned",
       "reason": "arrived with the app main merge before f132ed6f0, outside the unknown-caller feature; a typed tool is wanted but not built (4.90.0)"
     },
+    "GET /api/v1/email/opt-out-list": {
+      "status": "covered",
+      "tools": [
+        "conduyt_list_email_opt_outs"
+      ]
+    },
+    "POST /api/v1/email/opt-out-list": {
+      "status": "covered",
+      "tools": [
+        "conduyt_add_email_opt_out"
+      ]
+    },
     "POST /api/v1/email/opt-out-list/resubscribe": {
-      "status": "planned",
-      "reason": "bulk email send surfaces"
+      "status": "covered",
+      "tools": [
+        "conduyt_resubscribe_email_opt_out"
+      ]
     },
     "POST /api/v1/email/send": {
       "status": "covered",
@@ -4150,6 +4164,7 @@
         "conduyt_get_contact_table_defaults",
         "conduyt_set_contact_table_defaults",
         "conduyt_get_call_recording_settings",
+        "conduyt_get_calling_hours",
         "conduyt_get_lead_pool_settings",
         "conduyt_update_lead_pool_settings",
         "conduyt_get_lifecycle_settings",
@@ -4407,6 +4422,10 @@
         "conduyt_zoom_test"
       ]
     },
+    "POST /api/v1/short-links": {
+      "status": "planned",
+      "reason": "composer short-links route; the tri-surface rule owes it a real conduyt_* tool, board #466 (MCP/CLI parity for the composer short-links route)"
+    },
     "GET /api/v1/smart-lists": {
       "status": "covered",
       "tools": [
@@ -5018,6 +5037,10 @@
       "status": "excluded",
       "reason": "inbound provider callback receivers (Twilio/Resend/etc.), not client-callable"
     },
+    "POST /api/v1/webhooks/voice/upgrade-join": {
+      "status": "excluded",
+      "reason": "inbound provider callback receivers (Twilio/Resend/etc.), not client-callable"
+    },
     "POST /api/v1/webhooks/voice/vendor-greeting": {
       "status": "excluded",
       "reason": "inbound provider callback receivers (Twilio/Resend/etc.), not client-callable"