conduyt-mcp 4.90.0 → 4.91.0

package/README.md

@@ -15,10 +15,12 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 | Tool | Description |
 |------|-------------|
 | `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 |
-| `conduyt_create_contact` | Create a new contact (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_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_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 |
+| `conduyt_decide_duplicate_proposal` | Decide one proposal (`POST /contacts/{id}/duplicate-proposals/{proposalId}`, contacts:edit on both records): `not_sure` keeps both visible, `different` is final (never shown again), `merge` records a pair ALREADY merged (this tool never merges: use `conduyt_merge_contacts` first, else 409 `not_merged`); 409 `already_decided`, 403 `other_record_not_editable`; never retried |
 | `conduyt_add_contact_collaborator` | Add a team member as a collaborator (`POST /contacts/{id}/collaborators`); optional `expectedRevision`, 409 `contact_changed` |
 | `conduyt_remove_contact_collaborator` | Remove a collaborator (`DELETE /contacts/{id}/collaborators`, body); optional `expectedRevision`, 409 `contact_changed`, 404 when not a collaborator |
 | `conduyt_add_tags` | Add tags to a contact |

package/dist/tools/bulk.js

@@ -4,7 +4,7 @@ import { INVALID_NUMBER_REFUSALS } from "./contacts.js";
 /** (#136, Codex r1 m2) POST /bulk/contacts/update is NOT atomic and answers per row: an impossible phone is a per-row success:false inside HTTP 200 (no code) while other rows commit; the route takes no country */
 export const BULK_UPDATE_REFUSALS = " Results are PER ROW inside an HTTP 200 (not atomic: some rows can be saved while others fail): read data.summary { total, succeeded, failed } and data.results, each { id, success, error? }. An impossible US/Canada number (area code or exchange starting 0 or 1) fails only that row, success: false with the error text (no phone_invalid code, no top-level 400), and nothing is saved for that row. This route does not take country: a country-only row fails as a row, and a country sent beside another field is ignored while that field is applied (use conduyt_bulk_edit_contacts for a country; it refuses a null or blank country 400 country_invalid).";
 export function registerBulkTools(server, client) {
-    server.tool("conduyt_ai_import_contacts", "AI-powered bulk contact import. Accepts up to 1000 contacts with optional auto-tagging, smart list creation, and automation enrollment. Deduplicates by email, phone, or both.", {
+    server.tool("conduyt_ai_import_contacts", "AI-powered bulk contact import. Accepts up to 1000 contacts with optional auto-tagging, smart list creation, and automation enrollment. Deduplicates by email, phone, or both. A workspace whose identifier index is still being built answers 503 `IDENTITY_INDEX_NOT_READY` (nothing imported; retry later).", {
         contacts: z.array(z.object({
             firstName: z.string().optional(),
             lastName: z.string().optional(),
@@ -152,7 +152,7 @@ export function registerBulkTools(server, client) {
         const result = await client.post("/api/v1/bulk/deals/update", params);
         return formatResult(result);
     });
-    server.tool("conduyt_import_preflight", "Pre-check a contact import BEFORE running it — returns criticalWarnings (phone-less list bound for SMS, heavy create-only duplicate skips, double-mapped columns), duplicate/existing-match estimates, invalid emails, DNC/litigator hits, SMS-provider readiness, and plan-limit impact. Same engine the import wizard uses; call this before conduyt_ai_import_contacts on any sizeable list.", {
+    server.tool("conduyt_import_preflight", "Pre-check a contact import BEFORE running it — returns criticalWarnings (phone-less list bound for SMS, heavy create-only duplicate skips, double-mapped columns), duplicate/existing-match estimates, invalid emails, DNC/litigator hits, SMS-provider readiness, and plan-limit impact. Same engine the import wizard uses; call this before conduyt_ai_import_contacts on any sizeable list. A workspace whose identifier index is still being built answers 503 `IDENTITY_INDEX_NOT_READY` (nothing checked; retry later).", {
         objectType: z.enum(["contacts", "opportunities", "companies"]).default("contacts").describe("What the import creates"),
         importMode: z.enum(["create_and_update", "create_only", "update_only"]).optional().describe("Duplicate handling mode the import will use"),
         totalRows: z.number().describe("Total rows in the file/payload"),
@@ -160,6 +160,8 @@ export function registerBulkTools(server, client) {
         phones: z.array(z.string()).optional().describe("All phone values from the file (order-free)"),
         mappedFields: z.array(z.string()).optional().describe("The Conduyt field names your columns map to, e.g. ['firstName','phone']"),
         removeDuplicates: z.boolean().optional().describe("Whether explicit dedupe is on"),
+        ambiguousMatchMode: z.enum(["proposal", "hold", "create_new"]).nullish().describe("What the import does with a row whose email matches one record and phone another (identity v2): 'proposal' (the platform default: the row is created and carries a duplicate proposal naming the similar records) or 'hold' (held for review). 'create_new' is RETIRED for new imports (the server answers 400); it is accepted here only so a preview of an old job still validates."),
+        enrollAdditionalCampaign: z.boolean().optional().describe("true = the import's Add mode: a contested email or phone slot value is stripped and the row is still created (estimated the way the import will run it); every other mode skips such a row as secondary_identifier_conflict"),
         duplicateCheckFields: z.array(z.enum(["email", "phone"])).optional().describe("Identifiers explicit dedupe checks"),
         rowIdentifiers: z.array(z.object({
             email: z.string().nullable().optional(),

package/dist/tools/contacts.js

@@ -6,6 +6,11 @@ import { strictInput } from "./strict.js";
  *  create that carries callId must not carry either field. Refused here, after every field is merged, with the rule named. */
 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. */
+const IDENTITY_409_MEANING = "A 409 with { existingId, rule, ruleVersion, matchedOn, reason } means the server's identity policy identified the incoming person WITH the record existingId (rule and matchedOn say how). It is not proof by itself: the policy deliberately allows two different people on one shared identifier when their full names conflict (rule R6; shared phone lines exist), and that case is NOT refused: the server creates the record and shows a passive duplicate proposal (conduyt_list_duplicate_proposals). The server itself refuses creates it identifies as the same person, so never create a copy. Before you update existingId, CONFIRM the identity (name, company); never treat a shared phone or email as proof that it is the same person.";
+const IDENTITY_CREATE_ANSWERS = "Identity rules (v2): " + IDENTITY_409_MEANING + " 409 with code `identifier_changed` or `owner_busy` = another save for the same email, phone or owner was in progress, nothing was written: wait a moment and send the same request again (retryable). 503 with code `IDENTITY_INDEX_NOT_READY` = the workspace's identifier index is still being built at this size, nothing was written: retry later. A possible duplicate that is not an exact match is created and shown as a duplicate proposal on the record (conduyt_list_duplicate_proposals).";
+const IDENTITY_SAVE_RETRY = "Identity rules (v2): " + IDENTITY_409_MEANING + " 409 with code `identifier_changed` = another save for this email or phone was in progress (or the record's email or phone changed while this saved), nothing was written: reload the contact and send the change again (retryable). 409 with code `owner_busy` = another save for the same owner was in progress, nothing was written: wait a moment and send the same request again (retryable). 503 with code `IDENTITY_INDEX_NOT_READY` = the workspace's identifier index is still being built at this size, nothing was written: retry later.";
+const PROPOSAL_DECISIONS = ["not_sure", "different", "merge"];
 export const CONTACT_REVISION_MAX = 2147483647;
 const CONTACT_CHANGED = "A stale pin is refused with 409 and code contact_changed (nothing written): the error text carries `code`, the contact's CURRENT `revision` and the current `contact`; reload, decide, and call again with that revision (never retry the same pin). A malformed expectedRevision is a 400; only an omitted field means unpinned.";
 const expectedRevision = () => z.number().int().min(0).max(CONTACT_REVISION_MAX).optional().describe("Optimistic-concurrency pin: the contact `revision` as you last read it (conduyt_get_contact / conduyt_list_contacts / a previous change). Omit for last-write-wins per field.");
@@ -95,13 +100,13 @@ export function registerContactTools(server, client) {
         const result = await client.get(`/api/v1/contacts?${params}`);
         return formatResult(result);
     });
-    server.tool("conduyt_get_contact", "Get a single contact with full details — profile, tags, custom fields, timeline, deals, and activity history. Includes `revision` (integer save revision): pass it as expectedRevision on conduyt_update_contact or the collaborator tools so a newer change is never overwritten. Includes `hasOutboundSms` (boolean): true when this workspace has ever PROVABLY texted the contact (a proven send only: not a draft, a queued row or a pre-send failure); use it to pick the `context` for conduyt_check_message (false = 'first', true = 'conversation'). Also includes `hasOutboundEmail` (boolean): the same for email (true when at least one outbound email to the contact was proven sent, so a genuine \"Re:\" reply is a conversation and not flagged); use it to pick the `context` for an email check.", {
+    server.tool("conduyt_get_contact", "Get a single contact with full details — profile, tags, custom fields, timeline, deals, and activity history. Includes `revision` (integer save revision): pass it as expectedRevision on conduyt_update_contact or the collaborator tools so a newer change is never overwritten. Includes `hasOutboundSms` (boolean): true when this workspace has ever PROVABLY texted the contact (a proven send only: not a draft, a queued row or a pre-send failure); use it to pick the `context` for conduyt_check_message (false = 'first', true = 'conversation'). Also includes `hasOutboundEmail` (boolean): the same for email (true when at least one outbound email to the contact was proven sent, so a genuine \"Re:\" reply is a conversation and not flagged); use it to pick the `context` for an email check. Also includes `duplicateProposals` (the open and not-sure possible-duplicate lines on this record, each naming the other record as far as your key may see it) and `heldIdentifiers` (emails or phones held from this record because another record owns them, value-free); list or decide them with conduyt_list_duplicate_proposals / conduyt_decide_duplicate_proposal.", {
         id: z.string().describe("Contact UUID"),
     }, async ({ id }) => {
         const result = await client.get(`/api/v1/contacts/${id}`);
         return formatResult(result);
     });
-    const createContactTool = server.tool("conduyt_create_contact", "Create a new contact in the CRM. Email or phone is recommended but not strictly required. With callId (a lead made from a contact-less inbound call) you must NOT send source or assignedTo: the server derives both from the call, and the request is refused if either is present." + INVALID_NUMBER_REFUSALS, {
+    const createContactTool = server.tool("conduyt_create_contact", "Create a new contact in the CRM. Email or phone is recommended but not strictly required. With callId (a lead made from a contact-less inbound call) you must NOT send source or assignedTo: the server derives both from the call, and the request is refused if either is present." + INVALID_NUMBER_REFUSALS + " " + IDENTITY_CREATE_ANSWERS, {
         email: z.string().optional().describe("Contact email address"),
         firstName: z.string().optional().describe("First name"),
         lastName: z.string().optional().describe("Last name"),
@@ -131,7 +136,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, {
+    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, {
         id: z.string().describe("Contact UUID"),
         email: z.string().optional().describe("Updated email"),
         firstName: z.string().optional().describe("Updated first name"),
@@ -235,4 +240,18 @@ export function registerContactTools(server, client) {
         mergePreviews.drop(key);
         return formatResult(result);
     }));
+    strictInput(server.tool("conduyt_list_duplicate_proposals", "List the possible duplicates of one contact (GET /api/v1/contacts/{contactId}/duplicate-proposals, identity rules v2; requires contacts:view). Answers { data: { proposals, heldIdentifiers } }. Each proposal: { id (the proposalId for conduyt_decide_duplicate_proposal), status ('open' or 'not_sure': the only two shown), rule, ruleVersion, source, createdAt, decidedAt, raisedHere (true = this record is the newer arrival the proposal was raised on), other: { id, name, createdAt, visible, editable } }. When your key cannot view the other record it is described only as 'a contact you cannot view' with id and createdAt null and visible false: you cannot decide that pair. heldIdentifiers (up to 20) are the emails or phones this record was NOT given because another record owns them (rule 4), value-free: { id, kind ('email' or 'phone'), rule, source, createdAt, heldBy: [{ id, name, visible }] }. Read-only, nothing is changed. 404 = no such contact for you. conduyt_get_contact carries the same two lists.", {
+        contactId: z.string().uuid().describe("Contact UUID whose possible duplicates to list"),
+    }, async ({ contactId }) => {
+        const result = await client.get(`/api/v1/contacts/${encodeURIComponent(contactId)}/duplicate-proposals`);
+        return formatResult(result);
+    }));
+    strictInput(server.tool("conduyt_decide_duplicate_proposal", "Record a decision on one possible-duplicate pair shown on a contact (POST /api/v1/contacts/{contactId}/duplicate-proposals/{proposalId} with { decision }; requires contacts:edit on BOTH records of the pair). Get proposalId from conduyt_list_duplicate_proposals. decision, exactly one of: 'not_sure' = keep both records visible, the pair stays listed and who looked is recorded (it can be decided again later); 'different' = the two records are different people, the pair is never shown again and the decision is FINAL; 'merge' = record that the pair is ALREADY merged: this tool NEVER merges. Merge first with conduyt_merge_contacts (preview, then confirm), then send 'merge' here; before the merge exists it is refused with 409 code `not_merged`. A pair already decided 'different' or merged is final: 409 code `already_decided` (also when someone decided it just now). Other refusals, nothing written: 404 (no such proposal on this contact: for EVERY decision; or the other record is gone: for 'not_sure' and 'different' only, while 'merge' still succeeds after the other record has been merged away), 403 code `other_record_not_editable` (you cannot edit the other record), 403 (you can view this contact but not edit it), 400 (decision missing or not one of the three), 402 billing. Answers { data: { id, status, decidedAt } } with status 'not_sure', 'different' or 'merged'. Never retried automatically.", {
+        contactId: z.string().uuid().describe("Contact UUID the proposal is shown on"),
+        proposalId: z.string().uuid().describe("The proposal id from conduyt_list_duplicate_proposals"),
+        decision: z.enum(PROPOSAL_DECISIONS).describe("'not_sure' keeps both visible; 'different' = different people, never shown again (final); 'merge' = the pair is already merged elsewhere (run conduyt_merge_contacts first; this tool never merges)"),
+    }, async ({ contactId, proposalId, decision }) => {
+        const result = await client.post(`/api/v1/contacts/${encodeURIComponent(contactId)}/duplicate-proposals/${encodeURIComponent(proposalId)}`, { decision });
+        return formatResult(result);
+    }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt-mcp",
-  "version": "4.90.0",
+  "version": "4.91.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,9 +1,9 @@
 {
-  "generatedAt": "2026-10-16T01:23:28.000Z",
-  "toolCount": 352,
-  "totalEndpoints": 1090,
+  "generatedAt": "2026-10-16T01:48:16.550Z",
+  "toolCount": 354,
+  "totalEndpoints": 1092,
   "counts": {
-    "covered": 311,
+    "covered": 313,
     "excluded": 324,
     "planned": 455,
     "uncategorized": 0
@@ -1495,6 +1495,18 @@
       "status": "planned",
       "reason": "contact subroutes beyond the core CRUD/search tools"
     },
+    "GET /api/v1/contacts/:id/duplicate-proposals": {
+      "status": "covered",
+      "tools": [
+        "conduyt_list_duplicate_proposals"
+      ]
+    },
+    "POST /api/v1/contacts/:id/duplicate-proposals/:proposalId": {
+      "status": "covered",
+      "tools": [
+        "conduyt_decide_duplicate_proposal"
+      ]
+    },
     "POST /api/v1/contacts/:id/enrich": {
       "status": "planned",
       "reason": "contact subroutes beyond the core CRUD/search tools"