supersendtx-mcp 0.5.10 → 0.6.1

package/dist/index.js

@@ -82,63 +82,295 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { SuperSendTX } from "supersendtx";
 
+// src/arc-talk-tools.ts
+var ARC_MCP_TALK_GROWTH_TOOL_NAMES = [
+  "get_business_brief",
+  "research_marketing_site",
+  "get_setup_status",
+  "get_growth_health",
+  "list_product_events",
+  "inspect_attribute_values",
+  "list_campaigns",
+  "list_goals",
+  "list_lists",
+  "list_segments",
+  "get_tracking_snippet",
+  "verify_tracking_install",
+  "list_automations",
+  "get_setup_run",
+  "propose_lifecycle_events",
+  "list_plan",
+  "get_job_schedule",
+  "list_opportunities",
+  "list_ideas",
+  "get_comms_prefs",
+  "list_audience",
+  "preview_segment",
+  "estimate_reach",
+  "list_templates",
+  "get_campaign_performance",
+  "list_campaign_replies",
+  "get_learnings",
+  "read_repo_activity",
+  "get_codebase_digest",
+  "read_product_context",
+  "search_codebase",
+  "read_repo_file",
+  "query_product_analytics"
+];
+
 // src/arc-mcp.ts
-var ARC_MCP_TOOLS = [
+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 TALK_READ_TOOLS = ARC_MCP_TALK_GROWTH_TOOL_NAMES.map((growthTool) => ({
+  name: `arc_${growthTool}`,
+  description: `Read-only Arc tool: ${growthTool.replace(/_/g, " ")}.`,
+  inputSchema: openObjectSchema("Tool input fields (see Ranla Arc tool docs)."),
+  kind: "growth",
+  growthTool
+}));
+var SETUP_TOOLS = [
+  {
+    name: "arc_request_connection",
+    description: "Surface a Connect card for a missing integration slot.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slot: { type: "string" },
+        reason: { type: "string" }
+      },
+      required: ["slot"]
+    },
+    kind: "growth",
+    growthTool: "request_connection"
+  }
+];
+var META_TOOLS = [
+  {
+    name: "arc_list_threads",
+    description: "List Arc chat threads for this account.",
+    inputSchema: openObjectSchema(),
+    kind: "meta"
+  },
+  {
+    name: "arc_ensure_thread",
+    description: "Find or create a durable Arc 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_get_business_brief",
-    description: "Read the business brief and lifecycle map.",
-    inputSchema: { type: "object", properties: {} },
-    growthTool: "get_business_brief"
+    name: "arc_message",
+    description: "Send a message to Arc and wait for the turn. Use for strategy and any mutating work. Returns text plus pendingApproval when HITL is required.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Message for Arc" },
+        threadId: { type: "string", description: "Arc thread id (from arc_ensure_thread)" }
+      },
+      required: ["text"]
+    },
+    kind: "meta"
   },
   {
-    name: "arc_get_setup_status",
-    description: "Connection inventory and compounding blockers.",
-    inputSchema: { type: "object", properties: {} },
-    growthTool: "get_setup_status"
+    name: "arc_list_approvals",
+    description: "List pending Arc approval cards across threads.",
+    inputSchema: openObjectSchema(),
+    kind: "meta"
   },
   {
-    name: "arc_get_growth_health",
-    description: "Signup \u2192 activation \u2192 pay health over a window.",
+    name: "arc_approve",
+    description: "Approve a pending Arc HITL card and resume the run.",
     inputSchema: {
       type: "object",
-      properties: { days: { type: "number" } }
+      properties: {
+        messageId: { type: "string" }
+      },
+      required: ["messageId"]
     },
-    growthTool: "get_growth_health"
+    kind: "meta"
   },
   {
-    name: "arc_request_connection",
-    description: "Surface a Connect card for a missing integration slot.",
+    name: "arc_reject",
+    description: "Reject a pending Arc HITL card and resume the run.",
     inputSchema: {
       type: "object",
       properties: {
-        slot: { type: "string" },
-        reason: { type: "string" }
+        messageId: { type: "string" }
       },
-      required: ["slot"]
+      required: ["messageId"]
     },
-    growthTool: "request_connection"
+    kind: "meta"
   }
 ];
