apple-mail-mcp 2.8.3 → 2.8.5

package/README.md

@@ -98,6 +98,25 @@ npm install -g github:sweetrb/apple-mail-mcp
 
 On first use, macOS will ask for permission to automate Mail.app. Click "OK" to allow.
 
+## Configuring email (IMAP & SMTP)
+
+The server works out of the box over AppleScript with **no configuration**. Two
+**opt-in** power features take a one-time setup:
+
+- **Fast IMAP reads** — server-side search, counts, and large-mailbox handling
+  that AppleScript is too slow for (it times out on big Gmail mailboxes).
+- **Clean SMTP sending** — `send-email` submits clean MIME directly, avoiding the
+  macOS 15+ Mail.app `<blockquote>` wrapping that otherwise makes sent mail look
+  quoted/indented like a reply.
+
+Both are driven by non-secret `APPLE_MAIL_MCP_*` settings — supplied via an `env`
+block **or** a `config.json` file (for hosts like Claude Desktop that strip `env`)
+— with passwords kept in the macOS **Keychain**, never in config.
+
+👉 **[IMAP / SMTP Setup Guide](docs/IMAP-SETUP.md)** — step-by-step: app passwords,
+Keychain, both config methods, multi-account, SMTP, verification with the `doctor`
+tool, and troubleshooting. Verify any time by running the **`doctor`** tool.
+
 ## Requirements
 
 - **macOS** - Apple Mail and AppleScript are macOS-only

package/build/index.js

@@ -80308,6 +80308,28 @@ async function imapMoveMessageById(id, destMailbox, deps = {}) {
     }
   });
 }
+async function resolveTrashPath(client) {
+  try {
+    const boxes = await client.list();
+    const special = boxes.find((b) => b.specialUse === "\\Trash");
+    if (special) return special.path;
+    const named = boxes.find(
+      (b) => /^(trash|deleted messages|deleted items|bin)$/i.test(b.name) || /(^|\/)trash$/i.test(b.path)
+    );
+    if (named) return named.path;
+  } catch {
+  }
+  return resolveMailboxPath("trash", "list");
+}
+async function trashUids(client, uids, srcPath) {
+  const dest = await resolveTrashPath(client);
+  if (srcPath.trim().toLowerCase() === dest.trim().toLowerCase()) {
+    await client.messageDelete(uids, { uid: true });
+    return { dest, expunged: true };
+  }
+  await client.messageMove(uids, dest, { uid: true });
+  return { dest, expunged: false };
+}
 async function imapDeleteMessageById(id, deps = {}) {
   const ref = decodeImapId(id);
   if (!ref) return { success: false, error: `Not an IMAP message id: "${id}".` };
@@ -80316,9 +80338,11 @@ async function imapDeleteMessageById(id, deps = {}) {
     { ...deps, account: deps.account ?? ref.account },
     async (client) => {
       try {
-        const ok = await client.messageDelete([ref.uid], { uid: true });
-        if (!ok) return { success: false, error: `IMAP delete returned false for UID ${ref.uid}.` };
-        return { success: true, info: `Deleted UID ${ref.uid} from "${ref.path}" via IMAP.` };
+        const { dest, expunged } = await trashUids(client, [ref.uid], ref.path);
+        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.`
+        };
       } catch (e) {
         return { success: false, error: `IMAP delete failed for UID ${ref.uid}: ${errText(e)}` };
       }
@@ -80445,8 +80469,8 @@ var imapBatchFlag = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) =>
 var imapBatchUnflag = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
   await c.messageFlagsRemove(uids, ["\\Flagged"], { uid: true });
 });
-var imapBatchDelete = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
-  await c.messageDelete(uids, { uid: true });
+var imapBatchDelete = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids, path) => {
+  await trashUids(c, uids, path);
 });
 function imapBatchMove(ids, destMailbox, deps = {}) {
   return imapBatch(ids, deps, async (c, uids) => {
@@ -80733,6 +80757,8 @@ async function routeMessage(id, opts) {
 }
 
 // src/tools/doctor.ts
+var SETUP_GUIDE = "https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md";
+var CONFIG_FILE_HINT = "If your MCP host ignores the server 'env' block (e.g. Claude Desktop), put these in ~/Library/Application Support/apple-mail-mcp/config.json instead";
 async function runDoctor(mailManager2) {
   const checks = [];
   const hc = mailManager2.healthCheck();
@@ -80764,7 +80790,7 @@ async function runDoctor(mailManager2) {
     checks.push({
       name: "IMAP backend",
       status: "warn",
-      detail: `not configured \u2014 AppleScript is used for all accounts. Set ${IMAP_ENV.user} (+ Keychain/password), or ${IMAP_ENV.accounts} for multiple accounts, to enable server-side search and server-mailbox ops.`
+      detail: `not configured \u2014 AppleScript is used for all accounts. Set ${IMAP_ENV.user} (+ Keychain/password), or ${IMAP_ENV.accounts} for multiple accounts, to enable server-side search and server-mailbox ops. ${CONFIG_FILE_HINT}. Setup guide: ${SETUP_GUIDE}`
     });
   } else {
     for (const label of imapAccounts) {
@@ -80780,7 +80806,7 @@ async function runDoctor(mailManager2) {
   checks.push({
     name: "SMTP transport",
     status: isSmtpConfigured() ? "ok" : "warn",
-    detail: isSmtpConfigured() ? `configured (${smtpHost}); send-email auto-prefers clean SMTP (no Mail.app Sent-folder copy; a non-email "account" label still routes to AppleScript). Pass transport:"applescript" to force Mail.app. The apple-mail-send CLI is also available.` : `not configured \u2014 send-email uses AppleScript (subject to macOS 15+ blockquote wrapping). Set ${SMTP_ENV.host} and ${SMTP_ENV.user} (+ password via Keychain) to enable.`
+    detail: isSmtpConfigured() ? `configured (${smtpHost}); send-email auto-prefers clean SMTP (no Mail.app Sent-folder copy; a non-email "account" label still routes to AppleScript). Pass transport:"applescript" to force Mail.app. The apple-mail-send CLI is also available.` : `not configured \u2014 send-email uses AppleScript (subject to macOS 15+ blockquote wrapping). Set ${SMTP_ENV.host} and ${SMTP_ENV.user} (+ password via Keychain) to enable. ${CONFIG_FILE_HINT}. Setup guide: ${SETUP_GUIDE}`
   });
   const healthy = !checks.some((c) => c.status === "fail");
   return { healthy, checks };

package/package.json

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