@adeu/mcp-server 1.12.0 → 1.13.0

package/src/index.ts

@@ -1,4 +1,3 @@
-// FILE: node/packages/mcp-server/src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { readFileSync, existsSync } from "node:fs";
@@ -41,10 +40,18 @@ function readFileBytesOrThrow(filePath: string): Buffer {
   } catch (err: any) {
     if (err.code === "ENOENT") {
       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.`
+        `File not found: ${filePath}.\n` +
+        `If you are running in a sandboxed/containerized environment (such as Claude Desktop or another containerized client), ` +
+        `the host application or MCP server may not have direct access to your local workspace files.\n` +
+        `You can resolve this by installing and running the local 'adeu' CLI tool directly within your environment.\n` +
+        `Here is how the MCP tools map to their CLI equivalents:\n` +
+        `- read_docx               -> adeu extract ${filePath}\n` +
+        `- process_document_batch  -> adeu apply ${filePath}\n` +
+        `- diff_docx_files         -> adeu diff ${filePath} <modified_path>\n` +
+        `- accept_all_changes      -> adeu accept-all ${filePath}\n\n` +
+        `To run the local tool, install it via:\n` +
+        `  uv tool install adeu\n` +
+        `and run the mapped CLI command directly in your terminal.`
       );
     }
     throw err;
@@ -81,10 +88,15 @@ const DIFF_DOCX_DESC =
   "Compares two DOCX files and returns a unified diff of their text content. Useful for analyzing differences between versions before editing.";
 
 const gitSha = process.env.GIT_SHA || "unknown";
-const buildTs = process.env.BUILD_TIMESTAMP || "unknown";
 const packageVersion = process.env.PACKAGE_VERSION || "unknown";
 const buildTag = ` [Adeu v${packageVersion}+${gitSha}]`;
 
+// --- Scope Configuration ---
+const args = process.argv.slice(2);
+const scopeIdx = args.indexOf("--scope");
+const requestedScope = (scopeIdx !== -1 ? args[scopeIdx + 1] : "all").toLowerCase();
+const isDocxOnly = requestedScope === "docx";
+
 // --- Server Setup ---
 const server = new McpServer({
   name: "adeu-redlining-service",
@@ -191,7 +203,6 @@ registerAppResource(
 // ==========================================
 // 2. UI-ENABLED TOOLS
 // ==========================================
-
 registerAppTool(
   server,
   "read_docx",
@@ -276,66 +287,6 @@ registerAppTool(
   },
 );
 
-
-
-registerAppTool(
-  server,
-  "search_and_fetch_emails",
-  {
-    title: "Search & Fetch Emails",
-    description:
-      "Searches the user's live email inbox via the Adeu cloud backend.\n\n" +
-      "TWO MODES:\n" +
-      "1. 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.\n" +
-      "2. 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\n" +
-      "AUTO-ESCALATION: If a search returns exactly one preview, the backend automatically fetches the full email in the same call. Plan around the response shape — check the `type` field (`previews` vs `full_email`) before assuming.\n\n" +
-      "EMAIL ID FORMATS (`email_id` parameter accepts any of):\n" +
-      "- `msg_<6 chars>` — 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>` — 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) — works if you have it, but you usually won't.\n\n" +
-      "FOLDER 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\n" +
-      "ATTACHMENTS: attachments larger than `max_attachment_size_mb` (default 10) are listed in the response but NOT downloaded — 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(),
-      has_attachments: z.boolean().optional(),
-      attachment_name: z.string().optional(),
-      is_unread: z.boolean().optional(),
-      days_ago: z.number().optional(),
-      folder: z.enum(["inbox", "sent", "all"]).optional(),
-      limit: z.number().default(10),
-      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."),
-      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.",
-        ),
-    }),
-    _meta: { ui: { resourceUri: EMAIL_UI_URI } },
-  },
-  async (args) => {
-    try {
-      return (await search_and_fetch_emails(args)) as any;
-    } catch (e: any) {
-      return {
-        isError: true,
-        content: [{ type: "text", text: e.message }],
-      };
-    }
-  },
-);
-
 // ==========================================
 // 3. HEADLESS TOOLS (No UI)
 // ==========================================
@@ -600,6 +551,66 @@ server.registerTool(
     }
   },
 );
+
+if (!isDocxOnly) {
+registerAppTool(
+  server,
+  "search_and_fetch_emails",
+  {
+    title: "Search & Fetch Emails",
+    description:
+      "Searches the user's live email inbox via the Adeu cloud backend.\n\n" +
+      "TWO MODES:\n" +
+      "1. 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.\n" +
+      "2. 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\n" +
+      "AUTO-ESCALATION: If a search returns exactly one preview, the backend automatically fetches the full email in the same call. Plan around the response shape — check the `type` field (`previews` vs `full_email`) before assuming.\n\n" +
+      "EMAIL ID FORMATS (`email_id` parameter accepts any of):\n" +
+      "- `msg_<6 chars>` — 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>` — 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) — works if you have it, but you usually won't.\n\n" +
+      "FOLDER 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\n" +
+      "ATTACHMENTS: attachments larger than `max_attachment_size_mb` (default 10) are listed in the response but NOT downloaded — 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(),
+      has_attachments: z.boolean().optional(),
+      attachment_name: z.string().optional(),
+      is_unread: z.boolean().optional(),
+      days_ago: z.number().optional(),
+      folder: z.enum(["inbox", "sent", "all"]).optional(),
+      limit: z.number().default(10),
+      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."),
+      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.",
+        ),
+    }),
+    _meta: { ui: { resourceUri: EMAIL_UI_URI } },
+  },
+  async (args) => {
+    try {
+      return (await search_and_fetch_emails(args)) as any;
+    } catch (e: any) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: e.message }],
+      };
+    }
+  },
+);
+
 server.registerTool(
   "login_to_adeu_cloud",
   {
@@ -681,6 +692,8 @@ server.registerTool(
     }
   },
 );
