icloud-mcp 1.1.0 → 1.2.0

package/README.md

@@ -5,13 +5,14 @@ A Model Context Protocol (MCP) server that connects Claude Desktop to your iClou
 ## Features
 
 - 📬 Read and paginate through your inbox
-- 🔍 Search emails by keyword, sender, or date range
+- 🔍 Search emails by keyword, sender, date range, and more
 - 🗑️ Bulk delete emails by any combination of filters
 - 📁 Bulk move emails between folders with flexible filtering
 - 📊 Analyze top senders to identify inbox clutter
 - 🔢 Count emails matching any filter before taking action
-- ✅ Mark emails as read/unread, flag/unflag
-- 🗂️ List and create mailboxes
+- ✅ Mark emails as read/unread, flag/unflag in bulk or individually
+- 🗂️ List, create, rename, and delete mailboxes
+- 🔄 Dry run mode for bulk operations — preview before committing
 
 ## Prerequisites
 
@@ -77,33 +78,38 @@ Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manag
 
 | Tool | Description |
 |------|-------------|
-| `get_inbox_summary` | Total, unread, and recent email counts |
-| `get_top_senders` | Top senders by volume from a sample of recent emails |
+| `get_inbox_summary` | Total, unread, and recent email counts for INBOX |
+| `get_mailbox_summary` | Total, unread, and recent email counts for any folder |
+| `get_top_senders` | Top senders by volume from a sample of recent emails (supports `sampleSize` and `maxResults`) |
 | `get_unread_senders` | Top senders of unread emails (supports `sampleSize` and `maxResults`) |
 | `read_inbox` | Paginated inbox with sender, subject, date |
 | `get_email` | Full content of a specific email by UID |
 | `get_emails_by_sender` | All emails from a specific address |
 | `get_emails_by_date_range` | Emails between two dates |
-| `search_emails` | Search by keyword across subject, sender, and body |
+| `search_emails` | Search by keyword with optional filters (date, unread, domain, etc.) |
 | `count_emails` | Count emails matching any combination of filters without modifying them |
-| `bulk_move` | Move emails matching any combination of filters between folders |
-| `bulk_delete` | Delete emails matching any combination of filters |
-| `flag_email` | Flag or unflag an email |
-| `mark_as_read` | Mark an email as read or unread |
-| `delete_email` | Move an email to Deleted Messages |
+| `bulk_move` | Move emails matching any combination of filters between folders (supports `dryRun`) |
+| `bulk_delete` | Delete emails matching any combination of filters (supports `dryRun`) |
+| `bulk_flag` | Flag or unflag emails matching any combination of filters |
+| `bulk_mark_read` | Mark all emails (or all from a sender) as read |
+| `bulk_mark_unread` | Mark all emails (or all from a sender) as unread |
 | `bulk_delete_by_sender` | Delete all emails from a sender |
 | `bulk_delete_by_subject` | Delete all emails matching a subject keyword |
 | `bulk_move_by_sender` | Move all emails from a sender to a folder |
-| `bulk_mark_read` | Mark all emails (or all from a sender) as read |
-| `delete_older_than` | Delete all emails older than N days |
+| `flag_email` | Flag or unflag a single email |
+| `mark_as_read` | Mark a single email as read or unread |
+| `delete_email` | Move an email to Deleted Messages |
 | `move_email` | Move a single email to a folder |
+| `delete_older_than` | Delete all emails older than N days |
 | `list_mailboxes` | List all folders in your iCloud Mail |
 | `create_mailbox` | Create a new folder |
+| `rename_mailbox` | Rename an existing folder |
+| `delete_mailbox` | Delete a folder (must be empty first) |
 | `empty_trash` | Permanently delete all emails in Deleted Messages |
 
-## Bulk Move & Delete Filters
+## Bulk Move, Delete & Flag Filters
 
-`bulk_move` and `bulk_delete` accept any combination of these filters:
+`bulk_move`, `bulk_delete`, `bulk_flag`, `search_emails`, and `count_emails` all accept any combination of these filters:
 
 | Filter | Type | Description |
 |--------|------|-------------|
@@ -118,17 +124,25 @@ Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manag
 | `smaller` | number | Only emails smaller than this size in KB |
 | `hasAttachment` | boolean | Only emails with attachments |
 
+### Dry Run Mode
+
+Pass `dryRun: true` to `bulk_move` or `bulk_delete` to preview how many emails would be affected without making any changes:
+
+> *"How many emails would be deleted if I removed everything from linkedin.com before 2022?"*
+
 ## Example Usage
 
 Once configured, you can ask Claude things like:
 
 - *"Show me the top senders in my iCloud inbox"*
 - *"How many unread emails do I have from substack.com?"*
