conduyt-mcp 4.62.0 → 4.63.0

package/dist/index.js

@@ -40,6 +40,7 @@ import { registerPrivacyTools } from "./tools/privacy.js";
 import { registerSmartViewTools } from "./tools/smart-views.js";
 import { registerAccountExportTools } from "./tools/account-exports.js";
 import { registerLifecycleTools } from "./tools/lifecycle.js";
+import { registerLeadPoolTools } from "./tools/lead-pool.js";
 import { registerReplyCaptureTools } from "./tools/reply-capture.js";
 import { registerCallFlowTools } from "./tools/call-flows.js";
 import { registerProjectBlueTools } from "./tools/project-blue.js";
@@ -111,6 +112,7 @@ registerPrivacyTools(server, client);
 registerSmartViewTools(server, client);
 registerAccountExportTools(server, client);
 registerLifecycleTools(server, client);
+registerLeadPoolTools(server, client);
 registerReplyCaptureTools(server, client);
 registerCallFlowTools(server, client);
 registerProjectBlueTools(server, client);

package/dist/tools/lead-pool.d.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConduytClient } from "../client.js";
+/**
+ * (#120, 2026-09-18) the admin-curated lead pool behind Up for Grabs / Lead Pool: settings.poolFilter. When enabled,
+ * an unassigned lead is offered only if it matches EVERY configured criterion (tag any-of, source any-of, lead score
+ * >= minScore, lead score <= maxScore, ADDED to the CRM within the past createdWithinDays days — the contact's creation time, so a re-import into an existing contact is not new); an empty criterion is
+ * skipped; enabled with nothing configured reads as disabled. Claims are gated by the same rules. Tri-surface parity
+ * with Settings → Lead routing → Lead Pool and the CLI `lead-pool` commands.
+ */
+export interface PoolFilterShape {
+    enabled: boolean;
+    tagIds: string[];
+    sources: string[];
+    minScore: number | null;
+    maxScore: number | null;
+    createdWithinDays: number | null;
+}
+/** the stored filter as the API's zod shape (unknown / legacy keys tolerated) */
+export declare function poolFilterOf(settings: Record<string, unknown>): PoolFilterShape;
+export type TagRef = {
+    id: string;
+    name: string | null;
+};
+/** the same plain-English criteria the Up for Grabs page prints under its header (lib/pool-filter-summary.ts in the app):
+ *  a deleted tag (name null) stays visible because its id still filters every lead out; a failed lookup is said so */
+export declare function poolCriteriaPhrases(filter: PoolFilterShape, tags: TagRef[], tagLookupFailed?: boolean): string[];
+export declare function registerLeadPoolTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/lead-pool.js

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { formatResult } from "../client.js";
+import { patchGeneralSettings } from "./lifecycle.js";
+const EMPTY = { enabled: false, tagIds: [], sources: [], minScore: null, maxScore: null, createdWithinDays: null };
+function intOrNull(v) {
+    return typeof v === "number" && Number.isInteger(v) ? v : null;
+}
+/** the stored filter as the API's zod shape (unknown / legacy keys tolerated) */
+export function poolFilterOf(settings) {
+    const raw = settings.poolFilter;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return { ...EMPTY };
+    const r = raw;
+    const minScore = intOrNull(r.minScore);
+    return {
+        enabled: r.enabled === true,
+        tagIds: Array.isArray(r.tagIds) ? r.tagIds.filter((t) => typeof t === "string") : [],
+        sources: Array.isArray(r.sources) ? r.sources.filter((s) => typeof s === "string") : [],
+        minScore: minScore !== null && minScore > 0 ? minScore : null,
+        maxScore: intOrNull(r.maxScore),
+        createdWithinDays: intOrNull(r.createdWithinDays),
+    };
+}
+const list = (items) => items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} or ${items[items.length - 1]}`;
+/** the same plain-English criteria the Up for Grabs page prints under its header (lib/pool-filter-summary.ts in the app):
+ *  a deleted tag (name null) stays visible because its id still filters every lead out; a failed lookup is said so */
+export function poolCriteriaPhrases(filter, tags, tagLookupFailed = false) {
+    if (!filter.enabled)
+        return [];
+    const out = [];
+    if (filter.sources.length > 0)
+        out.push(`from ${list(filter.sources)}`);
+    if (filter.createdWithinDays !== null)
+        out.push(filter.createdWithinDays === 1 ? "added in the past day" : `added in the past ${filter.createdWithinDays} days`);
+    if (tags.length > 0) {
+        if (tagLookupFailed) {
+            out.push(`tagged one of ${tags.length} ${tags.length === 1 ? "tag" : "tags"} (names unavailable right now)`);
+        }
+        else {
+            const names = tags.filter((t) => t.name !== null).map((t) => t.name);
+            const deleted = tags.length - names.length;
+            if (deleted > 0)
+                names.push(deleted === 1 ? "a deleted tag (matches nothing)" : `${deleted} deleted tags (match nothing)`);
+            out.push(`tagged ${list(names)}`);
+        }
+    }
+    if (filter.minScore !== null && filter.maxScore !== null)
+        out.push(filter.minScore === filter.maxScore ? `lead score ${filter.minScore}` : `lead score ${filter.minScore} to ${filter.maxScore}`);
+    else if (filter.minScore !== null)
+        out.push(`lead score ${filter.minScore} or higher`);
+    else if (filter.maxScore !== null)
+        out.push(`lead score ${filter.maxScore} or lower`);
+    return out;
+}
+/** every configured id, resolved to a name where the tag still exists; the lookup is display-only and never throws */
+async function tagNamesFor(client, tagIds) {
+    if (tagIds.length === 0)
+        return { tags: [], tagLookupFailed: false };
+    try {
+        const result = (await client.get("/api/v1/tags?per_page=200"));
+        const rows = Array.isArray(result) ? result : Array.isArray(result.data) ? (result.data) : [];
+        const byId = new Map(rows.filter((t) => !!t && typeof t === "object" && typeof t.id === "string").map((t) => [t.id, t.name]));
+        return { tags: tagIds.map((id) => ({ id, name: byId.get(id) ?? null })), tagLookupFailed: false };
+    }
+    catch {
+        return { tags: tagIds.map((id) => ({ id, name: null })), tagLookupFailed: true };
+    }
+}
+const score = z.number().int().min(0).max(1000);
+export function registerLeadPoolTools(server, client) {
+    server.tool("conduyt_get_lead_pool_settings", "Read the admin-curated lead pool behind Up for Grabs / Lead Pool (settings.poolFilter + poolClaimDailyLimit). When enabled, an unassigned lead is offered only if it matches EVERY configured criterion: tagIds (any of), sources (any of), minScore (lead score >=), maxScore (lead score <=; min = max keeps one exact score), createdWithinDays (added to the CRM in the past N days: the contact's creation time — import, webhook, form, API or by hand; a re-import into an existing contact does not make it new). An empty criterion is skipped; enabled with nothing configured reads as disabled. Claims are gated by the same rules. tags carries the resolved tag names; criteria is the plain-English line the Up for Grabs page shows. Requires the settings scope.", {}, async () => {
+        const result = (await client.get("/api/v1/settings"));
+        const raw = result?.data ?? {};
+        const filter = poolFilterOf(raw);
+        const { tags, tagLookupFailed } = await tagNamesFor(client, filter.tagIds);
+        const poolClaimDailyLimit = intOrNull(raw.poolClaimDailyLimit);
+        return formatResult({ data: { ...filter, tags, ...(tagLookupFailed ? { tagLookupFailed } : {}), criteria: poolCriteriaPhrases(filter, tags, tagLookupFailed), poolClaimDailyLimit } });
+    });
+    server.tool("conduyt_update_lead_pool_settings", "Change the admin-curated lead pool (Up for Grabs / Lead Pool). Pass only what changes; every other criterion keeps its stored value. Criteria are ANDed: enabled, tagIds (contact has ANY of these tags; [] = no tag rule), sources (lead source is ANY of these; [] = no source rule), minScore / maxScore (lead score floor / ceiling, 0..1000, null = none; the same value for both keeps one exact score, e.g. \"lead quality 4\"), createdWithinDays (only leads ADDED to the CRM in the past N days — creation time, a re-import of an existing contact is not new; 1..365, null = none), poolClaimDailyLimit (0..200 grabs per agent per day, 0 = no cap). Enabling with no criterion at all is refused (it would read as disabled). maxScore below minScore is refused. Sends the settings revision it read; a 409 (another save landed first) returns the current settings to re-derive from. Requires settings:edit.", {
+        enabled: z.boolean().optional().describe("Turn the curated pool on or off"),
+        tagIds: z.array(z.string().uuid()).max(50).optional().describe("Tag UUIDs the lead must carry one of (conduyt_list_tags); [] clears the tag rule"),
+        sources: z.array(z.string().trim().min(1).max(100)).max(50).optional().describe("Lead sources, exact match, any of; [] clears the source rule"),
+        minScore: score.nullable().optional().describe("Lead score floor (>=); null clears"),
+        maxScore: score.nullable().optional().describe("Lead score ceiling (<=); null clears; equal to minScore = one exact score"),
+        createdWithinDays: z.number().int().min(1).max(365).nullable().optional().describe("Only leads added to the CRM (created) in the past N days; null clears"),
+        poolClaimDailyLimit: z.number().int().min(0).max(200).optional().describe("Daily self-serve claim cap per agent; 0 = off"),
+    }, async (params) => {
+        const current = (await client.get("/api/v1/settings"));
+        const stored = poolFilterOf(current?.data ?? {});
+        const next = {
+            enabled: params.enabled ?? stored.enabled,
+            tagIds: params.tagIds ?? stored.tagIds,
+            sources: params.sources ?? stored.sources,
+            minScore: params.minScore === undefined ? stored.minScore : params.minScore,
+            maxScore: params.maxScore === undefined ? stored.maxScore : params.maxScore,
+            createdWithinDays: params.createdWithinDays === undefined ? stored.createdWithinDays : params.createdWithinDays,
+        };
+        if (next.minScore !== null && next.maxScore !== null && next.maxScore < next.minScore) {
+            throw new Error(`maxScore (${next.maxScore}) must be at least minScore (${next.minScore})`);
+        }
+        const hasCriterion = next.tagIds.length > 0 || next.sources.length > 0 || next.minScore !== null || next.maxScore !== null || next.createdWithinDays !== null;
+        if (next.enabled && !hasCriterion) {
+            throw new Error("enabled with no criterion would read as disabled — pass at least one of tagIds, sources, minScore, maxScore, createdWithinDays, or set enabled=false");
+        }
+        const body = { poolFilter: next };
+        if (params.poolClaimDailyLimit !== undefined)
+            body.poolClaimDailyLimit = params.poolClaimDailyLimit;
+        return patchGeneralSettings(client, body);
+    });
+    server.tool("conduyt_list_up_for_grabs", "The Up for Grabs queue as the rep-facing page shows it: open claim offers plus the implicit pool of unassigned leads the account's curated pool filter admits (highest lead score first, up to 200), each with a teaser (name, company, source, score, city/state; phone and email only for admin keys) and eligibleCount. poolFilter is the active curation (tags resolved to names) and criteria the plain-English line under the page header — empty when curation is off. Claim with POST /api/v1/up-for-grabs/{contactId}/claim. Requires the up-for-grabs scope on the key.", {}, async () => {
+        const result = (await client.get("/api/v1/up-for-grabs"));
+        const data = result?.data ?? {};
+        const pf = data.poolFilter && typeof data.poolFilter === "object" ? data.poolFilter : null;
+        const filter = pf
+            ? { enabled: pf.enabled === true, tagIds: (pf.tags ?? []).map((t) => t.id), sources: pf.sources ?? [], minScore: pf.minScore ?? null, maxScore: pf.maxScore ?? null, createdWithinDays: pf.createdWithinDays ?? null }
+            : { ...EMPTY };
+        const offers = Array.isArray(data.offers) ? data.offers : [];
+        return formatResult({ data: { offers, count: offers.length, poolFilter: pf, criteria: poolCriteriaPhrases(filter, pf?.tags ?? [], pf?.tagLookupFailed === true) } });
+    });
+}

package/dist/tools/lifecycle.d.ts

@@ -1,3 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ConduytClient } from "../client.js";
+/** (default columns r18, Codex r17 h1) every general-settings PATCH names the revision it loaded: read it, save, and on a 409 hand
+ *  the conflict back with the current settings so the caller re-derives its change (tri-surface parity with the browser) */
+export declare function patchGeneralSettings(client: ConduytClient, body: Record<string, unknown>): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
 export declare function registerLifecycleTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/lifecycle.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { ConduytApiError, formatResult } from "../client.js";
 /** (default columns r18, Codex r17 h1) every general-settings PATCH names the revision it loaded: read it, save, and on a 409 hand
  *  the conflict back with the current settings so the caller re-derives its change (tri-surface parity with the browser) */
-async function patchGeneralSettings(client, body) {
+export async function patchGeneralSettings(client, body) {
     const read = async () => {
         const result = (await client.get("/api/v1/settings"));
         return typeof result?.data?.settingsRevision === "string" ? result.data.settingsRevision : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt-mcp",
-  "version": "4.62.0",
+  "version": "4.63.0",
   "description": "MCP server for Conduyt CRM — expose CRM operations as AI-accessible tools",
   "type": "module",
   "main": "dist/index.js",

package/scripts/coverage-matrix.json

@@ -1,11 +1,11 @@
 {
-  "generatedAt": "2026-09-16T16:47:18.079Z",
-  "toolCount": 277,
+  "generatedAt": "2026-09-18T04:50:57.467Z",
+  "toolCount": 280,
   "totalEndpoints": 984,
   "counts": {
-    "covered": 259,
+    "covered": 260,
     "excluded": 289,
-    "planned": 436,
+    "planned": 435,
     "uncategorized": 0
   },
   "matrix": {
@@ -3622,6 +3622,8 @@
       "tools": [
         "conduyt_get_contact_table_defaults",
         "conduyt_set_contact_table_defaults",
+        "conduyt_get_lead_pool_settings",
+        "conduyt_update_lead_pool_settings",
         "conduyt_get_lifecycle_settings",
         "conduyt_update_agent_statuses"
       ]
@@ -4174,8 +4176,10 @@
       "reason": "team member listing alias"
     },
     "GET /api/v1/up-for-grabs": {
-      "status": "planned",
-      "reason": "up-for-grabs claim surfaces"
+      "status": "covered",
+      "tools": [
+        "conduyt_list_up_for_grabs"
+      ]
     },
     "POST /api/v1/up-for-grabs/:contactId/claim": {
       "status": "planned",