-async function callArcMcpTool(apiKey, name, args, baseUrl) {
-  const def = ARC_MCP_TOOLS.find((tool) => tool.name === name);
-  if (!def) return null;
-  const origin = (baseUrl ?? process.env.SUPERSENDTX_API_URL ?? "https://app.supersendtx.com").replace(
-    /\/$/,
-    ""
-  );
-  const response = await fetch(`${origin}/api/growth/tools/${encodeURIComponent(def.growthTool)}`, {
-    method: "POST",
+var ARC_MCP_TOOLS = [...META_TOOLS, ...SETUP_TOOLS, ...TALK_READ_TOOLS];
+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 ?? "").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"
-    },
-    body: JSON.stringify({ input: args })
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...init.headers ?? {}
+    }
   });
   const body = await response.json().catch(() => ({}));
-  if (!response.ok) {
-    throw new Error(body.error ?? `Arc tool failed (${response.status})`);
+  return { ok: response.ok, status: response.status, body };
+}
+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;
+  const origin = resolveArcAppOrigin({ baseUrl, apiKey });
+  if (def.kind === "growth" && def.growthTool) {
+    const response = await arcFetch(origin, apiKey, `/api/growth/tools/${encodeURIComponent(def.growthTool)}`, {
+      method: "POST",
+      body: JSON.stringify({ input: args })
+    });
+    if (!response.ok) {
+      throw new Error(
+        typeof response.body.error === "string" ? response.body.error : `Arc tool failed (${response.status})`
+      );
+    }
+    return response.body.result ?? response.body;
+  }
+  switch (name) {
+    case "arc_list_threads": {
+      const response = await arcFetch(origin, apiKey, "/api/growth/threads");
+      if (!response.ok) {
+        throw new Error(
+          typeof response.body.error === "string" ? response.body.error : `List threads 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;
+      }
+      const response = await arcFetch(
+        origin,
+        apiKey,
+        `/api/growth/threads/${encodeURIComponent(threadId)}/messages`,
+        {
+          method: "POST",
+          body: JSON.stringify({ text, sync: true })
+        }
+      );
+      if (!response.ok && response.status !== 500) {
+        throw new Error(
+          typeof response.body.error === "string" ? response.body.error : `Arc message failed (${response.status})`
+        );
+      }
+      return { threadId, ...response.body };
+    }
+    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 Arc MCP tool: ${name}`);
   }
-  return body.result;
 }
 
 // src/tools.ts
@@ -148,7 +380,7 @@ function textResult(value, isError = false) {
     ...isError ? { isError: true } : {}
   };
 }
