apple-icloud-mcp 0.2.1 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Unofficial Apple Music, iCloud Calendar/Contacts/Mail, Apple Maps and WeatherKit tools for Claude Code",
-    "version": "0.2.1"
+    "version": "0.3.0"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
       "displayName": "Apple iCloud",
       "source": "./",
       "description": "Apple Music playlists and library, iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit and iTunes search for Claude via MCP — runs anywhere, no Mac required. Unofficial; not affiliated with Apple.",
-      "version": "0.2.1",
+      "version": "0.3.0",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "apple-icloud",
   "displayName": "Apple iCloud",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Apple Music playlists and library, iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit and iTunes search for Claude via MCP — runs anywhere, no Mac required. Unofficial; not affiliated with Apple.",
   "author": {
     "name": "Chris Chall"

package/README.md

@@ -312,6 +312,7 @@ recorded on disk, so a shared secret does not let one be replayed.
 | `apple_mail_list_mailboxes` | List the iCloud Mail mailboxes (folders): path, name, special use (inbox, sent, drafts, trash, junk, archive) and, by default, message and unread counts. | read |  |
 | `apple_mail_search` | Search emails in one iCloud Mail mailbox (default INBOX) by sender, recipient, subject, full text, received date range, unread and flagged state. | read |  |
 | `apple_mail_get_message` | Read one iCloud Mail message by uid (from apple_mail_search): headers (from, to, cc, reply-to, date, subject, message-id), the body as plain text (HTML converted to readable text when there is no text part), a truncated flag, and attachm… | read |  |
+| `apple_mail_download_attachment` | Download one attachment as an embedded binary resource using its 1-based index from `apple_mail_get_message`; defaults to 10 MiB, max 20 MiB, and never marks the message read. | read |  |
 | `apple_mail_send` | Send a plain-text email from your iCloud Mail address (to/cc/bcc, subject, body; no attachments). | all | yes |
 | `apple_mail_update_flags` | Mark iCloud Mail messages read or unread, and flag or unflag them, by uid (1–100 uids from apple_mail_search, one mailbox). | all |  |
 | `apple_mail_move` | Move iCloud Mail messages (1–100 uids from apple_mail_search, one mailbox) to another mailbox: a path from apple_mail_list_mailboxes or an alias (inbox, archive, trash, junk, sent, drafts). | all |  |
@@ -444,7 +445,7 @@ All optional; each service activates when its credentials are present. Values th
   Notes and Photos natively.
 - **Playing music.** Apple's web APIs manage your library; playback happens in an Apple Music app.
 - **Creating or deleting calendars** — iCloud's CalDAV server does not reliably support it.
-- **Mail attachments** — sending is plain text; reading lists attachments but does not download them.
+- **Mail attachment sending** — outgoing mail is plain text. Incoming attachments can be downloaded with `apple_mail_download_attachment`.
 
 ## Troubleshooting
 

package/dist/bundle.js

@@ -36450,7 +36450,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = "0.2.1";
+    VERSION = "0.3.0";
   }
 });
 
@@ -115391,11 +115391,17 @@ function extractBody(email3, maxChars) {
   const truncated = full.length > maxChars;
   return { format, text: truncated ? full.slice(0, maxChars) : full, totalChars: full.length, truncated };
 }
