apple-mail-mcp 2.10.32 → 2.10.33

package/README.md

@@ -1399,6 +1399,7 @@ batch of only `imap:` ids returns no `countDelta` rather than a fabricated one.
 | `APPLE_MAIL_MCP_AUDIT_LOG` | *(off)* | Absolute path to an NDJSON file. Setting it enables the audit log **and** the collateral diff below |
 | `APPLE_MAIL_MCP_AUDIT_SUBJECTS` | `0` | Set `1` to also record message **subjects**. Separate, deliberate second opt-in — see Privacy |
 | `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX` | `2000` | Skip the collateral snapshot for mailboxes larger than this many messages. `0` disables the snapshot entirely |
+| `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_CHUNK` | `250` | How many messages the collateral snapshot reads from Mail per request. Lower it if Mail declines slices on a very large mailbox |
 
 When set, each destructive operation appends **one JSON object per line**
 containing: timestamp, tool name, server version, the arguments it was called
@@ -1451,12 +1452,45 @@ exceed AppleScript's 2^29 integer range (where Mail hands them back as
 compared in the raw form, a message you explicitly asked to delete would be
 reported here as collateral.
 
-This costs one bulk property read per snapshot and is O(mailbox size), so it is
-bounded by `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX`. When the bound bites, the record
-says so explicitly (`"snapshot": "skipped"` with a reason) rather than omitting
-the field — a silently skipped snapshot would read as "nothing collateral
-happened", which is worse than no snapshot at all. `countDelta` is unaffected by
-the skip and still reconciles the counts.
+This is O(mailbox size), so it is bounded by `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX`.
+When the bound bites, the record says so explicitly (`"snapshot": "skipped"` with
+a reason) rather than omitting the field — a silently skipped snapshot would read
+as "nothing collateral happened", which is worse than no snapshot at all.
+`countDelta` is unaffected by the skip and still reconciles the counts.
+
+#### Partial snapshots on large mailboxes
+
+The mailbox is read in `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_CHUNK`-sized slices, each
+retried once on its own. It used to be a single whole-mailbox read, which meant
+Mail declining that one request lost the **entire** diff — and the bigger the
+mailbox, the more likely that was. The mechanism that attributes collateral
+damage was therefore least reliable exactly when the blast radius was largest.
+
+When a slice still will not read, the snapshot is reported as `partial` and it
+**names its own gap**:
+
+```json
+{
+  "snapshot": "partial",
+  "unobserved": [{ "phase": "after", "ranges": "251-500" }],
+  "appeared": [],
+  "skipReason": "Mail would not read 251-500 (after) of this mailbox, so the snapshot has a hole in it. …"
+}
+```
+
+Each half of the diff is withheld when the snapshot that could **refute** it has
+a hole, because a wrong name here is worse than a missing one:
+
+| Hole in | `disappeared` / `unrequested` | `appeared` |
+|---------|-------------------------------|------------|
+| neither (`"ok"`) | reported | reported |
+| `before` | reported (an undercount — a message never read before cannot be missed after) | withheld |
+| `after` | **withheld** — a message absent from a partial `after` may merely be unread, and naming it would present an innocent message as evidence of data loss | reported |
+| both | withheld | withheld |
+
+**An absent field means "not computable", never "empty".** Check
+`"snapshot": "ok"` before reading `disappeared` as a clean bill of health — the
+false-ok warning does exactly that, so a `partial` snapshot never triggers it.
 
 ### Privacy, and what the file costs you
 

package/build/index.js

@@ -78791,7 +78791,10 @@ import { appendFileSync } from "node:fs";
 var AUDIT_LOG_ENV = "APPLE_MAIL_MCP_AUDIT_LOG";
 var AUDIT_SUBJECTS_ENV = "APPLE_MAIL_MCP_AUDIT_SUBJECTS";
 var AUDIT_SNAPSHOT_MAX_ENV = "APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX";
+var AUDIT_SNAPSHOT_CHUNK_ENV = "APPLE_MAIL_MCP_AUDIT_SNAPSHOT_CHUNK";
 var DEFAULT_SNAPSHOT_MAX = 2e3;
+var DEFAULT_SNAPSHOT_CHUNK = 250;
+var SNAPSHOT_SLICE_ATTEMPTS = 2;
 function isOn(raw) {
   return /^(1|true|yes|on)$/i.test((raw ?? "").trim());
 }
@@ -78812,6 +78815,13 @@ function auditSnapshotMax() {
   if (!Number.isFinite(n) || n < 0) return DEFAULT_SNAPSHOT_MAX;
   return Math.floor(n);
 }
