icloud-mcp 1.2.2 → 1.4.1

package/README.md

@@ -13,6 +13,8 @@ A Model Context Protocol (MCP) server that connects Claude Desktop to your iClou
 - ✅ 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
+- 🔐 Safe move — emails are fingerprinted and verified in the destination before being removed from the source
+- 📝 Session logging — Claude tracks progress across long multi-step operations
 
 ## Prerequisites
 
@@ -70,7 +72,20 @@ Add the following under `mcpServers`, replacing the path with your npm root path
 
 > **Note:** If your `npm root -g` returned a different path, replace `/opt/homebrew/lib/node_modules` with that path.
 
-### 4. Restart Claude Desktop
+### 4. Add Custom Instructions (Recommended)
+
+For large inbox operations, add the following to Claude Desktop's custom instructions to ensure Claude stays on track and checks in with you regularly. Go to **Claude Desktop → Settings → Custom Instructions** and add:
+
+```
+When using icloud-mail tools:
+1. Before starting any multi-step operation, call log_clear then log_write with your full plan
+2. After every single tool call, call log_write with what you did and the result
+3. After every 3 tool calls, stop and summarize progress to the user and wait for confirmation before continuing
+4. Never assume a bulk operation succeeded — always verify with count_emails after
+5. If you are ever unsure what you have done so far, call log_read before proceeding
+```
+
+### 5. Restart Claude Desktop
 
 Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manage your iCloud inbox through Claude.
 
@@ -106,6 +121,11 @@ Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manag
 | `rename_mailbox` | Rename an existing folder |
 | `delete_mailbox` | Delete a folder (must be empty first) |
 | `empty_trash` | Permanently delete all emails in Deleted Messages |
+| `get_move_status` | Check the status of the current or most recent bulk move operation |
+| `abandon_move` | Abandon an in-progress move operation so a new one can start |
+| `log_write` | Write a step to the session log |
+| `log_read` | Read the session log to see what has been done so far |
+| `log_clear` | Clear the session log and start fresh |
 
 ## Bulk Move, Delete & Flag Filters
 
@@ -124,12 +144,20 @@ 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
+## 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?"*
 
+## Safe Move
+
+All bulk move operations use a copy-verify-delete approach. Emails are fingerprinted before copying, confirmed present in the destination, and only then removed from the source. A persistent manifest at `~/.icloud-mcp-move-manifest.json` tracks progress across chunks so that a crash or connection drop mid-operation never results in data loss. Use `get_move_status` to inspect any operation and `abandon_move` to clear a stuck one.
+
+## Session Log
+
+The session log persists to `~/.icloud-mcp-session.json` on your Mac — outside Claude's context window — so progress is never lost during long operations. Claude can write its plan at the start, log each completed step, and read the log back at any point to reorient itself.
+
 ## Example Usage
 
 Once configured, you can ask Claude things like:

package/index.js

@@ -3,6 +3,13 @@ import { ImapFlow } from 'imapflow';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const LOG_FILE = join(homedir(), '.icloud-mcp-session.json');
+const MANIFEST_FILE = join(homedir(), '.icloud-mcp-move-manifest.json');
+const MAX_HISTORY = 5;
 
 const IMAP_USER = process.env.IMAP_USER;
 const IMAP_PASSWORD = process.env.IMAP_PASSWORD;
@@ -22,6 +29,385 @@ function createClient() {
   });
 }
 
