apple-mail-mcp 1.8.1 → 2.0.0

package/README.md

@@ -86,17 +86,21 @@ On first use, macOS will ask for permission to automate Mail.app. Click "OK" to
 | **List Messages** | List messages with pagination, sender filter, date display |
 | **Search Messages** | Search by sender, subject, content, date range, read/flagged status — across all accounts |
 | **Read Messages** | Get full email content (plain text or HTML) |
-| **Send Email** | Compose and send new emails (with optional file attachments) |
+| **Send Email** | Compose and send new emails (attach by file path or inline base64 content) |
 | **Send Serial Email** | Mail merge — send personalized emails to a list of recipients with {{placeholder}} support |
-| **Create Draft** | Save emails to Drafts folder (with optional file attachments) |
+| **Create Draft** | Save emails to Drafts folder (attach by file path or inline base64 content) |
 | **Reply** | Reply to messages (with reply-all support) |
 | **Forward** | Forward messages to new recipients |
+| **Get Thread** | Group a conversation by normalized subject (across AppleScript or IMAP) |
 | **Mark Read/Unread** | Change read status (single or batch) |
 | **Flag/Unflag** | Flag or unflag messages (single or batch) |
 | **Delete Messages** | Move messages to trash (single or batch) |
 | **Move Messages** | Organize into mailboxes (single or batch) |
 | **List Attachments** | View attachment metadata (name, type, size) |
 | **Save Attachment** | Save attachments to disk |
+| **Fetch Attachment** | Get an attachment's bytes as base64 (no disk write) |
+
+Read/list/get tools also return **structured JSON** (`structuredContent`) alongside the text, so agents can consume results without parsing prose.
 
 ### Mailbox & Account Management
 
@@ -113,17 +117,25 @@ On first use, macOS will ask for permission to automate Mail.app. Click "OK" to
 |---------|-------------|
 | **List Rules** | View all mail rules and their enabled status |
 | **Enable/Disable Rules** | Toggle mail rules on or off |
+| **Create/Delete Rules** | Create rules with conditions + actions, or delete by name |
 | **Search Contacts** | Look up contacts from Contacts.app by name |
-| **Email Templates** | Save, list, use, and delete reusable email templates |
+| **Email Templates** | Save, list, use, and delete reusable email templates (persisted to disk across restarts) |
 
 ### Diagnostics
 
 | Feature | Description |
 |---------|-------------|
 | **Health Check** | Verify Mail.app connectivity |
+| **Doctor** | Diagnose Mail permission, account state, and each IMAP/SMTP backend with actionable messages |
 | **Statistics** | Message and unread counts per account, recently received stats |
 | **Sync Status** | Check if Mail.app is actively syncing |
 
+### MCP resources & prompts
+
+Resources expose read-only context the client can attach without a tool call:
+`mail://accounts`, `mail://templates`, and `mail://mailboxes/{account}`. Prompts
+package common workflows: `triage-inbox`, `compose-reply`, `weekly-summary`.
+
 ---
 
 ## Tool Reference
@@ -214,7 +226,7 @@ Send a new email immediately.
 | `cc` | string[] | No | CC recipients |
 | `bcc` | string[] | No | BCC recipients |
 | `account` | string | No | Send from specific account (with `transport: "smtp"`, overrides the From address) |
