apple-mail-mcp 2.13.1 → 2.14.0

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}`;
 }
@@ -81983,10 +82001,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 +82014,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}`);
@@ -84652,6 +84672,21 @@ function withErrorHandling(handler, errorPrefix) {
   };
 }
 
+// src/tools/mailboxListing.ts
+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 && isLocalStoreLabel(account)) {
+    parts.push(
+      `"${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");
+}
+
 // src/tools/batchResults.ts
 async function hybridBatchCounts(ids, appleFn, imapFn) {
   const distinctIds = [...new Set(ids)];
@@ -86690,16 +86725,36 @@ ${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.\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).",
+    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")
     },
     outputSchema: {
       mailboxes: external_exports.array(external_exports.object({}).passthrough()).optional(),
-      count: external_exports.number().optional()
+      count: external_exports.number().optional(),
+      // Declared explicitly: the SDK stamps additionalProperties:false on a bare
+      // zod shape, so an undeclared key makes the CLIENT reject the result.
+      partial: external_exports.boolean().optional(),
+      failedAccounts: external_exports.array(external_exports.string()).optional()
     }
   },
   withErrorHandling(async ({ account }) => {
@@ -86721,6 +86776,7 @@ ${list2}`, structured3);
       }
       const configs = resolveImapConfigs();
       const rows = [];
+      const failedAccounts = [];
       for (const config2 of configs) {
         try {
           const boxes = await imapListMailboxes({ config: config2 });
@@ -86734,11 +86790,18 @@ ${list2}`, structured3);
           }
         } catch (e) {
           console.error(`IMAP list-mailboxes failed for "${config2.accountLabel}": ${String(e)}`);
+          failedAccounts.push(config2.accountLabel);
         }
       }
       const { appleScriptOnly } = partitionAccountsForCounts(mailManager.listAccounts(), configs);
       for (const acct of appleScriptOnly) {
-        for (const mb of mailManager.listMailboxes(acct.name)) {
+        const checked = mailManager.listMailboxesChecked(acct.name);
+        if (checked.failed) {
+          console.error(`list-mailboxes failed for "${acct.name}": ${checked.error}`);
+          failedAccounts.push(acct.name);
+          continue;
+        }
+        for (const mb of checked.mailboxes) {
           rows.push({
             name: `${acct.name}/${mb.name}`,
             account: acct.name,
@@ -86747,14 +86810,42 @@ ${list2}`, structured3);
           });
         }
       }
-      const structured2 = { mailboxes: rows, count: rows.length };
-      if (rows.length === 0) return successResponse("No mailboxes found", structured2);
+      appendLocalStoreRows(rows, failedAccounts);
+      const partial2 = failedAccounts.length > 0;
+      const structured2 = {
+        mailboxes: rows,
+        count: rows.length,
+        ...partial2 ? { partial: partial2, failedAccounts } : {}
+      };
+      const caveat = partial2 ? `
+
+PARTIAL \u2014 could not read: ${failedAccounts.join(", ")}. This list is incomplete.` : "";
+      if (rows.length === 0) {
+        return partial2 ? errorResponse(
+          `Could not list mailboxes from any source. Failed: ${failedAccounts.join(", ")}.`
+        ) : successResponse("No mailboxes found", structured2);
+      }
       const list = rows.map((b) => `  - ${b.name} (${b.unreadCount} unread)`).join("\n");
       return successResponse(`Found ${rows.length} mailbox(es):
-${list}`, structured2);
+${list}${caveat}`, structured2);
     }
-    const mailboxes = mailManager.listMailboxes(account);
-    const structured = { mailboxes, count: mailboxes.length };
+    const { mailboxes, failed, error: error2 } = mailManager.listMailboxesChecked(account);
+    if (failed) {
+      return errorResponse(
+        unlistableStoreError(
+          account,
+          error2,
+          mailManager.listAccounts().map((a) => a.name)
+        )
+      );
+    }
+    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.1",
+  "version": "2.14.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",