+// ─── Move Manifest ────────────────────────────────────────────────────────────
+
+const CHUNK_SIZE = 250;
+const CHUNK_SIZE_RETRY = 100;
+
+function readManifest() {
+  if (!existsSync(MANIFEST_FILE)) return { current: null, history: [] };
+  try {
+    return JSON.parse(readFileSync(MANIFEST_FILE, 'utf8'));
+  } catch {
+    return { current: null, history: [] };
+  }
+}
+
+function writeManifest(data) {
+  writeFileSync(MANIFEST_FILE, JSON.stringify(data, null, 2));
+}
+
+function updateManifest(updater) {
+  const data = readManifest();
+  updater(data);
+  data.current.updatedAt = new Date().toISOString();
+  writeManifest(data);
+  return data;
+}
+
+function archiveCurrent(data) {
+  if (data.current) {
+    data.history.unshift(data.current);
+    if (data.history.length > MAX_HISTORY) data.history = data.history.slice(0, MAX_HISTORY);
+    data.current = null;
+  }
+}
+
+function getMoveStatus() {
+  const data = readManifest();
+  if (!data.current) return { status: 'no_operation', history: data.history.map(summarizeOp) };
+  return {
+    current: formatOperation(data.current),
+    history: data.history.map(summarizeOp)
+  };
+}
+
+function abandonMove() {
+  const data = readManifest();
+  if (!data.current) return { abandoned: false, message: 'No in-progress operation to abandon' };
+  if (data.current.status !== 'in_progress') {
+    return { abandoned: false, message: `Current operation is already '${data.current.status}', nothing to abandon` };
+  }
+  const operationId = data.current.operationId;
+  data.current.status = 'abandoned';
+  data.current.updatedAt = new Date().toISOString();
+  archiveCurrent(data);
+  writeManifest(data);
+  return { abandoned: true, operationId };
+}
+
+function startOperation(source, target, uids) {
+  const data = readManifest();
+
+  if (data.current && data.current.status === 'in_progress') {
+    const op = data.current;
+    throw new Error(
+      `Incomplete move operation detected (${op.operationId}): ` +
+      `${op.summary.emailsMoved} of ${op.totalUids} emails moved from '${op.source}' to '${op.target}' ` +
+      `started at ${op.startedAt}. ` +
+      `Call abandon_move to discard it or get_move_status to inspect it before starting a new operation.`
+    );
+  }
+
+  archiveCurrent(data);
+
+  const operationId = `move_${Date.now()}`;
+  const chunks = [];
+
+  for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
+    chunks.push({
+      index: chunks.length,
+      uids: uids.slice(i, i + CHUNK_SIZE),
+      fingerprints: [],
+      status: 'pending',
+      copiedAt: null,
+      verifiedAt: null,
+      deletedAt: null,
+      failureReason: null
+    });
+  }
+
+  data.current = {
+    operationId,
+    startedAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    source,
+    target,
+    totalUids: uids.length,
+    status: 'in_progress',
+    chunks,
+    summary: {
+      chunksComplete: 0,
+      emailsMoved: 0,
+      emailsPending: uids.length,
+      emailsFailed: 0
+    }
+  };
+
+  writeManifest(data);
+  return data.current;
+}
+
+function updateChunk(index, updates) {
+  updateManifest((data) => {
+    const chunk = data.current.chunks[index];
+    Object.assign(chunk, updates);
+
+    let moved = 0, failed = 0, pending = 0;
+    for (const c of data.current.chunks) {
+      if (c.status === 'complete') moved += c.uids.length;
+      else if (c.status === 'failed') failed += c.uids.length;
+      else pending += c.uids.length;
+    }
+    data.current.summary = {
+      chunksComplete: data.current.chunks.filter(c => c.status === 'complete').length,
+      emailsMoved: moved,
+      emailsPending: pending,
+      emailsFailed: failed
+    };
+  });
+}
+
+function completeOperation() {
+  const data = readManifest();
+  if (!data.current) return;
+  data.current.status = 'complete';
+  data.current.updatedAt = new Date().toISOString();
+  archiveCurrent(data);
+  writeManifest(data);
+}
+
+function failOperation(reason) {
+  const data = readManifest();
+  if (!data.current) return;
+  data.current.status = 'failed';
+  data.current.failureReason = reason;
+  data.current.updatedAt = new Date().toISOString();
+  archiveCurrent(data);
+  writeManifest(data);
+}
+
+function formatOperation(op) {
+  return {
+    operationId: op.operationId,
+    status: op.status,
+    source: op.source,
+    target: op.target,
+    startedAt: op.startedAt,
+    updatedAt: op.updatedAt,
+    summary: op.summary,
+    failedChunks: op.chunks.filter(c => c.status === 'failed').map(c => ({
+      index: c.index,
+      uids: c.uids.length,
+      reason: c.failureReason
+    }))
+  };
+}
+
+function summarizeOp(op) {
+  return {
+    operationId: op.operationId,
+    status: op.status,
+    source: op.source,
+    target: op.target,
+    startedAt: op.startedAt,
+    moved: op.summary.emailsMoved,
+    failed: op.summary.emailsFailed,
+    total: op.totalUids
+  };
+}
+
+// ─── Fingerprinting ───────────────────────────────────────────────────────────
+
+function buildFingerprint(msg) {
+  const messageId = msg.envelope?.messageId ?? null;
+  const sender = msg.envelope?.from?.[0]?.address ?? '';
+  const date = msg.envelope?.date ? new Date(msg.envelope.date).toISOString() : '';
+  const subject = msg.envelope?.subject ?? '';
+  const fallback = [sender, date, subject].join('|');
+  return { uid: msg.uid, messageId, fallback };
+}
+
+function fingerprintToKey(fp) {
+  return fp.messageId ?? fp.fallback;
+}
+
+// ─── IMAP Move Helpers ────────────────────────────────────────────────────────
+
+async function fetchEnvelopes(mailbox, uids) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const envelopes = [];
+  for await (const msg of client.fetch(uids, { envelope: true }, { uid: true })) {
+    envelopes.push(msg);
+  }
+  await client.logout();
+  return envelopes;
+}
+
+async function copyChunk(sourceMailbox, targetMailbox, uids) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(sourceMailbox);
+  await client.messageCopy(uids, targetMailbox, { uid: true });
+  await client.logout();
+}
+
+async function deleteChunk(sourceMailbox, uids) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(sourceMailbox);
+  await client.messageDelete(uids, { uid: true });
+  await client.logout();
+}
+
+async function verifyFingerprintsInTarget(targetMailbox, expectedFingerprints) {
+  const client = createClient();
+  await client.connect();
+  const mb = await client.mailboxOpen(targetMailbox);
+  const total = mb.exists;
+
+  // Fetch recent envelopes from target — copies land at the end
+  const fetchCount = Math.min(total, expectedFingerprints.length * 2 + 500);
+  const start = Math.max(1, total - fetchCount + 1);
+  const range = `${start}:${total}`;
+
+  const targetKeys = new Set();
+  for await (const msg of client.fetch(range, { envelope: true })) {
+    const fp = buildFingerprint(msg);
+    targetKeys.add(fingerprintToKey(fp));
+  }
+  await client.logout();
+
+  const missing = [];
+  for (const fp of expectedFingerprints) {
+    const key = fingerprintToKey(fp);
+    if (!targetKeys.has(key)) missing.push(fp);
+  }
+
+  return {
+    verified: missing.length === 0,
+    missing,
+    found: expectedFingerprints.length - missing.length,
+    expected: expectedFingerprints.length
+  };
+}
+
+// ─── Transient error detection ────────────────────────────────────────────────
+
+function isTransient(err) {
+  const msg = err.message ?? '';
+  return msg.includes('ECONNRESET') ||
+    msg.includes('ECONNREFUSED') ||
+    msg.includes('ETIMEDOUT') ||
+    msg.includes('EPIPE') ||
+    msg.includes('socket hang up') ||
+    msg.includes('Connection not available') ||
+    msg.includes('BAD') ||      // IMAP BAD response — often transient on Apple
+    msg.includes('NO ');        // IMAP NO response — often transient on Apple
+}
+
+async function withRetry(label, fn, maxAttempts = 3) {
+  let lastErr;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (!isTransient(err) || attempt === maxAttempts) throw err;
+      const delay = attempt * 2000; // 2s, 4s backoff
+      process.stderr.write(`[retry] ${label} failed (attempt ${attempt}/${maxAttempts}): ${err.message} — retrying in ${delay}ms\n`);
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+  throw lastErr;
+}
+
+// ─── Safe Move ────────────────────────────────────────────────────────────────
+
+async function safeMoveEmails(uids, sourceMailbox, targetMailbox) {
+  const operation = startOperation(sourceMailbox, targetMailbox, uids);
+  let totalMoved = 0;
+  let totalFailed = 0;
+
+  for (const chunk of operation.chunks) {
+    const chunkUids = chunk.uids;
+    let succeeded = false;
+
+    // Try at full chunk size first, then smaller on verification failure
+    for (const attemptChunkSize of [CHUNK_SIZE, CHUNK_SIZE_RETRY]) {
+      const subChunks = [];
+      for (let i = 0; i < chunkUids.length; i += attemptChunkSize) {
+        subChunks.push(chunkUids.slice(i, i + attemptChunkSize));
+      }
+
+      let verificationFailed = false;
+
+      for (const subChunk of subChunks) {
+        // Step 1: fetch fingerprints from source and write to manifest
+        // before doing anything destructive — retries on transient errors
+        const envelopes = await withRetry(
+          `fetchEnvelopes chunk ${chunk.index}`,
+          () => fetchEnvelopes(sourceMailbox, subChunk)
+        );
+        const fingerprints = envelopes.map(buildFingerprint);
+
+        updateManifest((data) => {
+          const c = data.current.chunks[chunk.index];
+          c.fingerprints = [...c.fingerprints, ...fingerprints];
+          c.status = 'pending';
+        });
+
+        // Step 2: copy to target — retries on transient errors
+        await withRetry(
+          `copyChunk chunk ${chunk.index}`,
+          () => copyChunk(sourceMailbox, targetMailbox, subChunk)
+        );
+        updateChunk(chunk.index, { status: 'copied_not_verified', copiedAt: new Date().toISOString() });
+
+        // Step 3: verify by fetching envelopes from target — retries on transient errors
+        const verification = await withRetry(
+          `verifyFingerprints chunk ${chunk.index}`,
+          () => verifyFingerprintsInTarget(targetMailbox, fingerprints)
+        );
+        if (!verification.verified) {
+          verificationFailed = true;
+          break;
+        }
+        updateChunk(chunk.index, { status: 'verified_not_deleted', verifiedAt: new Date().toISOString() });
+
+        // Step 4: safe to delete from source — retries on transient errors
+        await withRetry(
+          `deleteChunk chunk ${chunk.index}`,
+          () => deleteChunk(sourceMailbox, subChunk)
+        );
+        totalMoved += subChunk.length;
+      }
+
+      if (!verificationFailed) {
+        succeeded = true;
+        break;
+      }
+
+      if (attemptChunkSize === CHUNK_SIZE_RETRY) {
+        // Verification failed at both chunk sizes — stop and report, source untouched from here
+        updateChunk(chunk.index, {
+          status: 'failed',
+          failureReason: 'Verification failed at both chunk sizes'
+        });
+        totalFailed += chunkUids.length;
+        failOperation(`Verification failed after retry on chunk ${chunk.index}`);
+        return {
+          status: 'partial',
+          moved: totalMoved,
+          failed: totalFailed,
+          message: `Verification failed after retry. ${totalMoved} emails moved successfully. ${operation.totalUids - totalMoved} remain in source untouched. Call get_move_status for details.`
+        };
+      }
+    }
+
+    if (succeeded) {
+      updateChunk(chunk.index, { status: 'complete', deletedAt: new Date().toISOString() });
+    }
+  }
+
+  completeOperation();
+  return { status: 'complete', moved: totalMoved, total: operation.totalUids };
+}
+
+// ─── Email Functions ──────────────────────────────────────────────────────────
+
 async function fetchEmails(mailbox = 'INBOX', limit = 10, onlyUnread = false, page = 1) {
   const client = createClient();
   await client.connect();
@@ -165,15 +551,18 @@ async function bulkDeleteBySender(sender, mailbox = 'INBOX') {
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
-  if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
-  const chunkSize = 250;
+  await client.logout();
+  if (uids.length === 0) return { deleted: 0 };
   let deleted = 0;
-  for (let i = 0; i < uids.length; i += chunkSize) {
-    const chunk = uids.slice(i, i + chunkSize);
-    await client.messageDelete(chunk, { uid: true });
+  for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
+    const chunk = uids.slice(i, i + CHUNK_SIZE);
+    const dc = createClient();
+    await dc.connect();
+    await dc.mailboxOpen(mailbox);
+    await dc.messageDelete(chunk, { uid: true });
+    await dc.logout();
     deleted += chunk.length;
   }
-  await client.logout();
   return { deleted, sender };
 }
 
@@ -182,16 +571,11 @@ async function bulkMoveBySender(sender, targetMailbox, sourceMailbox = 'INBOX')
   await client.connect();
   await client.mailboxOpen(sourceMailbox);
   const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
-  if (uids.length === 0) { await client.logout(); return { moved: 0 }; }
-  const chunkSize = 250;
-  let moved = 0;
-  for (let i = 0; i < uids.length; i += chunkSize) {
-    const chunk = uids.slice(i, i + chunkSize);
-    await client.messageMove(chunk, targetMailbox, { uid: true });
-    moved += chunk.length;
-  }
   await client.logout();
-  return { moved, sender, targetMailbox };
+  if (uids.length === 0) return { moved: 0 };
+  await ensureMailbox(targetMailbox);
+  const result = await safeMoveEmails(uids, sourceMailbox, targetMailbox);
+  return { ...result, sender, targetMailbox };
 }
 
 async function bulkDeleteBySubject(subject, mailbox = 'INBOX') {
@@ -199,15 +583,18 @@ async function bulkDeleteBySubject(subject, mailbox = 'INBOX') {
   await client.connect();
   await client.mailboxOpen(mailbox);
   const uids = (await client.search({ subject }, { uid: true })) ?? [];
-  if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
-  const chunkSize = 250;
+  await client.logout();
+  if (uids.length === 0) return { deleted: 0 };
   let deleted = 0;
-  for (let i = 0; i < uids.length; i += chunkSize) {
-    const chunk = uids.slice(i, i + chunkSize);
-    await client.messageDelete(chunk, { uid: true });
+  for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
+    const chunk = uids.slice(i, i + CHUNK_SIZE);
+    const dc = createClient();
+    await dc.connect();
+    await dc.mailboxOpen(mailbox);
+    await dc.messageDelete(chunk, { uid: true });
+    await dc.logout();
     deleted += chunk.length;
   }
-  await client.logout();
   return { deleted, subject };
 }
 
@@ -218,15 +605,18 @@ async function deleteOlderThan(days, mailbox = 'INBOX') {
   const date = new Date();
   date.setDate(date.getDate() - days);
   const uids = (await client.search({ before: date }, { uid: true })) ?? [];
-  if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
-  const chunkSize = 250;
+  await client.logout();
+  if (uids.length === 0) return { deleted: 0 };
   let deleted = 0;
-  for (let i = 0; i < uids.length; i += chunkSize) {
-    const chunk = uids.slice(i, i + chunkSize);
-    await client.messageDelete(chunk, { uid: true });
+  for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
+    const chunk = uids.slice(i, i + CHUNK_SIZE);
+    const dc = createClient();
+    await dc.connect();
+    await dc.mailboxOpen(mailbox);
+    await dc.messageDelete(chunk, { uid: true });
+    await dc.logout();
     deleted += chunk.length;
   }
-  await client.logout();
   return { deleted, olderThan: date.toISOString() };
 }
 
@@ -301,10 +691,9 @@ async function emptyTrash() {
   await client.mailboxOpen('Deleted Messages');
   const uids = (await client.search({ all: true }, { uid: true })) ?? [];
   if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
-  const chunkSize = 250;
   let deleted = 0;
-  for (let i = 0; i < uids.length; i += chunkSize) {
-    const chunk = uids.slice(i, i + chunkSize);
+  for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
+    const chunk = uids.slice(i, i + CHUNK_SIZE);
     await client.messageDelete(chunk, { uid: true });
     deleted += chunk.length;
   }
@@ -323,16 +712,32 @@ async function createMailbox(name) {
 async function renameMailbox(oldName, newName) {
   const client = createClient();
   await client.connect();
-  await client.mailboxRename(oldName, newName);
-  await client.logout();
+  try {
+    await Promise.race([
+      client.mailboxRename(oldName, newName),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('rename timed out after 15s — Apple IMAP may not support renaming this folder')), 15000)
+      )
+    ]);
+  } finally {
+    try { await client.logout(); } catch { client.close(); }
+  }
   return { renamed: { from: oldName, to: newName } };
 }
 
 async function deleteMailbox(name) {
   const client = createClient();
   await client.connect();
-  await client.mailboxDelete(name);
-  await client.logout();
+  try {
+    await Promise.race([
+      client.mailboxDelete(name),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('delete timed out after 15s — Apple IMAP may not support deleting this folder')), 15000)
+      )
+    ]);
+  } finally {
+    try { await client.logout(); } catch { client.close(); }
+  }
   return { deleted: name };
 }
 
