engagelab-sms-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevEngageLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# engagelab-sms-mcp
+
+An [MCP](https://modelcontextprotocol.io/) server that lets AI assistants send SMS messages through [EngageLab](https://www.engagelab.com/).
+
+Add it to your MCP client (Cursor, Claude Desktop, etc.) and the AI can send template-based SMS on your behalf.
+
+## Prerequisites
+
+- Node.js 18+
+- An EngageLab account with SMS API credentials (`dev_key` and `dev_secret`)
+- At least one approved SMS template in your EngageLab console
+
+## Quick Start
+
+### Cursor
+
+Go to **Settings > MCP**, click **Add new MCP server**, and paste:
+
+```json
+{
+  "mcpServers": {
+    "engagelab-sms": {
+      "command": "npx",
+      "args": ["-y", "engagelab-sms-mcp"],
+      "env": {
+        "ENGAGELAB_DEV_KEY": "<your_dev_key>",
+        "ENGAGELAB_DEV_SECRET": "<your_dev_secret>"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Open **Settings > Developer > Edit Config** and add to `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "engagelab-sms": {
+      "command": "npx",
+      "args": ["-y", "engagelab-sms-mcp"],
+      "env": {
+        "ENGAGELAB_DEV_KEY": "<your_dev_key>",
+        "ENGAGELAB_DEV_SECRET": "<your_dev_secret>"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+Any MCP client that supports `stdio` transport can use this server. Point the command to `npx -y engagelab-sms-mcp` and pass the two required environment variables.
+
+## Available Tools
+
+### `send_sms`
+
+Send SMS messages through EngageLab using a pre-approved template.
+
+**Input:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `to` | `string[]` | Yes | Target phone numbers (international format recommended, e.g. `+8618700001111`) |
+| `template.id` | `string` | Yes | Approved EngageLab SMS template ID |
+| `template.params` | `object` | Yes | Template variable values, e.g. `{"code": "123456"}` |
+
+**Example input:**
+
+```json
+{
+  "to": ["+8618700001111"],
+  "template": {
+    "id": "your-template-id",
+    "params": {
+      "code": "123456"
+    }
+  }
+}
+```
+
+**Output:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | `boolean` | Whether the request was accepted |
+| `plan_id` | `string` | EngageLab plan ID for tracking |
+| `total_count` | `number` | Total recipients submitted |
+| `accepted_count` | `number` | Recipients accepted for delivery |
+| `message_id` | `string` | Message identifier (if available) |
+| `message` | `string` | Status or error description |
+| `code` | `number` | EngageLab response code (`0` = success) |
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `ENGAGELAB_DEV_KEY` | Yes | — | Your EngageLab dev key |
+| `ENGAGELAB_DEV_SECRET` | Yes | — | Your EngageLab dev secret |
+| `ENGAGELAB_BASE_URL` | No | `https://smsapi.engagelab.com` | API base URL |
+| `ENGAGELAB_REQUEST_TIMEOUT_MS` | No | `10000` | Request timeout in milliseconds |
+| `ENGAGELAB_MAX_RETRIES` | No | `1` | Max retry attempts for transient failures |
+
+## Troubleshooting
+
+**Server fails to start with "Missing required environment variable"**
+- Make sure both `ENGAGELAB_DEV_KEY` and `ENGAGELAB_DEV_SECRET` are set in the `env` block of your MCP client config.
+
+**`send_sms` returns error code 3002 ("invalid template id format")**
+- Check that your template ID matches an approved template in the EngageLab console.
+
+**`send_sms` returns error code related to template params**
+- Verify that `template.params` keys match the variable names defined in your EngageLab template.
+
+**SMS not received**
+- Use international phone number format (e.g. `+8618700001111`).
+- Confirm the template is approved and not suspended.
+
+## Links
+
+- [EngageLab SMS API Documentation](https://www.engagelab.com/docs/NEWSMS/REST-API/API-SMS-Sending)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+
+## License
+
+MIT

package/build/config.js

@@ -0,0 +1,35 @@
+const DEFAULT_BASE_URL = "https://smsapi.engagelab.com";
+const DEFAULT_TIMEOUT_MS = 10000;
+const DEFAULT_MAX_RETRIES = 1;
+function getRequiredEnv(name) {
+    const value = process.env[name];
+    if (!value || value.trim().length === 0) {
+        throw new Error(`Missing required environment variable ${name}. ` +
+            "Please set ENGAGELAB_DEV_KEY and ENGAGELAB_DEV_SECRET before starting the MCP server.");
+    }
+    return value.trim();
+}
+function parsePositiveInt(value, defaultValue) {
+    if (!value || value.trim().length === 0) {
+        return defaultValue;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`Invalid numeric environment variable value: ${value}`);
+    }
+    return parsed;
+}
+export function loadConfig() {
+    const devKey = getRequiredEnv("ENGAGELAB_DEV_KEY");
+    const devSecret = getRequiredEnv("ENGAGELAB_DEV_SECRET");
+    const baseUrl = (process.env.ENGAGELAB_BASE_URL ?? DEFAULT_BASE_URL).trim();
+    const requestTimeoutMs = parsePositiveInt(process.env.ENGAGELAB_REQUEST_TIMEOUT_MS, DEFAULT_TIMEOUT_MS);
+    const maxRetries = parsePositiveInt(process.env.ENGAGELAB_MAX_RETRIES, DEFAULT_MAX_RETRIES);
+    return {
+        baseUrl,
+        devKey,
+        devSecret,
+        requestTimeoutMs,
+        maxRetries,
+    };
+}

package/build/engagelab/client.js

@@ -0,0 +1,199 @@
+export class EngageLabApiError extends Error {
+    retriable;
+    statusCode;
+    apiCode;
+    apiMessage;
+    apiResponse;
+    constructor(args) {
+        super(args.message);
+        this.name = "EngageLabApiError";
+        this.retriable = args.retriable;
+        this.statusCode = args.statusCode;
+        this.apiCode = args.apiCode;
+        this.apiMessage = args.apiMessage;
+        this.apiResponse = args.apiResponse;
+    }
+}
+function buildAuthHeader(devKey, devSecret) {
+    return `Basic ${Buffer.from(`${devKey}:${devSecret}`).toString("base64")}`;
+}
+function toErrorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return "Unknown error";
+}
+function isRetriableStatus(status) {
+    return status === 429 || status >= 500;
+}
+function getRetryBackoffMs(attempt) {
+    return 300 * Math.pow(2, attempt);
+}
+async function sleep(ms) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new EngageLabApiError({
+                message: `Request timed out after ${timeoutMs}ms.`,
+                retriable: true,
+            });
+        }
+        throw new EngageLabApiError({
+            message: `Network request failed: ${toErrorMessage(error)}`,
+            retriable: true,
+        });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function tryParseJson(response) {
+    const rawBody = await response.text();
+    if (!rawBody) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(rawBody);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readApiMessage(value) {
+    if (typeof value.message === "string" && value.message.trim().length > 0) {
+        return value.message;
+    }
+    return undefined;
+}
+function readApiCode(value) {
+    if (typeof value.code === "number") {
+        return value.code;
+    }
+    return undefined;
+}
+function buildOptionalApiResponse(value) {
+    if (typeof value.plan_id === "string" &&
+        typeof value.total_count === "number" &&
+        typeof value.accepted_count === "number") {
+        return {
+            plan_id: value.plan_id,
+            total_count: value.total_count,
+            accepted_count: value.accepted_count,
+            message: typeof value.message === "string" ? value.message : undefined,
+            code: typeof value.code === "number" ? value.code : undefined,
+        };
+    }
+    return undefined;
+}
+function parseSendSmsSuccess(data) {
+    if (!data || typeof data !== "object") {
+        return undefined;
+    }
+    const raw = data;
+    if (typeof raw.plan_id !== "string" ||
+        typeof raw.total_count !== "number" ||
+        typeof raw.accepted_count !== "number") {
+        return undefined;
+    }
+    return {
+        plan_id: raw.plan_id,
+        total_count: raw.total_count,
+        accepted_count: raw.accepted_count,
+        message_id: typeof raw.message_id === "string" ? raw.message_id : undefined,
+        message: typeof raw.message === "string" ? raw.message : undefined,
+        code: typeof raw.code === "number" ? raw.code : undefined,
+    };
+}
+function buildHttpError(statusCode, parsedBody) {
+    let apiMessage;
+    let apiCode;
+    let apiResponse;
+    if (parsedBody && typeof parsedBody === "object") {
+        const body = parsedBody;
+        apiMessage = readApiMessage(body);
+        apiCode = readApiCode(body);
+        apiResponse = buildOptionalApiResponse(body);
+    }
+    const baseMessage = `EngageLab API request failed with HTTP ${statusCode}.`;
+    const message = apiMessage ? `${baseMessage} ${apiMessage}` : baseMessage;
+    return new EngageLabApiError({
+        message,
+        retriable: isRetriableStatus(statusCode),
+        statusCode,
+        apiCode,
+        apiMessage,
+        apiResponse,
+    });
+}
+function buildApiError(response) {
+    const message = response.message && response.message.length > 0
+        ? `EngageLab API business error: ${response.message}`
+        : "EngageLab API business error.";
+    return new EngageLabApiError({
+        message,
+        retriable: false,
+        statusCode: 200,
+        apiCode: response.code,
+        apiMessage: response.message,
+        apiResponse: response,
+    });
+}
+export async function sendSms(config, payload) {
+    const endpoint = new URL("/v1/messages", config.baseUrl).toString();
+    const authHeader = buildAuthHeader(config.devKey, config.devSecret);
+    for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
+        try {
+            const response = await fetchWithTimeout(endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: authHeader,
+                },
+                body: JSON.stringify(payload),
+            }, config.requestTimeoutMs);
+            const parsedBody = await tryParseJson(response);
+            if (!response.ok) {
+                throw buildHttpError(response.status, parsedBody);
+            }
+            const parsedSuccess = parseSendSmsSuccess(parsedBody);
+            if (!parsedSuccess) {
+                throw new EngageLabApiError({
+                    message: "EngageLab API returned an unexpected response shape.",
+                    retriable: false,
+                    statusCode: response.status,
+                });
+            }
+            if (typeof parsedSuccess.code === "number" && parsedSuccess.code !== 0) {
+                throw buildApiError(parsedSuccess);
+            }
+            return parsedSuccess;
+        }
+        catch (error) {
+            const normalized = error instanceof EngageLabApiError
+                ? error
+                : new EngageLabApiError({
+                    message: `Unexpected error while calling EngageLab API: ${toErrorMessage(error)}`,
+                    retriable: false,
+                });
+            const canRetry = normalized.retriable && attempt < config.maxRetries;
+            if (canRetry) {
+                await sleep(getRetryBackoffMs(attempt));
+                continue;
+            }
+            throw normalized;
+        }
+    }
+    throw new EngageLabApiError({
+        message: "Failed to call EngageLab API after retries.",
+        retriable: false,
+    });
+}