+function auditSnapshotChunk() {
+  const raw = process.env[AUDIT_SNAPSHOT_CHUNK_ENV]?.trim();
+  if (raw === void 0 || raw === "") return DEFAULT_SNAPSHOT_CHUNK;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 1) return DEFAULT_SNAPSHOT_CHUNK;
+  return Math.floor(n);
+}
 function writeAuditRecord(record2) {
   const path = auditLogPath();
   if (!path) return;
@@ -79402,10 +79412,24 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
    * into a SNAP record — the before/after pair the collateral diff subtracts.
    *
    * Empty string when the audit log is off or the snapshot is disabled, so the
-   * whole layer costs literally nothing by default. The two property reads are
-   * BULK (`id of messages of mb`, `message id of messages of mb`) — two Apple
-   * Events for the whole mailbox rather than two per message — and the joining
-   * is pure in-memory AppleScript.
+   * whole layer costs literally nothing by default. The property reads are BULK
+   * (`id of messages i thru j of mb`) — two Apple Events per SLICE rather than
+   * two per message — and the joining is pure in-memory AppleScript.
+   *
+   * ## Why it is sliced rather than one whole-mailbox read (#176)
+   *
+   * This used to be a single `id of messages of mb` pair. When Mail declined
+   * that request the entire snapshot came back `unavailable`, and the cost of
+   * the request grows with the mailbox — so the one mechanism that can attribute
+   * an unrequested departure was least reliable exactly when the batch and the
+   * mailbox, and therefore the blast radius, were largest. That correlation was
+   * the defect, not any individual failure.
+   *
+   * Now the mailbox is read in `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_CHUNK`-sized
+   * slices; each slice is retried once on its own; and a slice that still will
+   * not read costs only its own range. The unreadable ranges are emitted in
+   * their own field, so the diff can report a PARTIAL snapshot that names its
+   * own gap instead of an all-or-nothing `unavailable`.
    *
    * Above `APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX` messages the snapshot is skipped,
    * and the skip is EMITTED as a record with its reason. A silently skipped
@@ -79422,46 +79446,77 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
   snapshotFragment(phase, acctExpr, mbExpr, countVar, mbVar = "_tmb") {
     const max = auditSnapshotMax();
     if (!isAuditEnabled() || max <= 0) return "";
+    const chunk = auditSnapshotChunk();
     return `
         set _sStatus to "ok"
         set _sPayload to ""
-        set _sIds to {}
-        set _sMids to {}
+        set _sMiss to ""
+        set _sPairs to {}
+        set _sChunk to ${chunk}
         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
-          try
-            set _sIds to (id of messages of ${mbVar})
-            set _sMids to (message id of messages of ${mbVar})
-          on error
-            set _sStatus to "unavailable"
-          end try
-          if _sStatus is "ok" then
-            if (count of _sIds) is not (count of _sMids) then
+          set _sLo to 1
+          repeat while _sLo <= ${countVar}
+            set _sHi to _sLo + _sChunk - 1
+            if _sHi > ${countVar} then set _sHi to ${countVar}
+            set _sGot to false
+            repeat with _sTry from 1 to ${SNAPSHOT_SLICE_ATTEMPTS}
+              set _sIds to {}
+              set _sMids to {}
+              -- A slice is staged into _sBuf and merged only once it has been
+              -- read IN FULL. Appending as we go would leave a slice that threw
+              -- halfway both partially recorded AND marked unread, and the
+              -- retry would then record its messages a second time.
+              set _sBuf to {}
+              try
+                set _sIds to (id of messages _sLo thru _sHi of ${mbVar})
+                set _sMids to (message id of messages _sLo thru _sHi of ${mbVar})
+                if (class of _sIds) is not list then set _sIds to {_sIds}
+                if (class of _sMids) is not list then set _sMids to {_sMids}
+                if (count of _sIds) is (count of _sMids) then
+                  repeat with _q from 1 to (count of _sIds)
+                    set _sOne to ""
+                    try
+                      set _zSnapMid to ((item _q of _sMids) as string)${this.sanitizeFragment("_zSnapMid", "                      ")}
+                      set _sOne to ((item _q of _sIds) as string) & "${SNAP_PAIR}" & _zSnapMid
+                    on error
+                      set _sOne to ((item _q of _sIds) as string) & "${SNAP_PAIR}"
+                    end try
+                    set end of _sBuf to _sOne
+                  end repeat
+                  set _sGot to true
+                end if
+              end try
+              if _sGot then
+                repeat with _sB in _sBuf
+                  set end of _sPairs to (contents of _sB)
+                end repeat
+                exit repeat
+              end if
+            end repeat
+            if not _sGot then
+              if _sMiss is not "" then set _sMiss to _sMiss & ","
+              set _sMiss to _sMiss & (_sLo as string) & "-" & (_sHi as string)
+            end if
+            set _sLo to _sHi + 1
+          end repeat
+          if _sMiss is not "" then
+            if (count of _sPairs) is 0 then
               set _sStatus to "unavailable"
             else
-              set _sPairs to {}
-              repeat with _q from 1 to (count of _sIds)
-                set _sOne to ""
-                try
-                  set _zSnapMid to ((item _q of _sMids) as string)${this.sanitizeFragment("_zSnapMid", "                  ")}
-                  set _sOne to ((item _q of _sIds) as string) & "${SNAP_PAIR}" & _zSnapMid
-                on error
-                  set _sOne to ((item _q of _sIds) as string) & "${SNAP_PAIR}"
-                end try
-                set end of _sPairs to _sOne
-              end repeat
-              set _sTid to AppleScript's text item delimiters
-              set AppleScript's text item delimiters to "${SNAP_ITEM}"
-              set _sPayload to _sPairs as string
-              set AppleScript's text item delimiters to _sTid
+              set _sStatus to "partial"
             end if
           end if
+          set _sTid to AppleScript's text item delimiters
+          set AppleScript's text item delimiters to "${SNAP_ITEM}"
+          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 & "${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 & "${RECORD_SEP}"`;
   }
   /**
    * AppleScript capturing the message the op is ABOUT to touch into `_pre`,
@@ -79527,7 +79582,8 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
           mailbox: f[2] ?? "",
           phase: f[3] === "after" ? "after" : "before",
           status: f[4] ?? "",
-          payload: f[5] ?? ""
+          payload: f[5] ?? "",
+          miss: f[6] ?? ""
         });
         continue;
       }
@@ -79677,8 +79733,9 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         });
         continue;
       }
-      if (b.status !== "ok" || a.status !== "ok") {
-        const bad = b.status !== "ok" ? b : a;
+      const dead = (s) => s.status !== "ok" && s.status !== "partial";
+      if (dead(b) || dead(a)) {
+        const bad = dead(b) ? b : a;
         collateral.push({
           account: g.account,
           mailbox: g.mailbox,
@@ -79696,13 +79753,30 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       const unrequested = disappeared.filter(
         (e) => !requestedNumericIds.has(canonicalNumericId(e.id))
       );
+      const holes = [b, a].filter((s) => s.miss !== "").map((s) => ({ phase: s.phase, ranges: s.miss }));
+      if (holes.length === 0) {
+        collateral.push({
+          account: g.account,
+          mailbox: g.mailbox,
+          snapshot: "ok",
+          disappeared,
+          unrequested,
+          appeared
+        });
+        continue;
+      }
+      const derivable = [
+        a.miss === "" ? `what left the ${beforeEntries.length} message(s) read before it` : null,
+        b.miss === "" ? "what arrived during it" : null
+      ].filter((s) => s !== null);
       collateral.push({
         account: g.account,
         mailbox: g.mailbox,
-        snapshot: "ok",
-        disappeared,
-        unrequested,
-        appeared
+        snapshot: "partial",
+        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 } : {},
+        ...b.miss === "" ? { appeared } : {}
       });
     }
     return { countDeltas, preImages, outcomes: parsed.outcomes, collateral };
@@ -86387,7 +86461,7 @@ registerTool(
 registerTool(
   "fetch-attachment",
   {
-    description: "Use when: retrieving an attachment's raw bytes inline as base64 (by message id and attachmentName), e.g. to process its contents without touching disk.\nReturns: the attachment's bytes base64-encoded, with its size and (for IMAP) MIME type.\nDo not use when: you don't know the attachment name (use list-attachments first) or you just want it saved to disk (use save-attachment).",
+    description: "Use when: retrieving an attachment's raw bytes inline as base64 (by message id and attachmentName), e.g. to process its contents without keeping a file.\nReturns: the attachment's bytes base64-encoded, with its size and (for IMAP) MIME type.\nDo not use when: you don't know the attachment name (use list-attachments first) or you just want it saved to disk (use save-attachment).\nSafety: leaves no file behind, but the AppleScript path is not disk-free \u2014 Mail writes the attachment into a private temp directory, which is read back and then deleted. Needs no Full Disk Access either way: Mail performs that write under the Automation grant, and this server never reads the mail store itself.",
     inputSchema: {
       id: MESSAGE_ID_SCHEMA,
       attachmentName: external_exports.string().min(1, "Attachment name is required")

package/package.json

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