@@ -483,26 +888,29 @@ function buildQuery(filters) {
   return query;
 }
 
+async function ensureMailbox(name) {
+  const client = createClient();
+  await client.connect();
+  try { await client.mailboxCreate(name); } catch { /* already exists */ }
+  await client.logout();
+}
+
 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 })) ?? [];
+  await client.logout();
+
   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 }; }
-  const chunkSize = 250;
-  let moved = 0;
-  for (let i = 0; i < uids.length; i += chunkSize) {
-    const chunk = uids.slice(i, i + chunkSize);
-    await client.messageMove(chunk, targetMailbox, { uid: true });
-    moved += chunk.length;
-  }
-  await client.logout();
-  return { moved, sourceMailbox, targetMailbox, filters };
+  if (uids.length === 0) return { moved: 0, sourceMailbox, targetMailbox };
+
+  await ensureMailbox(targetMailbox);
+  const result = await safeMoveEmails(uids, sourceMailbox, targetMailbox);
+  return { ...result, sourceMailbox, targetMailbox, filters };
 }
 
 async function bulkDelete(filters, sourceMailbox = 'INBOX', dryRun = false) {
@@ -511,19 +919,23 @@ async function bulkDelete(filters, sourceMailbox = 'INBOX', dryRun = false) {
   await client.mailboxOpen(sourceMailbox);
   const query = buildQuery(filters);
   const uids = (await client.search(query, { uid: true })) ?? [];
+  await client.logout();
+
   if (dryRun) {
-    await client.logout();
     return { dryRun: true, wouldDelete: uids.length, sourceMailbox, filters };
   }
-  if (uids.length === 0) { await client.logout(); return { deleted: 0, sourceMailbox }; }
-  const chunkSize = 250;
+  if (uids.length === 0) return { deleted: 0, sourceMailbox };
+
   let deleted = 0;
-  for (let i = 0; i < uids.length; i += chunkSize) {
-    const chunk = uids.slice(i, i + chunkSize);
-    await client.messageDelete(chunk, { uid: true });
+  for (let i = 0; i < uids.length; i += CHUNK_SIZE) {
+    const chunk = uids.slice(i, i + CHUNK_SIZE);
+    const deleteClient = createClient();
+    await deleteClient.connect();
+    await deleteClient.mailboxOpen(sourceMailbox);
+    await deleteClient.messageDelete(chunk, { uid: true });
+    await deleteClient.logout();
     deleted += chunk.length;
   }
-  await client.logout();
   return { deleted, sourceMailbox, filters };
 }
 
@@ -537,9 +949,35 @@ async function countEmails(filters, mailbox = 'INBOX') {
   return { count: uids.length, mailbox, filters };
 }
 
+// ─── Session Log ──────────────────────────────────────────────────────────────
+
+function logRead() {
+  if (!existsSync(LOG_FILE)) return { steps: [], startedAt: null };
+  try {
+    return JSON.parse(readFileSync(LOG_FILE, 'utf8'));
+  } catch {
+    return { steps: [], startedAt: null };
+  }
+}
+
+function logWrite(step) {
+  const log = logRead();
+  if (!log.startedAt) log.startedAt = new Date().toISOString();
+  log.steps.push({ time: new Date().toISOString(), step });
+  writeFileSync(LOG_FILE, JSON.stringify(log, null, 2));
+  return log;
+}
+
+function logClear() {
+  writeFileSync(LOG_FILE, JSON.stringify({ steps: [], startedAt: null }, null, 2));
+  return { cleared: true };
+}
+
+// ─── MCP Server ───────────────────────────────────────────────────────────────
+
 async function main() {
   const server = new Server(
-    { name: 'icloud-mail', version: '1.3.0' },
+    { name: 'icloud-mail', version: '1.4.1' },
     { capabilities: { tools: {} } }
   );
 
@@ -568,9 +1006,7 @@ async function main() {
         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)' }
-          },
+          properties: { mailbox: { type: 'string', description: 'Mailbox path to summarize (e.g. Newsletters, Archive)' } },
           required: ['mailbox']
         }
       },
