apple-mail-mcp 2.20.20 → 2.20.22

package/README.md

@@ -1075,6 +1075,12 @@ List attachments on a message.
 **Returns:** List of attachments with name, MIME type, and `size` — the **decoded** byte count,
 i.e. what `fetch-attachment` returns.
 
+**A numeric `id` resolves the same way the read tools resolve one** (2.20.21): the mailbox the id
+was listed from when that is known, else a bounded cross-mailbox scan that skips very large
+mailboxes and stops at its time budget. An id that several mailboxes hold is **refused**, with the
+candidates named, rather than answered for whichever copy came first — so list or search the
+mailbox you mean immediately before calling this. `imap:…` ids are never ambiguous.
+
 **Sizes over IMAP.** `BODYSTRUCTURE` reports a part's size in its transfer encoding, so a
 base64 attachment's raw figure is ~4/3 of the file. `list-attachments` converts it: a
 `Content-Disposition` `size=` parameter wins when present; 7bit/8bit/binary parts are exact
@@ -1096,6 +1102,11 @@ of overwriting an existing file. AppleScript and MIME fallback paths stage the
 bytes privately, commit with an exclusive create, and leave the saved file
 owner-readable/writable (`0600`).
 
+**A numeric `id` resolves the same way the read tools resolve one** (2.20.21): the mailbox the id
+was listed from when that is known, else the bounded cross-mailbox scan. An id that several
+mailboxes hold **saves nothing** rather than writing some other message's attachment under the
+name you asked for.
+
 | Parameter        | Type   | Required | Description                |
 | ---------------- | ------ | -------- | -------------------------- |
 | `id`             | string | Yes      | Message ID                 |

package/build/index.js

@@ -83314,6 +83314,7 @@ var DATES_MARKER = "DATES";
 var HTML_MARKER = "HTML";
 var LOOKUP_ERROR_MARKER = "ERR";
 var BATCH_FATAL = "FATAL";
+var ATTACHMENTS_MARKER = "ATT";
 var RECON_TAG = "RECON";
 var SNAP_TAG = "SNAP";
 var SNAP_PAIR = "P";