+- *"How many emails would be moved if I archived everything from linkedin.com before 2022?"*
 - *"Move all emails from substack.com older than 2023 to my Newsletters folder"*
 - *"Delete all unread emails from linkedin.com before 2022"*
 - *"Move everything in my old_folders/college folder to Archive"*
 - *"How many emails do I have with attachments larger than 5MB?"*
-- *"Delete all emails from no-reply@instagram.com"*
+- *"Flag all unread emails from my bank"*
+- *"Rename my Newsletters folder to Old Newsletters"*
 - *"Show me emails from the last week"*
 
 ## Security

package/index.js

@@ -84,7 +84,7 @@ async function getInboxSummary(mailbox = 'INBOX') {
   return { mailbox, total: status.messages, unread: status.unseen, recent: status.recent };
 }
 
-async function getTopSenders(mailbox = 'INBOX', sampleSize = 500) {
+async function getTopSenders(mailbox = 'INBOX', sampleSize = 500, maxResults = 20) {
   const client = createClient();
   await client.connect();
   const mb = await client.mailboxOpen(mailbox);
@@ -108,8 +108,8 @@ async function getTopSenders(mailbox = 'INBOX', sampleSize = 500) {
   }
 
   await client.logout();
-  const topAddresses = Object.entries(senderCounts).sort((a, b) => b[1] - a[1]).slice(0, 20).map(([address, count]) => ({ address, count }));
-  const topDomains = Object.entries(senderDomains).sort((a, b) => b[1] - a[1]).slice(0, 20).map(([domain, count]) => ({ domain, count }));
+  const topAddresses = Object.entries(senderCounts).sort((a, b) => b[1] - a[1]).slice(0, maxResults).map(([address, count]) => ({ address, count }));
+  const topDomains = Object.entries(senderDomains).sort((a, b) => b[1] - a[1]).slice(0, maxResults).map(([domain, count]) => ({ domain, count }));
   return { sampledEmails: count, topAddresses, topDomains };
 }
 
@@ -126,7 +126,6 @@ async function getUnreadSenders(mailbox = 'INBOX', sampleSize = 500, maxResults
     return [];
   }
 
-  // Fetch all envelopes in a single batch instead of one by one
   for await (const msg of client.fetch(recentUids, { envelope: true }, { uid: true })) {
     const address = msg.envelope.from?.[0]?.address;
     if (address) senderCounts[address] = (senderCounts[address] || 0) + 1;
@@ -244,6 +243,34 @@ async function bulkMarkRead(mailbox = 'INBOX', sender = null) {
   return { marked: uids.length, sender: sender || 'all' };
 }
 
+async function bulkMarkUnread(mailbox = 'INBOX', sender = null) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const query = sender ? { from: sender, seen: true } : { seen: true };
+  const uids = (await client.search(query, { uid: true })) ?? [];
+  if (uids.length === 0) { await client.logout(); return { marked: 0 }; }
+  await client.messageFlagsRemove(uids, ['\\Seen'], { uid: true });
+  await client.logout();
+  return { marked: uids.length, sender: sender || 'all' };
+}
+
+async function bulkFlag(filters, flagged, mailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const query = buildQuery(filters);
+  const uids = (await client.search(query, { uid: true })) ?? [];
+  if (uids.length === 0) { await client.logout(); return { flagged: 0 }; }
+  if (flagged) {
+    await client.messageFlagsAdd(uids, ['\\Flagged'], { uid: true });
+  } else {
+    await client.messageFlagsRemove(uids, ['\\Flagged'], { uid: true });
+  }
+  await client.logout();
+  return { [flagged ? 'flagged' : 'unflagged']: uids.length, filters };
+}
+
 async function emptyTrash() {
   const client = createClient();
   await client.connect();
@@ -263,6 +290,30 @@ async function createMailbox(name) {
   return { created: name };
 }
 
+async function renameMailbox(oldName, newName) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxRename(oldName, newName);
+  await client.logout();
+  return { renamed: { from: oldName, to: newName } };
+}
+
+async function deleteMailbox(name) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxDelete(name);
+  await client.logout();
+  return { deleted: name };
+}
+
+async function getMailboxSummary(mailbox) {
+  const client = createClient();
+  await client.connect();
+  const status = await client.status(mailbox, { messages: true, unseen: true, recent: true });
+  await client.logout();
+  return { mailbox, total: status.messages, unread: status.unseen, recent: status.recent };
+}
+
 async function getEmailContent(uid, mailbox = 'INBOX') {
   const client = createClient();
   await client.connect();
@@ -344,14 +395,21 @@ async function listMailboxes() {
   return mailboxes;
 }
 
-async function searchEmails(query, mailbox = 'INBOX', limit = 10) {
+async function searchEmails(query, mailbox = 'INBOX', limit = 10, filters = {}) {
   const client = createClient();
   await client.connect();
   await client.mailboxOpen(mailbox);
-  const uids = (await client.search(
-    { or: [{ subject: query }, { from: query }, { body: query }] },
-    { uid: true }
-  )) ?? [];
+
+  // Build base text search
+  const textQuery = { or: [{ subject: query }, { from: query }, { body: query }] };
+
+  // Merge with additional filters if provided
+  const extraQuery = buildQuery(filters);
+  const finalQuery = Object.keys(extraQuery).length > 0 && !extraQuery.all
+    ? { ...textQuery, ...extraQuery }
+    : textQuery;
+
+  const uids = (await client.search(finalQuery, { uid: true })) ?? [];
   const emails = [];
   const recentUids = uids.slice(-limit).reverse();
   for (const uid of recentUids) {
@@ -368,7 +426,7 @@ async function searchEmails(query, mailbox = 'INBOX', limit = 10) {
     }
   }
   await client.logout();
-  return emails;
+  return { total: uids.length, showing: emails.length, emails };
 }
 
 async function moveEmail(uid, targetMailbox, sourceMailbox = 'INBOX') {
@@ -395,29 +453,36 @@ function buildQuery(filters) {
   if (filters.larger) query.larger = filters.larger * 1024;
   if (filters.smaller) query.smaller = filters.smaller * 1024;
   if (filters.hasAttachment) query.header = ['Content-Type', 'multipart/mixed'];
-  // If no filters set, match all
   if (Object.keys(query).length === 0) query.all = true;
   return query;
 }
 
-async function bulkMove(filters, targetMailbox, sourceMailbox = 'INBOX') {
+async function bulkMove(filters, targetMailbox, sourceMailbox = 'INBOX', dryRun = false) {
   const client = createClient();
   await client.connect();
   await client.mailboxOpen(sourceMailbox);
   const query = buildQuery(filters);
   const uids = (await client.search(query, { uid: true })) ?? [];
+  if (dryRun) {
+    await client.logout();
+    return { dryRun: true, wouldMove: uids.length, sourceMailbox, targetMailbox, filters };
+  }
   if (uids.length === 0) { await client.logout(); return { moved: 0, sourceMailbox, targetMailbox }; }
   await client.messageMove(uids, targetMailbox, { uid: true });
   await client.logout();
   return { moved: uids.length, sourceMailbox, targetMailbox, filters };
 }
 
-async function bulkDelete(filters, sourceMailbox = 'INBOX') {
+async function bulkDelete(filters, sourceMailbox = 'INBOX', dryRun = false) {
   const client = createClient();
   await client.connect();
   await client.mailboxOpen(sourceMailbox);
   const query = buildQuery(filters);
   const uids = (await client.search(query, { uid: true })) ?? [];
+  if (dryRun) {
+    await client.logout();
+    return { dryRun: true, wouldDelete: uids.length, sourceMailbox, filters };
+  }
   if (uids.length === 0) { await client.logout(); return { deleted: 0, sourceMailbox }; }
   await client.messageDelete(uids, { uid: true });
   await client.logout();
@@ -436,7 +501,7 @@ async function countEmails(filters, mailbox = 'INBOX') {
 
 async function main() {
   const server = new Server(
-    { name: 'icloud-mail', version: '1.1.0' },
+    { name: 'icloud-mail', version: '1.2.0' },
     { capabilities: { tools: {} } }
   );
 
@@ -460,6 +525,17 @@ async function main() {
         description: 'Get a summary of a mailbox including total, unread, and recent email counts',
         inputSchema: { type: 'object', properties: { mailbox: { type: 'string', description: 'Mailbox name (default INBOX)' } } }
       },
+      {
+        name: 'get_mailbox_summary',
+        description: 'Get total, unread, and recent email counts for any specific mailbox/folder',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            mailbox: { type: 'string', description: 'Mailbox path to summarize (e.g. Newsletters, Archive)' }
+          },
+          required: ['mailbox']
+        }
+      },
       {
         name: 'get_top_senders',
         description: 'Get the top senders by email count from a sample of the inbox',
@@ -467,7 +543,8 @@ async function main() {
           type: 'object',
           properties: {
             mailbox: { type: 'string', description: 'Mailbox to analyze (default INBOX)' },
-            sampleSize: { type: 'number', description: 'Number of emails to sample (default 500)' }
+            sampleSize: { type: 'number', description: 'Number of emails to sample (default 500)' },
+            maxResults: { type: 'number', description: 'Max number of senders/domains to return (default 20)' }
           }
         }
       },
@@ -523,17 +600,68 @@ async function main() {
       },
       {
         name: 'search_emails',
-        description: 'Search emails by keyword',
+        description: 'Search emails by keyword, with optional filters for date, read status, domain, and more',
         inputSchema: {
           type: 'object',
           properties: {
-            query: { type: 'string', description: 'Search query' },
+            query: { type: 'string', description: 'Search keyword (matches subject, sender, body)' },
             mailbox: { type: 'string', description: 'Mailbox to search (default INBOX)' },
-            limit: { type: 'number', description: 'Max results (default 10)' }
+            limit: { type: 'number', description: 'Max results (default 10)' },
+            ...filtersSchema
           },
           required: ['query']
         }
       },
+      {
+        name: 'count_emails',
+        description: 'Count how many emails match a set of filters without moving or deleting them. Use this before bulk_move or bulk_delete to preview how many emails will be affected.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            mailbox: { type: 'string', description: 'Mailbox to count in (default INBOX)' },
+            ...filtersSchema
+          }
+        }
+      },
+      {
+        name: 'bulk_move',
+        description: 'Move emails matching any combination of filters from one mailbox to another. Operates on ALL matching emails in a single IMAP operation. Use dryRun: true to preview without making changes.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            targetMailbox: { type: 'string', description: 'Destination mailbox path' },
+            sourceMailbox: { type: 'string', description: 'Source mailbox (default INBOX)' },
+            dryRun: { type: 'boolean', description: 'If true, preview what would be moved without actually moving' },
+            ...filtersSchema
+          },
+          required: ['targetMailbox']
+        }
+      },
+      {
+        name: 'bulk_delete',
+        description: 'Delete emails matching any combination of filters. Operates on ALL matching emails in a single IMAP operation. Use dryRun: true to preview without making changes.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sourceMailbox: { type: 'string', description: 'Mailbox to delete from (default INBOX)' },
+            dryRun: { type: 'boolean', description: 'If true, preview what would be deleted without actually deleting' },
+            ...filtersSchema
+          }
+        }
+      },
+      {
+        name: 'bulk_flag',
+        description: 'Flag or unflag emails matching any combination of filters in bulk',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            flagged: { type: 'boolean', description: 'True to flag, false to unflag' },
+            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' },
+            ...filtersSchema
+          },
+          required: ['flagged']
+        }
+      },
       {
         name: 'bulk_delete_by_sender',
         description: 'Delete all emails from a specific sender',
@@ -572,61 +700,56 @@ async function main() {
         }
       },
       {
-        name: 'delete_older_than',
-        description: 'Delete all emails older than a certain number of days',
+        name: 'bulk_mark_read',
+        description: 'Mark all emails as read, optionally filtered by sender',
         inputSchema: {
           type: 'object',
           properties: {
-            days: { type: 'number', description: 'Delete emails older than this many days' },
-            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' }
-          },
-          required: ['days']
+            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' },
+            sender: { type: 'string', description: 'Optional: only mark emails from this sender as read' }
+          }
         }
       },
       {
-        name: 'get_emails_by_date_range',
-        description: 'Get emails between two dates',
+        name: 'bulk_mark_unread',
+        description: 'Mark all emails as unread, optionally filtered by sender',
         inputSchema: {
           type: 'object',
           properties: {
-            startDate: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
-            endDate: { type: 'string', description: 'End date (YYYY-MM-DD)' },
             mailbox: { type: 'string', description: 'Mailbox (default INBOX)' },
-            limit: { type: 'number', description: 'Max results (default 10)' }
-          },
-          required: ['startDate', 'endDate']
+            sender: { type: 'string', description: 'Optional: only mark emails from this sender as unread' }
+          }
         }
       },
       {
-        name: 'bulk_mark_read',
-        description: 'Mark all emails as read, optionally filtered by sender',
+        name: 'delete_older_than',
+        description: 'Delete all emails older than a certain number of days',
         inputSchema: {
           type: 'object',
           properties: {
-            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' },
-            sender: { type: 'string', description: 'Optional: only mark emails from this sender as read' }
-          }
+            days: { type: 'number', description: 'Delete emails older than this many days' },
+            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' }
+          },
+          required: ['days']
         }
       },
       {
-        name: 'empty_trash',
-        description: 'Permanently delete all emails in Deleted Messages',
-        inputSchema: { type: 'object', properties: {} }
-      },
-      {
-        name: 'create_mailbox',
-        description: 'Create a new mailbox/folder',
+        name: 'get_emails_by_date_range',
+        description: 'Get emails between two dates',
         inputSchema: {
           type: 'object',
           properties: {
-            name: { type: 'string', description: 'Name of the new mailbox' }
+            startDate: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+            endDate: { type: 'string', description: 'End date (YYYY-MM-DD)' },
+            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' },
+            limit: { type: 'number', description: 'Max results (default 10)' }
           },
-          required: ['name']
+          required: ['startDate', 'endDate']
         }
       },
       {
         name: 'flag_email',
-        description: 'Flag or unflag an email',
+        description: 'Flag or unflag a single email',
         inputSchema: {
           type: 'object',
           properties: {
@@ -639,7 +762,7 @@ async function main() {
       },
       {
         name: 'mark_as_read',
-        description: 'Mark an email as read or unread',
+        description: 'Mark a single email as read or unread',
         inputSchema: {
           type: 'object',
           properties: {
@@ -652,7 +775,7 @@ async function main() {
       },
       {
         name: 'delete_email',
-        description: 'Delete an email',
+        description: 'Delete a single email',
         inputSchema: {
           type: 'object',
           properties: {
@@ -664,7 +787,7 @@ async function main() {
       },
       {
         name: 'move_email',
-        description: 'Move an email to a different mailbox/folder',
+        description: 'Move a single email to a different mailbox/folder',
         inputSchema: {
           type: 'object',
           properties: {
@@ -681,39 +804,43 @@ async function main() {
         inputSchema: { type: 'object', properties: {} }
       },
       {
-        name: 'bulk_move',
-        description: 'Move emails matching any combination of filters from one mailbox to another. Use this for large-scale moves — it operates on ALL matching emails in a single IMAP operation regardless of count. Prefer this over read_inbox + move_email for any bulk operation.',
+        name: 'create_mailbox',
+        description: 'Create a new mailbox/folder',
         inputSchema: {
           type: 'object',
           properties: {
-            targetMailbox: { type: 'string', description: 'Destination mailbox path' },
-            sourceMailbox: { type: 'string', description: 'Source mailbox (default INBOX)' },
-            ...filtersSchema
+            name: { type: 'string', description: 'Name of the new mailbox' }
           },
-          required: ['targetMailbox']
+          required: ['name']
         }
       },
       {
-        name: 'bulk_delete',
-        description: 'Delete emails matching any combination of filters. Use this for large-scale deletes — it operates on ALL matching emails in a single IMAP operation regardless of count. Prefer this over read_inbox + delete_email for any bulk operation.',
+        name: 'rename_mailbox',
+        description: 'Rename an existing mailbox/folder',
         inputSchema: {
           type: 'object',
           properties: {
-            sourceMailbox: { type: 'string', description: 'Mailbox to delete from (default INBOX)' },
-            ...filtersSchema
-          }
+            oldName: { type: 'string', description: 'Current mailbox path' },
+            newName: { type: 'string', description: 'New mailbox path' }
+          },
+          required: ['oldName', 'newName']
         }
       },
       {
-        name: 'count_emails',
-        description: 'Count how many emails match a set of filters without moving or deleting them. Use this before bulk_move or bulk_delete to preview how many emails will be affected.',
+        name: 'delete_mailbox',
+        description: 'Delete a mailbox/folder. The folder must be empty first.',
         inputSchema: {
           type: 'object',
           properties: {
-            mailbox: { type: 'string', description: 'Mailbox to count in (default INBOX)' },
-            ...filtersSchema
-          }
+            name: { type: 'string', description: 'Mailbox path to delete' }
+          },
+          required: ['name']
         }
+      },
+      {
+        name: 'empty_trash',
+        description: 'Permanently delete all emails in Deleted Messages',
+        inputSchema: { type: 'object', properties: {} }
       }
     ]
   }));
@@ -724,8 +851,10 @@ async function main() {
       let result;
       if (name === 'get_inbox_summary') {
         result = await getInboxSummary(args.mailbox || 'INBOX');
+      } else if (name === 'get_mailbox_summary') {
+        result = await getMailboxSummary(args.mailbox);
       } else if (name === 'get_top_senders') {
-        result = await getTopSenders(args.mailbox || 'INBOX', args.sampleSize || 500);
+        result = await getTopSenders(args.mailbox || 'INBOX', args.sampleSize || 500, args.maxResults || 20);
       } else if (name === 'get_unread_senders') {
         result = await getUnreadSenders(args.mailbox || 'INBOX', args.sampleSize || 500, args.maxResults || 20);
       } else if (name === 'get_emails_by_sender') {
@@ -735,23 +864,34 @@ async function main() {
       } else if (name === 'get_email') {
         result = await getEmailContent(args.uid, args.mailbox || 'INBOX');
       } else if (name === 'search_emails') {
-        result = await searchEmails(args.query, args.mailbox || 'INBOX', args.limit || 10);
+        const { query, mailbox, limit, ...filters } = args;
+        result = await searchEmails(query, mailbox || 'INBOX', limit || 10, filters);
+      } else if (name === 'count_emails') {
+        const { mailbox, ...filters } = args;
+        result = await countEmails(filters, mailbox || 'INBOX');
+      } else if (name === 'bulk_move') {
+        const { targetMailbox, sourceMailbox, dryRun, ...filters } = args;
+        result = await bulkMove(filters, targetMailbox, sourceMailbox || 'INBOX', dryRun || false);
+      } else if (name === 'bulk_delete') {
+        const { sourceMailbox, dryRun, ...filters } = args;
+        result = await bulkDelete(filters, sourceMailbox || 'INBOX', dryRun || false);
+      } else if (name === 'bulk_flag') {
+        const { flagged, mailbox, ...filters } = args;
+        result = await bulkFlag(filters, flagged, mailbox || 'INBOX');
       } else if (name === 'bulk_delete_by_sender') {
         result = await bulkDeleteBySender(args.sender, args.mailbox || 'INBOX');
       } else if (name === 'bulk_move_by_sender') {
         result = await bulkMoveBySender(args.sender, args.targetMailbox, args.sourceMailbox || 'INBOX');
       } else if (name === 'bulk_delete_by_subject') {
         result = await bulkDeleteBySubject(args.subject, args.mailbox || 'INBOX');
+      } else if (name === 'bulk_mark_read') {
+        result = await bulkMarkRead(args.mailbox || 'INBOX', args.sender || null);
+      } else if (name === 'bulk_mark_unread') {
+        result = await bulkMarkUnread(args.mailbox || 'INBOX', args.sender || null);
       } else if (name === 'delete_older_than') {
         result = await deleteOlderThan(args.days, args.mailbox || 'INBOX');
       } else if (name === 'get_emails_by_date_range') {
         result = await getEmailsByDateRange(args.startDate, args.endDate, args.mailbox || 'INBOX', args.limit || 10);
-      } else if (name === 'bulk_mark_read') {
-        result = await bulkMarkRead(args.mailbox || 'INBOX', args.sender || null);
-      } else if (name === 'empty_trash') {
-        result = await emptyTrash();
-      } else if (name === 'create_mailbox') {
-        result = await createMailbox(args.name);
       } else if (name === 'flag_email') {
         result = await flagEmail(args.uid, args.flagged, args.mailbox || 'INBOX');
       } else if (name === 'mark_as_read') {
@@ -762,15 +902,14 @@ async function main() {
         result = await moveEmail(args.uid, args.targetMailbox, args.sourceMailbox || 'INBOX');
       } else if (name === 'list_mailboxes') {
         result = await listMailboxes();
-      } else if (name === 'bulk_move') {
-        const { targetMailbox, sourceMailbox, ...filters } = args;
-        result = await bulkMove(filters, targetMailbox, sourceMailbox || 'INBOX');
-      } else if (name === 'bulk_delete') {
-        const { sourceMailbox, ...filters } = args;
-        result = await bulkDelete(filters, sourceMailbox || 'INBOX');
-      } else if (name === 'count_emails') {
-        const { mailbox, ...filters } = args;
-        result = await countEmails(filters, mailbox || 'INBOX');
+      } else if (name === 'create_mailbox') {
+        result = await createMailbox(args.name);
+      } else if (name === 'rename_mailbox') {
+        result = await renameMailbox(args.oldName, args.newName);
+      } else if (name === 'delete_mailbox') {
+        result = await deleteMailbox(args.name);
+      } else if (name === 'empty_trash') {
+        result = await emptyTrash();
       } else {
         throw new Error(`Unknown tool: ${name}`);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icloud-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A Model Context Protocol (MCP) server for iCloud Mail",
   "main": "index.js",
   "bin": {

package/test.js

@@ -32,7 +32,7 @@ function callTool(name, args = {}) {
       {
         cwd: projectDir,
         encoding: 'utf8',
-        timeout: 180000,
+        timeout: 300000,
         env: { ...process.env, IMAP_USER, IMAP_PASSWORD }
       }
     );
@@ -74,6 +74,7 @@ function assert(condition, message) {
 
 console.log('\n🧪 iCloud MCP Server Tests\n');
 
+// ─── Mailbox & Summary ────────────────────────────────────────────────────────
 console.log('📬 Mailbox & Summary');
 
 test('get_inbox_summary', () => {
@@ -84,6 +85,14 @@ test('get_inbox_summary', () => {
   console.log(`\n     → ${result.total} total, ${result.unread} unread`);
 });
 
+test('get_mailbox_summary', () => {
+  const result = callTool('get_mailbox_summary', { mailbox: 'INBOX' });
+  assert(typeof result.total === 'number', 'total should be a number');
+  assert(typeof result.unread === 'number', 'unread should be a number');
+  assert(result.mailbox === 'INBOX', 'mailbox should be INBOX');
+  console.log(`\n     → ${result.total} total, ${result.unread} unread`);
+});
+
 test('list_mailboxes', () => {
   const result = callTool('list_mailboxes');
   assert(Array.isArray(result), 'result should be an array');
@@ -92,14 +101,23 @@ test('list_mailboxes', () => {
   console.log(`\n     → ${result.length} mailboxes found`);
 });
 
-test('get_top_senders (sample 50)', () => {
+test('get_top_senders (sample 50, default maxResults)', () => {
   const result = callTool('get_top_senders', { sampleSize: 50 });
   assert(Array.isArray(result.topAddresses), 'topAddresses should be an array');
   assert(Array.isArray(result.topDomains), 'topDomains should be an array');
   assert(result.sampledEmails <= 50, 'should not exceed sample size');
+  assert(result.topAddresses.length <= 20, 'should not exceed default maxResults of 20');
   console.log(`\n     → top sender: ${result.topAddresses[0]?.address} (${result.topAddresses[0]?.count})`);
 });
 
+test('get_top_senders (sample 50, maxResults 5)', () => {
+  const result = callTool('get_top_senders', { sampleSize: 50, maxResults: 5 });
+  assert(Array.isArray(result.topAddresses), 'topAddresses should be an array');
+  assert(result.topAddresses.length <= 5, 'should not exceed maxResults of 5');
+  assert(result.topDomains.length <= 5, 'domains should not exceed maxResults of 5');
+  console.log(`\n     → ${result.topAddresses.length} senders, ${result.topDomains.length} domains (capped at 5)`);
+});
+
 test('get_unread_senders (sample 50, default maxResults)', () => {
   const result = callTool('get_unread_senders', { sampleSize: 50 });
   assert(Array.isArray(result), 'result should be an array');
@@ -121,6 +139,7 @@ test('get_unread_senders (sample 50, maxResults 50)', () => {
   console.log(`\n     → ${result.length} unread senders found (capped at 50)`);
 });
 
+// ─── Reading Emails ───────────────────────────────────────────────────────────
 console.log('\n📧 Reading Emails');
 
 test('read_inbox (page 1, limit 5)', () => {
@@ -149,10 +168,25 @@ test('read_inbox (unread only)', () => {
   console.log(`\n     → ${result.emails.length} unread emails`);
 });
 
-test('search_emails', () => {
+test('search_emails (keyword only)', () => {
   const result = callTool('search_emails', { query: 'test', limit: 5 });
-  assert(Array.isArray(result), 'result should be an array');
-  console.log(`\n     → ${result.length} results`);
+  assert(typeof result.total === 'number', 'total should be a number');
+  assert(Array.isArray(result.emails), 'emails should be an array');
+  console.log(`\n     → ${result.total} results`);
+});
+
+test('search_emails (keyword + unread filter)', () => {
+  const result = callTool('search_emails', { query: 'test', limit: 5, unread: true });
+  assert(typeof result.total === 'number', 'total should be a number');
+  assert(Array.isArray(result.emails), 'emails should be an array');
+  console.log(`\n     → ${result.total} unread results`);
+});
+
+test('search_emails (keyword + date filter)', () => {
+  const result = callTool('search_emails', { query: 'test', limit: 5, since: '2024-01-01' });
+  assert(typeof result.total === 'number', 'total should be a number');
+  assert(Array.isArray(result.emails), 'emails should be an array');
+  console.log(`\n     → ${result.total} results since 2024`);
 });
 
 test('get_emails_by_sender', () => {
@@ -186,6 +220,7 @@ test('get_email (fetch first email content)', () => {
   console.log(`\n     → fetched email: "${result.subject?.slice(0, 40)}..."`);
 });
 
+// ─── Count & Bulk Query ───────────────────────────────────────────────────────
 console.log('\n🔍 Count & Bulk Query');
 
 test('count_emails (all in INBOX)', () => {
@@ -201,12 +236,17 @@ test('count_emails (unread only)', () => {
   console.log(`\n     → ${result.count} unread emails`);
 });
 
+test('count_emails (read only)', () => {
+  const result = callTool('count_emails', { unread: false });
+  assert(typeof result.count === 'number', 'count should be a number');
+  console.log(`\n     → ${result.count} read emails`);
+});
+
 test('count_emails (by domain)', () => {
   const senders = callTool('get_top_senders', { sampleSize: 20 });
   const topDomain = senders.topDomains[0]?.domain;
   assert(topDomain, 'should have at least one domain');
   const result = callTool('count_emails', { domain: topDomain });
-  console.log('\n     → raw result:', JSON.stringify(result));
   assert(typeof result.count === 'number', 'count should be a number');
   console.log(`\n     → ${result.count} emails from @${topDomain}`);
 });
@@ -217,6 +257,30 @@ test('count_emails (before date)', () => {
   console.log(`\n     → ${result.count} emails before 2020`);
 });
 
+test('count_emails (flagged false)', () => {
+  const result = callTool('count_emails', { flagged: false });
+  assert(typeof result.count === 'number', 'count should be a number');
+  console.log(`\n     → ${result.count} unflagged emails`);
+});
+
+test('bulk_move (dryRun)', () => {
+  const senders = callTool('get_top_senders', { sampleSize: 20 });
+  const topDomain = senders.topDomains[0]?.domain;
+  assert(topDomain, 'should have at least one domain');
+  const result = callTool('bulk_move', { domain: topDomain, targetMailbox: 'Archive', dryRun: true });
+  assert(result.dryRun === true, 'dryRun should be true');
+  assert(typeof result.wouldMove === 'number', 'wouldMove should be a number');
+  console.log(`\n     → would move ${result.wouldMove} emails from @${topDomain}`);
+});
+
+test('bulk_delete (dryRun)', () => {
+  const result = callTool('bulk_delete', { before: '2015-01-01', dryRun: true });
+  assert(result.dryRun === true, 'dryRun should be true');
+  assert(typeof result.wouldDelete === 'number', 'wouldDelete should be a number');
+  console.log(`\n     → would delete ${result.wouldDelete} emails before 2015`);
+});
+
+// ─── Write Operations ─────────────────────────────────────────────────────────
 console.log('\n✏️  Write Operations (flag/mark only — no deletions)');
 
 test('flag_email and unflag_email', () => {
@@ -241,10 +305,35 @@ test('mark_as_read and mark_as_unread', () => {
   console.log(`\n     → marked read/unread uid ${uid}`);
 });
 
+// ─── Mailbox Management ───────────────────────────────────────────────────────
+console.log('\n🗂️  Mailbox Management');
+
+test('create_mailbox', () => {
+  const result = callTool('create_mailbox', { name: 'mcp-test-folder' });
+  assert(result.created === 'mcp-test-folder', 'should confirm creation');
+  console.log(`\n     → created: ${result.created}`);
+});
+
+test('rename_mailbox', () => {
+  const result = callTool('rename_mailbox', { oldName: 'mcp-test-folder', newName: 'mcp-test-folder-renamed' });
+  assert(result.renamed.from === 'mcp-test-folder', 'from should match old name');
+  assert(result.renamed.to === 'mcp-test-folder-renamed', 'to should match new name');
+  console.log(`\n     → renamed: ${result.renamed.from} → ${result.renamed.to}`);
+});
+
+test('delete_mailbox', () => {
+  const result = callTool('delete_mailbox', { name: 'mcp-test-folder-renamed' });
+  assert(result.deleted === 'mcp-test-folder-renamed', 'should confirm deletion');
+  console.log(`\n     → deleted: ${result.deleted}`);
+});
+
+// ─── Destructive (skipped) ────────────────────────────────────────────────────
 console.log('\n⚠️  Destructive Tests (skipped by default)');
-console.log('  Skipping: bulk_move (sender → target folder)');
-console.log('  Skipping: bulk_move (folder → folder)');
-console.log('  Skipping: bulk_delete (by domain)');
+console.log('  Skipping: bulk_move (live)');
+console.log('  Skipping: bulk_delete (live)');
+console.log('  Skipping: bulk_mark_read (live)');
+console.log('  Skipping: bulk_mark_unread (live)');
+console.log('  Skipping: bulk_flag (live)');
 console.log('  Skipping: bulk_delete_by_sender');
 console.log('  Skipping: bulk_delete_by_subject');
 console.log('  Skipping: delete_older_than');