apple-mail-mcp 2.8.5 → 2.8.7

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.5",
+  "version": "2.8.7",
   "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"
   ],