apple-mail-mcp 2.10.6 → 2.10.8

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`), covering 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,15 @@ 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.
+
 ---
 
 #### `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";
@@ -81653,9 +81681,8 @@ function sameImapAccount(left, right, deps) {
     if (aliases.has(left) && aliases.has(right)) return true;
   }
   const specs = listImapAccountSpecs();
-  const matches = (selector, spec) => spec.accountLabel === selector || spec.user === selector;
-  const leftSpec = specs.find((spec) => matches(left, spec));
-  const rightSpec = specs.find((spec) => matches(right, spec));
+  const leftSpec = specs.find((spec) => specMatchesSelector(spec, left));
+  const rightSpec = specs.find((spec) => specMatchesSelector(spec, right));
   return leftSpec !== void 0 && leftSpec === rightSpec;
 }
 function depsForAccount(account, deps) {
@@ -81667,14 +81694,21 @@ function depsForAccount(account, deps) {
 function depsForMessageRef(ref, deps) {
   return depsForAccount(ref.account, deps);
 }
+function specMatchesSelector(spec, selector) {
+  return spec.accountLabel === selector || spec.user === selector || (spec.aliases?.includes(selector) ?? false);
+}
 function str(v) {
   return typeof v === "string" && v.trim() ? v.trim() : void 0;
 }
+function imapIdentityKey(spec) {
+  return `${spec.host.trim().toLowerCase()}:${spec.port}:${spec.user.trim()}`;
+}
 function listImapAccountSpecs(env = process.env) {
   const specs = [];
+  const seen = /* @__PURE__ */ new Set();
   const user = env[IMAP_ENV.user]?.trim();
   if (user) {
-    specs.push({
+    const legacy = {
       accountLabel: env[IMAP_ENV.account]?.trim() || user,
       user,
       host: env[IMAP_ENV.host]?.trim() || "imap.gmail.com",
@@ -81682,7 +81716,9 @@ function listImapAccountSpecs(env = process.env) {
       password: env[IMAP_ENV.password],
       keychainService: env[IMAP_ENV.keychainService]?.trim(),
       keychainAccount: env[IMAP_ENV.keychainAccount]?.trim()
-    });
+    };
+    specs.push(legacy);
+    seen.add(imapIdentityKey(legacy));
   }
   const json = env[IMAP_ENV.accounts]?.trim();
   if (json) {
@@ -81694,12 +81730,22 @@ function listImapAccountSpecs(env = process.env) {
           const u = str(a.user);
           if (!u) continue;
           const label = str(a.account) || str(a.accountLabel) || u;
-          if (specs.some((s) => s.accountLabel === label)) continue;
+          const host = str(a.host) || "imap.gmail.com";
           const port = a.port ? Number(a.port) : 993;
+          const key = imapIdentityKey({ host, port, user: u });
+          if (seen.has(key)) {
+            const owner = specs.find((s) => imapIdentityKey(s) === key);
+            if (owner && owner.accountLabel !== label && !owner.aliases?.includes(label)) {
+              (owner.aliases ??= []).push(label);
+            }
+            continue;
+          }
+          if (specs.some((s) => s.accountLabel === label)) continue;
+          seen.add(key);
           specs.push({
             accountLabel: label,
             user: u,
-            host: str(a.host) || "imap.gmail.com",
+            host,
             port,
             password: str(a.password),
             keychainService: str(a.keychainService),
@@ -81737,7 +81783,7 @@ function specToConfig(spec) {
 }
 function isImapAccount(account, env = process.env) {
   if (!account) return false;
-  return listImapAccountSpecs(env).some((s) => s.accountLabel === account || s.user === account);
+  return listImapAccountSpecs(env).some((s) => specMatchesSelector(s, account));
 }
 function shouldUseImap(account, env = process.env) {
   return listImapAccountSpecs(env).length > 0 && (account === void 0 || isImapAccount(account, env));
@@ -81760,12 +81806,12 @@ function resolveImapConfig(env = process.env, account) {
   const specs = listImapAccountSpecs(env);
   if (specs.length === 0) {
     throw new Error(
-      `IMAP not configured. Set ${IMAP_ENV.user} (login address) to enable it. ${SETUP_HINT}`
+      `IMAP not configured. Set ${IMAP_ENV.user} (login address), or ${IMAP_ENV.accounts} for multiple accounts, to enable it. ${SETUP_HINT}`
     );
   }
   let spec;
   if (account) {
-    spec = specs.find((s) => s.accountLabel === account || s.user === account);
+    spec = specs.find((s) => specMatchesSelector(s, account));
     if (!spec) {
       throw new Error(
         `No IMAP account matching "${account}". Configured: ${specs.map((s) => s.accountLabel).join(", ")}.`
@@ -81977,7 +82023,7 @@ function errText(e) {
 var poolConnect = defaultConnect;
 var pools = /* @__PURE__ */ new Map();
 function poolKey(cfg) {
-  return `${cfg.host}:${cfg.port}:${cfg.user}`;
+  return imapIdentityKey(cfg);
 }
 function imapIdleMs() {
   const raw = process.env.APPLE_MAIL_MCP_IMAP_IDLE_MS;
@@ -82035,7 +82081,7 @@ async function acquirePooled(cfg) {
   }
 }
 async function imapHealthCheck(deps = {}) {
-  if (!deps.config && !process.env[IMAP_ENV.user]?.trim()) {
+  if (!deps.config && listImapAccountSpecs().length === 0) {
     return { configured: false, ok: false };
   }
   let cfg;
@@ -82095,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) => {
@@ -82115,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 {
@@ -82135,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.` };
@@ -82274,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 });
@@ -82450,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 });
   });
 }
@@ -82773,7 +82853,11 @@ async function runDoctor(mailManager2) {
       checks.push({
         name: `IMAP: ${label}`,
         status: h.ok ? "ok" : "fail",
-        detail: h.ok ? `connected to ${h.host}` : `connection failed: ${h.error}. Check the Keychain password and host/port.`
+        // `h.error` is optional on the health-check result, so interpolating it
+        // bare printed the literal string "connection failed: undefined" for
+        // any failure that carried no message (issue #138). Never render that:
+        // an unexplained failure is still worth naming, but as words.
+        detail: h.ok ? `connected to ${h.host}` : `connection failed: ${h.error ?? "the health check reported no detail"}. Check the Keychain password and host/port.`
       });
     }
   }
@@ -85075,16 +85159,20 @@ registerTool(
   },
   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 startedAt = Date.now();
+    const remainingMs = () => Math.max(0, deadlineMs - (Date.now() - startedAt));
     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 {
@@ -85118,8 +85206,21 @@ registerTool(
       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 {
@@ -85154,9 +85255,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;
         }
@@ -85188,7 +85300,7 @@ 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.`
         );
       }
       return successResponse(lines2.join("\n"), {

package/docs/IMAP-SETUP.md

@@ -199,6 +199,20 @@ Each array entry accepts: `account`, `user`, `host`, `port`, `password`
 (discouraged — prefer Keychain), `keychainService`, `keychainAccount`. Each
 account keeps its own pooled IMAP connection.
 
+**The array alone is enough.** You do not need the legacy single-account vars:
+listing every account in `APPLE_MAIL_MCP_IMAP_ACCOUNTS` and setting none of
+`APPLE_MAIL_MCP_IMAP_USER` / `_ACCOUNT` / `_HOST` is fully supported, and the
+first array entry becomes the default account. (Before 2.10.7 that shape worked
+for every tool but made `doctor` report `connection failed: undefined` for each
+account — see #138.)
+
+**Don't declare the same mailbox twice.** If the legacy vars already describe a
+mailbox, do not also give it an array entry — even under a different `account`
+nickname. An account's identity is its resolved `(host, port, user)`, not its
+label, so the duplicate is recognised and collapsed rather than counted twice
+(the extra nickname still works as an alias). Before 2.10.7 it was counted
+twice, inflating `get-unread-count` and `get-mail-stats`.
+
 ---
 
 ## Step 4 (optional) — SMTP sending
@@ -333,17 +347,18 @@ GUI is ignoring.
 | Variable | Purpose |
 |----------|---------|
 | `APPLE_MAIL_MCP_DEFAULT_ACCOUNT` | Account used when a tool omits `account` (name or email). |
-| `APPLE_MAIL_MCP_IMAP_USER` | Primary IMAP login; setting it enables IMAP. |
+| `APPLE_MAIL_MCP_IMAP_USER` | Primary IMAP login. Setting it enables IMAP — but so does `APPLE_MAIL_MCP_IMAP_ACCOUNTS` on its own; either is sufficient. |
 | `APPLE_MAIL_MCP_IMAP_ACCOUNT` | Mail.app account name to match for routing (default = USER). |
 | `APPLE_MAIL_MCP_IMAP_HOST` | IMAP host (default `imap.gmail.com`). |
 | `APPLE_MAIL_MCP_IMAP_PORT` | IMAP port (default `993`, implicit TLS). |
 | `APPLE_MAIL_MCP_IMAP_PASSWORD` | Password (discouraged; prefer Keychain). |
 | `APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE` | Keychain item service/server name. |
 | `APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT` | Keychain item account (default = USER). |
-| `APPLE_MAIL_MCP_IMAP_ACCOUNTS` | JSON array of additional accounts (multi-account). |
+| `APPLE_MAIL_MCP_IMAP_ACCOUNTS` | JSON array of accounts (multi-account). Sufficient on its own; also enables IMAP. |
 | `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`) — covers the Mail.app account enumeration as well as 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.6",
+  "version": "2.10.8",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",