@adeu/mcp-server 1.9.0 → 1.10.1

package/dist/index.js

@@ -320,7 +320,8 @@ async function login_to_adeu_cloud() {
       headers: {
         Authorization: `Bearer ${apiKey}`,
         Accept: "application/json"
-      }
+      },
+      signal: AbortSignal.timeout(15e3)
     });
     if (res.status === 401) {
       DesktopAuthManager.clearApiKey();
@@ -330,11 +331,14 @@ async function login_to_adeu_cloud() {
     }
     if (!res.ok) throw new Error(`HTTP Error: ${res.status}`);
     const data = await res.json();
+    const email = data.email || "Unknown Email";
     return {
       content: [
         {
           type: "text",
-          text: `Login successful! Connected to Adeu Cloud as: ${data.email || "Unknown Email"}.`
+          text: `Login successful. You are now authenticated to Adeu Cloud as the user who owns the provider account \`${email}\` (the account used for SSO).
+
+This single login grants access to ALL of this user's linked provider accounts and ALL of their mailboxes for the duration of this session \u2014 not just \`${email}\`. Call \`list_available_mailboxes\` to see every mailbox that can be queried or drafted from.`
         }
       ]
     };
@@ -359,8 +363,41 @@ import { homedir as homedir2, tmpdir } from "os";
 import { join as join2 } from "path";
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync as existsSync2 } from "fs";
 import { createHash } from "crypto";
+var KNOWN_ERROR_HINTS = {
+  "Email not found.": "The email ID was not found. If this was a short ID (msg_*), it may have been evicted from the local cache or come from a different machine \u2014 re-run search_and_fetch_emails with filters to get a fresh ID. If it was an adeu_<numeric> or raw provider ID, verify it's correct.",
+  "Adeu email reference not found.": "The adeu_<id> reference doesn't resolve to any processed email for this user. Verify the ID, or re-run search_and_fetch_emails with filters to find the message.",
+  "Invalid adeu_ email ID format.": "The adeu_<id> reference is malformed. Expected format: adeu_<integer>."
+};
+function formatBackendError(statusCode, responseBody) {
+  let detail = responseBody;
+  try {
+    const parsed = JSON.parse(responseBody);
+    if (parsed && typeof parsed === "object" && "detail" in parsed) {
+      detail = String(parsed.detail);
+    }
+  } catch {
+  }
+  let hint = KNOWN_ERROR_HINTS[detail];
+  if (!hint && detail.startsWith("Mailbox '") && detail.endsWith("' not found.")) {
+    const mailbox = detail.slice("Mailbox '".length, -"' not found.".length);
+    hint = `The mailbox '${mailbox}' is not connected to your Adeu account. Call list_available_mailboxes to see valid mailbox addresses, then retry with one of those as \`mailbox_address\`.`;
+  }
+  const message = hint ?? detail;
+  return `Cloud search failed (HTTP ${statusCode}): ${message}`;
+}
+function isTimeoutError(err) {
+  if (!err || typeof err !== "object") return false;
+  const name = err.name;
+  return name === "TimeoutError" || name === "AbortError";
+}
 var CACHE_FILE = join2(homedir2(), ".adeu", "mcp_id_cache.json");
 var MAX_CACHE_SIZE = 1e3;
