@adeu/mcp-server 1.18.4 → 1.19.0

package/README.md

@@ -30,7 +30,9 @@ Add the following to your MCP configuration file (`claude_desktop_config.json`):
 
 ## Exposed Tools
 
-Once connected, your AI agent will have access to the following tools:
+Once connected, your AI agent will have access to the following tools.
+
+### Document tools
 
 - `read_docx`: Reads a DOCX file and returns LLM-friendly text with inline CriticMarkup (`{++inserted++}`, `{--deleted--}`) for Tracked Changes and Comments. Supports pagination, structural outlining, and semantic appendix extraction.
 - `process_document_batch`: Applies a batch of search-and-replace text modifications, table edits, and comment replies to a document. Translates the LLM's edits into perfectly formatted native Word Track Changes.
@@ -38,6 +40,19 @@ Once connected, your AI agent will have access to the following tools:
 - `diff_docx_files`: Compares two DOCX files and returns a unified sub-word diff of their text content.
 - `finalize_document`: Prepares a document for signature by applying native OOXML read-only locking and deep metadata sanitization.
 
+### Email tools
+
+These require an authenticated Adeu Cloud session (see Cloud tools below).
+
+- `search_and_fetch_emails`: Searches the user's live email inbox via the Adeu Cloud backend and returns matching messages.
+- `create_email_draft`: Creates an email draft in the user's native draft box (Outlook Drafts or Gmail Drafts).
+- `list_available_mailboxes`: Lists all personal and shared/delegated mailboxes the authenticated user can access across every linked provider account, including each mailbox's address, display name, and auto-processing settings.
+
+### Cloud tools
+
+- `login_to_adeu_cloud`: Logs the user into Adeu Cloud, opening a browser window for SSO authentication.
+- `logout_of_adeu_cloud`: Logs out of the Adeu Cloud backend.
+
 ## Documentation & Support
 For full architectural details, prompt recommendations, and the project constitution, please visit the [main Adeu repository](https://github.com/dealfluence/adeu) or our [website](https://adeu.ai).
 

package/dist/index.js

@@ -542,10 +542,18 @@ 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.",
+  "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. If the email lives in a shared or secondary mailbox, pass `mailbox_address` explicitly \u2014 provider IDs only resolve within the mailbox they came from.",
   "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 lookupErrorHint(detail) {
+  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\`.`;
+  }
+  return hint;
+}
 function formatBackendError(statusCode, responseBody) {
   let detail = responseBody;
   try {
@@ -555,12 +563,7 @@ function formatBackendError(statusCode, responseBody) {
     }
   } 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;
+  const message = lookupErrorHint(detail) ?? detail;
   return `Cloud search failed (HTTP ${statusCode}): ${message}`;
 }
 function isTimeoutError(err) {
@@ -576,6 +579,11 @@ function formatBytes(bytes) {
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
+function cacheEntryParts(entry) {
+  if (!entry) return { id: null, mailbox: null };
+  if (typeof entry === "string") return { id: entry, mailbox: null };
+  return { id: entry.id ?? null, mailbox: entry.mailbox ?? null };
+}
 function loadIdCache() {
   if (existsSync2(CACHE_FILE)) {
     try {
@@ -599,11 +607,11 @@ function saveIdCache(cache) {
   } catch {
   }
 }
-function minifyEmailId(realId, cache) {
+function minifyEmailId(realId, cache, mailboxAddress) {
   if (!realId) return realId;
   const hash = createHash("md5").update(realId).digest("hex").slice(0, 6);
   const shortId = `msg_${hash}`;
-  cache[shortId] = realId;
+  cache[shortId] = { id: realId, mailbox: mailboxAddress ?? null };
   return shortId;
 }
 var StaleShortIdError = class extends Error {
@@ -618,13 +626,17 @@ function resolveEmailId(shortId) {
   if (!shortId) return shortId;
   if (shortId.startsWith("adeu_")) return shortId;
   const cache = loadIdCache();
-  const resolved = cache[shortId];
-  if (resolved) return resolved;
+  const { id } = cacheEntryParts(cache[shortId]);
+  if (id) return id;
   if (shortId.startsWith("msg_")) {
     throw new StaleShortIdError(shortId);
   }
   return shortId;
 }
+function resolveCachedMailbox(shortId) {
+  if (!shortId || !shortId.startsWith("msg_")) return null;
+  return cacheEntryParts(loadIdCache()[shortId]).mailbox;
+}
 var HTML_NAMED_ENTITIES = {
   nbsp: " ",
   amp: "&",
@@ -817,7 +829,8 @@ async function pollEmailTask(taskId, apiKey) {
     }
     if (status === "FAILED") {
       const errorMsg = taskData.error || "Unknown internal error";
-      throw new Error(`Validation task failed on the server: ${errorMsg}`);
+      const hint = lookupErrorHint(errorMsg);
+      throw new Error(`Validation task failed on the server: ${hint ?? errorMsg}`);
     }
     await new Promise((resolve3) => setTimeout(resolve3, 5e3));
   }
@@ -826,6 +839,7 @@ async function pollEmailTask(taskId, apiKey) {
 async function search_and_fetch_emails(args2) {
   const apiKey = await getCloudAuthToken();
   const maxAttachmentSizeMb = typeof args2.max_attachment_size_mb === "number" && args2.max_attachment_size_mb > 0 ? args2.max_attachment_size_mb : 10;
+  let effectiveMailbox = args2.mailbox_address;
   let data;
   if (args2.task_id) {
     const completedData = await pollEmailTask(args2.task_id, apiKey);
@@ -854,6 +868,10 @@ async function search_and_fetch_emails(args2) {
       }
       throw err;
     }
+    if (args2.email_id && !effectiveMailbox) {
+      const cachedMailbox = resolveCachedMailbox(args2.email_id);
+      if (cachedMailbox) effectiveMailbox = cachedMailbox;
+    }
     const payload = {
       email_id: realEmailId,
       sender: args2.sender,
@@ -865,7 +883,7 @@ async function search_and_fetch_emails(args2) {
       folder: args2.folder,
       limit: args2.limit ?? 10,
       offset: args2.offset ?? 0,
-      mailbox_address: args2.mailbox_address
+      mailbox_address: effectiveMailbox
     };
     Object.keys(payload).forEach(
       (k) => payload[k] === void 0 && delete payload[k]
@@ -925,14 +943,17 @@ async function search_and_fetch_emails(args2) {
             type: "text",
             text: "No emails found matching your search criteria."
           }
-        ]
+        ],
+        // Keep the UI channel populated (Python parity) — without it the
+        // widget's tool-result handler bails and the skeleton spins forever.
+        structuredContent: data
       };
     const lines = [
       `Found ${previews.length} email(s). Here are the previews:`,
       ""
     ];
     for (const p of previews) {
-      const shortId = minifyEmailId(p.id, cache);
+      const shortId = minifyEmailId(p.id, cache, effectiveMailbox);
       const attFlag = p.has_attachments ? "\u{1F4CE} (Has Attachments)" : "";
       const unreadFlag = p.is_read === false ? "\u{1F7E2} [UNREAD]" : "";
       lines.push(
@@ -959,13 +980,28 @@ async function search_and_fetch_emails(args2) {
   }
   if (data.type === "full_email") {
     const full = data.full_email || {};
-    const shortTargetId = minifyEmailId(full.id || "unknown_id", cache);
+    const shortTargetId = minifyEmailId(
+      full.id || "unknown_id",
+      cache,
+      effectiveMailbox
+    );
     saveIdCache(cache);
     const autoEscalated = !args2.email_id && (args2.sender !== void 0 || args2.subject !== void 0 || args2.has_attachments !== void 0 || args2.attachment_name !== void 0 || args2.is_unread !== void 0 || args2.days_ago !== void 0 || args2.folder !== void 0);
-    const baseDir = args2.working_directory && existsSync2(args2.working_directory) ? args2.working_directory : tmpdir();
+    let baseDir = tmpdir();
+    let usedWorkingDirectory = false;
+    let dirFallbackNote = null;
+    if (args2.working_directory) {
+      try {
+        mkdirSync2(args2.working_directory, { recursive: true });
+        baseDir = args2.working_directory;
+        usedWorkingDirectory = true;
+      } catch (e) {
+        dirFallbackNote = `\u26A0\uFE0F **Attachment location notice**: the requested \`working_directory\` (\`${args2.working_directory}\`) did not exist and could not be created (${e.message}). Any attachments were saved to the system temp directory instead \u2014 use the exact paths listed below; do NOT re-run the search expecting a different location.`;
+      }
+    }
     const saveDir = join2(
       baseDir,
-      args2.working_directory ? "adeu_attachments" : "adeu_downloads",
+      usedWorkingDirectory ? "adeu_attachments" : "adeu_downloads",
       shortTargetId
     );
     mkdirSync2(saveDir, { recursive: true });
@@ -1011,6 +1047,9 @@ async function search_and_fetch_emails(args2) {
         "_(Search returned exactly one result; auto-fetched full email below.)_\n"
       );
     }
+    if (dirFallbackNote) {
+      lines.push(dirFallbackNote + "\n");
+    }
     lines.push(
       `# Email Thread: ${full.subject}`,
       "",
@@ -1076,7 +1115,7 @@ ${removeNestedQuotes(stripTags(histMsg.body_html || ""))}
     );
     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.*"
+        "\n*You can now use tools like `read_docx`, `diff_docx_files`, or `finalize_document` on the local file paths listed under each message. These paths are on the user's machine \u2014 pass them directly to those tools; your own sandbox/shell may not see them, and that does NOT mean the download failed.*"
       );
     }
     return {
@@ -1086,7 +1125,8 @@ ${removeNestedQuotes(stripTags(histMsg.body_html || ""))}
   }
   return {
     isError: true,
-    content: [{ type: "text", text: "Unknown response format from backend." }]
+    content: [{ type: "text", text: "Unknown response format from backend." }],
+    structuredContent: data
   };
 }
 async function create_email_draft(args2) {
@@ -1115,8 +1155,13 @@ async function create_email_draft(args2) {
     }
   }
   if (args2.subject) formData.append("subject", args2.subject);
-  if (args2.mailbox_address) {
-    formData.append("mailbox_address", args2.mailbox_address);
+  let draftMailbox = args2.mailbox_address;
+  if (args2.reply_to_email_id && !draftMailbox) {
+    const cachedMailbox = resolveCachedMailbox(args2.reply_to_email_id);
+    if (cachedMailbox) draftMailbox = cachedMailbox;
+  }
+  if (draftMailbox) {
+    formData.append("mailbox_address", draftMailbox);
   }
   if (args2.to_recipients) {
     const recips = typeof args2.to_recipients === "string" ? JSON.parse(args2.to_recipients) : args2.to_recipients;
@@ -1289,8 +1334,8 @@ var READ_DOCX_TAIL = "Modes:\n- 'full' (default): paginated body content. Use pa
 var PROCESS_BATCH_COMMON_DESC = "Applies a batch of edits and review actions to a DOCX.\n\nAll changes evaluate against the ORIGINAL document state \u2014 do not chain dependent edits within one batch (e.g. rename X to Y, then modify Y). Apply the rename first, then send a second batch.\n\n";
 var PROCESS_BATCH_OPERATIONS_DESC = "Each item in `changes` must specify a `type`:\n1. 'modify': Search-and-replace. By default `target_text` must match uniquely (`match_mode`:'strict') \u2014 add surrounding context to disambiguate, or set `match_mode`:'first'/'all' to edit the first or every occurrence. Set `regex`:true to treat `target_text` as a regular expression (capture groups available in `new_text` as $1, $2\u2026). `new_text` supports Markdown: '# Heading 1' through '###### Heading 6', '**bold**', '_italic_', and '\\n\\n' to split into multiple paragraphs. Empty `new_text` deletes. Do NOT write CriticMarkup tags ({++, {--, {>>) manually \u2014 use the `comment` parameter for comments.\n   \u2022 EMPTY/FORM TABLE CELLS: a blank cell has no text to match. `read_docx` renders each cell with a trailing `{#cell:<id>}` anchor \u2014 to fill a blank cell, set `target_text` to that exact anchor (e.g. '{#cell:0000005E}') and put the value in `new_text`. Do NOT try to match the pipe layout ('Date |  |  |'); the pipes are display separators, not editable text.\n2. 'accept' / 'reject': Finalize or revert a tracked change by `target_id` (e.g. 'Chg:12').\n3. 'reply': Reply to a comment by `target_id` (e.g. 'Com:5') with `text`.\n4. 'insert_row' / 'delete_row': Table edits. Disk mode only \u2014 not supported on Live Word canvas.\n\nID VOLATILITY: 'Chg:N' and 'Com:N' shift between document states. Always call `read_docx` immediately before any accept/reject/reply \u2014 do not reuse IDs from earlier in the conversation. The `{#cell:<id>}` anchors are stable (Word-assigned) and safe to reuse across reads.\n\n`author_name` is used for attribution on all tracked changes and comments, in both disk and Live Word modes.";
 var DIFF_DOCX_DESC = "Compares two DOCX files and returns a compact `@@ Word Patch @@` diff \u2014 Adeu's token-level, sub-word patch format \u2014 of their text content. Useful for analyzing differences between versions before editing.";
-var gitSha = "dc59148";
-var packageVersion = "1.18.4";
+var gitSha = "7506148";
+var packageVersion = "1.19.0";
 var buildTag = ` [Adeu v${packageVersion}+${gitSha}]`;
 var args = process.argv.slice(2);
 var scopeIdx = args.indexOf("--scope");
@@ -1790,7 +1835,7 @@ if (!isDocxOnly) {
     "search_and_fetch_emails",
     {
       title: "Search & Fetch Emails",
-      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.",
+      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. The mailbox used in the original search is remembered with the short ID and re-applied automatically when you fetch or reply without specifying `mailbox_address`.\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; the directory is created automatically if it does not exist. This directory path refers to the user's native operating system, not the LLM's sandbox environment.",
       inputSchema: z.object({
         reasoning: z.string().describe(
           "Why do I need to search or fetch these emails? State this reason before any other parameter."
@@ -1805,7 +1850,9 @@ if (!isDocxOnly) {
         limit: z.coerce.number().default(10),
         offset: z.coerce.number().default(0),
         email_id: z.string().optional(),
-        working_directory: z.string().optional(),
+        working_directory: z.string().optional().describe(
+          "Optional. The current working directory of the project or task. If provided, attachments will be saved here under an 'adeu_attachments' subfolder; the directory is created automatically if it does not exist. If omitted, attachments are saved to the system temp directory."
+        ),
         mailbox_address: z.string().optional().describe("Optional target mailbox email address to search within."),
         task_id: z.string().optional().describe("If resuming a pending check, provide the task ID here."),
         max_attachment_size_mb: z.coerce.number().optional().describe(
@@ -1971,8 +2018,8 @@ ${stats.skipped_details.join("\n")}`;
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  const gitSha2 = "dc59148";
-  const buildTs = "2026-07-05T06:17:14.425Z";
+  const gitSha2 = "7506148";
+  const buildTs = "2026-07-08T07:12:39.168Z";
   console.error(
     `Adeu MCP Server (Node.js Engine: ${identifyEngine()}) running on stdio build=${gitSha2}@${buildTs}`
   );