apple-mail-mcp 2.16.1 → 2.17.0

package/README.md

@@ -937,10 +937,21 @@ List all mailboxes for an account.
 |-----------|------|----------|-------------|
 | `account` | string | No | Account to list from, or `"On My Mac"` for the local store |
 
-**Returns:** List of mailbox names with message and unread counts. A source that
-could not be read is **named** (`partial: true` + `failedAccounts`) rather than
-dropped, and a listing Mail refused outright returns an error naming the accounts
-that do exist — never an empty list.
+**Returns:** List of mailbox **paths** (account-relative, e.g. `Archive/Inbox` for
+a nested mailbox — a top-level `Inbox` stays `Inbox`) with message and unread
+counts. A source that could not be read is **named** (`partial: true` +
+`failedAccounts`) rather than dropped, and a listing Mail refused outright
+returns an error naming the accounts that do exist — never an empty list.
+
+**Nested mailboxes and Gmail labels.** Every `mailbox` parameter across this
+server (search-messages, list-messages, get-unread-count, move-message,
+delete-mailbox, rename-mailbox, create-rule's `moveTo`) accepts either the full
+path or a leaf name that is unique across the account — the same rule
+move-message has always used. A leaf name that matches more than one mailbox
+(e.g. a top-level `Inbox` and an `Archive/Inbox` on an Exchange account) is
+refused rather than guessed; pass the full path to disambiguate. This also
+means Gmail's nested special mailboxes now report their real path, e.g.
+`[Gmail]/All Mail` rather than `All Mail` — a visible change from before 2.17.0.
 
 **Mail's local "On My Mac" mailboxes** are not children of any account — they
 hang off the application — so they are reported under the synthetic account label

package/build/index.js

@@ -79291,6 +79291,41 @@ function buildAppLevelScript(command) {
     end tell
   `;
 }
+function mailboxPathFragment(mailboxVar, outputVar) {
+  return `
+        set ${outputVar} to name of ${mailboxVar}
+        set _pathParent to missing value
+        try
+          set _pathParent to container of ${mailboxVar}
+        end try
+        repeat while _pathParent is not missing value
+          set _parentClass to missing value
+          try
+            set _parentClass to class of _pathParent
+          end try
+          if _parentClass is not mailbox and _parentClass is not container then exit repeat
+          set ${outputVar} to (name of _pathParent) & "/" & ${outputVar}
+          set _pathNext to missing value
+          try
+            set _pathNext to container of _pathParent
+          end try
+          set _pathParent to _pathNext
+        end repeat`;
+}
+function mailboxLookupFragment(collExpr, path, outputVar) {
+  return `
+        set ${outputVar} to missing value
+        repeat with _mbc in (${collExpr})
+          set _mbcPath to ""
+          ${mailboxPathFragment("_mbc", "_mbcPath")}
+          ignoring case
+            if _mbcPath is "${escapeForAppleScript(path)}" then
+              set ${outputVar} to _mbc
+              exit repeat
+            end if
+          end ignoring
+        end repeat`;
+}
 var MAILBOX_ALIASES = {
   inbox: ["INBOX", "Inbox", "inbox"],
   sent: ["Sent", "Sent Items", "Sent Messages", "SENT", "sent"],
@@ -79299,13 +79334,39 @@ var MAILBOX_ALIASES = {
   junk: ["Junk", "Junk Email", "Spam", "JUNK", "junk"],
   archive: ["Archive", "ARCHIVE", "archive", "All Mail"]
 };
+function mailboxLeaf(path) {
+  return path.split("/").at(-1) ?? path;
+}
+function resolveAppleMailboxPath(mailbox, actualPaths) {
+  if (actualPaths.length === 0) return mailbox;
+  const candidates = [mailbox, ...MAILBOX_ALIASES[mailbox.toLowerCase()] ?? []];
+  for (const candidate of candidates) {
+    const exact = actualPaths.find((path) => path === candidate);
+    if (exact) return exact;
+    const folded = actualPaths.find((path) => path.toLowerCase() === candidate.toLowerCase());
+    if (folded) return folded;
+  }
+  for (const candidate of candidates) {
+    const leafMatches = actualPaths.filter(
+      (path) => mailboxLeaf(path).toLowerCase() === candidate.toLowerCase()
+    );
+    if (leafMatches.length === 1) return leafMatches[0];
+    if (leafMatches.length > 1) {
+      const paths = [...leafMatches].sort().map((path) => `"${path}"`).join(" and ");
+      throw new Error(
+        `Mailbox "${mailbox}" is ambiguous \u2014 it matches ${paths}. Pass the full path.`
+      );
+    }
+  }
+  return mailbox;
+}
 var GMAIL_INBOX_MAILBOXES = ["All Mail", "Important"];
 var INBOX_SCOPE_NAMES = /* @__PURE__ */ new Set(["inbox"]);
 function isInboxScope(mailbox) {
   return INBOX_SCOPE_NAMES.has(mailbox.trim().toLowerCase());
 }
 function gmailReceivingMailboxes(mailboxNames) {
-  const lower = mailboxNames.map((n) => n.toLowerCase());
+  const lower = mailboxNames.map((n) => mailboxLeaf(n).toLowerCase());
   if (!lower.includes("all mail")) return null;
   const present = GMAIL_INBOX_MAILBOXES.filter((want) => lower.includes(want.toLowerCase()));
   return present.length > 0 ? present : null;
@@ -79429,7 +79490,11 @@ var AppleMailManager = class {
         if (count of _acctM) is 1 then
           set _mbM to {}
           repeat with _m in (mailboxes of (item 1 of _acctM))
-            if (name of _m) is "${escapeForAppleScript(resolved)}" then set end of _mbM to _m
+            set _mPath to ""
+            ${mailboxPathFragment("_m", "_mPath")}
+            ignoring case
+              if _mPath is "${escapeForAppleScript(resolved)}" then set end of _mbM to _m
+            end ignoring
           end repeat
           if (count of _mbM) is 1 then set _tmb to item 1 of _mbM
         end if`;
@@ -79539,11 +79604,16 @@ ${indent}set _out to _out & (_idx as string) & "${FIELD_SEP}error:" & _zErr & "$
    * are read from Mail at runtime (`_uacct`, `mailbox of _msg`) instead of being
    * interpolated as literals from here — so they get the same delimiter
    * stripping the literal paths get in TypeScript.
+   *
+   * Emits the canonical container-walked path, not the leaf — otherwise
+   * `Inbox` and `Archive/Inbox` collapse into the same RECON record, and the
+   * forensics comparison that reads it back (`sameMailbox` in
+   * `recordSingleForensics`/the batch path) can be handed an ambiguous leaf.
    */
   reconEmitFromMessage(beforeVar, afterVar, posExpr = '""', indent = "          ") {
     return `set _umbName to ""
 ${indent}try
-${indent}  set _umbName to (name of _umb)
+${mailboxPathFragment("_umb", "_umbName")}
 ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragment("_umbName", indent)}${this.reconEmit("_uacct", "_umbName", beforeVar, afterVar, posExpr)}`;
   }
   /**
@@ -80018,8 +80088,8 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
     return accounts;
   }
   /**
-   * Returns cached mailbox names for an account, or fetches fresh.
-   * This caches only the name list used by resolveMailbox(), not the
+   * Returns cached canonical mailbox paths for an account, or fetches fresh.
+   * This caches only the path list used by resolveMailbox(), not the
    * full Mailbox objects with counts (which change frequently).
    */
   getCachedMailboxNames(account) {
@@ -80221,31 +80291,22 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
    * @returns Actual mailbox name, or original if not found
    */
   resolveMailbox(mailbox, account) {
-    const actualMailboxes = this.getCachedMailboxNames(account);
-    if (actualMailboxes.length === 0) {
-      return mailbox;
-    }
-    if (actualMailboxes.includes(mailbox)) {
+    return resolveAppleMailboxPath(mailbox, this.getCachedMailboxNames(account));
+  }
+  /**
+   * Non-throwing `resolveMailbox`, for callers comparing mailbox names AFTER
+   * a destructive op already ran (the forensics `sameMailbox` closures). An
+   * ambiguous leaf there must not raise — the op already happened, and a
+   * thrown error would misreport a successful move as a failure while the
+   * message sits safely in its new mailbox. Falls back to the unresolved
+   * input, which only degrades the self-move comparison, never the mutation.
+   */
+  resolveMailboxSafe(mailbox, account) {
+    try {
+      return this.resolveMailbox(mailbox, account);
+    } catch {
       return mailbox;
     }
-    const lowerMailbox = mailbox.toLowerCase();
-    const caseMatch = actualMailboxes.find((mb) => mb.toLowerCase() === lowerMailbox);
-    if (caseMatch) {
-      return caseMatch;
-    }
-    const aliases = MAILBOX_ALIASES[lowerMailbox];
-    if (aliases) {
-      for (const alias of aliases) {
-        if (actualMailboxes.includes(alias)) {
-          return alias;
-        }
-        const aliasMatch = actualMailboxes.find((mb) => mb.toLowerCase() === alias.toLowerCase());
-        if (aliasMatch) {
-          return aliasMatch;
-        }
-      }
-    }
-    return mailbox;
   }
   // ===========================================================================
   // Message Operations
@@ -80304,20 +80365,26 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       for (const acct of accounts) {
         if (allMessages.length >= limit) break;
         const remaining = limit - allMessages.length;
-        const res = this.searchMessagesWithDiagnostics(
-          query,
-          mailbox,
-          acct.name,
-          remaining,
-          dateFrom,
-          dateTo,
-          from,
-          subject,
-          isRead,
-          isFlagged
-        );
-        allMessages.push(...res.messages);
-        mergeSearchDiagnostics(diagnostics, res.diagnostics);
+        try {
+          const res = this.searchMessagesWithDiagnostics(
+            query,
+            mailbox,
+            acct.name,
+            remaining,
+            dateFrom,
+            dateTo,
+            from,
+            subject,
+            isRead,
+            isFlagged
+          );
+          allMessages.push(...res.messages);
+          mergeSearchDiagnostics(diagnostics, res.diagnostics);
+        } catch (err) {
+          diagnostics.partial = true;
+          const message = err instanceof Error ? err.message : String(err);
+          diagnostics.notSearchedMailboxes.push(`${acct.name} / ${mailbox ?? "*"}: ${message}`);
+        }
       }
       return { messages: allMessages.slice(0, limit), diagnostics };
     }
@@ -80343,10 +80410,14 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
     }
     const scanThreshold = getMailboxScanThreshold();
     let searchCommand;
+    let resultMailbox = mailbox || "INBOX";
+    let rowsIncludeMailbox = !mailbox;
     if (mailbox) {
       const targetMailbox = this.resolveMailbox(mailbox, targetAccount);
+      resultMailbox = targetMailbox;
       const gmailInbox = isInboxScope(mailbox) ? gmailReceivingMailboxes(this.getCachedMailboxNames(targetAccount)) : null;
       if (gmailInbox) {
+        rowsIncludeMailbox = true;
         const nameList = appleScriptLowerNameList(gmailInbox);
         searchCommand = `
       ${dateSetup}set outputText to ""
@@ -80359,12 +80430,12 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         if msgCount >= ${limit} then exit repeat
         set mbName to ""
         try
-          set mbName to name of mb
+          ${mailboxPathFragment("mb", "mbName")}
         end try
         ignoring case
-          if _wantNames contains mbName then
+          if _wantNames contains (name of mb) then
             try
-              ${buildMessageRowLoop({ collection: `messages of mb ${searchCondition}`, limit, dedup: true, dateFilter })}
+              ${buildMessageRowLoop({ collection: `messages of mb ${searchCondition}`, limit, dedup: true, dateFilter, trailing: ` & "${FIELD_SEP}" & mbName` })}
             on error _errMsg number _errNum
               set _timedOut to true
               set _notSearched to _notSearched & mbName & "${DIAG_ITEM_SEP}"
@@ -80379,14 +80450,19 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       ${dateSetup}set outputText to ""
       set _timedOut to false
       set _notSearched to ""
-      set theMailbox to mailbox "${escapeForAppleScript(targetMailbox)}"
+      ${mailboxLookupFragment(mbIter, targetMailbox, "theMailbox")}
       set msgCount to 0
-      try
-        ${buildMessageRowLoop({ collection: `messages of theMailbox ${searchCondition}`, limit, dateFilter })}
-      on error _errMsg number _errNum
+      if theMailbox is missing value then
         set _timedOut to true
         set _notSearched to "${escapeForAppleScript(targetMailbox)}${DIAG_ITEM_SEP}"
-      end try
+      else
+        try
+          ${buildMessageRowLoop({ collection: `messages of theMailbox ${searchCondition}`, limit, dateFilter })}
+        on error _errMsg number _errNum
+          set _timedOut to true
+          set _notSearched to "${escapeForAppleScript(targetMailbox)}${DIAG_ITEM_SEP}"
+        end try
+      end if
       return outputText & "${DIAG_MARKER}timedOut=" & (_timedOut as string) & "${DIAG_FIELD_SEP}skipped=${DIAG_FIELD_SEP}notSearched=" & _notSearched
     `;
       }
@@ -80404,7 +80480,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         if msgCount >= ${limit} then exit repeat
         set mbName to ""
         try
-          set mbName to name of mb
+          ${mailboxPathFragment("mb", "mbName")}
         end try
         if ((current date) - _startedAt) > ${SEARCH_ACCOUNT_BUDGET_SECONDS} then
           set _timedOut to true
@@ -80444,15 +80520,15 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         }
       };
     }
