apple-mail-mcp 2.8.4 → 2.8.6

package/README.md

@@ -12,7 +12,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that e
 [![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)
 
 <p align="center">
-  <img src="codex/assets/screenshot.png" alt="Apple Mail MCP — read, search, send, and organize Apple Mail from Codex, Claude, and other AI assistants" width="680">
+  <img src="https://raw.githubusercontent.com/sweetrb/apple-mail-mcp/main/codex/assets/screenshot.png" alt="Apple Mail MCP — read, search, send, and organize Apple Mail from Codex, Claude, and other AI assistants" width="680">
 </p>
 
 > **Note:** This is the **npm/Node.js** package — install with `npx` or `npm`. There is an unrelated Python project of the same name on PyPI ([`imdinu/apple-mail-mcp`](https://github.com/imdinu/apple-mail-mcp)) installed via `pipx`/`uvx`. If you're using `uvx` and seeing a `cyclopts` dependency error, you're looking for that project, not this one.
@@ -43,6 +43,12 @@ Install the sweetrb/apple-mail-mcp MCP server so you can help me manage my Apple
 
 Claude will handle the installation and configuration automatically.
 
+Or register it deterministically in one command:
+
+```bash
+claude mcp add apple-mail -s user -- npx -y apple-mail-mcp
+```
+
 ### Using the Plugin Marketplace
 
 Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:
@@ -54,6 +60,11 @@ Install as a Claude Code plugin for automatic configuration and enhanced AI beha
 
 This method also installs a **skill** that teaches Claude when and how to use Apple Mail effectively.
 
+> **Configuring IMAP/SMTP for a plugin install:** a plugin install has no editable `env` block,
+> so supply settings via the config file at `~/Library/Application Support/apple-mail-mcp/config.json`
+> — Method B in the [IMAP / SMTP Setup Guide](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md).
+> Passwords stay in the macOS Keychain; run the `doctor` tool to verify.
+
 ### Using the Codex Marketplace
 
 Install the same public marketplace in Codex:
@@ -69,14 +80,14 @@ The Codex package registers the same `apple-mail` MCP server through `npx -y app
 
 Configuration for two more hosts is included — each registers the same `apple-mail` MCP server (`npx -y apple-mail-mcp`):
 
-- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in. Add the server with `hermes mcp add apple-mail --command npx --args -y apple-mail-mcp`, or merge [`.hermes-plugin/config.yaml`](.hermes-plugin/config.yaml) into `~/.hermes/config.yaml`. Details: [`.hermes-plugin/README.md`](.hermes-plugin/README.md).
-- **[Antigravity](https://antigravity.google/)** (Google) — add the server entry from [`.antigravity-plugin/mcp_config.json`](.antigravity-plugin/mcp_config.json) to `~/.gemini/config/mcp_config.json` (or via Antigravity's MCP settings).
+- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in. Add the server with `hermes mcp add apple-mail --command npx --args -y apple-mail-mcp`, or merge [`.hermes-plugin/config.yaml`](https://github.com/sweetrb/apple-mail-mcp/blob/main/.hermes-plugin/config.yaml) into `~/.hermes/config.yaml`. Details: [`.hermes-plugin/README.md`](https://github.com/sweetrb/apple-mail-mcp/blob/main/.hermes-plugin/README.md).
+- **[Antigravity](https://antigravity.google/)** (Google) — add the server entry from [`.antigravity-plugin/mcp_config.json`](https://github.com/sweetrb/apple-mail-mcp/blob/main/.antigravity-plugin/mcp_config.json) to `~/.gemini/config/mcp_config.json` (or via Antigravity's MCP settings).
 
 ### Manual Installation
 
 **1. Install the server:**
 ```bash
-npm install -g github:sweetrb/apple-mail-mcp
+npm install -g apple-mail-mcp
 ```
 
 **2. Add to Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
@@ -113,7 +124,7 @@ Both are driven by non-secret `APPLE_MAIL_MCP_*` settings — supplied via an `e
 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,
+👉 **[IMAP / SMTP Setup Guide](https://github.com/sweetrb/apple-mail-mcp/blob/main/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.
 
@@ -381,7 +392,7 @@ SMTP not configured.
 
 ##### IMAP backend — opt-in
 
-> 📘 **For step-by-step setup (app passwords, Keychain, config methods, multi-account, upgrading, troubleshooting), see the [IMAP / SMTP Setup Guide](docs/IMAP-SETUP.md).** The summary below is the reference; the guide is the walkthrough.
+> 📘 **For step-by-step setup (app passwords, Keychain, config methods, multi-account, upgrading, troubleshooting), see the [IMAP / SMTP Setup Guide](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md).** The summary below is the reference; the guide is the walkthrough.
 
 AppleScript runs `search`/`list` predicates client-side over the Apple Event
 bridge, which is slow and can time out (false-empty) on large Gmail/IMAP
@@ -1133,7 +1144,7 @@ AI: [calls move-message for each, with mailbox="Archive"]
 ### npm (Recommended)
 
 ```bash
-npm install -g github:sweetrb/apple-mail-mcp
+npm install -g apple-mail-mcp
 ```
 
 ### From Source
@@ -1145,6 +1156,8 @@ cd apple-mail-mcp
 
 The repo ships prebuilt, dependency-free `build/index.js` and `build/cli.js` bundles, so a bare clone runs with nothing but Node installed. `npm install` and `npm run build` are only needed when you change the source.
 
+> You can also install straight from GitHub with `npm install -g github:sweetrb/apple-mail-mcp`, but that builds from source (requires pnpm) — prefer the registry package above.
+
 If installed from source, use this configuration:
 ```json
 {
@@ -1189,13 +1202,12 @@ The entrypoint is written as:
 | Limitation | Reason |
 |------------|--------|
 | macOS only | Apple Mail and AppleScript are macOS-specific |
-| No sending HTML email | Emails are sent as plain text; reading HTML content is supported |
+| MCP `send-email` is plain-text | The `send-email` tool sends plain text (reading HTML content is supported). To send HTML, use the bundled `apple-mail-send` CLI with `--html-body-file` (sends `multipart/alternative` via SMTP) |
 | Attachments require absolute paths | File attachments must use full absolute paths (e.g., `/Users/me/file.pdf`) |
 | No smart mailboxes | Cannot access Smart Mailboxes via AppleScript |
 | Very large mailboxes not searchable *via AppleScript* | Apple Mail's AppleScript bridge times out on mailboxes with tens of thousands of messages, so unscoped `search-messages` skips mailboxes above `APPLE_MAIL_MAX_SEARCH_MAILBOX` (default 5000) and reports them as a partial result. Scope with `mailbox` + a date window — or configure the [IMAP backend](#imap-backend--opt-in), which searches these server-side in well under a second. ([#24](https://github.com/sweetrb/apple-mail-mcp/issues/24)) |
 | Can't delete/rename server-side mailboxes or mutate drafts *via AppleScript* | Mail.app's AppleScript bridge can only `delete`/`rename` **local "On My Mac"** mailboxes and cannot delete/move drafts — it throws `AppleEvent handler failed` for IMAP/Gmail/Workspace/iCloud/Exchange mailboxes (the GUI can do it). Without IMAP configured, `delete-mailbox`/`rename-mailbox`/`delete-message`/`move-message` return a clear "do it in Mail.app directly" error instead of a generic failure. With the [IMAP backend](#imap-backend--opt-in) configured for the account, these operations run via IMAP and succeed. ([#42](https://github.com/sweetrb/apple-mail-mcp/issues/42)) |
-| In-memory templates | Email templates are not persisted across server restarts |
-| Numeric-only message IDs | Message IDs must contain only digits (validated by schema) |
+| Message ID format | Message IDs must be numeric (AppleScript ids) or `imap:…` tokens from the IMAP read path (validated by schema) |
 | Batch size cap | Batch operations are limited to 100 messages per request |
 | Date filter format | Date filters must be valid parseable dates (e.g., "January 1, 2026" or "2026-03-15"); bare numbers or non-date strings are rejected |
 | Attachment save path restrictions | `save-attachment` only allows saving to home directory, `/tmp`, `/private/tmp`, and `/Volumes`; path traversal is blocked |
@@ -1259,7 +1271,7 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 
 ### "Permission denied"
 - macOS needs automation permission
-- Go to System Preferences > Privacy & Security > Automation
+- Go to System Settings > Privacy & Security > Automation
 - Ensure your terminal/Claude has permission to control Mail
 
 ### "Message not found"
@@ -1315,11 +1327,11 @@ A software consulting, contracting, and development company.
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+MIT License - see [LICENSE](https://github.com/sweetrb/apple-mail-mcp/blob/main/LICENSE) for details.
 
 ## Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/sweetrb/apple-mail-mcp/blob/main/CONTRIBUTING.md) for guidelines.
 
 ## Related Projects
 
@@ -1331,4 +1343,4 @@ Part of a family of macOS MCP servers:
 
 ## Recurring macOS permission prompts
 
-If macOS keeps re-prompting for Full Disk Access or Automation for `node` (often after a `brew upgrade`), see [docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md](docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md) — the fix is to run this server under the official, Developer-ID-signed Node so the grant survives Node updates.
+If macOS keeps re-prompting for Full Disk Access or Automation for `node` (often after a `brew upgrade`), see [docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md) — the fix is to run this server under the official, Developer-ID-signed Node so the grant survives Node updates.

package/build/cli.js

@@ -11868,6 +11868,12 @@ var import_nodemailer = __toESM(require_nodemailer(), 1);
 import { execFileSync } from "child_process";
 import { isAbsolute } from "path";
 import { existsSync } from "fs";
+
+// src/utils/docsUrls.ts
+var SETUP_GUIDE_URL = "https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md";
+var SETUP_HINT = `Setup guide: ${SETUP_GUIDE_URL} \u2014 run the "doctor" tool to check your setup.`;
+
+// src/services/smtpMailer.ts
 var SMTP_ENV = {
   host: "APPLE_MAIL_MCP_SMTP_HOST",
   port: "APPLE_MAIL_MCP_SMTP_PORT",
@@ -11900,7 +11906,7 @@ function resolveSmtpConfig(env = process.env) {
   if (!user) missing.push(SMTP_ENV.user);
   if (missing.length > 0) {
     throw new Error(
-      `SMTP transport is not configured. Set ${missing.join(" and ")} (plus a password via ${SMTP_ENV.password} or the Keychain). See the README "SMTP transport" section.`
+      `SMTP transport is not configured. Set ${missing.join(" and ")} (plus a password via ${SMTP_ENV.password} or the Keychain). ` + SETUP_HINT
     );
   }
   const secure = /^(1|true|yes)$/i.test(env[SMTP_ENV.secure]?.trim() ?? "");
@@ -11917,7 +11923,7 @@ function resolveSmtpConfig(env = process.env) {
   }
   if (!pass) {
     throw new Error(
-      `No SMTP password found. Set ${SMTP_ENV.password}, or store an internet password in the Keychain for service "${env[SMTP_ENV.keychainService]?.trim() || host}" / account "${env[SMTP_ENV.keychainAccount]?.trim() || user}".`
+      `No SMTP password found. Set ${SMTP_ENV.password}, or store an internet password in the Keychain for service "${env[SMTP_ENV.keychainService]?.trim() || host}" / account "${env[SMTP_ENV.keychainAccount]?.trim() || user}". ` + SETUP_HINT
     );
   }
   return { host, port, secure, user, pass, from };
@@ -12003,7 +12009,8 @@ Optional:
   --help                Show this help
 
 SMTP connection comes from ${SMTP_ENV.host} / ${SMTP_ENV.user} (+ password via
-${SMTP_ENV.password} or the macOS Keychain). See the README "SMTP transport".`;
+${SMTP_ENV.password} or the macOS Keychain). Setup guide:
+${SETUP_GUIDE_URL}`;
 async function runCli(argv, deps = {}) {
   const send = deps.send ?? sendViaSmtp;
   const resolveConfig = deps.resolveConfig ?? resolveSmtpConfig;
@@ -12052,7 +12059,7 @@ async function runCli(argv, deps = {}) {
     config = resolveConfig(env);
   } catch (e) {
     err(e instanceof Error ? e.message : String(e));
-    err(`See the README "SMTP transport" section.`);
+    err(`Setup guide: ${SETUP_GUIDE_URL}`);
     return EX_CONFIG;
   }
   let body;

package/build/index.js

@@ -76219,7 +76219,7 @@ var ERROR_MAPPINGS = [
   // Permission errors
   {
     pattern: /not authorized|not permitted|access.*denied/i,
-    message: "Permission denied. Grant automation access in System Preferences > Privacy & Security > Automation."
+    message: "Permission denied. Grant automation access in System Settings > Privacy & Security > Automation."
   },
   // Application not running
   {
@@ -79153,7 +79153,7 @@ ${actionStmts.join("\n")}
         message: "Mail.app is accessible"
       });
     } else {
-      const errorHint = mailCheck.error?.includes("not authorized") ? " (check Automation permissions in System Preferences)" : "";
+      const errorHint = mailCheck.error?.includes("not authorized") ? " (check System Settings > Privacy & Security > Automation)" : "";
       checks.push({
         name: "mail_app",
         passed: false,
@@ -79173,7 +79173,7 @@ ${actionStmts.join("\n")}
       checks.push({
         name: "permissions",
         passed: !isPermError,
-        message: isPermError ? "AppleScript permissions denied. Grant access in System Preferences > Privacy & Security > Automation" : `Permission check returned: ${permCheck.error}`
+        message: isPermError ? "AppleScript permissions denied. Grant access in System Settings > Privacy & Security > Automation" : `Permission check returned: ${permCheck.error}`
       });
       if (isPermError) {
         return { healthy: false, checks };
@@ -79409,6 +79409,12 @@ var import_nodemailer = __toESM(require_nodemailer(), 1);
 import { execFileSync } from "child_process";
 import { isAbsolute as isAbsolute2 } from "path";
 import { existsSync as existsSync3 } from "fs";
+
+// src/utils/docsUrls.ts
+var SETUP_GUIDE_URL = "https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md";
+var SETUP_HINT = `Setup guide: ${SETUP_GUIDE_URL} \u2014 run the "doctor" tool to check your setup.`;
+
+// src/services/smtpMailer.ts
 var SMTP_ENV = {
   host: "APPLE_MAIL_MCP_SMTP_HOST",
   port: "APPLE_MAIL_MCP_SMTP_PORT",
@@ -79451,7 +79457,7 @@ function resolveSmtpConfig(env = process.env) {
   if (!user) missing.push(SMTP_ENV.user);
   if (missing.length > 0) {
     throw new Error(
-      `SMTP transport is not configured. Set ${missing.join(" and ")} (plus a password via ${SMTP_ENV.password} or the Keychain). See the README "SMTP transport" section.`
+      `SMTP transport is not configured. Set ${missing.join(" and ")} (plus a password via ${SMTP_ENV.password} or the Keychain). ` + SETUP_HINT
     );
   }
   const secure = /^(1|true|yes)$/i.test(env[SMTP_ENV.secure]?.trim() ?? "");
@@ -79468,7 +79474,7 @@ function resolveSmtpConfig(env = process.env) {
   }
   if (!pass) {
     throw new Error(
-      `No SMTP password found. Set ${SMTP_ENV.password}, or store an internet password in the Keychain for service "${env[SMTP_ENV.keychainService]?.trim() || host}" / account "${env[SMTP_ENV.keychainAccount]?.trim() || user}".`
+      `No SMTP password found. Set ${SMTP_ENV.password}, or store an internet password in the Keychain for service "${env[SMTP_ENV.keychainService]?.trim() || host}" / account "${env[SMTP_ENV.keychainAccount]?.trim() || user}". ` + SETUP_HINT
     );
   }
   return { host, port, secure, user, pass, from };
@@ -79811,7 +79817,9 @@ function resolveImapConfigs(env = process.env) {
 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.`);
+    throw new Error(
+      `IMAP not configured. Set ${IMAP_ENV.user} (login address) to enable it. ${SETUP_HINT}`
+    );
   }
   let spec;
   if (account) {
@@ -80308,6 +80316,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 +80346,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 +80477,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,7 +80765,6 @@ 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 = [];
@@ -80766,7 +80797,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. ${CONFIG_FILE_HINT}. Setup guide: ${SETUP_GUIDE}`
+      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_URL}`
     });
   } else {
     for (const label of imapAccounts) {
@@ -80782,7 +80813,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. ${CONFIG_FILE_HINT}. Setup guide: ${SETUP_GUIDE}`
+    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_URL}`
   });
   const healthy = !checks.some((c) => c.status === "fail");
   return { healthy, checks };

