apple-mail-mcp 1.6.10 → 1.7.0

package/README.md

@@ -270,6 +270,43 @@ Then send:
 
 The default `applescript` transport is unchanged; SMTP is opt-in per call.
 
+##### IMAP backend (read/search) — opt-in, Phase 1
+
+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). Read-only for now — `get-message` and all
+mutations stay on AppleScript (the IMAP rows report message **UIDs**, noted in
+the output).
+
+Routing is conservative: only a call whose explicit `account` matches the
+configured IMAP account goes to IMAP; everything else falls through to
+AppleScript.
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APPLE_MAIL_MCP_IMAP_USER` | Yes | — | Login address; setting it enables IMAP |
+| `APPLE_MAIL_MCP_IMAP_ACCOUNT` | No | = user | Mail account name to match for routing |
+| `APPLE_MAIL_MCP_IMAP_HOST` | No | `imap.gmail.com` | IMAP server hostname |
+| `APPLE_MAIL_MCP_IMAP_PORT` | No | `993` | IMAP port (993 = implicit TLS) |
+| `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 |
+
+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. Phase 2 (IMAP-backed
+> mutations + folder ops, which would also resolve the IMAP slice of
+> [#42](https://github.com/sweetrb/apple-mail-mcp/issues/42)) is not yet implemented.
+
 ---
 
 #### `send-serial-email`

package/build/index.js

@@ -25,6 +25,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { AppleMailManager } from "./services/appleMailManager.js";
 import { sendViaSmtp } from "./services/smtpMailer.js";
+import { isImapAccount, imapSearchMessages, imapListMessages } from "./services/imapClient.js";
 import { createSerialGate } from "./utils/serialize.js";
 // =============================================================================
 // Shared Validation Schemas
@@ -157,7 +158,23 @@ server.tool("search-messages", {
     dateFrom: DATE_FILTER_SCHEMA.describe("Start date filter (e.g., 'January 1, 2026')"),
     dateTo: DATE_FILTER_SCHEMA.describe("End date filter (e.g., 'March 1, 2026')"),
     limit: z.number().optional().describe("Maximum number of results (default: 50)"),
-}, withErrorHandling(({ query, mailbox, account, limit = 50, dateFrom, dateTo, from, subject, isRead, isFlagged, }) => {
+}, withErrorHandling(async ({ query, mailbox, account, limit = 50, dateFrom, dateTo, from, subject, isRead, isFlagged, }) => {
+    // IMAP backend (issue #43): server-side search when this account is
+    // explicitly configured for IMAP; otherwise fall through to AppleScript.
+    if (isImapAccount(account)) {
+        return successResponse(await imapSearchMessages({
+            query,
+            mailbox,
+            account,
+            limit,
+            dateFrom,
+            dateTo,
+            from,
+            subject,
+            isRead,
+            isFlagged,
+        }));
+    }
     const { messages, diagnostics } = mailManager.searchMessagesWithDiagnostics(query, mailbox, account, limit, dateFrom, dateTo, from, subject, isRead, isFlagged);
     const coverageBlock = partialCoverageBlock(diagnostics);
     if (messages.length === 0) {
@@ -200,7 +217,12 @@ server.tool("list-messages", {
     offset: z.number().optional().describe("Number of messages to skip (for pagination)"),
     from: z.string().optional().describe("Filter by sender email address or name"),
     unreadOnly: z.boolean().optional().describe("Only show unread messages"),
-}, withErrorHandling(({ mailbox, account, limit = 50, offset = 0, from }) => {
+}, withErrorHandling(async ({ mailbox, account, limit = 50, offset = 0, from, unreadOnly }) => {
+    // IMAP backend (issue #43): server-side listing when this account is
+    // explicitly configured for IMAP; otherwise fall through to AppleScript.
+    if (isImapAccount(account)) {
+        return successResponse(await imapListMessages({ mailbox, account, limit, offset, from, unreadOnly }));
+    }
     const { messages, diagnostics } = mailManager.listMessagesWithDiagnostics(mailbox, account, limit, from, offset);
     const coverageBlock = partialCoverageBlock(diagnostics);
     if (messages.length === 0) {

package/build/services/imapClient.d.ts

@@ -0,0 +1,75 @@
+export declare const IMAP_ENV: {
+    readonly user: "APPLE_MAIL_MCP_IMAP_USER";
+    readonly account: "APPLE_MAIL_MCP_IMAP_ACCOUNT";
+    readonly host: "APPLE_MAIL_MCP_IMAP_HOST";
+    readonly port: "APPLE_MAIL_MCP_IMAP_PORT";
+    readonly password: "APPLE_MAIL_MCP_IMAP_PASSWORD";
+    readonly keychainService: "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE";
+    readonly keychainAccount: "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT";
+};
+export interface ImapConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    pass: string;
+    accountLabel: string;
+}
+export interface ImapSearchArgs {
+    query?: string;
+    account?: string;
+    from?: string;
+    subject?: string;
+    mailbox?: string;
+    limit?: number;
+    dateFrom?: string;
+    dateTo?: string;
+    isRead?: boolean;
+    isFlagged?: boolean;
+    unreadOnly?: boolean;
+    offset?: number;
+}
+interface ImapAddress {
+    name?: string;
+    address?: string;
+}
+interface ImapEnvelope {
+    subject?: string;
+    date?: Date | string;
+    from?: ImapAddress[];
+}
+interface ImapMessage {
+    uid: number;
+    envelope?: ImapEnvelope;
+    flags?: Set<string>;
+}
+interface MailboxLock {
+    release: () => void;
+}
+export interface ImapClientLike {
+    connect(): Promise<void>;
+    getMailboxLock(path: string): Promise<MailboxLock>;
+    search(query: Record<string, unknown>, opts: {
+        uid: true;
+    }): Promise<number[] | false>;
+    fetch(range: string, query: Record<string, unknown>, opts: {
+        uid: true;
+    }): AsyncIterable<ImapMessage>;
+    logout(): Promise<void>;
+}
+export type ImapConnect = (cfg: ImapConfig) => Promise<ImapClientLike>;
+/** True only when IMAP is configured AND the explicit `account` matches it. */
+export declare function isImapAccount(account: string | undefined, env?: NodeJS.ProcessEnv): boolean;
+export declare function resolveImapConfig(env?: NodeJS.ProcessEnv): ImapConfig;
+/** Map common (Gmail) mailbox names to their IMAP paths. */
+export declare function resolveMailboxPath(mailbox: string | undefined, mode: "search" | "list"): string;
+export declare function imapSearchMessages(args: ImapSearchArgs, deps?: {
+    connect?: ImapConnect;
+    config?: ImapConfig;
+}): Promise<string>;
+export declare function imapListMessages(args: ImapSearchArgs, deps?: {
+    connect?: ImapConnect;
+    config?: ImapConfig;
+}): Promise<string>;
+export {};
+//# sourceMappingURL=imapClient.d.ts.map

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

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

package/build/services/imapClient.js

@@ -0,0 +1,177 @@
+/**
+ * IMAP backend for read/search (issue #43, Phase 1).
+ *
+ * AppleScript-over-Mail.app is the default. When an account is explicitly
+ * configured for IMAP (env below), `search-messages` and `list-messages` route
+ * here instead, running a SERVER-SIDE search — orders of magnitude faster than
+ * AppleScript's client-side `whose` enumeration on large Gmail mailboxes, and
+ * correct (no false-empty on timeout). Read-only; mutations stay on AppleScript.
+ *
+ * Opt-in via env (mirrors the SMTP transport pattern):
+ *   APPLE_MAIL_MCP_IMAP_USER      (required — enables IMAP; the login address)
+ *   APPLE_MAIL_MCP_IMAP_ACCOUNT   (Mail account name to match for routing; default = USER)
+ *   APPLE_MAIL_MCP_IMAP_HOST      (default imap.gmail.com)
+ *   APPLE_MAIL_MCP_IMAP_PORT      (default 993, implicit TLS)
+ *   APPLE_MAIL_MCP_IMAP_PASSWORD  (else Keychain via the two vars below)
+ *   APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE / _KEYCHAIN_ACCOUNT
+ *
+ * @module services/imapClient
+ */
+import { ImapFlow } from "imapflow";
+import { readKeychainPassword } from "../services/smtpMailer.js";
+export const IMAP_ENV = {
+    user: "APPLE_MAIL_MCP_IMAP_USER",
+    account: "APPLE_MAIL_MCP_IMAP_ACCOUNT",
+    host: "APPLE_MAIL_MCP_IMAP_HOST",
+    port: "APPLE_MAIL_MCP_IMAP_PORT",
+    password: "APPLE_MAIL_MCP_IMAP_PASSWORD",
+    keychainService: "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE",
+    keychainAccount: "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT",
+};
+/** True only when IMAP is configured AND the explicit `account` matches it. */
+export function isImapAccount(account, env = process.env) {
+    const user = env[IMAP_ENV.user]?.trim();
+    if (!user || !account)
+        return false;
+    const label = env[IMAP_ENV.account]?.trim() || user;
+    return account === label || account === user;
+}
+export function resolveImapConfig(env = process.env) {
+    const user = env[IMAP_ENV.user]?.trim();
+    if (!user) {
+        throw new Error(`IMAP not configured. Set ${IMAP_ENV.user} (login address) to enable it.`);
+    }
+    const host = env[IMAP_ENV.host]?.trim() || "imap.gmail.com";
+    const port = env[IMAP_ENV.port] ? Number.parseInt(env[IMAP_ENV.port], 10) : 993;
+    if (!Number.isInteger(port) || port <= 0) {
+        throw new Error(`Invalid ${IMAP_ENV.port}: "${env[IMAP_ENV.port]}".`);
+    }
+    let pass = env[IMAP_ENV.password];
+    if (!pass) {
+        const svc = env[IMAP_ENV.keychainService]?.trim();
+        const acct = env[IMAP_ENV.keychainAccount]?.trim() || user;
+        if (svc)
+            pass = readKeychainPassword(svc, acct) ?? undefined;
+    }
+    if (!pass) {
+        throw new Error(`No IMAP password. Set ${IMAP_ENV.password}, or ${IMAP_ENV.keychainService}/${IMAP_ENV.keychainAccount} for the Keychain.`);
+    }
+    return {
+        host,
+        port,
+        secure: port === 993,
+        user,
+        pass,
+        accountLabel: env[IMAP_ENV.account]?.trim() || user,
+    };
+}
+const defaultConnect = async (cfg) => {
+    const client = new ImapFlow({
+        host: cfg.host,
+        port: cfg.port,
+        secure: cfg.secure,
+        auth: { user: cfg.user, pass: cfg.pass },
+        logger: false,
+    });
+    await client.connect();
+    return client;
+};
+/** Map common (Gmail) mailbox names to their IMAP paths. */
+export function resolveMailboxPath(mailbox, mode) {
+    if (!mailbox)
+        return mode === "search" ? "[Gmail]/All Mail" : "INBOX";
+    const map = {
+        "all mail": "[Gmail]/All Mail",
+        "sent mail": "[Gmail]/Sent Mail",
+        sent: "[Gmail]/Sent Mail",
+        trash: "[Gmail]/Trash",
+        drafts: "[Gmail]/Drafts",
+        spam: "[Gmail]/Spam",
+        junk: "[Gmail]/Spam",
+        starred: "[Gmail]/Starred",
+        important: "[Gmail]/Important",
+    };
+    return map[mailbox.trim().toLowerCase()] ?? mailbox;
+}
+function buildCriteria(a, listMode) {
+    const c = {};
+    if (a.query)
+        c.or = [{ subject: a.query }, { from: a.query }];
+    if (a.from)
+        c.from = a.from;
+    if (a.subject)
+        c.subject = a.subject;
+    if (a.isRead === true)
+        c.seen = true;
+    if (a.isRead === false)
+        c.unseen = true;
+    if (a.unreadOnly && listMode)
+        c.unseen = true;
+    if (a.isFlagged === true)
+        c.flagged = true;
+    if (a.isFlagged === false)
+        c.unflagged = true;
+    if (a.dateFrom)
+        c.since = new Date(a.dateFrom);
+    if (a.dateTo)
+        c.before = new Date(a.dateTo);
+    if (Object.keys(c).length === 0)
+        c.all = true;
+    return c;
+}
+function formatRow(m) {
+    const env = m.envelope ?? {};
+    const subject = env.subject || "(no subject)";
+    const a = env.from?.[0];
+    const from = a
+        ? a.name
+            ? `${a.name} <${a.address ?? ""}>`
+            : (a.address ?? "(unknown)")
+        : "(unknown)";
+    const date = env.date ? new Date(env.date).toLocaleDateString() : "";
+    const read = m.flags?.has("\\Seen") ? "read" : "unread";
+    return `  - UID: ${m.uid} | ${date} | ${subject} (from: ${from}) [${read}]`;
+}
+async function run(args, listMode, deps) {
+    const cfg = deps.config ?? resolveImapConfig();
+    const client = await (deps.connect ?? defaultConnect)(cfg);
+    try {
+        const path = resolveMailboxPath(args.mailbox, listMode ? "list" : "search");
+        const lock = await client.getMailboxLock(path);
+        try {
+            const found = await client.search(buildCriteria(args, listMode), { uid: true });
+            const uids = Array.isArray(found) ? found : [];
+            if (uids.length === 0) {
+                return `No messages found via IMAP in "${path}" (account ${cfg.accountLabel}).`;
+            }
+            const limit = args.limit ?? 50;
+            const offset = args.offset ?? 0;
+            // UIDs are ascending → newest are the highest. Apply offset+limit from the newest end.
+            const newest = uids
+                .slice()
+                .reverse()
+                .slice(offset, offset + limit);
+            const byUid = new Map();
+            for await (const msg of client.fetch(newest.join(","), { envelope: true, flags: true }, { uid: true })) {
+                byUid.set(msg.uid, formatRow(msg));
+            }
+            const rows = newest.map((u) => byUid.get(u)).filter((r) => Boolean(r));
+            const verb = listMode ? "listed" : "matched";
+            return (`Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, mailbox "${path}"; ${uids.length} total ${verb}):\n` +
+                rows.join("\n") +
+                `\n\nNote: IDs are IMAP UIDs. get-message and message mutations still use the AppleScript path (Phase 1 is read/search only).`);
+        }
+        finally {
+            lock.release();
+        }
+    }
+    finally {
+        await client.logout().catch(() => undefined);
+    }
+}
+export function imapSearchMessages(args, deps = {}) {
+    return run(args, false, deps);
+}
+export function imapListMessages(args, deps = {}) {
+    return run(args, true, deps);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "1.6.10",
+  "version": "1.7.0",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude",
   "type": "module",
   "main": "build/index.js",
@@ -59,6 +59,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "imapflow": "^1.4.1",
     "nodemailer": "^9.0.0",
     "zod": "^3.22.4"
   },