@agenticmail/mcp 0.9.7 → 0.9.9

package/README.md

@@ -405,6 +405,19 @@ Reply sent to john@example.com with subject "Re: Q2 Budget Review"
 
 ---
 
+## External inbox exposure — surface this before walking the operator through relay setup
+
+> **The MCP tools that configure the relay (`setup_operator_email`, plus any agent advising the operator to run `agenticmail setup-email` or `setup-relay`) open every sub-agent up to the public internet via Gmail / Outlook plus-addressing.** Operators don't always realize this — host agents should warn explicitly:
+
+- **Plus-addresses are publicly guessable.** Once relay is configured, anyone can email `your-relay+secretary@gmail.com`, `your-relay+kepler@gmail.com`, … and the corresponding AgenticMail agent receives it. The `+sub` part is not a secret.
+- **External mail wakes the host dispatcher identically to internal `@localhost` mail.** The MCP server doesn't filter by source; the API publishes an SSE `new-mail` event for any inbound, and the host integration spawns a worker turn.
+- **The host bridges take a different path.** Mail to `your-relay+claudecode@gmail.com` / `your-relay+codex@gmail.com` routes to `handleBridgeMail`, which uses the host SDK's `resume` option to wake the operator's last session headlessly. If resume fails, it falls through to the bridge-escalation email at `setup_operator_email` — exactly why that MCP tool exists.
+- **Spam = worker turns.** Throttles in order of escalation: the `wake-budget` guard in the dispatcher (automatic), the relay-level spam filter, and `metadata.host`-based fencing for agents that should stay internal-only.
+
+When a host agent is about to call any of the relay-setup tools or instruct the operator to run `setup-email`, paraphrase this for the operator first so they can opt in deliberately rather than discovering it the day they get their first spam wake.
+
+---
+
 ## License
 
 [MIT](./LICENSE) - Ope Olatunji ([@ope-olatunji](https://github.com/ope-olatunji))

package/dist/index.js

@@ -22672,6 +22672,7 @@ var TOOL_SETS = {
   /** Mail-server setup / onboarding wizards. */
   setup: [
     "setup_guide",
+    "setup_operator_email",
     "setup_email_relay",
     "setup_email_domain",
     "setup_gmail_alias",
@@ -22932,7 +22933,7 @@ var toolDefinitions = [
   },
   {
     name: "reply_email",
-    description: "Reply to an email. Fetches the original message, auto-fills To, Subject (Re:), In-Reply-To, and References, then sends with quoted body. **For multi-agent thread coordination, pass `replyAll: true`** \u2014 the original sender lands on To: (so they wake, by default), every other thread participant lands on Cc: (so they see it without waking). This is the correct shape; the tool builds it for you. **Pass `wake` to override** the default wake target (e.g. you want to wake a specific CC'd participant). Outbound guard applies \u2014 HIGH severity content is held for review.",
+    description: 'Reply to an email. Fetches the original message, auto-fills To, Subject (Re:), In-Reply-To, and References, then sends with quoted body. **For multi-agent thread coordination, pass `replyAll: true`** \u2014 the original sender lands on To:, every other thread participant lands on Cc:. **Wake routing is body-aware**: if your reply addresses a specific CC\'d agent ("Marlow \u2014", "@kepler", "handing off to rivet", etc.), the dispatcher wakes them automatically. If your body has no such addressing, the original sender (on To:) wakes by default. **Pass `wake` to override** explicitly (e.g. `wake: ["marlow"]` to force-target one agent, or `wake: []` to deliver silently). Outbound guard applies \u2014 HIGH severity content is held for review.',
     inputSchema: {
       type: "object",
       properties: {
@@ -23137,6 +23138,17 @@ var toolDefinitions = [
       required: ["name"]
     }
   },
+  {
+    name: "setup_operator_email",
+    description: 'Save the operator\'s notification email address for bridge-escalation alerts. When sub-agents mail a host bridge (e.g. `wake: ["codex"]`) AND no fresh host session is available for a headless resume, the dispatcher forwards a digest to this address so the operator gets a phone push (via Gmail / Apple Mail / whichever app handles their address). Master-key scoped. The host agent should call this during bootstrap after asking the operator: "what email should we alert you at when sub-agents need your attention?" \u2014 the answer is typically the operator\'s personal Gmail with mobile push enabled. Idempotent: re-running with a new address updates the config.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        email: { type: "string", description: "Operator notification email (e.g. ope@gmail.com). Pass `null` or an empty string to clear an existing setting." }
+      },
+      required: ["email"]
+    }
+  },
   {
     name: "setup_email_relay",
     description: "Configure Gmail/Outlook relay for sending real internet email (requires master API key). BEGINNER-FRIENDLY: Just needs a Gmail/Outlook email + app password. Agents send as user+agentname@gmail.com. Automatically creates a default agent (secretary) unless skipped. Best for: quick setup, personal use, no domain needed.",
@@ -24275,6 +24287,20 @@ ${r.messages.map((m) => `  UID ${m.uid} (${m.folder})`).join("\n")}`;
         hostTag ? `  Host: ${hostTag} (this account is owned by the ${hostTag} dispatcher)` : ""
       ].filter(Boolean).join("\n");
     }
+    case "setup_operator_email": {
+      const raw = args2.email;
+      const email2 = typeof raw === "string" ? raw.trim() : "";
+      const body = email2 ? { email: email2 } : { email: null };
+      const result = await apiRequest("PATCH", "/system/operator-email", body, true);
+      if (!email2) {
+        return "Operator escalation email cleared. Bridge alerts will still be recorded as system events but no email forward will be sent.";
+      }
+      return [
+        `\u2713 Operator escalation email set to ${result?.email ?? email2}.`,
+        `When sub-agents mail a bridge inbox and no fresh host session is available for a headless resume, the dispatcher will email this address with a digest so you get a phone push.`,
+        `Re-run setup_operator_email with a new address any time to update.`
+      ].join("\n");
+    }
     case "setup_email_relay": {
       const result = await apiRequest("POST", "/gateway/relay", {
         provider: args2.provider,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/mcp",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "mcpName": "io.github.agenticmail/mcp",
   "description": "MCP server for AgenticMail — give any AI client real email and SMS capabilities",
   "type": "module",
@@ -30,7 +30,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0",
-    "@agenticmail/core": "^0.9.5"
+    "@agenticmail/core": "^0.9.6"
   },
   "devDependencies": {
     "tsup": "^8.4.0",