supersendtx-mcp 0.6.32 → 0.6.34

package/README.md

@@ -134,14 +134,19 @@ These call the app host and need a full-access key (OAuth sign-in and dashboard
 
 | Tool | Purpose |
 |------|---------|
-| `arc_ensure_thread` / `arc_list_threads` | Durable thread for this client |
+| `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 |
+| `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

@@ -84,7 +84,63 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { SuperSendTX } from "supersendtx";
 
 // package.json
-var version = "0.6.32";
+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 = [
@@ -96,6 +152,10 @@ var ARC_MCP_TALK_GROWTH_TOOL_NAMES = [
   // 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",
@@ -107,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",
@@ -134,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",
@@ -194,7 +254,8 @@ var TALK_READ_TOOLS = ARC_MCP_TALK_GROWTH_TOOL_NAMES.map((growthTool) => ({
   description: `Read-only Ranla tool: ${growthTool.replace(/_/g, " ")}.`,
   inputSchema: openObjectSchema("Pass the tool arguments as fields."),
   kind: "growth",
-  growthTool
+  growthTool,
+  readOnly: true
 }));
 var SETUP_TOOLS = [
   {
@@ -209,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"
   },
   {
@@ -246,7 +333,7 @@ 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"
   },
@@ -334,7 +421,9 @@ async function loadArcMcpTools(apiKey, baseUrl) {
       description: `${entry.mutates ? RANLA_AGENT_NAME : `${RANLA_AGENT_NAME}, read-only`}: ${entry.description}`,
       inputSchema: entry.inputSchema,
       kind: "growth",
-      growthTool: entry.name
+      growthTool: entry.name,
+      // Missing `mutates` is not a promise of read-only: only an explicit false is.
+      readOnly: entry.mutates === false
     }))
   ];
 }
@@ -361,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})`
@@ -369,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) {
@@ -1135,11 +1246,16 @@ function createMcpServer(apiKey, baseUrl) {
     { capabilities: { tools: {} } }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [...MCP_TOOLS, ...await loadArcMcpTools(apiKey, baseUrl)].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 ?? {}, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supersendtx-mcp",
-  "version": "0.6.32",
+  "version": "0.6.34",
   "description": "SuperSend TX MCP server — mail tools plus Ranla agent-first tools for Cursor and Claude",
   "license": "MIT",
   "type": "module",