apple-mail-mcp 2.11.2 → 2.13.0

package/README.md

@@ -1430,9 +1430,35 @@ Three more honesty rules:
   than list positions — and `expected` stays comparable with the mailbox instead
   of double-counting a duplicate into a false `over`.
 
-`imap:` ids are not reconciled. An IMAP UID names exactly one message in exactly
-one mailbox, so the mis-targeting class this exists for cannot occur there; a
-batch of only `imap:` ids returns no `countDelta` rather than a fabricated one.
+`imap:` ids are not reconciled by `countDelta`. An IMAP UID names exactly one
+message in exactly one mailbox, so the mis-targeting class this exists for cannot
+occur there; a batch of only `imap:` ids returns no `countDelta` rather than a
+fabricated one.
+
+They carry their own post-condition check instead. `delete-message` and
+`move-message` on an `imap:` id return a **`verification`** object in
+`structuredContent`:
+
+```json
+{
+  "verification": {
+    "verdict": "verified",
+    "how": "COPYUID: UID 5 arrived in \"Archive\" as UID 91"
+  }
+}
+```
+
+| `verdict` | Meaning |
+|---|---|
+| `verified` | The effect was **observed** — either the server's UIDPLUS `COPYUID` named the message's new UID in the destination, or the UID is no longer in the source mailbox. |
+| `unverified` | The server **accepted** the command and nothing could confirm the effect. Populates `why`. |
+
+`unverified` is **not a failure** and must not be rendered as one — it means
+"accepted, no observation either way". It is reported rather than hidden because
+an absent verification must never read as a successful one, the same rule the
+collateral diff follows. A message that is still in the source mailbox after an
+accepted move is reported `unverified` rather than failed, because a Gmail label
+store can legitimately keep a message visible in an all-mail view after a move.
 
 ### `APPLE_MAIL_MCP_AUDIT_LOG` — opt-in forensic log
 

package/build/index.js

@@ -83838,6 +83838,31 @@ function imapMailStats(deps = {}) {
 function errText(e) {
   return e instanceof Error ? e.message : String(e);
 }
+function assertMutated(result, what) {
+  if (!result) throw new Error(`${what}: server rejected the command (IMAP NO/BAD)`);
+  return result;
+}
+async function verifyMoved(client, moved, uid, srcPath, destPath) {
+  const newUid = moved.uidMap?.get(uid);
+  if (newUid !== void 0) {
+    return {
+      verdict: "verified",
+      how: `COPYUID: UID ${uid} arrived in "${destPath}" as UID ${newUid}`
+    };
+  }
+  try {
+    const stillThere = await client.fetchOne(String(uid), { uid: true }, { uid: true });
+    if (!stillThere) {
+      return { verdict: "verified", how: `UID ${uid} is no longer present in "${srcPath}"` };
+    }
+    return {
+      verdict: "unverified",
+      why: `the server accepted the MOVE, but UID ${uid} is still present in "${srcPath}" and this server does not advertise UIDPLUS, so arrival in "${destPath}" could not be confirmed. A Gmail label store can legitimately keep a message in an all-mail view after a move, so this is not reported as a failure`
+    };
+  } catch (e) {
+    return { verdict: "unverified", why: `the post-move check could not run: ${errText(e)}` };
+  }
+}
 var poolConnect = defaultConnect;
 var pools = /* @__PURE__ */ new Map();
 function poolKey(cfg) {
@@ -84176,8 +84201,16 @@ async function imapMoveMessageById(id, destMailbox, deps = {}) {
     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 });
-      return { success: true, info: `Moved UID ${ref.uid} to "${destPath}" via IMAP.` };
+      const moved = assertMutated(
+        await client.messageMove([ref.uid], destPath, { uid: true }),
+        `IMAP move of UID ${ref.uid} to "${destPath}"`
+      );
+      const verification = await verifyMoved(client, moved, ref.uid, ref.path, destPath);
+      return {
+        success: true,
+        info: verification.verdict === "verified" ? `Moved UID ${ref.uid} to "${destPath}" via IMAP (verified: ${verification.how}).` : `Moved UID ${ref.uid} to "${destPath}" via IMAP \u2014 UNVERIFIED: ${verification.why}.`,
+        verification
+      };
     } catch (e) {
       return {
         success: false,
@@ -84188,9 +84221,12 @@ async function imapMoveMessageById(id, destMailbox, deps = {}) {
     }
   });
 }