+}
+
 // --- Formatter for process_document_batch ---
 export function formatBatchResult(
   stats: any,

package/src/tools/email.test.ts

@@ -266,20 +266,76 @@ describe("Node Email Tools Finding #2 and Finding #6 tests", () => {
       vi.useRealTimers();
     });
 
-    it("should handle async task initiation upon searching", async () => {
-      global.fetch = vi.fn().mockResolvedValue({
-        ok: true,
-        status: 202,
-        json: async () => ({
-          status: "pending",
-          task_id: "email_task_typescript_123",
-          message: "Queued"
-        }),
-      } as Response);
+    it("should handle async task initiation upon searching and resolve when the task completes successfully", async () => {
+      let callCount = 0;
+      global.fetch = vi.fn().mockImplementation(async () => {
+        callCount++;
+        if (callCount === 1) {
+          return {
+            ok: true,
+            status: 202,
+            json: async () => ({
+              status: "pending",
+              task_id: "email_task_typescript_123",
+              message: "Queued",
+            }),
+          } as Response;
+        }
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            status: "COMPLETED",
+            type: "previews",
+            previews: [],
+          }),
+        } as Response;
+      });
+
+      const promise = search_and_fetch_emails({ subject: "heavy search" });
+      promise.catch(() => {});
+      await vi.runAllTimersAsync();
 
-      const result = await search_and_fetch_emails({ subject: "heavy search" });
+      const result = await promise;
 
-      expect(result.content[0].text).toContain("Email processing task started successfully");
+      expect(callCount).toBe(2);
+      expect(result.content[0].text).toContain("No emails found matching your search criteria.");
+    });
+
+    it("should handle async task initiation upon searching and return pending status on polling timeout (50s)", async () => {
+      let callCount = 0;
+      global.fetch = vi.fn().mockImplementation(async () => {
+        callCount++;
+        if (callCount === 1) {
+          return {
+            ok: true,
+            status: 202,
+            json: async () => ({
+              status: "pending",
+              task_id: "email_task_typescript_123",
+              message: "Queued",
+            }),
+          } as Response;
+        }
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ status: "PENDING" }),
+        } as Response;
+      });
+
+      const promise = search_and_fetch_emails({ subject: "heavy search" });
+      promise.catch(() => {});
+
+      for (let i = 0; i < 10; i++) {
+        await vi.advanceTimersByTimeAsync(5000);
+      }
+      await vi.runAllTimersAsync();
+
+      const result = await promise;
+
+      expect(callCount).toBe(11);
+      expect(result.content[0].text).toContain("is still processing");
       expect(result.content[0].text).toContain("task_id=email_task_typescript_123");
       expect(result.structuredContent?.status).toBe("pending");
       expect(result.structuredContent?.task_id).toBe("email_task_typescript_123");

package/src/tools/email.ts

@@ -302,6 +302,55 @@ function getUniqueFilepath(saveDir: string, filename: string): string {
   // mean the same logical attachment.
   return join(saveDir, filename);
 }
+async function pollEmailTask(taskId: string, apiKey: string): Promise<any> {
+  const pollUrl = `${BACKEND_URL}/api/v1/emails/tasks/${taskId}`;
+
+  for (let attempt = 0; attempt < 10; attempt++) {
+    let res: Response;
+    try {
+      res = await fetch(pollUrl, {
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          Accept: "application/json",
+        },
+        signal: AbortSignal.timeout(15_000),
+      });
+    } 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: any = await res.json();
+    const status = taskData.status;
+
+    if (status === "COMPLETED") {
+      return taskData;
+    }
+
+    if (status === "FAILED") {
+      const errorMsg = taskData.error || "Unknown internal error";
+      throw new Error(`Validation task failed on the server: ${errorMsg}`);
+    }
+
+    // Wait 5 seconds before next poll
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+  }
+
+  return null;
+}
+
 export async function search_and_fetch_emails(args: any): Promise<ToolResult> {
   const apiKey = await getCloudAuthToken();
   const maxAttachmentSizeMb: number =
@@ -316,52 +365,7 @@ export async function search_and_fetch_emails(args: any): Promise<ToolResult> {
     // ==========================================
     // PHASE 2: POLL (Wait for completion)
     // ==========================================
-    const pollUrl = `${BACKEND_URL}/api/v1/emails/tasks/${args.task_id}`;
-    let completedData: any = null;
-
-    for (let attempt = 0; attempt < 10; attempt++) {
-      let res: Response;
-      try {
-        res = await fetch(pollUrl, {
-          headers: {
-            Authorization: `Bearer ${apiKey}`,
-            Accept: "application/json",
-          },
-          signal: AbortSignal.timeout(15_000),
-        });
-      } 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: any = 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}`);
-      }
-
-      // Wait 5 seconds before next poll
-      await new Promise((resolve) => setTimeout(resolve, 5000));
-    }
+    const completedData = await pollEmailTask(args.task_id, apiKey);
 
     if (!completedData) {
       const msg = `Task ${args.task_id} is still processing. Please call \`search_and_fetch_emails\` again with task_id=${args.task_id}.`;
@@ -446,15 +450,20 @@ export async function search_and_fetch_emails(args: any): Promise<ToolResult> {
 
     if (res.status === 202 || (data && (data.status === "pending" || data.task_id) && data.type === undefined)) {
       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,
-        },
-      };
+      const completedData = await pollEmailTask(String(newTaskId), apiKey);
+
+      if (!completedData) {
+        const msg = `Task ${newTaskId} is still processing. 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,
+          },
+        };
+      }
+      data = completedData;
     }
   }