@adeu/mcp-server 1.6.9 → 1.7.3

package/README.md

@@ -0,0 +1,42 @@
+
+# @adeu/mcp-server
+
+[![GitHub Repo stars](https://img.shields.io/github/stars/dealfluence/adeu?style=social)](https://github.com/dealfluence/adeu)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Native Microsoft Word Track Changes for AI Agents**
+
+`@adeu/mcp-server` is a standalone Node.js [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that acts as a "Virtual DOM" for Microsoft Word documents. It provides AI agents (like Claude) with tools to safely read, edit, and sanitize `.docx` files without destroying underlying formatting or complex XML.
+
+This package provides the exact same engine as the Python `adeu` CLI, but executes entirely via Node.js—making it ideal for environments where Python is unavailable or undesired.
+
+## Usage with MCP Clients
+
+You can add this server directly to your MCP client (like Claude Desktop, Cursor, or Windsurf) using `npx`. 
+
+Add the following to your MCP configuration file (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "adeu-node": {
+      "command": "npx",
+      "args": ["-y", "@adeu/mcp-server"]
+    }
+  }
+}
+```
+
+## Exposed Tools
+
+Once connected, your AI agent will have access to the following 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.
+- `accept_all_changes`: Accepts all tracked changes and removes all comments to produce a finalized clean document.
+- `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.
+
+## 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

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { Server as Server2 } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-import { readFileSync } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 import { basename as basename2, resolve as resolve2, extname, dirname } from "path";
 import {
   identifyEngine,
@@ -160,10 +160,444 @@ ${ui_markdown}`;
   };
 }
 
+// src/desktop-auth.ts
+import { createServer } from "http";
+import { exec } from "child_process";
+import { homedir, platform } from "os";
+import { join } from "path";
+import {
+  writeFileSync,
+  readFileSync,
+  mkdirSync,
+  existsSync,
+  rmSync,
+  chmodSync
+} from "fs";
+
+// src/shared.ts
+var FRONTEND_URL = process.env.ADEU_FRONTEND_URL || "https://app.adeu.ai";
+var BACKEND_URL = process.env.ADEU_BACKEND_URL || "https://app.adeu.ai";
+
+// src/desktop-auth.ts
+var ADEU_DIR = join(homedir(), ".adeu");
+var CRED_PATH = join(ADEU_DIR, "credentials.json");
+function openBrowser(url) {
+  if (platform() === "darwin") exec(`open "${url}"`);
+  else if (platform() === "win32") exec(`start "" "${url}"`);
+  else exec(`xdg-open "${url}"`);
+}
+var DesktopAuthManager = class {
+  static getApiKey() {
+    if (!existsSync(CRED_PATH)) return null;
+    try {
+      const data = JSON.parse(readFileSync(CRED_PATH, "utf-8"));
+      return data.api_key || null;
+    } catch {
+      return null;
+    }
+  }
+  static setApiKey(apiKey) {
+    if (!existsSync(ADEU_DIR)) {
+      mkdirSync(ADEU_DIR, { recursive: true });
+    }
+    writeFileSync(CRED_PATH, JSON.stringify({ api_key: apiKey }));
+    chmodSync(CRED_PATH, 384);
+  }
+  static clearApiKey() {
+    if (existsSync(CRED_PATH)) {
+      rmSync(CRED_PATH);
+    }
+  }
+  static async authenticateInteractive() {
+    return new Promise((resolve3, reject) => {
+      let server2;
+      const timeout = setTimeout(
+        () => {
+          if (server2) server2.close();
+          reject(new Error("Authentication timed out after 5 minutes."));
+        },
+        5 * 60 * 1e3
+      );
+      server2 = createServer((req, res) => {
+        const url = new URL(req.url || "", `http://${req.headers.host}`);
+        if (url.pathname === "/callback") {
+          const apiKey = url.searchParams.get("api_key");
+          res.writeHead(apiKey ? 200 : 400, { "Content-Type": "text/html" });
+          const title = apiKey ? "Authentication Successful!" : "Authentication Failed";
+          const text = apiKey ? "Your Adeu MCP server has been successfully authenticated. You can safely close this window and return to Claude." : "No API key received. Please try again.";
+          const color = apiKey ? "#107c10" : "#d83b01";
+          res.end(`
+            <!DOCTYPE html><html><head><title>${title}</title>
+            <style>body{font-family:sans-serif;text-align:center;padding:50px;background:#f3f2f1;}.container{background:white;padding:40px;border-radius:8px;box-shadow:0 2px 4px rgba(0,0,0,0.1);max-width:500px;margin:0 auto;}h1{color:${color};}p{color:#605e5c;line-height:1.5;}</style>
+            </head><body><div class="container"><h1>${title}</h1><p>${text}</p>
+            <script>setTimeout(()=>window.close(), 3000);</script>
+            </div></body></html>
+          `);
+          clearTimeout(timeout);
+          setTimeout(() => server2.close(), 100);
+          if (apiKey) {
+            this.setApiKey(apiKey);
+            resolve3(apiKey);
+          } else {
+            reject(new Error("No API key received in callback."));
+          }
+        } else {
+          res.writeHead(404);
+          res.end();
+        }
+      });
+      server2.listen(0, "127.0.0.1", () => {
+        const address = server2.address();
+        if (address && typeof address !== "string") {
+          const authUrl = `${FRONTEND_URL}/login?desktop_port=${address.port}`;
+          openBrowser(authUrl);
+        }
+      });
+    });
+  }
+  static async ensureAuthenticated() {
+    const key = this.getApiKey();
+    if (key) return key;
+    return this.authenticateInteractive();
+  }
+};
+async function getCloudAuthToken() {
+  const key = DesktopAuthManager.getApiKey();
+  if (!key) {
+    throw new Error(
+      "Authentication Required: You are not logged in. Please call the `login_to_adeu_cloud` tool first to authenticate, then try this task again."
+    );
+  }
+  return key;
+}
+
+// src/tools/auth.ts
+async function login_to_adeu_cloud() {
+  try {
+    const apiKey = await DesktopAuthManager.ensureAuthenticated();
+    const res = await fetch(`${BACKEND_URL}/api/v1/auth/me`, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json"
+      }
+    });
+    if (res.status === 401) {
+      DesktopAuthManager.clearApiKey();
+      throw new Error(
+        "Your previous session expired. The stale key has been cleared. Please call `login_to_adeu_cloud` ONE MORE TIME to log in fresh."
+      );
+    }
+    if (!res.ok) throw new Error(`HTTP Error: ${res.status}`);
+    const data = await res.json();
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Login successful! Connected to Adeu Cloud as: ${data.email || "Unknown Email"}.`
+        }
+      ]
+    };
+  } catch (err) {
+    return { isError: true, content: [{ type: "text", text: err.message }] };
+  }
+}
+async function logout_of_adeu_cloud() {
+  DesktopAuthManager.clearApiKey();
+  return {
+    content: [
+      {
+        type: "text",
+        text: "Successfully logged out. The local API key has been removed."
+      }
+    ]
+  };
+}
+
+// src/tools/email.ts
+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 CACHE_FILE = join2(homedir2(), ".adeu", "mcp_id_cache.json");
+var MAX_CACHE_SIZE = 1e3;
+function loadIdCache() {
+  if (existsSync2(CACHE_FILE)) {
+    try {
+      return JSON.parse(readFileSync2(CACHE_FILE, "utf-8"));
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+function saveIdCache(cache) {
+  try {
+    mkdirSync2(join2(homedir2(), ".adeu"), { recursive: true });
+    const keys = Object.keys(cache);
+    if (keys.length > MAX_CACHE_SIZE) {
+      const trimmed = {};
+      keys.slice(-MAX_CACHE_SIZE).forEach((k) => trimmed[k] = cache[k]);
+      cache = trimmed;
+    }
+    writeFileSync2(CACHE_FILE, JSON.stringify(cache));
+  } catch {
+  }
+}
+function minifyEmailId(realId, cache) {
+  if (!realId) return realId;
+  const hash = createHash("md5").update(realId).digest("hex").slice(0, 6);
+  const shortId = `msg_${hash}`;
+  cache[shortId] = realId;
+  return shortId;
+}
+function resolveEmailId(shortId) {
+  if (!shortId) return shortId;
+  const cache = loadIdCache();
+  return cache[shortId] || shortId;
+}
+function stripTags(html) {
+  if (!html) return "";
+  let text = html.replace(/<(style|script|head)[^>]*>[\s\S]*?<\/\1>/gi, "");
+  text = text.replace(
+    /<\/?(p|div|br|hr|tr|li|h[1-6]|blockquote)\b[^>]*>/gi,
+    "\n"
+  );
+  text = text.replace(/<[^>]+>/g, "");
+  return text.replace(/\n\s*\n\s*\n+/g, "\n\n").trim();
+}
+function removeNestedQuotes(text) {
+  if (!text) return "";
+  const patterns = [
+    /_{10,}/m,
+    /^From:\s.*?\n(?:.*\n){0,5}?Sent:\s/m,
+    /-----Original Message-----/m,
+    /On .{1,200}? wrote:/m,
+    /^Original Message$/m
+  ];
+  let earliestCut = text.length;
+  for (const pattern of patterns) {
+    const match = pattern.exec(text);
+    if (match && match.index < earliestCut) {
+      earliestCut = match.index;
+    }
+  }
+  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;
+}
+async function search_and_fetch_emails(args) {
+  const apiKey = await getCloudAuthToken();
+  const realEmailId = args.email_id ? resolveEmailId(args.email_id) : void 0;
+  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
+  };
+  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)
+  });
+  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()}`);
+  const data = await res.json();
+  const cache = loadIdCache();
+  if (data.type === "previews") {
+    const previews = data.previews || [];
+    if (!previews.length)
+      return {
+        content: [
+          {
+            type: "text",
+            text: "No emails found matching your search criteria."
+          }
+        ]
+      };
+    const lines = [
+      `Found ${previews.length} email(s). Here are the previews:`,
+      ""
+    ];
+    for (const p of previews) {
+      const shortId = minifyEmailId(p.id, cache);
+      const attFlag = p.has_attachments ? "\u{1F4CE} (Has Attachments)" : "";
+      const unreadFlag = p.is_read === false ? "\u{1F7E2} [UNREAD]" : "";
+      lines.push(
+        `- **ID**: \`${shortId}\`
+  **Subject**: ${p.subject} ${attFlag} ${unreadFlag}
+  **From**: ${p.sender_name} <${p.sender_email}>
+  **Date**: ${p.received_datetime}
+  **Preview**: ${p.preview_text}
+`
+      );
+    }
+    saveIdCache(cache);
+    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`."
+    );
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+  if (data.type === "full_email") {
+    const full = data.full_email || {};
+    const shortTargetId = minifyEmailId(full.id || "unknown_id", cache);
+    saveIdCache(cache);
+    const baseDir = args.working_directory && existsSync2(args.working_directory) ? args.working_directory : tmpdir();
+    const saveDir = join2(
+      baseDir,
+      args.working_directory ? "adeu_attachments" : "adeu_downloads",
+      shortTargetId
+    );
+    mkdirSync2(saveDir, { recursive: true });
+    async function processAttachments(msg) {
+      const localFiles = [];
+      for (const att of msg.attachments || []) {
+        if (att.base64_data) {
+          try {
+            const filepath = getUniqueFilepath(
+              saveDir,
+              att.filename || "unnamed_file"
+            );
+            writeFileSync2(filepath, Buffer.from(att.base64_data, "base64"));
+            localFiles.push(filepath);
+            delete att.base64_data;
+          } catch (e) {
+            console.error(`Failed to save attachment ${att.filename}`, e);
+          }
+        }
+      }
+      return localFiles;
+    }
+    const targetFiles = await processAttachments(full);
+    const lines = [
+      `# 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}\``));
+    }
+    const cleanBody = removeNestedQuotes(stripTags(full.body_html || ""));
+    lines.push(`**Body**:
+\`\`\`
+${cleanBody}
+\`\`\`
+`);
+    if (full.is_thread && full.messages?.length) {
+      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);
+        lines.push(
+          `### Message -${i + 1} (Older)
+**From**: ${histMsg.sender_name} <${histMsg.sender_email}>
+**Date**: ${histMsg.received_datetime}`
+        );
+        if (histFiles.length) {
+          lines.push("**Attachments Saved Locally**:");
+          histFiles.forEach((f) => lines.push(`- \u{1F4CE} \`${f}\``));
+        }
+        lines.push(
+          `**Body**:
+\`\`\`
+${removeNestedQuotes(stripTags(histMsg.body_html || ""))}
+\`\`\`
+`
+        );
+      }
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+  return {
+    isError: true,
+    content: [{ type: "text", text: "Unknown response format from backend." }]
+  };
+}
+async function create_email_draft(args) {
+  const apiKey = await getCloudAuthToken();
+  if (!args.reply_to_email_id && (!args.subject || !args.to_recipients)) {
+    throw new Error(
+      "You must provide either 'reply_to_email_id' OR both 'subject' and 'to_recipients'."
+    );
+  }
+  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)
+    );
+  }
+  if (args.subject) formData.append("subject", args.subject);
+  if (args.to_recipients) {
+    const recips = typeof args.to_recipients === "string" ? JSON.parse(args.to_recipients) : args.to_recipients;
+    formData.append("to_recipients", JSON.stringify(recips));
+  }
+  if (args.attachment_paths) {
+    const paths = typeof args.attachment_paths === "string" ? JSON.parse(args.attachment_paths) : args.attachment_paths;
+    for (const p of paths) {
+      const buf = readFileSync2(p);
+      const filename = p.split(/[/\\]/).pop();
+      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
+  });
+  if (res.status === 401) {
+    DesktopAuthManager.clearApiKey();
+    throw new Error(
+      "Authentication expired. Please call `login_to_adeu_cloud`."
+    );
+  }
+  if (!res.ok)
+    throw new Error(`Cloud draft creation failed: ${await res.text()}`);
+  const data = await res.json();
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Successfully created email draft! Draft ID: ${data.id}`
+      }
+    ]
+  };
+}
+
 // src/index.ts
 function readFileBytesOrThrow(filePath) {
   try {
-    return readFileSync(filePath);
+    return readFileSync3(filePath);
   } catch (err) {
     if (err.code === "ENOENT") {
       throw new Error(`File not found: ${filePath}`);
@@ -176,7 +610,7 @@ 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 server = new Server(
+var server = new Server2(
   {
     name: "adeu-redlining-service",
     version: "1.0.0"
@@ -341,6 +775,51 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           },
           required: ["file_path"]
         }
+      },
+      {
+        name: "login_to_adeu_cloud",
+        description: "Logs the user into the Adeu Cloud backend. Securely opens a browser window for authentication.",
+        inputSchema: { type: "object", properties: {} }
+      },
+      {
+        name: "logout_of_adeu_cloud",
+        description: "Logs out of the Adeu Cloud backend by clearing the local API key.",
+        inputSchema: { type: "object", properties: {} }
+      },
+      {
+        name: "search_and_fetch_emails",
+        description: "Searches the user's live email inbox. By default, searches only the Inbox folder. Returns a list of lightweight previews. Call again with `email_id` to fetch the full body and download attachments.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            sender: { type: "string" },
+            subject: { type: "string" },
+            has_attachments: { type: "boolean" },
+            attachment_name: { type: "string" },
+            is_unread: { type: "boolean" },
+            days_ago: { type: "number" },
+            folder: { type: "string", enum: ["inbox", "sent", "all"] },
+            limit: { type: "number", default: 10 },
+            offset: { type: "number", default: 0 },
+            email_id: { type: "string" },
+            working_directory: { type: "string" }
+          }
+        }
+      },
+      {
+        name: "create_email_draft",
+        description: "Creates an email draft in the user's native draft box. Provide `reply_to_email_id` to reply, or `subject` and `to_recipients` for a new email.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            body_markdown: { type: "string" },
+            reply_to_email_id: { type: "string" },
+            subject: { type: "string" },
+            to_recipients: { type: "array", items: { type: "string" } },
+            attachment_paths: { type: "array", items: { type: "string" } }
+          },
+          required: ["body_markdown"]
+        }
       }
     ]
   };
@@ -510,6 +989,18 @@ ${result.reportText}`
           ]
         };
       }
+      if (name === "login_to_adeu_cloud") {
+        return await login_to_adeu_cloud();
+      }
+      if (name === "logout_of_adeu_cloud") {
+        return await logout_of_adeu_cloud();
+      }
+      if (name === "search_and_fetch_emails") {
+        return await search_and_fetch_emails(args || {});
+      }
+      if (name === "create_email_draft") {
+        return await create_email_draft(args || {});
+      }
       throw new Error(`Unknown tool: ${name}`);
     } catch (error) {
       return {