+var FALLBACK_TRASH_PATH = "Trash";
 async function resolveTrashPath(client) {
+  let listed = false;
   try {
     const boxes = await client.list();
+    listed = true;
     const special = boxes.find((b) => b.specialUse === "\\Trash");
     if (special) return special.path;
     const named = boxes.find(
@@ -84199,26 +84235,55 @@ async function resolveTrashPath(client) {
     if (named) return named.path;
   } catch {
   }
-  return resolveMailboxPath("trash", "list");
+  if (!listed) return resolveMailboxPath("trash", "list");
+  try {
+    const created = await client.mailboxCreate(FALLBACK_TRASH_PATH);
+    return created?.path || FALLBACK_TRASH_PATH;
+  } catch {
+    return FALLBACK_TRASH_PATH;
+  }
 }
 async function trashUids(client, uids, srcPath) {
   const dest = await resolveTrashPath(client);
   if (srcPath.trim().toLowerCase() === dest.trim().toLowerCase()) {
-    await client.messageDelete(uids, { uid: true });
+    assertMutated(
+      await client.messageDelete(uids, { uid: true }),
+      `IMAP expunge of ${uids.length} message(s) from "${srcPath}"`
+    );
     return { dest, expunged: true };
   }
-  await client.messageMove(uids, dest, { uid: true });
-  return { dest, expunged: false };
+  const moved = assertMutated(
+    await client.messageMove(uids, dest, { uid: true }),
+    `IMAP move of ${uids.length} message(s) from "${srcPath}" to "${dest}"`
+  );
+  return { dest, expunged: false, moved };
+}
+async function verifyExpunged(client, uid, path) {
+  try {
+    const stillThere = await client.fetchOne(String(uid), { uid: true }, { uid: true });
+    if (!stillThere) {
+      return { verdict: "verified", how: `UID ${uid} is no longer present in "${path}"` };
+    }
+    return {
+      verdict: "unverified",
+      why: `the server accepted the EXPUNGE but UID ${uid} is still present in "${path}"`
+    };
+  } catch (e) {
+    return { verdict: "unverified", why: `the post-delete check could not run: ${errText(e)}` };
+  }
 }
 async function imapDeleteMessageById(id, deps = {}) {
   const ref = decodeImapId(id);
   if (!ref) return { success: false, error: `Not an IMAP message id: "${id}".` };
   return withMailbox(ref.path, depsForMessageRef(ref, deps), async (client) => {
     try {
-      const { dest, expunged } = await trashUids(client, [ref.uid], ref.path);
+      const { dest, expunged, moved } = await trashUids(client, [ref.uid], ref.path);
+      const verification = expunged || !moved ? await verifyExpunged(client, ref.uid, ref.path) : await verifyMoved(client, moved, ref.uid, ref.path, dest);
+      const what = expunged ? `Permanently deleted UID ${ref.uid} from Trash ("${ref.path}") via IMAP` : `Moved UID ${ref.uid} to Trash ("${dest}") via IMAP`;
       return {
         success: true,
-        info: expunged ? `Permanently deleted UID ${ref.uid} from Trash ("${ref.path}") via IMAP.` : `Moved UID ${ref.uid} to Trash ("${dest}") via IMAP.`
+        info: verification.verdict === "verified" ? `${what} (verified: ${verification.how}).` : `${what} \u2014 UNVERIFIED: ${verification.why}.`,
+        verification
       };
     } catch (e) {
       return { success: false, error: `IMAP delete failed for UID ${ref.uid}: ${errText(e)}` };
@@ -84347,22 +84412,37 @@ async function imapBatch(ids, deps, op) {
   return { success, failed, errors };
 }
 var imapBatchMarkRead = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
-  await c.messageFlagsAdd(uids, ["\\Seen"], { uid: true });
+  assertMutated(
+    await c.messageFlagsAdd(uids, ["\\Seen"], { uid: true }),
+    `IMAP mark-read of ${uids.length} message(s)`
+  );
 });
 var imapBatchMarkUnread = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
-  await c.messageFlagsRemove(uids, ["\\Seen"], { uid: true });
+  assertMutated(
+    await c.messageFlagsRemove(uids, ["\\Seen"], { uid: true }),
+    `IMAP mark-unread of ${uids.length} message(s)`
+  );
 });
 var imapBatchFlag = (ids, colorIndex, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
   if (colorIndex === void 0) {
-    await c.messageFlagsAdd(uids, ["\\Flagged"], { uid: true });
+    assertMutated(
+      await c.messageFlagsAdd(uids, ["\\Flagged"], { uid: true }),
+      `IMAP flag of ${uids.length} message(s)`
+    );
     return;
   }
   const { set, clear } = mailFlagBitsFor(colorIndex);
-  await c.messageFlagsAdd(uids, ["\\Flagged", ...set], { uid: true });
+  assertMutated(
+    await c.messageFlagsAdd(uids, ["\\Flagged", ...set], { uid: true }),
+    `IMAP flag of ${uids.length} message(s)`
+  );
   if (clear.length) await c.messageFlagsRemove(uids, clear, { uid: true });
 });
 var imapBatchUnflag = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
-  await c.messageFlagsRemove(uids, ["\\Flagged", ...MAIL_FLAG_BITS], { uid: true });
+  assertMutated(
+    await c.messageFlagsRemove(uids, ["\\Flagged", ...MAIL_FLAG_BITS], { uid: true }),
+    `IMAP unflag of ${uids.length} message(s)`
+  );
 });
 var imapBatchDelete = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids, path) => {
   await trashUids(c, uids, path);
@@ -84370,7 +84450,10 @@ 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 findMailboxPathOrThrow(c, destMailbox) ?? resolveMailboxPath(destMailbox, "list");
-    await c.messageMove(uids, dest, { uid: true });
+    assertMutated(
+      await c.messageMove(uids, dest, { uid: true }),
+      `IMAP move of ${uids.length} message(s) to "${dest}"`
+    );
   });
 }
 function senderName(from) {
@@ -84780,10 +84863,12 @@ function formatMergedRows(rows, showReadState = true) {
 async function routeMessage(id, opts) {
   if (decodeImapId(id)) {
     const r = await opts.imap();
-    return r.success ? successResponse(
+    if (!r.success) return errorResponse(r.error ?? opts.fail);
+    const structured = opts.structuredFromResult ? opts.structuredFromResult(r) : opts.structured;
+    return successResponse(
       r.info ?? opts.ok,
-      opts.structuredFromResult ? opts.structuredFromResult(r) : opts.structured
-    ) : errorResponse(r.error ?? opts.fail);
+      r.verification && structured ? { ...structured, verification: r.verification } : structured
+    );
   }
   return opts.apple();
 }
@@ -85347,6 +85432,13 @@ var COUNT_DELTA_OUTPUT_SCHEMA = external_exports.array(
     note: external_exports.string().optional()
   })
 ).optional();