-function optString(args, key) {
+function optString2(args, key) {
   if (args[key] == null) return void 0;
   const value = String(args[key]).trim();
   return value || void 0;
@@ -195,10 +427,10 @@ async function callMcpTool(client, name, args, options = {}) {
     }
     switch (name) {
       case "send_email": {
-        const from = optString(args, "from");
-        const to = optString(args, "to");
-        const subject = optString(args, "subject");
-        const templateId = optString(args, "template_id") || optString(args, "template_alias");
+        const from = optString2(args, "from");
+        const to = optString2(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) {
@@ -209,9 +441,9 @@ async function callMcpTool(client, name, args, options = {}) {
           from,
           to,
           ...subject ? { subject } : {},
-          html: optString(args, "html"),
-          text: optString(args, "text"),
-          reply_to: optString(args, "reply_to"),
+          html: optString2(args, "html"),
+          text: optString2(args, "text"),
+          reply_to: optString2(args, "reply_to"),
           ...templateId ? { template: { id: templateId, ...variables ? { variables } : {} } } : {}
         });
         return textResult(result);
@@ -219,12 +451,12 @@ async function callMcpTool(client, name, args, options = {}) {
       case "list_emails": {
         const result = await client.emails.list({
           limit: optNumber(args, "limit"),
-          cursor: optString(args, "cursor")
+          cursor: optString2(args, "cursor")
         });
         return textResult(result);
       }
       case "get_email": {
-        const id = optString(args, "id");
+        const id = optString2(args, "id");
         if (!id) return textResult("Missing required argument: id", true);
         return textResult(await client.emails.get(id));
       }
@@ -248,7 +480,7 @@ async function callMcpTool(client, name, args, options = {}) {
         return textResult(result);
       }
       case "verify_domain": {
-        const domain = optString(args, "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);
@@ -256,12 +488,12 @@ async function callMcpTool(client, name, args, options = {}) {
       case "list_domains": {
         const result = await client.domains.list({
           limit: optNumber(args, "limit"),
-          cursor: optString(args, "cursor")
+          cursor: optString2(args, "cursor")
         });
         return textResult(result);
       }
       case "create_domain": {
-        const domainName = optString(args, "name");
+        const domainName = optString2(args, "name");
         if (!domainName) return textResult("Missing required argument: name", true);
         const inbound = optBoolean(args, "inbound_enabled");
         return textResult(
@@ -275,12 +507,12 @@ async function callMcpTool(client, name, args, options = {}) {
         return textResult(
           await client.webhooks.list({
             limit: optNumber(args, "limit"),
-            cursor: optString(args, "cursor")
+            cursor: optString2(args, "cursor")
           })
         );
       }
       case "create_webhook": {
-        const url = optString(args, "url");
+        const url = optString2(args, "url");
         if (!url) return textResult("Missing required argument: url", true);
         const events = optStringArray(args, "events");
         return textResult(
@@ -291,7 +523,7 @@ async function callMcpTool(client, name, args, options = {}) {
         );
       }
       case "delete_webhook": {
-        const id = optString(args, "id");
+        const id = optString2(args, "id");
         if (!id) return textResult("Missing required argument: id", true);
         return textResult(await client.webhooks.delete(id));
       }
@@ -299,67 +531,67 @@ async function callMcpTool(client, name, args, options = {}) {
         return textResult(
           await client.suppressions.list({
             limit: optNumber(args, "limit"),
-            cursor: optString(args, "cursor"),
-            email: optString(args, "email")
+            cursor: optString2(args, "cursor"),
+            email: optString2(args, "email")
           })
         );
       }
       case "add_suppression": {
-        const email = optString(args, "email");
+        const email = optString2(args, "email");
         if (!email) return textResult("Missing required argument: email", true);
         return textResult(
           await client.suppressions.create({
             email,
-            reason: optString(args, "reason")
+            reason: optString2(args, "reason")
           })
         );
       }
       case "remove_suppression": {
-        const idOrEmail = optString(args, "id") ?? optString(args, "email");
+        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 = optString(args, "status");
+        const status = optString2(args, "status");
         return textResult(
           await client.templates.list({
             limit: optNumber(args, "limit"),
-            cursor: optString(args, "cursor"),
+            cursor: optString2(args, "cursor"),
             ...status === "draft" || status === "published" ? { status } : {}
           })
         );
       }
       case "get_template": {
-        const idOrAlias = optString(args, "id") ?? optString(args, "alias");
+        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 = optString(args, "name");
-        const subjectArg = optString(args, "subject");
+        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 = optString(args, "format");
+        const format = optString2(args, "format");
         return textResult(
           await client.templates.create({
             name: name2,
             subject: subjectArg,
             ...format === "blocks" || format === "html" ? { format } : {},
-            html: optString(args, "html"),
-            text: optString(args, "text"),
-            alias: optString(args, "alias")
+            html: optString2(args, "html"),
+            text: optString2(args, "text"),
+            alias: optString2(args, "alias")
           })
         );
       }
       case "publish_template": {
-        const idOrAlias = optString(args, "id") ?? optString(args, "alias");
+        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));
       }
       case "send_test_webhook_event": {
-        const event = optString(args, "event");
+        const event = optString2(args, "event");
         if (!event || !EMAIL_WEBHOOK_EVENTS.has(event)) {
           return textResult(
             `Missing or invalid event. Use one of: ${[...EMAIL_WEBHOOK_EVENTS].join(", ")}`,
@@ -369,7 +601,7 @@ async function callMcpTool(client, name, args, options = {}) {
         return textResult(
           await client.emails.testWebhook({
             event,
-            email_id: optString(args, "email_id"),
+            email_id: optString2(args, "email_id"),
             deliver: optBoolean(args, "deliver")
           })
         );
@@ -675,12 +907,21 @@ async function runStdioServer() {
 
 // 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.supersendtx.com";
+  } catch {
+  }
+  return (process.env.SUPERSENDTX_OAUTH_ISSUER?.trim() || process.env.SUPERSENDTX_APP_URL?.trim() || "https://app.supersendtx.com").replace(/\/$/, "");
+}
 function buildProtectedResourceMetadata(origin) {
   const resource = `${origin.replace(/\/$/, "")}${MCP_HTTP_PATH}`;
-  const appOrigin = process.env.SUPERSENDTX_OAUTH_ISSUER?.trim() || process.env.SUPERSENDTX_APP_URL?.trim() || "https://app.supersendtx.com";
+  const appOrigin = appOriginForMcpOrigin(origin);
   return {
     resource,
-    authorization_servers: [appOrigin.replace(/\/$/, "")],
+    authorization_servers: [appOrigin],
     scopes_supported: ["full"],
     bearer_methods_supported: ["header"]
   };
@@ -691,14 +932,24 @@ function buildWwwAuthenticateChallenge(origin) {
 }
 
 // src/oauth-resolve.ts
-function getOAuthResolveUrl() {
-  const appBase = (process.env.SUPERSENDTX_APP_URL?.trim() || process.env.SUPERSENDTX_OAUTH_ISSUER?.trim() || "https://app.supersendtx.com").replace(/\/$/, "");
-  return `${appBase}/api/mcp/oauth/resolve`;
+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) {
+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(), {
+  const response = await fetch(getOAuthResolveUrl(mcpOrigin), {
     method: "POST",
     headers: {
       authorization: `Bearer ${accessToken}`,
@@ -733,11 +984,11 @@ function getRequestOrigin(req) {
   const proto = firstHeaderValue(req.headers["x-forwarded-proto"]) || "http";
   return `${proto}://${host}`;
 }
-async function resolveApiKeyFromAuthorization(authorization, baseUrl) {
+async function resolveApiKeyFromAuthorization(authorization, baseUrl, mcpOrigin) {
   const bearer = parseBearerToken(authorization);
   if (!bearer) return null;
   if (isSuperSendTxApiKey(bearer)) return bearer;
-  return resolveOAuthAccessToken(bearer);
+  return resolveOAuthAccessToken(bearer, mcpOrigin);
 }
 async function handleHttpRequest(req, res, options = {}) {
   const origin = getRequestOrigin(req);
@@ -767,7 +1018,8 @@ async function handleHttpRequest(req, res, options = {}) {
   }
   const apiKey = await resolveApiKeyFromAuthorization(
     typeof req.headers.authorization === "string" ? req.headers.authorization : void 0,
-    options.baseUrl
+    options.baseUrl,
+    origin
   );
   if (!apiKey) {
     sendJson(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "supersendtx-mcp",
-  "version": "0.5.10",
-  "description": "SuperSend TX MCP server — stdio or local HTTP (--http) for Cursor and Claude",
+  "version": "0.6.1",
+  "description": "SuperSend TX MCP server — mail tools plus Arc agent-first tools for Cursor and Claude",
   "license": "MIT",
   "type": "module",
   "bin": {