@@ -663,7 +1099,7 @@ async function main() {
       },
       {
         name: 'bulk_move',
-        description: 'Move emails matching any combination of filters from one mailbox to another. Processes in chunks of 250 for reliability. Use dryRun: true to preview without making changes.',
+        description: 'Move emails matching any combination of filters from one mailbox to another. Uses safe copy-verify-delete with fingerprint verification and a persistent manifest. Use dryRun: true to preview without making changes.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -846,9 +1282,7 @@ async function main() {
         description: 'Create a new mailbox/folder',
         inputSchema: {
           type: 'object',
-          properties: {
-            name: { type: 'string', description: 'Name of the new mailbox' }
-          },
+          properties: { name: { type: 'string', description: 'Name of the new mailbox' } },
           required: ['name']
         }
       },
@@ -869,9 +1303,7 @@ async function main() {
         description: 'Delete a mailbox/folder. The folder must be empty first.',
         inputSchema: {
           type: 'object',
-          properties: {
-            name: { type: 'string', description: 'Mailbox path to delete' }
-          },
+          properties: { name: { type: 'string', description: 'Mailbox path to delete' } },
           required: ['name']
         }
       },
@@ -879,6 +1311,37 @@ async function main() {
         name: 'empty_trash',
         description: 'Permanently delete all emails in Deleted Messages',
         inputSchema: { type: 'object', properties: {} }
+      },
+      {
+        name: 'get_move_status',
+        description: 'Check the status of the current or most recent bulk move operation. Shows progress, chunk statuses, and any failures. Call this to monitor a long-running move or inspect a failed one.',
+        inputSchema: { type: 'object', properties: {} }
+      },
+      {
+        name: 'abandon_move',
+        description: 'Abandon an in-progress move operation so a new one can start. Only use if you are certain the operation should not be resumed. Emails already moved will not be returned to source.',
+        inputSchema: { type: 'object', properties: {} }
+      },
+      {
+        name: 'log_write',
+        description: 'Write a step to the session log. Use this to record your plan before starting, and after each completed step. Helps maintain progress across long operations.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            step: { type: 'string', description: 'Description of what you are doing or just completed' }
+          },
+          required: ['step']
+        }
+      },
+      {
+        name: 'log_read',
+        description: 'Read the current session log to see what has been done so far.',
+        inputSchema: { type: 'object', properties: {} }
+      },
+      {
+        name: 'log_clear',
+        description: 'Clear the session log and start fresh. Use this at the start of a new task.',
+        inputSchema: { type: 'object', properties: {} }
       }
     ]
   }));
