apple-mail-mcp 2.10.23 → 2.10.25

package/README.md

@@ -852,11 +852,12 @@ likely to be refused as ambiguous. Passing the source mailbox explicitly is the
 stay scoped, and it overrides the remembered location. These parameters name where the ids **came
 from**; for `batch-move-messages` that is distinct from `mailbox`, the destination.
 
-`sourceMailbox` is the one that scopes, and it works on its own: omitting `sourceAccount` means
-that mailbox **in the default account**, exactly as an omitted `account` does elsewhere. If the
-default account cannot be determined, the ids fail with an error asking for an explicit
-`sourceAccount` — a scope the server can't honor is never quietly downgraded to the guess-the-copy
-walk. `sourceAccount` by itself pins nothing, since the mailbox is what an id is scoped to.
+`sourceMailbox` and `sourceAccount` are an atomic scope pair: provide **both** for numeric ids.
+The server never fills in a missing account from mutable default-send state, because the same
+mailbox name can exist in more than one account and numeric ids are only unique within an account
+and mailbox. A whitespace-only source field is rejected. `sourceAccount` by itself pins nothing,
+since the mailbox is what an id is scoped to; `imap:…` ids ignore both fields because they carry
+their own account, mailbox, and UID identity.
 
 **A repeated id is one message.** `ids` is treated as a set: a duplicate names the same message,
 so it is operated on once, and the batch returns **one result per distinct id**. `success` is
@@ -868,7 +869,7 @@ therefore a count of messages, not of list positions.
 |-----------|------|----------|-------------|
 | `ids` | string[] | Yes | Message IDs to delete (max 100) |
 | `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
-| `sourceAccount` | string | No | Account the numeric ids were listed from. Defaults to the default account; on its own it pins nothing — pair it with `sourceMailbox`. |
+| `sourceAccount` | string | No | Account the numeric ids were listed from. Required when `sourceMailbox` is supplied; on its own it pins nothing. |
 
 `structuredContent` carries `countDelta` — what the batch actually did to each
 source mailbox. See [Auditing destructive operations](#auditing-destructive-operations).
@@ -883,7 +884,7 @@ source mailbox. See [Auditing destructive operations](#auditing-destructive-oper
 | `mailbox` | string | Yes | Destination mailbox |
 | `account` | string | No | Account containing mailbox |
 | `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
