@adeu/mcp-server 1.10.1 → 1.12.0

package/README.md

@@ -39,4 +39,18 @@ Once connected, your AI agent will have access to the following tools:
 - `finalize_document`: Prepares a document for signature by applying native OOXML read-only locking and deep metadata sanitization.
 
 ## 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).
+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).
+
+---
+
+## Development Runbook Note: Workspace Linkage Trap
+
+> [!WARNING]
+> **Node MCP: a committed source fix is NOT a running fix.**
+> `dist/` is gitignored and the server runs the compiled bundle. After ANY change to `node/packages/core` or `mcp-server`:
+> 
+> 1. **Relink dependencies:** `cd node && npm install` (relinks `@adeu/core` in the workspace; a copied — not symlinked — core is the #1 cause of "fix didn't take").
+> 2. **Rebuild the workspace:** `npm run build` (core builds before mcp-server; confirm `core/dist` timestamp is updated).
+> 3. **Verify:** Check that the build verification sentinel check succeeds (automatically runs postbuild, or can be run manually via `npm run build:verify` under `packages/mcp-server`).
+> 4. **Restart the MCP server:** Restart the MCP server AND reconnect in the client to flush any cached process states.
+> 5. **Confirm the build stamp:** Verify that the build stamp in the live server (via `server_info` or startup logs) matches your built git HEAD.

package/dist/index.js

@@ -7,7 +7,7 @@ import { readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
 import { basename as basename2, resolve as resolve2, extname, dirname, join as join3 } from "path";
 import { z } from "zod";
 import {
-  registerAppTool,
+  registerAppTool as origRegisterAppTool,
   registerAppResource,
   RESOURCE_MIME_TYPE
 } from "@modelcontextprotocol/ext-apps/server";
@@ -15,6 +15,7 @@ import fs from "fs";
 import {
   identifyEngine,
   extractTextFromBuffer,
+  _extractTextFromDoc,
   DocumentObject as DocumentObject2,
   RedlineEngine,
   BatchValidationError,
@@ -109,14 +110,15 @@ ${ui_markdown}`;
     }
   };
 }
-function build_outline_response(doc, projected_text, file_path, outline_max_level = 2, outline_verbose = false) {
+function build_outline_response(doc, projected_text, file_path, outline_max_level = 2, outline_verbose = false, paragraph_offsets = null) {
   const [body] = split_structural_appendix(projected_text);
   const pagination_result = paginate(body, "");
   const nodes = extract_outline(
     doc,
     body,
     pagination_result.body_pages,
-    pagination_result.body_page_offsets
+    pagination_result.body_page_offsets,
+    paragraph_offsets
   );
   const rendered = render_outline_tree(
     nodes,
@@ -608,62 +610,129 @@ function getUniqueFilepath(saveDir, filename) {
 async function search_and_fetch_emails(args) {
   const apiKey = await getCloudAuthToken();
   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) {
+  let data;
+  if (args.task_id) {
+    const pollUrl = `${BACKEND_URL}/api/v1/emails/tasks/${args.task_id}`;
+    let completedData = null;
+    for (let attempt = 0; attempt < 10; attempt++) {
+      let res;
+      try {
+        res = await fetch(pollUrl, {
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            Accept: "application/json"
+          },
+          signal: AbortSignal.timeout(15e3)
+        });
+      } catch (err) {
+        if (isTimeoutError(err)) {
+          throw new Error("Checking task status timed out.");
+        }
+        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(formatBackendError(res.status, await res.text()));
+      }
+      const taskData = await res.json();
+      const status = taskData.status;
+      if (status === "COMPLETED") {
+        completedData = taskData;
+        break;
+      }
+      if (status === "FAILED") {
+        const errorMsg = taskData.error || "Unknown internal error";
+        throw new Error(`Validation task failed on the server: ${errorMsg}`);
+      }
+      await new Promise((resolve3) => setTimeout(resolve3, 5e3));
+    }
+    if (!completedData) {
+      const msg = `Task ${args.task_id} is still processing. Please call \`search_and_fetch_emails\` again with task_id=${args.task_id}.`;
       return {
-        isError: true,
-        content: [{ type: "text", text: err.message }]
+        content: [{ type: "text", text: msg }],
+        structuredContent: {
+          status: "pending",
+          task_id: args.task_id,
+          message: msg
+        }
       };
     }
-    throw err;
-  }
-  const payload = {
-    email_id: realEmailId,
-    sender: args.sender,
-    subject: args.subject,
-    has_attachments: args.has_attachments,
-    attachment_name: args.attachment_name,
-    is_unread: args.is_unread,
-    days_ago: args.days_ago,
-    folder: args.folder,
-    limit: args.limit ?? 10,
-    offset: args.offset ?? 0,
-    mailbox_address: args.mailbox_address
-  };
-  Object.keys(payload).forEach(
-    (k) => payload[k] === void 0 && delete payload[k]
-  );
-  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)) {
+    data = completedData;
+  } else {
+    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,
+      subject: args.subject,
+      has_attachments: args.has_attachments,
+      attachment_name: args.attachment_name,
+      is_unread: args.is_unread,
+      days_ago: args.days_ago,
+      folder: args.folder,
+      limit: args.limit ?? 10,
+      offset: args.offset ?? 0,
+      mailbox_address: args.mailbox_address
+    };
+    Object.keys(payload).forEach(
+      (k) => payload[k] === void 0 && delete payload[k]
+    );
+    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(
-        "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."
+        "Authentication expired. Please call `login_to_adeu_cloud` to re-authenticate."
       );
     }