-| `attachments` | string[] | No | Absolute file paths to attach, max 20 files (e.g., `["/Users/me/report.pdf"]`) |
+| `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments: absolute file paths (e.g., `"/Users/me/report.pdf"`) and/or inline `{filename, contentBase64}` objects for content not on disk |
 | `transport` | `"applescript"` \| `"smtp"` | No | Send transport (default `"applescript"`). Use `"smtp"` to send clean MIME directly, avoiding the macOS 15+ Mail.app `<blockquote>` wrapping — see [SMTP transport](#smtp-transport) |
 
 **Example:**
@@ -270,24 +282,31 @@ Then send:
 
 The default `applescript` transport is unchanged; SMTP is opt-in per call.
 
-##### IMAP backend (read/search) — opt-in, Phase 1
+##### IMAP backend — opt-in
 
 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
-mailboxes (see [#24](https://github.com/sweetrb/apple-mail-mcp/issues/24)). When
-an account is configured for IMAP, `search-messages` and `list-messages` instead
-run a **server-side IMAP search** ([#43](https://github.com/sweetrb/apple-mail-mcp/issues/43)) —
-typically sub-second and correct on the same mailbox where AppleScript times out.
-This is **opt-in and additive**: any account without IMAP configured behaves
-exactly as before (AppleScript). When an account is IMAP-configured,
-`search-messages`/`list-messages` (read) and `create-mailbox`/`rename-mailbox`/
-`delete-mailbox` (folder ops) route to IMAP. The folder ops are the key win for
-server accounts: IMAP's `CREATE`/`RENAME`/`DELETE` succeed on exactly the
-iCloud/Gmail/Workspace/Exchange mailboxes where Mail.app's AppleScript bridge
-can't (#42). `get-message` and message-level mutations (mark/flag/move/delete-
-message) stay on AppleScript for now — they key off a message id, and the IMAP
-read rows report **UIDs** (a different, per-mailbox namespace), so routing them
-safely needs a UID-aware design (tracked on #43).
+mailboxes (see [#24](https://github.com/sweetrb/apple-mail-mcp/issues/24)), and
+its `delete`/`rename mailbox` and draft handlers don't work on server-side
+accounts at all (#42). When an account is configured for IMAP, the MCP routes to
+a server-side IMAP backend ([#43](https://github.com/sweetrb/apple-mail-mcp/issues/43))
+that is fast and correct on exactly those mailboxes. This is **opt-in and
+additive**: any account without IMAP configured behaves exactly as before
+(AppleScript).
+
+What routes to IMAP when an account is IMAP-configured:
+
+- **Read:** `search-messages`, `list-messages` (server-side `SEARCH`, typically sub-second), and `get-message`.
+- **Folder ops:** `create-mailbox`, `rename-mailbox`, `delete-mailbox` — IMAP's `CREATE`/`RENAME`/`DELETE` succeed on the iCloud/Gmail/Workspace/Exchange mailboxes Mail.app's AppleScript bridge can't touch (#42).
+- **Message mutations:** `mark-as-read`/`unread`, `flag-message`/`unflag-message`, `move-message`, `delete-message`.
+
+**Message ids are backend-tagged.** The IMAP read path emits self-describing ids
+of the form `imap:<token>` (the token encodes the account, mailbox path, and
+UID). Pass that id back to `get-message` or any message mutation and it routes to
+IMAP automatically; bare numeric ids continue to use AppleScript. So an agent
+never has to know which backend a message came from — the id carries it. (Batch
+operations remain AppleScript-only and accept numeric ids; use the single-message
+tools for IMAP ids.)
 
 Routing is conservative: only a call whose explicit `account` matches the
 configured IMAP account goes to IMAP; everything else falls through to
@@ -302,6 +321,20 @@ AppleScript.
 | `APPLE_MAIL_MCP_IMAP_PASSWORD` | No | — | Password (if set, used instead of the Keychain) |
 | `APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE` | No | — | Keychain item service/server name |
 | `APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT` | No | = user | Keychain item account |
+| `APPLE_MAIL_MCP_IMAP_ACCOUNTS` | No | — | JSON array of **additional** IMAP accounts for multi-account setups (see below) |
+| `APPLE_MAIL_MCP_IMAP_IDLE` | No | `0` | Set `1` to enable IMAP IDLE push notifications (new-mail alerts) for every configured account |
+| `APPLE_MAIL_MCP_IMAP_IDLE_MS` | No | `60000` | Idle timeout (ms) before a pooled IMAP connection is closed |
+
+**Multiple IMAP accounts (C2):** set `APPLE_MAIL_MCP_IMAP_ACCOUNTS` to a JSON array, e.g.
+`[{"account":"Work","user":"me@co.com","host":"imap.co.com","keychainService":"imap.co.com"}]`.
+Each entry accepts `account`, `user`, `host`, `port`, `password`, `keychainService`,
+`keychainAccount`. Calls route to the account matching their `account` argument (or the
+decoded `imap:` id), and each account keeps its own pooled connection.
+
+**Push notifications (B5):** with `APPLE_MAIL_MCP_IMAP_IDLE=1`, the server watches each
+account's INBOX and emits an MCP logging message + `notifications/resources/updated` for
+`mail://mailboxes/{account}` when new mail arrives (real-time IDLE where the server
+supports it, polling fallback otherwise).
 
 As with SMTP, the password is read from the macOS **Keychain** by default (use
 an app-specific password for Gmail/Workspace/iCloud), so no secret goes in