package/build/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { registerSendSmsTool } from "./tools/send-sms.js";
+const server = new McpServer({
+    name: "engagelab-sms-mcp",
+    version: "1.0.0",
+});
+const config = loadConfig();
+registerSendSmsTool(server, config);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("engagelab-sms-mcp is running on stdio");
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown startup error";
+    console.error(`Fatal error in main(): ${message}`);
+    process.exit(1);
+});

package/build/test-client.js

@@ -0,0 +1,77 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+function getServerScriptPath() {
+    return path.resolve(process.cwd(), "build", "index.js");
+}
+async function assertBuildExists(serverScriptPath) {
+    try {
+        await access(serverScriptPath);
+    }
+    catch {
+        throw new Error(`Cannot find built MCP server at ${serverScriptPath}. Run "npm run build" first.`);
+    }
+}
+function readPayloadFromEnv() {
+    const raw = process.env.SMS_TEST_PAYLOAD;
+    if (!raw || raw.trim().length === 0) {
+        throw new Error("SMS_TEST_PAYLOAD is required for --call mode. " +
+            'Example: {"to":["+8618701235678"],"template":{"id":"tpl-id","params":{"code":"123456"}}}');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("SMS_TEST_PAYLOAD is not valid JSON.");
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("SMS_TEST_PAYLOAD must be a JSON object.");
+    }
+    return parsed;
+}
+async function main() {
+    const serverScriptPath = getServerScriptPath();
+    await assertBuildExists(serverScriptPath);
+    const shouldCall = process.argv.includes("--call");
+    const childEnv = {
+        ...process.env,
+        ENGAGELAB_DEV_KEY: process.env.ENGAGELAB_DEV_KEY ?? "test_key_for_list_mode",
+        ENGAGELAB_DEV_SECRET: process.env.ENGAGELAB_DEV_SECRET ?? "test_secret_for_list_mode",
+    };
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [serverScriptPath],
+        env: childEnv,
+    });
+    const client = new Client({
+        name: "engagelab-sms-mcp-test-client",
+        version: "1.0.0",
+    });
+    try {
+        await client.connect(transport);
+        const listResult = await client.listTools();
+        const toolNames = listResult.tools.map((tool) => tool.name);
+        console.log("Connected. Tools:", toolNames);
+        if (!shouldCall) {
+            console.log('List-only mode complete. Use "--call" to invoke send_sms.');
+            return;
+        }
+        const payload = readPayloadFromEnv();
+        const callResult = await client.callTool({
+            name: "send_sms",
+            arguments: payload,
+        });
+        console.log("send_sms result:");
+        console.log(JSON.stringify(callResult, null, 2));
+    }
+    finally {
+        await client.close();
+    }
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    console.error(`Test client failed: ${message}`);
+    process.exit(1);
+});