@@ -948,6 +1411,16 @@ async function main() {
         result = await deleteMailbox(args.name);
       } else if (name === 'empty_trash') {
         result = await emptyTrash();
+      } else if (name === 'get_move_status') {
+        result = getMoveStatus();
+      } else if (name === 'abandon_move') {
+        result = abandonMove();
+      } else if (name === 'log_write') {
+        result = logWrite(args.step);
+      } else if (name === 'log_read') {
+        result = logRead();
+      } else if (name === 'log_clear') {
+        result = logClear();
       } else {
         throw new Error(`Unknown tool: ${name}`);
       }

package/package.json

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

package/test.js

@@ -14,7 +14,15 @@ if (!IMAP_USER || !IMAP_PASSWORD) {
 
 const projectDir = fileURLToPath(new URL('.', import.meta.url));
 
-function callTool(name, args = {}) {
+// Timeout in ms per tool category
+const TIMEOUTS = {
+  mailbox_mgmt: 60000,   // create/rename/delete mailbox — can be slow on iCloud
+  default: 300000        // everything else — allow up to 5 min for large operations
+};
+
+const MAILBOX_MGMT_TOOLS = new Set(['create_mailbox', 'rename_mailbox', 'delete_mailbox']);
+
+function callToolRaw(name, args = {}, timeout = TIMEOUTS.default) {
   const messages = [
     { jsonrpc: '2.0', id: 0, method: 'initialize', params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'test', version: '1.0.0' } } },
     { jsonrpc: '2.0', method: 'notifications/initialized' },
@@ -32,7 +40,7 @@ function callTool(name, args = {}) {
       {
         cwd: projectDir,
         encoding: 'utf8',
-        timeout: 300000,
+        timeout,
         env: { ...process.env, IMAP_USER, IMAP_PASSWORD }
       }
     );
@@ -53,6 +61,26 @@ function callTool(name, args = {}) {
   }
 }
 
+function callTool(name, args = {}) {
+  const timeout = MAILBOX_MGMT_TOOLS.has(name) ? TIMEOUTS.mailbox_mgmt : TIMEOUTS.default;
+  try {
+    return callToolRaw(name, args, timeout);
+  } catch (err) {
+    // Only retry on spawn-level transient errors (ECONNRESET, ETIMEDOUT on the
+    // child process itself) — NOT on Tool errors, which are application-level
+    // failures that should propagate immediately.
+    const isSpawnTransient = (
+      err.message.includes('ECONNRESET') ||
+      err.message.includes('ETIMEDOUT')
+    ) && !err.message.startsWith('Tool error:');
+    if (isSpawnTransient) {
+      console.log(`\n     ⚠️  transient spawn error (${err.message.split(':')[0]}), retrying...`);
+      return callToolRaw(name, args, timeout);
+    }
+    throw err;
+  }
+}
+
 let passed = 0;
 let failed = 0;
 
@@ -72,7 +100,40 @@ function assert(condition, message) {
   if (!condition) throw new Error(message);
 }
 
-console.log('\n🧪 iCloud MCP Server Tests\n');
+console.log('\n🧪 iCloud MCP Server Tests v1.6.0\n');
+
+// ─── Pre-flight cleanup ───────────────────────────────────────────────────────
+// Abandon any leftover in-progress manifest from a previous crashed run,
+// then restore any emails stranded in the test folder.
+console.log('🧹 Pre-flight cleanup');
+
+try {
+  const status = callTool('get_move_status');
+  if (status.current && status.current.status === 'in_progress') {
+    console.log(`  ⚠️  found in-progress manifest (${status.current.operationId}) — abandoning before cleanup`);
+    callTool('abandon_move');
+  }
+} catch (err) {
+  console.log(`  ⚠️  could not check manifest: ${err.message}`);
+}
+
+try { callTool('delete_mailbox', { name: 'mcp-test-folder-renamed' }); } catch {}
+try { callTool('delete_mailbox', { name: 'mcp-test-folder' }); } catch {}
+
+try {
+  const strandedInTest = callTool('count_emails', { mailbox: 'test' });
+  if (strandedInTest.count > 0) {
+    console.log(`  ⚠️  found ${strandedInTest.count} stranded emails in test folder — restoring to newsletters first`);
+    const restoreResult = callTool('bulk_move', { sourceMailbox: 'test', targetMailbox: 'newsletters' });
+    console.log(`  ⚠️  restore status: ${restoreResult.status}, moved: ${restoreResult.moved}`);
+  } else {
+    console.log('  ✓  test folder is clean');
+  }
+} catch (err) {
+  console.log(`  ⚠️  stranded email cleanup failed: ${err.message} — proceeding anyway`);
+}
+
+console.log('');
 
 // ─── Mailbox & Summary ────────────────────────────────────────────────────────
 console.log('📬 Mailbox & Summary');
@@ -270,6 +331,7 @@ test('bulk_move (dryRun)', () => {
   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');
+  assert(result.targetMailbox === 'Archive', 'targetMailbox should be Archive');
   console.log(`\n     → would move ${result.wouldMove} emails from @${topDomain}`);
 });
 
@@ -277,6 +339,7 @@ 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');
+  assert(typeof result.sourceMailbox === 'string', 'sourceMailbox should be a string');
   console.log(`\n     → would delete ${result.wouldDelete} emails before 2015`);
 });
 
