@adeu/mcp-server 1.9.0 → 1.10.0

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();
@@ -359,8 +360,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 +425,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 +600,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 +633,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 +691,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 +707,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 +717,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 +788,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 +798,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 +817,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 +845,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 +876,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 +902,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 +915,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 +940,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 +953,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 +1127,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 +1140,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 +1153,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 +1166,11 @@ 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 +1194,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 +1211,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 {
@@ -1109,7 +1385,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 +1408,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 user has access to. Returns each mailbox's `email_address`, `display_name`, auto-processing settings, and write-back preference.\n\nCall this FIRST when the user mentions a specific mailbox or shared inbox by name, 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.\n\nOmitting `mailbox_address` on those tools targets the user's primary personal mailbox.",
     inputSchema: {}
   },
   async () => {
@@ -1143,6 +1419,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 +1477,7 @@ async function main() {
   );
 }
 main().catch(console.error);
+export {
+  formatBatchResult
+};
 //# sourceMappingURL=index.js.map