conduyt-mcp 4.99.0 → 4.101.0

package/README.md

@@ -14,7 +14,7 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 ### Contacts
 | Tool | Description |
 |------|-------------|
-| `conduyt_list_contacts` | List and search contacts with filters |
+| `conduyt_list_contacts` | List and search contacts with filters (search, exact `email`, `tag` names, `tagId` uuids: ANY-of, repeatable up to 20, `meta.total` counts the filtered set) |
 | `conduyt_get_contact` | Get full contact details with timeline; `hasOutboundSms` = the workspace has ever provably texted the contact; `hasOutboundEmail` = the same for email; `duplicateProposals` and `heldIdentifiers` = the open possible-duplicate lines and held identifiers |
 | `conduyt_create_contact` | Create a new contact (a 409 with `existingId`, `rule`, `ruleVersion`, `matchedOn`, `reason` means the identity policy identified the incoming person with that record: confirm the identity (name, company) before updating it, a shared phone or email is not proof, and the server creates (with a passive duplicate proposal) a different person on a shared identifier; 409 `identifier_changed` / `owner_busy` and 503 `IDENTITY_INDEX_NOT_READY` are retryable, nothing written; with `callId`: the lead for a contact-less inbound call, linked in the same transaction; the server derives source "Inbound Call" and the owner) |
 | `conduyt_update_contact` | Update contact fields (incl. `assignedTo`; `keepPreviousOwnerAsCollaborator: true` with a reassignment keeps the previous owner as a read-only collaborator instead of releasing them, 400 without `assignedTo`); optional `expectedRevision` (0..2147483647) refuses a stale save with 409 `contact_changed` (code + current revision in the error) |
@@ -36,6 +36,7 @@ MCP server for [Conduyt CRM](https://conduyt.app) — expose your CRM as AI-acce
 | `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_my_profile` | Read the caller's own identity (`GET /users/me`, same as `/auth/me`): `data.user` incl. `ringtone` (the incoming-ring slug, null = Conduyt Default), `data.account`, role, permissions, `apiKey`, `accounts`. Editing the profile is a signed-in person's action and is not exposed to API keys |
 | `conduyt_create_short_link` | Make (or reuse) the workspace's Conduyt short link for a public link-shortener address the Message check flagged (`POST /short-links`, body `{ url }`; key needs the `messages` scope, member needs communications.create). Not shortenable: our own host, merge fields, `mailto:`/`tel:`/`sms:`, or any address the Message check does not flag as a link shortener (400 `not_shortenable`). Other errors verbatim, never retried: 400 `invalid_body`, 403 `forbidden`, 413 `body_too_large`, 429 `rate_limited` (with Retry-After), 503 `short_link_unavailable` (nothing changed) |
 | `conduyt_get_deal_card_fields` / `conduyt_set_deal_card_fields` | Read / replace the kanban card fields (1-8, built-ins or `custom:<fieldKey>`) |
 | `conduyt_get_settings_revision` | The account `settingsRevision` (plus stored stage rules and rot days): pass it as `expectedSettingsRevision` to `conduyt_archive_pipeline` / `conduyt_delete_stage` so a stale one is refused 409 `stale_settings_revision` |

package/dist/register-all.js

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

package/dist/tool-annotations.js

@@ -221,6 +221,7 @@ export const TOOL_ANNOTATIONS = {
     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_get_my_profile: ro("Get My Profile"),
     conduyt_create_short_link: update("Create Short Link"), // one link per account and target: a repeat returns the same link (idempotent), nothing existing is changed
     conduyt_list_saved_filters: ro("List Saved Filters"),
     conduyt_create_saved_filter: create("Create Saved Filter"),

package/dist/tools/contacts.d.ts

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

package/dist/tools/contacts.js

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

package/dist/tools/my-profile.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConduytClient } from "../client.js";
+/**
+ * The caller's own profile read (app route GET /api/v1/users/me, the same handler as GET /auth/me). data.user carries the
+ * incoming-ring slug (#385) as `ringtone`. PATCH /users/me is deliberately not a tool: it is a signed-in person's action
+ * (profile, ringtone, password) and the API refuses an API key, so a tool for it would only ever return 403.
+ */
+export declare function registerMyProfileTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/my-profile.js

@@ -0,0 +1,10 @@
+import { formatResult } from "../client.js";
+import { strictInput } from "./strict.js";
+/**
+ * The caller's own profile read (app route GET /api/v1/users/me, the same handler as GET /auth/me). data.user carries the
+ * incoming-ring slug (#385) as `ringtone`. PATCH /users/me is deliberately not a tool: it is a signed-in person's action
+ * (profile, ringtone, password) and the API refuses an API key, so a tool for it would only ever return 403.
+ */
+export function registerMyProfileTools(server, client) {
+    strictInput(server.tool("conduyt_get_my_profile", "Read the caller's own identity (GET /api/v1/users/me, identical to GET /auth/me): data.user (id, email, firstName, lastName, avatarUrl, phone, birthdayMonth, birthdayDay, tourSeenAt, and ringtone: the slug of the incoming ring this person hears, or null = Conduyt Default; the slug is one of classic, soft-bell, marimba, digital-pulse, rising-chime, office-trill, double-ring, pocket-melody, retro-cell, kalimba, uplift), data.account (the current account, name at data.account.name), role, permissions, leadVisibilityMode, apiKey (the key's own metadata when called with an API key, else null) and accounts. Any authenticated caller, including a scoped key, may read it. Editing the profile (name, phone, birthday, ringtone, password) is a signed-in person's action in the app and is not available to an API key.", {}, async () => formatResult(await client.get("/api/v1/users/me"))));
+}

package/dist/tools/short-links.js

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

package/package.json

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

@@ -200,6 +200,11 @@
       "status": "planned",
       "reason": "company subroutes beyond core CRUD"
     },