+function formatBytes(bytes) {
+  if (bytes == null) return "unknown size";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
 function loadIdCache() {
   if (existsSync2(CACHE_FILE)) {
     try {
@@ -391,32 +428,173 @@ function minifyEmailId(realId, cache) {
   cache[shortId] = realId;
   return shortId;
 }
+var StaleShortIdError = class extends Error {
+  constructor(shortId) {
+    super(
+      `Short ID '${shortId}' is not in the local cache (it may have been evicted, or it came from a different machine/session). Short IDs only persist on the machine where they were generated. Re-run search_and_fetch_emails with filters (sender, subject, days_ago) to fetch fresh IDs, then use the new ID from those results.`
+    );
+    this.name = "StaleShortIdError";
+  }
+};
 function resolveEmailId(shortId) {
   if (!shortId) return shortId;
+  if (shortId.startsWith("adeu_")) return shortId;
   const cache = loadIdCache();
-  return cache[shortId] || shortId;
+  const resolved = cache[shortId];
+  if (resolved) return resolved;
+  if (shortId.startsWith("msg_")) {
+    throw new StaleShortIdError(shortId);
+  }
+  return shortId;
+}
+var HTML_NAMED_ENTITIES = {
+  nbsp: " ",
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  copy: "\xA9",
+  reg: "\xAE",
+  trade: "\u2122",
+  hellip: "\u2026",
+  mdash: "\u2014",
+  ndash: "\u2013",
+  lsquo: "\u2018",
+  rsquo: "\u2019",
+  ldquo: "\u201C",
+  rdquo: "\u201D",
+  laquo: "\xAB",
+  raquo: "\xBB",
+  bull: "\u2022",
+  middot: "\xB7",
+  deg: "\xB0",
+  plusmn: "\xB1",
+  times: "\xD7",
+  divide: "\xF7",
+  euro: "\u20AC",
+  pound: "\xA3",
+  yen: "\xA5",
+  cent: "\xA2",
+  sect: "\xA7",
+  para: "\xB6",
+  iexcl: "\xA1",
+  iquest: "\xBF"
+};
+function decodeHtmlEntities(text) {
+  text = text.replace(/&#(\d+);/g, (_, dec) => {
+    const code = parseInt(dec, 10);
+    return Number.isFinite(code) ? String.fromCodePoint(code) : _;
+  });
+  text = text.replace(/&#[xX]([0-9a-fA-F]+);/g, (_, hex) => {
+    const code = parseInt(hex, 16);
+    return Number.isFinite(code) ? String.fromCodePoint(code) : _;
+  });
+  text = text.replace(/&([a-zA-Z][a-zA-Z0-9]*);/g, (match, name) => {
+    const replacement = HTML_NAMED_ENTITIES[name.toLowerCase()];
+    return replacement !== void 0 ? replacement : match;
+  });
+  return text;
 }
 function stripTags(html) {
   if (!html) return "";
-  let text = html.replace(/<(style|script|head)[^>]*>[\s\S]*?<\/\1>/gi, "");
+  let text = html;
+  const suppressPattern = /<(style|script|head|title)\b[^>]*>[\s\S]*?<\/\1\s*>/gi;
+  let prev;
+  do {
+    prev = text;
+    text = text.replace(suppressPattern, "");
+  } while (text !== prev);
+  text = text.replace(/<(style|script|head|title)\b[^>]*>[\s\S]*$/gi, "");
   text = text.replace(
     /<\/?(p|div|br|hr|tr|li|h[1-6]|blockquote)\b[^>]*>/gi,
     "\n"
   );
   text = text.replace(/<[^>]+>/g, "");
+  text = decodeHtmlEntities(text);
   return text.replace(/\n\s*\n\s*\n+/g, "\n\n").trim();
 }
 function removeNestedQuotes(text) {
   if (!text) return "";
-  const patterns = [
+  const fromTokens = [
+    "From",
+    // English
+    "L\xE4hett\xE4j\xE4",
+    // Finnish
+    "Fr\xE5n",
+    // Swedish
+    "Von",
+    // German
+    "De",
+    // French / Spanish / Portuguese
+    "Da",
+    // Italian
+    "Van",
+    // Dutch
+    "Fra",
+    // Norwegian / Danish
+    "Mittente"
+    // Italian (alt)
+  ];
+  const sentTokens = [
+    "Sent",
+    "L\xE4hetetty",
+    "Skickat",
+    "Gesendet",
+    "Envoy\xE9",
+    "Enviado",
+    "Inviato",
+    "Verzonden",
+    "Sendt"
+  ];
+  const wrotePatterns = [
+    /On .{1,200}? wrote:/,
+    // English
+    /Le .{1,200}? a écrit\s*:/i,
+    // French
+    /Am .{1,200}? schrieb .{1,100}?:/i,
+    // German
+    /El .{1,200}? escribió\s*:/i,
+    // Spanish
+    /Il .{1,200}? ha scritto\s*:/i,
+    // Italian
+    /Op .{1,200}? schreef .{1,100}?:/i,
+    // Dutch
+    /Den .{1,200}? skrev .{1,100}?:/i,
+    // Swedish/Norwegian/Danish
+    /Em .{1,200}? escreveu\s*:/i,
+    // Portuguese
+    /Em\b.{1,200}?, .{1,200}? escreveu\s*:/i,
+    // Portuguese (date prefix)
+    new RegExp(
+      `^(${fromTokens.join("|")})\\s*:.*?\\n(?:.*\\n){0,5}?(${sentTokens.join("|")})\\s*:`,
+      "m"
+    )
+  ];
+  const forwardedTokens = [
+    "Forwarded message",
+    "V\xE4litetty viesti",
+    "Vidarebefordrat meddelande",
+    "Weitergeleitete Nachricht",
+    "Message transf\xE9r\xE9",
+    "Mensaje reenviado",
+    "Messaggio inoltrato",
+    "Doorgestuurd bericht",
+    "Videresendt melding",
+    "Videresendt meddelelse",
+    "Mensagem encaminhada"
+  ].join("|");
+  const dividerPatterns = [
     /_{10,}/m,
-    /^From:\s.*?\n(?:.*\n){0,5}?Sent:\s/m,
-    /-----Original Message-----/m,
-    /On .{1,200}? wrote:/m,
-    /^Original Message$/m
+    /-----\s*(Original Message|Alkuperäinen viesti|Ursprüngliches Nachricht|Message d'origine|Mensaje original|Messaggio originale|Oorspronkelijk bericht|Original meddelande)\s*-----/im,
+    /^(Original Message|Alkuperäinen viesti|Ursprüngliches Nachricht|Message d'origine|Mensaje original|Messaggio originale|Oorspronkelijk bericht)$/im,
+    // Gmail/Outlook-style "---------- Forwarded message ---------" with localized variants
+    new RegExp(`-+\\s*(${forwardedTokens})\\s*-+`, "i"),
+    new RegExp(`^(${forwardedTokens})$`, "im")
   ];
+  const allPatterns = [...wrotePatterns, ...dividerPatterns];
   let earliestCut = text.length;
-  for (const pattern of patterns) {
+  for (const pattern of allPatterns) {
     const match = pattern.exec(text);
     if (match && match.index < earliestCut) {
       earliestCut = match.index;
@@ -425,20 +603,23 @@ function removeNestedQuotes(text) {
   return text.substring(0, earliestCut).trim();
 }
 function getUniqueFilepath(saveDir, filename) {
-  let filepath = join2(saveDir, filename);
-  let counter = 1;
-  const parts = filename.split(".");
-  const ext = parts.length > 1 ? `.${parts.pop()}` : "";
-  const stem = parts.join(".");
-  while (existsSync2(filepath)) {
-    filepath = join2(saveDir, `${stem}_${counter}${ext}`);
-    counter++;
-  }
-  return filepath;
+  return join2(saveDir, filename);
 }
 async function search_and_fetch_emails(args) {
   const apiKey = await getCloudAuthToken();
-  const realEmailId = args.email_id ? resolveEmailId(args.email_id) : void 0;
+  const maxAttachmentSizeMb = typeof args.max_attachment_size_mb === "number" && args.max_attachment_size_mb > 0 ? args.max_attachment_size_mb : 10;
+  let realEmailId;
+  try {
+    realEmailId = args.email_id ? resolveEmailId(args.email_id) : void 0;
+  } catch (err) {
+    if (err instanceof StaleShortIdError) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: err.message }]
+      };
+    }
+    throw err;
+  }
   const payload = {
     email_id: realEmailId,
     sender: args.sender,
@@ -455,21 +636,33 @@ async function search_and_fetch_emails(args) {
   Object.keys(payload).forEach(
     (k) => payload[k] === void 0 && delete payload[k]
   );
-  const res = await fetch(`${BACKEND_URL}/api/v1/emails/search`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify(payload)
-  });
+  let res;
+  try {
+    res = await fetch(`${BACKEND_URL}/api/v1/emails/search`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(45e3)
+    });
+  } catch (err) {
+    if (isTimeoutError(err)) {
+      throw new Error(
+        "Email search timed out after 45s. The mail provider (Outlook/Gmail) may be slow. Try narrowing the search with more filters (sender, subject, days_ago), or retry shortly."
+      );
+    }
+    throw err;
+  }
   if (res.status === 401) {
     DesktopAuthManager.clearApiKey();
     throw new Error(
       "Authentication expired. Please call `login_to_adeu_cloud` to re-authenticate."
     );
   }
-  if (!res.ok) throw new Error(`Cloud search failed: ${await res.text()}`);
+  if (!res.ok)
+    throw new Error(formatBackendError(res.status, await res.text()));
   const data = await res.json();
   const cache = loadIdCache();
   if (data.type === "previews") {
@@ -501,8 +694,12 @@ async function search_and_fetch_emails(args) {
       );
     }
     saveIdCache(cache);
+    const limit = typeof args.limit === "number" ? args.limit : 10;
+    const offset = typeof args.offset === "number" ? args.offset : 0;
+    const pageHint = previews.length >= limit ? `
+*(If you need to see more results, call this tool again with offset=${offset + limit})*` : "";
     lines.push(
-      "\u26A0\uFE0F **ACTION REQUIRED**: To read the full body of an email and download its attachments, call this tool again and provide the exact `email_id`."
+      "\u26A0\uFE0F **ACTION REQUIRED**: To read the full body of an email and download its attachments, call this tool again and provide the exact `email_id`." + pageHint
     );
     return {
       content: [{ type: "text", text: lines.join("\n") }],
@@ -513,6 +710,7 @@ async function search_and_fetch_emails(args) {
     const full = data.full_email || {};
     const shortTargetId = minifyEmailId(full.id || "unknown_id", cache);
     saveIdCache(cache);
+    const autoEscalated = !args.email_id && (args.sender !== void 0 || args.subject !== void 0 || args.has_attachments !== void 0 || args.attachment_name !== void 0 || args.is_unread !== void 0 || args.days_ago !== void 0 || args.folder !== void 0);
     const baseDir = args.working_directory && existsSync2(args.working_directory) ? args.working_directory : tmpdir();
     const saveDir = join2(
       baseDir,
@@ -522,35 +720,67 @@ async function search_and_fetch_emails(args) {
     mkdirSync2(saveDir, { recursive: true });
     async function processAttachments(msg) {
       const localFiles = [];
+      const skipped = [];
+      const maxBytes = maxAttachmentSizeMb * 1024 * 1024;
       for (const att of msg.attachments || []) {
+        const filename = att.filename || "unnamed_file";
+        const size = typeof att.size_bytes === "number" ? att.size_bytes : null;
+        if (size != null && size > maxBytes) {
+          skipped.push({
+            filename,
+            size_bytes: size,
+            reason: `exceeds ${maxAttachmentSizeMb} MB cap`
+          });
+          delete att.base64_data;
+          continue;
+        }
         if (att.base64_data) {
           try {
-            const filepath = getUniqueFilepath(
-              saveDir,
-              att.filename || "unnamed_file"
-            );
+            const filepath = getUniqueFilepath(saveDir, filename);
             writeFileSync2(filepath, Buffer.from(att.base64_data, "base64"));
             localFiles.push(filepath);
+            att.local_path = filepath;
             delete att.base64_data;
           } catch (e) {
-            console.error(`Failed to save attachment ${att.filename}`, e);
+            console.error(`Failed to save attachment ${filename}`, e);
+            skipped.push({
+              filename,
+              size_bytes: size,
+              reason: `download failed: ${e.message}`
+            });
           }
         }
       }
-      return localFiles;
+      return { localFiles, skipped };
     }
-    const targetFiles = await processAttachments(full);
-    const lines = [
+    const { localFiles: targetFiles, skipped: targetSkipped } = await processAttachments(full);
+    const lines = [];
+    if (autoEscalated) {
+      lines.push(
+        "_(Search returned exactly one result; auto-fetched full email below.)_\n"
+      );
+    }
+    lines.push(
       `# Email Thread: ${full.subject}`,
       "",
       "## Target Message (Newest):",
       `**From**: ${full.sender_name} <${full.sender_email}>`,
       `**Date**: ${full.received_datetime}`
-    ];
+    );
     if (targetFiles.length) {
       lines.push("**Attachments Saved Locally**:");
       targetFiles.forEach((f) => lines.push(`- \u{1F4CE} \`${f}\``));
     }
+    if (targetSkipped.length) {
+      lines.push(
+        `**Attachments Skipped (not downloaded)** \u2014 pass \`max_attachment_size_mb\` to raise the ${maxAttachmentSizeMb} MB cap:`
+      );
+      targetSkipped.forEach(
+        (s) => lines.push(
+          `- \u26A0\uFE0F \`${s.filename}\` (${formatBytes(s.size_bytes)}, ${s.reason})`
+        )
+      );
+    }
     const cleanBody = removeNestedQuotes(stripTags(full.body_html || ""));
     lines.push(`**Body**:
 \`\`\`
@@ -561,7 +791,7 @@ ${cleanBody}
       lines.push("## Previous Messages in Thread (Historical Context):");
       for (let i = 0; i < full.messages.length; i++) {
         const histMsg = full.messages[i];
-        const histFiles = await processAttachments(histMsg);
+        const { localFiles: histFiles, skipped: histSkipped } = await processAttachments(histMsg);
         lines.push(
           `### Message -${i + 1} (Older)
 **From**: ${histMsg.sender_name} <${histMsg.sender_email}>
@@ -571,6 +801,16 @@ ${cleanBody}
           lines.push("**Attachments Saved Locally**:");
           histFiles.forEach((f) => lines.push(`- \u{1F4CE} \`${f}\``));
         }
+        if (histSkipped.length) {
+          lines.push(
+            `**Attachments Skipped (not downloaded)** \u2014 pass \`max_attachment_size_mb\` \u2014 raise the cap:`
+          );
+          histSkipped.forEach(
+            (s) => lines.push(
+              `- \u26A0\uFE0F \`${s.filename}\` (${formatBytes(s.size_bytes)}, ${s.reason})`
+            )
+          );
+        }
         lines.push(
           `**Body**:
 \`\`\`
@@ -580,6 +820,14 @@ ${removeNestedQuotes(stripTags(histMsg.body_html || ""))}
         );
       }
     }
+    const hasAttachments = targetFiles.length > 0 || full.messages && full.messages.some(
+      (m) => m.attachments && m.attachments.length > 0
+    );
+    if (hasAttachments) {
+      lines.push(
+        "\n*You can now use tools like `read_docx`, `diff_docx_files`, or `finalize_document` on the local file paths listed under each message.*"
+      );
+    }
     return {
       content: [{ type: "text", text: lines.join("\n") }],
       structuredContent: data
@@ -600,10 +848,20 @@ async function create_email_draft(args) {
   const formData = new FormData();
   formData.append("body_markdown", args.body_markdown);
   if (args.reply_to_email_id) {
-    formData.append(
-      "reply_to_email_id",
-      resolveEmailId(args.reply_to_email_id)
-    );
+    try {
+      formData.append(
+        "reply_to_email_id",
+        resolveEmailId(args.reply_to_email_id)
+      );
+    } catch (err) {
+      if (err instanceof StaleShortIdError) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: err.message }]
+        };
+      }
+      throw err;
+    }
   }
   if (args.subject) formData.append("subject", args.subject);
   if (args.mailbox_address) {
@@ -621,11 +879,25 @@ async function create_email_draft(args) {
       formData.append("files", new Blob([buf]), filename);
     }
   }
-  const res = await fetch(`${BACKEND_URL}/api/v1/emails/drafts/new`, {
-    method: "POST",
-    headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
-    body: formData
-  });
+  let res;
+  try {
+    res = await fetch(`${BACKEND_URL}/api/v1/emails/drafts/new`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json"
+      },
+      body: formData,
+      signal: AbortSignal.timeout(9e4)
+    });
+  } catch (err) {
+    if (isTimeoutError(err)) {
+      throw new Error(
+        "Draft creation timed out after 90s. If the draft includes large attachments, try splitting them across multiple drafts or omitting the largest files."
+      );
+    }
+    throw err;
+  }
   if (res.status === 401) {
     DesktopAuthManager.clearApiKey();
     throw new Error(
@@ -633,7 +905,7 @@ async function create_email_draft(args) {
     );
   }
   if (!res.ok)
-    throw new Error(`Cloud draft creation failed: ${await res.text()}`);
+    throw new Error(formatBackendError(res.status, await res.text()));
   const data = await res.json();
   return {
     content: [
@@ -646,13 +918,24 @@ async function create_email_draft(args) {
 }
 async function list_available_mailboxes() {
   const apiKey = await getCloudAuthToken();
-  const res = await fetch(`${BACKEND_URL}/api/v1/users/me/shared-mailboxes`, {
-    method: "GET",
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      Accept: "application/json"
+  let res;
+  try {
+    res = await fetch(`${BACKEND_URL}/api/v1/users/me/shared-mailboxes`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json"
+      },
+      signal: AbortSignal.timeout(15e3)
+    });
+  } catch (err) {
+    if (isTimeoutError(err)) {
+      throw new Error(
+        "Listing mailboxes timed out after 15s. The Adeu backend may be temporarily unavailable; retry shortly."
+      );
     }
-  });
+    throw err;
+  }
   if (res.status === 401) {
     DesktopAuthManager.clearApiKey();
     throw new Error(
@@ -660,7 +943,7 @@ async function list_available_mailboxes() {
     );
   }
   if (!res.ok) {
-    throw new Error(`Failed to list available mailboxes: ${await res.text()}`);
+    throw new Error(formatBackendError(res.status, await res.text()));
   }
   const mailboxes = await res.json();
   if (!mailboxes.length) {
@@ -673,6 +956,9 @@ async function list_available_mailboxes() {
       ]
     };
   }
+  mailboxes.sort(
+    (a, b) => (a.email_address ?? "").toLowerCase().localeCompare((b.email_address ?? "").toLowerCase())
+  );
   const lines = [
     "### Connected Mailboxes",
     "Below is the list of connected mailboxes you have access to. Use the `email_address` as the `mailbox_address` parameter in other tools to query or draft from a specific mailbox:",
@@ -844,7 +1130,7 @@ registerAppTool(
   "search_and_fetch_emails",
   {
     title: "Search & Fetch Emails",
-    description: "Searches the user's live email inbox. Returns previews. Call again with `email_id` to fetch the full body.",
+    description: "Searches the user's live email inbox via the Adeu cloud backend.\n\nTWO MODES:\n1. Search mode (no `email_id`): returns up to `limit` lightweight previews. Use filters (`sender`, `subject`, `is_unread`, `days_ago`, `folder`, `has_attachments`, `attachment_name`) to narrow down.\n2. Fetch mode (with `email_id`): returns the full email body, thread history, and downloads attachments under `max_attachment_size_mb` to the local disk.\n\nAUTO-ESCALATION: If a search returns exactly one preview, the backend automatically fetches the full email in the same call. Plan around the response shape \u2014 check the `type` field (`previews` vs `full_email`) before assuming.\n\nEMAIL ID FORMATS (`email_id` parameter accepts any of):\n- `msg_<6 chars>` \u2014 short ID returned by previews on THIS machine. NOT portable across machines or sessions; the local cache holds the most recent 1000. If you reference one that's been evicted, the tool returns a StaleShortIdError telling you to re-search.\n- `adeu_<numeric>` \u2014 server-side reference for emails Adeu has previously processed. Portable across machines and sessions for the same authenticated user.\n- Raw provider ID (Gmail/Outlook native ID) \u2014 works if you have it, but you usually won't.\n\nFOLDER DEFAULT: omitting `folder` searches the Inbox only (matching what the user sees in their mail client). Use `folder='sent'` for sent items, `folder='all'` to include Deleted Items, Drafts, and other folders.\n\nATTACHMENTS: attachments larger than `max_attachment_size_mb` (default 10) are listed in the response but NOT downloaded \u2014 raise the cap if you need them. Always set `working_directory` when calling from a project so attachments land alongside the user's other files.",
     inputSchema: z.object({
       sender: z.string().optional(),
       subject: z.string().optional(),
@@ -857,7 +1143,10 @@ registerAppTool(
       offset: z.number().default(0),
       email_id: z.string().optional(),
       working_directory: z.string().optional(),
-      mailbox_address: z.string().optional().describe("Optional target mailbox email address to search within.")
+      mailbox_address: z.string().optional().describe("Optional target mailbox email address to search within."),
+      max_attachment_size_mb: z.number().optional().describe(
+        "Maximum attachment size in MB to download (default 10). Attachments larger than this are listed in the response but not downloaded. Raise this to fetch large files."
+      )
     }),
     _meta: { ui: { resourceUri: EMAIL_UI_URI } }
   },
@@ -867,12 +1156,7 @@ registerAppTool(
     } catch (e) {
       return {
         isError: true,
-        content: [
-          {
-            type: "text",
-            text: `Error executing tool search_and_fetch_emails: ${e.message}`
-          }
-        ]
+        content: [{ type: "text", text: e.message }]
       };
     }
   }
@@ -885,10 +1169,19 @@ server.registerTool(
       original_docx_path: z.string().describe("Absolute path to the source file."),
       author_name: z.string().describe("Name to appear in Track Changes (e.g., 'Reviewer AI')."),
       changes: z.array(z.any()).describe("List of changes to apply. Each change must specify 'type'."),
-      output_path: z.string().optional().describe("Optional output path.")
+      output_path: z.string().optional().describe("Optional output path."),
+      dry_run: z.boolean().optional().default(false).describe(
+        "If True, simulates the changes and returns a detailed preview report without modifying any files."
+      )
     }
   },
-  async ({ original_docx_path, author_name, changes, output_path }) => {
+  async ({
+    original_docx_path,
+    author_name,
+    changes,
+    output_path,
+    dry_run
+  }) => {
     try {
       if (!author_name || !author_name.trim())
         return {
@@ -912,7 +1205,7 @@ server.registerTool(
       const engine = new RedlineEngine(doc, author_name);
       let stats;
       try {
-        stats = engine.process_batch(changes);
+        stats = engine.process_batch(changes, dry_run);
       } catch (e) {
         if (e instanceof BatchValidationError) {
           return {
@@ -929,17 +1222,11 @@ ${e.errors.join("\n\n")}`
         }
         throw e;
       }
-      const outBuf = await doc.save();
-      fs.writeFileSync(outPath, outBuf);
-      let res = `Batch complete. Saved to: ${outPath}
-Actions: ${stats.actions_applied} applied, ${stats.actions_skipped} skipped.
-Edits: ${stats.edits_applied} applied, ${stats.edits_skipped} skipped.`;
-      if (stats.skipped_details?.length > 0) {
-        res += `
-
-Skipped Details:
-${stats.skipped_details.join("\n")}`;
+      if (!dry_run) {
+        const outBuf = await doc.save();
+        fs.writeFileSync(outPath, outBuf);
       }
+      const res = formatBatchResult(stats, outPath, !!dry_run);
       return { content: [{ type: "text", text: res }] };
     } catch (e) {
       return {
@@ -1086,7 +1373,9 @@ ${result.reportText}`
 );
 server.registerTool(
   "login_to_adeu_cloud",
-  { description: "Logs the user into the Adeu Cloud backend." },
+  {
+    description: "Logs the user into Adeu Cloud. Opens a browser window for SSO authentication.\n\nIMPORTANT \u2014 login is user-level, not account-level:\n- An Adeu user can have multiple linked provider accounts (Microsoft, Google) and multiple mailboxes (personal + shared/delegated). One linked account is marked primary.\n- Signing in through ANY of the user's linked accounts authenticates the same Adeu user. Once logged in, the session can read from and draft in ALL of that user's linked accounts and ALL of their mailboxes \u2014 not just the one used to sign in.\n- The choice of which provider account to sign in through is purely an SSO mechanism; it does not select a 'current account' for the session.\n\nWhen the user asks which accounts or mailboxes are available, call `list_available_mailboxes` rather than naming a single account from the login response."
+  },
   async () => {
     try {
       return await login_to_adeu_cloud();
@@ -1109,7 +1398,7 @@ server.registerTool(
 server.registerTool(
   "create_email_draft",
   {
-    description: "Creates an email draft in the user's native draft box.",
+    description: "Creates an email draft in the user's native draft box (Outlook Drafts or Gmail Drafts).\n\nTWO MODES:\n1. Reply mode: pass `reply_to_email_id` to create a threaded reply. The draft inherits subject, recipients, and threading headers from the original \u2014 do NOT pass `subject` or `to_recipients`.\n2. New email mode: omit `reply_to_email_id` and pass BOTH `subject` and `to_recipients`.\n\n`reply_to_email_id` accepts the same ID formats as search_and_fetch_emails (`msg_*` short IDs, `adeu_*` references, or raw provider IDs). Short IDs are validated against the local cache before the call; stale ones fail fast with a clear error telling you to re-search.\n\n`body_markdown` is converted server-side to styled HTML with inlined CSS for email-client compatibility. Write the body in plain Markdown \u2014 do not pre-render HTML.\n\n`attachment_paths` takes absolute file paths on the user's local disk and uploads them with the draft. Useful right after search_and_fetch_emails downloaded attachments \u2014 those local paths can be passed directly here.",
     inputSchema: {
       body_markdown: z.string(),
       reply_to_email_id: z.string().optional(),
@@ -1132,7 +1421,7 @@ server.registerTool(
 server.registerTool(
   "list_available_mailboxes",
   {
-    description: "Lists all personal and shared delegated mailboxes configured for the authenticated profile. Use this to discover valid email addresses to scope search and draft operations.",
+    description: "Lists all personal and shared/delegated mailboxes the authenticated Adeu user has access to, across ALL of their linked provider accounts. Returns each mailbox's `email_address`, `display_name`, auto-processing settings, and write-back preference.\n\nThis is the right tool to answer 'which accounts/mailboxes am I logged into?' \u2014 Adeu login is user-level, so a single MCP session can see every mailbox listed here regardless of which provider account was used for SSO.\n\nCall this FIRST when the user names a specific mailbox or shared inbox, to resolve the canonical `email_address`. Then pass that address as `mailbox_address` to `search_and_fetch_emails` or `create_email_draft` to scope the operation. Omitting `mailbox_address` on those tools targets the user's primary personal mailbox.",
     inputSchema: {}
   },
   async () => {
@@ -1143,6 +1432,56 @@ server.registerTool(
     }
   }
 );
+function formatBatchResult(stats, outPath, dry_run) {
+  let res = "";
+  if (dry_run) {
+    res = `Dry-run simulation complete.
+`;
+  } else {
+    res = `Batch complete. Saved to: ${outPath}
+`;
+  }
+  res += `Actions: ${stats.actions_applied} applied, ${stats.actions_skipped} skipped.
+`;
+  res += `Edits: ${stats.edits_applied} applied, ${stats.edits_skipped} skipped.
+`;
+  if (stats.edits && stats.edits.length > 0) {
+    res += "\nDetailed Edit Reports:\n";
+    for (let i = 0; i < stats.edits.length; i++) {
+      const report = stats.edits[i];
+      const status_indicator = report.status === "applied" ? "\u2705 [applied]" : "\u274C [failed]";
+      res += `Edit ${i + 1} ${status_indicator}:
+`;
+      res += `  Target: '${report.target_text}'
+`;
+      res += `  New text: '${report.new_text}'
+`;
+      if (report.warning) {
+        res += `  Warning: ${report.warning}
+`;
+      }
+      if (report.error) {
+        res += `  Error: ${report.error}
+`;
+      }
+      if (report.critic_markup) {
+        res += `  Preview (CriticMarkup): ${report.critic_markup}
+`;
+      }
+      if (report.clean_text) {
+        res += `  Clean text preview: ${report.clean_text}
+`;
+      }
+    }
+  }
+  if (stats.skipped_details && stats.skipped_details.length > 0) {
+    res += `
+
+Skipped Details:
+${stats.skipped_details.join("\n")}`;
+  }
+  return res;
+}
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -1151,4 +1490,7 @@ async function main() {
   );
 }
 main().catch(console.error);
+export {
+  formatBatchResult
+};
 //# sourceMappingURL=index.js.map