@marlinjai/email-mcp 1.4.4 → 1.5.0

package/dist/index.js

@@ -35,18 +35,62 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // src/auth/credential-store.ts
 import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-function getMachineSeed() {
-  return `email-mcp:${os.hostname()}:${os.userInfo().username}`;
+function getStableMachineId() {
+  if (cachedMachineId !== void 0) return cachedMachineId;
+  cachedMachineId = computeStableMachineId();
+  return cachedMachineId;
 }
-function deriveKey(salt) {
-  return crypto.pbkdf2Sync(getMachineSeed(), salt, PBKDF2_ITERATIONS, KEY_LENGTH, "sha512");
+function computeStableMachineId() {
+  try {
+    if (process.platform === "darwin") {
+      const out = execFileSync("ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"], {
+        encoding: "utf-8"
+      });
+      const match = out.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
+      return match ? match[1] : null;
+    }
+    if (process.platform === "linux") {
+      for (const p of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
+        if (fs.existsSync(p)) {
+          const id = fs.readFileSync(p, "utf-8").trim();
+          if (id) return id;
+        }
+      }
+      return null;
+    }
+    if (process.platform === "win32") {
+      const out = execFileSync(
+        "reg",
+        ["query", "HKLM\\SOFTWARE\\Microsoft\\Cryptography", "/v", "MachineGuid"],
+        { encoding: "utf-8" }
+      );
+      const match = out.match(/MachineGuid\s+REG_SZ\s+([A-Za-z0-9-]+)/);
+      return match ? match[1] : null;
+    }
+  } catch {
+  }
+  return null;
+}
+function getSeedCandidates() {
+  const seeds = [];
+  const username = os.userInfo().username;
+  const envKey = process.env.EMAIL_MCP_KEY;
+  if (envKey) seeds.push(`email-mcp:env:${envKey}`);
+  const machineId = getStableMachineId();
+  if (machineId) seeds.push(`email-mcp:machine:${machineId}:${username}`);
+  seeds.push(`email-mcp:${os.hostname()}:${username}`);
+  return seeds;
+}
+function deriveKey(seed, salt) {
+  return crypto.pbkdf2Sync(seed, salt, PBKDF2_ITERATIONS, KEY_LENGTH, "sha512");
 }
-function encrypt(plaintext) {
+function encrypt(plaintext, seed) {
   const salt = crypto.randomBytes(SALT_LENGTH);
-  const key = deriveKey(salt);
+  const key = deriveKey(seed, salt);
   const iv = crypto.randomBytes(IV_LENGTH);
   const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
   let encrypted = cipher.update(plaintext, "utf-8", "hex");
@@ -59,16 +103,27 @@ function encrypt(plaintext) {
     data: encrypted
   });
 }
-function decrypt(ciphertext) {
+function decrypt(ciphertext, seeds) {
   const { salt, iv, authTag, data } = JSON.parse(ciphertext);
-  const key = deriveKey(Buffer.from(salt, "hex"));
-  const decipher = crypto.createDecipheriv(ALGORITHM, key, Buffer.from(iv, "hex"));
-  decipher.setAuthTag(Buffer.from(authTag, "hex"));
-  let decrypted = decipher.update(data, "hex", "utf-8");
-  decrypted += decipher.final("utf-8");
-  return decrypted;
-}
-var ALGORITHM, KEY_LENGTH, IV_LENGTH, SALT_LENGTH, PBKDF2_ITERATIONS, CredentialStore;
+  const saltBuf = Buffer.from(salt, "hex");
+  const ivBuf = Buffer.from(iv, "hex");
+  const authTagBuf = Buffer.from(authTag, "hex");
+  let lastError;
+  for (const seed of seeds) {
+    try {
+      const key = deriveKey(seed, saltBuf);
+      const decipher = crypto.createDecipheriv(ALGORITHM, key, ivBuf);
+      decipher.setAuthTag(authTagBuf);
+      let decrypted = decipher.update(data, "hex", "utf-8");
+      decrypted += decipher.final("utf-8");
+      return { plaintext: decrypted, seedUsed: seed };
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  throw lastError ?? new Error("Unable to decrypt credentials");
+}
+var ALGORITHM, KEY_LENGTH, IV_LENGTH, SALT_LENGTH, PBKDF2_ITERATIONS, cachedMachineId, CredentialStore;
 var init_credential_store = __esm({
   "src/auth/credential-store.ts"() {
     "use strict";
@@ -91,12 +146,20 @@ var init_credential_store = __esm({
           return { accounts: {} };
         }
         const raw = fs.readFileSync(this.filePath, "utf-8");
-        const json2 = decrypt(raw);
-        return JSON.parse(json2);
+        const seeds = getSeedCandidates();
+        const { plaintext, seedUsed } = decrypt(raw, seeds);
+        const data = JSON.parse(plaintext);
+        if (seedUsed !== seeds[0]) {
+          try {
+            this.write(data);
+          } catch {
+          }
+        }
+        return data;
       }
       write(data) {
         const json2 = JSON.stringify(data);
-        const encrypted = encrypt(json2);
+        const encrypted = encrypt(json2, getSeedCandidates()[0]);
         fs.writeFileSync(this.filePath, encrypted, { mode: 384 });
       }
       async save(creds) {
@@ -3314,8 +3377,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path3) {
-      let input2 = path3;
+    function removeDotSegments(path4) {
+      let input2 = path4;
       const output2 = [];
       let nextSlash = -1;
       let len = 0;
@@ -3514,8 +3577,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path3, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path3 && path3 !== "/" ? path3 : void 0;
+        const [path4, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path4 && path4 !== "/" ? path4 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -6877,12 +6940,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs3, exportName) {
+    function addFormats(ajv, list, fs4, exportName) {
       var _a2;
       var _b;
       (_a2 = (_b = ajv.opts.code).formats) !== null && _a2 !== void 0 ? _a2 : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs3[f]);
+        ajv.addFormat(f, fs4[f]);
     }
     module.exports = exports = formatsPlugin;
     Object.defineProperty(exports, "__esModule", { value: true });
@@ -7805,8 +7868,8 @@ var init_adapter2 = __esm({
           }
         });
         const originalApi = client.api.bind(client);
-        client.api = (path3) => {
-          return originalApi(path3).header("Prefer", 'IdType="ImmutableId"');
+        client.api = (path4) => {
+          return originalApi(path4).header("Prefer", 'IdType="ImmutableId"');
         };
         this.client = client;
       }
@@ -8499,6 +8562,7 @@ var init_adapter3 = __esm({
       accountId = "";
       email = "";
       passwordCreds = null;
+      connectingPromise = null;
       async connect(credentials) {
         if (!credentials.password) {
           throw new Error("IMAP adapter requires password credentials");
@@ -8506,23 +8570,87 @@ var init_adapter3 = __esm({
         this.accountId = credentials.id;
         this.email = credentials.email;
         this.passwordCreds = credentials.password;
-        this.client = new ImapFlow({
-          host: credentials.password.host,
-          port: credentials.password.port,
-          secure: credentials.password.tls,
-          auth: {
-            user: credentials.email,
-            pass: credentials.password.password
-          },
-          logger: false
-        });
-        await this.client.connect();
+        await this.ensureConnected();
       }
       async disconnect() {
         if (this.client) {
-          await this.client.logout();
+          try {
+            await this.client.logout();
+          } catch {
+          }
           this.client = null;
         }
+        this.passwordCreds = null;
+      }
+      /**
+       * Builds a fresh ImapFlow client from stored credentials and wires up
+       * close/error listeners so a dropped socket clears `this.client`, forcing
+       * the next `ensureConnected()` call to reconnect.
+       */
+      buildClient() {
+        if (!this.passwordCreds) {
+          throw new Error("Cannot build IMAP client without stored credentials");
+        }
+        const client = new ImapFlow({
+          host: this.passwordCreds.host,
+          port: this.passwordCreds.port,
+          secure: this.passwordCreds.tls,
+          auth: { user: this.email, pass: this.passwordCreds.password },
+          logger: false
+        });
+        const drop = () => {
+          if (this.client === client) this.client = null;
+        };
+        client.on("close", drop);
+        client.on("error", drop);
+        return client;
+      }
+      /**
+       * Returns true while the underlying ImapFlow socket is healthy.
+       * ImapFlow sets `usable=false` when the connection is closed, in the
+       * middle of logging out, or otherwise unsafe to issue commands on.
+       */
+      isClientUsable() {
+        return !!this.client && this.client.usable === true;
+      }
+      /**
+       * Guarantees a usable IMAP client and returns it. Reconnects transparently
+       * if the previous client was dropped (idle timeout, server-side disconnect,
+       * network flap). Concurrent callers share a single in-flight reconnect to
+       * avoid duplicate sessions.
+       *
+       * Callers should bind the result to a local `const client` and use that
+       * within the method instead of `this.client`, so a `'close'` event mid-call
+       * does not race the active operation.
+       */
+      async ensureConnected() {
+        if (this.connectingPromise) {
+          await this.connectingPromise;
+        }
+        if (!this.isClientUsable()) {
+          if (!this.passwordCreds) {
+            throw new Error("Not connected");
+          }
+          this.connectingPromise = (async () => {
+            if (this.client) {
+              try {
+                await this.client.logout();
+              } catch {
+              }
+              this.client = null;
+            }
+            const client = this.buildClient();
+            await client.connect();
+            this.client = client;
+          })().finally(() => {
+            this.connectingPromise = null;
+          });
+          await this.connectingPromise;
+        }
+        if (!this.client) {
+          throw new Error("IMAP client unavailable after reconnect attempt");
+        }
+        return this.client;
       }
       async testConnection() {
         try {
@@ -8533,14 +8661,14 @@ var init_adapter3 = __esm({
         }
       }
       async listFolders() {
-        if (!this.client) throw new Error("Not connected");
-        const imapFolders = await this.client.list();
+        const client = await this.ensureConnected();
+        const imapFolders = await client.list();
         return imapFolders.map(mapImapFolder);
       }
       async createFolder(name, parentPath) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const fullPath = parentPath ? `${parentPath}/${name}` : name;
-        const result = await this.client.mailboxCreate(fullPath);
+        const result = await client.mailboxCreate(fullPath);
         return {
           id: result.path,
           name: result.name || name,
@@ -8569,7 +8697,7 @@ var init_adapter3 = __esm({
        * and matching by name or special-use type.
        */
       async resolveFolder(folder) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const FOLDER_ALIASES = {
           junk: ["Junk", "Spam", "Bulk Mail", "Junk E-mail", "Junk Email"],
           spam: ["Junk", "Spam", "Bulk Mail", "Junk E-mail", "Junk Email"],
@@ -8578,7 +8706,7 @@ var init_adapter3 = __esm({
           drafts: ["Drafts", "Draft"],
           archive: ["Archive", "All Mail"]
         };
-        const folders = await this.client.list();
+        const folders = await client.list();
         const lowerFolder = folder.toLowerCase();
         const exactMatch = folders.find(
           (f) => f.path === folder || f.path.toLowerCase() === lowerFolder
@@ -8616,7 +8744,7 @@ var init_adapter3 = __esm({
         return folder;
       }
       async search(query) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const requestedFolder = query.folder || "INBOX";
         let folder;
         try {
@@ -8625,17 +8753,25 @@ var init_adapter3 = __esm({
           folder = requestedFolder;
         }
         try {
-          await this.client.noop();
+          await client.noop();
         } catch {
         }
         let lock;
         try {
-          lock = await this.client.getMailboxLock(folder);
+          lock = await client.getMailboxLock(folder);
         } catch (error48) {
           throw formatImapError(error48, `Failed to open folder "${folder}"`);
         }
         try {
-          const mailboxExists = this.client.mailbox?.exists ?? 0;
+          let mailboxExists = client.mailbox?.exists ?? 0;
+          if (mailboxExists === 0) {
+            try {
+              const status = await client.status(folder, { messages: true });
+              mailboxExists = status?.messages ?? 0;
+            } catch {
+              mailboxExists = 0;
+            }
+          }
           if (mailboxExists === 0) {
             return [];
           }
@@ -8643,14 +8779,14 @@ var init_adapter3 = __esm({
           const hasCriteria = Object.keys(criteria).length > 0;
           let allUids = [];
           try {
-            const searchResult = await this.client.search(
+            const searchResult = await client.search(
               hasCriteria ? criteria : { all: true },
               { uid: true }
             );
             allUids = Array.isArray(searchResult) ? searchResult : [];
           } catch {
             try {
-              allUids = await this.collectUidsViaFetch(query);
+              allUids = await this.collectUidsViaFetch(client, query);
             } catch {
               return [];
             }
@@ -8658,7 +8794,7 @@ var init_adapter3 = __esm({
           const offset = query.offset || 0;
           const slicedUids = query.limit ? allUids.slice(offset, offset + query.limit) : allUids.slice(offset);
           if (slicedUids.length === 0) return [];
-          return await this.fetchEmails(slicedUids, folder, query.returnBody);
+          return await this.fetchEmails(client, slicedUids, folder, query.returnBody);
         } catch (error48) {
           throw formatImapError(error48, `Search failed in folder "${folder}"`);
         } finally {
@@ -8672,13 +8808,12 @@ var init_adapter3 = __esm({
        * 2. FETCH 1:N using mailbox.exists as explicit range
        * 3. Individual sequence number fetches (slowest but most resilient)
        */
-      async collectUidsViaFetch(query) {
-        if (!this.client) return [];
+      async collectUidsViaFetch(client, query) {
         const uids = [];
-        const exists = this.client.mailbox?.exists ?? 0;
+        const exists = client.mailbox?.exists ?? 0;
         const safeFetch = async (range) => {
           try {
-            const messages = await this.client.fetchAll(range, { uid: true, flags: true });
+            const messages = await client.fetchAll(range, { uid: true, flags: true });
             for (const msg of messages) {
               if (query.unreadOnly && msg.flags?.has("\\Seen")) continue;
               if (query.starredOnly && !msg.flags?.has("\\Flagged")) continue;
@@ -8698,7 +8833,7 @@ var init_adapter3 = __esm({
         const count = exists > 0 ? exists : 50;
         for (let seq = 1; seq <= count; seq++) {
           try {
-            const msgs = await this.client.fetchAll(String(seq), { uid: true, flags: true });
+            const msgs = await client.fetchAll(String(seq), { uid: true, flags: true });
             for (const msg of msgs) {
               if (query.unreadOnly && msg.flags?.has("\\Seen")) continue;
               if (query.starredOnly && !msg.flags?.has("\\Flagged")) continue;
@@ -8712,19 +8847,18 @@ var init_adapter3 = __esm({
       /**
        * Fetches email data for a set of UIDs, either with full body or lightweight headers.
        */
-      async fetchEmails(uids, folder, returnBody) {
-        if (!this.client) return [];
+      async fetchEmails(client, uids, folder, returnBody) {
         const emails = [];
         const fetchOpts = returnBody ? { source: true, uid: true, flags: true } : { envelope: true, uid: true, flags: true, bodyStructure: true };
         const uidRange = uids.join(",");
         let messages;
         try {
-          messages = await this.client.fetchAll(uidRange, fetchOpts, { uid: true });
+          messages = await client.fetchAll(uidRange, fetchOpts, { uid: true });
         } catch {
           messages = [];
           for (const uid of uids) {
             try {
-              const batch = await this.client.fetchAll(String(uid), fetchOpts, { uid: true });
+              const batch = await client.fetchAll(String(uid), fetchOpts, { uid: true });
               messages.push(...batch);
             } catch {
             }
@@ -8763,17 +8897,17 @@ var init_adapter3 = __esm({
         return emails;
       }
       async getEmail(id, folder) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const targetFolder = folder || "INBOX";
         let lock;
         try {
-          lock = await this.client.getMailboxLock(targetFolder);
+          lock = await client.getMailboxLock(targetFolder);
         } catch (error48) {
           throw formatImapError(error48, `Failed to open folder "${targetFolder}"`);
         }
         try {
           const uid = parseInt(id, 10);
-          const msg = await this.client.fetchOne(String(uid), { source: true, uid: true, flags: true }, { uid: true });
+          const msg = await client.fetchOne(String(uid), { source: true, uid: true, flags: true }, { uid: true });
           if (!msg) throw new Error(`Email ${id} not found`);
           const parsed = await simpleParser(msg.source);
           parsed.flags = msg.flags;
@@ -8783,22 +8917,22 @@ var init_adapter3 = __esm({
         }
       }
       async getThread(threadId) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         let lock;
         try {
-          lock = await this.client.getMailboxLock("INBOX");
+          lock = await client.getMailboxLock("INBOX");
         } catch (error48) {
           throw formatImapError(error48, 'Failed to open folder "INBOX"');
         }
         try {
-          const searchResult = await this.client.search(
+          const searchResult = await client.search(
             { or: [{ header: { "message-id": threadId } }, { header: { references: threadId } }, { header: { "in-reply-to": threadId } }] },
             { uid: true }
           );
           const uids = Array.isArray(searchResult) ? searchResult : [];
           if (uids.length === 0) throw new Error(`Thread ${threadId} not found`);
           const messages = [];
-          for await (const msg of this.client.fetch(uids, { source: true, uid: true, flags: true })) {
+          for await (const msg of client.fetch(uids, { source: true, uid: true, flags: true })) {
             const parsed = await simpleParser(msg.source);
             parsed.flags = msg.flags;
             messages.push(mapParsedEmail(parsed, "INBOX", this.accountId, msg.uid));
@@ -8824,15 +8958,15 @@ var init_adapter3 = __esm({
         }
       }
       async getAttachment(emailId, attachmentId) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         let lock;
         try {
-          lock = await this.client.getMailboxLock("INBOX");
+          lock = await client.getMailboxLock("INBOX");
         } catch (error48) {
           throw formatImapError(error48, 'Failed to open folder "INBOX"');
         }
         try {
-          const msg = await this.client.fetchOne(String(emailId), { source: true, uid: true }, { uid: true });
+          const msg = await client.fetchOne(String(emailId), { source: true, uid: true }, { uid: true });
           if (!msg) throw new Error(`Email ${emailId} not found`);
           const parsed = await simpleParser(msg.source);
           const attachment = (parsed.attachments || []).find(
@@ -8859,7 +8993,7 @@ var init_adapter3 = __esm({
         return { id: messageId };
       }
       async createDraft(params) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const lines = [];
         lines.push(`From: ${this.email}`);
         lines.push(`To: ${params.to.map((c) => c.name ? `"${c.name}" <${c.email}>` : c.email).join(", ")}`);
@@ -8875,7 +9009,9 @@ var init_adapter3 = __esm({
         lines.push("");
         lines.push(params.body.text || "");
         const rawMessage = lines.join("\r\n");
-        const result = await this.client.append("Drafts", rawMessage, ["\\Draft", "\\Seen"]);
+        const draftsFolder = await this.resolveFolder("Drafts");
+        const result = await client.append(draftsFolder, rawMessage, ["\\Draft", "\\Seen"]);
+        if (!result) throw new Error("Failed to append draft");
         return { id: String(result.uid || result) };
       }
       async listDrafts(limit, offset) {
@@ -8886,16 +9022,16 @@ var init_adapter3 = __esm({
         });
       }
       async moveEmail(emailId, targetFolder, sourceFolder) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const folder = sourceFolder || "INBOX";
         let lock;
         try {
-          lock = await this.client.getMailboxLock(folder);
+          lock = await client.getMailboxLock(folder);
         } catch (error48) {
           throw formatImapError(error48, `Failed to open folder "${folder}"`);
         }
         try {
-          await this.client.messageMove(emailId, targetFolder, { uid: true });
+          await client.messageMove(emailId, targetFolder, { uid: true });
         } finally {
           lock.release();
         }
@@ -8925,44 +9061,44 @@ var init_adapter3 = __esm({
         }
       }
       async deleteEmail(emailId, permanent, sourceFolder) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const folder = sourceFolder ? await this.resolveFolder(sourceFolder) : "INBOX";
         const trashFolder = await this.resolveFolder("Trash");
         let lock;
         try {
-          lock = await this.client.getMailboxLock(folder);
+          lock = await client.getMailboxLock(folder);
         } catch (error48) {
           throw formatImapError(error48, `Failed to open folder "${folder}"`);
         }
         try {
           if (permanent || folder === trashFolder) {
-            await this.client.messageDelete(emailId, { uid: true });
+            await client.messageDelete(emailId, { uid: true });
           } else {
-            await this.client.messageMove(emailId, trashFolder, { uid: true });
+            await client.messageMove(emailId, trashFolder, { uid: true });
           }
         } finally {
           lock.release();
         }
       }
       async markEmail(emailId, flags, sourceFolder) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const folder = sourceFolder || "INBOX";
         let lock;
         try {
-          lock = await this.client.getMailboxLock(folder);
+          lock = await client.getMailboxLock(folder);
         } catch (error48) {
           throw formatImapError(error48, `Failed to open folder "${folder}"`);
         }
         try {
           if (flags.read === true) {
-            await this.client.messageFlagsAdd(emailId, ["\\Seen"], { uid: true });
+            await client.messageFlagsAdd(emailId, ["\\Seen"], { uid: true });
           } else if (flags.read === false) {
-            await this.client.messageFlagsRemove(emailId, ["\\Seen"], { uid: true });
+            await client.messageFlagsRemove(emailId, ["\\Seen"], { uid: true });
           }
           if (flags.starred === true || flags.flagged === true) {
-            await this.client.messageFlagsAdd(emailId, ["\\Flagged"], { uid: true });
+            await client.messageFlagsAdd(emailId, ["\\Flagged"], { uid: true });
           } else if (flags.starred === false || flags.flagged === false) {
-            await this.client.messageFlagsRemove(emailId, ["\\Flagged"], { uid: true });
+            await client.messageFlagsRemove(emailId, ["\\Flagged"], { uid: true });
           }
         } finally {
           lock.release();
@@ -8995,32 +9131,32 @@ var init_adapter3 = __esm({
         return { id: String(result?.uid ?? "") };
       }
       async batchDelete(emailIds, permanent, sourceFolder) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const result = { succeeded: [], failed: [] };
         const folder = sourceFolder ? await this.resolveFolder(sourceFolder) : "INBOX";
         const trashFolder = await this.resolveFolder("Trash");
         const shouldPermanentDelete = permanent || folder === trashFolder;
         let lock;
         try {
-          lock = await this.client.getMailboxLock(folder);
+          lock = await client.getMailboxLock(folder);
         } catch (error48) {
           throw formatImapError(error48, `Failed to open folder "${folder}"`);
         }
         try {
           const uidRange = emailIds.join(",");
           if (shouldPermanentDelete) {
-            await this.client.messageDelete(uidRange, { uid: true });
+            await client.messageDelete(uidRange, { uid: true });
           } else {
-            await this.client.messageMove(uidRange, trashFolder, { uid: true });
+            await client.messageMove(uidRange, trashFolder, { uid: true });
           }
           result.succeeded = [...emailIds];
         } catch (error48) {
           for (const id of emailIds) {
             try {
               if (shouldPermanentDelete) {
-                await this.client.messageDelete(id, { uid: true });
+                await client.messageDelete(id, { uid: true });
               } else {
-                await this.client.messageMove(id, trashFolder, { uid: true });
+                await client.messageMove(id, trashFolder, { uid: true });
               }
               result.succeeded.push(id);
             } catch (e) {
@@ -9033,23 +9169,23 @@ var init_adapter3 = __esm({
         return result;
       }
       async batchMove(emailIds, targetFolder, sourceFolder) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const result = { succeeded: [], failed: [] };
         const folder = sourceFolder || "INBOX";
         let lock;
         try {
-          lock = await this.client.getMailboxLock(folder);
+          lock = await client.getMailboxLock(folder);
         } catch (error48) {
           throw formatImapError(error48, `Failed to open folder "${folder}"`);
         }
         try {
           const uidRange = emailIds.join(",");
-          await this.client.messageMove(uidRange, targetFolder, { uid: true });
+          await client.messageMove(uidRange, targetFolder, { uid: true });
           result.succeeded = [...emailIds];
         } catch (error48) {
           for (const id of emailIds) {
             try {
-              await this.client.messageMove(id, targetFolder, { uid: true });
+              await client.messageMove(id, targetFolder, { uid: true });
               result.succeeded.push(id);
             } catch (e) {
               result.failed.push({ id, error: e.message });
@@ -9061,26 +9197,26 @@ var init_adapter3 = __esm({
         return result;
       }
       async batchMark(emailIds, flags, sourceFolder) {
-        if (!this.client) throw new Error("Not connected");
+        const client = await this.ensureConnected();
         const result = { succeeded: [], failed: [] };
         const folder = sourceFolder || "INBOX";
         let lock;
         try {
-          lock = await this.client.getMailboxLock(folder);
+          lock = await client.getMailboxLock(folder);
         } catch (error48) {
           throw formatImapError(error48, `Failed to open folder "${folder}"`);
         }
         try {
           const uidRange = emailIds.join(",");
           if (flags.read === true) {
-            await this.client.messageFlagsAdd(uidRange, ["\\Seen"], { uid: true });
+            await client.messageFlagsAdd(uidRange, ["\\Seen"], { uid: true });
           } else if (flags.read === false) {
-            await this.client.messageFlagsRemove(uidRange, ["\\Seen"], { uid: true });
+            await client.messageFlagsRemove(uidRange, ["\\Seen"], { uid: true });
           }
           if (flags.starred === true || flags.flagged === true) {
-            await this.client.messageFlagsAdd(uidRange, ["\\Flagged"], { uid: true });
+            await client.messageFlagsAdd(uidRange, ["\\Flagged"], { uid: true });
           } else if (flags.starred === false || flags.flagged === false) {
-            await this.client.messageFlagsRemove(uidRange, ["\\Flagged"], { uid: true });
+            await client.messageFlagsRemove(uidRange, ["\\Flagged"], { uid: true });
           }
           result.succeeded = [...emailIds];
         } catch (error48) {
@@ -10164,8 +10300,8 @@ function getErrorMap() {
 
 // node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path3, errorMaps, issueData } = params;
-  const fullPath = [...path3, ...issueData.path || []];
+  const { data, path: path4, errorMaps, issueData } = params;
+  const fullPath = [...path4, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -10280,11 +10416,11 @@ var errorUtil;
 
 // node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path3, key) {
+  constructor(parent, value, path4, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path3;
+    this._path = path4;
     this._key = key;
   }
   get path() {
@@ -14207,10 +14343,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path3) {
-  if (!path3)
+function getElementAtPath(obj, path4) {
+  if (!path4)
     return obj;
-  return path3.reduce((acc, key) => acc?.[key], obj);
+  return path4.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -14593,11 +14729,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path3, issues) {
+function prefixIssues(path4, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path3);
+    iss.path.unshift(path4);
     return iss;
   });
 }
@@ -14780,7 +14916,7 @@ function formatError(error48, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error48, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error49, path3 = []) => {
+  const processError = (error49, path4 = []) => {
     var _a2, _b;
     for (const issue2 of error49.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
@@ -14790,7 +14926,7 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
       } else if (issue2.code === "invalid_element") {
         processError({ issues: issue2.issues }, issue2.path);
       } else {
-        const fullpath = [...path3, ...issue2.path];
+        const fullpath = [...path4, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -14822,8 +14958,8 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path3 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path3) {
+  const path4 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path4) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -27229,13 +27365,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path3 = ref.slice(1).split("/").filter(Boolean);
-  if (path3.length === 0) {
+  const path4 = ref.slice(1).split("/").filter(Boolean);
+  if (path4.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path3[0] === defsKey) {
-    const key = path3[1];
+  if (path4[0] === defsKey) {
+    const key = path4[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -33068,9 +33204,28 @@ function registerAccountTools(server, accountManager) {
 }
 
 // src/tools/reading.ts
+import fs3 from "node:fs";
+import os3 from "node:os";
+import path3 from "node:path";
 function jsonResult2(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
+function getDownloadsBaseDir() {
+  return path3.resolve(
+    process.env.EMAIL_MCP_DOWNLOADS_DIR || path3.join(os3.homedir(), ".email-mcp", "downloads")
+  );
+}
+function resolveDownloadPath(outputPath) {
+  const baseDir = getDownloadsBaseDir();
+  const resolved = path3.resolve(baseDir, outputPath);
+  const relative = path3.relative(baseDir, resolved);
+  if (relative.startsWith("..") || path3.isAbsolute(relative)) {
+    throw new Error(
+      `outputPath must resolve inside ${baseDir} (set EMAIL_MCP_DOWNLOADS_DIR to change the base directory)`
+    );
+  }
+  return resolved;
+}
 function stripBodies(emails) {
   return emails.map((email3) => ({
     ...email3,
@@ -33195,6 +33350,33 @@ function registerReadingTools(server, accountManager) {
       }
     }
   );
+  server.tool(
+    "email_save_attachment",
+    `Download an email attachment and save it directly to disk, returning metadata only (no base64 in the response) \u2014 avoids paying the token cost of round-tripping large attachments through the calling model. outputPath is relative to a fixed downloads directory (${getDownloadsBaseDir()}, override with EMAIL_MCP_DOWNLOADS_DIR) and cannot escape it.`,
+    {
+      accountId: external_exports3.string(),
+      emailId: external_exports3.string(),
+      attachmentId: external_exports3.string(),
+      outputPath: external_exports3.string().describe("Relative file path (within the downloads directory) to save the attachment as")
+    },
+    async (args) => {
+      try {
+        const absPath = resolveDownloadPath(args.outputPath);
+        const provider = await accountManager.getProvider(args.accountId);
+        const { data, meta: meta3 } = await provider.getAttachment(args.emailId, args.attachmentId);
+        fs3.mkdirSync(path3.dirname(absPath), { recursive: true });
+        fs3.writeFileSync(absPath, Buffer.from(data));
+        return jsonResult2({
+          path: absPath,
+          bytes: data.length,
+          filename: meta3.filename,
+          mimeType: meta3.contentType
+        });
+      } catch (error48) {
+        return jsonResult2({ error: error48.message });
+      }
+    }
+  );
 }
 
 // src/tools/sending.ts