package/docs/IMAP-SETUP.md

@@ -0,0 +1,333 @@
+# IMAP / SMTP Setup Guide
+
+`apple-mail-mcp` works out of the box over AppleScript with no configuration. The
+**IMAP backend is opt-in** and makes the server talk to your mail provider
+directly for the operations where that's faster and more reliable than driving
+Mail.app — most importantly **search, counts, and large mailboxes**, where
+AppleScript times out. Configuring **SMTP** additionally lets the server send
+clean MIME (avoiding the macOS 15+ Mail.app `<blockquote>` wrapping).
+
+This is **additive and per-account**: any account you don't configure for IMAP
+keeps using AppleScript exactly as before. You can mix — e.g. Gmail over IMAP,
+everything else over AppleScript.
+
+> **TL;DR**
+> 1. Generate an **app-specific password** at your mail provider.
+> 2. Store it in the **macOS Keychain** (the server reads it from there — it
+>    never goes in any config file).
+> 3. Tell the server which account(s) to use, via an **`env` block** or a
+>    **`config.json` file** (see Step 3 below).
+> 4. **Restart** your MCP client and run the **`doctor`** tool to verify.
+
+---
+
+## What IMAP accelerates
+
+When an account is IMAP-configured, these route to IMAP (otherwise AppleScript):
+
+| Capability | Tools |
+|------------|-------|
+| Server-side search / list | `search-messages`, `list-messages` |
+| Read a message | `get-message` |
+| Message mutations | `mark-as-read`/`unread`, `flag`/`unflag-message`, `move-message`, `delete-message` |
+| Batch mutations | `batch-mark-as-read`/`unread`, `batch-flag`/`unflag-messages`, `batch-move-messages`, `batch-delete-messages` |
+| Folder ops | `create-mailbox`, `rename-mailbox`, `delete-mailbox` |
+| Counts & stats | `get-unread-count`, `list-mailboxes`, `get-mail-stats` |
+| Attachments | `list-attachments`, `save-attachment`, `fetch-attachment` |
+| Threading | `get-thread` |
+| New-mail push | IMAP IDLE notifications (opt-in) |
+
+---
+
+## Prerequisites
+
+- macOS with Mail.app configured (the AppleScript backend still handles anything
+  not IMAP-configured).
+- **`apple-mail-mcp` v2.1.0+** for the IMAP acceleration features, and **v2.1.1+**
+  if you need the `config.json` method (see Step 3, Method B).
+- For each account: the ability to create an **app-specific password** (requires
+  2-factor auth enabled on that account).
+
+Check your version with the `doctor` tool, or `npm view apple-mail-mcp version`.
+
+---
+
+## Step 1 — Generate an app-specific password
+
+Use an **app-specific password**, never your real account password. Where to get one:
+
+- **Gmail (personal):** [myaccount.google.com](https://myaccount.google.com) →
+  **Security** → (2-Step Verification must be ON) → **App passwords** → create one,
+  name it `apple-mail-mcp`. You get a 16-character password shown **once**.
+- **Google Workspace** (e.g. a company `you@yourdomain.com` on Google): same flow,
+  signed in as that account. ⚠️ Your Workspace **admin must allow app passwords**;
+  if the option is missing, app-password IMAP isn't available for that account.
+- **iCloud:** [account.apple.com](https://account.apple.com) → **Sign-In and
+  Security** → **App-Specific Passwords**. Note the two different identities below.
+- **Other IMAP providers (Fastmail, etc.):** create an app password in the
+  provider's security settings.
+
+> **iCloud gotcha — Apple ID vs IMAP login.** Your **Apple ID** (what you sign in
+> to account.apple.com with, possibly a Gmail address) is *not* your IMAP login.
+> The IMAP **username** is your iCloud mailbox address, e.g. `you@icloud.com`
+> (or a `@me.com` alias). The app password is generated under the Apple ID but
+> authenticates the iCloud mailbox login. Also note an iCloud app password only
+> works for iCloud — it can't log into Gmail.
+
+---
+
+## Step 2 — Store the password in the Keychain
+
+The server reads the password from the macOS login Keychain via `security
+find-internet-password -s <service> -a <account>`. Add an entry to match. Run
+this in **Terminal** (the `-w` flag prompts for the password silently, so it's
+never in your shell history):
+
+```bash
+# Gmail / Google Workspace (service is always imap.gmail.com)
+security add-internet-password -U -s imap.gmail.com -a you@gmail.com -r imap -w
+
+# iCloud (service imap.mail.me.com; account is the iCloud MAILBOX address)
+security add-internet-password -U -s imap.mail.me.com -a you@icloud.com -r imap -w
+```
+
+Paste the app-specific password at the prompt and press Return. The `-s` (service)
+and `-a` (account) values must match what you put in the config in Step 3
+(`KEYCHAIN_SERVICE` / `KEYCHAIN_ACCOUNT`).
+
+If you also want **SMTP** sending and your provider uses the same app password for
+SMTP (Gmail does), you don't need a second Keychain entry — just point the SMTP
+`KEYCHAIN_SERVICE`/`KEYCHAIN_ACCOUNT` at the same item.
+
+---
+
+## Step 3 — Configure the server
+
+The server reads `APPLE_MAIL_MCP_*` settings. There are two ways to supply them;
+**use whichever your MCP client supports.**
+
+### Method A — `env` block in your MCP client config
+
+Works with clients that pass an `env` block through to the server (e.g. **Claude
+Code** via `~/.claude.json`, and most standard `mcpServers` configs).
+
+```jsonc
+{
+  "mcpServers": {
+    "apple-mail": {
+      "command": "node",
+      "args": ["/path/to/apple-mail-mcp/build/index.js"],
+      "env": {
+        "APPLE_MAIL_MCP_IMAP_USER": "you@gmail.com",
+        "APPLE_MAIL_MCP_IMAP_ACCOUNT": "you@gmail.com",
+        "APPLE_MAIL_MCP_IMAP_HOST": "imap.gmail.com",
+        "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE": "imap.gmail.com",
+        "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT": "you@gmail.com"
+      }
+    }
+  }
+}
+```
+
+### Method B — `config.json` file (for hosts that strip `env`)  *(v2.1.1+)*
+
+Some host apps (notably **Claude Desktop**) launch MCP servers with a **scrubbed
+environment and ignore the `env` block**, so Method A silently does nothing
+there. For those, put the same settings in a JSON file the host doesn't manage:
+
+- Default path: `~/Library/Application Support/apple-mail-mcp/config.json`
+- Or set `APPLE_MAIL_MCP_CONFIG_FILE` to a path of your choice.
+
+```json
+{
+  "APPLE_MAIL_MCP_IMAP_USER": "you@gmail.com",
+  "APPLE_MAIL_MCP_IMAP_ACCOUNT": "you@gmail.com",
+  "APPLE_MAIL_MCP_IMAP_HOST": "imap.gmail.com",
+  "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE": "imap.gmail.com",
+  "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT": "you@gmail.com"
+}
+```
+
+At startup the server merges these into its environment **without overriding**
+anything already set, so Method A still wins if both are present. **Only
+non-secret config goes here — passwords stay in the Keychain.**
+
+> Not sure which method? Configure with Method A; if `doctor` still says "not
+> configured" after a restart, your host strips `env` — switch to Method B.
+> Plugin-marketplace installs (Claude Code `/plugin install apple-mail`) have no
+> editable `env` block at all, so they always use Method B.
+
+### `APPLE_MAIL_MCP_IMAP_ACCOUNT` and routing
+
+`APPLE_MAIL_MCP_IMAP_ACCOUNT` should equal the **Mail.app account name** (what
+`list-accounts` shows). A tool call routes to IMAP only when its `account`
+argument matches a configured account's name or login — so this value is how the
+server knows "calls for this account go to IMAP."
+
+### Multiple accounts
+
+Configure additional accounts with `APPLE_MAIL_MCP_IMAP_ACCOUNTS`, a JSON **array
+of objects, passed as a single string value** (the whole array is one env-var /
+config-file string, as in the example below). The legacy single-account
+vars above define the first/default account; the array adds the rest:
+
+```json
+{
+  "APPLE_MAIL_MCP_IMAP_USER": "you@gmail.com",
+  "APPLE_MAIL_MCP_IMAP_ACCOUNT": "you@gmail.com",
+  "APPLE_MAIL_MCP_IMAP_HOST": "imap.gmail.com",
+  "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE": "imap.gmail.com",
+  "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT": "you@gmail.com",
+  "APPLE_MAIL_MCP_IMAP_ACCOUNTS": "[{\"account\":\"Work\",\"user\":\"you@company.com\",\"host\":\"imap.gmail.com\",\"keychainService\":\"imap.gmail.com\",\"keychainAccount\":\"you@company.com\"},{\"account\":\"iCloud\",\"user\":\"you@icloud.com\",\"host\":\"imap.mail.me.com\",\"keychainService\":\"imap.mail.me.com\",\"keychainAccount\":\"you@icloud.com\"}]"
+}
+```
+
+Each array entry accepts: `account`, `user`, `host`, `port`, `password`
+(discouraged — prefer Keychain), `keychainService`, `keychainAccount`. Each
+account keeps its own pooled IMAP connection.
+
+---
+
+## Step 4 (optional) — SMTP sending
+
+Lets `send-email` submit clean MIME directly (use `transport: "smtp"`), avoiding
+the macOS 15+ blockquote wrapping. SMTP is single-account (the default sender):
+
+```json
+{
+  "APPLE_MAIL_MCP_SMTP_HOST": "smtp.gmail.com",
+  "APPLE_MAIL_MCP_SMTP_PORT": "587",
+  "APPLE_MAIL_MCP_SMTP_USER": "you@gmail.com",
+  "APPLE_MAIL_MCP_SMTP_FROM": "you@gmail.com",
+  "APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE": "imap.gmail.com",
+  "APPLE_MAIL_MCP_SMTP_KEYCHAIN_ACCOUNT": "you@gmail.com"
+}
+```
+
+(Reusing the IMAP Keychain item is fine when the provider accepts the same app
+password for SMTP, as Gmail does.)
+
+---
+
+## Step 5 (optional) — New-mail push (IMAP IDLE)
+
+Add `"APPLE_MAIL_MCP_IMAP_IDLE": "1"` to get new-mail notifications for every
+configured IMAP account. See the README's "Push notifications (IMAP IDLE)"
+section for details. Tune the pooled-connection idle timeout with
+`APPLE_MAIL_MCP_IMAP_IDLE_MS` (default `30000`; `0` = never close).
+
+---
+
+## Step 6 — Restart and verify
+
+1. **Restart your MCP client** so the server picks up the new config (env and
+   config-file changes are read at startup).
+2. Run the **`doctor`** tool. Each configured account should report:
+   `IMAP: <account> → connected to <host>`, and SMTP `configured` if you set it up.
+
+If an account shows `connection failed`, see Troubleshooting.
+
+---
+
+## Upgrading from an earlier version
+
+- **From a version with no IMAP backend (before 1.7.0):** IMAP is purely
+  additive — nothing you had changes. Just follow Steps 1–6 for the accounts you
+  want to accelerate.
+- **From 2.0.0 / 2.1.0:** the optimizations (attachments, batch, counts/stats,
+  threading) light up automatically for any account already IMAP-configured — no
+  new setup needed. If you weren't using IMAP yet, follow Steps 1–6.
+- **If your host app strips `env`** (e.g. Claude Desktop): upgrade to **2.1.1+**
+  and move your settings into `config.json` (Method B). This is the most common
+  reason an upgrade "doesn't seem to use IMAP."
+- **Already had iCloud working, now adding Gmail:** remember each provider needs
+  its **own** app password — an iCloud password can't authenticate Gmail.
+
+---
+
+## Troubleshooting
+
+**`doctor` says "IMAP backend: not configured" after a restart.**
+The server isn't seeing your settings. Most often the host stripped the `env`
+block — switch to the `config.json` method (Method B) and confirm the file is at
+`~/Library/Application Support/apple-mail-mcp/config.json` (or wherever
+`APPLE_MAIL_MCP_CONFIG_FILE` points). Verify it parses: `python3 -m json.tool < <path>`.
+
+**`doctor` says "connection failed" for an account.**
+- The Keychain item is missing or under a different service/account. Check:
+  `security find-internet-password -s imap.gmail.com -a you@gmail.com` (should
+  return without "could not be found"). It must match your `KEYCHAIN_SERVICE` /
+  `KEYCHAIN_ACCOUNT`.
+- You used your real password instead of an **app-specific** password.
+- **iCloud:** you used your Apple ID as the login instead of the iCloud mailbox
+  address; try `you@icloud.com`, the `@me.com` alias, or the bare local part.
+- **Workspace:** your admin disabled app passwords (or requires OAuth) — IMAP via
+  app password isn't available for that account.
+
+**Storing the Keychain password over SSH / headless fails with `User interaction is not allowed`.**
+`security add-internet-password` — and the server *reading* the password back —
+need the login Keychain **unlocked**, which normally only happens in a **GUI login
+session**. From a plain `ssh` session the Keychain is locked, so the write fails
+with `SecKeychainAddInternetPassword: User interaction is not allowed` (exit 36),
+and a server started there can't read passwords either. Options:
+
+- **Run it in a GUI session** — a Terminal on the Mac itself, or via Screen Sharing.
+- **Unlock over SSH with a tty:**
+  `ssh -t you@host 'security unlock-keychain && security add-internet-password -U -r imap -s imap.gmail.com -a you@gmail.com -w'`
+  — the `-t` lets `unlock-keychain` prompt for your macOS **login** password, after
+  which the add (and later server reads) succeed. A metadata check —
+  `security find-internet-password -s … -a …` with no `-w` — does work over plain
+  ssh, so you can confirm an item *exists* even when you can't unlock it.
+- **Truly headless** (CI, or a server with no GUI login and no unlockable Keychain):
+  skip the Keychain — set `APPLE_MAIL_MCP_SMTP_PASSWORD` / `APPLE_MAIL_MCP_IMAP_PASSWORD`
+  (or a per-account `"password"` inside `APPLE_MAIL_MCP_IMAP_ACCOUNTS`) directly, and
+  restrict the config file's permissions to the service account.
+
+**Calls aren't routing to IMAP even though `doctor` shows connected.**
+The tool's `account` argument must match the configured account's name/login.
+Set `APPLE_MAIL_MCP_IMAP_ACCOUNT` to the exact Mail.app account name from
+`list-accounts`, and pass that same `account` to tools.
+
+**A disabled Mail account.** IMAP connects to the server directly, so it works
+even if the account is disabled in Mail.app — useful for reaching an account the
+GUI is ignoring.
+
+---
+
+## Security notes
+
+- **Passwords live only in the macOS Keychain.** No config file or env value
+  here holds a secret — only account names, hosts, and Keychain *references*.
+  (You *can* put a `password` directly in config, but don't.)
+- Use **app-specific passwords** so you can revoke access per-integration without
+  changing your real password.
+- The `config.json` and env values are non-sensitive (addresses/hosts), but
+  there's no reason to share them either.
+
+---
+
+## Full environment variable reference
+
+| 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_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_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_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. |
+| `APPLE_MAIL_MCP_SMTP_USER` / `_FROM` | SMTP login / From address. |
+| `APPLE_MAIL_MCP_SMTP_PASSWORD` | Password (discouraged; prefer Keychain). |
+| `APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE` / `_KEYCHAIN_ACCOUNT` | SMTP Keychain reference. |
+| `APPLE_MAIL_MCP_CONFIG_FILE` | Path to the config JSON (default app-support dir). |
+| `APPLE_MAIL_MCP_TEMPLATES_FILE` | Email-templates store path (default `~/Library/Application Support/apple-mail-mcp/templates.json`). |
+| `APPLE_MAIL_MCP_MAX_BUFFER` | Max AppleScript (`osascript`) output buffer in bytes (default 64 MiB). |
+| `APPLE_MAIL_MAX_SEARCH_MAILBOX` | Per-mailbox message-count guard for unscoped AppleScript search (default `5000`; `0` disables). Note: no `_MCP` in the name. |

package/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md

@@ -0,0 +1,109 @@
+# Node runtime & TCC permission stability
+
+macOS gates this MCP server's access to your data behind **TCC** permissions —
+**Full Disk Access** (to read app data such as Mail, Notes, or Photos) and
+**Automation / Apple Events** (to drive an app like Mail.app or Notes.app via
+AppleScript). See this repo's Full Disk Access / Automation notes for *which*
+operations need which permission.
+
+This page is about a **separate, recurring annoyance**: being asked to approve
+those permissions **over and over**, often right after a routine `brew upgrade`.
+
+## Symptom
+
+- You granted Full Disk Access (and/or Automation) to "node", but days later
+  macOS prompts again — `"node" wants access to ...` or `"node" wants to control
+  "Mail"`.
+- System Settings → Privacy & Security → Full Disk Access shows **several
+  identical "node" rows**, usually only one enabled.
+- It tends to happen immediately after you update Node.
+
+## Cause
+
+TCC binds a permission grant to the **code identity of the binary that performs
+the access** — here, the `node` executable that launches the MCP server. For a
+binary that is only **ad-hoc signed** (no Developer ID / Team ID), TCC keys the
+grant to the binary's **cdhash**, a hash of its contents.
+
+Homebrew's `node` formula is ad-hoc signed:
+
+```bash
+$ codesign -dvvv "$(which node)" 2>&1 | grep -E 'Signature|TeamIdentifier'
+Signature=adhoc
+TeamIdentifier=not set
+```
+
+Every Node update **replaces the binary**, which **changes the cdhash**, so TCC
+no longer recognizes it as the thing you approved — and re-prompts. The extra
+"node" rows are stale cdhashes from previous versions.
+
+By contrast, properly signed apps (Chrome, Slack, …) keep their permissions
+across auto-updates because TCC matches them on a stable **Designated
+Requirement** derived from their Developer ID, not on the cdhash.
+
+## Fix: run the MCP under the official, Developer-ID-signed Node
+
+Node binaries distributed from **nodejs.org** are signed with a real Developer
+ID (`Node.js Foundation`, Team `HX7739G8FX`), notarized, and self-contained.
+Pointing the MCP server at one gives TCC a **stable** identity to match, so a
+permission you grant **persists across future Node updates**. It also decouples
+the MCP runtime from your Homebrew/dev Node, which can keep updating freely.
+
+### Steps (Apple Silicon shown; use `darwin-x64` on Intel)
+
+1. Install a current LTS to a stable path (kept off `PATH` so it won't shadow
+   your dev Node):
+
+   ```bash
+   VER=v24.17.0 ARCH=darwin-arm64
+   mkdir -p ~/mcp-runtime && cd ~/mcp-runtime
+   curl -O https://nodejs.org/dist/$VER/node-$VER-$ARCH.tar.gz
+   curl -O https://nodejs.org/dist/$VER/SHASUMS256.txt
+   grep "  node-$VER-$ARCH.tar.gz$" SHASUMS256.txt | shasum -a 256 -c -   # must print OK
+   tar -xzf node-$VER-$ARCH.tar.gz
+   ln -sfn node-$VER-$ARCH node-current
+   ```
+
+2. Confirm it's Developer-ID signed:
+
+   ```bash
+   codesign -dvvv ~/mcp-runtime/node-current/bin/node 2>&1 | grep -E 'Authority=Developer ID|TeamIdentifier'
+   # Authority=Developer ID Application: Node.js Foundation (HX7739G8FX)
+   # TeamIdentifier=HX7739G8FX
+   ```
+
+3. Point this MCP server's launcher at it. For Claude Desktop, edit
+   `~/Library/Application Support/Claude/claude_desktop_config.json` and set this
+   server's `command` to the absolute path:
+
+   ```json
+   {
+     "mcpServers": {
+       "apple-mail": {
+         "command": "/Users/<you>/mcp-runtime/node-current/bin/node",
+         "args": ["/path/to/apple-mail-mcp/build/index.js"]
+       }
+     }
+   }
+   ```
+
+   Servers launched via `npx` that don't need Full Disk Access can stay on
+   Homebrew Node.
+
+4. **Restart your MCP client** so the server relaunches under the new Node.
+
+5. **Grant the permissions once** to the new binary:
+   - *Full Disk Access*: System Settings → Privacy & Security → Full Disk Access
+     → **+** → ⌘⇧G → paste `~/mcp-runtime/node-current/bin/node`.
+   - *Automation*: the first time the server drives an app you'll get a one-time
+     `"node" wants to control "<App>"` prompt — click **Allow**.
+
+   Both grants are keyed to the official Node's stable signature, so you should
+   not be asked again — including after future Node updates. You can delete the
+   stale "node" rows from the Full Disk Access list.
+
+### Updating the dedicated Node later
+
+Drop a newer official LTS tarball into `~/mcp-runtime/`, repoint the
+`node-current` symlink, and restart your client. The signing identity is
+unchanged, so existing grants carry over — no re-approval.

package/docs/STABILITY-PERF-AUDIT-2026-06-17.md

@@ -0,0 +1,131 @@
+# apple-mail-mcp — Stability & Performance Audit
+
+**Date:** 2026-06-17 · **Version audited:** 1.6.1 (`main` @ `4b5610d`)
+**Scope:** full codebase — `appleMailManager.ts` (2652 LOC), `index.ts`, `utils/{applescript,serialize,mimeParse}.ts`, CI/publish workflows.
+
+This audit looks only at robustness and speed; feature gaps and style are out of scope. Findings are ranked by **impact × likelihood**, with effort estimates so they can be scheduled. Line numbers are against `main` @ `4b5610d`.
+
+> **Resolution status (all items addressed 2026-06-17).** Every finding below has shipped or been explicitly deferred:
+>
+> | # | Finding | Status | Released |
+> |---|---------|--------|----------|
+> | 1 | execSync maxBuffer | Fixed ([#27](https://github.com/sweetrb/apple-mail-mcp/issues/27)) | 1.6.2 |
+> | 2 | stats locale + swallow | Fixed ([#28](https://github.com/sweetrb/apple-mail-mcp/issues/28)) | 1.6.3 |
+> | 3 | list-messages / by-id swallow | Fixed ([#29](https://github.com/sweetrb/apple-mail-mcp/issues/29)) | 1.6.4 |
+> | 4 | `\|\|\|` delimiter collisions | Fixed ([#30](https://github.com/sweetrb/apple-mail-mcp/issues/30)) | 1.6.5 |
+> | 5 | batch fan-out | Fixed ([#31](https://github.com/sweetrb/apple-mail-mcp/issues/31)) | 1.6.6 |
+> | 6+7 | get-message source scan / preferHtml | Fixed ([#32](https://github.com/sweetrb/apple-mail-mcp/issues/32)) | 1.6.7 |
+> | 9 | rename-mailbox partial-move | Fixed ([#33](https://github.com/sweetrb/apple-mail-mcp/issues/33)) | 1.6.8 |
+> | 10 | escape control chars | Fixed (audit hardening) | 1.6.9 |
+> | 8 | aggregate stat timeouts | Fixed (audit hardening) | 1.6.9 |
+> | 12 | saveAttachment prefix bypass | Fixed (audit hardening) | 1.6.9 |
+> | 13 | searchContacts per-person try | Fixed (audit hardening) | 1.6.9 |
+> | 14 | useTemplate empty override | Fixed (audit hardening) | 1.6.9 |
+> | 11 | per-message bulk reads | **Deferred** — the #24 count-guard now bounds scans to small mailboxes, so the refactor's regression risk on the hottest paths outweighs the gain | — |
+> | 15 | CI can't run integration suite | Addressed — `npm run test:all` documented as a pre-release gate in CONTRIBUTING; the release-publish race was also fixed with a `concurrency` guard on `publish.yml` | — |
+>
+> Known limitation surfaced during validation: Mail.app **cannot delete iCloud mailboxes via AppleScript** ("AppleEvent handler failed"), so `delete-mailbox` / `rename-mailbox` cannot complete on iCloud-account mailboxes. This is a platform constraint, not a code defect; the rename fix ensures it fails *safely* (source preserved).
+
+## Summary
+
+The architecture is sound and several hard problems are already solved well (serial gate for Mail's single-threaded dispatch #11, the `with timeout`/SIGKILL executor, the `error:`-prefix protocol that surfaces AppleScript failures, the #24 search count-guard). The remaining risks cluster into four themes:
+
+1. **Swallowed failures that masquerade as empty/zero success** — the #24 family. Several read methods still do this (`list-messages`, `get-mail-stats`, `get-recently-received`, by-id lookups). This is the single highest-value theme because it produces *confidently wrong* answers.
+2. **The `1 MB execSync buffer** — every osascript call is capped at Node's default `maxBuffer`, so large messages/sources silently fail.
+3. **`|||` delimiter collisions** — the string serialization corrupts on any field containing `|||`.
+4. **N× full-tree-walk fan-out** in batch operations — correct but pathologically slow at scale.
+
+## Priority table
+
+| # | Sev | Type | Finding | Effort |
+|---|-----|------|---------|--------|
+| 1 | High | stability | No `maxBuffer` on `execSync` → 1 MB cap truncates/throws on large messages, `getRawSource`, attachment extraction | S |
+| 2 | High | stability | `get-mail-stats` / `get-recently-received` reintroduce the #15 locale bug + swallow → silent `0/0/0` | S |
+| 3 | High | stability | `list-messages` & by-id lookups still have the #24 unbounded-all-mailbox + swallowed-timeout pattern (false empty) | M |
+| 4 | High | stability | `\|\|\|` / `\|\|\|ITEM\|\|\|` delimiter collisions corrupt every parser on hostile/odd field values | M |
+| 5 | High | perf | Batch ops are N separate osascript spawns, each a full account→mailbox→`whose id` tree walk | M |
+| 6 | Med | perf/stability | `get-message` always reads full `source of msg` for attachmentless messages (slow; trips finding #1) | S |
+| 7 | Med | stability | `get-message preferHtml` returns raw MIME source mislabeled as `htmlContent` (dumps base64 into context) | S |
+| 8 | Med | stability | All-mailbox stat methods (`list-mailboxes`, `get-unread-count`, `get-sync-status`) on default 30s → silent empty/zero on timeout | S |
+| 9 | Med | stability | `rename-mailbox` move-then-delete has no rollback / partial-move accounting (data-loss risk on large mailboxes) | M |
+| 10 | Med | stability | `escapeForAppleScript` doesn't neutralize newlines/control chars in interpolated names/subjects | S |
+| 11 | Low | perf | Per-message property round-trips in search/list (≥6 reads/msg); could bulk-read on small mailboxes | M |
+| 12 | Low | stability | `saveAttachment` path-prefix check uses bare `startsWith` (sibling-prefix bypass: `/Volumes` vs `/Volumes-evil`) | S |
+| 13 | Low | stability | `searchContacts` lacks per-person `try` → one bad contact aborts the whole search | S |
+| 14 | Low | stability | `useTemplate` `overrides.x || template.x` drops intentional empty-string overrides; templates in-memory only | S |
+| 15 | Low | process | Integration suite can't run in CI; real-Mail regressions only caught by local `npm run test:all` | M |
+
+Effort: S ≈ <½ day, M ≈ ½–2 days.
+
+---
+
+## High severity
+
+### 1. No `maxBuffer` on `execSync` — 1 MB cap truncates large outputs
+`executeAppleScript` (`utils/applescript.ts:349`) calls `execSync` with `encoding`, `timeout`, `killSignal`, `stdio` — but **no `maxBuffer`**, so Node's 1 MB default applies to every Mail operation. `getRawSource` (`appleMailManager.ts:922`) explicitly anticipates *20 MB* sources; `getMessageContent` returns full `source of msg` as `htmlContent`; large `search`/`list` outputs accumulate too. When output exceeds 1 MB, `execSync` throws `ENOBUFS`, which the executor reports as a failure, and the caller returns `null` → the user sees "message not found" / "attachment not found" or missing body for exactly the large/attachment-bearing messages where it matters most.
+**Fix:** set a generous `maxBuffer` (e.g. 64 MB) in the `execSync` options, ideally configurable via env. Cheap and high-value.
+
+### 2. `get-mail-stats` / `get-recently-received` — locale bug + swallow → silent `0/0/0`
+`getRecentlyReceivedStats` (`appleMailManager.ts:2506`) builds AppleScript date thresholds with hard-coded English month names: `date "January 5, 2026"` (`formatDate`, lines 2514–2539). This is the exact construct issue **#15** replaced with the locale-independent `buildAppleScriptDate` (line ~246) because `date "May 30, 2026"` throws *"Invalid date and time (-30720)"* on non-English system locales. The throw is swallowed by the nested per-account/per-inbox `try` blocks (2542, 2546), so on any non-English locale the method returns `{last24h:0, last7d:0, last30d:0}` as a clean success — and it feeds `getMailStats`. A correctness regression of the same class as #24.
+**Fix:** build the three thresholds with `buildAppleScriptDate`; surface failure instead of returning zero.
+
+### 3. `list-messages` and by-id lookups still carry the #24 pattern
+The #24 fix landed only on `searchMessages`. `listMessages` (all-mailboxes branch, `appleMailManager.ts:803–842`) still iterates every mailbox with an unbounded `messages of mb` materialization and a swallowing per-mailbox `try`, returning `[]` on timeout — a false "No messages found" on large multi-account setups. `getMessageById` / `getMessageContent` / `getRawSource` (789–942) likewise walk every mailbox of every account with no count-guard and a swallowing `on error … return ""`, so a slow account makes a real message look deleted.
+**Fix:** extend the #24 approach (count-guard via `APPLE_MAIL_MAX_SEARCH_MAILBOX`, per-account budget, partial-result diagnostics) to `listMessages`; for by-id lookups, add the count-guard and distinguish "not found" from "timed out."
+
+### 4. `|||` delimiter collisions corrupt parsing
+Results are serialized by concatenating fields with the literal `"|||"` and records with `"|||ITEM|||"`, then split in TS. No field value is sanitized first. Any subject, sender, contact name, attachment filename, or mailbox name containing `|||` shifts every subsequent field. Vulnerable parsers include `parseMessageList` (~1086), `getMessageById` (843), `getMessageContent` (898), `listAttachments` (~1785), `listMailboxes` (~1938), `fetchAccounts` (~2127), `listRules` (~2193), `searchContacts` (~2285), `getSyncStatus` (~2639). Concretely, an attachment named `report|||v2.pdf` makes the parser read `v2.pdf` as the MIME type and `parseInt` the size as `0`. `fetchMailboxNames` (~2148) is a separate variant that splits on `", "`, colliding with any mailbox name containing a comma-space.
+**Fix:** switch field/record separators to ASCII control characters that cannot appear in mail text (Unit Separator ``, Record Separator ``), or length-prefix/JSON-encode each record. Update both the AppleScript emitters and the TS parsers together.
+
+### 5. Batch operations are N× full-tree-walk osascript spawns
+`batchDeleteMessages` (1656), `batchMoveMessages` (1679), `batchMarkAsRead/Unread` (1697/1709), `batchFlag/Unflag` (1725+) each loop over the ids calling the single-id method. Every single-id method spawns its own osascript and walks `accounts → mailboxes of acct → messages whose id is …` to locate one message. So a 100-id batch = 100 processes, each a full breadth-first tree scan with a `whose id` query per mailbox, all serialized through the gate — minutes to hours on large accounts. (The batch APIs are capped at 100 ids, which bounds but doesn't fix it.)
+**Fix:** one AppleScript that takes the whole id list, walks the tree once, and returns a per-id result vector; parse into `BatchOperationResult[]`.
+
+---
+
+## Medium severity
+
+### 6. `get-message` always full-source-scans attachmentless messages
+`getMessageById` (789) computes `hasAttachments` by reading the entire `source of msg` whenever the fast attachment count is 0 (819–824), to catch MIME-embedded attachments. That's the slowest part of the common path and it interacts badly with finding #1 (1 MB cap). **Fix:** make the source-scan opt-in (e.g. a `deepAttachmentCheck` flag) or skip it when the fast count suffices for the caller.
+
+### 7. `preferHtml` returns raw MIME, not HTML
+`getMessageContent` (865) sets `htmlContent = source of msg` — the entire raw MIME (headers + base64 attachments), not the HTML body. `get-message preferHtml:true` (`index.ts:256`) then returns that whole blob into the model context: token blowup plus the 1 MB buffer risk. **Fix:** extract the `text/html` MIME part (you already have `mimeParse.ts`), or rename/redocument and bound the size.
+
+### 8. All-mailbox stat methods silently degrade on 30s timeout
+`listMailboxes` (~1913), `getUnreadCount` no-mailbox path (~1966), `getSyncStatus` (~2607) iterate all mailboxes/accounts at the **default 30s** timeout and return `[]`/`0` on timeout — a false "all read"/"no mailboxes." **Fix:** raise timeouts for these aggregate scans and surface partial/error rather than benign zeros.
+
+### 9. `rename-mailbox` partial-move data-loss risk
+`renameMailbox` (~2046) creates the destination, moves messages in a loop, then deletes the source — all in one `try`. A mid-loop error jumps to `on error` with no rollback and no count of how many moved, leaving messages split across two mailboxes; mutating `messages of srcMailbox` while iterating it is itself unsafe. On a large mailbox the move can also exceed the 60s timeout and be SIGKILLed before completion. **Fix:** snapshot ids, verify source/destination counts match before deleting the source, and report partial moves.
+
+### 10. `escapeForAppleScript` doesn't handle newlines/control chars
+`escapeForAppleScript` (155) escapes `\` and `"` but not raw newlines. AppleScript string literals can't span raw newlines, so a mailbox/template/contact name or subject containing `\n` can terminate the literal and inject a statement (or just error). Inputs are otherwise nicely escaped/validated — this is the one gap. **Fix:** strip or escape control characters (`\n`, `\r`, `\t`, line-continuation) in the escape function.
+
+---
+
+## Low severity
+
+- **11 — per-message round-trips** (search/list): each emitted message does ≥6 property reads (`subject of msg`, `sender of msg`, …); on a mailbox these are serial Apple Events. Bulk list-property reads (`subject of msgs`, `sender of msgs`) cut round-trips on the small mailboxes that survive the #24 guard. Measure first.
+- **12 — `saveAttachment` prefix check** (~1831/1890): `startsWith(homedir())` allows `/Users/robother`; `startsWith("/Volumes")` allows `/Volumes-evil`. Compare against `prefix + path.sep` or use a `path.relative` containment check.
+- **13 — `searchContacts`** (~2250): no per-person `try`, so one contact with no `emails` aborts the scan and returns `[]`. Wrap the per-person read.
+- **14 — templates**: `useTemplate` `overrides.subject || template.subject` (~2358) discards an intentional `""` override; the `Map` is in-memory and `nextTemplateId` resets to 1 each start, so ids collide across restarts. Documented limitation — note in README or persist.
+- **15 — CI can't run integration tests**: `ci.yml` runs unit tests/lint/typecheck/build + a nice "committed build/ matches source" guard, but the real-Mail `test:integration` suite needs a GUI Mail.app and so only runs locally. Real AppleScript regressions can ship. Mitigation: make `npm run test:all` a documented pre-release gate (or a self-hosted runner).
+
+---
+
+## What's already done well (don't regress these)
+
+- **Serial gate** (`utils/serialize.ts`) — correctly funnels all Mail calls through one promise chain with a settle delay; the right fix for Mail's single-threaded dispatch (#11).
+- **Executor hardening** (`utils/applescript.ts`) — `with timeout` a few seconds under the process timeout so Mail aborts cleanly from inside its own dispatch, `SIGKILL` to reap wedged osascript, retry with backoff on transient errors, user-friendly error mapping.
+- **`error:`-prefix protocol** — move/delete/reply/forward/mark/mailbox ops return `"error:" & errMsg` from `on error` and TS checks for it, surfacing AppleScript-level failures that `result.success` alone misses. The methods that *don't* use it (findings #2, #3, #8) are exactly where the swallow bugs live.
+- **`moveMessageInternal`** — account-scoped resolution, explicit ambiguity refusal, distinct error strings, `{success,error}` return; the model the batch path should adopt.
+- **Attachment input validation** — rejects path traversal/separators/null in names; resolves + prefix-checks save paths (modulo the `startsWith` nit in #12).
+- **Cache stores mailbox *names* only** (not counts) with invalidation wired on the three structure-changing ops — the right call.
+- **#24 search fix** — count-guard + per-account budget + partial diagnostics; findings #2/#3/#8 are about extending that discipline to the rest of the read surface.
+
+## Suggested sequencing
+
+1. **Quick wins (one small PR):** #1 maxBuffer, #2 locale/swallow, #10 escape control chars, #12 prefix check. All small, all pure stability.
+2. **The swallow-family PR:** #3 (extend #24 guard to list/by-id) + #8 (aggregate stat timeouts) — shares code with the #24 work.
+3. **The serialization PR:** #4 delimiters (touches many emitters/parsers; do it once, carefully, with tests).
+4. **The perf PR:** #5 batch single-walk, then measure #11 before investing.
+5. #6/#7/#9 as standalone medium fixes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.8.4",
+  "version": "2.8.6",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",
@@ -10,6 +10,7 @@
   },
   "files": [
     "build",
+    "docs",
     "README.md",
     "LICENSE"
   ],