apple-mail-mcp 2.10.7 → 2.10.9

package/README.md

@@ -486,6 +486,7 @@ for an explicitly-named IMAP account, never on an omitted account.
 | `APPLE_MAIL_MCP_IMAP_IDLE` | No | `0` | Set `1` to enable IMAP IDLE push notifications (new-mail alerts) for every configured account |
 | `APPLE_MAIL_MCP_IMAP_IDLE_MS` | No | `30000` | Idle timeout (ms) before a pooled IMAP connection is closed (`0` = never close) |
 | `APPLE_MAIL_MCP_STATS_BUDGET_MS` | No | `25000` | Per-account wall-clock budget for `get-mail-stats` (minimum `1000`). Raise it for very large accounts |
+| `APPLE_MAIL_MCP_STATS_DEADLINE_MS` | No | `50000` | Overall wall-clock deadline for one `get-mail-stats` call (minimum `2000`), measured from when the request arrived and covering time queued behind other tool calls, account enumeration **and** every per-account read. Keep it below your client's request timeout |
 
 **Multiple IMAP accounts (C2):** set `APPLE_MAIL_MCP_IMAP_ACCOUNTS` to a JSON array, e.g.
 `[{"account":"Work","user":"me@co.com","host":"imap.co.com","keychainService":"imap.co.com"}]`.
@@ -775,9 +776,15 @@ Move a message to a different mailbox.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Message ID |
-| `mailbox` | string | Yes | Destination mailbox |
+| `mailbox` | string | Yes | Destination mailbox — full path (`Work/Archive`) or a leaf name that is unique on the account |
 | `account` | string | No | Account containing mailbox |
 
+A destination is matched first as a full path, then as a leaf name. If a leaf
+name matches **more than one** mailbox (e.g. `Archive` under both `Work` and
+`Thornlands`), the move is refused with an error naming every candidate — pass
+the full path. The same applies to `batch-move-messages`, `delete-mailbox` and
+`rename-mailbox`.
+
 ---
 
 #### `list-attachments`
@@ -1157,6 +1164,28 @@ overruns is reported via `partial: true` + `failedAccounts` rather than being
 folded in as a silent zero; a scoped call to a single account returns an error
 naming the budget instead. Raise the budget if you have a very large account.
 
+The whole call is additionally bounded by one wall-clock deadline,
+`APPLE_MAIL_MCP_STATS_DEADLINE_MS` (default `50000`), which covers the Mail.app
+account enumeration as well as every per-account read. Per-step budgets alone
+were not enough: their worst cases **add up**, and the sum could exceed a
+client's request timeout, so the call died with nothing returned instead of
+degrading. Keep the deadline below your MCP client's request timeout — whatever
+cannot be read inside it is named in `failedAccounts`, so you always get a
+partial answer rather than a dead call.
+
+**Concurrent `get-mail-stats` calls do not run concurrently.** Tool calls are
+serialized so they cannot race into Mail.app's single-threaded AppleScript
+dispatch, so each call waits for the ones ahead of it and per-call latency grows
+with queue depth — N concurrent calls take about N × the single-call cost. Since
+this is the most expensive read tool, that is very visible here: measured on 3
+IMAP accounts, three concurrent calls returned at 5.5s / 10.3s / 15.6s against a
+~5.2s solo cost. The deadline is measured from when the request **arrived**, so
+that wait is spent from the same budget as the work: a call that waited ≥1s
+reports `queueWaitMs`, and one that arrives with its deadline already spent
+returns straight away naming the queue rather than starting work whose answer
+would land after your client has given up. Issue these calls one at a time, and
+prefer `get-unread-count` when a single number will do.
+
 ---
 
 #### `get-sync-status`

package/build/index.js