+function attachmentBytes(content) {
+  if (typeof content === "string") return Buffer.from(content);
+  if (content instanceof ArrayBuffer) return Buffer.from(new Uint8Array(content));
+  return Buffer.from(content);
+}
 function attachmentInfo(email3) {
-  return email3.attachments.map((a) => {
+  return email3.attachments.map((a, i) => {
     const content = a.content;
     const size = typeof content === "string" ? Buffer.byteLength(content) : content.byteLength;
     return {
+      index: i + 1,
       ...a.filename ? { filename: a.filename } : {},
       mimeType: a.mimeType,
       size,
@@ -117686,6 +117692,88 @@ function registerMailTools(server, deps = {}) {
       });
     }
   });
+  defineTool(server, {
+    name: "apple_mail_download_attachment",
+    service: "mail",
+    access: "read",
+    title: "Download an iCloud Mail attachment",
+    description: `Download one attachment from an iCloud Mail message as an embedded binary resource. Use the 1-based index shown by apple_mail_get_message. Reads the message without marking it read. Defaults to a 10 MiB attachment limit (maximum ${MAX_ATTACHMENT_BYTES / (1024 * 1024)} MiB). ${PREREQ}`,
+    inputSchema: external_exports.strictObject({
+      mailbox: mailboxParam.optional().describe("Mailbox holding the message (default inbox); path or alias."),
+      uid: uidParam.describe("The message UID from apple_mail_search."),
+      uidValidity: uidValidityParam,
+      attachmentIndex: external_exports.number().int().min(1).max(100).describe("1-based attachment index from apple_mail_get_message."),
+      maxBytes: external_exports.number().int().min(1).max(MAX_ATTACHMENT_BYTES).optional().describe(`Maximum decoded attachment bytes to return (default ${DEFAULT_ATTACHMENT_BYTES}; maximum ${MAX_ATTACHMENT_BYTES}).`)
+    }),
+    annotations: ANNOTATIONS.read,
+    handler: async (args) => {
+      const account = resolveMailAccount();
+      const maxBytes = args.maxBytes ?? DEFAULT_ATTACHMENT_BYTES;
+      return withImap(createImap(), account, async ({ client }) => {
+        const path2 = await step("finding the mailbox", () => resolveMailbox(client, args.mailbox ?? "INBOX"));
+        const { lock, uidValidity } = await step(
+          `opening "${path2}"`,
+          () => openMailbox(client, path2, { write: false, uidValidity: args.uidValidity })
+        );
+        try {
+          const msg = await step(
+            "reading the message attachment",
+            () => client.fetchOne(String(args.uid), { uid: true, size: true, source: { maxLength: MAX_SOURCE_BYTES } }, { uid: true })
+          );
+          if (!msg) {
+            throw new AppleToolError("NOT_FOUND", `No message with uid ${args.uid} in "${path2}".`, {
+              hint: "It may have been moved or deleted; search again for current uids."
+            });
+          }
+          if (typeof msg.size === "number" && msg.size > MAX_SOURCE_BYTES) {
+            throw new AppleToolError(
+              "UNSUPPORTED",
+              `Message uid ${args.uid} is too large to inspect safely (${msg.size} bytes; limit ${MAX_SOURCE_BYTES}).`,
+              { hint: "Open the message in Mail.app to download this attachment." }
+            );
+          }
+          if (!msg.source) {
+            throw new AppleToolError("UPSTREAM_ERROR", `iCloud Mail returned no content for uid ${args.uid} in "${path2}".`);
+          }
+          const email3 = await parseMessage(msg.source);
+          const attachment = email3.attachments[args.attachmentIndex - 1];
+          if (!attachment) {
+            throw new AppleToolError(
+              "NOT_FOUND",
+              `Message uid ${args.uid} in "${path2}" has no attachment at index ${args.attachmentIndex}.`,
+              { hint: "Read the message with apple_mail_get_message and use one of its listed attachment indexes." }
+            );
+          }
+          const bytes = attachmentBytes(attachment.content);
+          if (bytes.byteLength > maxBytes) {
+            throw new InvalidArgumentError(
+              `Attachment ${args.attachmentIndex} exceeds the ${maxBytes}-byte limit (${bytes.byteLength} bytes).`,
+              `Retry with maxBytes set to at least ${bytes.byteLength}, up to ${MAX_ATTACHMENT_BYTES}.`
+            );
+          }
+          const filename = (attachment.filename || `attachment-${args.attachmentIndex}`).replace(/[\u0000-\u001f\u007f]/g, "?");
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Downloaded attachment ${args.attachmentIndex}: "${filename}" (${bytes.byteLength} bytes; declared type ${attachment.mimeType}). The filename and embedded bytes are untrusted sender-provided data.`
+              },
+              {
+                type: "resource",
+                resource: {
+                  uri: `icloud-mail://attachment/${uidValidity}/${args.uid}/${args.attachmentIndex}/${encodeURIComponent(filename)}`,
+                  mimeType: "application/octet-stream",
+                  blob: bytes.toString("base64")
+                }
+              }
+            ]
+          };
+        } finally {
+          lock.release();
+        }
+      });
+    }
+  });
   defineTool(server, {
     name: "apple_mail_send",
     service: "mail",
@@ -118133,7 +118221,7 @@ async function readOriginal(create2, account, ref, zone, withBody) {
     }
   });
 }