package/build/tools/send-sms.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { EngageLabApiError, sendSms } from "../engagelab/client.js";
+const sendSmsInputSchema = z.object({
+    to: z
+        .array(z.string().trim().min(1).describe("Phone number in international format."))
+        .min(1)
+        .describe("Target phone numbers."),
+    template: z.object({
+        id: z.string().trim().min(1).describe("Approved EngageLab SMS template ID."),
+        params: z
+            .record(z.union([z.string(), z.number(), z.boolean()]))
+            .describe("Template variable assignments, e.g. {\"name\":\"Bob\"}."),
+    }),
+});
+const sendSmsOutputSchema = z.object({
+    success: z.boolean(),
+    plan_id: z.string().optional(),
+    total_count: z.number().optional(),
+    accepted_count: z.number().optional(),
+    message_id: z.string().optional(),
+    message: z.string().optional(),
+    code: z.number().optional(),
+});
+function toErrorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return "Unknown error";
+}
+export function registerSendSmsTool(server, config) {
+    server.registerTool("send_sms", {
+        title: "Send SMS",
+        description: "Send SMS through EngageLab using a template. Requires ENGAGELAB_DEV_KEY and ENGAGELAB_DEV_SECRET environment variables.",
+        inputSchema: sendSmsInputSchema,
+        outputSchema: sendSmsOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ to, template }) => {
+        try {
+            const response = await sendSms(config, { to, template });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `SMS request accepted. plan_id=${response.plan_id}, accepted_count=${response.accepted_count}/${response.total_count}.`,
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    plan_id: response.plan_id,
+                    total_count: response.total_count,
+                    accepted_count: response.accepted_count,
+                    message_id: response.message_id,
+                    message: response.message,
+                    code: response.code,
+                },
+            };
+        }
+        catch (error) {
+            if (error instanceof EngageLabApiError) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: `send_sms failed: ${error.message}`,
+                        },
+                    ],
+                    structuredContent: {
+                        success: false,
+                        plan_id: error.apiResponse?.plan_id,
+                        total_count: error.apiResponse?.total_count,
+                        accepted_count: error.apiResponse?.accepted_count,
+                        message: error.apiMessage,
+                        code: error.apiCode,
+                    },
+                };
+            }
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `send_sms failed with an unexpected error: ${toErrorMessage(error)}`,
+                    },
+                ],
+                structuredContent: {
+                    success: false,
+                    message: toErrorMessage(error),
+                },
+            };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "engagelab-sms-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for sending SMS through EngageLab",
+  "main": "./build/index.js",
+  "type": "module",
+  "bin": {
+    "engagelab-sms-mcp": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test:mcp:list": "npm run build && node build/test-client.js",
+    "test:mcp:call": "npm run build && node build/test-client.js --call"
+  },
+  "files": [
+    "build"
+  ],
+  "keywords": [
+    "mcp",
+    "sms",
+    "engagelab",
+    "model-context-protocol"
+  ],
+  "author": "DevEngageLab",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DevEngageLab/engagelab-sms-mcp.git"
+  },
+  "homepage": "https://github.com/DevEngageLab/engagelab-sms-mcp",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  }
+}