ranla-mcp 0.6.54 → 0.7.0

package/dist/index.js

@@ -0,0 +1,1704 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+var DEFAULT_HTTP_PORT = 3e3;
+var DEFAULT_HTTP_HOST = "127.0.0.1";
+function parseCliArgs(argv) {
+  const args = argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    return { mode: "help" };
+  }
+  const http = args.includes("--http");
+  if (!http) {
+    return { mode: "stdio" };
+  }
+  let port = DEFAULT_HTTP_PORT;
+  let host = DEFAULT_HTTP_HOST;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--port" || arg === "-p") {
+      const raw = args[i + 1];
+      const parsed = Number(raw);
+      if (!raw || !Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        throw new Error(`Invalid --port value: ${raw ?? "(missing)"}`);
+      }
+      port = parsed;
+      i++;
+      continue;
+    }
+    if (arg?.startsWith("--port=")) {
+      const raw = arg.slice("--port=".length);
+      const parsed = Number(raw);
+      if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        throw new Error(`Invalid --port value: ${raw}`);
+      }
+      port = parsed;
+      continue;
+    }
+    if (arg === "--host") {
+      const raw = args[i + 1]?.trim();
+      if (!raw) throw new Error("Missing --host value");
+      host = raw;
+      i++;
+      continue;
+    }
+    if (arg?.startsWith("--host=")) {
+      const raw = arg.slice("--host=".length).trim();
+      if (!raw) throw new Error("Missing --host value");
+      host = raw;
+    }
+  }
+  return { mode: "http", port, host };
+}
+function printHelp() {
+  console.error(`Usage:
+  ranla-mcp                  # stdio (default)
+  ranla-mcp --http [--port 3000] [--host 127.0.0.1]
+
+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 (default https://api.ranla.ai)
+  RANLA_APP_URL / SUPERSENDTX_APP_URL   Optional app host for the Ranla agent tools
+
+HTTP auth:
+  Authorization: Bearer rnl_\u2026 or stx_\u2026 (API key) or MCP OAuth access token
+`);
+}
+function isSuperSendTxApiKey(token) {
+  return /^(?:stx_|rnl_)[a-f0-9]{48}$/i.test(token.trim());
+}
+function parseBearerToken(authorization) {
+  if (!authorization) return null;
+  const match = /^Bearer\s+(\S+)/i.exec(authorization.trim());
+  return match?.[1] || null;
+}
+
+// src/update-check.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var UPDATE_CHECK_TIMEOUT_MS = 1500;
+var CLIENT_NAME_ENV = "SUPERSENDTX_CLIENT_NAME";
+var CLIENT_VERSION_ENV = "SUPERSENDTX_CLIENT_VERSION";
+function parseVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value.trim());
+  if (!match) return null;
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    pre: match[4] ? match[4].split(".") : []
+  };
+}
+function compareVersions(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (left.core[i] !== right.core[i]) return left.core[i] - right.core[i];
+  }
+  if (!left.pre.length || !right.pre.length) return right.pre.length - left.pre.length;
+  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i++) {
+    const l = left.pre[i];
+    const r = right.pre[i];
+    if (l === void 0) return -1;
+    if (r === void 0) return 1;
+    if (l === r) continue;
+    const ln = /^\d+$/.test(l) ? Number(l) : null;
+    const rn = /^\d+$/.test(r) ? Number(r) : null;
+    if (ln !== null && rn !== null) return ln - rn;
+    if (ln !== null) return -1;
+    if (rn !== null) return 1;
+    return l < r ? -1 : 1;
+  }
+  return 0;
+}
+function isNewerVersion(latest, current) {
+  return compareVersions(latest, current) > 0;
+}
+function noUpdateCheckEnvVar(packageName) {
+  return `${packageName.replace(/^@/, "").toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_NO_UPDATE_CHECK`;
+}
+function envFlag(value) {
+  const v = value?.trim().toLowerCase();
+  return Boolean(v) && v !== "0" && v !== "false" && v !== "no";
+}
+function isUpdateCheckDisabled(packageNames, env = process.env) {
+  if (envFlag(env.CI) || envFlag(env.NO_UPDATE_NOTIFIER)) return true;
+  return packageNames.some((name) => envFlag(env[noUpdateCheckEnvVar(name)]));
+}
+function resolveClientIdentity(own, env = process.env) {
+  const name = env[CLIENT_NAME_ENV]?.trim();
+  const version2 = env[CLIENT_VERSION_ENV]?.trim();
+  if (name && version2 && parseVersion(version2)) return { name, version: version2 };
+  return own;
+}
+function buildUserAgent(own, env = process.env) {
+  const client = resolveClientIdentity(own, env);
+  const parts = [`${client.name}/${client.version}`];
+  if (client.name !== own.name) parts.push(`${own.name}/${own.version}`);
+  parts.push(`node/${process.versions.node}`);
+  return parts.join(" ");
+}
+function withUserAgent(init, userAgent) {
+  const headers = init?.headers;
+  if (headers instanceof Headers) {
+    const next = new Headers(headers);
+    if (!next.has("user-agent")) next.set("User-Agent", userAgent);
+    return { ...init, headers: next };
+  }
+  if (Array.isArray(headers)) {
+    const has2 = headers.some(([key]) => key.toLowerCase() === "user-agent");
+    return { ...init, headers: has2 ? headers : [...headers, ["User-Agent", userAgent]] };
+  }
+  const record = headers ?? {};
+  const has = Object.keys(record).some((key) => key.toLowerCase() === "user-agent");
+  return { ...init, headers: has ? record : { ...record, "User-Agent": userAgent } };
+}
+function fetchWithUserAgent(userAgent) {
+  return ((input, init) => globalThis.fetch(input, withUserAgent(init, userAgent)));
+}
+function defaultUpdateCheckFile(packageName, env = process.env) {
+  const base = env.XDG_CONFIG_HOME?.trim() || (process.platform === "win32" ? env.APPDATA?.trim() || join(homedir(), "AppData", "Roaming") : "") || join(homedir(), ".config");
+  return join(base, packageName.replace(/^@/, "").replace(/\//g, "-"), "update-check.json");
+}
+function readCache(file) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof parsed.checkedAt !== "number") return null;
+    return { checkedAt: parsed.checkedAt, latest: typeof parsed.latest === "string" ? parsed.latest : void 0 };
+  } catch {
+    return null;
+  }
+}
+function writeCache(file, cache) {
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(cache));
+  } catch {
+  }
+}
+async function fetchLatestVersion(packageName, options = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? UPDATE_CHECK_TIMEOUT_MS);
+  timer.unref?.();
+  try {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const response = await doFetch(`https://registry.npmjs.org/${packageName.replace("/", "%2F")}/latest`, {
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) throw new Error(`registry returned ${response.status}`);
+    const body = await response.json();
+    if (typeof body.version !== "string" || !parseVersion(body.version)) throw new Error("registry returned no version");
+    return body.version;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function startUpdateCheck(options) {
+  let info = null;
+  const none = { result: () => null, done: Promise.resolve(null) };
+  try {
+    const env = options.env ?? process.env;
+    const { name, version: version2 } = options;
+    if (!parseVersion(version2)) return none;
+    if (isUpdateCheckDisabled([name, ...options.alsoKnownAs ?? []], env)) return none;
+    const now = options.now ?? Date.now;
+    const file = options.cacheFile ?? defaultUpdateCheckFile(name, env);
+    const toInfo = (latest) => latest && isNewerVersion(latest, version2) ? { name, current: version2, latest } : null;
+    const cache = readCache(file);
+    info = toInfo(cache?.latest);
+    const age = cache ? now() - cache.checkedAt : Infinity;
+    if (age >= 0 && age < (options.intervalMs ?? UPDATE_CHECK_INTERVAL_MS)) {
+      return { result: () => info, done: Promise.resolve(info) };
+    }
+    const done = fetchLatestVersion(name, { fetch: options.fetch, timeoutMs: options.timeoutMs }).then(
+      (latest) => {
+        writeCache(file, { checkedAt: now(), latest });
+        info = toInfo(latest);
+        return info;
+      },
+      () => {
+        writeCache(file, { checkedAt: now(), latest: cache?.latest });
+        return info;
+      }
+    );
+    return { result: () => info, done };
+  } catch {
+    return { result: () => info, done: Promise.resolve(info) };
+  }
+}
+function formatMcpUpdateNotice(info) {
+  return `${info.name} ${info.latest} is available (you have ${info.current}). Update: use "npx -y ${info.name}@latest" in your MCP config and restart your MCP client, or npm i -g ${info.name}@latest`;
+}
+function formatMcpAgentUpdateNotice(info) {
+  return `Update available: ${info.name} ${info.latest} is out; this MCP server is ${info.current}. Tell the user once: change the server's command to "npx -y ${info.name}@latest" (or run npm i -g ${info.name}@latest), then restart their MCP client.`;
+}
+
+// src/env.ts
+var DEFAULT_API_BASE_URL = "https://api.ranla.ai";
+var DEFAULT_APP_URL = "https://app.ranla.ai";
+function applyRanlaMcpEnv(env = process.env) {
+  if (env[CLIENT_NAME_ENV]?.trim() === "supersendtx-mcp") return;
+  if (!env.SUPERSENDTX_API_KEY?.trim() && env.RANLA_API_KEY?.trim()) {
+    env.SUPERSENDTX_API_KEY = env.RANLA_API_KEY.trim();
+  }
+  if (!env.SUPERSENDTX_APP_URL?.trim()) {
+    env.SUPERSENDTX_APP_URL = env.RANLA_APP_URL?.trim() || DEFAULT_APP_URL;
+  }
+  if (!env.SUPERSENDTX_API_URL?.trim()) {
+    env.SUPERSENDTX_API_URL = env.RANLA_API_URL?.trim() || DEFAULT_API_BASE_URL;
+  }
+}
+
+// src/http.ts
+import { createServer } from "http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { SuperSendTX } from "@supersend/ranla";
+
+// package.json
+var version = "0.7.0";
+
+// src/annotations.ts
+var READ = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+var WRITE = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+var DELETE = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
+var OUT = { openWorldHint: true };
+var FIXED_TOOL_HINTS = {
+  /** A sent email can't be unsent. */
+  send_email: { ...DELETE, ...OUT },
+  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,
+  /** Writes records at the customer's DNS provider and can replace ones already there. */
+  apply_domain_dns: { ...DELETE, ...OUT, title: "Apply domain DNS records" },
+  /** Looks the domain up in public DNS. */
+  verify_domain: { ...WRITE, ...OUT, idempotentHint: true },
+  list_webhooks: READ,
+  /** Events go to a URL outside Ranla from then on. */
+  create_webhook: { ...WRITE, ...OUT },
+  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, ...OUT },
+  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 },
+  /**
+   * Ranla researches the web, and a turn can delete or overwrite workspace
+   * records. What reaches people or spends stops at an approval.
+   */
+  arc_message: { ...DELETE, ...OUT, title: "Message Ranla" },
+  /** Commands include deletes (`campaign delete`, `contact delete`); what reaches people or spends stops at an approval. */
+  arc_ranla: { ...DELETE, ...OUT, title: "Run a Ranla command" },
+  arc_list_approvals: { ...READ, title: "List pending approvals" },
+  /** Approving can send email to real people or publish, which can't be undone. */
+  arc_approve: { ...DELETE, ...OUT, title: "Approve a Ranla step" },
+  /** 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, ...OUT };
+}
+
+// src/arc-mcp.ts
+import { randomUUID } from "crypto";
+
+// src/client-info.ts
+var MCP_PACKAGE = { name: "ranla-mcp", version };
+function mcpUserAgent(env = process.env) {
+  return buildUserAgent(MCP_PACKAGE, env);
+}
+function mcpServerName(env = process.env) {
+  return resolveClientIdentity(MCP_PACKAGE, env).name;
+}
+function startMcpUpdateCheck(env = process.env) {
+  const client = resolveClientIdentity(MCP_PACKAGE, env);
+  const check = startUpdateCheck({ ...client, alsoKnownAs: [MCP_PACKAGE.name], env });
+  let logged = false;
+  const log = (info) => {
+    if (!info || logged) return;
+    logged = true;
+    try {
+      process.stderr.write(`${formatMcpUpdateNotice(info)}
+`);
+    } catch {
+    }
+  };
+  log(check.result());
+  void check.done.then(log, () => {
+  });
+  return check;
+}
+
+// src/arc-mcp.ts
+var DEFAULT_APP_ORIGIN = "https://app.supersendtx.com";
+var DEFAULT_RANLA_APP_ORIGIN = "https://app.ranla.ai";
+var MCP_THREAD_TITLE = "MCP";
+function openObjectSchema(description) {
+  return {
+    type: "object",
+    properties: {},
+    additionalProperties: true,
+    ...description ? { description } : {}
+  };
+}
+var RANLA_AGENT_NAME = "Ranla";
+var RANLA_COMMAND_TOOL_NAME = "arc_ranla";
+var RANLA_COMMAND_INTRO = `Run one of ${RANLA_AGENT_NAME}'s commands in this account. command is "<noun> <verb>", such as "campaign list" or "page propose", and input holds its fields. "help <noun>" lists a noun's commands with every field. A command that needs sign-off does nothing yet: it comes back with pendingApproval, and arc_approve with its messageId applies it. For strategy, or anything that needs ${RANLA_AGENT_NAME}'s judgement or research, use arc_message.`;
+function ranlaCommandTool(index) {
+  return {
+    name: RANLA_COMMAND_TOOL_NAME,
+    description: index ? `${RANLA_COMMAND_INTRO}
+
+Commands:
+${index}` : RANLA_COMMAND_INTRO,
+    inputSchema: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: '"<noun> <verb>", or "help <noun>".' },
+        input: { type: "object", description: "The command's fields.", additionalProperties: true },
+        threadId: { type: "string", description: "Ranla thread to record it in (from arc_ensure_thread). Optional." }
+      },
+      required: ["command"]
+    },
+    kind: "meta"
+  };
+}
+var META_TOOLS = [
+  {
+    name: "arc_list_threads",
+    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"
+  },
+  {
+    name: "arc_ensure_thread",
+    description: "Find or create a durable Ranla thread for MCP (default title \u201CMCP\u201D). Returns { threadId, title }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: `Thread title (default ${MCP_THREAD_TITLE})` },
+        threadId: { type: "string", description: "Reuse this thread id if it still exists" }
+      }
+    },
+    kind: "meta"
+  },
+  {
+    name: "arc_message",
+    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. Long research turns are followed to the end; one still going after 15 minutes comes back with running: true, and arc_get_thread reads the answer later.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: `Message for ${RANLA_AGENT_NAME}` },
+        threadId: { type: "string", description: "Ranla thread id (from arc_ensure_thread)" }
+      },
+      required: ["text"]
+    },
+    kind: "meta"
+  },
+  {
+    name: "arc_list_approvals",
+    description: "List pending Ranla approvals across threads.",
+    inputSchema: openObjectSchema(),
+    kind: "meta"
+  },
+  {
+    name: "arc_approve",
+    description: "Approve a pending Ranla approval and resume the run.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        messageId: { type: "string" }
+      },
+      required: ["messageId"]
+    },
+    kind: "meta"
+  },
+  {
+    name: "arc_reject",
+    description: "Reject a pending Ranla approval and resume the run.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        messageId: { type: "string" }
+      },
+      required: ["messageId"]
+    },
+    kind: "meta"
+  }
+];
+var ARC_MCP_TOOLS = [...META_TOOLS, ranlaCommandTool()];
+function resolveArcAppOrigin(options = {}) {
+  const fromEnv = process.env.RANLA_APP_URL?.trim() || process.env.SUPERSENDTX_APP_URL?.trim() || "";
+  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 ?? 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;
+  return DEFAULT_APP_ORIGIN;
+}
+async function arcFetch(origin, apiKey, path, init = {}) {
+  const response = await fetch(`${origin}${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": mcpUserAgent(),
+      ...init.headers ?? {}
+    }
+  });
+  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);
+}
+async function fetchCommandIndex(apiKey, baseUrl) {
+  try {
+    const origin = resolveArcAppOrigin({ baseUrl, apiKey });
+    const response = await arcFetch(origin, apiKey, "/api/growth/commands", {
+      signal: AbortSignal.timeout(CATALOG_TIMEOUT_MS)
+    });
+    const index = response.body.index;
+    return response.ok && typeof index === "string" && index.trim() ? index : null;
+  } catch {
+    return null;
+  }
+}
+async function loadArcMcpTools(apiKey, baseUrl) {
+  const index = await fetchCommandIndex(apiKey, baseUrl);
+  if (!index) return ARC_MCP_TOOLS;
+  return [...META_TOOLS, ranlaCommandTool(index)];
+}
+var ARC_MESSAGE_MAX_WAIT_MS = 15 * 6e4;
+var ARC_MESSAGE_POLL_MS = 2e3;
+var ARC_THREAD_POLL_MS = 5e3;
+var ARC_MESSAGE_REQUEST_TIMEOUT_MS = 11e4;
+var LOST_REQUEST_STATUSES = /* @__PURE__ */ new Set([408, 429, 502, 503, 504, 520, 521, 522, 523, 524]);
+var STILL_RUNNING_NOTE = "Ranla is still working on this. Read the answer with arc_get_thread in a minute or two.";
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function turnFromThread(threadId, messages, extra) {
+  const lastFounder = messages.map((message) => message.role).lastIndexOf("user");
+  const after = messages.slice(lastFounder + 1).filter((message) => message.role !== "user");
+  const text = after.map((message) => typeof message.text === "string" ? message.text.trim() : "").filter(Boolean).join("\n\n");
+  const tools = after.flatMap(
+    (message) => (message.tools ?? []).map((tool) => ({
+      toolName: tool.name ?? "",
+      label: tool.label ?? "",
+      ...tool.isError ? { isError: true } : {}
+    }))
+  );
+  const artifacts = after.filter((message) => message.artifact?.type && message.artifact.id).map((message) => ({ type: message.artifact.type, id: message.artifact.id }));
+  const pendingApprovals = after.filter((message) => message.id && message.approval?.status === "pending").map((message) => ({
+    messageId: message.id,
+    summary: message.approval.summary ?? "",
+    ...message.approval.detail ? { detail: message.approval.detail } : {}
+  }));
+  return {
+    threadId,
+    text,
+    tools,
+    ...artifacts.length > 0 ? { artifacts } : {},
+    ...pendingApprovals.length > 0 ? { pendingApproval: pendingApprovals.at(-1) } : {},
+    ...pendingApprovals.length > 1 ? { pendingApprovals } : {},
+    ...extra
+  };
+}
+async function followThread(origin, apiKey, threadId, deadline, extra) {
+  while (true) {
+    const response = await arcFetch(origin, apiKey, `/api/growth/threads/${encodeURIComponent(threadId)}`).catch(
+      () => null
+    );
+    const thread = response?.ok ? response.body.thread : void 0;
+    if (thread && thread.running !== true) {
+      const messages = Array.isArray(response.body.messages) ? response.body.messages : [];
+      return turnFromThread(threadId, messages, extra);
+    }
+    if (Date.now() >= deadline) {
+      return { threadId, text: "", tools: [], running: true, note: STILL_RUNNING_NOTE, ...extra };
+    }
+    await sleep(ARC_THREAD_POLL_MS);
+  }
+}
+async function sendArcMessage(origin, apiKey, threadId, text) {
+  const path = `/api/growth/threads/${encodeURIComponent(threadId)}/messages`;
+  const idempotencyKey = randomUUID();
+  const deadline = Date.now() + ARC_MESSAGE_MAX_WAIT_MS;
+  let runId;
+  let setAsideApprovals;
+  let lost = false;
+  const extra = () => ({
+    ...runId ? { runId } : {},
+    ...setAsideApprovals ? { setAsideApprovals } : {}
+  });
+  while (true) {
+    const response = await arcFetch(origin, apiKey, path, {
+      method: "POST",
+      headers: { "Idempotency-Key": idempotencyKey },
+      body: JSON.stringify({ text, sync: true }),
+      signal: AbortSignal.timeout(ARC_MESSAGE_REQUEST_TIMEOUT_MS)
+    }).catch(() => null);
+    if (!response || LOST_REQUEST_STATUSES.has(response.status)) {
+      lost = true;
+      if (Date.now() >= deadline) {
+        return { threadId, text: "", tools: [], running: true, note: STILL_RUNNING_NOTE, ...extra() };
+      }
+      await sleep(ARC_MESSAGE_POLL_MS);
+      continue;
+    }
+    if (response.status === 409 && lost && !runId) {
+      return followThread(origin, apiKey, threadId, deadline, extra());
+    }
+    if (!response.ok && response.status !== 500) {
+      throw new Error(
+        typeof response.body.error === "string" ? response.body.error : `Ranla message failed (${response.status})`
+      );
+    }
+    const body = response.body;
+    if (typeof body.runId === "string" && body.runId) runId = body.runId;
+    if (Array.isArray(body.setAsideApprovals) && body.setAsideApprovals.length > 0) {
+      setAsideApprovals ?? (setAsideApprovals = body.setAsideApprovals);
+    }
+    if (body.running !== true) return { threadId, ...body, ...extra() };
+    if (!runId) return followThread(origin, apiKey, threadId, deadline, extra());
+    if (Date.now() >= deadline) return { threadId, ...body, ...extra() };
+    await sleep(ARC_MESSAGE_POLL_MS);
+  }
+}
+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) {
+  if (!isArcMcpToolName(name)) return null;
+  const origin = resolveArcAppOrigin({ baseUrl, apiKey });
+  if (name === RANLA_COMMAND_TOOL_NAME) {
+    const command = optString(args, "command");
+    if (!command) throw new Error("Missing required argument: command");
+    const input = args.input && typeof args.input === "object" && !Array.isArray(args.input) ? args.input : {};
+    const threadId = optString(args, "threadId");
+    const response = await arcFetch(origin, apiKey, "/api/growth/commands", {
+      method: "POST",
+      body: JSON.stringify({ command, input, ...threadId ? { threadId } : {} })
+    });
+    if (!response.ok) {
+      throw new Error(
+        typeof response.body.error === "string" ? response.body.error : `Ranla command failed (${response.status})`
+      );
+    }
+    return response.body;
+  }
+  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 })
+    });
+    if (!response.ok) {
+      throw new Error(
+        typeof response.body.error === "string" ? response.body.error : `Ranla tool failed (${response.status})`
+      );
+    }
+    return response.body.result ?? response.body;
+  }
+  switch (name) {
+    case "arc_list_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})`
+        );
+      }
+      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) {
+        const byId = await arcFetch(
+          origin,
+          apiKey,
+          `/api/growth/threads/${encodeURIComponent(existingId)}`
+        );
+        if (byId.ok) {
+          const thread2 = byId.body.thread;
+          if (thread2?.id) {
+            return { threadId: thread2.id, title: thread2.title ?? null };
+          }
+        }
+      }
+      const title = optString(args, "title") ?? MCP_THREAD_TITLE;
+      const byTitle = await arcFetch(
+        origin,
+        apiKey,
+        `/api/growth/threads?title=${encodeURIComponent(title)}`
+      );
+      if (byTitle.ok) {
+        const threads = Array.isArray(byTitle.body.threads) ? byTitle.body.threads : [];
+        const hit = threads.find(
+          (row) => row && typeof row === "object" && row.title === title
+        );
+        if (hit) return { threadId: hit.id, title: hit.title ?? title };
+      }
+      const created = await arcFetch(origin, apiKey, "/api/growth/threads", {
+        method: "POST",
+        body: JSON.stringify({ title })
+      });
+      if (!created.ok) {
+        throw new Error(
+          typeof created.body.error === "string" ? created.body.error : `Create thread failed (${created.status})`
+        );
+      }
+      const thread = created.body.thread;
+      if (!thread?.id) throw new Error("Create thread returned no id");
+      return { threadId: thread.id, title: thread.title ?? title };
+    }
+    case "arc_message": {
+      const text = optString(args, "text");
+      if (!text) throw new Error("Missing required argument: text");
+      let threadId = optString(args, "threadId");
+      if (!threadId) {
+        const ensured = await callArcMcpTool(apiKey, "arc_ensure_thread", {}, baseUrl);
+        threadId = ensured.threadId;
+      }
+      return sendArcMessage(origin, apiKey, threadId, text);
+    }
+    case "arc_list_approvals": {
+      const response = await arcFetch(origin, apiKey, "/api/growth/approvals");
+      if (!response.ok) {
+        throw new Error(
+          typeof response.body.error === "string" ? response.body.error : `List approvals failed (${response.status})`
+        );
+      }
+      return response.body;
+    }
+    case "arc_approve":
+    case "arc_reject": {
+      const messageId = optString(args, "messageId");
+      if (!messageId) throw new Error("Missing required argument: messageId");
+      const decision = name === "arc_approve" ? "approve" : "reject";
+      const response = await arcFetch(
+        origin,
+        apiKey,
+        `/api/growth/approvals/${encodeURIComponent(messageId)}`,
+        {
+          method: "POST",
+          body: JSON.stringify({ decision, sync: true })
+        }
+      );
+      if (!response.ok && response.status !== 500) {
+        throw new Error(
+          typeof response.body.error === "string" ? response.body.error : `Approval ${decision} failed (${response.status})`
+        );
+      }
+      return response.body;
+    }
+    default:
+      throw new Error(`Unknown Ranla MCP tool: ${name}`);
+  }
+}
+
+// src/tools.ts
+function textResult(value, isError = false) {
+  return {
+    content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }],
+    ...isError ? { isError: true } : {}
+  };
+}
+function optString2(args, key) {
+  if (args[key] == null) return void 0;
+  const value = String(args[key]).trim();
+  return value || void 0;
+}
+function optNumber(args, key) {
+  if (args[key] == null || args[key] === "") return void 0;
+  const n = Number(args[key]);
+  return Number.isFinite(n) ? n : void 0;
+}
+function optBoolean(args, key) {
+  if (args[key] == null) return void 0;
+  if (typeof args[key] === "boolean") return args[key];
+  const raw = String(args[key]).trim().toLowerCase();
+  if (raw === "true" || raw === "1") return true;
+  if (raw === "false" || raw === "0") return false;
+  return void 0;
+}
+function optStringArray(args, key) {
+  const value = args[key];
+  if (value == null) return void 0;
+  if (Array.isArray(value)) return value.map((v) => String(v));
+  return void 0;
+}
+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,
+  "affiliate.created": true,
+  "affiliate.approved": true,
+  "affiliate.updated": true,
+  "referral.created": true,
+  "referral.converted": true,
+  "commission.created": true,
+  "commission.earned": true,
+  "commission.reversed": true,
+  "commission.paid": true,
+  "payout.created": true,
+  "payout.paid": true,
+  "payout.failed": true
+};
+var WEBHOOK_EVENTS = Object.keys(WEBHOOK_EVENT_FLAGS);
+var EMAIL_CATEGORIES = ["transactional", "product", "newsletter"];
+async function callMcpTool(client, name, args, options = {}) {
+  try {
+    if (isArcMcpToolName(name)) {
+      const apiKey = options.apiKey ?? resolveApiKey();
+      const result = await callArcMcpTool(apiKey, name, args, options.baseUrl);
+      return textResult(result);
+    }
+    switch (name) {
+      case "send_email": {
+        const from = optString2(args, "from");
+        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);
+        if (!to) return textResult("Missing required argument: to", true);
+        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: 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);
+      }
+      case "list_emails": {
+        const result = await client.emails.list({
+          limit: optNumber(args, "limit"),
+          cursor: optString2(args, "cursor")
+        });
+        return textResult(result);
+      }
+      case "get_email": {
+        const id = optString2(args, "id");
+        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) {
+          return textResult("Missing required argument: domain", true);
+        }
+        const providerRaw = typeof args.provider === "string" ? args.provider.trim().toLowerCase() : "";
+        if (providerRaw !== "cloudflare" && providerRaw !== "godaddy" && providerRaw !== "vercel") {
+          return textResult(
+            'Missing or invalid provider. Use provider "cloudflare", "godaddy", or "vercel".',
+            true
+          );
+        }
+        const credentials = args.credentials && typeof args.credentials === "object" ? args.credentials : void 0;
+        const result = await client.domains.apply(domain, {
+          provider: providerRaw,
+          ...credentials ? { credentials } : {}
+        });
+        return textResult(result);
+      }
+      case "verify_domain": {
+        const domain = optString2(args, "domain");
+        if (!domain) return textResult("Missing required argument: domain", true);
+        const result = await client.domains.verify(domain);
+        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"),
+          ...inbound !== void 0 ? { inbound_enabled: inbound } : {}
+        });
+        return textResult(result);
+      }
+      case "create_domain": {
+        const domainName = optString2(args, "name");
+        if (!domainName) return textResult("Missing required argument: name", true);
+        const inbound = optBoolean(args, "inbound_enabled");
+        return textResult(
+          await client.domains.create({
+            name: domainName,
+            ...inbound !== void 0 ? { inbound_enabled: inbound } : {}
+          })
+        );
+      }
+      case "list_webhooks": {
+        return textResult(
+          await client.webhooks.list({
+            limit: optNumber(args, "limit"),
+            cursor: optString2(args, "cursor")
+          })
+        );
+      }
+      case "create_webhook": {
+        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,
+            ...events ? { events } : {}
+          })
+        );
+      }
+      case "delete_webhook": {
+        const id = optString2(args, "id");
+        if (!id) return textResult("Missing required argument: id", true);
+        return textResult(await client.webhooks.delete(id));
+      }
+      case "list_suppressions": {
+        return textResult(
+          await client.suppressions.list({
+            limit: optNumber(args, "limit"),
+            cursor: optString2(args, "cursor"),
+            email: optString2(args, "email")
+          })
+        );
+      }
+      case "add_suppression": {
+        const email = optString2(args, "email");
+        if (!email) return textResult("Missing required argument: email", true);
+        return textResult(
+          await client.suppressions.create({
+            email,
+            reason: optString2(args, "reason")
+          })
+        );
+      }
+      case "remove_suppression": {
+        const idOrEmail = optString2(args, "id") ?? optString2(args, "email");
+        if (!idOrEmail) {
+          return textResult("Missing required argument: id or email", true);
+        }
+        return textResult(await client.suppressions.remove(idOrEmail));
+      }
+      case "list_templates": {
+        const status = optString2(args, "status");
+        return textResult(
+          await client.templates.list({
+            limit: optNumber(args, "limit"),
+            cursor: optString2(args, "cursor"),
+            ...status === "draft" || status === "published" ? { status } : {}
+          })
+        );
+      }
+      case "get_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.get(idOrAlias));
+      }
+      case "create_template": {
+        const name2 = optString2(args, "name");
+        const subjectArg = optString2(args, "subject");
+        if (!name2) return textResult("Missing required argument: name", true);
+        const format = optString2(args, "format");
+        return textResult(
+          await client.templates.create({
+            name: name2,
+            // 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"),
+            alias: optString2(args, "alias")
+          })
+        );
+      }
+      case "publish_template": {
+        const idOrAlias = optString2(args, "id") ?? optString2(args, "alias");
+        if (!idOrAlias) return textResult("Missing required argument: id or alias", true);
+        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 || !TEST_WEBHOOK_EVENTS.has(event)) {
+          return textResult(
+            `Missing or invalid event. Use one of: ${[...TEST_WEBHOOK_EVENTS].join(", ")}`,
+            true
+          );
+        }
+        return textResult(
+          await client.emails.testWebhook({
+            event,
+            email_id: optString2(args, "email_id"),
+            webhook_id: optString2(args, "webhook_id"),
+            deliver: optBoolean(args, "deliver")
+          })
+        );
+      }
+      case "get_deliverability": {
+        const window = args.window === "7d" ? "7d" : "30d";
+        const result = await client.emails.insights(window);
+        return textResult(result);
+      }
+      default:
+        return textResult(`Unknown tool: ${name}`, true);
+    }
+  } catch (error) {
+    const message = error && typeof error === "object" && "message" in error ? String(error.message) : "Request failed";
+    return textResult(message, true);
+  }
+}
+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 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 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" },
+        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"]
+    }
+  },
+  {
+    name: "list_emails",
+    description: "List recent emails sent from this account.",
+    inputSchema: {
+      type: "object",
+      properties: { ...paginationProps }
+    }
+  },
+  {
+    name: "get_email",
+    description: "Get a single email by public id (msg_\u2026).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Email id (msg_\u2026)" }
+      },
+      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,
+        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"]
+    }
+  },
+  {
+    name: "create_domain",
+    description: "Add a sending domain. DNS must still be applied and verified before production sends.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Domain name (example.com)" },
+        inbound_enabled: { type: "boolean", description: "Enable inbound receiving on this domain" }
+      },
+      required: ["name"]
+    }
+  },
+  {
+    name: "apply_domain_dns",
+    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: {
+        domain: { type: "string" },
+        provider: { type: "string", enum: ["cloudflare", "godaddy", "vercel"] },
+        credentials: {
+          type: "object",
+          description: "Optional inline registrar credentials (GoDaddy api key/secret)"
+        }
+      },
+      required: ["domain", "provider"]
+    }
+  },
+  {
+    name: "verify_domain",
+    description: "Verify DNS for a sending domain after records are applied.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        domain: { type: "string" }
+      },
+      required: ["domain"]
+    }
+  },
+  {
+    name: "list_webhooks",
+    description: "List webhook endpoints for this account.",
+    inputSchema: {
+      type: "object",
+      properties: { ...paginationProps }
+    }
+  },
+  {
+    name: "create_webhook",
+    description: "Create a webhook endpoint. Returns the endpoint plus a signing secret (shown once).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "HTTPS URL that receives events" },
+        events: {
+          type: "array",
+          items: { type: "string", enum: WEBHOOK_EVENTS },
+          description: "Event types to deliver (all of them when omitted)"
+        }
+      },
+      required: ["url"]
+    }
+  },
+  {
+    name: "delete_webhook",
+    description: "Delete a webhook endpoint by id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Webhook id" }
+      },
+      required: ["id"]
+    }
+  },
+  {
+    name: "list_suppressions",
+    description: "List suppressed recipient addresses.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...paginationProps,
+        email: { type: "string", description: "Optional filter by email" }
+      }
+    }
+  },
+  {
+    name: "add_suppression",
+    description: "Add an address to the suppression list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        email: { type: "string" },
+        reason: { type: "string" }
+      },
+      required: ["email"]
+    }
+  },
+  {
+    name: "remove_suppression",
+    description: "Remove a suppression by id or email address.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Suppression id" },
+        email: { type: "string", description: "Email address (alternative to id)" }
+      }
+    }
+  },
+  {
+    name: "list_templates",
+    description: "List email templates.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...paginationProps,
+        status: { type: "string", enum: ["draft", "published"] }
+      }
+    }
+  },
+  {
+    name: "get_template",
+    description: "Get a template by id or alias.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        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). Publish it before sending with it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        subject: { type: "string" },
+        format: { type: "string", enum: ["html", "blocks"] },
+        html: { type: "string" },
+        text: { type: "string" },
+        alias: { type: "string" }
+      },
+      required: ["name"]
+    }
+  },
+  {
+    name: "publish_template",
+    description: "Publish a template, snapshotting an immutable version for sends.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        alias: { type: "string" },
+        label: { type: "string", description: "Optional name for this version in the template history" }
+      }
+    }
+  },
+  {
+    name: "send_test_webhook_event",
+    description: "Simulate a webhook event (POST /emails/test) for CI or local webhook testing. Optionally deliver to subscribed endpoints.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        event: {
+          type: "string",
+          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"
+        }
+      },
+      required: ["event"]
+    }
+  },
+  {
+    name: "get_deliverability",
+    description: "Fetch best-effort deliverability metrics for recent sends (7d or 30d window).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        window: { type: "string", enum: ["7d", "30d"] }
+      }
+    }
+  }
+];
+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() || process.env.RANLA_API_KEY?.trim();
+  if (!key) {
+    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("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;
+var MCP_SERVER_INSTRUCTIONS = [
+  "Ranla is an AI growth agent for a software business: lifecycle email, audiences, campaigns, pages, ads, and replies, plus transactional email from the same workspace.",
+  'For growth work, or anything that needs judgement or research, send the request to Ranla with arc_message and show its reply. Use arc_ranla when the user names one specific step, such as "campaign list".',
+  "Anything that sends, spends, or publishes comes back as pendingApproval and does nothing yet. Show it to the user and call arc_approve or arc_reject only after they answer.",
+  "Use the mail tools (send_email, domains, templates, webhooks, suppressions) only when the user asks about application mail such as receipts or sign-in codes."
+].join("\n\n");
+var MCP_TOOL_SECURITY_SCHEMES = [{ type: "oauth2", scopes: ["full"] }];
+function withUpdateNotice(result, notice) {
+  return { ...result, content: [...result.content, { type: "text", text: notice }] };
+}
+function createMcpServer(apiKey, baseUrl, options = {}) {
+  const client = new SuperSendTX(apiKey, {
+    ...baseUrl ? { baseUrl } : {},
+    fetch: fetchWithUserAgent(mcpUserAgent())
+  });
+  const knownUpdate = options.updateCheck?.result();
+  const instructions = knownUpdate ? `${MCP_SERVER_INSTRUCTIONS}
+
+${formatMcpAgentUpdateNotice(knownUpdate)}` : MCP_SERVER_INSTRUCTIONS;
+  const server = new Server(
+    { name: mcpServerName(), version: MCP_SERVER_VERSION },
+    { capabilities: { tools: {} }, instructions }
+  );
+  let updateNoticeSent = false;
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    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,
+        securitySchemes: MCP_TOOL_SECURITY_SCHEMES,
+        _meta: { securitySchemes: MCP_TOOL_SECURITY_SCHEMES }
+      };
+    })
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const result = await callMcpTool(client, request.params.name, request.params.arguments ?? {}, {
+      apiKey,
+      baseUrl
+    });
+    const update = updateNoticeSent ? null : options.updateCheck?.result();
+    if (!update) return result;
+    updateNoticeSent = true;
+    return withUpdateNotice(result, formatMcpAgentUpdateNotice(update));
+  });
+  return server;
+}
+async function runStdioServer() {
+  const apiKey = resolveApiKey();
+  const server = createMcpServer(apiKey, resolveApiUrl(), { updateCheck: startMcpUpdateCheck() });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// src/oauth-metadata.ts
+var MCP_HTTP_PATH = "/mcp";
+function appOriginForMcpOrigin(mcpOrigin) {
+  try {
+    const host = new URL(mcpOrigin).hostname.toLowerCase();
+    if (host === "mcp.ranla.ai") return "https://app.ranla.ai";
+    if (host === "mcp.supersendtx.com") return "https://app.ranla.ai";
+  } catch {
+  }
+  return (process.env.SUPERSENDTX_OAUTH_ISSUER?.trim() || process.env.SUPERSENDTX_APP_URL?.trim() || "https://app.ranla.ai").replace(/\/$/, "");
+}
+function buildProtectedResourceMetadata(origin) {
+  const resource = `${origin.replace(/\/$/, "")}${MCP_HTTP_PATH}`;
+  const appOrigin = appOriginForMcpOrigin(origin);
+  return {
+    resource,
+    authorization_servers: [appOrigin],
+    scopes_supported: ["full"],
+    bearer_methods_supported: ["header"]
+  };
+}
+function buildWwwAuthenticateChallenge(origin) {
+  const metadataUrl = `${origin.replace(/\/$/, "")}/.well-known/oauth-protected-resource`;
+  return `Bearer error="invalid_token", error_description="OAuth authentication required", resource_metadata="${metadataUrl}"`;
+}
+
+// src/oauth-resolve.ts
+function appOriginForMcpOrigin2(mcpOrigin) {
+  if (mcpOrigin) {
+    try {
+      const host = new URL(mcpOrigin).hostname.toLowerCase();
+      if (host === "mcp.ranla.ai") return "https://app.ranla.ai";
+      if (host === "mcp.supersendtx.com") return "https://app.supersendtx.com";
+    } catch {
+    }
+  }
+  return (process.env.SUPERSENDTX_APP_URL?.trim() || process.env.SUPERSENDTX_OAUTH_ISSUER?.trim() || "https://app.supersendtx.com").replace(/\/$/, "");
+}
+function getOAuthResolveUrl(mcpOrigin) {
+  return `${appOriginForMcpOrigin2(mcpOrigin)}/api/mcp/oauth/resolve`;
+}
+async function resolveOAuthAccessToken(accessToken, mcpOrigin) {
+  const resolveSecret = process.env.SUPERSENDTX_MCP_RESOLVE_SECRET?.trim() || process.env.SUPERSENDTX_CREDENTIALS_ENCRYPTION_KEY?.trim() || (process.env.NODE_ENV === "production" ? "" : "supersendtx-dev-mcp-resolve");
+  if (!resolveSecret) return null;
+  const response = await fetch(getOAuthResolveUrl(mcpOrigin), {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${accessToken}`,
+      "content-type": "application/json",
+      "x-supersendtx-mcp-resolve": resolveSecret
+    }
+  });
+  if (!response.ok) return null;
+  const data = await response.json().catch(() => null);
+  const apiKey = data?.apiKey?.trim();
+  return apiKey || null;
+}
+
+// src/http.ts
+var OPENAI_APPS_CHALLENGE_PATH = "/.well-known/openai-apps-challenge";
+function sendJson(res, status, body, headers = {}) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(payload),
+    ...headers
+  });
+  res.end(payload);
+}
+function firstHeaderValue(value) {
+  if (!value) return void 0;
+  const raw = Array.isArray(value) ? value[0] : value;
+  const trimmed = raw?.split(",")[0]?.trim();
+  return trimmed || void 0;
+}
+function getRequestOrigin(req) {
+  const host = firstHeaderValue(req.headers["x-forwarded-host"]) || firstHeaderValue(req.headers.host) || "127.0.0.1";
+  const proto = firstHeaderValue(req.headers["x-forwarded-proto"]) || "http";
+  return `${proto}://${host}`;
+}
+async function resolveApiKeyFromAuthorization(authorization, baseUrl, mcpOrigin) {
+  const bearer = parseBearerToken(authorization);
+  if (!bearer) return null;
+  if (isSuperSendTxApiKey(bearer)) return bearer;
+  return resolveOAuthAccessToken(bearer, mcpOrigin);
+}
+async function handleHttpRequest(req, res, options = {}) {
+  const origin = getRequestOrigin(req);
+  const url = new URL(req.url || "/", origin);
+  if (req.method === "OPTIONS") {
+    res.writeHead(204, {
+      "access-control-allow-origin": "*",
+      "access-control-allow-methods": "GET, POST, DELETE, OPTIONS",
+      "access-control-allow-headers": "Authorization, Content-Type, Accept, Mcp-Session-Id, X-Supersendtx-Mcp-Resolve"
+    });
+    res.end();
+    return;
+  }
+  if (url.pathname === "/health") {
+    sendJson(res, 200, { ok: true, service: "ranla-mcp" });
+    return;
+  }
+  if (url.pathname === OPENAI_APPS_CHALLENGE_PATH) {
+    const token = process.env.OPENAI_APPS_CHALLENGE_TOKEN?.trim();
+    if (!token) {
+      sendJson(res, 404, { error: "Not found" });
+      return;
+    }
+    res.writeHead(200, {
+      "content-type": "text/plain; charset=utf-8",
+      "content-length": Buffer.byteLength(token),
+      "cache-control": "no-store"
+    });
+    res.end(token);
+    return;
+  }
+  if (url.pathname === "/.well-known/oauth-protected-resource") {
+    sendJson(res, 200, buildProtectedResourceMetadata(origin), {
+      "cache-control": "public, max-age=300, s-maxage=3600"
+    });
+    return;
+  }
+  if (url.pathname !== "/mcp" && url.pathname !== "/") {
+    sendJson(res, 404, { error: "Not found. MCP endpoint is POST/GET /mcp" });
+    return;
+  }
+  const apiKey = await resolveApiKeyFromAuthorization(
+    typeof req.headers.authorization === "string" ? req.headers.authorization : void 0,
+    options.baseUrl,
+    origin
+  );
+  if (!apiKey) {
+    sendJson(
+      res,
+      401,
+      { error: "Missing or invalid Authorization. Use Bearer stx_\u2026 / rnl_\u2026 or complete MCP OAuth." },
+      { "www-authenticate": buildWwwAuthenticateChallenge(origin) }
+    );
+    return;
+  }
+  const server = createMcpServer(apiKey, options.baseUrl);
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: void 0
+  });
+  try {
+    await server.connect(transport);
+    await transport.handleRequest(req, res);
+  } finally {
+    await transport.close().catch(() => void 0);
+    await server.close().catch(() => void 0);
+  }
+}
+async function runHttpServer(options) {
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port;
+  const baseUrl = resolveApiUrl();
+  const httpServer = createServer((req, res) => {
+    void handleHttpRequest(req, res, { baseUrl }).catch((error) => {
+      if (!res.headersSent) {
+        sendJson(res, 500, {
+          error: error instanceof Error ? error.message : "Internal server error"
+        });
+      } else {
+        res.end();
+      }
+    });
+  });
+  await new Promise((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(port, host, () => resolve());
+  });
+  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
+async function main() {
+  applyRanlaMcpEnv();
+  const options = parseCliArgs(process.argv);
+  if (options.mode === "help") {
+    printHelp();
+    process.exit(0);
+  }
+  if (options.mode === "http") {
+    await runHttpServer({ port: options.port, host: options.host });
+    return;
+  }
+  await runStdioServer();
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});