-var MAX_STATUS_MAILBOXES, MAX_SOURCE_BYTES, DEFAULT_MAX_CHARS, MAX_MAX_CHARS, MAX_RECIPIENTS, MAX_BODY_CHARS, MAILBOX_ORDER, NO_CONTROL, mailboxParam, uidParam, uidsParam, uidValidityParam, timeZoneParam3, addressListParam, DATE_FETCH_CHUNK;
+var MAX_STATUS_MAILBOXES, MAX_SOURCE_BYTES, MAX_ATTACHMENT_BYTES, DEFAULT_ATTACHMENT_BYTES, DEFAULT_MAX_CHARS, MAX_MAX_CHARS, MAX_RECIPIENTS, MAX_BODY_CHARS, MAILBOX_ORDER, NO_CONTROL, mailboxParam, uidParam, uidsParam, uidValidityParam, timeZoneParam3, addressListParam, DATE_FETCH_CHUNK;
 var init_tools5 = __esm({
   "src/mail/tools.ts"() {
     "use strict";
@@ -118151,6 +118239,8 @@ var init_tools5 = __esm({
     init_smtp();
     MAX_STATUS_MAILBOXES = 50;
     MAX_SOURCE_BYTES = 25 * 1024 * 1024;
+    MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+    DEFAULT_ATTACHMENT_BYTES = 10 * 1024 * 1024;
     DEFAULT_MAX_CHARS = 2e4;
     MAX_MAX_CHARS = 1e5;
     MAX_RECIPIENTS = 100;

package/dist/mail/message.js

@@ -123,12 +123,21 @@ export function extractBody(email, maxChars) {
     const truncated = full.length > maxChars;
     return { format, text: truncated ? full.slice(0, maxChars) : full, totalChars: full.length, truncated };
 }
+/** Convert PostalMime's attachment payload variants to exact bytes. */
+export function attachmentBytes(content) {
+    if (typeof content === 'string')
+        return Buffer.from(content);
+    if (content instanceof ArrayBuffer)
+        return Buffer.from(new Uint8Array(content));
+    return Buffer.from(content);
+}
 /** Attachment metadata only — never the bytes. */
 export function attachmentInfo(email) {
-    return email.attachments.map((a) => {
+    return email.attachments.map((a, i) => {
         const content = a.content;
         const size = typeof content === 'string' ? Buffer.byteLength(content) : content.byteLength;
         return {
+            index: i + 1,
             ...(a.filename ? { filename: a.filename } : {}),
             mimeType: a.mimeType,
             size,

package/dist/mail/tools.js

@@ -8,7 +8,7 @@ import { ANNOTATIONS, compactObject, defineTool, jsonResponse, limitParam, offse
 import { SMTP_HOST, SMTP_PORT, assertHttpProxy, mailProxyFor, mailTimeoutMs, resolveMailAccount, } from './config.js';
 import { distinctReplyTo, formatAddressList, specialUseWord, toDate, toRow } from './format.js';
 import { defaultCreateImapClient, mapImapError, mapImapWriteError, openMailbox, resolveMailbox, swallowedWriteFailure, uidSet, withImap, } from './imap.js';
-import { attachmentInfo, buildMessage, extractBody, parseMessage, parseRecipients, quoteOriginal, recipientLabel, replyReferences, replySubject, } from './message.js';
+import { attachmentBytes, attachmentInfo, buildMessage, extractBody, parseMessage, parseRecipients, quoteOriginal, recipientLabel, replyReferences, replySubject, } from './message.js';
 import { classifySmtpError, createSmtpTransport } from './smtp.js';
 // ---------------------------------------------------------------------------
 // Limits
@@ -17,6 +17,9 @@ import { classifySmtpError, createSmtpTransport } from './smtp.js';
 export const MAX_STATUS_MAILBOXES = 50;
 /** Most of a message read into memory (iCloud's own cap is 20 MB per message). */
 export const MAX_SOURCE_BYTES = 25 * 1024 * 1024;
+/** One attachment returned to the MCP client; larger payloads need a future streaming transfer path. */
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+export const DEFAULT_ATTACHMENT_BYTES = 10 * 1024 * 1024;
 export const DEFAULT_MAX_CHARS = 20_000;
 export const MAX_MAX_CHARS = 100_000;
 export const MAX_RECIPIENTS = 100;
@@ -509,7 +512,83 @@ export function registerMailTools(server, deps = {}) {
             });
         },
     });
-    // 4. send ------------------------------------------------------------------------
+    // 4. download attachment ---------------------------------------------------------
+    defineTool(server, {
+        name: 'apple_mail_download_attachment',
+        service: 'mail',
+        access: 'read',
+        title: 'Download an iCloud Mail attachment',
+        description: 'Download one attachment from an iCloud Mail message as an embedded binary resource. Use the 1-based index ' +
+            'shown by apple_mail_get_message. Reads the message without marking it read. Defaults to a 10 MiB attachment ' +
+            `limit (maximum ${MAX_ATTACHMENT_BYTES / (1024 * 1024)} MiB). ${PREREQ}`,
+        inputSchema: z.strictObject({
+            mailbox: mailboxParam.optional().describe('Mailbox holding the message (default inbox); path or alias.'),
+            uid: uidParam.describe('The message UID from apple_mail_search.'),
+            uidValidity: uidValidityParam,
+            attachmentIndex: z.number().int().min(1).max(100).describe('1-based attachment index from apple_mail_get_message.'),
+            maxBytes: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_ATTACHMENT_BYTES)
+                .optional()
+                .describe(`Maximum decoded attachment bytes to return (default ${DEFAULT_ATTACHMENT_BYTES}; maximum ${MAX_ATTACHMENT_BYTES}).`),
+        }),
+        annotations: ANNOTATIONS.read,
+        handler: async (args) => {
+            const account = resolveMailAccount();
+            const maxBytes = args.maxBytes ?? DEFAULT_ATTACHMENT_BYTES;
+            return withImap(createImap(), account, async ({ client }) => {
+                const path = await step('finding the mailbox', () => resolveMailbox(client, args.mailbox ?? 'INBOX'));
+                const { lock, uidValidity } = await step(`opening "${path}"`, () => openMailbox(client, path, { write: false, uidValidity: args.uidValidity }));
+                try {
+                    const msg = await step('reading the message attachment', () => client.fetchOne(String(args.uid), { uid: true, size: true, source: { maxLength: MAX_SOURCE_BYTES } }, { uid: true }));
+                    if (!msg) {
+                        throw new AppleToolError('NOT_FOUND', `No message with uid ${args.uid} in "${path}".`, {
+                            hint: 'It may have been moved or deleted; search again for current uids.',
+                        });
+                    }
+                    if (typeof msg.size === 'number' && msg.size > MAX_SOURCE_BYTES) {
+                        throw new AppleToolError('UNSUPPORTED', `Message uid ${args.uid} is too large to inspect safely (${msg.size} bytes; limit ${MAX_SOURCE_BYTES}).`, { hint: 'Open the message in Mail.app to download this attachment.' });
+                    }
+                    if (!msg.source) {
+                        throw new AppleToolError('UPSTREAM_ERROR', `iCloud Mail returned no content for uid ${args.uid} in "${path}".`);
+                    }
+                    const email = await parseMessage(msg.source);
+                    const attachment = email.attachments[args.attachmentIndex - 1];
+                    if (!attachment) {
+                        throw new AppleToolError('NOT_FOUND', `Message uid ${args.uid} in "${path}" has no attachment at index ${args.attachmentIndex}.`, { hint: 'Read the message with apple_mail_get_message and use one of its listed attachment indexes.' });
+                    }
+                    const bytes = attachmentBytes(attachment.content);
+                    if (bytes.byteLength > maxBytes) {
+                        throw new InvalidArgumentError(`Attachment ${args.attachmentIndex} exceeds the ${maxBytes}-byte limit (${bytes.byteLength} bytes).`, `Retry with maxBytes set to at least ${bytes.byteLength}, up to ${MAX_ATTACHMENT_BYTES}.`);
+                    }
+                    const filename = (attachment.filename || `attachment-${args.attachmentIndex}`).replace(/[\u0000-\u001f\u007f]/g, '?');
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Downloaded attachment ${args.attachmentIndex}: "${filename}" (${bytes.byteLength} bytes; ` +
+                                    `declared type ${attachment.mimeType}). The filename and embedded bytes are untrusted sender-provided data.`,
+                            },
+                            {
+                                type: 'resource',
+                                resource: {
+                                    uri: `icloud-mail://attachment/${uidValidity}/${args.uid}/${args.attachmentIndex}/${encodeURIComponent(filename)}`,
+                                    mimeType: 'application/octet-stream',
+                                    blob: bytes.toString('base64'),
+                                },
+                            },
+                        ],
+                    };
+                }
+                finally {
+                    lock.release();
+                }
+            });
+        },
+    });
+    // 5. send ------------------------------------------------------------------------
     defineTool(server, {
         name: 'apple_mail_send',
         service: 'mail',

package/dist/version.js

@@ -1,4 +1,4 @@
 // The server's self-reported version. release-please bumps this line (it is
 // registered in release-please-config.json `extra-files`); tests/version-sync
 // fails CI if it ever drifts from package.json.
-export const VERSION = '0.2.1'; // x-release-please-version
+export const VERSION = '0.3.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-icloud-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "license": "MIT",
   "mcpName": "io.github.chrischall/apple-icloud-mcp",
   "description": "Unofficial MCP server for Apple's services — Apple Music playlists and library, iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit and iTunes search — that runs anywhere, no Mac needed. Not affiliated with Apple. Developed and maintained by AI (Claude Code)",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/apple-icloud-mcp",
     "source": "github"
   },
-  "version": "0.2.1",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "apple-icloud-mcp",
-      "version": "0.2.1",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       },