@sendly/mcp 1.0.0

package/README.md

@@ -0,0 +1,105 @@
+# @sendly/mcp
+
+SMS for AI agents — send messages, manage conversations, verify phone numbers via [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Quick Setup
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sendly": {
+      "command": "npx",
+      "args": ["-y", "@sendly/mcp"],
+      "env": {
+        "SENDLY_API_KEY": "sk_test_v1_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "sendly": {
+      "command": "npx",
+      "args": ["-y", "@sendly/mcp"],
+      "env": {
+        "SENDLY_API_KEY": "sk_test_v1_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### VS Code / Windsurf
+
+Same pattern — set `SENDLY_API_KEY` in the environment and run `npx @sendly/mcp` as the MCP server command.
+
+## Available Tools
+
+### Messaging
+
+| Tool | Description |
+|------|-------------|
+| `send_sms` | Send an SMS message to a phone number |
+| `list_messages` | List sent and received messages with pagination |
+| `get_message` | Get details of a specific message |
+| `schedule_sms` | Schedule a message for future delivery |
+| `cancel_scheduled_message` | Cancel a scheduled message (credits refunded) |
+
+### Conversations
+
+| Tool | Description |
+|------|-------------|
+| `list_conversations` | List conversation threads by recent activity |
+| `get_conversation` | Get a conversation with optional message history |
+| `reply_to_conversation` | Reply within a conversation (auto-sets recipient) |
+| `update_conversation` | Update metadata or tags on a conversation |
+| `close_conversation` | Close a conversation (auto-reopens on new inbound) |
+| `reopen_conversation` | Reopen a closed conversation |
+| `mark_conversation_read` | Reset unread count to zero |
+
+### OTP / Verification
+
+| Tool | Description |
+|------|-------------|
+| `send_otp` | Send a one-time password via SMS |
+| `check_otp` | Verify an OTP code |
+| `get_verification_status` | Check verification status |
+
+### Account
+
+| Tool | Description |
+|------|-------------|
+| `get_account` | Get credit balance, verification status, rate limits |
+
+## Authentication
+
+Set `SENDLY_API_KEY` as an environment variable:
+
+- **Test keys** (`sk_test_v1_...`) — sandbox mode, messages simulated, OTP codes returned in response
+- **Live keys** (`sk_live_v1_...`) — real SMS delivery on verified phone numbers
+
+Get your API key at [sendly.live](https://sendly.live) → Settings → API Keys.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SENDLY_API_KEY` | Yes | Your Sendly API key |
+| `SENDLY_BASE_URL` | No | API base URL (default: `https://sendly.live`) |
+
+## Links
+
+- [Documentation](https://sendly.live/docs)
+- [API Reference](https://sendly.live/docs/api)
+- [Sendly Dashboard](https://sendly.live)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var API_KEY = process.env.SENDLY_API_KEY;
+var BASE_URL = process.env.SENDLY_BASE_URL || "https://sendly.live";
+if (!API_KEY) {
+  process.stderr.write(
+    "SENDLY_API_KEY environment variable is required.\nGet your API key at https://sendly.live \u2192 Settings \u2192 API Keys\n"
+  );
+  process.exit(1);
+}
+async function api(method, path, body, query) {
+  const url = new URL(`/api/v1${path}`, BASE_URL);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0) url.searchParams.set(k, v);
+    }
+  }
+  const headers = {
+    Authorization: `Bearer ${API_KEY}`
+  };
+  if (body) headers["Content-Type"] = "application/json";
+  const res = await fetch(url.toString(), {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : void 0
+  });
+  if (res.status === 204) return { success: true };
+  const data = await res.json();
+  if (!res.ok) {
+    const msg = typeof data === "object" && data !== null ? data.error || data.message || JSON.stringify(data) : String(data);
+    throw new Error(String(msg));
+  }
+  return data;
+}
+function ok(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function err(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    isError: true
+  };
+}
+var server = new McpServer({
+  name: "sendly",
+  version: "1.0.0"
+});
+server.tool(
+  "send_sms",
+  "Send an SMS message to a phone number. Returns the message with delivery status. Use 'transactional' for alerts/OTP (bypasses quiet hours), 'marketing' for promotions.",
+  {
+    to: z.string().describe("Recipient phone number in E.164 format (+14155551234)"),
+    text: z.string().describe("Message text content"),
+    messageType: z.enum(["marketing", "transactional"]).optional().describe("Message type (default: marketing)"),
+    metadata: z.record(z.string(), z.any()).optional().describe("Custom key-value metadata to attach")
+  },
+  async ({ to, text, messageType, metadata }) => {
+    try {
+      const body = { to, text };
+      if (messageType) body.messageType = messageType;
+      if (metadata) body.metadata = metadata;
+      return ok(await api("POST", "/messages", body));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "list_messages",
+  "List sent and received SMS messages with pagination, ordered by creation date.",
+  {
+    limit: z.number().optional().describe("Messages to return (1-100, default 50)"),
+    offset: z.number().optional().describe("Pagination offset"),
+    status: z.enum(["queued", "sent", "delivered", "failed"]).optional().describe("Filter by delivery status")
+  },
+  async ({ limit, offset, status }) => {
+    try {
+      return ok(
+        await api("GET", "/messages", void 0, {
+          limit: limit?.toString(),
+          offset: offset?.toString(),
+          status
+        })
+      );
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "get_message",
+  "Get details of a specific SMS message including delivery status, timestamps, and metadata.",
+  {
+    messageId: z.string().describe("The message ID")
+  },
+  async ({ messageId }) => {
+    try {
+      return ok(await api("GET", `/messages/${messageId}`));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "schedule_sms",
+  "Schedule an SMS for future delivery (5 minutes to 5 days from now). Credits are reserved immediately and refunded if cancelled.",
+  {
+    to: z.string().describe("Recipient phone number in E.164 format"),
+    text: z.string().describe("Message text content"),
+    scheduledAt: z.string().describe("ISO 8601 datetime for delivery (e.g., 2026-03-16T09:00:00Z)"),
+    messageType: z.enum(["marketing", "transactional"]).optional().describe("Message type (default: marketing)")
+  },
+  async ({ to, text, scheduledAt, messageType }) => {
+    try {
+      const body = { to, text, scheduledAt };
+      if (messageType) body.messageType = messageType;
+      return ok(await api("POST", "/messages/schedule", body));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "cancel_scheduled_message",
+  "Cancel a scheduled message before it sends. Credits are refunded automatically.",
+  {
+    messageId: z.string().describe("The scheduled message ID to cancel")
+  },
+  async ({ messageId }) => {
+    try {
+      return ok(await api("DELETE", `/messages/scheduled/${messageId}`));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "list_conversations",
+  "List SMS conversation threads ordered by most recent activity. Each conversation groups all messages with a specific phone number.",
+  {
+    limit: z.number().optional().describe("Conversations to return (1-100, default 50)"),
+    offset: z.number().optional().describe("Pagination offset"),
+    status: z.enum(["active", "closed"]).optional().describe("Filter by conversation status")
+  },
+  async ({ limit, offset, status }) => {
+    try {
+      return ok(
+        await api("GET", "/conversations", void 0, {
+          limit: limit?.toString(),
+          offset: offset?.toString(),
+          status
+        })
+      );
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "get_conversation",
+  "Get a conversation thread by ID. Set includeMessages=true to load the message history.",
+  {
+    conversationId: z.string().describe("The conversation ID"),
+    includeMessages: z.boolean().optional().describe("Include message history (default false)"),
+    messageLimit: z.number().optional().describe("Number of messages to include (default 50)")
+  },
+  async ({ conversationId, includeMessages, messageLimit }) => {
+    try {
+      return ok(
+        await api("GET", `/conversations/${conversationId}`, void 0, {
+          include_messages: includeMessages ? "true" : void 0,
+          message_limit: messageLimit?.toString()
+        })
+      );
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "reply_to_conversation",
+  "Send a reply within an existing conversation. The recipient is automatically set from the conversation's phone number.",
+  {
+    conversationId: z.string().describe("The conversation ID to reply in"),
+    text: z.string().describe("Reply message text"),
+    mediaUrls: z.array(z.string()).optional().describe("Media URLs for MMS")
+  },
+  async ({ conversationId, text, mediaUrls }) => {
+    try {
+      const body = { text };
+      if (mediaUrls?.length) body.mediaUrls = mediaUrls;
+      return ok(
+        await api("POST", `/conversations/${conversationId}/messages`, body)
+      );
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "update_conversation",
+  "Update a conversation's metadata or tags. Use metadata for custom key-value data, tags for categorization.",
+  {
+    conversationId: z.string().describe("The conversation ID"),
+    metadata: z.record(z.string(), z.any()).optional().describe("Custom key-value metadata"),
+    tags: z.array(z.string()).optional().describe("Tags for categorization (replaces existing tags)")
+  },
+  async ({ conversationId, metadata, tags }) => {
+    try {
+      const body = {};
+      if (metadata) body.metadata = metadata;
+      if (tags) body.tags = tags;
+      return ok(await api("PATCH", `/conversations/${conversationId}`, body));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "close_conversation",
+  "Close a conversation. Closed conversations auto-reopen when a new inbound message arrives.",
+  {
+    conversationId: z.string().describe("The conversation ID to close")
+  },
+  async ({ conversationId }) => {
+    try {
+      return ok(await api("POST", `/conversations/${conversationId}/close`));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "reopen_conversation",
+  "Reopen a previously closed conversation, setting its status back to active.",
+  {
+    conversationId: z.string().describe("The conversation ID to reopen")
+  },
+  async ({ conversationId }) => {
+    try {
+      return ok(await api("POST", `/conversations/${conversationId}/reopen`));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "mark_conversation_read",
+  "Mark a conversation as read, resetting the unread count to zero.",
+  {
+    conversationId: z.string().describe("The conversation ID")
+  },
+  async ({ conversationId }) => {
+    try {
+      return ok(
+        await api("POST", `/conversations/${conversationId}/mark-read`)
+      );
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "send_otp",
+  "Send an OTP verification code via SMS. Use for phone verification, 2FA, or identity confirmation. Returns a verification ID to check the code against. In sandbox mode (test API key), the code is returned in the response for testing.",
+  {
+    to: z.string().describe("Phone number to verify in E.164 format"),
+    appName: z.string().optional().describe("Your app/brand name shown in the SMS"),
+    codeLength: z.number().optional().describe("Digits in the code (default 6)"),
+    timeoutSecs: z.number().optional().describe("Code validity in seconds (default 300)")
+  },
+  async ({ to, appName, codeLength, timeoutSecs }) => {
+    try {
+      const body = { to };
+      if (appName) body.appName = appName;
+      if (codeLength) body.codeLength = codeLength;
+      if (timeoutSecs) body.timeoutSecs = timeoutSecs;
+      return ok(await api("POST", "/verify", body));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "check_otp",
+  "Verify an OTP code. Returns the verification status: 'verified' (correct), 'invalid_code' (wrong code, shows remaining attempts), 'expired', or 'max_attempts_exceeded'.",
+  {
+    verificationId: z.string().describe("The verification ID from send_otp"),
+    code: z.string().describe("The code entered by the user")
+  },
+  async ({ verificationId, code }) => {
+    try {
+      return ok(await api("POST", `/verify/${verificationId}/check`, { code }));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "get_verification_status",
+  "Check the current status of an OTP verification (pending, verified, expired, failed).",
+  {
+    verificationId: z.string().describe("The verification ID")
+  },
+  async ({ verificationId }) => {
+    try {
+      return ok(await api("GET", `/verify/${verificationId}`));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+server.tool(
+  "get_account",
+  "Get account info: credit balance, phone number verification status, rate limits, and API key details. Check this to understand available credits and sending capabilities.",
+  {},
+  async () => {
+    try {
+      return ok(await api("GET", "/account"));
+    } catch (e) {
+      return err(e);
+    }
+  }
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sendly/mcp",
+  "version": "1.0.0",
+  "description": "Sendly MCP Server — SMS for AI agents. Send messages, manage conversations, verify phone numbers.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "sendly-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sendly",
+    "sms",
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "messaging",
+    "otp",
+    "verification"
+  ],
+  "author": "Sendly <support@sendly.live>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SendlyHQ/sendly-mcp.git"
+  },
+  "homepage": "https://sendly.live/docs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}