@sendly/mcp 2.2.0 → 2.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @sendly/mcp
 
-Full SMS platform for AI agents — 82 tools for messaging, contacts, campaigns, templates, webhooks, OTP verification, conversations, labels, drafts, and more via [Model Context Protocol](https://modelcontextprotocol.io).
+Full SMS platform for AI agents — 91 tools for messaging, contacts, campaigns, templates, webhooks, OTP verification, conversations, labels, drafts, and more via [Model Context Protocol](https://modelcontextprotocol.io).
 
 ## Quick Setup
 
@@ -54,7 +54,7 @@ openclaw mcp set sendly '{"command":"npx","args":["-y","@sendly/mcp"],"env":{"SE
 
 Then ask your agent: *"Send a test SMS to +15005550000 saying Hello from my agent"*
 
-## All 82 Tools
+## All 91 Tools
 
 ### Messaging (6)
 
@@ -90,7 +90,7 @@ Then ask your agent: *"Send a test SMS to +15005550000 saying Hello from my agen
 | `mark_conversation_read` | Reset unread count to zero |
 | `get_suggested_replies` | AI-generated replies in 3 tones |
 
-### Contacts (6)
+### Contacts (9)
 
 | Tool | Description |
 |------|-------------|
@@ -99,6 +99,9 @@ Then ask your agent: *"Send a test SMS to +15005550000 saying Hello from my agen
 | `get_contact` | Get contact with list memberships |
 | `update_contact` | Update name, email, or metadata |
 | `delete_contact` | Delete (removes from all lists) |
+| `mark_contact_valid` | Mark a contact's phone number as validated |
+| `check_contact_numbers` | Bulk-check phone number validity |
+| `bulk_mark_contacts_valid` | Bulk-mark contacts as validated |
 | `import_contacts` | Bulk import up to 10,000 contacts |
 
 ### Contact Lists (7)
@@ -168,7 +171,7 @@ Then ask your agent: *"Send a test SMS to +15005550000 saying Hello from my agen
 | `approve_draft` | Approve and send as real SMS |
 | `reject_draft` | Reject with reason |
 
-### Webhooks (9)
+### Webhooks (12)
 
 | Tool | Description |
 |------|-------------|
@@ -181,6 +184,9 @@ Then ask your agent: *"Send a test SMS to +15005550000 saying Hello from my agen
 | `list_webhook_deliveries` | Delivery history with statuses |
 | `rotate_webhook_secret` | Rotate signing secret |
 | `list_webhook_event_types` | List available event types |
+| `reset_webhook_circuit` | Reset open circuit breaker on an endpoint |
+| `redeliver_webhook` | Redeliver a failed webhook event |
+| `backfill_webhook` | Backfill missed deliveries for an endpoint |
 
 ### OTP / Verify (7)
 
@@ -207,11 +213,14 @@ Then ask your agent: *"Send a test SMS to +15005550000 saying Hello from my agen
 |------|-------------|
 | `get_account` | Credit balance, verification status, rate limits |
 
-### Enterprise (1)
+### Enterprise (4)
 
 | Tool | Description |
 |------|-------------|
 | `generate_business_page` | Generate hosted business page for verification *(enterprise only)* |
+| `enterprise_workspace_get_verification` | Get current toll-free verification record for a workspace *(enterprise only)* |
+| `enterprise_workspace_submit_verification` | Submit or resubmit toll-free verification (partial-update friendly) *(enterprise only)* |
+| `enterprise_workspace_resubmit_verification` | Convenience alias of submit — use when retrying after rejection *(enterprise only)* |
 
 ## Authentication
 
@@ -241,7 +250,7 @@ With test keys, use magic numbers:
 
 ## Links
 
-- [MCP Tools Reference](https://sendly.live/docs/ai/mcp-tools) — all 82 tools with schemas
+- [MCP Tools Reference](https://sendly.live/docs/ai/mcp-tools) — all 91 tools with schemas
 - [Agent Skills](https://sendly.live/skills) — SKILL.md files for 8 platforms
 - [API Reference](https://sendly.live/docs/api)
 - [Sendly Dashboard](https://sendly.live/dashboard)

package/dist/index.js

@@ -3,6 +3,9 @@
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
 
 // src/tools.ts
 import { z } from "zod";
@@ -1238,6 +1241,78 @@ function registerAllTools(server2, api2) {
       }
     }
   );
+  server2.tool(
+    "reset_webhook_circuit",
+    "Reset the circuit breaker for a webhook so deliveries resume immediately instead of waiting for the automatic 5-minute recovery.",
+    { webhookId: z.string().describe("The webhook ID") },
+    async ({ webhookId }) => {
+      try {
+        return ok(await api2("POST", `/webhooks/${webhookId}/reset-circuit`));
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
+  server2.tool(
+    "redeliver_webhook",
+    "Replay failed or cancelled webhook deliveries from the audit log for a time window. Use after a customer endpoint has recovered from an outage. Reset the circuit first if it is open. Each replay preserves the original event_id for dedup.",
+    {
+      webhookId: z.string().describe("The webhook ID"),
+      since: z.string().optional().describe(
+        "Earliest delivery time, ISO-8601. Defaults to 24h ago."
+      ),
+      until: z.string().optional().describe("Latest delivery time, ISO-8601. Defaults to now."),
+      eventTypes: z.array(z.string()).optional().describe("Filter by event type. Defaults to all."),
+      statuses: z.array(z.string()).optional().describe(
+        "Replay deliveries in any of these statuses. Defaults to ['failed', 'cancelled']."
+      ),
+      limit: z.number().int().positive().max(1e4).optional().describe("Max deliveries to requeue. Defaults to 1000, max 10000.")
+    },
+    async ({ webhookId, since, until, eventTypes, statuses, limit }) => {
+      try {
+        const body = {};
+        if (since !== void 0) body.since = since;
+        if (until !== void 0) body.until = until;
+        if (eventTypes !== void 0) body.event_types = eventTypes;
+        if (statuses !== void 0) body.statuses = statuses;
+        if (limit !== void 0) body.limit = limit;
+        return ok(
+          await api2("POST", `/webhooks/${webhookId}/redeliver`, body)
+        );
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
+  server2.tool(
+    "backfill_webhook",
+    "Synthesize webhook events from the underlying message log for events that have no audit row (the case redeliver_webhook cannot recover). Use this when a circuit-breaker outage left events with no delivery record. Synthesized events have fresh IDs \u2014 clients should dedupe by event.data.object.id (the message ID). Reset the circuit first if it is open.",
+    {
+      webhookId: z.string().describe("The webhook ID"),
+      since: z.string().optional().describe(
+        "Earliest message time, ISO-8601. Defaults to 24h ago."
+      ),
+      until: z.string().optional().describe("Latest message time, ISO-8601. Defaults to now."),
+      eventTypes: z.array(z.string()).optional().describe(
+        "Filter by event type. Defaults to subscribed message events."
+      ),
+      limit: z.number().int().positive().max(1e4).optional().describe("Max events to synthesize. Defaults to 1000, max 10000.")
+    },
+    async ({ webhookId, since, until, eventTypes, limit }) => {
+      try {
+        const body = {};
+        if (since !== void 0) body.since = since;
+        if (until !== void 0) body.until = until;
+        if (eventTypes !== void 0) body.event_types = eventTypes;
+        if (limit !== void 0) body.limit = limit;
+        return ok(
+          await api2("POST", `/webhooks/${webhookId}/backfill`, body)
+        );
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
   server2.tool(
     "send_otp",
     "Send an OTP verification code via SMS. Use for phone verification, 2FA, or identity confirmation. In sandbox mode (test API key), the code is returned in the response.",
@@ -1414,10 +1489,323 @@ function registerAllTools(server2, api2) {
       }
     }
   );
+  server2.tool(
+    "enterprise_workspace_get_verification",
+    "Get the current verification record for an enterprise workspace. Useful before submit/resubmit to see what's already on file (the server merges your submit payload with existing fields).",
+    {
+      workspaceId: z.string().describe("The enterprise workspace ID")
+    },
+    async ({ workspaceId }) => {
+      try {
+        return ok(
+          await api2(
+            "GET",
+            `/enterprise/workspaces/${encodeURIComponent(workspaceId)}/verification`
+          )
+        );
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
+  const verificationSubmitSchema = {
+    workspaceId: z.string().describe("The enterprise workspace ID"),
+    businessName: z.string().optional().describe("Legal business name"),
+    doingBusinessAs: z.string().optional().describe("DBA / trade name, if different from legal name"),
+    website: z.string().optional().describe("Business website URL (https://...)"),
+    entityType: z.string().optional().describe(
+      "Entity type (e.g., LLC, CORPORATION, SOLE_PROPRIETOR, NON_PROFIT, GOVERNMENT). For SOLE_PROPRIETOR, omit brn/brnType/brnCountry."
+    ),
+    address: z.object({
+      street: z.string().optional().describe("Street address"),
+      city: z.string().optional().describe("City"),
+      state: z.string().optional().describe("State or province (full name preferred, e.g., 'California')"),
+      zip: z.string().optional().describe("ZIP or postal code"),
+      country: z.string().optional().describe("ISO country code (e.g., 'US')")
+    }).optional().describe("Business address (nested). Omit fields you don't want to change."),
+    contact: z.object({
+      firstName: z.string().optional().describe("Contact first name"),
+      lastName: z.string().optional().describe("Contact last name"),
+      email: z.string().optional().describe("Contact email"),
+      phone: z.string().optional().describe("Contact phone in E.164 format")
+    }).optional().describe("Authorized contact (nested). Omit fields you don't want to change."),
+    brn: z.string().optional().describe("Business registration number (e.g., EIN). Omit for sole proprietors."),
+    brnType: z.string().optional().describe("BRN type (e.g., EIN, DUNS, VAT). Omit for sole proprietors."),
+    brnCountry: z.string().optional().describe("BRN issuing country ISO code. Omit for sole proprietors."),
+    useCase: z.string().optional().describe("Use case (e.g., 'Insurance Services', '2FA', 'Appointment Reminders')"),
+    useCaseSummary: z.string().optional().describe("Brief description of what the business sends and why"),
+    sampleMessages: z.string().optional().describe("Sample messages the business will send (text, can be multi-line)"),
+    optInWorkflow: z.string().optional().describe("Description of how recipients opt in (web form, paper form, verbal, etc.)"),
+    optInImageUrls: z.array(z.string()).optional().describe("Array of URLs to opt-in proof images/screenshots"),
+    monthlyVolume: z.number().optional().describe("Expected monthly message volume"),
+    additionalInformation: z.string().optional().describe("Additional context for the carrier reviewer"),
+    ageGatedContent: z.boolean().optional().describe("True if content is age-gated (alcohol, gambling, etc.)"),
+    isvReseller: z.string().optional().describe("ISV / reseller name, if applicable"),
+    privacyUrl: z.string().optional().describe("Privacy policy URL (auto-preserved if hosted on Sendly)"),
+    termsUrl: z.string().optional().describe("Terms of service URL (auto-preserved if hosted on Sendly)")
+  };
+  const submitVerificationHandler = async (params) => {
+    try {
+      const { workspaceId, ...rest } = params;
+      const body = {};
+      for (const [k, v] of Object.entries(rest)) {
+        if (v !== void 0) body[k] = v;
+      }
+      return ok(
+        await api2(
+          "POST",
+          `/enterprise/workspaces/${encodeURIComponent(workspaceId)}/verification/submit`,
+          body
+        )
+      );
+    } catch (e) {
+      return err(e);
+    }
+  };
+  server2.tool(
+    "enterprise_workspace_submit_verification",
+    "Submit or resubmit a toll-free verification for an enterprise workspace. Partial-update friendly: omit fields you don't want to change \u2014 they'll be filled from the existing record. Hosted page URLs (/biz/, /opt-in/, /legal/) generated during provision are auto-preserved. For sole proprietors, leave brn/brnType/brnCountry undefined.",
+    verificationSubmitSchema,
+    submitVerificationHandler
+  );
+  server2.tool(
+    "enterprise_workspace_resubmit_verification",
+    "Convenience alias for submit_verification \u2014 identical behavior. Use when retrying after a rejection.",
+    verificationSubmitSchema,
+    submitVerificationHandler
+  );
+  const upgradeEntitySchema = {
+    workspaceId: z.string().describe(
+      "The Sendly workspace ID being upgraded. Found in the dashboard URL or the `organizationId` field of any object."
+    )
+  };
+  const upgradeStartSchema = {
+    workspaceId: z.string().describe("The Sendly workspace ID being upgraded."),
+    businessName: z.string().describe(
+      "Legal name of the new entity, exactly as filed with the IRS / state (e.g. 'Acme Holdings LLC')."
+    ),
+    brn: z.string().describe(
+      "Business registration number for the new entity. For US LLCs/Corps this is the EIN (XX-XXXXXXX)."
+    ),
+    brnType: z.enum(["EIN", "SSN", "DUNS", "CRA", "VAT", "LEI", "OTHER"]).describe("Type of business registration number."),
+    brnCountry: z.string().describe(
+      "ISO 3166-1 alpha-2 country code for the registration (e.g. 'US', 'CA')."
+    ),
+    entityType: z.enum([
+      "SOLE_PROPRIETOR",
+      "PRIVATE_PROFIT",
+      "PUBLIC_PROFIT",
+      "NON_PROFIT",
+      "GOVERNMENT"
+    ]).describe(
+      "Legal form of the entity. Use PRIVATE_PROFIT for LLCs and standard corporations."
+    ),
+    doingBusinessAs: z.string().optional(),
+    website: z.string().optional(),
+    address1: z.string().optional(),
+    address2: z.string().optional(),
+    city: z.string().optional(),
+    state: z.string().optional().describe("Full state/province name, not the 2-letter code."),
+    zip: z.string().optional(),
+    addressCountry: z.string().optional(),
+    contactFirstName: z.string().optional(),
+    contactLastName: z.string().optional(),
+    contactEmail: z.string().optional(),
+    contactPhone: z.string().optional().describe("E.164 format with country code, e.g. '+14155551234'."),
+    monthlyVolume: z.string().optional(),
+    useCase: z.string().optional(),
+    useCaseSummary: z.string().optional(),
+    sampleMessages: z.string().optional(),
+    optInWorkflow: z.string().optional(),
+    privacyUrl: z.string().optional(),
+    termsUrl: z.string().optional(),
+    additionalInformation: z.string().optional(),
+    ageGatedContent: z.boolean().optional(),
+    einDocBase64: z.string().optional().describe(
+      "Optional IRS letter (CP-575 or 147C) as a base64-encoded PDF, \u22645MB. Strongly recommended for entities formed within the last 6 months \u2014 the carrier may otherwise reject because the new EIN isn't yet visible in public registries."
+    ),
+    einDocFilename: z.string().optional().describe("Optional filename for the EIN doc (defaults to 'ein-doc.pdf').")
+  };
+  const buildUpgradeForm = (input) => {
+    const form = new FormData();
+    for (const [k, v] of Object.entries(input)) {
+      if (k === "workspaceId" || k === "einDocBase64" || k === "einDocFilename")
+        continue;
+      if (v === void 0 || v === null) continue;
+      form.append(k, typeof v === "boolean" ? String(v) : v);
+    }
+    if (input.einDocBase64 && typeof input.einDocBase64 === "string") {
+      const buf = Buffer.from(input.einDocBase64, "base64");
+      const blob = new Blob([buf], { type: "application/pdf" });
+      form.append(
+        "einDoc",
+        blob,
+        input.einDocFilename || "ein-doc.pdf"
+      );
+    }
+    return form;
+  };
+  server2.tool(
+    "preflight_business_upgrade",
+    "Validate a proposed business entity upgrade before submitting. Returns issues + auto-fix suggestions (e.g. 'sole-prop + EIN mismatch \u2014 change entity to PRIVATE_PROFIT'). Use this to dry-run new entity details before calling start_business_upgrade. Read-only; no DB or carrier writes.",
+    {
+      businessName: z.string(),
+      brn: z.string(),
+      brnType: z.enum(["EIN", "SSN", "DUNS", "CRA", "VAT", "LEI", "OTHER"]),
+      brnCountry: z.string(),
+      entityType: z.enum([
+        "SOLE_PROPRIETOR",
+        "PRIVATE_PROFIT",
+        "PUBLIC_PROFIT",
+        "NON_PROFIT",
+        "GOVERNMENT"
+      ]),
+      doingBusinessAs: z.string().optional(),
+      website: z.string().optional(),
+      address1: z.string().optional(),
+      city: z.string().optional(),
+      state: z.string().optional(),
+      zip: z.string().optional(),
+      addressCountry: z.string().optional(),
+      contactEmail: z.string().optional(),
+      contactPhone: z.string().optional(),
+      monthlyVolume: z.string().optional(),
+      useCase: z.string().optional(),
+      sampleMessages: z.string().optional(),
+      optInWorkflow: z.string().optional()
+    },
+    async (input) => {
+      try {
+        return ok(await api2("POST", "/verification/preflight", input));
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
+  server2.tool(
+    "get_business_upgrade_best_prefill",
+    "Read 'best-of' values for the upgrade form across all of the caller's verified workspaces. Returns most-recent non-empty values per messaging field (useCase, sampleMessages, optInWorkflow, etc.). Useful when populating a fresh upgrade form for a workspace whose current record is incomplete.",
+    {},
+    async () => {
+      try {
+        return ok(await api2("GET", "/verification/best-prefill"));
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
+  server2.tool(
+    "start_business_upgrade",
+    "Start a business entity upgrade for the given workspace. Auto-provisions a new toll-free number + messaging profile under the new entity, submits to the carrier for review, and stores the EIN document (if provided) securely until approval. The current toll-free number keeps sending throughout the 1-2 week review window; on approval, the new number takes over atomically. Use preflight_business_upgrade first to surface any blockers.",
+    upgradeStartSchema,
+    async (input) => {
+      try {
+        const { workspaceId } = input;
+        const form = buildUpgradeForm(input);
+        return ok(
+          await api2(
+            "POST",
+            `/workspaces/${encodeURIComponent(workspaceId)}/upgrade`,
+            form
+          )
+        );
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
+  server2.tool(
+    "get_business_upgrade_status",
+    "Check the status of a pending business entity upgrade for a workspace. Returns the pending row (with status, target toll-free number, rejection reason if any) or null if no upgrade is in flight. Statuses: pending, waiting_for_telnyx, waiting_for_customer, rejected, verified.",
+    upgradeEntitySchema,
+    async ({ workspaceId }) => {
+      try {
+        return ok(
+          await api2(
+            "GET",
+            `/workspaces/${encodeURIComponent(workspaceId)}/upgrade/status`
+          )
+        );
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
+  server2.tool(
+    "cancel_business_upgrade",
+    "Cancel a pending business entity upgrade. Releases the reserved toll-free number, deletes the new messaging profile, removes the stored EIN document, and clears the pending record. The current toll-free number is unaffected. Idempotent \u2014 returns success even if there was nothing to cancel.",
+    upgradeEntitySchema,
+    async ({ workspaceId }) => {
+      try {
+        return ok(
+          await api2(
+            "POST",
+            `/workspaces/${encodeURIComponent(workspaceId)}/upgrade/cancel`
+          )
+        );
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
+  server2.tool(
+    "resubmit_business_upgrade",
+    "Resubmit a previously rejected (or waiting-for-customer) business entity upgrade with corrected fields and optionally a new EIN document. Same field shape as start_business_upgrade; fields you omit keep the previously-submitted values.",
+    upgradeStartSchema,
+    async (input) => {
+      try {
+        const { workspaceId } = input;
+        const form = buildUpgradeForm(input);
+        return ok(
+          await api2(
+            "POST",
+            `/workspaces/${encodeURIComponent(workspaceId)}/upgrade/resubmit`,
+            form
+          )
+        );
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
+  server2.tool(
+    "set_business_upgrade_old_number_disposition",
+    "After a successful business upgrade, choose what happens to the old (now-superseded) toll-free number. 'moved' keeps it active under another workspace owned by the same user (requires targetWorkspaceId); 'released' returns it to the carrier pool. Idempotent.",
+    {
+      workspaceId: z.string(),
+      disposition: z.enum(["moved", "released"]).describe(
+        "'moved' = keep old number active on another workspace; 'released' = return to carrier pool."
+      ),
+      targetWorkspaceId: z.string().optional().describe(
+        "Required when disposition='moved'. Workspace ID to attach the old number to."
+      )
+    },
+    async ({
+      workspaceId,
+      disposition,
+      targetWorkspaceId
+    }) => {
+      try {
+        return ok(
+          await api2(
+            "POST",
+            `/workspaces/${encodeURIComponent(workspaceId)}/upgrade/disposition`,
+            { disposition, targetOrgId: targetWorkspaceId }
+          )
+        );
+      } catch (e) {
+        return err(e);
+      }
+    }
+  );
 }
 
 // src/index.ts
-var VERSION = "2.0.0";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(
+  readFileSync(resolve(__dirname, "../package.json"), "utf8")
+);
+var VERSION = pkg.version;
 var API_KEY = process.env.SENDLY_API_KEY;
 var BASE_URL = process.env.SENDLY_BASE_URL || "https://sendly.live";
 if (!API_KEY) {
@@ -1458,7 +1846,7 @@ async function api(method, path, body, query) {
   }
   const headers = {
     Authorization: `Bearer ${API_KEY}`,
-    "User-Agent": "@sendly/mcp/2.0.2"
+    "User-Agent": `@sendly/mcp/${VERSION}`
   };
   if (body) headers["Content-Type"] = "application/json";
   const res = await fetch(url.toString(), {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendly/mcp",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Sendly MCP Server — Full SMS platform for AI agents. Messaging, contacts, campaigns, templates, webhooks, OTP verification, and more.",
   "type": "module",
   "main": "dist/index.js",