-    return this.parseSearchResult(result.output, mailbox || "INBOX", targetAccount);
+    return this.parseSearchResult(result.output, resultMailbox, targetAccount, rowsIncludeMailbox);
   }
   /**
    * Split a per-account search payload into its message list and the DIAG
    * trailer, parse both, and return a SearchResult. See searchMessagesWithDiagnostics.
    */
-  parseSearchResult(output, mailbox, account) {
+  parseSearchResult(output, mailbox, account, rowsIncludeMailbox = false) {
     const { payload, diagnostics } = splitSearchDiagnostics(output, account);
-    const messages = payload.trim() ? this.parseMessageList(payload, mailbox, account) : [];
+    const messages = payload.trim() ? this.parseMessageList(payload, mailbox, account, rowsIncludeMailbox) : [];
     return { messages, diagnostics };
   }
   /**
@@ -80484,7 +80560,8 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
                 set msgFlagged to flagged status of msg as string
                 set msgJunk to junk mail status of msg as string
                 set msgDeleted to deleted status of msg as string
-                set msgMailbox to name of mb
+                set msgMailbox to ""
+                ${mailboxPathFragment("mb", "msgMailbox")}
                 set msgAccount to name of acct
                 set hasAtt to "false"
                 try
@@ -80545,7 +80622,9 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         set targetMb to missing value
         ignoring case
           repeat with mb in _mbs
-            if (name of mb) is "${escapeForAppleScript(resolved)}" then
+            set _mbPath to ""
+            ${mailboxPathFragment("mb", "_mbPath")}
+            if _mbPath is "${escapeForAppleScript(resolved)}" then
               set targetMb to mb
               exit repeat
             end if
@@ -80554,7 +80633,9 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         set targetMb to missing value
         ignoring case
           repeat with mb in mailboxes of acct
-            if (name of mb) is "${escapeForAppleScript(resolved)}" then
+            set _mbPath to ""
+            ${mailboxPathFragment("mb", "_mbPath")}
+            if _mbPath is "${escapeForAppleScript(resolved)}" then
               set targetMb to mb
               exit repeat
             end if
@@ -80799,9 +80880,15 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       for (const acct of accounts) {
         if (allMessages.length >= limit) break;
         const remaining = limit - allMessages.length;
-        const res = this.listMessagesWithDiagnostics(mailbox, acct.name, remaining, from, offset);
-        allMessages.push(...res.messages);
-        mergeSearchDiagnostics(diagnostics, res.diagnostics);
+        try {
+          const res = this.listMessagesWithDiagnostics(mailbox, acct.name, remaining, from, offset);
+          allMessages.push(...res.messages);
+          mergeSearchDiagnostics(diagnostics, res.diagnostics);
+        } catch (err) {
+          diagnostics.partial = true;
+          const message = err instanceof Error ? err.message : String(err);
+          diagnostics.notSearchedMailboxes.push(`${acct.name} / ${mailbox ?? "*"}: ${message}`);
+        }
       }
       return { messages: allMessages.slice(0, limit), diagnostics };
     }
@@ -80812,10 +80899,14 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
     const scanThreshold = getMailboxScanThreshold();
     const mbIter = local ? "_mbs" : "mailboxes";
     let listCommand;
+    let resultMailbox = mailbox || "INBOX";
+    let rowsIncludeMailbox = !mailbox;
     if (mailbox) {
       const targetMailbox = this.resolveMailbox(mailbox, targetAccount);
+      resultMailbox = targetMailbox;
       const gmailInbox = isInboxScope(mailbox) ? gmailReceivingMailboxes(this.getCachedMailboxNames(targetAccount)) : null;
       if (gmailInbox) {
+        rowsIncludeMailbox = true;
         const nameList = appleScriptLowerNameList(gmailInbox);
         listCommand = `
       set outputText to ""
@@ -80829,10 +80920,10 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         if msgCount >= ${limit} then exit repeat
         set mbName to ""
         try
-          set mbName to name of mb
+          ${mailboxPathFragment("mb", "mbName")}
         end try
         ignoring case
-          if _wantNames contains mbName then
+          if _wantNames contains (name of mb) then
             try
               ${buildMessageRowLoop({ collection: `messages of mb ${fromFilter}`, limit, offset, dedup: true, withAttachments: true, trailing: ` & "${FIELD_SEP}" & mbName` })}
             on error _errMsg number _errNum
@@ -80849,15 +80940,20 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       set outputText to ""
       set _timedOut to false
       set _notSearched to ""
-      set theMailbox to mailbox "${escapeForAppleScript(targetMailbox)}"
+      ${mailboxLookupFragment(mbIter, targetMailbox, "theMailbox")}
       set msgCount to 0
       set skipped to 0
-      try
-        ${buildMessageRowLoop({ collection: `messages of theMailbox ${fromFilter}`, limit, offset, withAttachments: true })}
-      on error _errMsg number _errNum
+      if theMailbox is missing value then
         set _timedOut to true
         set _notSearched to "${escapeForAppleScript(targetMailbox)}${DIAG_ITEM_SEP}"
-      end try
+      else
+        try
+          ${buildMessageRowLoop({ collection: `messages of theMailbox ${fromFilter}`, limit, offset, withAttachments: true })}
+        on error _errMsg number _errNum
+          set _timedOut to true
+          set _notSearched to "${escapeForAppleScript(targetMailbox)}${DIAG_ITEM_SEP}"
+        end try
+      end if
       return outputText & "${DIAG_MARKER}timedOut=" & (_timedOut as string) & "${DIAG_FIELD_SEP}skipped=${DIAG_FIELD_SEP}notSearched=" & _notSearched
     `;
       }
@@ -80876,7 +80972,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         if msgCount >= ${limit} then exit repeat
         set mbName to ""
         try
-          set mbName to name of mb
+          ${mailboxPathFragment("mb", "mbName")}
         end try
         if ((current date) - _startedAt) > ${SEARCH_ACCOUNT_BUDGET_SECONDS} then
           set _timedOut to true
@@ -80916,7 +81012,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         }
       };
     }
-    return this.parseSearchResult(result.output, mailbox || "INBOX", targetAccount);
+    return this.parseSearchResult(result.output, resultMailbox, targetAccount, rowsIncludeMailbox);
   }
   /**
    * Parse message list output from AppleScript.
@@ -80929,7 +81025,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
    * false-negative for MIME-embedded attachments (a known AppleScript
    * limitation). Use getMessage or list-attachments for authoritative info.
    */
-  parseMessageList(output, mailbox, account) {
+  parseMessageList(output, mailbox, account, rowsIncludeMailbox = false) {
     const items = output.split(RECORD_SEP);
     const messages = [];
     for (const item of items) {
@@ -80937,9 +81033,9 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       if (parts.length < 6) continue;
       let msgMailbox = mailbox;
       let hasAttachments = false;
-      if (parts.length >= 8) {
+      if (rowsIncludeMailbox && parts.length >= 7) {
         msgMailbox = parts[6];
-        hasAttachments = parts[7] === "true";
+        hasAttachments = parts.length >= 8 ? parts[7] === "true" : false;
       } else if (parts.length === 7) {
         hasAttachments = parts[6] === "true";
       }
@@ -81367,7 +81463,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
     const valid = [{ id, num: Number(id) }];
     const parsed = this.parseForensicStream(output, valid);
     const succeeded = parsed.okPositions.has(1);
-    const sameMailbox = (account, mailbox) => destination !== void 0 && destination.account === account && this.resolveMailbox(destination.mailbox, destination.account) === this.resolveMailbox(mailbox, account);
+    const sameMailbox = (account, mailbox) => destination !== void 0 && destination.account === account && this.resolveMailboxSafe(destination.mailbox, destination.account) === this.resolveMailboxSafe(mailbox, account);
     const home = parsed.recons[0];
     this.lastForensics = this.buildForensicReport(
       parsed,
@@ -81540,9 +81636,9 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
    * Move a message to a destination mailbox, with full nested-mailbox support.
    *
    * Resolving the destination as `mailbox "X" of account "Y"` only finds
-   * top-level mailboxes, so nested destinations (e.g. a "Moore" subfolder)
-   * silently failed. Instead we walk the target account's full mailbox tree and
-   * match by name. Resolution is:
+   * top-level mailboxes on some stores. Instead we walk the account's recursive
+   * mailbox collection, reconstruct each container path, and match by path.
+   * Resolution is:
    *   - account-scoped (won't move to a same-named mailbox in another account)
    *   - ambiguity-aware: if the name matches more than one mailbox in the
    *     account we refuse to guess and return an error — silently moving mail to
@@ -81613,15 +81709,17 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         return "1${FIELD_SEP}ok" & _pre & "${RECORD_SEP}" & _out`;
     const script = buildAppLevelScript(`
       try
-        -- \`mailboxes of account\` is already flat: it includes nested mailboxes
-        -- (named by path, e.g. "Processed/Vendors"). Descending via \`mailboxes of mb\`
-        -- is unreliable (it double-prepends the parent path), so we DON'T recurse \u2014
-        -- we match against this flat list by exact name and use the reference directly
-        -- (addressing \`mailbox "X" of account "Y"\` only finds some top-level mailboxes).
+        -- \`mailboxes of account\` recursively includes nested mailboxes, but
+        -- \`name of mb\` is only the leaf. Reconstruct each path from its
+        -- container chain so Inbox and Archive/Inbox remain distinct.
         set destName to "${safeMailbox}"
         set destMatches to {}
         repeat with mb in (mailboxes of account "${safeAccount}")
-          if (name of mb) is destName then set end of destMatches to mb
+          set _destPath to ""
+          ${mailboxPathFragment("mb", "_destPath")}
+          ignoring case
+            if _destPath is destName then set end of destMatches to mb
+          end ignoring
         end repeat
         if (count of destMatches) is 0 then return "error:Destination mailbox \\"" & destName & "\\" not found in account \\"${safeAccount}\\""
         if (count of destMatches) > 1 then return "error:Destination mailbox \\"" & destName & "\\" is ambiguous (" & (count of destMatches) & " matches) in account \\"${safeAccount}\\"; disambiguate or move by full path"
@@ -81927,7 +82025,7 @@ ${this.errorEmit("              ")}
       }
       const { okPositions } = parsed;
       const dest = forensics?.destination;
-      const sameMailbox = (account, mailbox) => dest !== void 0 && dest.account === account && this.resolveMailbox(dest.mailbox, dest.account) === this.resolveMailbox(mailbox, account);
+      const sameMailbox = (account, mailbox) => dest !== void 0 && dest.account === account && this.resolveMailboxSafe(dest.mailbox, dest.account) === this.resolveMailboxSafe(mailbox, account);
       const expectedFor = (account, mailbox, pos) => {
         if (sameMailbox(account, mailbox)) return null;
         if (pos !== null) return okPositions.has(pos) ? 1 : 0;
@@ -81973,7 +82071,11 @@ ${this.errorEmit("              ")}
         set destName to "${safeMailbox}"
         set destMatches to {}
         repeat with _dmb in (mailboxes of account "${safeAccount}")
-          if (name of _dmb) is destName then set end of destMatches to _dmb
+          set _destPath to ""
+          ${mailboxPathFragment("_dmb", "_destPath")}
+          ignoring case
+            if _destPath is destName then set end of destMatches to _dmb
+          end ignoring
         end repeat
         if (count of destMatches) is 0 then return "${BATCH_FATAL}Destination mailbox \\"" & destName & "\\" not found in account \\"${safeAccount}\\""
         if (count of destMatches) > 1 then return "${BATCH_FATAL}Destination mailbox \\"" & destName & "\\" is ambiguous (" & (count of destMatches) & " matches) in account \\"${safeAccount}\\"; move by full path"
@@ -82206,10 +82308,11 @@ ${this.errorEmit("              ")}
     const listCommand = (iterExpr) => `
       set mailboxList to {}
       repeat with mb in ${iterExpr}
-        set mbName to name of mb
+        set mbPath to ""
+        ${mailboxPathFragment("mb", "mbPath")}
         set mbUnread to unread count of mb
         set mbCount to count of messages of mb
-        set end of mailboxList to mbName & "${FIELD_SEP}" & mbUnread & "${FIELD_SEP}" & mbCount
+        set end of mailboxList to mbPath & "${FIELD_SEP}" & mbUnread & "${FIELD_SEP}" & mbCount
       end repeat
       set AppleScript's text item delimiters to "${RECORD_SEP}"
       return mailboxList as text
@@ -82257,8 +82360,10 @@ ${this.errorEmit("              ")}
   getUnreadCount(mailbox, account) {
     const targetAccount = this.resolveAccount(account);
     const targetMailbox = this.resolveMailbox(mailbox || "INBOX", targetAccount);
-    const safeMailbox = escapeForAppleScript(targetMailbox);
-    const command = `return unread count of mailbox "${safeMailbox}"`;
+    const command = `
+      ${mailboxLookupFragment("mailboxes", targetMailbox, "theMailbox")}
+      if theMailbox is missing value then error "Mailbox \\"${escapeForAppleScript(targetMailbox)}\\" not found"
+      return unread count of theMailbox`;
     const script = buildAccountScopedScript(targetAccount, command);
     const result = executeAppleScript(script, { timeoutMs: 6e4 });
     if (!result.success) {
@@ -82314,11 +82419,12 @@ ${this.errorEmit("              ")}
       return { success: false, error: disabled };
     }
     const targetMailbox = this.resolveMailbox(name, targetAccount);
-    const safeName = escapeForAppleScript(targetMailbox);
     const safeAccount = escapeForAppleScript(targetAccount);
     const script = buildAppLevelScript(`
       try
-        delete mailbox "${safeName}" of account "${safeAccount}"
+        ${mailboxLookupFragment(`mailboxes of account "${safeAccount}"`, targetMailbox, "theMailbox")}
+        if theMailbox is missing value then error "Mailbox \\"${escapeForAppleScript(targetMailbox)}\\" not found in account \\"${safeAccount}\\""
+        delete theMailbox
         return "ok"
       on error errMsg
         return "error:" & errMsg
@@ -82344,6 +82450,14 @@ ${this.errorEmit("              ")}
       console.error(`Refusing to rename mailbox: ${serverSide}`);
       return { success: false, error: serverSide };
     }
+    let resolvedOld;
+    try {
+      resolvedOld = this.resolveMailbox(oldName, targetAccount);
+    } catch (err) {
+      const error2 = err instanceof Error ? err.message : String(err);
+      console.error(`Refusing to rename mailbox: ${error2}`);
+      return { success: false, error: error2 };
+    }
     const created = this.createMailbox(newName, targetAccount);
     if (!created.success) {
       return {
@@ -82351,15 +82465,25 @@ ${this.errorEmit("              ")}
         error: created.error ?? `Could not create the destination mailbox "${newName}" needed for the rename.`
       };
     }
-    const resolvedOld = this.resolveMailbox(oldName, targetAccount);
-    const resolvedNew = this.resolveMailbox(newName, targetAccount);
-    const safeOld = escapeForAppleScript(resolvedOld);
-    const safeNew = escapeForAppleScript(resolvedNew);
+    let resolvedNew;
+    try {
+      resolvedNew = this.resolveMailbox(newName, targetAccount);
+    } catch (err) {
+      const rolledBack = this.deleteMailboxIfEmpty(newName, targetAccount);
+      let error2 = err instanceof Error ? err.message : String(err);
+      error2 += rolledBack ? ` The empty destination mailbox "${newName}" was rolled back, so no orphan was left.` : ` The destination mailbox "${newName}" was created and could not be auto-removed; delete it manually if it is an empty leftover.`;
+      console.error(`Failed to rename mailbox: ${error2}`);
+      this.invalidateCache();
+      return { success: false, error: error2 };
+    }
     const safeAccount = escapeForAppleScript(targetAccount);
+    const mbColl = `mailboxes of account "${safeAccount}"`;
     const moveScript = buildAppLevelScript(`
       try
-        set srcMailbox to mailbox "${safeOld}" of account "${safeAccount}"
-        set destMailbox to mailbox "${safeNew}" of account "${safeAccount}"
+        ${mailboxLookupFragment(mbColl, resolvedOld, "srcMailbox")}
+        ${mailboxLookupFragment(mbColl, resolvedNew, "destMailbox")}
+        if srcMailbox is missing value then error "Mailbox \\"${escapeForAppleScript(resolvedOld)}\\" not found in account \\"${safeAccount}\\""
+        if destMailbox is missing value then error "Mailbox \\"${escapeForAppleScript(resolvedNew)}\\" not found in account \\"${safeAccount}\\""
         set srcCount to count of messages of srcMailbox
         set msgs to (every message of srcMailbox)
         repeat with m in msgs
@@ -82369,7 +82493,7 @@ ${this.errorEmit("              ")}
         end repeat
         set srcAfter to count of messages of srcMailbox
         if srcAfter is 0 then
-          delete mailbox "${safeOld}" of account "${safeAccount}"
+          delete srcMailbox
           return "ok${FIELD_SEP}" & srcCount
         else
           return "partial${FIELD_SEP}" & (srcCount - srcAfter) & "${FIELD_SEP}" & srcCount & "${FIELD_SEP}" & srcAfter
@@ -82866,14 +82990,16 @@ end tell`;
     return accounts;
   }
   /**
-   * Fetches mailbox names for an account directly from Mail.app.
+   * Fetches canonical mailbox paths for an account directly from Mail.app.
    * Used internally by the cache; prefer getCachedMailboxNames().
    */
   fetchMailboxNames(account) {
     const body = `
       set mbNames to {}
       repeat with mb in ${isLocalStoreLabel(account) ? "_mbs" : "mailboxes"}
-        set end of mbNames to name of mb
+        set mbPath to ""
+        ${mailboxPathFragment("mb", "mbPath")}
+        set end of mbNames to mbPath
       end repeat
       return mbNames
     `;
@@ -82977,10 +83103,22 @@ end tell`;
     if (a.markFlagged) actionStmts.push(`        set mark flagged of newRule to true`);
     if (a.delete) actionStmts.push(`        set delete message of newRule to true`);
     if (a.moveTo) {
-      const safeMbox = escapeForAppleScript(a.moveTo);
-      const mboxRef = a.moveToAccount ? `mailbox "${safeMbox}" of account "${escapeForAppleScript(a.moveToAccount)}"` : `mailbox "${safeMbox}"`;
       actionStmts.push(`        set should move message of newRule to true`);
-      actionStmts.push(`        set move message of newRule to ${mboxRef}`);
+      if (a.moveToAccount) {
+        const resolvedMbox = this.resolveMailbox(a.moveTo, a.moveToAccount);
+        const safeAccount = escapeForAppleScript(a.moveToAccount);
+        actionStmts.push(
+          `        ${mailboxLookupFragment(`mailboxes of account "${safeAccount}"`, resolvedMbox, "_ruleDestMb")}`
+        );
+        actionStmts.push(
+          `        if _ruleDestMb is missing value then error "Mailbox \\"${escapeForAppleScript(resolvedMbox)}\\" not found in account \\"${safeAccount}\\""`
+        );
+        actionStmts.push(`        set move message of newRule to _ruleDestMb`);
+      } else {
+        actionStmts.push(
+          `        set move message of newRule to mailbox "${escapeForAppleScript(a.moveTo)}"`
+        );
+      }
     }
     if (!actionStmts.length) {
       return { success: false, error: "A rule needs at least one action." };
@@ -86996,7 +87134,7 @@ function appendLocalStoreRows(rows, failedAccounts) {
 registerTool(
   "list-mailboxes",
   {
-    description: 'Use when: discovering the mailbox/folder names (and unread/message counts) available in an account, e.g. before moving messages or searching a specific mailbox.\nReturns: each mailbox\'s name with its unread (and, for IMAP, total message) count, plus a count. A source that could not be read is NAMED \u2014 the result carries `partial: true` + `failedAccounts` and the list is a floor, not the complete set \u2014 and a listing Mail refused outright (e.g. an account that does not exist) returns an ERROR naming the accounts that do exist, never an empty list.\nDo not use when: you want the messages inside a mailbox (use list-messages or search-messages) or the list of accounts (use list-accounts).\nNote: Mail\'s local "On My Mac" mailboxes are not part of any account, so they are reported under the synthetic account label "On My Mac" \u2014 an unscoped call includes them, and `account: "On My Mac"` lists only them. They will not appear in list-accounts, which reports real accounts only.',
+    description: 'Use when: discovering the mailbox/folder paths (and unread/message counts) available in an account, e.g. before moving messages or searching a specific mailbox.\nReturns: each mailbox\'s canonical account-relative path in `name`, unread/message counts, and a total count. Use the full path for nested mailboxes (for example `Archive/Inbox`); a top-level `Inbox` remains `Inbox`. A source that could not be read is NAMED \u2014 the result carries `partial: true` + `failedAccounts` and the list is a floor, not the complete set \u2014 and a listing Mail refused outright (e.g. an account that does not exist) returns an ERROR naming the accounts that do exist, never an empty list.\nDo not use when: you want the messages inside a mailbox (use list-messages or search-messages) or the list of accounts (use list-accounts).\nNote: Mail\'s local "On My Mac" mailboxes are not part of any account, so they are reported under the synthetic account label "On My Mac" \u2014 an unscoped call includes them, and `account: "On My Mac"` lists only them. They will not appear in list-accounts, which reports real accounts only.',
     inputSchema: {
       account: external_exports.string().optional().describe("Account to list mailboxes from")
     },

package/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md

@@ -60,8 +60,8 @@ the MCP runtime from your Homebrew/dev Node, which can keep updating freely.
    curl -O https://nodejs.org/dist/$VER/node-$VER-$ARCH.tar.gz
    curl -O https://nodejs.org/dist/$VER/SHASUMS256.txt
    grep "  node-$VER-$ARCH.tar.gz$" SHASUMS256.txt | shasum -a 256 -c -   # must print OK
-   tar -xzf node-$VER-$ARCH.tar.gz
-   ln -sfn node-$VER-$ARCH node-current
+   mkdir -p node-current
+   tar -xzf node-$VER-$ARCH.tar.gz --strip-components=1 -C node-current
    ```
 
 2. Confirm it's Developer-ID signed:
@@ -98,12 +98,36 @@ the MCP runtime from your Homebrew/dev Node, which can keep updating freely.
    - *Automation*: the first time the server drives an app you'll get a one-time
      `"node" wants to control "<App>"` prompt — click **Allow**.
 
-   Both grants are keyed to the official Node's stable signature, so you should
-   not be asked again — including after future Node updates. You can delete the
-   stale "node" rows from the Full Disk Access list.
+   ⚠️ **A TCC grant is keyed to the binary's resolved *path*, not only to its
+   signature.** Because the steps above unpack Node into a fixed directory
+   (`~/mcp-runtime/node-current`) rather than a versioned one, that path never
+   moves and the grants survive Node updates — see "Updating" below. If you
+   instead point `node-current` at a `node-vX.Y.Z-…` directory, every update
+   changes the resolved path, presents a brand-new ungranted identity, and you
+   will be re-prompted for all of it.
+
+   You can delete any stale "node" rows from the Full Disk Access list.
 
 ### Updating the dedicated Node later
 
-Drop a newer official LTS tarball into `~/mcp-runtime/`, repoint the
-`node-current` symlink, and restart your client. The signing identity is
-unchanged, so existing grants carry over — no re-approval.
+Replace the **contents** of the same directory — do not create a new one and do
+not repoint anything:
+
+```bash
+VER=v24.19.0 ARCH=darwin-arm64
+cd ~/mcp-runtime
+curl -O https://nodejs.org/dist/$VER/node-$VER-$ARCH.tar.gz
+curl -O https://nodejs.org/dist/$VER/SHASUMS256.txt
+grep "  node-$VER-$ARCH.tar.gz$" SHASUMS256.txt | shasum -a 256 -c -   # must print OK
+rm -rf node-current && mkdir -p node-current
+tar -xzf node-$VER-$ARCH.tar.gz --strip-components=1 -C node-current
+```
+
+The path is unchanged and the official builds are Developer-ID signed with a
+requirement that pins identifier + Team ID (no cdhash), so **both** halves of
+the grant still match: existing grants carry over with no re-approval.
+
+⚠️ **Restart your MCP client afterwards.** Replacing the binary unlinks the one
+any already-running server is executing; macOS then cannot validate that path,
+so those processes fail with *"Permission denied"* until they are restarted.
+Nothing is wrong with your grants — a freshly launched server works fine.

package/package.json

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