+var VERIFICATION_OUTPUT_SCHEMA = external_exports.object({
+  verdict: external_exports.enum(["verified", "unverified"]),
+  /** Present on `verified`: what was observed. */
+  how: external_exports.string().optional(),
+  /** Present on `unverified`: why no observation was possible. */
+  why: external_exports.string().optional()
+}).optional();
 var CHECK_ITEM_SCHEMA = external_exports.object({}).passthrough();
 var require2 = createRequire(import.meta.url);
 var { version: version2 } = require2("../package.json");
@@ -86199,7 +86291,8 @@ registerTool(
     outputSchema: {
       ok: external_exports.boolean().optional(),
       id: external_exports.string().optional(),
-      countDelta: COUNT_DELTA_OUTPUT_SCHEMA
+      countDelta: COUNT_DELTA_OUTPUT_SCHEMA,
+      verification: VERIFICATION_OUTPUT_SCHEMA
     }
   },
   withErrorHandling(
@@ -86239,7 +86332,8 @@ registerTool(
       ok: external_exports.boolean().optional(),
       id: external_exports.string().optional(),
       mailbox: external_exports.string().optional(),
-      countDelta: COUNT_DELTA_OUTPUT_SCHEMA
+      countDelta: COUNT_DELTA_OUTPUT_SCHEMA,
+      verification: VERIFICATION_OUTPUT_SCHEMA
     }
   },
   withErrorHandling(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.11.2",
+  "version": "2.13.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",