+    {
+      "match": "PATCH /api/v1/users/me",
+      "status": "excluded",
+      "reason": "a signed-in person's own profile edit (name, phone, birthday, ringtone, password): session only (assertSessionOnly), never an API key's; GET /users/me is covered by conduyt_get_my_profile"
+    },
     {
       "match": "/api/v1/users",
       "status": "planned",

package/scripts/coverage-matrix.json

@@ -1,11 +1,11 @@
 {
-  "generatedAt": "2026-10-25T02:48:35.925Z",
-  "toolCount": 365,
-  "totalEndpoints": 1107,
+  "generatedAt": "2026-10-27T01:28:17.262Z",
+  "toolCount": 366,
+  "totalEndpoints": 1108,
   "counts": {
-    "covered": 321,
-    "excluded": 330,
-    "planned": 456,
+    "covered": 322,
+    "excluded": 332,
+    "planned": 454,
     "uncategorized": 0
   },
   "matrix": {
@@ -593,6 +593,10 @@
       "status": "excluded",
       "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
     },
+    "POST /api/v1/auth/signup-events": {
+      "status": "excluded",
+      "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
+    },
     "POST /api/v1/auth/switch-account": {
       "status": "excluded",
       "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
@@ -4854,12 +4858,14 @@
       ]
     },
     "GET /api/v1/users/me": {
-      "status": "planned",
-      "reason": "team management subroutes beyond list/invite"
+      "status": "covered",
+      "tools": [
+        "conduyt_get_my_profile"
+      ]
     },
     "PATCH /api/v1/users/me": {
-      "status": "planned",
-      "reason": "team management subroutes beyond list/invite"
+      "status": "excluded",
+      "reason": "a signed-in person's own profile edit (name, phone, birthday, ringtone, password): session only (assertSessionOnly), never an API key's; GET /users/me is covered by conduyt_get_my_profile"
     },
     "GET /api/v1/users/me/tour": {
       "status": "planned",