-| `sourceAccount` | string | No | Account the numeric ids were listed from. Defaults to the default account; on its own it pins nothing — pair it with `sourceMailbox`. |
+| `sourceAccount` | string | No | Account the numeric ids were listed from. Required when `sourceMailbox` is supplied; on its own it pins nothing. |
 
 `structuredContent` carries `countDelta` — what the batch actually did to each
 **source** mailbox. See [Auditing destructive operations](#auditing-destructive-operations).
@@ -894,7 +895,7 @@ source mailbox. See [Auditing destructive operations](#auditing-destructive-oper
 |-----------|------|----------|-------------|
 | `ids` | string[] | Yes | Message IDs (max 100) |
 | `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
-| `sourceAccount` | string | No | Account the numeric ids were listed from. Defaults to the default account; on its own it pins nothing — pair it with `sourceMailbox`. |
+| `sourceAccount` | string | No | Account the numeric ids were listed from. Required when `sourceMailbox` is supplied; on its own it pins nothing. |
 
 #### `batch-flag-messages` / `batch-unflag-messages`
 
@@ -903,7 +904,7 @@ source mailbox. See [Auditing destructive operations](#auditing-destructive-oper
 | `ids` | string[] | Yes | Message IDs (max 100) |
 | `color` | string | No | (`batch-flag-messages` only) Flag color — see [`flag-message`](#flag-message--unflag-message). Applied on both routes, so a mixed batch of numeric and `imap:` ids all end up colored. |
 | `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
-| `sourceAccount` | string | No | Account the numeric ids were listed from. Defaults to the default account; on its own it pins nothing — pair it with `sourceMailbox`. |
+| `sourceAccount` | string | No | Account the numeric ids were listed from. Required when `sourceMailbox` is supplied; on its own it pins nothing. |
 
 ---
 

package/build/index.js

@@ -78300,6 +78300,7 @@ var DIAG_ITEM_SEP = "M";
 var CONTENT_MARKER = "CONTENT";
 var MSGID_MARKER = "MSGID";
 var HTML_MARKER = "HTML";
+var LOOKUP_ERROR_MARKER = "ERR";
 var BATCH_FATAL = "FATAL";
 var RECON_TAG = "RECON";
 var SNAP_TAG = "SNAP";
@@ -78653,6 +78654,8 @@ var AppleMailManager = class {
    * misses and falls back to the full scan, so it can never wedge a lookup.
    */
   idLocationIndex = /* @__PURE__ */ new Map();
+  /** Error from the most recent numeric message read, if it was refused. */
+  lastMessageLookupError;
   /** Cap on the id→location index so a long-lived process can't grow unbounded. */
   ID_LOCATION_MAX = 5e3;
   /** Record (or refresh) where a message id lives, evicting oldest when full. */
@@ -78681,6 +78684,12 @@ var AppleMailManager = class {
   noteMessageLocation(id, account, mailbox) {
     this.rememberLocation(id, account, mailbox);
   }
+  /** Consume the most recent read refusal so the tool layer can preserve it. */
+  consumeLastMessageLookupError() {
+    const error2 = this.lastMessageLookupError;
+    this.lastMessageLookupError = void 0;
+    return error2;
+  }
   /**
    * AppleScript fragment resolving `account` + `mailbox` into `_tmb`, leaving
    * `_tmb` as `missing value` when it can't be pinned down. Exact-name match
@@ -79699,6 +79708,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
    *   returned the entire raw MIME blob mislabeled as HTML (#32).
    */
   getMessageContent(id, includeHtml = false, hint) {
+    this.lastMessageLookupError = void 0;
     const sourceFetch = includeHtml ? `set htmlSource to ""
                 try
                   set htmlSource to source of msg
@@ -79724,17 +79734,25 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
     }
     const script = buildAppLevelScript(`
       try
+        set _hits to {}
+        set _names to ""
         repeat with acct in accounts
           repeat with mb in mailboxes of acct
             try
               set matchingMsgs to (messages of mb whose id is ${Number(id)})
               if (count of matchingMsgs) > 0 then
-                set msg to item 1 of matchingMsgs
-                ${innerFetch}
+                set end of _hits to item 1 of matchingMsgs
+                set _names to _names & (name of acct) & "/" & (name of mb) & ", "
               end if
             end try
           end repeat
         end repeat
+        if (count of _hits) is 0 then return "${LOOKUP_ERROR_MARKER}Message not found"
+        if (count of _hits) > 1 then return "${LOOKUP_ERROR_MARKER}${AMBIGUOUS_ID_PREFIX}${Number(id)} is present in more than one mailbox (" & _names & "); list or search that mailbox first so the read targets the right copy"
+        if (count of _hits) is 1 then
+          set msg to item 1 of _hits
+          ${innerFetch}
+        end if
         return ""
       on error errMsg
         return ""
@@ -79756,6 +79774,10 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       if (!result.success) console.error(`Failed to get message content: ${result.error}`);
       return null;
     }
+    if (result.output.startsWith(LOOKUP_ERROR_MARKER)) {
+      this.lastMessageLookupError = result.output.slice(LOOKUP_ERROR_MARKER.length).trim();
+      return null;
+    }
     const htmlSplit = result.output.split(HTML_MARKER);
     const contentPart = htmlSplit[0];
     const rawSource = htmlSplit.length > 1 ? htmlSplit[1] : "";
@@ -79783,6 +79805,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
    * a 20MB attachment can take several seconds over Exchange/IMAP.
    */
   getRawSource(id, hint) {
+    this.lastMessageLookupError = void 0;
     const loc = hint?.account && hint?.mailbox ? { account: hint.account, mailbox: hint.mailbox } : this.idLocationIndex.get(id.toString());
     if (loc) {
       const scopedScript = this.scopedByIdScript(
@@ -79792,21 +79815,34 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         "return source of msg"
       );
       const scoped = executeAppleScript(scopedScript, { timeoutMs: 12e4 });
-      if (scoped.success && scoped.output.trim()) return scoped.output;
+      if (scoped.success && scoped.output.trim() && !scoped.output.startsWith(LOOKUP_ERROR_MARKER)) {
+        return scoped.output;
+      }
+      if (scoped.success && scoped.output.startsWith(LOOKUP_ERROR_MARKER)) {
+        this.lastMessageLookupError = scoped.output.slice(LOOKUP_ERROR_MARKER.length).trim();
+      }
     }
     const script = buildAppLevelScript(`
       try
+        set _hits to {}
+        set _names to ""
         repeat with acct in accounts
           repeat with mb in mailboxes of acct
             try
               set matchingMsgs to (messages of mb whose id is ${Number(id)})
               if (count of matchingMsgs) > 0 then
-                set msg to item 1 of matchingMsgs
-                return source of msg
+                set end of _hits to item 1 of matchingMsgs
+                set _names to _names & (name of acct) & "/" & (name of mb) & ", "
               end if
             end try
           end repeat
         end repeat
+        if (count of _hits) is 0 then return "${LOOKUP_ERROR_MARKER}Message not found"
+        if (count of _hits) > 1 then return "${LOOKUP_ERROR_MARKER}${AMBIGUOUS_ID_PREFIX}${Number(id)} is present in more than one mailbox (" & _names & "); list or search that mailbox first so the read targets the right copy"
+        if (count of _hits) is 1 then
+          set msg to item 1 of _hits
+          return source of msg
+        end if
         return ""
       on error errMsg
         return ""
@@ -79816,6 +79852,10 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
     if (!result.success || !result.output.trim()) {
       return null;
     }
+    if (result.output.startsWith(LOOKUP_ERROR_MARKER)) {
+      this.lastMessageLookupError = result.output.slice(LOOKUP_ERROR_MARKER.length).trim();
+      return null;
+    }
     return result.output;
   }
   /**
@@ -80256,27 +80296,13 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
     const safeBody = escapeForAppleScriptBody(body);
     const replyAllClause = replyAll ? " with reply to all" : "";
     const sendAction = send ? "send theReply" : "";
-    const script = buildAppLevelScript(`
-      try
-        repeat with acct in accounts
-          repeat with mb in mailboxes of acct
-            try
-              set matchingMsgs to (messages of mb whose id is ${Number(id)})
-              if (count of matchingMsgs) > 0 then
-                set msg to item 1 of matchingMsgs
-                set theReply to reply msg without opening window${replyAllClause}
-                set content of theReply to "${safeBody}"
-                ${sendAction}
-                return "ok"
-              end if
-            end try
-          end repeat
-        end repeat
-        return "error:Message not found"
-      on error errMsg
-        return "error:" & errMsg
-      end try
-    `);
+    const script = this.findMessageScript(
+      id,
+      `
+          set theReply to reply msg without opening window${replyAllClause}
+          set content of theReply to "${safeBody}"
+          ${sendAction}`
+    );
     const result = executeAppleScript(script, { timeoutMs: 6e4 });
     if (!result.success || result.output.startsWith("error:")) {
       console.error(`Failed to reply to message: ${result.error || result.output}`);
@@ -80301,28 +80327,14 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       recipientCommands += `make new to recipient at end of to recipients of theForward with properties {address:"${escapeForAppleScript(addr)}"}
 `;
     }
-    const script = buildAppLevelScript(`
-      try
-        repeat with acct in accounts
-          repeat with mb in mailboxes of acct
-            try
-              set matchingMsgs to (messages of mb whose id is ${Number(id)})
-              if (count of matchingMsgs) > 0 then
-                set msg to item 1 of matchingMsgs
-                set theForward to forward msg without opening window
-                ${recipientCommands}
-                ${safeBody ? `set content of theForward to "${safeBody}"` : ""}
-                ${sendAction}
-                return "ok"
-              end if
-            end try
-          end repeat
-        end repeat
-        return "error:Message not found"
-      on error errMsg
-        return "error:" & errMsg
-      end try
-    `);
+    const script = this.findMessageScript(
+      id,
+      `
+          set theForward to forward msg without opening window
+          ${recipientCommands}
+          ${safeBody ? `set content of theForward to "${safeBody}"` : ""}
+          ${sendAction}`
+    );
     const result = executeAppleScript(script, { timeoutMs: 6e4 });
     if (!result.success || result.output.startsWith("error:")) {
       console.error(`Failed to forward message: ${result.error || result.output}`);
@@ -80734,39 +80746,44 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
   /**
    * Turn a caller-supplied batch source scope into an account+mailbox pair.
    *
-   * `mailbox` is what does the scoping, and it works ON ITS OWN: an omitted
-   * `account` means "the default account" here exactly as it does for every
-   * other tool in this server (see resolveAccount), never "ignore the argument
-   * you were given". Requiring both used to make a lone `sourceMailbox` a silent
-   * no-op — the ids fell back to the whole-tree path and were then refused as
-   * ambiguous, which is the very failure the parameter exists to prevent.
+   * A numeric source scope is an account+mailbox pair. A mailbox name alone is
+   * not an identity: the same mailbox can exist in several accounts, and a
+   * numeric Mail id is not globally unique. Resolving a missing account from
+   * mutable default-send state can therefore target the wrong account. Require
+   * both fields so a caller cannot silently cross that account boundary.
    *
    * The safety property is absolute: when the account cannot be determined there
    * is NO fallback to the scan-and-guess walk. The caller gets an error naming
    * the mailbox it asked for, so it can retry with an explicit `sourceAccount`.
    * (An `account` with no `mailbox` cannot pin anything, so it scopes nothing —
-   * those ids still go through the index / ambiguity-checked path.)
+   * those ids still go through the index / ambiguity-checked path. A supplied
+   * whitespace-only field is rejected rather than silently discarded.)
    */
   resolveBatchScope(scope) {
-    const mailbox = scope?.mailbox?.trim();
-    if (!mailbox) return { kind: "none" };
-    const account = scope?.account?.trim();
-    if (account) return { kind: "scoped", account, mailbox };
-    const known = this.getCachedAccounts();
-    if (known.length === 0) {
+    const rawMailbox = scope?.mailbox;
+    const rawAccount = scope?.account;
+    const mailbox = rawMailbox?.trim();
+    const account = rawAccount?.trim();
+    if (rawMailbox !== void 0 && !mailbox) {
+      return {
+        kind: "unresolvable",
+        error: "sourceMailbox must contain a mailbox name; whitespace-only scope is not allowed."
+      };
+    }
+    if (rawAccount !== void 0 && !account) {
       return {
         kind: "unresolvable",
-        error: `Cannot scope to source mailbox "${mailbox}": no sourceAccount was given and no Mail account could be read (Mail returned none, or the AppleScript transport failed). Retry with an explicit sourceAccount.`
+        error: "sourceAccount must contain an account name; whitespace-only scope is not allowed."
       };
     }
-    const chosen = this.resolveAccount();
-    if (!known.some((a) => a.name === chosen)) {
+    if (!mailbox) return { kind: "none" };
+    if (!account) {
       return {
         kind: "unresolvable",
-        error: `Cannot scope to source mailbox "${mailbox}": no sourceAccount was given and the default account could not be determined. Retry with an explicit sourceAccount (available: ${known.map((a) => a.name).join(", ")}).`
+        error: `Cannot scope to source mailbox "${mailbox}" without sourceAccount: numeric Mail ids are only unique within an account and mailbox. Retry with both sourceAccount and sourceMailbox explicitly set.`
       };
     }
-    return { kind: "scoped", account: chosen, mailbox };
+    return { kind: "scoped", account, mailbox };
   }
   /**
    * Run one operation over many message IDs in a SINGLE osascript invocation.
@@ -84420,10 +84437,10 @@ function withJsonSchema2020_12(transport2) {
 // src/index.ts
 loadFileConfig();
 var BATCH_SOURCE_MAILBOX_SCHEMA = external_exports.string().optional().describe(
-  "Mailbox the numeric ids were listed from (e.g. 'INBOX'). Pins each id to that mailbox \u2014 strongly recommended, since one numeric id can match in several mailboxes. Works on its own: without sourceAccount it means that mailbox in the default account. Ignored for imap: ids."
+  "Mailbox the numeric ids were listed from (e.g. 'INBOX'). Must be paired with sourceAccount to form an unambiguous scope. Ignored for imap: ids."
 );
 var BATCH_SOURCE_ACCOUNT_SCHEMA = external_exports.string().optional().describe(
-  "Account the numeric ids were listed from. Defaults to the default account. On its own it pins nothing \u2014 pair it with sourceMailbox."
+  "Account the numeric ids were listed from. Required when sourceMailbox is supplied; on its own it pins nothing."
 );
 var FLAG_COLOR_INDEX = {
   red: 0,
@@ -84730,7 +84747,10 @@ Do not use when: you don't yet have an id (use search-messages or list-messages
           account,
           mailbox
         });
-        if (!content) return errorResponse(`Message with ID "${id}" not found`);
+        if (!content) {
+          const lookupError = mailManager.consumeLastMessageLookupError();
+          return errorResponse(lookupError ?? `Message with ID "${id}" not found`);
+        }
         const isHtml = preferHtml === true && !!content.htmlContent;
         const body = isHtml ? content.htmlContent : content.plainText;
         return successResponse(`Subject: ${content.subject}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.10.23",
+  "version": "2.10.25",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",