conduyt-mcp 4.12.0 → 4.14.0

package/dist/index.js

@@ -35,6 +35,7 @@ import { registerDashboardTools } from "./tools/dashboard.js";
 import { registerAiExtendedTools } from "./tools/ai-extended.js";
 import { registerWorkflowSandboxTools } from "./tools/workflow-sandbox.js";
 import { registerPrivacyTools } from "./tools/privacy.js";
+import { registerAccountExportTools } from "./tools/account-exports.js";
 const apiUrl = process.env.CONDUYT_API_URL;
 const apiKey = process.env.CONDUYT_API_KEY;
 if (!apiUrl || !apiKey) {
@@ -92,5 +93,6 @@ registerDashboardTools(server, client);
 registerAiExtendedTools(server, client);
 registerWorkflowSandboxTools(server, client);
 registerPrivacyTools(server, client);
+registerAccountExportTools(server, client);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/account-exports.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConduytClient } from "../client.js";
+/**
+ * Scheduled account exports (Enterprise): settings + run history.
+ *
+ * Listing/downloading full-account export files is account-wide PII egress,
+ * so the /account-exports endpoints require the EXPLICIT 'account-exports'
+ * API-key scope (same posture as 'dnc' — an admin must grant it per key; an
+ * unrestricted key does NOT imply it). The settings endpoints ride the
+ * normal 'settings' scope. File BYTES are not fetched through MCP (a 50k-row
+ * CSV does not belong in a tool result) — tools return metadata plus the
+ * authed downloadPath for the API/CLI to retrieve.
+ */
+export declare function registerAccountExportTools(server: McpServer, client: ConduytClient): void;

package/dist/tools/account-exports.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { formatResult } from "../client.js";
+/**
+ * Scheduled account exports (Enterprise): settings + run history.
+ *
+ * Listing/downloading full-account export files is account-wide PII egress,
+ * so the /account-exports endpoints require the EXPLICIT 'account-exports'
+ * API-key scope (same posture as 'dnc' — an admin must grant it per key; an
+ * unrestricted key does NOT imply it). The settings endpoints ride the
+ * normal 'settings' scope. File BYTES are not fetched through MCP (a 50k-row
+ * CSV does not belong in a tool result) — tools return metadata plus the
+ * authed downloadPath for the API/CLI to retrieve.
+ */
+export function registerAccountExportTools(server, client) {
+    server.tool("conduyt_scheduled_export_get_settings", "Get the account's scheduled-export configuration (enabled, frequency, entities) and whether the Enterprise feature is available on the current plan.", {}, async () => {
+        const result = await client.get("/api/v1/settings/scheduled-export");
+        return formatResult(result);
+    });
+    server.tool("conduyt_scheduled_export_update_settings", "Update scheduled-export settings. Enabling requires an Enterprise plan (403 upsell otherwise). Omitted fields keep their current values. Weekly exports run on Mondays; all exports run in the morning of the account timezone and files are kept 14 days.", {
+        enabled: z.boolean().optional().describe("Turn scheduled exports on/off"),
+        frequency: z.enum(["daily", "weekly"]).optional().describe("How often to export (weekly = Mondays)"),
+        entities: z
+            .array(z.enum(["contacts", "deals", "companies"]))
+            .min(1)
+            .optional()
+            .describe("Which entities to include"),
+    }, async (params) => {
+        const result = await client.patch("/api/v1/settings/scheduled-export", params);
+        return formatResult(result);
+    });
+    server.tool("conduyt_account_exports_list", "List recent scheduled account-export runs with per-file metadata (rows, truncation, size, expiry) and authed downloadPath for each completed file. Requires the explicit 'account-exports' API-key scope. Download the CSV bytes via the API or CLI using downloadPath — not through MCP.", {}, async () => {
+        const result = await client.get("/api/v1/account-exports");
+        return formatResult(result);
+    });
+}

package/dist/tools/discovery.js

@@ -1,7 +1,9 @@
+import { createRequire } from "node:module";
 import { z } from "zod";
 import { formatResult } from "../client.js";
