@adeu/mcp-server 1.9.0 → 1.10.0

package/src/index.ts

@@ -241,7 +241,17 @@ registerAppTool(
   {
     title: "Search & Fetch Emails",
     description:
-      "Searches the user's live email inbox. Returns previews. Call again with `email_id` to fetch the full body.",
+      "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(),
@@ -258,6 +268,12 @@ registerAppTool(
         .string()
         .optional()
         .describe("Optional target mailbox email address to search within."),
+      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 } },
   },
@@ -267,12 +283,7 @@ registerAppTool(
     } catch (e: any) {
       return {
         isError: true,
-        content: [
-          {
-            type: "text",
-            text: `Error executing tool search_and_fetch_emails: ${e.message}`,
-          },
-        ],
+        content: [{ type: "text", text: e.message }],
       };
     }
   },
@@ -297,9 +308,14 @@ server.registerTool(
         .array(z.any())
         .describe("List of changes to apply. Each change must specify 'type'."),
       output_path: z.string().optional().describe("Optional output path."),
+      dry_run: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("If True, simulates the changes and returns a detailed preview report without modifying any files."),
     },
   },
-  async ({ original_docx_path, author_name, changes, output_path }) => {
+  async ({ original_docx_path, author_name, changes, output_path, dry_run }) => {
     try {
       if (!author_name || !author_name.trim())
         return {
@@ -326,7 +342,7 @@ server.registerTool(
 
       let stats;
       try {
-        stats = engine.process_batch(changes);
+        stats = engine.process_batch(changes, dry_run);
       } catch (e: any) {
         if (e instanceof BatchValidationError) {
           return {
@@ -342,14 +358,12 @@ server.registerTool(
         throw e;
       }
 
-      const outBuf = await doc.save();
-
-      fs.writeFileSync(outPath, outBuf);
-
-      let res = `Batch complete. Saved to: ${outPath}\nActions: ${stats.actions_applied} applied, ${stats.actions_skipped} skipped.\nEdits: ${stats.edits_applied} applied, ${stats.edits_skipped} skipped.`;
-      if (stats.skipped_details?.length > 0) {
-        res += `\n\nSkipped Details:\n${stats.skipped_details.join("\n")}`;
+      if (!dry_run) {
+        const outBuf = await doc.save();
+        fs.writeFileSync(outPath, outBuf);
       }
+
+      const res = formatBatchResult(stats, outPath, !!dry_run);
       return { content: [{ type: "text", text: res }] };
     } catch (e: any) {
       return {
@@ -557,7 +571,14 @@ server.registerTool(
 server.registerTool(
   "create_email_draft",
   {
-    description: "Creates an email draft in the user's native draft box.",
+    description:
+      "Creates an email draft in the user's native draft box (Outlook Drafts or Gmail Drafts).\n\n" +
+      "TWO MODES:\n" +
+      "1. Reply mode: pass `reply_to_email_id` to create a threaded reply. The draft inherits subject, recipients, and threading headers from the original — do NOT pass `subject` or `to_recipients`.\n" +
+      "2. 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 — 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 — those local paths can be passed directly here.",
     inputSchema: {
       body_markdown: z.string(),
       reply_to_email_id: z.string().optional(),
@@ -584,7 +605,9 @@ server.registerTool(
   "list_available_mailboxes",
   {
     description:
-      "Lists all personal and shared delegated mailboxes configured for the authenticated profile. Use this to discover valid email addresses to scope search and draft operations.",
+      "Lists all personal and shared delegated mailboxes the authenticated user has access to. Returns each mailbox's `email_address`, `display_name`, auto-processing settings, and write-back preference.\n\n" +
+      "Call this FIRST when the user mentions a specific mailbox or shared inbox by name, 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.\n\n" +
+      "Omitting `mailbox_address` on those tools targets the user's primary personal mailbox.",
     inputSchema: {},
   },
   async () => {
@@ -595,6 +618,50 @@ server.registerTool(
     }
   },
 );
+// --- Formatter for process_document_batch ---
+export function formatBatchResult(
+  stats: any,
+  outPath: string,
+  dry_run: boolean,
+): string {
+  let res = "";
+  if (dry_run) {
+    res = `Dry-run simulation complete.\n`;
+  } else {
+    res = `Batch complete. Saved to: ${outPath}\n`;
+  }
+  res += `Actions: ${stats.actions_applied} applied, ${stats.actions_skipped} skipped.\n`;
+  res += `Edits: ${stats.edits_applied} applied, ${stats.edits_skipped} skipped.\n`;
+
+  if (stats.edits && stats.edits.length > 0) {
+    res += "\nDetailed Edit Reports:\n";
+    for (let i = 0; i < stats.edits.length; i++) {
+      const report = stats.edits[i];
+      const status_indicator = report.status === "applied" ? "✅ [applied]" : "❌ [failed]";
+      res += `Edit ${i + 1} ${status_indicator}:\n`;
+      res += `  Target: '${report.target_text}'\n`;
+      res += `  New text: '${report.new_text}'\n`;
+      if (report.warning) {
+        res += `  Warning: ${report.warning}\n`;
+      }
+      if (report.error) {
+        res += `  Error: ${report.error}\n`;
+      }
+      if (report.critic_markup) {
+        res += `  Preview (CriticMarkup): ${report.critic_markup}\n`;
+      }
+      if (report.clean_text) {
+        res += `  Clean text preview: ${report.clean_text}\n`;
+      }
+    }
+  }
+
+  if (stats.skipped_details && stats.skipped_details.length > 0) {
+    res += `\n\nSkipped Details:\n${stats.skipped_details.join("\n")}`;
+  }
+  return res;
+}
+
 // --- Startup ---
 async function main() {
   const transport = new StdioServerTransport();

package/src/tools/auth.ts

@@ -12,6 +12,7 @@ export async function login_to_adeu_cloud(): Promise<ToolResult> {
         Authorization: `Bearer ${apiKey}`,
         Accept: "application/json",
       },
+      signal: AbortSignal.timeout(15_000),
     });
 
     if (res.status === 401) {

package/src/tools/email.test.ts

@@ -0,0 +1,258 @@
+// FILE: node/packages/mcp-server/src/tools/email.test.ts
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { search_and_fetch_emails, list_available_mailboxes } from "./email.js";
+
+// Mock the Auth module so tests bypass active browser logins
+vi.mock("../desktop-auth.js", () => {
+  return {
+    getCloudAuthToken: vi.fn().mockResolvedValue("mock_token_abc"),
+    DesktopAuthManager: {
+      getApiKey: vi.fn().mockReturnValue("mock_token_abc"),
+      clearApiKey: vi.fn(),
+    },
+  };
+});
+
+describe("Node Email Tools Finding #2 and Finding #6 tests", () => {
+  const originalFetch = global.fetch;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("Finding #6: Correctly handles stale msg_ short IDs inside tool boundary", async () => {
+    const result = await search_and_fetch_emails({
+      email_id: "msg_stale99",
+    });
+
+    expect(result.isError).toBe(true);
+    const text = result.content[0].text;
+    expect(text).toContain("is not in the local cache");
+    expect(text).toContain("evicted, or it came from a different machine");
+    expect(text).toContain("Re-run search_and_fetch_emails with filters");
+  });
+
+  it("Finding #6: Maps backend Mailbox Not Found 404 error to Node boundary ToolError", async () => {
+    // Stub fetch to simulate a 404 response with Mailbox error body
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+      text: async () =>
+        JSON.stringify({
+          detail: "Mailbox 'bogus@nowhere.invalid' not found.",
+        }),
+    } as Response);
+
+    await expect(
+      search_and_fetch_emails({ mailbox_address: "bogus@nowhere.invalid" }),
+    ).rejects.toThrowError(
+      "Cloud search failed (HTTP 404): The mailbox 'bogus@nowhere.invalid' 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`.",
+    );
+  });
+
+  it("Finding #6: Maps backend Email Not Found 404 error to Node boundary ToolError", async () => {
+    // Stub fetch to simulate 404 for an invalid adeu_ ID (which bypasses local cache checks)
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+      text: async () => JSON.stringify({ detail: "Email not found." }),
+    } as Response);
+
+    await expect(
+      search_and_fetch_emails({ email_id: "adeu_9999" }),
+    ).rejects.toThrowError(
+      "Cloud search failed (HTTP 404): 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 — 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.",
+    );
+  });
+
+  it("Finding #2: Asserts correct Markdown parity and Personal Mailbox fallback on list_available_mailboxes", async () => {
+    // Stub fetch to return one null-display mailbox and one alphabetical secondary mailbox
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => [
+        {
+          email_address: "secondary@adeu.ai",
+          display_name: "Secondary Mailbox",
+          auto_process_enabled: false,
+          write_back_preference: "INTERNAL",
+        },
+        {
+          email_address: "primary@adeu.ai",
+          display_name: null, // Tests 'Personal Mailbox' fallback
+          auto_process_enabled: true,
+          write_back_preference: "DRAFT",
+        },
+      ],
+    } as Response);
+
+    const result = await list_available_mailboxes();
+    expect(result.isError).toBeFalsy();
+
+    const output = result.content[0].text;
+
+    // Verify preamble parity
+    expect(output).toContain("### Connected Mailboxes");
+    expect(output).toContain(
+      "Below is the list of connected mailboxes you have access to.",
+    );
+
+    // Verify Fallback formatting
+    expect(output).toContain("**Personal Mailbox**");
+
+    // Verify deterministic alphabetical sorting by email address (primary before secondary)
+    const idxPrimary = output.indexOf("primary@adeu.ai");
+    const idxSecondary = output.indexOf("secondary@adeu.ai");
+    expect(idxPrimary).not.toBe(-1);
+    expect(idxSecondary).not.toBe(-1);
+    expect(idxPrimary).toBeLessThan(idxSecondary);
+
+    // Verify labels formatting matches Python exactly
+    expect(output).toContain("- **Email Address**:");
+    expect(output).toContain("- **Auto-Processing**:");
+    expect(output).toContain("- **Write-Back Mode**:");
+  });
+
+  it("Finding #6: Gracefully maps generic, unmapped server errors on search_and_fetch_emails", async () => {
+    // Simulate generic HTTP 500 error
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 500,
+      text: async () =>
+        JSON.stringify({ detail: "Database connection failed." }),
+    } as Response);
+
+    await expect(search_and_fetch_emails({ limit: 10 })).rejects.toThrowError(
+      "Cloud search failed (HTTP 500): Database connection failed.",
+    );
+  });
+
+  it("Finding #6: Converts abort/timeout errors to actionable ToolErrors on search_and_fetch_emails", async () => {
+    // Simulate a native fetch Timeout/AbortError
+    const timeoutError = new Error("The operation was aborted.");
+    timeoutError.name = "AbortError";
+    global.fetch = vi.fn().mockRejectedValue(timeoutError);
+
+    await expect(search_and_fetch_emails({ limit: 10 })).rejects.toThrowError(
+      "Email search timed out after 45s. The mail provider (Outlook/Gmail) may be slow.",
+    );
+  });
+
+  it("Findings #3, #9, and #11: Asserts preview pagination, auto-escalation note, and downstream tool suggests", async () => {
+    // --- Scenario 1: Previews listing with limit met (Finding #3 pagination hint) ---
+    const mockPreviewsPayload = {
+      type: "previews",
+      previews: [
+        {
+          id: "id1",
+          subject: "Subject 1",
+          sender_name: "Sender 1",
+          sender_email: "s1@adeu.ai",
+          received_datetime: "2026-01-01T12:00:00Z",
+          preview_text: "Text 1",
+          has_attachments: false,
+          is_read: true,
+        },
+        {
+          id: "id2",
+          subject: "Subject 2",
+          sender_name: "Sender 2",
+          sender_email: "s2@adeu.ai",
+          received_datetime: "2026-01-01T12:00:00Z",
+          preview_text: "Text 2",
+          has_attachments: false,
+          is_read: true,
+        },
+      ],
+    };
+
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => mockPreviewsPayload,
+    } as Response);
+
+    const resPreviews = await search_and_fetch_emails({
+      subject: "Invoice",
+      limit: 2,
+      offset: 0,
+    });
+
+    const previewsText = resPreviews.content[0].text;
+    expect(previewsText).toContain(
+      "*(If you need to see more results, call this tool again with offset=2)*",
+    );
+
+    // --- Scenario 2: Single result auto-escalation (Finding #11 banner notice) ---
+    const mockFullEmailPayload = {
+      type: "full_email",
+      full_email: {
+        id: "adeu_12345",
+        subject: "Contract Review Required",
+        sender_name: "Legal",
+        sender_email: "legal@adeu.ai",
+        received_datetime: "2026-01-01T12:00:00Z",
+        body_html: "<p>Please look at this document.</p>",
+        is_thread: false,
+        attachments: [],
+      },
+    };
+
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => mockFullEmailPayload,
+    } as Response);
+
+    const resEscalation = await search_and_fetch_emails({
+      subject: "Contract Review Required",
+    });
+
+    const escalationText = resEscalation.content[0].text;
+    expect(
+      escalationText.startsWith(
+        "_(Search returned exactly one result; auto-fetched full email below.)_",
+      ),
+    ).toBe(true);
+
+    // --- Scenario 3: Suggestions for attachments (Finding #9 downstream hint) ---
+    const mockAttachmentsPayload = {
+      type: "full_email",
+      full_email: {
+        id: "adeu_12345",
+        subject: "Contract Attachment",
+        sender_name: "Legal",
+        sender_email: "legal@adeu.ai",
+        received_datetime: "2026-01-01T12:00:00Z",
+        body_html: "<p>Please see attachment.</p>",
+        is_thread: false,
+        attachments: [
+          {
+            filename: "draft_contract.docx",
+            size_bytes: 1024,
+            base64_data: Buffer.from("dummy docx contents").toString("base64"),
+          },
+        ],
+      },
+    };
+
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => mockAttachmentsPayload,
+    } as Response);
+
+    const resAttachments = await search_and_fetch_emails({
+      email_id: "adeu_12345",
+    });
+
+    const attachmentsText = resAttachments.content[0].text;
+    expect(attachmentsText).toContain(
+      "You can now use tools like `read_docx`, `diff_docx_files`, or `finalize_document`",
+    );
+  });
+});