@adeu/mcp-server 1.18.0 → 1.18.2

package/dist/index.js

@@ -204,12 +204,17 @@ function build_search_response(text, search_query, search_regex, search_case_sen
   const [body] = split_structural_appendix(text);
   const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const flags = search_case_sensitive ? "g" : "gi";
-  const patternStr = search_regex ? search_query : escapeRegExp(search_query);
+  let regexDowngradedNote = "";
   let regex;
-  try {
-    regex = new RegExp(patternStr, flags);
-  } catch (e) {
-    throw new Error(`Invalid regex pattern: ${e.message}`);
+  if (search_regex) {
+    try {
+      regex = new RegExp(search_query, flags);
+    } catch (e) {
+      regexDowngradedNote = `> **Note:** \`${search_query}\` is not a valid regular expression (${e.message}), so it was searched as literal text instead. If you meant a regex, fix the pattern; if you meant literal text, set \`search_regex\` to false.`;
+      regex = new RegExp(escapeRegExp(search_query), flags);
+    }
+  } else {
+    regex = new RegExp(escapeRegExp(search_query), flags);
   }
   const allMatches = Array.from(body.matchAll(regex));
   const pag_res = paginate(body, "");
@@ -264,6 +269,9 @@ The query DOES appear elsewhere in the document (${allMatches.length} match${all
 
 Verify your search spelling, or try setting \`search_case_sensitive\` to false or enabling \`search_regex\` if you used pattern wildcards.`;
     }
+    if (regexDowngradedNote) body_msg = `${regexDowngradedNote}
+
+${body_msg}`;
     const llm_content2 = `> **File Path:** \`${resolve(file_path)}\`
 
 ${body_msg}`;
@@ -354,6 +362,7 @@ ${body_msg}`;
     );
     i++;
   }
+  if (regexDowngradedNote) ui_parts.unshift(regexDowngradedNote);
   const ui_markdown = ui_parts.join("\n\n");
   const llm_content = `> **File Path:** \`${resolve(file_path)}\`
 
@@ -1220,6 +1229,36 @@ async function list_available_mailboxes() {
 }
 
 // src/index.ts
+var MATCH_MODE_SYNONYMS = {
+  strict: "strict",
+  first: "first",
+  all: "all",
+  first_only: "first",
+  firstonly: "first",
+  "first-only": "first",
+  all_occurrences: "all",
+  alloccurrences: "all",
+  "all-occurrences": "all",
+  every: "all"
+};
+function coerceChangeItemInPlace(item) {
+  if (item === null || typeof item !== "object" || Array.isArray(item)) return;
+  if (!("type" in item) || item.type === void 0 || item.type === null) {
+    if ("cells" in item) item.type = "insert_row";
+    else if ("text" in item && "target_id" in item) item.type = "reply";
+    else if ("target_text" in item && "new_text" in item) item.type = "modify";
+  }
+  if ("match_mode" in item) {
+    const raw = item.match_mode;
+    if (typeof raw !== "string") {
+      delete item.match_mode;
+    } else {
+      const mapped = MATCH_MODE_SYNONYMS[raw.trim().toLowerCase()];
+      if (mapped === void 0) delete item.match_mode;
+      else item.match_mode = mapped;
+    }
+  }
+}
 function readFileBytesOrThrow(filePath) {
   try {
     return readFileSync3(filePath);
@@ -1250,8 +1289,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 = "17f87f0";
-var packageVersion = "1.18.0";
+var gitSha = "263a4e4";
+var packageVersion = "1.18.2";
 var buildTag = ` [Adeu v${packageVersion}+${gitSha}]`;
 var args = process.argv.slice(2);
 var scopeIdx = args.indexOf("--scope");
@@ -1347,6 +1386,9 @@ registerAppTool(
     title: "Read DOCX",
     description: READ_DOCX_COMMON_DESC + READ_DOCX_TAIL,
     inputSchema: z.object({
+      reasoning: z.string().describe(
+        "Why do I need to read this docx document? State this reason before any other parameter."
+      ),
       file_path: z.string().describe("Absolute path to the DOCX file."),
       clean_view: z.boolean().default(false).describe(
         "If False (default), returns the 'Raw' text with inline CriticMarkup. If True, returns 'Accepted' text."
@@ -1370,6 +1412,7 @@ registerAppTool(
     _meta: { ui: { resourceUri: MARKDOWN_UI_URI } }
   },
   async ({
+    reasoning,
     file_path,
     clean_view,
     mode,
@@ -1381,6 +1424,7 @@ registerAppTool(
     search_case_sensitive
   }) => {
     try {
+      void reasoning;
       const buf = readFileBytesOrThrow(file_path);
       if (mode === "outline") {
         const doc = await DocumentObject2.load(buf);
@@ -1433,8 +1477,8 @@ registerAppTool(
   }
 );
 var CHANGE_ITEM_SCHEMA = z.object({
-  type: z.enum(["modify", "accept", "reject", "reply", "insert_row", "delete_row"]).describe(
-    "Change kind: 'modify' (search-and-replace), 'accept'/'reject' (resolve a tracked change by id), 'reply' (reply to a comment by id), 'insert_row'/'delete_row' (table edits; disk mode only)."
+  type: z.enum(["modify", "accept", "reject", "reply", "insert_row", "delete_row"]).optional().describe(
+    "Change kind: 'modify' (search-and-replace), 'accept'/'reject' (resolve a tracked change by id), 'reply' (reply to a comment by id), 'insert_row'/'delete_row' (table edits; disk mode only). If omitted it is inferred when unambiguous from the other fields."
   ),
   target_text: z.string().optional().describe(
     "modify / insert_row / delete_row: the existing text to locate (interpreted as a regex when regex=true)."
@@ -1465,6 +1509,9 @@ server.registerTool(
   {
     description: PROCESS_BATCH_COMMON_DESC + PROCESS_BATCH_OPERATIONS_DESC,
     inputSchema: {
+      reasoning: z.string().describe(
+        "Why do I need to apply these changes to the document? State this reason before any other parameter."
+      ),
       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.union([z.string(), CHANGE_ITEM_SCHEMA])).describe(
@@ -1477,6 +1524,7 @@ server.registerTool(
     }
   },
   async ({
+    reasoning,
     original_docx_path,
     author_name,
     changes,
@@ -1484,6 +1532,7 @@ server.registerTool(
     dry_run
   }) => {
     try {
+      void reasoning;
       if (!author_name || !author_name.trim())
         return {
           content: [
@@ -1495,19 +1544,49 @@ server.registerTool(
           content: [{ type: "text", text: "Error: No changes provided." }]
         };
       const sanitizedChanges = changes.map((item) => {
+        let obj = item;
         if (typeof item === "string") {
           try {
             const parsed = JSON.parse(item);
-            if (parsed !== null && typeof parsed === "object") {
-              return parsed;
-            }
-            return item;
+            obj = parsed !== null && typeof parsed === "object" ? parsed : item;
           } catch {
-            return item;
+            obj = item;
           }
         }
-        return item;
+        if (obj !== null && typeof obj === "object" && !Array.isArray(obj)) {
+          coerceChangeItemInPlace(obj);
+        }
+        return obj;
       });
+      const VALID_TYPES = /* @__PURE__ */ new Set([
+        "modify",
+        "accept",
+        "reject",
+        "reply",
+        "insert_row",
+        "delete_row"
+      ]);
+      const typeErrors = [];
+      sanitizedChanges.forEach((c, i) => {
+        if (c !== null && typeof c === "object" && !Array.isArray(c) && (!c.type || !VALID_TYPES.has(c.type))) {
+          typeErrors.push(
+            `- Change ${i + 1}: missing or unrecognized "type". Use one of: modify (needs target_text + new_text), accept/reject (needs target_id like "Chg:12"), reply (needs target_id like "Com:5" + text), insert_row (needs target_text + cells), delete_row (needs target_text). Received keys: [${Object.keys(c).join(", ")}].`
+          );
+        }
+      });
+      if (typeErrors.length > 0) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Batch rejected. Some changes are malformed:
+
+${typeErrors.join("\n")}`
+            }
+          ]
+        };
+      }
       let outPath = output_path;
       if (!outPath) {
         const ext = extname(original_docx_path);
@@ -1560,12 +1639,16 @@ server.registerTool(
   {
     description: "Accepts all tracked changes and removes all comments in a single operation.",
     inputSchema: {
+      reasoning: z.string().describe(
+        "Why do I need to accept all changes in this document? State this reason before any other parameter."
+      ),
       docx_path: z.string().describe("Absolute path to the DOCX file."),
       output_path: z.string().optional().describe("Optional output path.")
     }
   },
-  async ({ docx_path, output_path }) => {
+  async ({ reasoning, docx_path, output_path }) => {
     try {
+      void reasoning;
       let outPath = output_path;
       if (!outPath) {
         const ext = extname(docx_path);
@@ -1597,6 +1680,9 @@ server.registerTool(
   {
     description: DIFF_DOCX_DESC,
     inputSchema: {
+      reasoning: z.string().describe(
+        "Why do I need to diff these two documents? State this reason before any other parameter."
+      ),
       original_path: z.string().describe("Absolute path to the baseline DOCX file."),
       modified_path: z.string().describe("Absolute path to the modified DOCX file."),
       compare_clean: z.boolean().default(true).describe(
@@ -1604,8 +1690,9 @@ server.registerTool(
       )
     }
   },
-  async ({ original_path, modified_path, compare_clean }) => {
+  async ({ reasoning, original_path, modified_path, compare_clean }) => {
     try {
+      void reasoning;
       const origBuf = readFileBytesOrThrow(original_path);
       const modBuf = readFileBytesOrThrow(modified_path);
       const origText = await extractTextFromBuffer(origBuf, compare_clean);
@@ -1632,6 +1719,9 @@ server.registerTool(
   {
     description: "Prepares a document for external distribution or e-signature. Note: in this zero-dependency environment, protection_mode='encrypt' is unsupported and falls back to a native read-only lock; export_pdf and password are ignored.",
     inputSchema: {
+      reasoning: z.string().describe(
+        "Why do I need to finalize this document? State this reason before any other parameter."
+      ),
       file_path: z.string().describe("Absolute path to the DOCX file."),
       output_path: z.string().optional().describe("Optional output path."),
       sanitize_mode: z.enum(["full", "keep-markup"]).optional().describe("full removes all markup, keep-markup redacts metadata."),
@@ -1647,6 +1737,7 @@ server.registerTool(
     }
   },
   async ({
+    reasoning,
     file_path,
     output_path,
     sanitize_mode,
@@ -1656,6 +1747,7 @@ server.registerTool(
     export_pdf
   }) => {
     try {
+      void reasoning;
       let outPath = output_path;
       if (!outPath) {
         const ext = extname(file_path);
@@ -1700,6 +1792,9 @@ if (!isDocxOnly) {
       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.",
       inputSchema: z.object({
+        reasoning: z.string().describe(
+          "Why do I need to search or fetch these emails? State this reason before any other parameter."
+        ),
         sender: z.string().optional(),
         subject: z.string().optional(),
         has_attachments: z.boolean().optional(),
@@ -1733,7 +1828,12 @@ if (!isDocxOnly) {
   server.registerTool(
     "login_to_adeu_cloud",
     {
-      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."
+      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.",
+      inputSchema: {
+        reasoning: z.string().describe(
+          "Why do I need to log in to Adeu Cloud? State this reason before any other parameter."
+        )
+      }
     },
     async () => {
       try {
@@ -1745,7 +1845,14 @@ if (!isDocxOnly) {
   );
   server.registerTool(
     "logout_of_adeu_cloud",
-    { description: "Logs out of the Adeu Cloud backend." },
+    {
+      description: "Logs out of the Adeu Cloud backend.",
+      inputSchema: {
+        reasoning: z.string().describe(
+          "Why do I need to log out of Adeu Cloud? State this reason before any other parameter."
+        )
+      }
+    },
     async () => {
       try {
         return await logout_of_adeu_cloud();
@@ -1759,6 +1866,9 @@ if (!isDocxOnly) {
     {
       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: {
+        reasoning: z.string().describe(
+          "Why do I need to create this email draft? State this reason before any other parameter."
+        ),
         body_markdown: z.string(),
         reply_to_email_id: z.string().optional(),
         subject: z.string().optional(),
@@ -1781,7 +1891,11 @@ if (!isDocxOnly) {
     "list_available_mailboxes",
     {
       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: {}
+      inputSchema: {
+        reasoning: z.string().describe(
+          "Why do I need to list available mailboxes? State this reason before any other parameter."
+        )
+      }
     },
     async () => {
       try {
@@ -1857,8 +1971,8 @@ ${stats.skipped_details.join("\n")}`;
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  const gitSha2 = "17f87f0";
-  const buildTs = "2026-06-30T13:06:23.169Z";
+  const gitSha2 = "263a4e4";
+  const buildTs = "2026-07-03T13:50:27.555Z";
   console.error(
     `Adeu MCP Server (Node.js Engine: ${identifyEngine()}) running on stdio build=${gitSha2}@${buildTs}`
   );