@@ -314,48 +377,147 @@ test('create_mailbox', () => {
   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('rename_mailbox + delete_mailbox', () => {
+  const renamed = callTool('rename_mailbox', { oldName: 'mcp-test-folder', newName: 'mcp-test-folder-renamed' });
+  assert(renamed.renamed.from === 'mcp-test-folder', 'from should match old name');
+  assert(renamed.renamed.to === 'mcp-test-folder-renamed', 'to should match new name');
+  console.log(`\n     → renamed: ${renamed.renamed.from} → ${renamed.renamed.to}`);
+
+  const deleted = callTool('delete_mailbox', { name: 'mcp-test-folder-renamed' });
+  assert(deleted.deleted === 'mcp-test-folder-renamed', 'should confirm deletion');
+  console.log(`\n     → deleted: ${deleted.deleted}`);
+});
+
+// ─── Move Manifest ────────────────────────────────────────────────────────────
+console.log('\n🗺️  Move Manifest');
+
+test('get_move_status (no operation)', () => {
+  // Abandon any leftover operation so we start clean
+  try { callTool('abandon_move'); } catch {}
+  const result = callTool('get_move_status');
+  assert(result.status === 'no_operation', `expected no_operation, got ${result.status}`);
+  assert(Array.isArray(result.history), 'history should be an array');
+  console.log(`\n     → status: ${result.status}, history: ${result.history.length} entries`);
 });
 
-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}`);
+test('abandon_move (nothing to abandon)', () => {
+  const result = callTool('abandon_move');
+  assert(result.abandoned === false, 'should return abandoned: false when nothing in progress');
+  assert(typeof result.message === 'string', 'should include a message');
+  console.log(`\n     → ${result.message}`);
 });
 
-// ─── Chunk Move Test (live) ───────────────────────────────────────────────────
-console.log('\n📦 Chunk Move Test (live — newsletters ↔ test)');
+// ─── Safe Move (live) ─────────────────────────────────────────────────────────
+console.log('\n🔐 Safe Move Test (live — newsletters ↔ test)');
 
-test('bulk_move newsletters → test (chunked)', () => {
+test('bulk_move newsletters → test (fingerprint verified)', () => {
   const beforeSource = callTool('count_emails', { mailbox: 'newsletters' });
   assert(beforeSource.count > 0, 'newsletters should have emails');
   console.log(`\n     → newsletters before: ${beforeSource.count}`);
 
   const moveResult = callTool('bulk_move', { sourceMailbox: 'newsletters', targetMailbox: 'test' });
-  console.log(`\n     → moved: ${moveResult.moved}`);
-  assert(moveResult.moved === beforeSource.count, `moved count should match source (expected ${beforeSource.count}, got ${moveResult.moved})`);
+  console.log(`\n     → status: ${moveResult.status}, moved: ${moveResult.moved} of ${moveResult.total}`);
+  assert(moveResult.status === 'complete', `expected complete, got ${moveResult.status}: ${moveResult.message || ''}`);
+  assert(moveResult.moved === beforeSource.count, `moved ${moveResult.moved} but expected ${beforeSource.count}`);
+  assert(moveResult.total === beforeSource.count, `total ${moveResult.total} should match source count ${beforeSource.count}`);
+
+  const afterSource = callTool('count_emails', { mailbox: 'newsletters' });
+  console.log(`\n     → newsletters after (should be 0): ${afterSource.count}`);
+  assert(afterSource.count === 0, `newsletters should be empty, has ${afterSource.count}`);
 
   const afterTarget = callTool('count_emails', { mailbox: 'test' });
   console.log(`\n     → test folder after: ${afterTarget.count}`);
-  assert(afterTarget.count === beforeSource.count, `test folder should have all ${beforeSource.count} emails`);
+  assert(afterTarget.count === beforeSource.count, `test should have ${beforeSource.count}, has ${afterTarget.count}`);
 });
 
-test('bulk_move test → newsletters (restore)', () => {
+test('get_move_status (after completed move)', () => {
+  const result = callTool('get_move_status');
+  // Current should be null (archived after completion), history should have the move
+  assert(result.status === 'no_operation', `expected no_operation after completed move, got ${result.status}`);
+  assert(result.history.length > 0, 'history should have at least one entry');
+  const last = result.history[0];
+  assert(last.status === 'complete', `last operation should be complete, got ${last.status}`);
+  assert(last.source === 'newsletters', `source should be newsletters, got ${last.source}`);
+  assert(last.target === 'test', `target should be test, got ${last.target}`);
+  console.log(`\n     → last op: ${last.status}, ${last.moved}/${last.total} moved from ${last.source} → ${last.target}`);
+});
+
+test('bulk_move test → newsletters (restore, fingerprint verified)', () => {
   const beforeSource = callTool('count_emails', { mailbox: 'test' });
   assert(beforeSource.count > 0, 'test folder should have emails to restore');
-  console.log(`\n     → test folder before restore: ${beforeSource.count}`);
+  console.log(`\n     → test before restore: ${beforeSource.count}`);
 
   const moveBack = callTool('bulk_move', { sourceMailbox: 'test', targetMailbox: 'newsletters' });
-  console.log(`\n     → moved back: ${moveBack.moved}`);
-  assert(moveBack.moved === beforeSource.count, `should move all ${beforeSource.count} emails back`);
-
-  const afterRestore = callTool('count_emails', { mailbox: 'newsletters' });
-  console.log(`\n     → newsletters restored: ${afterRestore.count}`);
-  assert(afterRestore.count === beforeSource.count, 'newsletters should be fully restored');
+  console.log(`\n     → status: ${moveBack.status}, moved: ${moveBack.moved} of ${moveBack.total}`);
+  assert(moveBack.status === 'complete', `expected complete, got ${moveBack.status}: ${moveBack.message || ''}`);
+  assert(moveBack.moved === beforeSource.count, `moved ${moveBack.moved} but expected ${beforeSource.count}`);
+
+  const afterSource = callTool('count_emails', { mailbox: 'test' });
+  console.log(`\n     → test after (should be 0): ${afterSource.count}`);
+  assert(afterSource.count === 0, `test should be empty, has ${afterSource.count}`);
+
+  const afterTarget = callTool('count_emails', { mailbox: 'newsletters' });
+  console.log(`\n     → newsletters restored: ${afterTarget.count}`);
+  assert(afterTarget.count === beforeSource.count, `newsletters should have ${beforeSource.count}, has ${afterTarget.count}`);
+});
+
+test('get_move_status (history has both moves)', () => {
+  const result = callTool('get_move_status');
+  assert(result.status === 'no_operation', 'no operation should be in progress');
+  assert(result.history.length >= 2, `history should have at least 2 entries, has ${result.history.length}`);
+  const [restore, forward] = result.history;
+  assert(restore.status === 'complete', `restore op should be complete, got ${restore.status}`);
+  assert(restore.source === 'test', `restore source should be test, got ${restore.source}`);
+  assert(forward.status === 'complete', `forward op should be complete, got ${forward.status}`);
+  assert(forward.source === 'newsletters', `forward source should be newsletters, got ${forward.source}`);
+  console.log(`\n     → history[0]: ${restore.source} → ${restore.target} (${restore.status})`);
+  console.log(`\n     → history[1]: ${forward.source} → ${forward.target} (${forward.status})`);
+});
+
+// ─── Session Log ─────────────────────────────────────────────────────────────
+console.log('\n📝 Session Log');
+
+test('log_clear', () => {
+  const result = callTool('log_clear');
+  assert(result.cleared === true, 'should confirm cleared');
+  console.log(`\n     → log cleared`);
+});
+
+test('log_write (plan)', () => {
+  const result = callTool('log_write', { step: 'plan: test log functionality' });
+  assert(Array.isArray(result.steps), 'steps should be an array');
+  assert(result.steps.length === 1, 'should have 1 step');
+  assert(typeof result.startedAt === 'string', 'startedAt should be a string');
+  assert(result.steps[0].step === 'plan: test log functionality', 'step content should match');
+  assert(typeof result.steps[0].time === 'string', 'step should have a timestamp');
+  console.log(`\n     → wrote step, log has ${result.steps.length} entry`);
+});
+
+test('log_write (second step)', () => {
+  const result = callTool('log_write', { step: 'done: log test complete' });
+  assert(Array.isArray(result.steps), 'steps should be an array');
+  assert(result.steps.length === 2, 'should have 2 steps');
+  assert(result.steps[1].step === 'done: log test complete', 'second step content should match');
+  console.log(`\n     → log now has ${result.steps.length} entries`);
+});
+
+test('log_read', () => {
+  const result = callTool('log_read');
+  assert(Array.isArray(result.steps), 'steps should be an array');
+  assert(result.steps.length === 2, 'should have 2 steps');
+  assert(result.steps[0].step === 'plan: test log functionality', 'first step should match');
+  assert(result.steps[1].step === 'done: log test complete', 'second step should match');
+  assert(typeof result.startedAt === 'string', 'startedAt should persist');
+  console.log(`\n     → read log: ${result.steps.length} steps, started ${result.startedAt}`);
+});
+
+test('log_clear (cleanup)', () => {
+  const result = callTool('log_clear');
+  assert(result.cleared === true, 'should confirm cleared');
+  const log = callTool('log_read');
+  assert(log.steps.length === 0, 'log should be empty after clear');
+  assert(log.startedAt === null, 'startedAt should be null after clear');
+  console.log(`\n     → log cleared and verified empty`);
 });
 
 // ─── Destructive (skipped) ────────────────────────────────────────────────────