+const requireJson = createRequire(import.meta.url);
 export function registerDiscoveryTools(server, client) {
-    server.tool("conduyt_api_catalog", "Discover all Conduyt CRM API endpoints across 90+ domains, with full request and response schemas. Call this first to learn what the CRM can do — the response carries the exact, current endpoint counts.", {}, async () => {
+    server.tool("conduyt_api_catalog", "Discover all Conduyt CRM API endpoints across 90+ domains, with full request and response schemas. Call this first to learn what the CRM can do — the response carries the exact, current endpoint counts. NOTE: the catalog is the full REST surface; not every endpoint has a dedicated MCP tool. Call conduyt_mcp_coverage to see exactly which endpoints are callable through MCP tools versus API-only.", {}, async () => {
         const result = await client.get("/api/v1/schema/api-catalog");
         return formatResult(result);
     });
@@ -22,4 +24,27 @@ export function registerDiscoveryTools(server, client) {
         const result = await client.get(`/api/v1/search?${params}`);
         return formatResult(result);
     });
+    server.tool("conduyt_mcp_coverage", "The REST-to-MCP coverage matrix: which of the catalog's API endpoints are callable through MCP tools (and by which tool), which are deliberately excluded (with reasons — e.g. interactive-only auth/billing, inbound webhook receivers, realtime browser surfaces), and which are planned but not yet wrapped. Use this to know up front whether a capability you discovered in conduyt_api_catalog is executable here, instead of failing mid-task. Ships with the package and matches this release's tools exactly.", {
+        status: z
+            .enum(["covered", "excluded", "planned"])
+            .optional()
+            .describe("Only return endpoints with this coverage status"),
+        pathPrefix: z.string().optional().describe("Only return endpoints whose path starts with this prefix (e.g. /api/v1/contacts)"),
+    }, async ({ status, pathPrefix }) => {
+        // Pinned at build/publish time by scripts/verify-coverage.mjs (the
+        // prepublish gate fails if any endpoint lacks a designation).
+        const matrix = requireJson("../../scripts/coverage-matrix.json");
+        let entries = Object.entries(matrix.matrix);
+        if (status)
+            entries = entries.filter(([, v]) => v.status === status);
+        if (pathPrefix)
+            entries = entries.filter(([k]) => k.split(" ")[1]?.startsWith(pathPrefix));
+        return formatResult({
+            generatedAt: matrix.generatedAt,
+            toolCount: matrix.toolCount,
+            totalEndpoints: matrix.totalEndpoints,
+            counts: matrix.counts,
+            endpoints: Object.fromEntries(entries),
+        });
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt-mcp",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "description": "MCP server for Conduyt CRM — expose CRM operations as AI-accessible tools",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,8 @@
   },
   "files": [
     "dist",
+    "scripts/coverage-matrix.json",
+    "scripts/coverage-manifest.json",
     "README.md",
     ".env.example"
   ],
@@ -21,8 +23,9 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test \"src/**/*.test.ts\"",
-    "prepublishOnly": "npm run check:version && npm run test && npm run build && ENFORCE=1 node scripts/verify-contracts.mjs",
+    "prepublishOnly": "npm run check:version && npm run test && npm run build && ENFORCE=1 node scripts/verify-contracts.mjs && ENFORCE=1 node scripts/verify-coverage.mjs",
     "audit:contracts": "node scripts/verify-contracts.mjs",
+    "audit:coverage": "node scripts/verify-coverage.mjs",
     "contracts:refresh": "node scripts/refresh-contracts.mjs",
     "check:version": "node scripts/check-version-sync.mjs"
   },

package/scripts/coverage-manifest.json

@@ -0,0 +1,504 @@
+{
+  "description": "SOL-016: the INTENTIONAL REST->MCP coverage policy. Every catalog endpoint must be either covered by a tool (derived automatically), matched by a rule here, or the coverage gate fails \u2014 silent drift between 'discoverable API' and 'callable MCP' is the failure mode this prevents. Rules are first-match-wins prefix matches on 'METHOD /path' keys (a bare path prefix matches every method).",
+  "statuses": {
+    "excluded": "never MCP-callable by design \u2014 the reason says why",
+    "planned": "callable in principle; a typed tool is wanted but not built yet"
+  },
+  "rules": [
+    {
+      "match": "/api/health",
+      "status": "excluded",
+      "reason": "unauthenticated liveness probe; trivially reachable without a tool"
+    },
+    {
+      "match": "/api/v1/cron/",
+      "status": "excluded",
+      "reason": "CRON_SECRET-gated infrastructure jobs; never key-callable"
+    },
+    {
+      "match": "GET /api/v1/account-exports/:id/files/:entity/download",
+      "status": "excluded",
+      "reason": "raw CSV bytes (up to 50k rows) do not belong in a tool result; conduyt_account_exports_list returns the authed downloadPath for API/CLI retrieval"
+    },
+    {
+      "match": "/api/v1/auth/",
+      "status": "excluded",
+      "reason": "interactive session/password/SSO flows; API keys are the MCP auth model"
+    },
+    {
+      "match": "/api/v1/admin/",
+      "status": "excluded",
+      "reason": "super-admin platform operations (Conduyt staff only)"
+    },
+    {
+      "match": "/api/v1/billing",
+      "status": "excluded",
+      "reason": "the API itself rejects key-based billing management (interactive session required)"
+    },
+    {
+      "match": "/api/public/",
+      "status": "excluded",
+      "reason": "public unauthenticated surfaces (forms, booking, unsubscribe) \u2014 no key semantics"
+    },
+    {
+      "match": "/api/v1/public/",
+      "status": "excluded",
+      "reason": "public unauthenticated surfaces \u2014 no key semantics"
+    },
+    {
+      "match": "/api/v1/webhooks/manage",
+      "status": "planned",
+      "reason": "OUTBOUND webhook subscription management (CRUD/test/deliveries) \u2014 agent-relevant, unlike the inbound receivers below"
+    },
+    {
+      "match": "/api/v1/webhooks/replay",
+      "status": "planned",
+      "reason": "outbound webhook delivery replay \u2014 agent-relevant"
+    },
+    {
+      "match": "/api/v1/webhooks/",
+      "status": "excluded",
+      "reason": "inbound provider callback receivers (Twilio/Resend/etc.), not client-callable"
+    },
+    {
+      "match": "/api/v1/scim/",
+      "status": "excluded",
+      "reason": "IdP-facing SCIM protocol surface (its own bearer tokens)"
+    },
+    {
+      "match": "/api/v1/sso/",
+      "status": "excluded",
+      "reason": "SAML/SSO configuration + protocol endpoints; interactive/IdP-facing"
+    },
+    {
+      "match": "/api/v1/dialer/",
+      "status": "excluded",
+      "reason": "realtime browser dialer (WebRTC tokens, live call control) \u2014 needs a live audio session"
+    },
+    {
+      "match": "/api/v1/screen-share",
+      "status": "excluded",
+      "reason": "realtime browser RTC surface"
+    },
+    {
+      "match": "/api/v1/remote-assist",
+      "status": "excluded",
+      "reason": "realtime browser RTC surface"
+    },
+    {
+      "match": "/api/v1/push",
+      "status": "excluded",
+      "reason": "browser push-notification subscription plumbing"
+    },
+    {
+      "match": "/api/v1/confirm",
+      "status": "excluded",
+      "reason": "emailed one-click confirmation links (token-in-URL), not key-callable"
+    },
+    {
+      "match": "/api/v1/status-metadata",
+      "status": "excluded",
+      "reason": "UI enum/metadata hydration for dashboard pickers; tools embed their enums"
+    },
+    {
+      "match": "/api/v1/uploads",
+      "status": "excluded",
+      "reason": "presigned browser upload handshake; MCP has no file-stream transport today"
+    },
+    {
+      "match": "/api/v1/files",
+      "status": "planned",
+      "reason": "file listing/metadata is agent-useful; upload stays browser-side"
+    },
+    {
+      "match": "/api/v1/chat",
+      "status": "planned",
+      "reason": "team chat read/post for agents"
+    },
+    {
+      "match": "/api/v1/settings",
+      "status": "planned",
+      "reason": "account settings read/update surfaces"
+    },
+    {
+      "match": "/api/v1/imports",
+      "status": "planned",
+      "reason": "import job monitoring/resubmission (ai-import tool covers creation)"
+    },
+    {
+      "match": "/api/v1/reports",
+      "status": "planned",
+      "reason": "additional report surfaces beyond ai/insights"
+    },
+    {
+      "match": "/api/v1/reporting",
+      "status": "planned",
+      "reason": "additional report surfaces beyond ai/insights"
+    },
+    {
+      "match": "/api/v1/calendar",
+      "status": "planned",
+      "reason": "calendar/booking management beyond current appointment tools"
+    },
+    {
+      "match": "/api/v1/calendars",
+      "status": "planned",
+      "reason": "calendar connection management"
+    },
+    {
+      "match": "/api/v1/booking-pages",
+      "status": "planned",
+      "reason": "booking page management"
+    },
+    {
+      "match": "/api/v1/booking-routing-forms",
+      "status": "planned",
+      "reason": "booking routing form management"
+    },
+    {
+      "match": "/api/v1/automations",
+      "status": "planned",
+      "reason": "automation subroutes beyond the workflow-builder tools (step-logs detail, node ops)"
+    },
+    {
+      "match": "/api/v1/automation-executions",
+      "status": "planned",
+      "reason": "execution inspection"
+    },
+    {
+      "match": "/api/v1/contacts",
+      "status": "planned",
+      "reason": "contact subroutes beyond the core CRUD/search tools"
+    },
+    {
+      "match": "/api/v1/deals",
+      "status": "planned",
+      "reason": "deal subroutes beyond core CRUD (history, files, links)"
+    },
+    {
+      "match": "/api/v1/companies",
+      "status": "planned",
+      "reason": "company subroutes beyond core CRUD"
+    },
+    {
+      "match": "/api/v1/users",
+      "status": "planned",
+      "reason": "team management subroutes beyond list/invite"
+    },
+    {
+      "match": "/api/v1/tasks",
+      "status": "planned",
+      "reason": "task subroutes beyond core CRUD"
+    },
+    {
+      "match": "/api/v1/workflows",
+      "status": "planned",
+      "reason": "workflow template surfaces"
+    },
+    {
+      "match": "/api/v1/emails",
+      "status": "planned",
+      "reason": "email template/sequence management"
+    },
+    {
+      "match": "/api/v1/email-domains",
+      "status": "planned",
+      "reason": "sending-domain management"
+    },
+    {
+      "match": "/api/v1/mailbox",
+      "status": "planned",
+      "reason": "mailbox sync surfaces"
+    },
+    {
+      "match": "/api/v1/conversations",
+      "status": "planned",
+      "reason": "conversation thread surfaces"
+    },
+    {
+      "match": "/api/v1/messages",
+      "status": "planned",
+      "reason": "message surfaces beyond send tools"
+    },
+    {
+      "match": "/api/v1/sms",
+      "status": "planned",
+      "reason": "SMS surfaces beyond send tools"
+    },
+    {
+      "match": "/api/v1/sms-providers",
+      "status": "planned",
+      "reason": "external SMS provider management"
+    },
+    {
+      "match": "/api/v1/drip-campaigns",
+      "status": "planned",
+      "reason": "drip campaign management"
+    },
+    {
+      "match": "/api/v1/drip-tracks",
+      "status": "planned",
+      "reason": "drip track management"
+    },
+    {
+      "match": "/api/v1/lead-routing",
+      "status": "planned",
+      "reason": "lead routing rule management"
+    },
+    {
+      "match": "/api/v1/lead-pool",
+      "status": "planned",
+      "reason": "lead pool claim surfaces"
+    },
+    {
+      "match": "/api/v1/up-for-grabs",
+      "status": "planned",
+      "reason": "up-for-grabs claim surfaces"
+    },
+    {
+      "match": "/api/v1/invoices",
+      "status": "planned",
+      "reason": "invoicing"
+    },
+    {
+      "match": "/api/v1/generated-documents",
+      "status": "planned",
+      "reason": "document generation/sending"
+    },
+    {
+      "match": "/api/v1/document-templates",
+      "status": "planned",
+      "reason": "document template management"
+    },
+    {
+      "match": "/api/v1/forms",
+      "status": "planned",
+      "reason": "form management"
+    },
+    {
+      "match": "/api/v1/notifications",
+      "status": "planned",
+      "reason": "notification surfaces"
+    },
+    {
+      "match": "/api/v1/notes",
+      "status": "planned",
+      "reason": "note subroutes beyond create"
+    },
+    {
+      "match": "/api/v1/quick-notes",
+      "status": "planned",
+      "reason": "quick note surfaces"
+    },
+    {
+      "match": "/api/v1/quick-connects",
+      "status": "planned",
+      "reason": "quick connect management"
+    },
+    {
+      "match": "/api/v1/groups",
+      "status": "planned",
+      "reason": "member group management"
+    },
+    {
+      "match": "/api/v1/rep-shifts",
+      "status": "planned",
+      "reason": "rep shift scheduling"
+    },
+    {
+      "match": "/api/v1/availability",
+      "status": "planned",
+      "reason": "availability windows"
+    },
+    {
+      "match": "/api/v1/smart-views",
+      "status": "planned",
+      "reason": "smart view management beyond summaries"
+    },
+    {
+      "match": "/api/v1/smart-lists",
+      "status": "planned",
+      "reason": "smart list management"
+    },
+    {
+      "match": "/api/v1/custom-fields",
+      "status": "planned",
+      "reason": "custom field admin beyond read"
+    },
+    {
+      "match": "/api/v1/pipelines",
+      "status": "planned",
+      "reason": "pipeline subroutes beyond core CRUD"
+    },
+    {
+      "match": "/api/v1/calls",
+      "status": "planned",
+      "reason": "call subroutes beyond list/log"
+    },
+    {
+      "match": "/api/v1/ai",
+      "status": "planned",
+      "reason": "AI surfaces beyond chat/insights/tasks tools"
+    },
+    {
+      "match": "/api/v1/api-keys",
+      "status": "planned",
+      "reason": "API key admin beyond self-check"
+    },
+    {
+      "match": "/api/v1/accounts",
+      "status": "planned",
+      "reason": "sub-account management"
+    },
+    {
+      "match": "/api/v1/batch-operations",
+      "status": "planned",
+      "reason": "batch operation monitoring"
+    },
+    {
+      "match": "/api/v1/knowledge",
+      "status": "planned",
+      "reason": "RAG knowledge-base management"
+    },
+    {
+      "match": "/api/v1/playbooks",
+      "status": "planned",
+      "reason": "playbook management"
+    },
+    {
+      "match": "/api/v1/playbook-enrollments",
+      "status": "planned",
+      "reason": "playbook enrollment surfaces"
+    },
+    {
+      "match": "/api/v1/warmy-engine",
+      "status": "planned",
+      "reason": "email warm-up engine surfaces"
+    },
+    {
+      "match": "/api/v1/integrations",
+      "status": "planned",
+      "reason": "integration management"
+    },
+    {
+      "match": "/api/v1/schema",
+      "status": "planned",
+      "reason": "schema/catalog subroutes beyond the catalog tool"
+    },
+    {
+      "match": "/api/v1/errors",
+      "status": "planned",
+      "reason": "client error ingestion"
+    },
+    {
+      "match": "/api/v1/gdpr-export",
+      "status": "planned",
+      "reason": "gdpr export alias routes (contact-scoped tools exist)"
+    },
+    {
+      "match": "/api/track/",
+      "status": "excluded",
+      "reason": "email open/click tracking pixels and redirects \u2014 recipient-facing"
+    },
+    {
+      "match": "/api/webhooks/",
+      "status": "excluded",
+      "reason": "inbound provider callback receivers (Resend), not client-callable"
+    },
+    {
+      "match": "/api/v1/health",
+      "status": "excluded",
+      "reason": "unauthenticated liveness probe"
+    },
+    {
+      "match": "/api/v1/appointments",
+      "status": "planned",
+      "reason": "appointment mutation subroutes beyond booking tools"
+    },
+    {
+      "match": "/api/v1/account/",
+      "status": "planned",
+      "reason": "account readiness/onboarding surfaces"
+    },
+    {
+      "match": "/api/v1/activities",
+      "status": "planned",
+      "reason": "activity detail reads beyond the log tools"
+    },
+    {
+      "match": "/api/v1/bulk",
+      "status": "planned",
+      "reason": "bulk operation discovery/monitoring beyond the typed bulk tools"
+    },
+    {
+      "match": "/api/v1/bulk-operations",
+      "status": "planned",
+      "reason": "bulk operation monitoring"
+    },
+    {
+      "match": "/api/v1/contact",
+      "status": "planned",
+      "reason": "singular contact alias route"
+    },
+    {
+      "match": "/api/v1/data-model/",
+      "status": "planned",
+      "reason": "data-model quality reporting"
+    },
+    {
+      "match": "/api/v1/dnc/",
+      "status": "planned",
+      "reason": "DNC import beyond the typed DNC tools"
+    },
+    {
+      "match": "/api/v1/drip-enrollments",
+      "status": "planned",
+      "reason": "drip enrollment timeline inspection"
+    },
+    {
+      "match": "/api/v1/email/",
+      "status": "planned",
+      "reason": "bulk email send surfaces"
+    },
+    {
+      "match": "/api/v1/phone-numbers",
+      "status": "planned",
+      "reason": "phone number inventory"
+    },
+    {
+      "match": "/api/v1/products",
+      "status": "planned",
+      "reason": "product catalog subroutes"
+    },
+    {
+      "match": "/api/v1/saved-filters",
+      "status": "planned",
+      "reason": "saved filter management"
+    },
+    {
+      "match": "/api/v1/scoring-rules",
+      "status": "planned",
+      "reason": "scoring rule simulation beyond scoring tools"
+    },
+    {
+      "match": "/api/v1/tags",
+      "status": "planned",
+      "reason": "tag detail reads beyond list/create tools"
+    },
+    {
+      "match": "/api/v1/team/",
+      "status": "planned",
+      "reason": "team member listing alias"
+    },
+    {
+      "match": "/api/v1/webhook-logs",
+      "status": "planned",
+      "reason": "outbound webhook delivery logs"
+    },
+    {
+      "match": "/api/v1/webhooks",
+      "status": "planned",
+      "reason": "outbound webhook subscription management (distinct from the inbound /webhooks/ receivers)"
+    }
+  ]
+}