@@ -83780,19 +83781,32 @@ function mailboxPathFragment(mailboxVar, outputVar) {
           set _pathParent to _pathNext
         end repeat`;
 }
-function mailboxLookupFragment(collExpr, path3, outputVar) {
-  return `
-        set ${outputVar} to missing value
+function mailboxLookupFragment(collExpr, path3, outputVar, hintIndex) {
+  const safePath = escapeForAppleScript(path3);
+  const hint = hintIndex === void 0 ? "" : `
+        try
+          set _mbc to item ${hintIndex} of (${collExpr})
+          set _mbcPath to ""
+          ${mailboxPathFragment("_mbc", "_mbcPath")}
+          ignoring case
+            if _mbcPath is "${safePath}" then set ${outputVar} to _mbc
+          end ignoring
+        end try`;
+  const walk = `
         repeat with _mbc in (${collExpr})
           set _mbcPath to ""
           ${mailboxPathFragment("_mbc", "_mbcPath")}
           ignoring case
-            if _mbcPath is "${escapeForAppleScript(path3)}" then
+            if _mbcPath is "${safePath}" then
               set ${outputVar} to _mbc
               exit repeat
             end if
           end ignoring
         end repeat`;
+  return `
+        set ${outputVar} to missing value${hint}${hintIndex === void 0 ? walk : `
+        if ${outputVar} is missing value then${walk}
+        end if`}`;
 }
 var MAILBOX_ALIASES = {
   inbox: ["INBOX", "Inbox", "inbox"],
@@ -84788,6 +84802,17 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
   resolveMailbox(mailbox, account) {
     return resolveAppleMailboxPath(mailbox, this.getCachedMailboxNames(account));
   }
+  /**
+   * The 1-based position of `path` in the account's cached mailbox list, which is
+   * built by walking the account's `mailboxes` in order. `mailboxLookupFragment`
+   * checks that one mailbox first instead of working out the path of every one.
+   * Undefined when the path is not in the list; a stale position is harmless, the
+   * fragment verifies the path and falls back to the full walk.
+   */
+  mailboxIndexHint(account, path3) {
+    const index = this.getCachedMailboxNames(account).indexOf(path3);
+    return index >= 0 ? index + 1 : void 0;
+  }
   /**
    * Non-throwing `resolveMailbox`, for callers comparing mailbox names AFTER
    * a destructive op already ran (the forensics `sameMailbox` closures). An
@@ -84954,7 +84979,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       ${dateSetup}set outputText to ""
       set _timedOut to false
       set _notSearched to ""
-      ${mailboxLookupFragment(mbIter, targetMailbox, "theMailbox")}
+      ${mailboxLookupFragment(mbIter, targetMailbox, "theMailbox", this.mailboxIndexHint(targetAccount, targetMailbox))}
       set msgCount to 0
       if theMailbox is missing value then
         set _timedOut to true
@@ -85686,7 +85711,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       set outputText to ""
       set _timedOut to false
       set _notSearched to ""
-      ${mailboxLookupFragment(mbIter, targetMailbox, "theMailbox")}
+      ${mailboxLookupFragment(mbIter, targetMailbox, "theMailbox", this.mailboxIndexHint(targetAccount, targetMailbox))}
       set msgCount to 0
       set skipped to 0
       if theMailbox is missing value then
@@ -86903,14 +86928,7 @@ ${this.errorEmit("              ")}
    * when AppleScript returns empty (known issue across all account types).
    */
   listAttachments(id) {
-    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
+    const attachmentLoop = `
                 set outputText to ""
                 set attCount to 0
                 -- Each property is read inside its own try: \`MIME type of att\` throws
@@ -86936,20 +86954,20 @@ ${this.errorEmit("              ")}
                     set outputText to outputText & attName & "${FIELD_SEP}" & attType & "${FIELD_SEP}" & attSize
                     set attCount to attCount + 1
                   end if
-                end repeat
-                return outputText
-              end if
-            end try
-          end repeat
-        end repeat
-        return ""
-      on error errMsg
-        return ""
-      end try
-    `);
-    const result = executeAppleScript(script, { timeoutMs: 6e4 });
-    if (result.success && result.output.trim()) {
-      const items = result.output.split(RECORD_SEP);
+                end repeat`;
+    this.lastMessageLookupError = void 0;
+    const output = this.resolveById(
+      id,
+      `${attachmentLoop}
+                return "${ATTACHMENTS_MARKER}" & outputText`,
+      void 0
+    );
+    if (output === null) {
+      const refusal = this.consumeLastMessageLookupError();
+      if (refusal) throw new Error(refusal);
+    }
+    if (output?.startsWith(ATTACHMENTS_MARKER) && output.length > ATTACHMENTS_MARKER.length) {
+      const items = output.slice(ATTACHMENTS_MARKER.length).split(RECORD_SEP);
       const attachments = [];
       for (const item of items) {
         const parts = item.split(FIELD_SEP);
@@ -87007,14 +87025,28 @@ ${this.errorEmit("              ")}
       }
     };
     const numericId = Number(id);
-    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 ${numericId})
-              if (count of matchingMsgs) > 0 then
-                set msg to item 1 of matchingMsgs
+    this.lastMessageLookupError = void 0;
+    const located = this.resolveById(
+      id,
+      `set _where to ""
+                try
+                  ${mailboxPathFragment("_hitMb", "_where")}
+                end try
+                return _hitAcct & "${FIELD_SEP}" & _where`,
+      void 0
+    );
+    if (located === null) {
+      const why = this.consumeLastMessageLookupError();
+      if (why) {
+        cleanupTemporaryDirectory();
+        console.error(`Failed to save attachment: ${why}`);
+        return false;
+      }
+    }
+    const [holderAccount, holderMailbox] = (located ?? "").split(FIELD_SEP);
+    if (holderAccount && holderMailbox)
+      this.rememberLocation(String(id), holderAccount, holderMailbox);
+    const saveAction = `
                 repeat with att in mail attachments of msg
                   if name of att is "${safeName}" then
                     set savePath to POSIX file "${safeTemporaryPath}"
@@ -87022,7 +87054,16 @@ ${this.errorEmit("              ")}
                     return "ok"
                   end if
                 end repeat
-                return "error:Attachment not found"
+                return "error:Attachment not found"`;
+    const script = holderAccount && holderMailbox ? this.scopedByIdScript(holderAccount, holderMailbox, id, saveAction) : buildAppLevelScript(`
+      try
+        repeat with acct in accounts
+          repeat with mb in mailboxes of acct
+            try
+              set matchingMsgs to (messages of mb whose id is ${numericId})
+              if (count of matchingMsgs) > 0 then
+                set msg to item 1 of matchingMsgs
+                ${saveAction}
               end if
             end try
           end repeat
@@ -87166,7 +87207,7 @@ ${this.errorEmit("              ")}
     const targetAccount = this.resolveAccount(account);
     const targetMailbox = this.resolveMailbox(mailbox || "INBOX", targetAccount);
     const command = `
-      ${mailboxLookupFragment("mailboxes", targetMailbox, "theMailbox")}
+      ${mailboxLookupFragment("mailboxes", targetMailbox, "theMailbox", this.mailboxIndexHint(targetAccount, targetMailbox))}
       if theMailbox is missing value then error "Mailbox \\"${escapeForAppleScript(targetMailbox)}\\" not found"
       return unread count of theMailbox`;
     const script = buildAccountScopedScript(targetAccount, command);

package/package.json

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