apple-mail-mcp 1.9.0 → 2.1.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:**
@@ -287,14 +299,17 @@ 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`.
+- **Batch mutations (2.1):** `batch-mark-as-read`/`unread`, `batch-flag`/`unflag-messages`, `batch-move-messages`, `batch-delete-messages` — `imap:` ids are grouped by mailbox and applied as a single `UID STORE`/`UID MOVE`; numeric ids in the same batch still use AppleScript.
+- **Counts & stats (2.1):** `get-unread-count` and `list-mailboxes` use `STATUS`; `get-mail-stats` (with an `account`) uses `STATUS` + `SEARCH SINCE` — authoritative and fast even on huge mailboxes.
+- **Attachments (2.1):** `list-attachments`, `save-attachment`, `fetch-attachment` use `BODYSTRUCTURE` + `FETCH BODY[part]` for `imap:` ids — faster and able to see MIME-embedded attachments AppleScript misses.
+- **Threading (2.1):** `get-thread` links a conversation via `References`/`Message-ID` (`HEADER SEARCH`) for an `imap:` seed, falling back to subject grouping otherwise.
 
 **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.)
+UID). Pass that id back to `get-message`, a message mutation, a batch op, or the
+attachment/thread tools 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.
 
 Routing is conservative: only a call whose explicit `account` matches the
 configured IMAP account goes to IMAP; everything else falls through to
@@ -309,21 +324,72 @@ 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.
 
 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
 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 — the one remaining
-> follow-up on [#43](https://github.com/sweetrb/apple-mail-mcp/issues/43).
+> Note: IMAP connections are pooled — one kept-alive connection per account is
+> reused across calls (verified with a NOOP, closed after `APPLE_MAIL_MCP_IMAP_IDLE_MS`
+> of inactivity), so there's no per-call connection overhead ([#50](https://github.com/sweetrb/apple-mail-mcp/issues/50)).
 >
 > **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
 > (e.g. `iCloud`), and use an **app-specific password** (from appleid.apple.com)
 > stored in the Keychain.
 
+##### Push notifications (IMAP IDLE) — opt-in
+
+When `APPLE_MAIL_MCP_IMAP_IDLE=1`, the server opens a dedicated, long-lived
+connection to **each configured IMAP account** and watches its INBOX for new
+mail. On arrival it pushes two MCP notifications to the client (no polling by the
+client required):
+
+1. **`notifications/message`** (logging) — a human-readable line, e.g.
+   `New mail in "Work": 2 new message(s) (INBOX now 1843).`
+2. **`notifications/resources/updated`** — for the affected account's resource
+   `mail://mailboxes/{account}`, so a client subscribed to that resource knows to
+   re-read it.
+
+This requires an IMAP account to be configured (single-account env or
+`APPLE_MAIL_MCP_IMAP_ACCOUNTS`); accounts that only use AppleScript aren't
+watched. Detection is **real-time** via the IMAP IDLE `EXISTS` event where the
+server pushes it, with an automatic **polling fallback** for servers that don't.
+Dropped connections reconnect with backoff, and the watchers shut down cleanly on
+`SIGINT`/`SIGTERM`.
+
+Enable it in your MCP client config alongside the IMAP settings:
+
+```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_KEYCHAIN_SERVICE": "imap.gmail.com",
+        "APPLE_MAIL_MCP_IMAP_IDLE": "1"
+      }
+    }
+  }
+}
+```
+
+> Note: this is most useful with clients that surface MCP logging messages or
+> subscribe to resource-update notifications. Clients that ignore notifications
+> are unaffected — the feature is opt-in and adds no behavior unless enabled.
+
 ---
 
 #### `send-serial-email`
@@ -373,10 +439,34 @@ 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`).
+
 ---
 
 #### `reply-to-message`
@@ -614,6 +704,41 @@ Enable or disable a mail rule.
 
 ---
 
+#### `create-rule`
+
+Create a Mail rule with one or more conditions and actions.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Rule name (must be unique) |
+| `conditions` | object[] | Yes | One or more `{field, operator, value}` (see below) |
+| `actions` | object | Yes | At least one of `markRead`, `markFlagged`, `delete`, `moveTo` |
+| `matchAll` | boolean | No | `true` (default) = all conditions must match; `false` = any |
+| `enabled` | boolean | No | Whether the rule is enabled on creation (default `true`) |
+
+Each condition is `{ field, operator, value }` where `field` is one of `from`, `to`, `cc`, `subject`, `content` and `operator` is one of `contains`, `notContains`, `equals`, `beginsWith`, `endsWith`. Actions: `markRead` / `markFlagged` / `delete` (booleans), `moveTo` (mailbox name) with optional `moveToAccount`.
+
+**Example:**
+```json
+{
+  "name": "Newsletters",
+  "conditions": [{ "field": "from", "operator": "contains", "value": "newsletter" }],
+  "actions": { "markRead": true, "moveTo": "Reading" }
+}
+```
+
+---
+
+#### `delete-rule`
+
+Delete a mail rule by name.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Rule name |
+
+---
+
 ### Contacts
 
 #### `search-contacts`
@@ -631,7 +756,7 @@ Search contacts in Contacts.app.
 
 ### Templates
 
-Email templates are stored in memory for the duration of the server session.
+Email templates are **persisted to disk** so they survive server restarts, stored as JSON at `APPLE_MAIL_MCP_TEMPLATES_FILE` (default `~/Library/Application Support/apple-mail-mcp/templates.json`).
 
 #### `save-template`
 
@@ -702,6 +827,16 @@ Verify Mail.app connectivity and permissions.
 
 ---
 
+#### `doctor`
+
+Run a full setup diagnostic: Mail.app automation permission, account state (flagging disabled accounts), and each configured IMAP/SMTP backend — each reported as ok / warn / fail with an actionable message.
+
+**Parameters:** None
+
+**Returns:** A per-check report (`structuredContent` carries the raw `{healthy, checks[]}`).
+
+---
+
 #### `get-mail-stats`
 
 Get mail statistics.