apple-mail-mcp 2.13.2 → 2.14.1

package/README.md

@@ -935,9 +935,23 @@ List all mailboxes for an account.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `account` | string | No | Account to list from |
-
-**Returns:** List of mailbox names with message and unread counts.
+| `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.
+
+**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
+**`On My Mac`**. An unscoped call includes them (listed last); `account="On My
+Mac"` lists only them. `on my computer`, `local` and `local folders` are accepted
+as aliases.
+
+They deliberately do **not** appear in `list-accounts`, which reports real
+accounts only: the local store is a store, not an account. Nothing selects it
+implicitly — omitting `account` still resolves to a real account for every other
+tool.
 
 ---
 

package/build/index.js

@@ -79129,6 +79129,24 @@ function buildAccountScopedScript(account, command) {
     end tell
   `;
 }
+var LOCAL_STORE_LABEL = "On My Mac";
+var LOCAL_STORE_ALIASES = ["on my mac", "on my computer", "local", "local folders"];
+function isLocalStoreLabel(name) {
+  return name !== void 0 && LOCAL_STORE_ALIASES.includes(name.trim().toLowerCase());
+}
+function localMailboxBindingFragment() {
+  return `
+      set _mbs to {}
+      repeat with _m in mailboxes
+        set _isLoc to false
+        try
+          if (account of _m) is missing value then set _isLoc to true
+        on error
+          set _isLoc to true
+        end try
+        if _isLoc then set end of _mbs to (contents of _m)
+      end repeat`;
+}
 function groupKey(account, mailbox) {
   return `${account}\0${mailbox}`;
 }
@@ -79452,16 +79470,61 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         set _sMiss to ""
         set _sPairs to {}
         set _sChunk to ${chunk}
+        -- The mailbox's MEASURED length, emitted only when it disagrees with the
+        -- count (#187). -1 = "not measured", which is the normal case: the probe
+        -- only runs a binary search when the count's last position is unreadable.
+        -- Initialised here, not in the else-branch, or the skipped/unavailable
+        -- paths would reference an unbound variable when emitting.
+        set _sTrue to -1
         if ${countVar} < 0 then
           set _sStatus to "unavailable"
         else if ${countVar} > ${max} then
           set _sStatus to "skipped"
           set _sPayload to "mailbox holds " & (${countVar} as string) & " messages, above ${AUDIT_SNAPSHOT_MAX_ENV}=${max}"
         else
+          -- #187: the count can read HIGH, and an out-of-range range RAISES as
+          -- a whole rather than clamping. On a mailbox smaller than one chunk
+          -- there is only ONE slice, so a high count made it fail entirely:
+          -- _sPairs stayed empty, the status collapsed to "unavailable", and
+          -- the record carried no holes and no warning. The collateral
+          -- instrument switched itself off in exactly the stale direction #155
+          -- evidences, silently.
+          --
+          -- So establish a bound that actually EXISTS before slicing. If the
+          -- last position the count claims is readable, the count is not high
+          -- and this costs one probe. Otherwise binary-search the true end,
+          -- which is O(log n) probes and also MEASURES how stale the count is.
+          set _sBound to ${countVar}
+          if _sBound > 0 then
+            set _sEndOk to false
+            try
+              get id of message _sBound of ${mbVar}
+              set _sEndOk to true
+            end try
+            if not _sEndOk then
+              set _sLoB to 0
+              set _sHiB to _sBound
+              repeat while (_sHiB - _sLoB) > 1
+                set _sMid to (_sLoB + _sHiB) div 2
+                set _sMidOk to false
+                try
+                  get id of message _sMid of ${mbVar}
+                  set _sMidOk to true
+                end try
+                if _sMidOk then
+                  set _sLoB to _sMid
+                else
+                  set _sHiB to _sMid
+                end if
+              end repeat
+              set _sBound to _sLoB
+              set _sTrue to _sLoB
+            end if
+          end if
           set _sLo to 1
-          repeat while _sLo <= ${countVar}
+          repeat while _sLo <= _sBound
             set _sHi to _sLo + _sChunk - 1
-            if _sHi > ${countVar} then set _sHi to ${countVar}
+            if _sHi > _sBound then set _sHi to _sBound
             set _sGot to false
             repeat with _sTry from 1 to ${SNAPSHOT_SLICE_ATTEMPTS}
               set _sIds to {}
@@ -79519,7 +79582,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
           -- PARTIAL under the existing rules and withholds the halves a
           -- truncation would poison.
           try
-            set _sOverId to ((id of message (${countVar} + 1) of ${mbVar}) as string)
+            set _sOverId to ((id of message (_sBound + 1) of ${mbVar}) as string)
             -- A specifier that CLAMPS rather than raising hands back the LAST
             -- message instead of failing. That is not evidence of a truncation,
             -- so only an id this enumeration did not already record counts.
@@ -79529,7 +79592,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
             end repeat
             if not _sSeen then
               if _sMiss is not "" then set _sMiss to _sMiss & ","
-              set _sMiss to _sMiss & ((${countVar} + 1) as string) & "-end"
+              set _sMiss to _sMiss & ((_sBound + 1) as string) & "-end"
             end if
           end try
           if _sMiss is not "" then
@@ -79544,7 +79607,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
           set _sPayload to _sPairs as string
           set AppleScript's text item delimiters to _sTid
         end if
-        set _out to _out & "${SNAP_TAG}${FIELD_SEP}" & ${acctExpr} & "${FIELD_SEP}" & ${mbExpr} & "${FIELD_SEP}${phase}${FIELD_SEP}" & _sStatus & "${FIELD_SEP}" & _sPayload & "${FIELD_SEP}" & _sMiss & "${RECORD_SEP}"`;
+        set _out to _out & "${SNAP_TAG}${FIELD_SEP}" & ${acctExpr} & "${FIELD_SEP}" & ${mbExpr} & "${FIELD_SEP}${phase}${FIELD_SEP}" & _sStatus & "${FIELD_SEP}" & _sPayload & "${FIELD_SEP}" & _sMiss & "${FIELD_SEP}" & (_sTrue as string) & "${RECORD_SEP}"`;
   }
   /**
    * AppleScript capturing the message the op is ABOUT to touch into `_pre`,
@@ -79605,13 +79668,15 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         continue;
       }
       if (f[0] === SNAP_TAG) {
+        const measured = f[7] !== void 0 && f[7] !== "" ? Number(f[7]) : -1;
         snaps.push({
           account: f[1] ?? "",
           mailbox: f[2] ?? "",
           phase: f[3] === "after" ? "after" : "before",
           status: f[4] ?? "",
           payload: f[5] ?? "",
-          miss: f[6] ?? ""
+          miss: f[6] ?? "",
+          ...Number.isFinite(measured) && measured >= 0 ? { measuredLength: measured } : {}
         });
         continue;
       }
@@ -79795,6 +79860,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       const unrequested = disappeared.filter(
         (e) => !requestedNumericIds.has(canonicalNumericId(e.id))
       );
+      const countStale = [b, a].filter((s) => s.measuredLength !== void 0).map((s) => ({ phase: s.phase, measuredLength: s.measuredLength }));
       const holes = [b, a].filter((s) => s.miss !== "").map((s) => ({ phase: s.phase, ranges: s.miss }));
       if (holes.length === 0) {
         collateral.push({
@@ -79803,7 +79869,8 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
           snapshot: "ok",
           disappeared,
           unrequested,
-          appeared
+          appeared,
+          ...countStale.length ? { countStale } : {}
         });
         continue;
       }
@@ -79815,6 +79882,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         account: g.account,
         mailbox: g.mailbox,
         snapshot: "partial",
+        ...countStale.length ? { countStale } : {},
         skipReason: `Mail would not read ${holes.map((h) => `${h.ranges} (${h.phase})`).join(", ")} of this mailbox, so the snapshot has a hole in it. ` + (derivable.length > 0 ? `Still derivable and reported: ${derivable.join(" and ")}. ` : `Neither half of the diff is derivable from it. `) + `Anything the unread range could refute is omitted rather than guessed \u2014 an absent field here means "not computable", not "empty".`,
         unobserved: holes,
         ...a.miss === "" ? { disappeared, unrequested } : {},
@@ -81983,10 +82051,11 @@ ${this.errorEmit("              ")}
    * List all mailboxes for an account.
    */
   listMailboxes(account, options = {}) {
-    const targetAccount = this.resolveAccount(account);
-    const listCommand = `
+    const local = isLocalStoreLabel(account);
+    const targetAccount = local ? LOCAL_STORE_LABEL : this.resolveAccount(account);
+    const listCommand = (iterExpr) => `
       set mailboxList to {}
-      repeat with mb in mailboxes
+      repeat with mb in ${iterExpr}
         set mbName to name of mb
         set mbUnread to unread count of mb
         set mbCount to count of messages of mb
@@ -81995,7 +82064,8 @@ ${this.errorEmit("              ")}
       set AppleScript's text item delimiters to "${RECORD_SEP}"
       return mailboxList as text
     `;
-    const script = buildAccountScopedScript(targetAccount, listCommand);
+    const script = local ? buildAppLevelScript(`${localMailboxBindingFragment()}
+      ${listCommand("_mbs")}`) : buildAccountScopedScript(targetAccount, listCommand("mailboxes"));
     const result = executeAppleScript(script, { timeoutMs: options.timeoutMs ?? 6e4 });
     if (!result.success) {
       console.error(`Failed to list mailboxes: ${result.error}`);
@@ -84653,19 +84723,15 @@ function withErrorHandling(handler, errorPrefix) {
 }
 
 // src/tools/mailboxListing.ts
-var LOCAL_STORE_NAMES = ["on my mac", "on my computer", "local", "local folders"];
-function isLocalStoreName(name) {
-  return LOCAL_STORE_NAMES.includes(name.trim().toLowerCase());
-}
 function unlistableStoreError(account, error2, knownAccounts) {
   const scope = account ? ` for "${account}"` : "";
   const parts = [`Could not list mailboxes${scope}: ${error2 ?? "Mail declined the request"}`];
   if (knownAccounts.length > 0) {
     parts.push(`Accounts on this Mac: ${knownAccounts.join(", ")}.`);
   }
-  if (account && isLocalStoreName(account)) {
+  if (account && isLocalStoreLabel(account)) {
     parts.push(
-      `"${account}" is Mail's LOCAL store, not an account \u2014 its mailboxes are not children of any account, so they cannot be reached with an \`account\` argument. Enumerating them is not yet supported.`
+      `"${account}" addresses Mail's LOCAL store, which IS listable \u2014 it is read at the application level rather than through an account, so this failure is not "no such account". Something went wrong reading the local store itself.`
     );
   }
   return parts.join("\n\n");
@@ -86709,10 +86775,26 @@ ${r.base64}`,
     );
   }, "Error fetching attachment")
 );
+function appendLocalStoreRows(rows, failedAccounts) {
+  const checked = mailManager.listMailboxesChecked(LOCAL_STORE_LABEL);
+  if (checked.failed) {
+    console.error(`list-mailboxes failed for "${LOCAL_STORE_LABEL}": ${checked.error}`);
+    failedAccounts.push(LOCAL_STORE_LABEL);
+    return;
+  }
+  for (const mb of checked.mailboxes) {
+    rows.push({
+      name: `${LOCAL_STORE_LABEL}/${mb.name}`,
+      account: LOCAL_STORE_LABEL,
+      unreadCount: mb.unreadCount,
+      messageCount: mb.messageCount
+    });
+  }
+}
 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 and are not currently enumerated by this tool.",
+    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.',
     inputSchema: {
       account: external_exports.string().optional().describe("Account to list mailboxes from")
     },
@@ -86778,6 +86860,7 @@ ${list2}`, structured3);
           });
         }
       }
+      appendLocalStoreRows(rows, failedAccounts);
       const partial2 = failedAccounts.length > 0;
       const structured2 = {
         mailboxes: rows,
@@ -86806,7 +86889,13 @@ ${list}${caveat}`, structured2);
         )
       );
     }
-    const structured = { mailboxes, count: mailboxes.length };
+    const localFailures = [];
+    if (account === void 0) appendLocalStoreRows(mailboxes, localFailures);
+    const structured = {
+      mailboxes,
+      count: mailboxes.length,
+      ...localFailures.length ? { partial: true, failedAccounts: localFailures } : {}
+    };
     if (mailboxes.length === 0) {
       return successResponse("No mailboxes found", structured);
     }

package/package.json

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