@@ -78388,6 +78388,12 @@ var AppleMailManager = class {
    * presenting a fallback zero/empty as a real answer. (#130)
    */
   lastAccountsError = null;
+  /**
+   * Same, for the mailbox listing — read via `listMailboxesChecked()`. Kept
+   * separate from `lastAccountsError` so a failed mailbox read on one account
+   * can't be misread as the account enumeration having failed. (#135)
+   */
+  lastMailboxesError = null;
   /**
    * Remembers where each message id was last seen: id → {account, mailbox}.
    *
@@ -78417,12 +78423,12 @@ var AppleMailManager = class {
   /**
    * Returns cached accounts or fetches fresh data if cache is expired/empty.
    */
-  getCachedAccounts() {
+  getCachedAccounts(options = {}) {
     const now = Date.now();
     if (this.cache.accounts && now < this.cache.accounts.expiry) {
       return this.cache.accounts.data;
     }
-    const accounts = this.fetchAccounts();
+    const accounts = this.fetchAccounts(options);
     if (accounts === null) {
       return this.cache.accounts?.data ?? [];
     }
@@ -80187,7 +80193,7 @@ var AppleMailManager = class {
   /**
    * List all mailboxes for an account.
    */
-  listMailboxes(account) {
+  listMailboxes(account, options = {}) {
     const targetAccount = this.resolveAccount(account);
     const listCommand = `
       set mailboxList to {}
@@ -80201,9 +80207,10 @@ var AppleMailManager = class {
       return mailboxList as text
     `;
     const script = buildAccountScopedScript(targetAccount, listCommand);
-    const result = executeAppleScript(script, { timeoutMs: 6e4 });
+    const result = executeAppleScript(script, { timeoutMs: options.timeoutMs ?? 6e4 });
     if (!result.success) {
       console.error(`Failed to list mailboxes: ${result.error}`);
+      this.lastMailboxesError = result.error ?? "AppleScript transport failed";
       return [];
     }
     if (!result.output.trim()) return [];
@@ -80221,6 +80228,20 @@ var AppleMailManager = class {
     }
     return mailboxes;
   }
+  /**
+   * listMailboxes() plus whether the underlying AppleScript read actually worked.
+   *
+   * An empty list is ambiguous on its own — Mail with no mailboxes and a timed-out
+   * transport both produce `[]`, and folding the second into a total as 0 is the
+   * silent-zero class #130 fixed elsewhere. A caller summing counts across
+   * accounts needs to tell them apart. (#135)
+   */
+  listMailboxesChecked(account, options = {}) {
+    this.lastMailboxesError = null;
+    const mailboxes = this.listMailboxes(account, options);
+    const error2 = this.lastMailboxesError;
+    return error2 ? { mailboxes, failed: true, error: error2 } : { mailboxes, failed: false };
+  }
   /**
    * Get unread count for a mailbox.
    */
@@ -80756,18 +80777,22 @@ end tell`;
   /**
    * List all mail accounts (uses cache).
    */
-  listAccounts() {
-    return this.getCachedAccounts();
+  listAccounts(options = {}) {
+    return this.getCachedAccounts(options);
   }
   /**
    * listAccounts() plus whether the underlying AppleScript read actually worked.
    *
    * `failed: true` means the list is a fallback (stale cache or empty) because the
    * transport errored — NOT that Mail has no accounts. (#130)
+   *
+   * `timeoutMs` bounds the AppleScript read when the cache is cold, so a caller
+   * working to an overall deadline can spend a known slice here instead of the
+   * blanket 30s. A cache hit costs nothing and ignores it. (#135)
    */
-  listAccountsChecked() {
+  listAccountsChecked(options = {}) {
     this.lastAccountsError = null;
-    const accounts = this.getCachedAccounts();
+    const accounts = this.getCachedAccounts(options);
     const error2 = this.lastAccountsError;
     return error2 ? { accounts, failed: true, error: error2 } : { accounts, failed: false };
   }
@@ -80792,7 +80817,7 @@ end tell`;
    * "Mail answered, and there genuinely are no accounts" — collapsing the two is
    * what let a wedged transport report a confident "No Mail accounts found". (#130)
    */
-  fetchAccounts() {
+  fetchAccounts(options = {}) {
     const script = buildAppLevelScript(`
       set accountList to {}
       repeat with acct in accounts
@@ -80808,7 +80833,10 @@ end tell`;
       set AppleScript's text item delimiters to "${RECORD_SEP}"
       return accountList as text
     `);
-    const result = executeAppleScript(script);
+    const result = executeAppleScript(
+      script,
+      options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {}
+    );
     if (!result.success) {
       console.error(`Failed to list accounts: ${result.error}`);
       this.lastAccountsError = result.error ?? "AppleScript transport failed";
@@ -82113,13 +82141,26 @@ async function useClient(deps, fn, retryOnDrop = false) {
 function withClient(deps, fn) {
   return useClient(deps, fn);
 }
-async function findMailboxPath(client, name) {
+async function resolveMailbox(client, name) {
   const wanted = name.trim().toLowerCase();
   const boxes = await client.list();
   const byPath = boxes.find((b) => b.path.toLowerCase() === wanted);
-  if (byPath) return byPath.path;
-  const byName = boxes.find((b) => b.name.toLowerCase() === wanted);
-  return byName ? byName.path : null;
+  if (byPath) return { kind: "found", path: byPath.path };
+  const byName = boxes.filter((b) => b.name.toLowerCase() === wanted);
+  if (byName.length === 1) return { kind: "found", path: byName[0].path };
+  if (byName.length > 1) {
+    return { kind: "ambiguous", candidates: byName.map((b) => b.path).sort() };
+  }
+  return { kind: "none" };
+}
+function ambiguousMailboxError(name, candidates, accountLabel) {
+  const where = accountLabel ? ` on IMAP account ${accountLabel}` : "";
+  return `Mailbox "${name}" is ambiguous${where} \u2014 it matches ${candidates.map((c) => `"${c}"`).join(" and ")}. Pass the full path.`;
+}
+async function findMailboxPathOrThrow(client, name) {
+  const res = await resolveMailbox(client, name);
+  if (res.kind === "ambiguous") throw new Error(ambiguousMailboxError(name, res.candidates));
+  return res.kind === "found" ? res.path : null;
 }
 function imapCreateMailbox(name, deps = {}) {
   return withClient(deps, async (client) => {
@@ -82133,13 +82174,20 @@ function imapCreateMailbox(name, deps = {}) {
 }
 function imapDeleteMailbox(name, deps = {}) {
   return withClient(deps, async (client, cfg) => {
-    const path = await findMailboxPath(client, name);
-    if (!path) {
+    const res = await resolveMailbox(client, name);
+    if (res.kind === "ambiguous") {
+      return {
+        success: false,
+        error: ambiguousMailboxError(name, res.candidates, cfg.accountLabel)
+      };
+    }
+    if (res.kind === "none") {
       return {
         success: false,
         error: `Mailbox "${name}" not found on IMAP account ${cfg.accountLabel}.`
       };
     }
+    const path = res.path;
     try {
       await client.mailboxDelete(path);
       return {
@@ -82153,13 +82201,20 @@ function imapDeleteMailbox(name, deps = {}) {
 }
 function imapRenameMailbox(oldName, newName, deps = {}) {
   return withClient(deps, async (client, cfg) => {
-    const path = await findMailboxPath(client, oldName);
-    if (!path) {
+    const found = await resolveMailbox(client, oldName);
+    if (found.kind === "ambiguous") {
+      return {
+        success: false,
+        error: ambiguousMailboxError(oldName, found.candidates, cfg.accountLabel)
+      };
+    }
+    if (found.kind === "none") {
       return {
         success: false,
         error: `Mailbox "${oldName}" not found on IMAP account ${cfg.accountLabel}.`
       };
     }
+    const path = found.path;
     try {
       const res = await client.mailboxRename(path, newName);
       return { success: true, info: `Renamed "${res.path}" to "${res.newPath}" via IMAP.` };
@@ -82292,8 +82347,15 @@ function imapUnflagMessage(id, deps = {}) {
 async function imapMoveMessageById(id, destMailbox, deps = {}) {
   const ref = decodeImapId(id);
   if (!ref) return { success: false, error: `Not an IMAP message id: "${id}".` };
-  return withClient(depsForMessageRef(ref, deps), async (client) => {
-    const destPath = await findMailboxPath(client, destMailbox) ?? resolveMailboxPath(destMailbox, "list");
+  return withClient(depsForMessageRef(ref, deps), async (client, cfg) => {
+    const dest = await resolveMailbox(client, destMailbox);
+    if (dest.kind === "ambiguous") {
+      return {
+        success: false,
+        error: ambiguousMailboxError(destMailbox, dest.candidates, cfg.accountLabel)
+      };
+    }
+    const destPath = dest.kind === "found" ? dest.path : resolveMailboxPath(destMailbox, "list");
     const lock = await client.getMailboxLock(ref.path);
     try {
       await client.messageMove([ref.uid], destPath, { uid: true });
@@ -82468,7 +82530,7 @@ var imapBatchDelete = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids, p
 });
 function imapBatchMove(ids, destMailbox, deps = {}) {
   return imapBatch(ids, deps, async (c, uids) => {
-    const dest = await findMailboxPath(c, destMailbox) ?? resolveMailboxPath(destMailbox, "list");
+    const dest = await findMailboxPathOrThrow(c, destMailbox) ?? resolveMailboxPath(destMailbox, "list");
     await c.messageMove(uids, dest, { uid: true });
   });
 }
@@ -82544,6 +82606,9 @@ async function imapThread(id, deps = {}, limit = 50) {
   );
 }
 
+// src/tools/respond.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+
 // src/utils/serialize.ts
 function createSerialGate(settleMs = 50) {
   let tail = Promise.resolve();
@@ -82612,15 +82677,23 @@ function partialCoverageBlock(diagnostics) {
 ${notes.map((n) => `  - ${n}`).join("\n")}`;
 }
 var serializeAppleScript = createSerialGate();
+var callTiming = new AsyncLocalStorage();
+function currentCallTiming() {
+  return callTiming.getStore();
+}
 function withErrorHandling(handler, errorPrefix) {
   return async (params) => {
+    const arrivedAt = Date.now();
     return serializeAppleScript(async () => {
-      try {
-        return await handler(params);
-      } catch (error2) {
-        const message = error2 instanceof Error ? error2.message : "Unknown error";
-        return errorResponse(`${errorPrefix}: ${message}`);
-      }
+      const timing = { arrivedAt, queueWaitMs: Date.now() - arrivedAt };
+      return callTiming.run(timing, async () => {
+        try {
+          return await handler(params);
+        } catch (error2) {
+          const message = error2 instanceof Error ? error2.message : "Unknown error";
+          return errorResponse(`${errorPrefix}: ${message}`);
+        }
+      });
     });
   };
 }
@@ -85092,21 +85165,36 @@ registerTool(
       // tolerated by the permissive advertisement (#135).
       perMailbox: external_exports.array(external_exports.object({}).passthrough()).optional(),
       partial: external_exports.boolean().optional(),
-      failedAccounts: external_exports.array(external_exports.string()).optional()
+      failedAccounts: external_exports.array(external_exports.string()).optional(),
+      // Present only when this call waited behind other tool calls. Without it,
+      // queue wait is invisible from the outside and a caller timing the call
+      // sees a duration no per-account budget explains (#135).
+      queueWaitMs: external_exports.number().optional()
     }
   },
   withErrorHandling(async ({ account }) => {
     const budgetMs = Math.max(1e3, Number(process.env.APPLE_MAIL_MCP_STATS_BUDGET_MS ?? 25e3));
+    const deadlineMs = Math.max(
+      2e3,
+      Number(process.env.APPLE_MAIL_MCP_STATS_DEADLINE_MS ?? 5e4)
+    );
+    const timing = currentCallTiming();
+    const queueWaitMs = timing?.queueWaitMs ?? 0;
+    const startedAt = timing?.arrivedAt ?? Date.now();
+    const remainingMs = () => Math.max(0, deadlineMs - (Date.now() - startedAt));
+    if (queueWaitMs > 0 && remainingMs() < 1e3) {
+      return errorResponse(
+        `Could not read mail statistics: the ${deadlineMs}ms overall deadline was spent waiting ${queueWaitMs}ms in the tool-call queue before this call could start. Tool calls are serialized so they cannot race into Mail.app, so concurrent get-mail-stats calls each wait for the ones ahead of them \u2014 and it is the most expensive read tool (one IMAP STATUS per mailbox, and Gmail lists every label). Issue one at a time, prefer "get-unread-count" when a single number will do, or raise APPLE_MAIL_MCP_STATS_DEADLINE_MS.`
+      );
+    }
     const withBudget = async (work, label) => {
+      const ms = Math.min(budgetMs, remainingMs());
       let timer;
       try {
         return await Promise.race([
           work,
           new Promise((_, reject) => {
-            timer = setTimeout(
-              () => reject(new Error(`${label} timed out after ${budgetMs}ms`)),
-              budgetMs
-            );
+            timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
           })
         ]);
       } finally {
@@ -85119,7 +85207,9 @@ registerTool(
         s = await withBudget(imapMailStats({ account }), `IMAP mail-stats for "${account}"`);
       } catch (e) {
         return errorResponse(
-          `Could not read mail statistics for "${account}": ${String(e)}. Gathering stats costs one IMAP STATUS per mailbox, so a very large account can exceed the ${budgetMs}ms budget \u2014 raise APPLE_MAIL_MCP_STATS_BUDGET_MS, or run the "doctor" tool if the connection itself is the problem.`
+          `Could not read mail statistics for "${account}": ${String(e)}. Gathering stats costs one IMAP STATUS per mailbox, so a very large account can exceed the ${budgetMs}ms budget \u2014 raise APPLE_MAIL_MCP_STATS_BUDGET_MS, or run the "doctor" tool if the connection itself is the problem.` + // Don't send someone tuning a budget when the queue is what ran the
+          // clock down: the remaining deadline caps the budget (#135).
+          (queueWaitMs >= 1e3 ? ` Note: this call waited ${queueWaitMs}ms behind other tool calls before starting, which counts against the ${deadlineMs}ms overall deadline and so caps the effective budget \u2014 issue get-mail-stats calls one at a time.` : ``)
         );
       }
       const lines2 = [
@@ -85133,15 +85223,38 @@ registerTool(
         `  Last 7 days: ${s.recent.last7d}`,
         `  Last 30 days: ${s.recent.last30d}`
       ];
-      return successResponse(lines2.join("\n"), { account, ...s });
+      if (queueWaitMs >= 1e3) {
+        lines2.push(
+          ``,
+          `\u23F3 Waited ${(queueWaitMs / 1e3).toFixed(1)}s in the tool-call queue before this call started (calls are serialized so they cannot race into Mail.app), so the time you measured is queue wait plus work.`
+        );
+      }
+      return successResponse(lines2.join("\n"), {
+        account,
+        ...s,
+        ...queueWaitMs >= 1e3 ? { queueWaitMs } : {}
+      });
     }
     if (account === void 0 && shouldUseImap(account)) {
       let totalMessages = 0;
       let totalUnread = 0;
       const recent = { last24h: 0, last7d: 0, last30d: 0 };
       const perAccount = [];
-      const sources = planCountSources(mailManager.listAccounts(), resolveImapConfigs());
       const failedAccounts = [];
+      const imapConfigs = resolveImapConfigs();
+      const enumerateMs = Math.max(1e3, Math.min(1e4, Math.floor(remainingMs() * 0.3)));
+      const enumerated = mailManager.listAccountsChecked({ timeoutMs: enumerateMs });
+      const sources = enumerated.failed ? imapConfigs.map((config2) => ({
+        kind: "imap",
+        config: config2,
+        label: config2.accountLabel
+      })) : planCountSources(enumerated.accounts, imapConfigs);
+      if (enumerated.failed) {
+        console.error(
+          `Mail.app account enumeration failed for get-mail-stats: ${enumerated.error}`
+        );
+        failedAccounts.push("Mail.app accounts (AppleScript enumeration)");
+      }
       const settled = await Promise.all(
         sources.filter((s) => s.kind === "imap").map(async (src) => {
           try {
@@ -85176,9 +85289,20 @@ registerTool(
       }
       for (const src of sources) {
         if (src.kind === "imap") continue;
+        const left = remainingMs();
+        if (left < 1e3) {
+          failedAccounts.push(src.label);
+          continue;
+        }
+        const read = mailManager.listMailboxesChecked(src.account.name, { timeoutMs: left });
+        if (read.failed) {
+          console.error(`AppleScript mail-stats failed for "${src.label}": ${read.error}`);
+          failedAccounts.push(src.label);
+          continue;
+        }
         let m = 0;
         let u = 0;
-        for (const mb of mailManager.listMailboxes(src.account.name)) {
+        for (const mb of read.mailboxes) {
           m += mb.messageCount;
           u += mb.unreadCount;
         }
@@ -85210,7 +85334,15 @@ registerTool(
       if (failedAccounts.length > 0) {
         lines2.push(
           ``,
-          `\u26A0\uFE0F  PARTIAL: ${failedAccounts.length} account(s) could not be read (${failedAccounts.join(", ")}), so the real totals are higher. They either failed or exceeded the ${budgetMs}ms budget \u2014 raise APPLE_MAIL_MCP_STATS_BUDGET_MS if an account is simply large, or run the "doctor" tool to check the connection.`
+          `\u26A0\uFE0F  PARTIAL: ${failedAccounts.length} account(s) could not be read (${failedAccounts.join(", ")}), so the real totals are higher. They either failed, exceeded the ${budgetMs}ms per-account budget, or ran out of the ${deadlineMs}ms overall deadline \u2014 raise APPLE_MAIL_MCP_STATS_BUDGET_MS and/or APPLE_MAIL_MCP_STATS_DEADLINE_MS if an account is simply large, or run the "doctor" tool to check the connection.` + // Attribute the shortfall to the queue when the queue is what ate the
+          // deadline, instead of leaving it to look like a slow account (#135).
+          (queueWaitMs >= 1e3 ? ` Note: ${queueWaitMs}ms of that deadline was spent queued behind other tool calls, not reading mail \u2014 issuing get-mail-stats calls one at a time will recover it.` : ``)
+        );
+      }
+      if (queueWaitMs >= 1e3) {
+        lines2.push(
+          ``,
+          `\u23F3 Waited ${(queueWaitMs / 1e3).toFixed(1)}s in the tool-call queue before this call started (calls are serialized so they cannot race into Mail.app), so the time you measured is queue wait plus work.`
         );
       }
       return successResponse(lines2.join("\n"), {
@@ -85218,7 +85350,8 @@ registerTool(
         totalUnread,
         accounts: perAccount,
         recent,
-        ...failedAccounts.length > 0 ? { partial: true, failedAccounts } : {}
+        ...failedAccounts.length > 0 ? { partial: true, failedAccounts } : {},
+        ...queueWaitMs >= 1e3 ? { queueWaitMs } : {}
       });
     }
     const stats = mailManager.getMailStats();

package/docs/IMAP-SETUP.md

@@ -358,6 +358,7 @@ GUI is ignoring.
 | `APPLE_MAIL_MCP_IMAP_IDLE` | `1` to enable IMAP IDLE new-mail push. |
 | `APPLE_MAIL_MCP_IMAP_IDLE_MS` | Pooled-connection idle timeout in ms (default `30000`; `0` = never close). |
 | `APPLE_MAIL_MCP_STATS_BUDGET_MS` | Per-account wall-clock budget for `get-mail-stats` in ms (default `25000`, minimum `1000`). |
+| `APPLE_MAIL_MCP_STATS_DEADLINE_MS` | Overall wall-clock deadline for one `get-mail-stats` call in ms (default `50000`, minimum `2000`) — measured from when the request arrived, and covering time spent queued behind other tool calls as well as the Mail.app account enumeration and every per-account read. Keep it below your MCP client's request timeout. |
 | `APPLE_MAIL_MCP_SMTP_HOST` | SMTP host; setting it enables `transport:"smtp"`. |
 | `APPLE_MAIL_MCP_SMTP_PORT` | SMTP port (`465` if secure, else `587`). |
 | `APPLE_MAIL_MCP_SMTP_SECURE` | `true` for implicit TLS (465); else STARTTLS. |

package/package.json

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