apple-mail-mcp 2.0.0 → 2.1.1

package/README.md

@@ -299,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
@@ -331,25 +334,85 @@ Each entry accepts `account`, `user`, `host`, `port`, `password`, `keychainServi
 `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
 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.
 
+##### Configuration file (when the host strips `env`)
+
+Some host apps (e.g. Claude Desktop) launch the MCP server with a scrubbed
+environment and ignore the `env` block in their server config, so there's no way
+to pass `APPLE_MAIL_MCP_*` settings through it. In that case, put them in a JSON
+file the host doesn't manage — `APPLE_MAIL_MCP_CONFIG_FILE`, or by default
+`~/Library/Application Support/apple-mail-mcp/config.json`:
+
+```json
+{
+  "APPLE_MAIL_MCP_IMAP_USER": "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_IDLE": "1"
+}
+```
+
+The server reads it at startup and merges values into the environment **without
+overriding** anything already set there (so an explicit `env` still wins). Store
+only non-secret config here — **passwords belong in the Keychain**, never in this
+file.
+
+##### 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`
@@ -427,16 +490,6 @@ Return an attachment's bytes as base64 (the read counterpart to inline-base64 se
 
 **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`
@@ -674,6 +727,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`
@@ -691,7 +779,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`
 
@@ -762,6 +850,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.

package/build/index.js

@@ -23,21 +23,24 @@ import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { AppleMailManager } from "./services/appleMailManager.js";
+import { AppleMailManager, isPathWithinAllowedRoots } from "./services/appleMailManager.js";
+import { writeFileSync } from "fs";
+import { resolve as resolvePath, join as joinPath } from "path";
 import { sendViaSmtp } from "./services/smtpMailer.js";
-import { isImapAccount, resolveImapConfigs, imapSearchMessages, imapListMessages, imapCreateMailbox, imapDeleteMailbox, imapRenameMailbox, imapGetMessage, imapMarkRead, imapMarkUnread, imapFlagMessage, imapUnflagMessage, imapMoveMessageById, imapDeleteMessageById, } from "./services/imapClient.js";
+import { isImapAccount, resolveImapConfigs, imapSearchMessages, imapListMessages, imapUnreadCount, imapListMailboxes, imapMailStats, imapListAttachments, imapFetchAttachment, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete, imapBatchMove, imapThread, imapCreateMailbox, imapDeleteMailbox, imapRenameMailbox, imapGetMessage, imapMarkRead, imapMarkUnread, imapFlagMessage, imapUnflagMessage, imapMoveMessageById, imapDeleteMessageById, } from "./services/imapClient.js";
 import { successResponse, errorResponse, partialCoverageBlock, withErrorHandling, messageSummary, } from "./tools/respond.js";
 import { routeMessage } from "./services/messageRouter.js";
 import { runDoctor, formatDoctorReport } from "./tools/doctor.js";
 import { registerResourcesAndPrompts } from "./tools/resourcesAndPrompts.js";
 import { normalizeSubject, subjectFromGetMessage } from "./tools/thread.js";
 import { ImapIdleWatcher } from "./services/imapIdle.js";
+import { loadFileConfig } from "./services/fileConfig.js";
+// Load file-based config FIRST (2.1.1) — before anything reads APPLE_MAIL_MCP_*.
+// Lets users configure the server when the host app strips the MCP env block.
+loadFileConfig();
 // =============================================================================
 // Shared Validation Schemas
 // =============================================================================
-/** AppleScript message IDs are always numeric. Enforced to prevent AppleScript
- *  injection via the `whose id is ${id}` interpolation. */
-const NUMERIC_MESSAGE_ID_SCHEMA = z.string().regex(/^\d+$/, "Message ID must be numeric");
 /** A single-message id is EITHER an AppleScript numeric id OR an IMAP composite
  *  token (`imap:<base64url>`, emitted by the IMAP read path). The IMAP form is
  *  base64url so it stays injection-safe; it never reaches AppleScript (it's
@@ -45,10 +48,11 @@ const NUMERIC_MESSAGE_ID_SCHEMA = z.string().regex(/^\d+$/, "Message ID must be
 const MESSAGE_ID_SCHEMA = z
     .string()
     .regex(/^(\d+|imap:[A-Za-z0-9_-]+)$/, "Message ID must be numeric or an IMAP id (imap:…)");
-/** Batch operations are AppleScript-only and capped to prevent unbounded loops /
- *  DoS. IMAP ids are rejected here — use the single-message tools for those. */
+/** Batch operations accept numeric (AppleScript) and/or imap: ids (I2) and are
+ *  capped to prevent unbounded loops / DoS. Numeric ids run via AppleScript;
+ *  imap: ids are grouped by mailbox and applied in a single UID command. */
 const BATCH_IDS_SCHEMA = z
-    .array(NUMERIC_MESSAGE_ID_SCHEMA)
+    .array(MESSAGE_ID_SCHEMA)
     .min(1, "At least one message ID is required")
     .max(100, "Cannot process more than 100 messages in a single batch");
 /** Date filter strings must look like natural-language dates (e.g. "March 1, 2026").
@@ -99,6 +103,31 @@ const mailManager = new AppleMailManager();
 registerResourcesAndPrompts(server, mailManager);
 // Response helpers, the AppleScript serial gate, withErrorHandling, and the
 // message backend router now live in @/tools/respond and @/services/messageRouter.
+/**
+ * Split a batch of ids into numeric (AppleScript) and imap: (IMAP) groups, run
+ * each path, and merge into success/fail counts (I2). imap: ids apply in a
+ * single UID command per mailbox; numeric ids use the existing AppleScript batch.
+ */
+async function hybridBatchCounts(ids, appleFn, imapFn) {
+    const imapIds = ids.filter((i) => i.startsWith("imap:"));
+    const numericIds = ids.filter((i) => !i.startsWith("imap:"));
+    let success = 0;
+    let fail = 0;
+    const errors = [];
+    if (numericIds.length > 0) {
+        const res = appleFn(numericIds);
+        const s = res.filter((r) => r.success).length;
+        success += s;
+        fail += res.length - s;
+    }
+    if (imapIds.length > 0) {
+        const r = await imapFn(imapIds);
+        success += r.success;
+        fail += r.failed;
+        errors.push(...r.errors);
+    }
+    return { success, fail, errors };
+}
 // =============================================================================
 // Message Tools
 // =============================================================================
@@ -192,6 +221,14 @@ server.tool("get-thread", {
     mailbox: z.string().optional().describe("Mailbox to search (omit to search all)"),
     limit: z.number().optional().describe("Max messages in the thread (default 50)"),
 }, withErrorHandling(async ({ id, account, mailbox, limit = 50 }) => {
+    // True threading via References/Message-ID when we have an imap: id (I5);
+    // falls through to subject grouping if the server lacks HEADER search or
+    // nothing References-linked is found.
+    if (id.startsWith("imap:")) {
+        const t = await imapThread(id, { account }, limit);
+        if (t && t.count > 1)
+            return successResponse(t.text, { ...t.structured });
+    }
     // Resolve the seed message's subject, then gather the conversation by
     // normalized subject (B1). Works across the AppleScript and IMAP backends.
     let seedSubject = null;
@@ -467,10 +504,8 @@ server.tool("move-message", {
 // --- batch-delete-messages ---
 server.tool("batch-delete-messages", {
     ids: BATCH_IDS_SCHEMA,
-}, withErrorHandling(({ ids }) => {
-    const results = mailManager.batchDeleteMessages(ids);
-    const successCount = results.filter((r) => r.success).length;
-    const failCount = results.length - successCount;
+}, withErrorHandling(async ({ ids }) => {
+    const { success: successCount, fail: failCount } = await hybridBatchCounts(ids, (n) => mailManager.batchDeleteMessages(n), (im) => imapBatchDelete(im));
     if (failCount === 0) {
         return successResponse(`Successfully deleted ${successCount} message(s)`);
     }
@@ -486,10 +521,8 @@ server.tool("batch-move-messages", {
     ids: BATCH_IDS_SCHEMA,
     mailbox: z.string().min(1, "Destination mailbox is required"),
     account: z.string().optional().describe("Account containing the destination mailbox"),
-}, withErrorHandling(({ ids, mailbox, account }) => {
-    const results = mailManager.batchMoveMessages(ids, mailbox, account);
-    const successCount = results.filter((r) => r.success).length;
-    const failCount = results.length - successCount;
+}, withErrorHandling(async ({ ids, mailbox, account }) => {
+    const { success: successCount, fail: failCount } = await hybridBatchCounts(ids, (n) => mailManager.batchMoveMessages(n, mailbox, account), (im) => imapBatchMove(im, mailbox, { account }));
     if (failCount === 0) {
         return successResponse(`Successfully moved ${successCount} message(s) to "${mailbox}"`);
     }
@@ -503,10 +536,8 @@ server.tool("batch-move-messages", {
 // --- batch-mark-as-read ---
 server.tool("batch-mark-as-read", {
     ids: BATCH_IDS_SCHEMA,
-}, withErrorHandling(({ ids }) => {
-    const results = mailManager.batchMarkAsRead(ids);
-    const successCount = results.filter((r) => r.success).length;
-    const failCount = results.length - successCount;
+}, withErrorHandling(async ({ ids }) => {
+    const { success: successCount, fail: failCount } = await hybridBatchCounts(ids, (n) => mailManager.batchMarkAsRead(n), (im) => imapBatchMarkRead(im));
     if (failCount === 0) {
         return successResponse(`Successfully marked ${successCount} message(s) as read`);
     }
@@ -520,10 +551,8 @@ server.tool("batch-mark-as-read", {
 // --- batch-mark-as-unread ---
 server.tool("batch-mark-as-unread", {
     ids: BATCH_IDS_SCHEMA,
-}, withErrorHandling(({ ids }) => {
-    const results = mailManager.batchMarkAsUnread(ids);
-    const successCount = results.filter((r) => r.success).length;
-    const failCount = results.length - successCount;
+}, withErrorHandling(async ({ ids }) => {
+    const { success: successCount, fail: failCount } = await hybridBatchCounts(ids, (n) => mailManager.batchMarkAsUnread(n), (im) => imapBatchMarkUnread(im));
     if (failCount === 0) {
         return successResponse(`Successfully marked ${successCount} message(s) as unread`);
     }
@@ -537,10 +566,8 @@ server.tool("batch-mark-as-unread", {
 // --- batch-flag-messages ---
 server.tool("batch-flag-messages", {
     ids: BATCH_IDS_SCHEMA,
-}, withErrorHandling(({ ids }) => {
-    const results = mailManager.batchFlagMessages(ids);
-    const successCount = results.filter((r) => r.success).length;
-    const failCount = results.length - successCount;
+}, withErrorHandling(async ({ ids }) => {
+    const { success: successCount, fail: failCount } = await hybridBatchCounts(ids, (n) => mailManager.batchFlagMessages(n), (im) => imapBatchFlag(im));
     if (failCount === 0) {
         return successResponse(`Successfully flagged ${successCount} message(s)`);
     }
@@ -554,10 +581,8 @@ server.tool("batch-flag-messages", {
 // --- batch-unflag-messages ---
 server.tool("batch-unflag-messages", {
     ids: BATCH_IDS_SCHEMA,
-}, withErrorHandling(({ ids }) => {
-    const results = mailManager.batchUnflagMessages(ids);
-    const successCount = results.filter((r) => r.success).length;
-    const failCount = results.length - successCount;
+}, withErrorHandling(async ({ ids }) => {
+    const { success: successCount, fail: failCount } = await hybridBatchCounts(ids, (n) => mailManager.batchUnflagMessages(n), (im) => imapBatchUnflag(im));
     if (failCount === 0) {
         return successResponse(`Successfully unflagged ${successCount} message(s)`);
     }
@@ -571,8 +596,17 @@ server.tool("batch-unflag-messages", {
 // --- list-attachments ---
 server.tool("list-attachments", {
     id: MESSAGE_ID_SCHEMA,
-}, withErrorHandling(({ id }) => {
-    const attachments = mailManager.listAttachments(id);
+}, withErrorHandling(async ({ id }) => {
+    // IMAP (I1): BODYSTRUCTURE enumerates parts (incl. MIME attachments
+    // AppleScript can't see) without downloading the message.
+    const attachments = id.startsWith("imap:")
+        ? await (async () => {
+            const r = await imapListAttachments(id);
+            if (!r.success)
+                throw new Error(r.error || "Failed to list attachments via IMAP");
+            return r.attachments ?? [];
+        })()
+        : mailManager.listAttachments(id);
     const structured = { attachments, count: attachments.length };
     if (attachments.length === 0) {
         return successResponse("No attachments found", structured);
@@ -590,7 +624,25 @@ server.tool("save-attachment", {
     id: MESSAGE_ID_SCHEMA,
     attachmentName: z.string().min(1, "Attachment name is required"),
     savePath: z.string().min(1, "Save directory path is required"),
-}, withErrorHandling(({ id, attachmentName, savePath }) => {
+}, withErrorHandling(async ({ id, attachmentName, savePath }) => {
+    // IMAP (I1): fetch the part's bytes via IMAP, then write into savePath (a
+    // directory) as savePath/attachmentName — mirroring the AppleScript path,
+    // with the same name + allowed-roots validation.
+    if (id.startsWith("imap:")) {
+        if (/[/\\\0]/.test(attachmentName) || attachmentName.includes("..")) {
+            return errorResponse(`Invalid attachment name: "${attachmentName}"`);
+        }
+        const resolvedDir = resolvePath(savePath);
+        if (!isPathWithinAllowedRoots(resolvedDir)) {
+            return errorResponse(`Save path "${savePath}" is outside allowed directories`);
+        }
+        const r = await imapFetchAttachment(id, attachmentName);
+        if (!r.success || !r.base64) {
+            return errorResponse(r.error || `Failed to fetch attachment "${attachmentName}"`);
+        }
+        writeFileSync(joinPath(resolvedDir, attachmentName), Buffer.from(r.base64, "base64"));
+        return successResponse(`Attachment "${attachmentName}" saved to ${savePath}`);
+    }
     const success = mailManager.saveAttachment(id, attachmentName, savePath);
     if (!success) {
         return errorResponse(`Failed to save attachment "${attachmentName}"`);
@@ -599,12 +651,19 @@ server.tool("save-attachment", {
 }, "Error saving attachment"));
 // --- fetch-attachment ---
 server.tool("fetch-attachment", {
-    id: NUMERIC_MESSAGE_ID_SCHEMA,
+    id: MESSAGE_ID_SCHEMA,
     attachmentName: z.string().min(1, "Attachment name is required"),
-}, withErrorHandling(({ id, attachmentName }) => {
+}, withErrorHandling(async ({ id, attachmentName }) => {
     // Returns the attachment bytes as base64 (B4) — the read counterpart to
-    // sending inline base64 content, for clients that want the bytes directly
-    // rather than writing to disk via save-attachment.
+    // sending inline base64 content. IMAP (I1) fetches the part directly; numeric
+    // ids fall back to the AppleScript/MIME path.
+    if (id.startsWith("imap:")) {
+        const r = await imapFetchAttachment(id, attachmentName);
+        if (!r.success || !r.base64) {
+            return errorResponse(r.error || `Failed to fetch attachment "${attachmentName}"`);
+        }
+        return successResponse(`Fetched "${attachmentName}" (${r.bytes} bytes, base64-encoded below).\n\n${r.base64}`, { attachmentName, bytes: r.bytes, mimeType: r.mimeType, contentBase64: r.base64 });
+    }
     const r = mailManager.getAttachmentBase64(id, attachmentName);
     if (!r.success) {
         return errorResponse(r.error || `Failed to fetch attachment "${attachmentName}"`);
@@ -617,7 +676,24 @@ server.tool("fetch-attachment", {
 // --- list-mailboxes ---
 server.tool("list-mailboxes", {
     account: z.string().optional().describe("Account to list mailboxes from"),
-}, withErrorHandling(({ account }) => {
+}, withErrorHandling(async ({ account }) => {
+    // IMAP (I6): LIST + per-mailbox STATUS — sees the true server hierarchy and
+    // authoritative counts; falls back to AppleScript for non-IMAP accounts.
+    if (isImapAccount(account)) {
+        const boxes = await imapListMailboxes({ account });
+        const structured = {
+            mailboxes: boxes.map((b) => ({
+                name: b.path,
+                unreadCount: b.unseen,
+                messageCount: b.messages,
+            })),
+            count: boxes.length,
+        };
+        if (boxes.length === 0)
+            return successResponse("No mailboxes found", structured);
+        const list = boxes.map((b) => `  - ${b.path} (${b.unseen} unread)`).join("\n");
+        return successResponse(`Found ${boxes.length} mailbox(es):\n${list}`, structured);
+    }
     const mailboxes = mailManager.listMailboxes(account);
     const structured = { mailboxes, count: mailboxes.length };
     if (mailboxes.length === 0) {
@@ -630,8 +706,12 @@ server.tool("list-mailboxes", {
 server.tool("get-unread-count", {
     mailbox: z.string().optional().describe("Mailbox to check (default: all)"),
     account: z.string().optional().describe("Account to check"),
-}, withErrorHandling(({ mailbox, account }) => {
-    const count = mailManager.getUnreadCount(mailbox, account);
+}, withErrorHandling(async ({ mailbox, account }) => {
+    // IMAP (I4): STATUS (UNSEEN) is authoritative and fast even on huge
+    // mailboxes; falls back to AppleScript for non-IMAP accounts.
+    const count = isImapAccount(account)
+        ? await imapUnreadCount(mailbox, { account })
+        : mailManager.getUnreadCount(mailbox, account);
     const location = mailbox ? ` in "${mailbox}"` : "";
     return successResponse(`${count} unread message(s)${location}`, {
         unread: count,
@@ -893,7 +973,29 @@ server.tool("doctor", {}, withErrorHandling(async () => {
     return successResponse(formatDoctorReport(report), { ...report });
 }, "Error running doctor"));
 // --- get-mail-stats ---
-server.tool("get-mail-stats", {}, withErrorHandling(() => {
+server.tool("get-mail-stats", {
+    account: z
+        .string()
+        .optional()
+        .describe("Limit to one account; uses fast IMAP STATUS if that account is IMAP-configured"),
+}, withErrorHandling(async ({ account }) => {
+    // IMAP (I3): for a named IMAP account, STATUS gives authoritative counts and
+    // SEARCH SINCE gives recent activity — fast even on huge mailboxes.
+    if (account && isImapAccount(account)) {
+        const s = await imapMailStats({ account });
+        const lines = [
+            `📊 Mail Statistics — ${account} (IMAP)`,
+            `══════════════════`,
+            `Total messages: ${s.totalMessages}`,
+            `Unread messages: ${s.totalUnread}`,
+            ``,
+            `📥 Recently Received (INBOX):`,
+            `  Last 24 hours: ${s.recent.last24h}`,
+            `  Last 7 days: ${s.recent.last7d}`,
+            `  Last 30 days: ${s.recent.last30d}`,
+        ];
+        return successResponse(lines.join("\n"), { account, ...s });
+    }
     const stats = mailManager.getMailStats();
     const lines = [];
     lines.push(`📊 Mail Statistics`);

package/build/services/fileConfig.d.ts

@@ -0,0 +1,7 @@
+export declare function fileConfigPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Merge a JSON config file's string values into `env` for keys not already set.
+ * Returns the list of keys actually applied. Tolerates a missing/corrupt file.
+ */
+export declare function loadFileConfig(env?: NodeJS.ProcessEnv, path?: string): string[];
+//# sourceMappingURL=fileConfig.d.ts.map

package/build/services/fileConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileConfig.d.ts","sourceRoot":"","sources":["../../src/services/fileConfig.ts"],"names":[],"mappings":"AAqBA,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAI3E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,GAAE,MAA4B,GACjC,MAAM,EAAE,CAiBV"}

package/build/services/fileConfig.js

@@ -0,0 +1,52 @@
+/**
+ * File-based configuration loader (2.1.1).
+ *
+ * Some host apps (e.g. Claude Desktop) spawn the MCP server with a scrubbed
+ * environment and ignore/strip the `env` block in their server config, so
+ * there's no way to pass `APPLE_MAIL_MCP_*` settings in. This loads them from a
+ * JSON file the host doesn't manage, merging into `process.env` WITHOUT
+ * overriding anything already set (so an explicit env still wins).
+ *
+ * The file holds only non-secret config — account/host/Keychain-service names
+ * and flags. Passwords are NEVER stored here; they stay in the macOS Keychain.
+ *
+ * Path: `APPLE_MAIL_MCP_CONFIG_FILE`, else
+ * `~/Library/Application Support/apple-mail-mcp/config.json`.
+ *
+ * @module services/fileConfig
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+export function fileConfigPath(env = process.env) {
+    const override = env.APPLE_MAIL_MCP_CONFIG_FILE;
+    if (override && override.trim())
+        return override.trim();
+    return join(homedir(), "Library", "Application Support", "apple-mail-mcp", "config.json");
+}
+/**
+ * Merge a JSON config file's string values into `env` for keys not already set.
+ * Returns the list of keys actually applied. Tolerates a missing/corrupt file.
+ */
+export function loadFileConfig(env = process.env, path = fileConfigPath(env)) {
+    const applied = [];
+    try {
+        if (!existsSync(path))
+            return applied;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return applied;
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v !== "string")
+                continue;
+            if (env[k] === undefined || env[k] === "") {
+                env[k] = v;
+                applied.push(k);
+            }
+        }
+    }
+    catch (e) {
+        console.error(`Failed to load apple-mail-mcp config file ${path}: ${String(e)}`);
+    }
+    return applied;
+}

package/build/services/imapClient.d.ts

@@ -38,12 +38,33 @@ interface ImapEnvelope {
     subject?: string;
     date?: Date | string;
     from?: ImapAddress[];
+    messageId?: string;
+    inReplyTo?: string;
+}
+export interface ImapBodyStructure {
+    part?: string;
+    type?: string;
+    disposition?: string;
+    dispositionParameters?: Record<string, string>;
+    parameters?: Record<string, string>;
+    size?: number;
+    encoding?: string;
+    childNodes?: ImapBodyStructure[];
 }
 interface ImapMessage {
     uid: number;
     envelope?: ImapEnvelope;
     flags?: Set<string>;
     source?: Buffer | string;
+    bodyStructure?: ImapBodyStructure;
+    headers?: Buffer | string;
+}
+interface ImapDownload {
+    meta?: {
+        filename?: string;
+        contentType?: string;
+    };
+    content: AsyncIterable<Uint8Array>;
 }
 interface MailboxLock {
     release: () => void;
@@ -68,6 +89,19 @@ export interface ImapClientLike {
         uid: true;
     }): Promise<ImapMessage | false>;
     list(): Promise<ImapMailboxListing[]>;
+    status(path: string, query: {
+        messages?: boolean;
+        unseen?: boolean;
+        recent?: boolean;
+    }): Promise<{
+        path: string;
+        messages?: number;
+        unseen?: number;
+        recent?: number;
+    }>;
+    download(range: string, part: string, opts: {
+        uid: true;
+    }): Promise<ImapDownload>;
     mailboxCreate(path: string): Promise<{
         path: string;
         created: boolean;
@@ -123,6 +157,32 @@ export declare function resolveImapConfig(env?: NodeJS.ProcessEnv, account?: str
 export declare function resolveMailboxPath(mailbox: string | undefined, mode: "search" | "list"): string;
 export declare function imapSearchMessages(args: ImapSearchArgs, deps?: ImapDeps): Promise<string>;
 export declare function imapListMessages(args: ImapSearchArgs, deps?: ImapDeps): Promise<string>;
+/** Unread count via IMAP STATUS (UNSEEN). No mailbox → sum across all mailboxes. */
+export declare function imapUnreadCount(mailbox: string | undefined, deps?: ImapDeps): Promise<number>;
+export interface ImapMailboxInfo {
+    path: string;
+    name: string;
+    messages: number;
+    unseen: number;
+}
+/** List mailboxes with per-mailbox message/unseen counts via LIST + STATUS (I6). */
+export declare function imapListMailboxes(deps?: ImapDeps): Promise<ImapMailboxInfo[]>;
+export interface ImapStats {
+    totalMessages: number;
+    totalUnread: number;
+    perMailbox: {
+        mailbox: string;
+        messages: number;
+        unseen: number;
+    }[];
+    recent: {
+        last24h: number;
+        last7d: number;
+        last30d: number;
+    };
+}
+/** Aggregate stats via STATUS (counts) + INBOX SEARCH SINCE (recent) (I3). */
+export declare function imapMailStats(deps?: ImapDeps): Promise<ImapStats>;
 export interface ImapOpResult {
     success: boolean;
     error?: string;
@@ -154,5 +214,53 @@ export declare const imapFlagMessage: (id: string, deps?: {}) => Promise<ImapOpR
 export declare const imapUnflagMessage: (id: string, deps?: {}) => Promise<ImapOpResult>;
 export declare function imapMoveMessageById(id: string, destMailbox: string, deps?: ImapDeps): Promise<ImapOpResult>;
 export declare function imapDeleteMessageById(id: string, deps?: ImapDeps): Promise<ImapOpResult>;
+export interface ImapAttachmentInfo {
+    id: string;
+    name: string;
+    mimeType: string;
+    size: number;
+}
+/** List a message's attachments via IMAP BODYSTRUCTURE (no full download). */
+export declare function imapListAttachments(id: string, deps?: ImapDeps): Promise<{
+    success: boolean;
+    attachments?: ImapAttachmentInfo[];
+    error?: string;
+}>;
+/** Fetch one attachment's bytes (base64) via IMAP, matched by filename. */
+export declare function imapFetchAttachment(id: string, attachmentName: string, deps?: ImapDeps): Promise<{
+    success: boolean;
+    base64?: string;
+    bytes?: number;
+    mimeType?: string;
+    error?: string;
+}>;
+export interface ImapBatchResult {
+    success: number;
+    failed: number;
+    errors: string[];
+}
+export declare const imapBatchMarkRead: (ids: string[], deps?: ImapDeps) => Promise<ImapBatchResult>;
+export declare const imapBatchMarkUnread: (ids: string[], deps?: ImapDeps) => Promise<ImapBatchResult>;
+export declare const imapBatchFlag: (ids: string[], deps?: ImapDeps) => Promise<ImapBatchResult>;
+export declare const imapBatchUnflag: (ids: string[], deps?: ImapDeps) => Promise<ImapBatchResult>;
+export declare const imapBatchDelete: (ids: string[], deps?: ImapDeps) => Promise<ImapBatchResult>;
+export declare function imapBatchMove(ids: string[], destMailbox: string, deps?: ImapDeps): Promise<ImapBatchResult>;
+export interface ImapThreadMessage {
+    id: string;
+    subject: string;
+    sender: string;
+    date: string;
+    isRead: boolean;
+}
+export interface ImapThreadResult {
+    count: number;
+    text: string;
+    structured: {
+        subject: string;
+        messages: ImapThreadMessage[];
+        count: number;
+    };
+}
+export declare function imapThread(id: string, deps?: ImapDeps, limit?: number): Promise<ImapThreadResult | null>;
 export {};
 //# sourceMappingURL=imapClient.d.ts.map

package/build/services/imapClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"imapClient.d.ts","sourceRoot":"","sources":["../../src/services/imapClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"imapClient.d.ts","sourceRoot":"","sources":["../../src/services/imapClient.ts"],"names":[],"mappings":"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"}

package/build/services/imapClient.js

@@ -294,6 +294,97 @@ export function imapSearchMessages(args, deps = {}) {
 export function imapListMessages(args, deps = {}) {
     return run(args, true, deps);
 }
+// ===========================================================================
+// Counts & stats via IMAP STATUS (2.1 optimizations I3/I4/I6)
+//
+// STATUS is a single server round-trip that returns authoritative message/unseen
+// counts without enumerating messages — far faster and more reliable than
+// AppleScript on large mailboxes (where the per-message walk times out, #8/#24).
+// ===========================================================================
+/** Unread count via IMAP STATUS (UNSEEN). No mailbox → sum across all mailboxes. */
+export function imapUnreadCount(mailbox, deps = {}) {
+    return useClient(deps, async (client) => {
+        if (mailbox) {
+            const s = await client.status(resolveMailboxPath(mailbox, "list"), { unseen: true });
+            return s.unseen ?? 0;
+        }
+        let total = 0;
+        for (const b of await client.list()) {
+            try {
+                const s = await client.status(b.path, { unseen: true });
+                total += s.unseen ?? 0;
+            }
+            catch {
+                // skip mailboxes that can't be STATUS'd (e.g. \Noselect parents)
+            }
+        }
+        return total;
+    }, true);
+}
+/** List mailboxes with per-mailbox message/unseen counts via LIST + STATUS (I6). */
+export function imapListMailboxes(deps = {}) {
+    return useClient(deps, async (client) => {
+        const out = [];
+        for (const b of await client.list()) {
+            let messages = 0;
+            let unseen = 0;
+            try {
+                const s = await client.status(b.path, { messages: true, unseen: true });
+                messages = s.messages ?? 0;
+                unseen = s.unseen ?? 0;
+            }
+            catch {
+                // \Noselect or otherwise un-status-able mailbox → report zeros
+            }
+            out.push({ path: b.path, name: b.name, messages, unseen });
+        }
+        return out;
+    }, true);
+}
+/** Aggregate stats via STATUS (counts) + INBOX SEARCH SINCE (recent) (I3). */
+export function imapMailStats(deps = {}) {
+    return useClient(deps, async (client) => {
+        const perMailbox = [];
+        let totalMessages = 0;
+        let totalUnread = 0;
+        for (const b of await client.list()) {
+            try {
+                const s = await client.status(b.path, { messages: true, unseen: true });
+                const messages = s.messages ?? 0;
+                const unseen = s.unseen ?? 0;
+                totalMessages += messages;
+                totalUnread += unseen;
+                perMailbox.push({ mailbox: b.path, messages, unseen });
+            }
+            catch {
+                // skip un-status-able mailbox
+            }
+        }
+        // Recent counts against INBOX (the meaningful "received" surface).
+        const since = (days) => new Date(Date.now() - days * 86_400_000);
+        const countSince = async (days) => {
+            try {
+                const lock = await client.getMailboxLock("INBOX");
+                try {
+                    const found = await client.search({ since: since(days) }, { uid: true });
+                    return Array.isArray(found) ? found.length : 0;
+                }
+                finally {
+                    lock.release();
+                }
+            }
+            catch {
+                return 0;
+            }
+        };
+        const [last24h, last7d, last30d] = await Promise.all([
+            countSince(1),
+            countSince(7),
+            countSince(30),
+        ]);
+        return { totalMessages, totalUnread, perMailbox, recent: { last24h, last7d, last30d } };
+    }, true);
+}
 function errText(e) {
     return e instanceof Error ? e.message : String(e);
 }
@@ -618,3 +709,203 @@ export async function imapDeleteMessageById(id, deps = {}) {
         }
     });
 }
+/** Walk a BODYSTRUCTURE tree collecting attachment parts (disposition or filename). */
+function collectAttachments(node, out = []) {
+    if (!node)
+        return out;
+    const filename = node.dispositionParameters?.filename || node.parameters?.name;
+    const disposition = node.disposition?.toLowerCase();
+    const isAttachment = !!node.part && (disposition === "attachment" || (!!filename && disposition !== "inline"));
+    if (isAttachment) {
+        out.push({
+            part: node.part,
+            filename: filename || `part-${node.part}`,
+            mimeType: node.type || "application/octet-stream",
+            size: node.size ?? 0,
+        });
+    }
+    for (const child of node.childNodes ?? [])
+        collectAttachments(child, out);
+    return out;
+}
+async function streamToBuffer(content) {
+    const chunks = [];
+    for await (const chunk of content)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks);
+}
+/** List a message's attachments via IMAP BODYSTRUCTURE (no full download). */
+export async function imapListAttachments(id, deps = {}) {
+    const ref = decodeImapId(id);
+    if (!ref)
+        return { success: false, error: `Not an IMAP message id: "${id}".` };
+    return withMailbox(ref.path, { ...deps, account: deps.account ?? ref.account }, async (client) => {
+        const msg = await client.fetchOne(String(ref.uid), { bodyStructure: true }, { uid: true });
+        if (!msg || !msg.bodyStructure) {
+            return { success: false, error: `IMAP message UID ${ref.uid} not found in "${ref.path}".` };
+        }
+        const attachments = collectAttachments(msg.bodyStructure).map((a) => ({
+            id: `${id}#${a.part}`,
+            name: a.filename,
+            mimeType: a.mimeType,
+            size: a.size,
+        }));
+        return { success: true, attachments };
+    });
+}
+/** Fetch one attachment's bytes (base64) via IMAP, matched by filename. */
+export async function imapFetchAttachment(id, attachmentName, deps = {}) {
+    const ref = decodeImapId(id);
+    if (!ref)
+        return { success: false, error: `Not an IMAP message id: "${id}".` };
+    return withMailbox(ref.path, { ...deps, account: deps.account ?? ref.account }, async (client) => {
+        const msg = await client.fetchOne(String(ref.uid), { bodyStructure: true }, { uid: true });
+        if (!msg || !msg.bodyStructure) {
+            return { success: false, error: `IMAP message UID ${ref.uid} not found in "${ref.path}".` };
+        }
+        const atts = collectAttachments(msg.bodyStructure);
+        const match = atts.find((a) => a.filename === attachmentName);
+        if (!match) {
+            const names = atts.map((a) => a.filename).join(", ") || "none";
+            return {
+                success: false,
+                error: `Attachment "${attachmentName}" not found on UID ${ref.uid}. Available: ${names}.`,
+            };
+        }
+        const dl = await client.download(String(ref.uid), match.part, { uid: true });
+        const buf = await streamToBuffer(dl.content);
+        return {
+            success: true,
+            base64: buf.toString("base64"),
+            bytes: buf.length,
+            mimeType: match.mimeType,
+        };
+    });
+}
+async function imapBatch(ids, deps, op) {
+    const groups = new Map();
+    const errors = [];
+    let failed = 0;
+    for (const id of ids) {
+        const ref = decodeImapId(id);
+        if (!ref) {
+            failed++;
+            errors.push(`Not an IMAP id: "${id}"`);
+            continue;
+        }
+        const key = `${ref.account}${ref.path}`;
+        const g = groups.get(key) ?? { account: ref.account, path: ref.path, uids: [] };
+        g.uids.push(ref.uid);
+        groups.set(key, g);
+    }
+    let success = 0;
+    for (const g of groups.values()) {
+        try {
+            await useClient({ ...deps, account: deps.account ?? g.account }, async (client) => {
+                const lock = await client.getMailboxLock(g.path);
+                try {
+                    await op(client, g.uids, g.path);
+                }
+                finally {
+                    lock.release();
+                }
+            });
+            success += g.uids.length;
+        }
+        catch (e) {
+            failed += g.uids.length;
+            errors.push(`${g.path}: ${errText(e)}`);
+        }
+    }
+    return { success, failed, errors };
+}
+export const imapBatchMarkRead = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
+    await c.messageFlagsAdd(uids, ["\\Seen"], { uid: true });
+});
+export const imapBatchMarkUnread = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
+    await c.messageFlagsRemove(uids, ["\\Seen"], { uid: true });
+});
+export const imapBatchFlag = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
+    await c.messageFlagsAdd(uids, ["\\Flagged"], { uid: true });
+});
+export const imapBatchUnflag = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
+    await c.messageFlagsRemove(uids, ["\\Flagged"], { uid: true });
+});
+export const imapBatchDelete = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
+    await c.messageDelete(uids, { uid: true });
+});
+export function imapBatchMove(ids, destMailbox, deps = {}) {
+    return imapBatch(ids, deps, async (c, uids) => {
+        const dest = (await findMailboxPath(c, destMailbox)) ?? resolveMailboxPath(destMailbox, "list");
+        await c.messageMove(uids, dest, { uid: true });
+    });
+}
+function senderName(from) {
+    const a = from?.[0];
+    if (!a)
+        return "(unknown)";
+    return a.name ? `${a.name} <${a.address ?? ""}>` : (a.address ?? "(unknown)");
+}
+function dateMs(m) {
+    return m.envelope?.date ? new Date(m.envelope.date).getTime() : 0;
+}
+export async function imapThread(id, deps = {}, limit = 50) {
+    const ref = decodeImapId(id);
+    if (!ref)
+        return null;
+    return useClient({ ...deps, account: deps.account ?? ref.account }, async (client) => {
+        const lock = await client.getMailboxLock(ref.path);
+        try {
+            const seed = await client.fetchOne(String(ref.uid), { envelope: true, headers: ["references", "in-reply-to", "message-id"] }, { uid: true });
+            if (!seed)
+                return null;
+            const seedMsgId = seed.envelope?.messageId;
+            const refIds = new Set();
+            const hdr = seed.headers ? seed.headers.toString() : "";
+            for (const m of hdr.matchAll(/<[^>]+>/g))
+                refIds.add(m[0]);
+            if (seed.envelope?.inReplyTo)
+                refIds.add(seed.envelope.inReplyTo);
+            const uidSet = new Set([ref.uid]);
+            const addFound = (found) => {
+                if (Array.isArray(found))
+                    found.forEach((u) => uidSet.add(u));
+            };
+            // Descendants: anything referencing the seed.
+            if (seedMsgId) {
+                addFound(await client.search({ header: { references: seedMsgId } }, { uid: true }));
+                addFound(await client.search({ header: { "in-reply-to": seedMsgId } }, { uid: true }));
+            }
+            // Ancestors: messages whose Message-ID is in the seed's References (bounded).
+            for (const mid of [...refIds].slice(0, 20)) {
+                addFound(await client.search({ header: { "message-id": mid } }, { uid: true }));
+            }
+            if (uidSet.size <= 1)
+                return null; // only the seed → caller falls back to subject
+            const uids = [...uidSet].slice(0, limit);
+            const msgs = [];
+            for await (const msg of client.fetch(uids.join(","), { envelope: true, flags: true }, { uid: true })) {
+                msgs.push(msg);
+            }
+            msgs.sort((a, b) => dateMs(a) - dateMs(b)); // oldest first
+            const subject = seed.envelope?.subject || "(no subject)";
+            const structured = {
+                subject,
+                count: msgs.length,
+                messages: msgs.map((m) => ({
+                    id: encodeImapId(ref.account, ref.path, m.uid),
+                    subject: m.envelope?.subject || "(no subject)",
+                    sender: senderName(m.envelope?.from),
+                    date: m.envelope?.date ? new Date(m.envelope.date).toISOString() : "",
+                    isRead: m.flags?.has("\\Seen") ?? false,
+                })),
+            };
+            const text = `Thread "${subject}" — ${msgs.length} message(s) via IMAP (References-linked, oldest first):\n` +
+                msgs.map((m) => formatRow(m, ref.account, ref.path)).join("\n");
+            return { count: msgs.length, text, structured };
+        }
+        finally {
+            lock.release();
+        }
+    }, true);
+}

package/package.json

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