@@ -309,10 +342,8 @@ config. Gmail label semantics: common names (`All Mail`, `Sent`, `Trash`,
 `Spam`, `Important`, …) map to their `[Gmail]/…` IMAP paths automatically.
 
 > Note: each call currently opens its own IMAP connection (no pooling yet), so
-> expect a few seconds of connection overhead per call. Phase 2 added the folder
-> ops (create/rename/delete-mailbox) — resolving the IMAP slice of
-> [#42](https://github.com/sweetrb/apple-mail-mcp/issues/42). IMAP-backed
-> message-level mutations are still future work (see #43).
+> expect a few seconds of connection overhead per call — the one remaining
+> follow-up on [#43](https://github.com/sweetrb/apple-mail-mcp/issues/43).
 >
 > **iCloud:** set `APPLE_MAIL_MCP_IMAP_HOST=imap.mail.me.com`, `APPLE_MAIL_MCP_IMAP_USER`
 > to your iCloud address, `APPLE_MAIL_MCP_IMAP_ACCOUNT` to the Mail account name
@@ -368,10 +399,44 @@ Save an email to Drafts without sending.
 | `cc` | string[] | No | CC recipients |
 | `bcc` | string[] | No | BCC recipients |
 | `account` | string | No | Account for draft |
-| `attachments` | string[] | No | Absolute file paths to attach, max 20 files |
+| `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments: absolute file paths and/or inline `{filename, contentBase64}` objects |
 
 **Returns:** Confirmation that draft was created.
 
+#### `get-thread`
+
+Group a conversation by normalized subject (across the AppleScript or IMAP backend).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | A message ID in the conversation (numeric or `imap:…`) |
+| `account` | string | No | Account to search (omit to search all) |
+| `mailbox` | string | No | Mailbox to search (omit to search all) |
+| `limit` | number | No | Max messages in the thread (default 50) |
+
+**Returns:** The conversation's messages, oldest-first.
+
+#### `fetch-attachment`
+
+Return an attachment's bytes as base64 (the read counterpart to inline-base64 send).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Numeric message ID |
+| `attachmentName` | string | Yes | Attachment filename (from `list-attachments`) |
+
+**Returns:** The attachment bytes, base64-encoded (also in `structuredContent.contentBase64`).
+
+#### `create-rule` / `delete-rule`
+
+Create a Mail rule with conditions and actions, or delete a rule by name.
+
+`create-rule` parameters: `name` (string), `conditions` (array of `{field: from|to|cc|subject|content, operator: contains|notContains|equals|beginsWith|endsWith, value}`), `actions` (`{markRead?, markFlagged?, delete?, moveTo?, moveToAccount?}`), `matchAll` (default true), `enabled` (default true). `delete-rule` parameters: `name`.
+
+#### `doctor`
+
+Run a full setup diagnostic: Mail.app automation permission, account state (flags disabled accounts), and each configured IMAP/SMTP backend, each reported as ok / warn / fail with an actionable message. No parameters.
+
 ---
 
 #### `reply-to-message`
@@ -848,8 +913,8 @@ The entrypoint is written as:
 | No sending HTML email | Emails are sent as plain text; reading HTML content is supported |
 | 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 | 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 to search inside one. ([#24](https://github.com/sweetrb/apple-mail-mcp/issues/24)) |
-| Can't delete/rename server-side mailboxes or mutate drafts | 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 and drafts (the GUI can do it). `delete-mailbox`/`rename-mailbox`/`delete-message`/`move-message` now return a clear "do it in Mail.app directly" error in that case instead of a generic failure. ([#42](https://github.com/sweetrb/apple-mail-mcp/issues/42)) |
+| 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) |
 | Batch size cap | Batch operations are limited to 100 messages per request |