-    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(formatBackendError(res.status, await res.text()));
+    data = await res.json();
+    if (res.status === 202 || data && (data.status === "pending" || data.task_id) && data.type === void 0) {
+      const newTaskId = data.task_id;
+      const msg = `Email processing task started successfully. Task ID: ${newTaskId}. Please call \`search_and_fetch_emails\` again immediately with task_id=${newTaskId} to monitor the progress.`;
+      return {
+        content: [{ type: "text", text: msg }],
+        structuredContent: {
+          status: "pending",
+          task_id: String(newTaskId),
+          message: msg
+        }
+      };
+    }
   }
-  if (!res.ok)
-    throw new Error(formatBackendError(res.status, await res.text()));
-  const data = await res.json();
   const cache = loadIdCache();
   if (data.type === "previews") {
     const previews = data.previews || [];
@@ -983,7 +1052,9 @@ function readFileBytesOrThrow(filePath) {
     return readFileSync3(filePath);
   } catch (err) {
     if (err.code === "ENOENT") {
-      throw new Error(`File not found: ${filePath}`);
+      throw new Error(
+        `File not found: ${filePath}. Note: If you are running in a sandboxed/containerized environment, the host application or MCP server may not have access to your local workspace files. You can resolve this by installing Adeu directly inside your sandboxed environment using 'uv tool install adeu' and executing the commands via the CLI.`
+      );
     }
     throw err;
   }
@@ -1001,10 +1072,30 @@ 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. `target_text` must uniquely match \u2014 include surrounding context if the phrase is ambiguous. `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.\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.\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 unified diff of their text content. Useful for analyzing differences between versions before editing.";
+var gitSha = "893d263";
+var packageVersion = "1.12.0";
+var buildTag = ` [Adeu v${packageVersion}+${gitSha}]`;
 var server = new McpServer({
   name: "adeu-redlining-service",
-  version: "1.0.0"
+  version: packageVersion
 });
+var originalRegisterTool = server.registerTool.bind(server);
+server.registerTool = (name, schema, handler) => {
+  if (schema && typeof schema === "object") {
+    if (schema.description) {
+      schema.description = schema.description.trim() + buildTag;
+    }
+  }
+  return originalRegisterTool(name, schema, handler);
+};
+var registerAppTool = (mcpServer, name, schema, handler) => {
+  if (schema && typeof schema === "object") {
+    if (schema.description) {
+      schema.description = schema.description.trim() + buildTag;
+    }
+  }
+  return origRegisterAppTool(mcpServer, name, schema, handler);
+};
 var UI_CSP = {
   connectDomains: ["https://fonts.googleapis.com", "https://fonts.gstatic.com"],
   resourceDomains: [
@@ -1097,21 +1188,26 @@ registerAppTool(
   }) => {
     try {
       const buf = readFileBytesOrThrow(file_path);
-      const text = await extractTextFromBuffer(buf, clean_view);
       if (mode === "outline") {
         const doc = await DocumentObject2.load(buf);
-        return build_outline_response(
+        const extract_res = _extractTextFromDoc(doc, clean_view, true, true);
+        const res2 = build_outline_response(
           doc,
-          text,
+          extract_res.text,
           file_path,
           outline_max_level,
-          outline_verbose
+          outline_verbose,
+          extract_res.paragraph_offsets
         );
+        return res2;
       }
+      const text = await extractTextFromBuffer(buf, clean_view);
       if (mode === "appendix") {
-        return build_appendix_response(text, page, file_path);
+        const res2 = build_appendix_response(text, page, file_path);
+        return res2;
       }
-      return build_paginated_response(text, page, file_path);
+      const res = build_paginated_response(text, page, file_path);
+      return res;
     } catch (e) {
       return {
         isError: true,
@@ -1144,6 +1240,7 @@ registerAppTool(
       email_id: z.string().optional(),
       working_directory: z.string().optional(),
       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.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."
       )
@@ -1485,8 +1582,10 @@ ${stats.skipped_details.join("\n")}`;
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  const gitSha2 = "893d263";
+  const buildTs = "2026-06-18T14:35:42.322Z";
   console.error(
-    `Adeu MCP Server (Node.js Engine: ${identifyEngine()}) running on stdio`
+    `Adeu MCP Server (Node.js Engine: ${identifyEngine()}) running on stdio build=${gitSha2}@${buildTs}`
   );
 }
 main().catch(console.error);