@adeu/mcp-server 1.9.0 → 1.10.1

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,22 @@ 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 +350,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 +366,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 {
@@ -533,7 +555,15 @@ server.registerTool(
 );
 server.registerTool(
   "login_to_adeu_cloud",
-  { description: "Logs the user into the Adeu Cloud backend." },
+  {
+    description:
+      "Logs the user into Adeu Cloud. Opens a browser window for SSO authentication.\n\n" +
+      "IMPORTANT — 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 — 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\n" +
+      "When the user asks which accounts or mailboxes are available, call `list_available_mailboxes` rather than naming a single account from the login response.",
+  },
   async () => {
     try {
       return (await login_to_adeu_cloud()) as any;
@@ -557,7 +587,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 +621,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 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\n" +
+      "This is the right tool to answer 'which accounts/mailboxes am I logged into?' — 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\n" +
+      "Call 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: {},
   },
   async () => {
@@ -595,6 +634,51 @@ 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) {
@@ -23,11 +24,18 @@ export async function login_to_adeu_cloud(): Promise<ToolResult> {
     if (!res.ok) throw new Error(`HTTP Error: ${res.status}`);
 
     const data: any = await res.json();
+    const email = data.email || "Unknown Email";
     return {
       content: [
         {
           type: "text",
-          text: `Login successful! Connected to Adeu Cloud as: ${data.email || "Unknown Email"}.`,
+          text:
+            `Login successful. You are now authenticated to Adeu Cloud as the user ` +
+            `who owns the provider account \`${email}\` (the account used for SSO).\n\n` +
+            `This single login grants access to ALL of this user's linked provider ` +
+            `accounts and ALL of their mailboxes for the duration of this session — ` +
+            `not just \`${email}\`. Call \`list_available_mailboxes\` to see every mailbox ` +
+            `that can be queried or drafted from.`,
         },
       ],
     };

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`",
+    );
+  });
+});