supersendtx-mcp 0.6.30 → 0.6.34

package/README.md

@@ -1,6 +1,6 @@
 # supersendtx-mcp
 
-MCP server for [SuperSend TX](https://supersendtx.com) — send email and manage domains, webhooks, suppressions, and templates from Cursor, Claude Code, and other MCP clients.
+MCP server for [SuperSend TX](https://supersendtx.com) — send email and manage domains, webhooks, suppressions, and templates from Cursor, Claude Code, and other MCP clients, and talk to Ranla, the agent in the same account.
 
 **Install:** `npx -y supersendtx-mcp` · **Docs:** https://docs.supersendtx.com/ai/mcp
 
@@ -10,14 +10,14 @@ MCP server for [SuperSend TX](https://supersendtx.com) — send email and manage
 |------|---------------|------|
 | **stdio** (default) | `npx -y supersendtx-mcp` | `SUPERSENDTX_API_KEY=stx_…` or `rnl_…` |
 | **HTTP** (local) | `npx -y supersendtx-mcp --http --port 3000` | `Authorization: Bearer stx_…` or `rnl_…` on each request |
-| **HTTP** (hosted) | `https://mcp.supersendtx.com/mcp` | **OAuth** (recommended) or `Authorization: Bearer stx_…` or `rnl_…` |
+| **HTTP** (hosted) | `https://mcp.ranla.ai/mcp` | **OAuth** (default) or `Authorization: Bearer stx_…` or `rnl_…` |
 
-Optional: `SUPERSENDTX_API_URL` (e.g. `http://localhost:3003/api` for local API).
+Create API keys on the dashboard **API keys** page. `RANLA_API_KEY` works in place of `SUPERSENDTX_API_KEY`. Optional: `SUPERSENDTX_API_URL` sets the mail API base URL (default `https://api.supersendtx.com`). Over HTTP the server reads only the `Authorization` header.
 
 Local HTTP endpoint: `http://127.0.0.1:3000/mcp` · health: `GET /health`  
-Hosted health: `GET https://mcp.supersendtx.com/health`
+Hosted health: `GET https://mcp.ranla.ai/health`
 
-Hosted OAuth: add only `"url": "https://mcp.supersendtx.com/mcp"` — the client runs the browser consent flow. Bearer `stx_…` or `rnl_…` still works for advanced setups.
+Hosted OAuth: add only `"url": "https://mcp.ranla.ai/mcp"`. The client opens a browser to sign in on `app.ranla.ai`; click **Allow access**. `https://mcp.supersendtx.com/mcp` is the same server, and existing configs keep working. A Bearer key still works for advanced setups.
 
 ---
 
@@ -60,11 +60,25 @@ npx -y supersendtx-mcp --http --port 3000
 
 ### Cursor (hosted)
 
+OAuth (default) — no key in config:
+
+```json
+{
+  "mcpServers": {
+    "supersendtx": {
+      "url": "https://mcp.ranla.ai/mcp"
+    }
+  }
+}
+```
+
+Bearer (advanced):
+
 ```json
 {
   "mcpServers": {
     "supersendtx": {
-      "url": "https://mcp.supersendtx.com/mcp",
+      "url": "https://mcp.ranla.ai/mcp",
       "headers": {
         "Authorization": "Bearer stx_your_key_here"
       }
@@ -78,23 +92,62 @@ npx -y supersendtx-mcp --http --port 3000
 ## Claude Code
 
 ```bash
+# HTTP (hosted, OAuth — run /mcp in Claude Code to sign in)
+claude mcp add --transport http supersendtx https://mcp.ranla.ai/mcp
+
 # stdio
 claude mcp add --transport stdio supersendtx -- npx -y supersendtx-mcp
 
 # HTTP (local — after starting --http server)
-claude mcp add --transport http supersendtx http://127.0.0.1:3000/mcp
-
-# HTTP (hosted)
-claude mcp add --transport http supersendtx https://mcp.supersendtx.com/mcp
+claude mcp add --transport http supersendtx http://127.0.0.1:3000/mcp --header "Authorization: Bearer stx_your_key_here"
 ```
 
-Export `SUPERSENDTX_API_KEY` for stdio, or configure Bearer headers for HTTP.
+Export `SUPERSENDTX_API_KEY` for stdio.
 
 ---
 
 ## Tools
 
-See https://docs.supersendtx.com/ai/mcp — emails, domains, webhooks, suppressions, templates, deliverability, webhook test.
+### Mail tools
+
+These call the public API through the `supersendtx` SDK.
+
+| Tool | Purpose |
+|------|---------|
+| `send_email` | Send now, or later with `scheduled_at` |
+| `list_emails` / `get_email` | List or fetch sends |
+| `cancel_email` | Cancel a scheduled send |
+| `list_received_emails` / `get_received_email` | Inbound mail |
+| `list_domains` / `get_domain` / `create_domain` | Domains; `get_domain` returns DNS records |
+| `apply_domain_dns` / `verify_domain` | Apply DNS (`cloudflare`, `godaddy`, `vercel`) and verify |
+| `list_webhooks` / `create_webhook` / `delete_webhook` | Webhook endpoints |
+| `list_suppressions` / `add_suppression` / `remove_suppression` | Suppression list |
+| `list_templates` / `get_template` / `create_template` / `publish_template` | Templates |
+| `send_test_webhook_event` | Test webhook event (outbound email events) |
+| `get_deliverability` | Best-effort metrics (`7d` / `30d`) |
+
+`send_email` takes `from`, `to`, and either `subject` with `html` / `text` or `template_id` / `template_alias` with `variables`. Optional: `cc`, `bcc`, `reply_to`, `scheduled_at`, `category` (`transactional`, `product`, `newsletter`), `tags`, `headers`, `idempotency_key`, `unsubscribe`. Recipient fields take one address, several separated by commas, or an array.
+
+### Ranla agent tools
+
+These call the app host and need a full-access key (OAuth sign-in and dashboard keys have one; a `sending`-scope key gets a 403).
+
+| Tool | Purpose |
+|------|---------|
+| `arc_ensure_thread` / `arc_list_threads` | Durable thread for this client; list threads a page at a time |
+| `arc_get_thread` | Read a thread's messages, artifacts and waiting approvals |
+| `arc_message` | Send text to Ranla and wait for the turn — returns `text`, `artifacts`, and `pendingApproval` |
+| `arc_list_approvals` / `arc_approve` / `arc_reject` | Answer approvals |
+| `arc_request_connection` | Connect link for a missing integration |
+| `arc_<tool>` | Read-only Ranla tools, listed from the account with input schemas. Results say in `forCaller` when a step needs `arc_message` |
+
+Flow: `arc_ensure_thread` → `arc_message` → if a step needs approval, `arc_list_approvals` → `arc_approve` or `arc_reject`.
+
+An SEO page approval also carries `actionId`: pass it to `arc_seo_page_package` to read the draft, for example to build the page in your own repo.
+
+Every tool has a `title` and `readOnlyHint` / `destructiveHint` annotations, so clients can run reads without asking and confirm writes.
+
+Full reference: https://docs.supersendtx.com/ai/mcp
 
 ## License
 

package/dist/index.js

@@ -55,12 +55,13 @@ function printHelp() {
   supersendtx-mcp                  # stdio (default)
   supersendtx-mcp --http [--port 3000] [--host 127.0.0.1]
 
-Environment:
-  SUPERSENDTX_API_KEY   Required for stdio (Bearer stx_\u2026 or rnl_\u2026 for HTTP)
-  SUPERSENDTX_API_URL   Optional API base (default https://api.supersendtx.com)
+Environment (RANLA_* or SUPERSENDTX_*):
+  RANLA_API_KEY / SUPERSENDTX_API_KEY   API key (rnl_\u2026 or stx_\u2026), required for stdio
+  RANLA_API_URL / SUPERSENDTX_API_URL   Optional mail API base (ranla-mcp: https://api.ranla.ai)
+  RANLA_APP_URL / SUPERSENDTX_APP_URL   Optional app host for the Ranla agent tools
 
 HTTP auth:
-  Authorization: Bearer stx_\u2026 or rnl_\u2026 (API key) or MCP OAuth access token
+  Authorization: Bearer rnl_\u2026 or stx_\u2026 (API key) or MCP OAuth access token
 `);
 }
 function isSuperSendTxApiKey(token) {
@@ -82,14 +83,79 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { SuperSendTX } from "supersendtx";
 
+// package.json
+var version = "0.6.34";
+
+// src/annotations.ts
+var READ = { readOnlyHint: true };
+var WRITE = { readOnlyHint: false, destructiveHint: false };
+var DELETE = { readOnlyHint: false, destructiveHint: true };
+var FIXED_TOOL_HINTS = {
+  send_email: { ...WRITE, openWorldHint: true },
+  list_emails: READ,
+  get_email: READ,
+  cancel_email: DELETE,
+  list_received_emails: READ,
+  get_received_email: READ,
+  list_domains: READ,
+  get_domain: READ,
+  create_domain: WRITE,
+  apply_domain_dns: { ...WRITE, title: "Apply domain DNS records", openWorldHint: true },
+  verify_domain: { ...WRITE, idempotentHint: true },
+  list_webhooks: READ,
+  create_webhook: WRITE,
+  delete_webhook: DELETE,
+  list_suppressions: READ,
+  add_suppression: { ...WRITE, idempotentHint: true },
+  remove_suppression: DELETE,
+  list_templates: READ,
+  get_template: READ,
+  create_template: WRITE,
+  publish_template: WRITE,
+  send_test_webhook_event: { ...WRITE, openWorldHint: true },
+  get_deliverability: READ,
+  arc_list_threads: { ...READ, title: "List Ranla threads" },
+  arc_get_thread: { ...READ, title: "Read a Ranla thread" },
+  arc_ensure_thread: { ...WRITE, title: "Open a Ranla thread", idempotentHint: true },
+  arc_message: { ...WRITE, title: "Message Ranla" },
+  arc_list_approvals: { ...READ, title: "List pending approvals" },
+  /** Approving can send email to real people. */
+  arc_approve: { ...WRITE, title: "Approve a Ranla step", openWorldHint: true },
+  /** Rejecting discards the proposal. */
+  arc_reject: { ...DELETE, title: "Reject a Ranla step" }
+};
+var UPPER = /* @__PURE__ */ new Set(["ai", "aeo", "api", "dns", "id", "seo", "url"]);
+function titleFromToolName(name) {
+  const words = name.replace(/^arc_/, "").split("_").filter(Boolean);
+  return words.map((word, index) => {
+    if (UPPER.has(word)) return word.toUpperCase();
+    return index === 0 ? word.charAt(0).toUpperCase() + word.slice(1) : word;
+  }).join(" ");
+}
+function mcpToolAnnotations(tool) {
+  const fixed = FIXED_TOOL_HINTS[tool.name];
+  if (fixed) {
+    const { title: title2, ...hints } = fixed;
+    return { title: title2 ?? titleFromToolName(tool.name), ...hints };
+  }
+  const title = titleFromToolName(tool.name);
+  return tool.readOnly === true ? { title, ...READ } : { title, ...WRITE };
+}
+
 // src/arc-talk-tools.ts
 var ARC_MCP_TALK_GROWTH_TOOL_NAMES = [
   // Cold-start SEO plan: a minute of vendor data and a planning call. Read-only, so MCP carries it.
   "seo_plan",
-  "ask_choice",
   "get_business_brief",
   "get_brand",
   "read_url",
+  // A canvas document Ranla wrote, as it stands now. Writing to one mutates
+  // and goes through `arc_message` like every other write.
+  "read_canvas",
+  // The ids read_canvas takes; nothing else an external agent can call returns them.
+  "list_documents",
+  // Every image in the account, with public URLs an external agent can use as they are.
+  "list_library_images",
   "get_setup_status",
   "get_growth_health",
   "get_revenue_health",
@@ -101,6 +167,7 @@ var ARC_MCP_TALK_GROWTH_TOOL_NAMES = [
   "list_goals",
   "list_lists",
   "list_segments",
+  "get_segment",
   "get_tracking_snippet",
   "verify_tracking_install",
   "list_automations",
@@ -128,7 +195,6 @@ var ARC_MCP_TALK_GROWTH_TOOL_NAMES = [
   "get_ad_delivery_diagnostics",
   "get_search_term_evidence",
   "list_proposed_ad_campaigns",
-  "recommend_ad_landings",
   "read_campaign_design",
   "list_campaign_replies",
   "get_learnings",
@@ -186,9 +252,10 @@ var RANLA_AGENT_NAME = "Ranla";
 var TALK_READ_TOOLS = ARC_MCP_TALK_GROWTH_TOOL_NAMES.map((growthTool) => ({
   name: `arc_${growthTool}`,
   description: `Read-only Ranla tool: ${growthTool.replace(/_/g, " ")}.`,
-  inputSchema: openObjectSchema("Tool input fields (see Ranla tool docs)."),
+  inputSchema: openObjectSchema("Pass the tool arguments as fields."),
   kind: "growth",
-  growthTool
+  growthTool,
+  readOnly: true
 }));
 var SETUP_TOOLS = [
   {
@@ -203,14 +270,40 @@ var SETUP_TOOLS = [
       required: ["slot"]
     },
     kind: "growth",
-    growthTool: "request_connection"
+    growthTool: "request_connection",
+    readOnly: false
   }
 ];
 var META_TOOLS = [
   {
     name: "arc_list_threads",
-    description: "List Ranla chat threads for this account.",
-    inputSchema: openObjectSchema(),
+    description: "List Ranla chat threads for this account, most recent first: id, title, desk, last activity and a one-line preview. Pass nextBefore as before for older threads. Read one with arc_get_thread.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "integer", description: "Threads per page. Default 50, max 100." },
+        before: {
+          type: "string",
+          description: "ISO timestamp from nextBefore: only threads last active before it."
+        }
+      }
+    },
+    kind: "meta"
+  },
+  {
+    name: "arc_get_thread",
+    description: "Read a Ranla thread: its messages (role, text, tools used, artifacts by id, approvals waiting on arc_approve), newest page first. Pass earlierBefore as before for older messages.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        threadId: { type: "string", description: "From arc_list_threads or arc_ensure_thread." },
+        before: {
+          type: "string",
+          description: "ISO timestamp from earlierBefore: the page of messages older than it."
+        }
+      },
+      required: ["threadId"]
+    },
     kind: "meta"
   },
   {
@@ -227,7 +320,7 @@ var META_TOOLS = [
   },
   {
     name: "arc_message",
-    description: "Send a message to Ranla and wait for the turn. Use for strategy and any mutating work. Returns text plus pendingApproval when HITL is required.",
+    description: "Send a message to Ranla and wait for the turn. Use for strategy and anything that changes the account. Returns text, artifacts (drafts, plans, and documents it made or opened, by id), and pendingApproval when a step needs approval.",
     inputSchema: {
       type: "object",
       properties: {
@@ -240,13 +333,13 @@ var META_TOOLS = [
   },
   {
     name: "arc_list_approvals",
-    description: "List pending Ranla approval cards across threads.",
+    description: "List pending Ranla approvals across threads.",
     inputSchema: openObjectSchema(),
     kind: "meta"
   },
   {
     name: "arc_approve",
-    description: "Approve a pending Ranla HITL card and resume the run.",
+    description: "Approve a pending Ranla approval and resume the run.",
     inputSchema: {
       type: "object",
       properties: {
@@ -258,7 +351,7 @@ var META_TOOLS = [
   },
   {
     name: "arc_reject",
-    description: "Reject a pending Ranla HITL card and resume the run.",
+    description: "Reject a pending Ranla approval and resume the run.",
     inputSchema: {
       type: "object",
       properties: {
@@ -275,7 +368,7 @@ function resolveArcAppOrigin(options = {}) {
   if (fromEnv) return fromEnv.replace(/\/$/, "");
   const key = options.apiKey ?? process.env.SUPERSENDTX_API_KEY ?? process.env.RANLA_API_KEY ?? "";
   if (key.startsWith("rnl_")) return DEFAULT_RANLA_APP_ORIGIN;
-  const apiUrl = (options.baseUrl ?? process.env.SUPERSENDTX_API_URL ?? "").replace(/\/$/, "");
+  const apiUrl = (options.baseUrl ?? process.env.SUPERSENDTX_API_URL ?? process.env.RANLA_API_URL ?? "").replace(/\/$/, "");
   if (apiUrl.includes("api.ranla.ai")) return DEFAULT_RANLA_APP_ORIGIN;
   if (apiUrl.includes("app.ranla.ai")) return apiUrl;
   if (apiUrl.includes("app.supersendtx.com")) return apiUrl;
@@ -294,17 +387,57 @@ async function arcFetch(origin, apiKey, path, init = {}) {
   const body = await response.json().catch(() => ({}));
   return { ok: response.ok, status: response.status, body };
 }
+var ARC_TOOL_PREFIX = "arc_";
+var CATALOG_TIMEOUT_MS = 4e3;
+function isArcMcpToolName(name) {
+  return name.startsWith(ARC_TOOL_PREFIX);
+}
+function isCatalogEntry(value) {
+  if (!value || typeof value !== "object") return false;
+  const entry = value;
+  const schema = entry.inputSchema;
+  return typeof entry.name === "string" && /^[a-z0-9_]+$/.test(entry.name) && typeof entry.description === "string" && !!schema && typeof schema === "object" && schema.type === "object";
+}
+async function fetchGrowthToolCatalog(apiKey, baseUrl) {
+  try {
+    const origin = resolveArcAppOrigin({ baseUrl, apiKey });
+    const response = await arcFetch(origin, apiKey, "/api/growth/tools", {
+      signal: AbortSignal.timeout(CATALOG_TIMEOUT_MS)
+    });
+    if (!response.ok || !Array.isArray(response.body.tools)) return null;
+    const entries = response.body.tools.filter(isCatalogEntry);
+    return entries.length > 0 ? entries : null;
+  } catch {
+    return null;
+  }
+}
+async function loadArcMcpTools(apiKey, baseUrl) {
+  const catalog = await fetchGrowthToolCatalog(apiKey, baseUrl);
+  if (!catalog) return ARC_MCP_TOOLS;
+  return [
+    ...META_TOOLS,
+    ...catalog.map((entry) => ({
+      name: `${ARC_TOOL_PREFIX}${entry.name}`,
+      description: `${entry.mutates ? RANLA_AGENT_NAME : `${RANLA_AGENT_NAME}, read-only`}: ${entry.description}`,
+      inputSchema: entry.inputSchema,
+      kind: "growth",
+      growthTool: entry.name,
+      // Missing `mutates` is not a promise of read-only: only an explicit false is.
+      readOnly: entry.mutates === false
+    }))
+  ];
+}
 function optString(args, key) {
   if (args[key] == null) return void 0;
   const value = String(args[key]).trim();
   return value || void 0;
 }
 async function callArcMcpTool(apiKey, name, args, baseUrl) {
-  const def = ARC_MCP_TOOLS.find((tool) => tool.name === name);
-  if (!def) return null;
+  if (!isArcMcpToolName(name)) return null;
   const origin = resolveArcAppOrigin({ baseUrl, apiKey });
-  if (def.kind === "growth" && def.growthTool) {
-    const response = await arcFetch(origin, apiKey, `/api/growth/tools/${encodeURIComponent(def.growthTool)}`, {
+  if (!META_TOOLS.some((tool) => tool.name === name)) {
+    const growthTool = name.slice(ARC_TOOL_PREFIX.length);
+    const response = await arcFetch(origin, apiKey, `/api/growth/tools/${encodeURIComponent(growthTool)}`, {
       method: "POST",
       body: JSON.stringify({ input: args })
     });
@@ -317,7 +450,13 @@ async function callArcMcpTool(apiKey, name, args, baseUrl) {
   }
   switch (name) {
     case "arc_list_threads": {
-      const response = await arcFetch(origin, apiKey, "/api/growth/threads");
+      const query = new URLSearchParams();
+      const limit = optString(args, "limit");
+      const before = optString(args, "before");
+      if (limit) query.set("limit", limit);
+      if (before) query.set("before", before);
+      const suffix = query.toString() ? `?${query.toString()}` : "";
+      const response = await arcFetch(origin, apiKey, `/api/growth/threads${suffix}`);
       if (!response.ok) {
         throw new Error(
           typeof response.body.error === "string" ? response.body.error : `List threads failed (${response.status})`
@@ -325,6 +464,22 @@ async function callArcMcpTool(apiKey, name, args, baseUrl) {
       }
       return response.body;
     }
+    case "arc_get_thread": {
+      const threadId = optString(args, "threadId");
+      if (!threadId) throw new Error("Missing required argument: threadId");
+      const before = optString(args, "before");
+      const response = await arcFetch(
+        origin,
+        apiKey,
+        `/api/growth/threads/${encodeURIComponent(threadId)}${before ? `?before=${encodeURIComponent(before)}` : ""}`
+      );
+      if (!response.ok) {
+        throw new Error(
+          typeof response.body.error === "string" ? response.body.error : `Get thread failed (${response.status})`
+        );
+      }
+      return response.body;
+    }
     case "arc_ensure_thread": {
       const existingId = optString(args, "threadId");
       if (existingId) {
@@ -456,23 +611,46 @@ function optStringArray(args, key) {
   if (Array.isArray(value)) return value.map((v) => String(v));
   return void 0;
 }
-var EMAIL_WEBHOOK_EVENTS = /* @__PURE__ */ new Set([
-  "email.received",
-  "email.sent",
-  "email.delivered",
-  "email.delivery_delayed",
-  "email.bounced",
-  "email.complained",
-  "email.opened",
-  "email.clicked",
-  "email.failed",
-  "email.suppressed",
-  "email.scheduled"
-]);
+function optRecipients(args, key) {
+  const value = args[key];
+  if (value == null) return void 0;
+  const parts = (Array.isArray(value) ? value.map((entry) => String(entry)) : String(value).split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/)).map((entry) => entry.trim()).filter(Boolean);
+  if (parts.length === 0) return void 0;
+  return parts.length === 1 ? parts[0] : parts;
+}
+function optStringMap(args, key) {
+  const value = args[key];
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const entries = Object.entries(value).filter(([, entry]) => entry != null);
+  return entries.length > 0 ? Object.fromEntries(entries.map(([name, entry]) => [name, String(entry)])) : void 0;
+}
+var TEST_WEBHOOK_EVENT_FLAGS = {
+  "email.sent": true,
+  "email.delivered": true,
+  "email.delivery_delayed": true,
+  "email.bounced": true,
+  "email.complained": true,
+  "email.opened": true,
+  "email.clicked": true,
+  "email.failed": true,
+  "email.suppressed": true,
+  "email.scheduled": true
+};
+var TEST_WEBHOOK_EVENTS = new Set(Object.keys(TEST_WEBHOOK_EVENT_FLAGS));
+var WEBHOOK_EVENT_FLAGS = {
+  ...TEST_WEBHOOK_EVENT_FLAGS,
+  "email.received": true,
+  "contact.unsubscribed": true,
+  "automation.started": true,
+  "automation.step_completed": true,
+  "automation.completed": true,
+  "automation.failed": true
+};
+var WEBHOOK_EVENTS = Object.keys(WEBHOOK_EVENT_FLAGS);
+var EMAIL_CATEGORIES = ["transactional", "product", "newsletter"];
 async function callMcpTool(client, name, args, options = {}) {
   try {
-    const arc = ARC_MCP_TOOLS.find((tool) => tool.name === name);
-    if (arc) {
+    if (isArcMcpToolName(name)) {
       const apiKey = options.apiKey ?? resolveApiKey();
       const result = await callArcMcpTool(apiKey, name, args, options.baseUrl);
       return textResult(result);
@@ -480,7 +658,7 @@ async function callMcpTool(client, name, args, options = {}) {
     switch (name) {
       case "send_email": {
         const from = optString2(args, "from");
-        const to = optString2(args, "to");
+        const to = optRecipients(args, "to");
         const subject = optString2(args, "subject");
         const templateId = optString2(args, "template_id") || optString2(args, "template_alias");
         if (!from) return textResult("Missing required argument: from", true);
@@ -488,14 +666,33 @@ async function callMcpTool(client, name, args, options = {}) {
         if (!templateId && !subject) {
           return textResult("Provide subject, or template_id / template_alias", true);
         }
+        const category = optString2(args, "category");
+        if (category && !EMAIL_CATEGORIES.includes(category)) {
+          return textResult(`Invalid category. Use one of: ${EMAIL_CATEGORIES.join(", ")}`, true);
+        }
         const variables = args.variables && typeof args.variables === "object" && !Array.isArray(args.variables) ? args.variables : void 0;
+        const cc = optRecipients(args, "cc");
+        const bcc = optRecipients(args, "bcc");
+        const tags = optStringMap(args, "tags");
+        const headers = optStringMap(args, "headers");
+        const scheduledAt = optString2(args, "scheduled_at");
+        const idempotencyKey = optString2(args, "idempotency_key");
+        const unsubscribe = optBoolean(args, "unsubscribe");
         const result = await client.emails.send({
           from,
           to,
           ...subject ? { subject } : {},
           html: optString2(args, "html"),
           text: optString2(args, "text"),
-          reply_to: optString2(args, "reply_to"),
+          reply_to: optRecipients(args, "reply_to"),
+          ...cc ? { cc } : {},
+          ...bcc ? { bcc } : {},
+          ...tags ? { tags } : {},
+          ...headers ? { headers } : {},
+          ...scheduledAt ? { scheduled_at: scheduledAt } : {},
+          ...category ? { category } : {},
+          ...unsubscribe !== void 0 ? { unsubscribe } : {},
+          ...idempotencyKey ? { idempotencyKey } : {},
           ...templateId ? { template: { id: templateId, ...variables ? { variables } : {} } } : {}
         });
         return textResult(result);
@@ -512,6 +709,30 @@ async function callMcpTool(client, name, args, options = {}) {
         if (!id) return textResult("Missing required argument: id", true);
         return textResult(await client.emails.get(id));
       }
+      case "cancel_email": {
+        const id = optString2(args, "id");
+        if (!id) return textResult("Missing required argument: id", true);
+        return textResult(await client.emails.cancel(id));
+      }
+      case "list_received_emails": {
+        return textResult(
+          await client.receivedEmails.list({
+            limit: optNumber(args, "limit"),
+            cursor: optString2(args, "cursor"),
+            domain: optString2(args, "domain")
+          })
+        );
+      }
+      case "get_received_email": {
+        const id = optString2(args, "id");
+        if (!id) return textResult("Missing required argument: id", true);
+        return textResult(await client.receivedEmails.get(id));
+      }
+      case "get_domain": {
+        const domain = optString2(args, "domain");
+        if (!domain) return textResult("Missing required argument: domain", true);
+        return textResult(await client.domains.get(domain));
+      }
       case "apply_domain_dns": {
         const domain = String(args.domain ?? "").trim();
         if (!domain) {
@@ -538,9 +759,11 @@ async function callMcpTool(client, name, args, options = {}) {
         return textResult(result);
       }
       case "list_domains": {
+        const inbound = optBoolean(args, "inbound_enabled");
         const result = await client.domains.list({
           limit: optNumber(args, "limit"),
-          cursor: optString2(args, "cursor")
+          cursor: optString2(args, "cursor"),
+          ...inbound !== void 0 ? { inbound_enabled: inbound } : {}
         });
         return textResult(result);
       }
@@ -567,6 +790,10 @@ async function callMcpTool(client, name, args, options = {}) {
         const url = optString2(args, "url");
         if (!url) return textResult("Missing required argument: url", true);
         const events = optStringArray(args, "events");
+        const unknown = events?.filter((event) => !WEBHOOK_EVENTS.includes(event)) ?? [];
+        if (unknown.length > 0) {
+          return textResult(`Unknown event types: ${unknown.join(", ")}. Use: ${WEBHOOK_EVENTS.join(", ")}`, true);
+        }
         return textResult(
           await client.webhooks.create({
             url,
@@ -624,12 +851,12 @@ async function callMcpTool(client, name, args, options = {}) {
         const name2 = optString2(args, "name");
         const subjectArg = optString2(args, "subject");
         if (!name2) return textResult("Missing required argument: name", true);
-        if (!subjectArg) return textResult("Missing required argument: subject", true);
         const format = optString2(args, "format");
         return textResult(
           await client.templates.create({
             name: name2,
-            subject: subjectArg,
+            // Optional: a layout-only template has no default subject.
+            ...subjectArg ? { subject: subjectArg } : {},
             ...format === "blocks" || format === "html" ? { format } : {},
             html: optString2(args, "html"),
             text: optString2(args, "text"),
@@ -640,13 +867,14 @@ async function callMcpTool(client, name, args, options = {}) {
       case "publish_template": {
         const idOrAlias = optString2(args, "id") ?? optString2(args, "alias");
         if (!idOrAlias) return textResult("Missing required argument: id or alias", true);
-        return textResult(await client.templates.publish(idOrAlias));
+        const label = optString2(args, "label");
+        return textResult(await client.templates.publish(idOrAlias, label ? { label } : {}));
       }
       case "send_test_webhook_event": {
         const event = optString2(args, "event");
-        if (!event || !EMAIL_WEBHOOK_EVENTS.has(event)) {
+        if (!event || !TEST_WEBHOOK_EVENTS.has(event)) {
           return textResult(
-            `Missing or invalid event. Use one of: ${[...EMAIL_WEBHOOK_EVENTS].join(", ")}`,
+            `Missing or invalid event. Use one of: ${[...TEST_WEBHOOK_EVENTS].join(", ")}`,
             true
           );
         }
@@ -654,6 +882,7 @@ async function callMcpTool(client, name, args, options = {}) {
           await client.emails.testWebhook({
             event,
             email_id: optString2(args, "email_id"),
+            webhook_id: optString2(args, "webhook_id"),
             deliver: optBoolean(args, "deliver")
           })
         );
@@ -675,26 +904,56 @@ var paginationProps = {
   limit: { type: "number", description: "Page size (1\u2013100)" },
   cursor: { type: "string", description: "Opaque cursor for the next page" }
 };
+var recipientProp = (what) => ({
+  description: `${what}: one address, several separated by commas, or an array of addresses`,
+  anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }]
+});
 var MCP_TOOLS = [
   {
     name: "send_email",
-    description: "Send a transactional email via SuperSend TX. Provide subject + html/text, or a published template_id / template_alias with optional variables.",
+    description: "Send an email. Provide subject + html/text, or a published template_id / template_alias with optional variables. Set scheduled_at to send later (cancel with cancel_email).",
     inputSchema: {
       type: "object",
       properties: {
-        from: { type: "string", description: "Sender address (must match a verified domain or sandbox sender)" },
-        to: { type: "string", description: "Recipient email address" },
+        from: {
+          type: "string",
+          description: "Sender address on a verified domain (or `Name <address>`). Before a domain is verified, use the sandbox sender noreply@mail.ranla.ai and send only to the account email."
+        },
+        to: recipientProp("Recipients"),
+        cc: recipientProp("Cc recipients"),
+        bcc: recipientProp("Bcc recipients"),
+        reply_to: recipientProp("Reply-To"),
         subject: { type: "string", description: "Optional when using a published template" },
         html: { type: "string" },
         text: { type: "string" },
-        reply_to: { type: "string" },
-        template_id: { type: "string", description: "Published template UUID" },
+        template_id: { type: "string", description: "Published template id" },
         template_alias: { type: "string", description: "Published template alias" },
         variables: {
           type: "object",
           description: "Template variables when using template_id or template_alias",
           additionalProperties: true
-        }
+        },
+        scheduled_at: { type: "string", description: "ISO 8601 time to send, e.g. 2026-10-01T09:00:00Z" },
+        category: {
+          type: "string",
+          enum: [...EMAIL_CATEGORIES],
+          description: "Default transactional. product and newsletter add an unsubscribe link and skip recipients who opted out of that category."
+        },
+        tags: {
+          type: "object",
+          description: "Tags as name \u2192 value, for filtering and webhooks",
+          additionalProperties: { type: "string" }
+        },
+        headers: {
+          type: "object",
+          description: "Extra email headers as name \u2192 value",
+          additionalProperties: { type: "string" }
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Retry-safe key: the same key within 24 hours returns the first send instead of sending twice"
+        },
+        unsubscribe: { type: "boolean", description: "Add a managed unsubscribe link to this send" }
       },
       required: ["from", "to"]
     }
@@ -718,12 +977,59 @@ var MCP_TOOLS = [
       required: ["id"]
     }
   },
+  {
+    name: "cancel_email",
+    description: "Cancel a scheduled email before it sends.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Email id (msg_\u2026) of a scheduled send" }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "list_received_emails",
+    description: "List inbound emails received on domains with inbound enabled.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...paginationProps,
+        domain: { type: "string", description: "Only messages received on this domain" }
+      }
+    }
+  },
+  {
+    name: "get_received_email",
+    description: "Get one inbound email, including its headers and body.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Received email id" }
+      },
+      required: ["id"]
+    }
+  },
   {
     name: "list_domains",
     description: "List sending domains for this account.",
     inputSchema: {
       type: "object",
-      properties: { ...paginationProps }
+      properties: {
+        ...paginationProps,
+        inbound_enabled: { type: "boolean", description: "Only domains with inbound receiving on (or off)" }
+      }
+    }
+  },
+  {
+    name: "get_domain",
+    description: "Get one sending domain by id or name, with its DNS records and verification status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        domain: { type: "string", description: "Domain id or name (example.com)" }
+      },
+      required: ["domain"]
     }
   },
   {
@@ -740,7 +1046,7 @@ var MCP_TOOLS = [
   },
   {
     name: "apply_domain_dns",
-    description: "Apply SuperSend TX DNS records for a domain. Cloudflare and GoDaddy can use credentials stored in the dashboard; GoDaddy also accepts one-time credentials on the request.",
+    description: "Create the sending domain's DNS records at your DNS provider (Cloudflare, GoDaddy, or Vercel), using the connection stored in the dashboard. GoDaddy also accepts one-time credentials on the request.",
     inputSchema: {
       type: "object",
       properties: {
@@ -782,8 +1088,8 @@ var MCP_TOOLS = [
         url: { type: "string", description: "HTTPS URL that receives events" },
         events: {
           type: "array",
-          items: { type: "string" },
-          description: "Optional event types (defaults apply when omitted)"
+          items: { type: "string", enum: WEBHOOK_EVENTS },
+          description: "Event types to deliver (all of them when omitted)"
         }
       },
       required: ["url"]
@@ -795,7 +1101,7 @@ var MCP_TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        id: { type: "string", description: "Webhook id (wh_\u2026)" }
+        id: { type: "string", description: "Webhook id" }
       },
       required: ["id"]
     }
@@ -851,14 +1157,14 @@ var MCP_TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        id: { type: "string", description: "Template id (tpl_\u2026)" },
+        id: { type: "string", description: "Template id" },
         alias: { type: "string", description: "Published alias (alternative to id)" }
       }
     }
   },
   {
     name: "create_template",
-    description: "Create a draft email template (html or blocks format).",
+    description: "Create a draft email template (html or blocks format). Publish it before sending with it.",
     inputSchema: {
       type: "object",
       properties: {
@@ -869,7 +1175,7 @@ var MCP_TOOLS = [
         text: { type: "string" },
         alias: { type: "string" }
       },
-      required: ["name", "subject"]
+      required: ["name"]
     }
   },
   {
@@ -879,7 +1185,8 @@ var MCP_TOOLS = [
       type: "object",
       properties: {
         id: { type: "string" },
-        alias: { type: "string" }
+        alias: { type: "string" },
+        label: { type: "string", description: "Optional name for this version in the template history" }
       }
     }
   },
@@ -891,10 +1198,11 @@ var MCP_TOOLS = [
       properties: {
         event: {
           type: "string",
-          enum: [...EMAIL_WEBHOOK_EVENTS],
-          description: "Webhook event type to simulate"
+          enum: [...TEST_WEBHOOK_EVENTS],
+          description: "Email event to simulate (email.received cannot be simulated \u2014 send a real inbound message)"
         },
         email_id: { type: "string", description: "Optional existing email id (msg_\u2026)" },
+        webhook_id: { type: "string", description: "Deliver to this one webhook endpoint only" },
         deliver: {
           type: "boolean",
           description: "When true (default), enqueue delivery to account webhooks"
@@ -915,30 +1223,39 @@ var MCP_TOOLS = [
   }
 ];
 var MCP_TOOLS_WITH_ARC = [...MCP_TOOLS, ...ARC_MCP_TOOLS];
+function resolveApiUrl(env = process.env) {
+  return env.SUPERSENDTX_API_URL?.trim() || env.RANLA_API_URL?.trim() || void 0;
+}
 function resolveApiKey() {
-  const key = process.env.SUPERSENDTX_API_KEY?.trim();
+  const key = process.env.SUPERSENDTX_API_KEY?.trim() || process.env.RANLA_API_KEY?.trim();
   if (!key) {
-    throw new Error("SUPERSENDTX_API_KEY is required");
+    throw new Error("Set RANLA_API_KEY (or SUPERSENDTX_API_KEY) to an API key");
   }
   if (!key.startsWith("stx_") && !key.startsWith("rnl_")) {
-    throw new Error("SUPERSENDTX_API_KEY must start with stx_ or rnl_");
+    throw new Error("The API key must start with rnl_ or stx_ (RANLA_API_KEY / SUPERSENDTX_API_KEY)");
   }
   return key;
 }
 
 // src/server.ts
+var MCP_SERVER_VERSION = version;
 function createMcpServer(apiKey, baseUrl) {
   const client = new SuperSendTX(apiKey, baseUrl ? { baseUrl } : {});
   const server = new Server(
-    { name: "supersendtx-mcp", version: "0.3.0" },
+    { name: "supersendtx-mcp", version: MCP_SERVER_VERSION },
     { capabilities: { tools: {} } }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: MCP_TOOLS_WITH_ARC.map((tool) => ({
-      name: tool.name,
-      description: tool.description,
-      inputSchema: tool.inputSchema
-    }))
+    tools: [...MCP_TOOLS, ...await loadArcMcpTools(apiKey, baseUrl)].map((tool) => {
+      const annotations = mcpToolAnnotations(tool);
+      return {
+        name: tool.name,
+        title: annotations.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations
+      };
+    })
   }));
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const result = await callMcpTool(client, request.params.name, request.params.arguments ?? {}, {
@@ -951,8 +1268,7 @@ function createMcpServer(apiKey, baseUrl) {
 }
 async function runStdioServer() {
   const apiKey = resolveApiKey();
-  const baseUrl = process.env.SUPERSENDTX_API_URL?.trim();
-  const server = createMcpServer(apiKey, baseUrl || void 0);
+  const server = createMcpServer(apiKey, resolveApiUrl());
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
@@ -1097,7 +1413,7 @@ async function handleHttpRequest(req, res, options = {}) {
 async function runHttpServer(options) {
   const host = options.host ?? "127.0.0.1";
   const port = options.port;
-  const baseUrl = process.env.SUPERSENDTX_API_URL?.trim() || void 0;
+  const baseUrl = resolveApiUrl();
   const httpServer = createServer((req, res) => {
     void handleHttpRequest(req, res, { baseUrl }).catch((error) => {
       if (!res.headersSent) {
@@ -1113,8 +1429,8 @@ async function runHttpServer(options) {
     httpServer.once("error", reject);
     httpServer.listen(port, host, () => resolve());
   });
-  console.error(`SuperSend TX MCP HTTP listening on http://${host}:${port}/mcp`);
-  console.error("Authenticate with Bearer stx_\u2026 / rnl_\u2026 or MCP OAuth access token");
+  console.error(`MCP HTTP server listening on http://${host}:${port}/mcp`);
+  console.error("Authenticate with Bearer rnl_\u2026 / stx_\u2026 or an MCP OAuth access token");
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supersendtx-mcp",
-  "version": "0.6.30",
+  "version": "0.6.34",
   "description": "SuperSend TX MCP server — mail tools plus Ranla agent-first tools for Cursor and Claude",
   "license": "MIT",
   "type": "module",
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "supersendtx": "0.15.5"
+    "supersendtx": "0.15.6"
   },
   "devDependencies": {
     "tsup": "^8.5.0",