apple-mail-mcp 2.19.18 → 2.19.19

package/README.md

@@ -240,6 +240,7 @@ Search for messages matching criteria. Searches all accounts by default.
 | `dateFrom`  | string  | No       | Start date filter (e.g., "January 1, 2026")                                                                                               |
 | `dateTo`    | string  | No       | End date filter (e.g., "March 1, 2026")                                                                                                   |
 | `limit`     | number  | No       | Max results, 1–500 (default: 50)                                                                                                          |
+| `offset`    | number  | No       | Newest matches to skip, ≥ 0 (for pagination). IMAP accounts only; without a `mailbox`, `offset` + `limit` may not exceed 5,000            |
 
 **Returns:** List of matching messages with ID, date, subject, sender, and read state.
 
@@ -1103,14 +1104,23 @@ which made a filter-less `list-messages` fail on such a mailbox before 2.19.16.
 **Very large IMAP mailboxes are read newest-first in bounded windows**
 ([#256](https://github.com/sweetrb/apple-mail-mcp/issues/256)). Above 10,000
 messages, a filter-less `list-messages`/`search-messages` pages by message
-sequence number from the top of the mailbox — it fetches UIDs and flags for
-just enough of the newest messages to fill `limit` + `offset` (skipping
-`\Deleted` ones) and full rows for the page alone, so `limit: 1` on a
-793,614-message mailbox costs one small `FETCH`, not a whole-mailbox `SEARCH`.
+sequence number: page `offset` of `limit` is sequence numbers
+`N-offset-limit+1 .. N-offset`, so it fetches UIDs and flags for that range
+alone (plus a small margin; `\Deleted` ones are skipped and the page topped up
+from below) and full rows for the page. The cost is the page, not the offset:
+`limit: 1` at offset 790,000 of a 793,614-message mailbox is one ~33-message
+`FETCH`, not a whole-mailbox `SEARCH` or a walk over every skipped message.
+Offsets count sequence positions. iCloud keeps messages awaiting expunge out of
+the sequence space, so there they are exact; on a server that keeps them in it,
+a page shifts by the number of such messages above it (they are never
+returned).
 A filtered search there runs the same criteria over newest-first sequence
 windows (5,000 messages, growing to 50,000) and stops once the page is full;
 the reported total then reads `at least N` unless the walk reached the bottom
-of the mailbox. A `SEARCH` or `FETCH` that fails names the mailbox, its size and
+of the mailbox. A filtered search's deep `offset` has no such shortcut — which
+messages match is only known by searching the skipped windows — so its cost
+still grows with the offset (in 50,000-message `SEARCH` windows); narrow it
+with `dateTo` instead. A `SEARCH` or `FETCH` that fails names the mailbox, its size and
 the server's own reason (or a likely timeout) instead of reporting "no
 messages".
 

package/build/cli.js

@@ -58049,6 +58049,7 @@ __export(imapClient_exports, {
   MAX_COMPOSE_SOURCE_BYTES: () => MAX_COMPOSE_SOURCE_BYTES,
   MAX_RFC822_FILE_BYTES: () => MAX_RFC822_FILE_BYTES,
   MAX_RFC822_INLINE_BYTES: () => MAX_RFC822_INLINE_BYTES,
+  MAX_UNSCOPED_SEARCH_DEPTH: () => MAX_UNSCOPED_SEARCH_DEPTH,
   __resetPool: () => __resetPool,
   __setPoolConnect: () => __setPoolConnect,
   bodyStructureHasAttachments: () => bodyStructureHasAttachments,
@@ -58096,7 +58097,8 @@ __export(imapClient_exports, {
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
-  shouldUseImap: () => shouldUseImap
+  shouldUseImap: () => shouldUseImap,
+  unscopedSearchOffsetError: () => unscopedSearchOffsetError
 });
 import { createHash } from "node:crypto";
 function encodeImapId(account, path, uid) {
@@ -58442,6 +58444,10 @@ function messageIdentity(entry) {
   const messageId = raw.replace(/^<+|>+$/g, "").trim().toLowerCase();
   return messageId ? `mid:${messageId}` : `${entry.path}\0${entry.message.uid}`;
 }
+function unscopedSearchOffsetError(offset, limit) {
+  if (offset <= 0 || offset + limit <= MAX_UNSCOPED_SEARCH_DEPTH) return void 0;
+  return `search-messages without a mailbox merges every mailbox's newest offset+limit matches, so it pages at most ${MAX_UNSCOPED_SEARCH_DEPTH.toLocaleString("en-US")} deep (offset ${offset} + limit ${limit} asked). Name a mailbox (e.g. the account's All Mail or Archive) to page deeper, or narrow the search with dateTo.`;
+}
 function isUnfiltered(criteria) {
   const keys = Object.keys(criteria);
   return keys.length === 1 && criteria.deleted === false;
@@ -58565,16 +58571,16 @@ function pageRows(fetch) {
 function omissionReason(fetch) {
   return "the server's FETCH response for this message could not be read, even without BODYSTRUCTURE or ENVELOPE" + (fetch.cause ? ` (${fetch.cause})` : "");
 }
-async function walkWindows(exists, page, firstWindow, readWindow) {
+async function walkWindows(top, page, firstWindow, readWindow, openTop = true) {
   const wanted = page.skip + page.take;
   const uids = [];
   let seen = 0;
   let matched = 0;
-  let hi = exists;
+  let hi = top;
   let width = Math.max(1, Math.min(firstWindow, MAX_WINDOW));
   while (hi >= 1 && seen < wanted) {
     const lo = Math.max(1, hi - width + 1);
-    const live = (await readWindow(lo, hi === exists ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
+    const live = (await readWindow(lo, hi === top && openTop ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
     matched += live.length;
     for (const uid of live) {
       if (seen >= wanted) break;
@@ -58586,13 +58592,21 @@ async function walkWindows(exists, page, firstWindow, readWindow) {
   }
   return { uids, matched, exhausted: hi < 1 };
 }
+function sequenceTop(client, statusCount) {
+  const mb = client.mailbox;
+  const exists = mb && typeof mb.exists === "number" && mb.exists >= 0 ? mb.exists : void 0;
+  return exists ?? statusCount;
+}
 async function listLargeMailbox(client, exists, page) {
+  const top = sequenceTop(client, exists) - page.skip;
+  if (top < 1 || page.take === 0) {
+    return { messages: [], omitted: [], total: exists, totalExact: true };
+  }
   let deletedSeen = 0;
   const walk = await walkWindows(
-    exists,
-    page,
-    // Room for a few ghosts on the first read without a second round trip.
-    page.skip + page.take + 64,
+    top,
+    { skip: 0, take: page.take },
+    page.take + DELETED_MARGIN,
     async (lo, hi) => {
       const live = [];
       for await (const msg of client.fetch(`${lo}:${hi}`, { uid: true, flags: true })) {
@@ -58600,7 +58614,10 @@ async function listLargeMailbox(client, exists, page) {
         else live.push(msg.uid);
       }
       return live;
-    }
+    },
+    // From the very top the first window is `lo:*`, as before; below it the
+    // range is exact.
+    page.skip === 0
   );
   return {
     ...pageRows(await fetchRows(client, walk.uids)),
@@ -58678,6 +58695,10 @@ async function run(args, listMode, deps) {
       }
       const limit = args.limit ?? 50;
       const offset = args.offset ?? 0;
+      if (unscopedSearch) {
+        const tooDeep = unscopedSearchOffsetError(offset, limit);
+        if (tooDeep) throw new Error(tooDeep);
+      }
       const criteria = buildCriteria(args, listMode);
       const page = unscopedSearch ? { skip: 0, take: offset + limit } : { skip: offset, take: limit };
       const fetched = [];
@@ -59755,7 +59776,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
+var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, MAX_UNSCOPED_SEARCH_DEPTH, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, DELETED_MARGIN, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
 var init_imapClient = __esm({
   "src/services/imapClient.ts"() {
     "use strict";
@@ -59829,6 +59850,7 @@ var init_imapClient = __esm({
     LARGE_MAILBOX_MESSAGES = 1e4;
     FIRST_SEARCH_WINDOW = 5e3;
     MAX_WINDOW = 5e4;
+    MAX_UNSCOPED_SEARCH_DEPTH = 5e3;
     ROW_QUERY = {
       envelope: true,
       flags: true,
@@ -59847,6 +59869,7 @@ var init_imapClient = __esm({
       internalDate: true,
       headers: ["date", "from", "subject", "message-id", "in-reply-to", "content-type"]
     };
+    DELETED_MARGIN = 32;
     poolConnect = defaultConnect;
     pools = /* @__PURE__ */ new Map();
     connecting = /* @__PURE__ */ new Map();

package/build/index.js

@@ -65378,6 +65378,7 @@ __export(imapClient_exports, {
   MAX_COMPOSE_SOURCE_BYTES: () => MAX_COMPOSE_SOURCE_BYTES,
   MAX_RFC822_FILE_BYTES: () => MAX_RFC822_FILE_BYTES,
   MAX_RFC822_INLINE_BYTES: () => MAX_RFC822_INLINE_BYTES,
+  MAX_UNSCOPED_SEARCH_DEPTH: () => MAX_UNSCOPED_SEARCH_DEPTH,
   __resetPool: () => __resetPool,
   __setPoolConnect: () => __setPoolConnect,
   bodyStructureHasAttachments: () => bodyStructureHasAttachments,
@@ -65425,7 +65426,8 @@ __export(imapClient_exports, {
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
-  shouldUseImap: () => shouldUseImap
+  shouldUseImap: () => shouldUseImap,
+  unscopedSearchOffsetError: () => unscopedSearchOffsetError
 });
 import { createHash } from "node:crypto";
 function encodeImapId(account, path, uid) {
@@ -65771,6 +65773,10 @@ function messageIdentity(entry) {
   const messageId = raw.replace(/^<+|>+$/g, "").trim().toLowerCase();
   return messageId ? `mid:${messageId}` : `${entry.path}\0${entry.message.uid}`;
 }
+function unscopedSearchOffsetError(offset, limit) {
+  if (offset <= 0 || offset + limit <= MAX_UNSCOPED_SEARCH_DEPTH) return void 0;
+  return `search-messages without a mailbox merges every mailbox's newest offset+limit matches, so it pages at most ${MAX_UNSCOPED_SEARCH_DEPTH.toLocaleString("en-US")} deep (offset ${offset} + limit ${limit} asked). Name a mailbox (e.g. the account's All Mail or Archive) to page deeper, or narrow the search with dateTo.`;
+}
 function isUnfiltered(criteria) {
   const keys = Object.keys(criteria);
   return keys.length === 1 && criteria.deleted === false;
@@ -65894,16 +65900,16 @@ function pageRows(fetch) {
 function omissionReason(fetch) {
   return "the server's FETCH response for this message could not be read, even without BODYSTRUCTURE or ENVELOPE" + (fetch.cause ? ` (${fetch.cause})` : "");
 }
-async function walkWindows(exists, page, firstWindow, readWindow) {
+async function walkWindows(top, page, firstWindow, readWindow, openTop = true) {
   const wanted = page.skip + page.take;
   const uids = [];
   let seen = 0;
   let matched = 0;
-  let hi = exists;
+  let hi = top;
   let width = Math.max(1, Math.min(firstWindow, MAX_WINDOW));
   while (hi >= 1 && seen < wanted) {
     const lo = Math.max(1, hi - width + 1);
-    const live = (await readWindow(lo, hi === exists ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
+    const live = (await readWindow(lo, hi === top && openTop ? "*" : hi, hi - lo + 1)).slice().sort((a, b) => b - a);
     matched += live.length;
     for (const uid of live) {
       if (seen >= wanted) break;
@@ -65915,13 +65921,21 @@ async function walkWindows(exists, page, firstWindow, readWindow) {
   }
   return { uids, matched, exhausted: hi < 1 };
 }
+function sequenceTop(client, statusCount) {
+  const mb = client.mailbox;
+  const exists = mb && typeof mb.exists === "number" && mb.exists >= 0 ? mb.exists : void 0;
+  return exists ?? statusCount;
+}
 async function listLargeMailbox(client, exists, page) {
+  const top = sequenceTop(client, exists) - page.skip;
+  if (top < 1 || page.take === 0) {
+    return { messages: [], omitted: [], total: exists, totalExact: true };
+  }
   let deletedSeen = 0;
   const walk = await walkWindows(
-    exists,
-    page,
-    // Room for a few ghosts on the first read without a second round trip.
-    page.skip + page.take + 64,
+    top,
+    { skip: 0, take: page.take },
+    page.take + DELETED_MARGIN,
     async (lo, hi) => {
       const live = [];
       for await (const msg of client.fetch(`${lo}:${hi}`, { uid: true, flags: true })) {
@@ -65929,7 +65943,10 @@ async function listLargeMailbox(client, exists, page) {
         else live.push(msg.uid);
       }
       return live;
-    }
+    },
+    // From the very top the first window is `lo:*`, as before; below it the
+    // range is exact.
+    page.skip === 0
   );
   return {
     ...pageRows(await fetchRows(client, walk.uids)),
@@ -66007,6 +66024,10 @@ async function run(args, listMode, deps) {
       }
       const limit = args.limit ?? 50;
       const offset = args.offset ?? 0;
+      if (unscopedSearch) {
+        const tooDeep = unscopedSearchOffsetError(offset, limit);
+        if (tooDeep) throw new Error(tooDeep);
+      }
       const criteria = buildCriteria(args, listMode);
       const page = unscopedSearch ? { skip: 0, take: offset + limit } : { skip: offset, take: limit };
       const fetched = [];
@@ -67084,7 +67105,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
+var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, MAX_UNSCOPED_SEARCH_DEPTH, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, DELETED_MARGIN, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
 var init_imapClient = __esm({
   "src/services/imapClient.ts"() {
     "use strict";
@@ -67158,6 +67179,7 @@ var init_imapClient = __esm({
     LARGE_MAILBOX_MESSAGES = 1e4;
     FIRST_SEARCH_WINDOW = 5e3;
     MAX_WINDOW = 5e4;
+    MAX_UNSCOPED_SEARCH_DEPTH = 5e3;
     ROW_QUERY = {
       envelope: true,
       flags: true,
@@ -67176,6 +67198,7 @@ var init_imapClient = __esm({
       internalDate: true,
       headers: ["date", "from", "subject", "message-id", "in-reply-to", "content-type"]
     };
+    DELETED_MARGIN = 32;
     poolConnect = defaultConnect;
     pools = /* @__PURE__ */ new Map();
     connecting = /* @__PURE__ */ new Map();
@@ -88471,7 +88494,10 @@ registerTool(
       isFlagged: external_exports.boolean().optional().describe("Filter by flagged status"),
       dateFrom: DATE_FILTER_SCHEMA.describe("Start date filter (e.g., 'January 1, 2026')"),
       dateTo: DATE_FILTER_SCHEMA.describe("End date filter (e.g., 'March 1, 2026')"),
-      limit: external_exports.number().int().min(1).max(500).optional().describe("Maximum number of results (default: 50, max: 500)")
+      limit: external_exports.number().int().min(1).max(500).optional().describe("Maximum number of results (default: 50, max: 500)"),
+      offset: external_exports.number().int().min(0).optional().describe(
+        "Number of newest matches to skip (for pagination; IMAP accounts only). Without a mailbox, offset + limit may not exceed 5,000 \u2014 name a mailbox to page deeper."
+      )
     },
     outputSchema: LIST_OUTPUT_SCHEMA
   },
@@ -88482,6 +88508,7 @@ registerTool(
       mailbox,
       account,
       limit = 50,
+      offset = 0,
       dateFrom,
       dateTo,
       from,
@@ -88489,12 +88516,17 @@ registerTool(
       isRead,
       isFlagged
     }) => {
+      if (offset > 0 && !mailbox) {
+        const tooDeep = unscopedSearchOffsetError(offset, limit);
+        if (tooDeep) return errorResponse(tooDeep);
+      }
       if (shouldUseImap(account)) {
         const imapArgs = {
           query,
           body,
           mailbox,
           limit,
+          offset,
           dateFrom,
           dateTo,
           from,
@@ -88513,11 +88545,16 @@ registerTool(
             omittedMessages: r.omittedMessages
           });
         }
-        const fan = await fanOutImapMessages(imapArgs, "search");
         const { appleScriptOnly } = partitionAccountsForCounts(
           mailManager.listAccounts(),
           resolveImapConfigs()
         );
+        if (offset > 0 && appleScriptOnly.length > 0 && !body) {
+          return errorResponse(
+            `offset is supported only on IMAP accounts, and ${appleScriptOnly.map((a) => `"${a.name}"`).join(", ")} ${appleScriptOnly.length === 1 ? "is" : "are"} AppleScript-only. Pass an IMAP account to page, or omit offset.`
+          );
+        }
+        const fan = await fanOutImapMessages(imapArgs, "search");
         if (body) {
           const apple2 = {
             rows: [],
@@ -88548,6 +88585,11 @@ registerTool(
         );
         return mergedMessageResponse(fan, apple, limit, "matched");
       }
+      if (offset > 0) {
+        return errorResponse(
+          `offset is supported only on IMAP accounts; IMAP is not configured for ${account ? `account "${account}"` : "any account"}. Omit offset, or narrow the search with dateFrom/dateTo instead.`
+        );
+      }
       if (body) {
         return errorResponse(
           `Body search requires the IMAP backend, which is not configured for ${account ? `account "${account}"` : "any account"}. Configure IMAP (see the IMAP backend section of the README) or search by query/subject/from instead.`

package/package.json

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