apple-mail-mcp 1.7.0 → 1.8.0

package/README.md

@@ -279,9 +279,15 @@ 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).
+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).
 
 Routing is conservative: only a call whose explicit `account` matches the
 configured IMAP account goes to IMAP; everything else falls through to
@@ -303,9 +309,15 @@ 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.
+> 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).
+>
+> **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.
 
 ---
 

package/build/index.js

@@ -25,7 +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 { isImapAccount, imapSearchMessages, imapListMessages, imapCreateMailbox, imapDeleteMailbox, imapRenameMailbox, } from "./services/imapClient.js";
 import { createSerialGate } from "./utils/serialize.js";
 // =============================================================================
 // Shared Validation Schemas
@@ -582,7 +582,15 @@ server.tool("get-unread-count", {
 server.tool("create-mailbox", {
     name: z.string().min(1, "Mailbox name is required"),
     account: z.string().optional().describe("Account to create the mailbox in"),
-}, withErrorHandling(({ name, account }) => {
+}, withErrorHandling(async ({ name, account }) => {
+    // IMAP backend (issue #43, Phase 2): server-side folder op when this account
+    // is IMAP-configured; otherwise AppleScript.
+    if (isImapAccount(account)) {
+        const r = await imapCreateMailbox(name);
+        if (!r.success)
+            return errorResponse(r.error || `Failed to create mailbox "${name}"`);
+        return successResponse(r.info || `Mailbox "${name}" created`);
+    }
     const success = mailManager.createMailbox(name, account);
     if (!success) {
         return errorResponse(`Failed to create mailbox "${name}"`);
@@ -593,7 +601,13 @@ server.tool("create-mailbox", {
 server.tool("delete-mailbox", {
     name: z.string().min(1, "Mailbox name is required"),
     account: z.string().optional().describe("Account containing the mailbox"),
-}, withErrorHandling(({ name, account }) => {
+}, withErrorHandling(async ({ name, account }) => {
+    if (isImapAccount(account)) {
+        const r = await imapDeleteMailbox(name);
+        if (!r.success)
+            return errorResponse(r.error || `Failed to delete mailbox "${name}"`);
+        return successResponse(r.info || `Mailbox "${name}" deleted`);
+    }
     const { success, error } = mailManager.deleteMailbox(name, account);
     if (!success) {
         return errorResponse(error || `Failed to delete mailbox "${name}"`);
@@ -605,7 +619,14 @@ server.tool("rename-mailbox", {
     oldName: z.string().min(1, "Current mailbox name is required"),
     newName: z.string().min(1, "New mailbox name is required"),
     account: z.string().optional().describe("Account containing the mailbox"),
-}, withErrorHandling(({ oldName, newName, account }) => {
+}, withErrorHandling(async ({ oldName, newName, account }) => {
+    if (isImapAccount(account)) {
+        const r = await imapRenameMailbox(oldName, newName);
+        if (!r.success) {
+            return errorResponse(r.error || `Failed to rename mailbox "${oldName}" to "${newName}"`);
+        }
+        return successResponse(r.info || `Mailbox renamed from "${oldName}" to "${newName}"`);
+    }
     const { success, error } = mailManager.renameMailbox(oldName, newName, account);
     if (!success) {
         return errorResponse(error || `Failed to rename mailbox "${oldName}" to "${newName}"`);

package/build/services/imapClient.d.ts

@@ -46,6 +46,10 @@ interface ImapMessage {
 interface MailboxLock {
     release: () => void;
 }
+interface ImapMailboxListing {
+    path: string;
+    name: string;
+}
 export interface ImapClientLike {
     connect(): Promise<void>;
     getMailboxLock(path: string): Promise<MailboxLock>;
@@ -55,6 +59,18 @@ export interface ImapClientLike {
     fetch(range: string, query: Record<string, unknown>, opts: {
         uid: true;
     }): AsyncIterable<ImapMessage>;
+    list(): Promise<ImapMailboxListing[]>;
+    mailboxCreate(path: string): Promise<{
+        path: string;
+        created: boolean;
+    }>;
+    mailboxRename(path: string, newPath: string): Promise<{
+        path: string;
+        newPath: string;
+    }>;
+    mailboxDelete(path: string): Promise<{
+        path: string;
+    }>;
     logout(): Promise<void>;
 }
 export type ImapConnect = (cfg: ImapConfig) => Promise<ImapClientLike>;
@@ -71,5 +87,22 @@ export declare function imapListMessages(args: ImapSearchArgs, deps?: {
     connect?: ImapConnect;
     config?: ImapConfig;
 }): Promise<string>;
+export interface ImapOpResult {
+    success: boolean;
+    error?: string;
+    info?: string;
+}
+export declare function imapCreateMailbox(name: string, deps?: {
+    connect?: ImapConnect;
+    config?: ImapConfig;
+}): Promise<ImapOpResult>;
+export declare function imapDeleteMailbox(name: string, deps?: {
+    connect?: ImapConnect;
+    config?: ImapConfig;
+}): Promise<ImapOpResult>;
+export declare function imapRenameMailbox(oldName: string, newName: string, deps?: {
+    connect?: ImapConnect;
+    config?: ImapConfig;
+}): Promise<ImapOpResult>;
 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":"AAsBA,eAAO,MAAM,QAAQ;;;;;;;;CAQX,CAAC;AAEX,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,WAAW;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;CACtB;AACD,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACrB;AACD,UAAU,WAAW;IACnB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AACD,MAAM,WAAW,cAAc;IAC7B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACnD,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC;IACvF,KAAK,CACH,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,EAAE;QAAE,GAAG,EAAE,IAAI,CAAA;KAAE,GAClB,aAAa,CAAC,WAAW,CAAC,CAAC;IAC9B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AAEvE,+EAA+E;AAC/E,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAKT;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,CA6BlF;AAcD,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAc/F;AA8ED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAO,GACxD,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAO,GACxD,OAAO,CAAC,MAAM,CAAC,CAEjB"}
+{"version":3,"file":"imapClient.d.ts","sourceRoot":"","sources":["../../src/services/imapClient.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,QAAQ;;;;;;;;CAQX,CAAC;AAEX,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,WAAW;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;CACtB;AACD,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACrB;AACD,UAAU,WAAW;IACnB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AACD,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AACD,MAAM,WAAW,cAAc;IAC7B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACnD,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC;IACvF,KAAK,CACH,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,EAAE;QAAE,GAAG,EAAE,IAAI,CAAA;KAAE,GAClB,aAAa,CAAC,WAAW,CAAC,CAAC;IAC9B,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACtC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACzE,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzF,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AAEvE,+EAA+E;AAC/E,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAKT;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,CA6BlF;AAcD,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAc/F;AA8ED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAO,GACxD,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAO,GACxD,OAAO,CAAC,MAAM,CAAC,CAEjB;AAYD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAkCD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAO,GACxD,OAAO,CAAC,YAAY,CAAC,CAWvB;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAO,GACxD,OAAO,CAAC,YAAY,CAAC,CAmBvB;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,WAAW,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAO,GACxD,OAAO,CAAC,YAAY,CAAC,CAmBvB"}

package/build/services/imapClient.js

@@ -175,3 +175,86 @@ export function imapSearchMessages(args, deps = {}) {
 export function imapListMessages(args, deps = {}) {
     return run(args, true, deps);
 }
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** Connect, run `fn`, always log out. */
+async function withClient(deps, fn) {
+    const cfg = deps.config ?? resolveImapConfig();
+    const client = await (deps.connect ?? defaultConnect)(cfg);
+    try {
+        return await fn(client, cfg);
+    }
+    finally {
+        await client.logout().catch(() => undefined);
+    }
+}
+/**
+ * Resolve a user-supplied mailbox name to an actual server path by listing the
+ * mailboxes and matching on full path, then leaf name (case-insensitive).
+ * Returns null when no such mailbox exists.
+ */
+async function findMailboxPath(client, name) {
+    const wanted = name.trim().toLowerCase();
+    const boxes = await client.list();
+    const byPath = boxes.find((b) => b.path.toLowerCase() === wanted);
+    if (byPath)
+        return byPath.path;
+    const byName = boxes.find((b) => b.name.toLowerCase() === wanted);
+    return byName ? byName.path : null;
+}
+export function imapCreateMailbox(name, deps = {}) {
+    return withClient(deps, async (client) => {
+        try {
+            const res = await client.mailboxCreate(name);
+            return res.created
+                ? { success: true, info: `Created mailbox "${res.path}".` }
+                : { success: true, info: `Mailbox "${res.path}" already existed.` };
+        }
+        catch (e) {
+            return { success: false, error: `IMAP create failed for "${name}": ${errText(e)}` };
+        }
+    });
+}
+export function imapDeleteMailbox(name, deps = {}) {
+    return withClient(deps, async (client, cfg) => {
+        const path = await findMailboxPath(client, name);
+        if (!path) {
+            return {
+                success: false,
+                error: `Mailbox "${name}" not found on IMAP account ${cfg.accountLabel}.`,
+            };
+        }
+        try {
+            await client.mailboxDelete(path);
+            return {
+                success: true,
+                info: `Deleted mailbox "${path}" via IMAP (account ${cfg.accountLabel}).`,
+            };
+        }
+        catch (e) {
+            return { success: false, error: `IMAP delete failed for "${path}": ${errText(e)}` };
+        }
+    });
+}
+export function imapRenameMailbox(oldName, newName, deps = {}) {
+    return withClient(deps, async (client, cfg) => {
+        const path = await findMailboxPath(client, oldName);
+        if (!path) {
+            return {
+                success: false,
+                error: `Mailbox "${oldName}" not found on IMAP account ${cfg.accountLabel}.`,
+            };
+        }
+        try {
+            const res = await client.mailboxRename(path, newName);
+            return { success: true, info: `Renamed "${res.path}" to "${res.newPath}" via IMAP.` };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: `IMAP rename failed for "${path}" -> "${newName}": ${errText(e)}`,
+            };
+        }
+    });
+}

package/package.json

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