@adeu/mcp-server 1.20.0 → 1.22.0

package/src/index.ts

@@ -19,21 +19,17 @@ import {
   create_word_patch_diff,
   finalize_document,
 } from "@adeu/core";
+import { describe_illegal_control_chars } from "@adeu/core";
 
 import {
   build_paginated_response,
+  build_full_document_response,
   build_outline_response,
   build_appendix_response,
   build_search_response,
 } from "./response-builders.js";
 
-import { login_to_adeu_cloud, logout_of_adeu_cloud } from "./tools/auth.js";
-import {
-  search_and_fetch_emails,
-  create_email_draft,
-  list_available_mailboxes,
-} from "./tools/email.js";
-import { MARKDOWN_UI_URI, EMAIL_UI_URI } from "./shared.js";
+import { MARKDOWN_UI_URI } from "./shared.js";
 // Parity with Python models.py `_infer_type_in_place` + `_coerce_match_mode_in_place`.
 // The MCP boundary schema is permissive; these repairs let recoverable payloads
 // (a missing `type` that's unambiguous from the key signature, or a non-canonical
@@ -133,7 +129,7 @@ const READ_DOCX_TAIL =
   "Modes:\n- 'full' (default): paginated body content. Use page=N to navigate.\n- 'outline': heading map only — start here for large docs to plan targeted reads. Defaults to L1-L2 headings; pass outline_max_level=3-6 to see deeper structure.\n- 'appendix': defined terms, anchors, and cross-reference targets. Consult before editing legal/technical docs to avoid breaking references.";
 
 const PROCESS_BATCH_COMMON_DESC =
-  "Applies a batch of edits and review actions to a DOCX.\n\nAll changes evaluate against the ORIGINAL document state — 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";
+  "Applies a batch of edits and review actions to a DOCX.\n\nBatches apply SEQUENTIALLY: each change is validated and applied against the document state produced by the changes before it, so you may chain dependent edits within one batch (e.g. rename X to Y, then modify Y — the second edit must target Y, the text as it reads after the rename). Validation failures reject the whole batch transactionally: nothing is applied until every change resolves.\n\n";
 const PROCESS_BATCH_OPERATIONS_DESC =
   "Each item in `changes` must specify a `type`:\n1. 'modify': Search-and-replace. By default `target_text` must match uniquely (`match_mode`:'strict') — add surrounding context to disambiguate, or set `match_mode`:'first'/'all' to edit the first or every occurrence. Set `regex`:true to treat `target_text` as a regular expression (capture groups available in `new_text` as $1, $2…). `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 — use the `comment` parameter for comments.\n   • EMPTY/FORM TABLE CELLS: a blank cell has no text to match. `read_docx` renders each cell with a trailing `{#cell:<id>}` anchor — to fill a blank cell, set `target_text` to that exact anchor (e.g. '{#cell:0000005E}') and put the value in `new_text`. Do NOT try to match the pipe layout ('Date |  |  |'); the pipes are display separators, not editable text.\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 — 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 — do not reuse IDs from earlier in the conversation. The `{#cell:<id>}` anchors are stable (Word-assigned) and safe to reuse across reads.\n\n`author_name` is used for attribution on all tracked changes and comments, in both disk and Live Word modes.";
 
@@ -144,14 +140,6 @@ const gitSha = process.env.GIT_SHA || "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",
@@ -234,34 +222,6 @@ registerAppResource(
   },
 );
 
-registerAppResource(
-  server,
-  EMAIL_UI_URI,
-  EMAIL_UI_URI,
-  { mimeType: RESOURCE_MIME_TYPE, description: "Adeu Email Viewer UI" },
-  async () => {
-    let html = getAssetContent(
-      "templates",
-      "email_ui.html",
-      "<html><body>UI Template Not Found</body></html>",
-    );
-    const svg = getAssetContent("assets", "adeu.svg", "");
-
-    html = html.replace("[[ adeu_svg_code ]]", svg);
-
-    return {
-      contents: [
-        {
-          uri: EMAIL_UI_URI,
-          mimeType: RESOURCE_MIME_TYPE,
-          text: html,
-          _meta: { ui: { csp: UI_CSP } },
-        },
-      ],
-    };
-  },
-);
-
 // ==========================================
 // 2. UI-ENABLED TOOLS
 // ==========================================
@@ -294,7 +254,7 @@ registerAppTool(
         .union([z.number(), z.string()])
         .optional()
         .describe(
-          "Without `search_query`: 1-indexed document page to display (defaults to 1). With `search_query`: restricts matches to that document page (defaults to searching all pages; pass `page='all'` to be explicit).",
+          "Without `search_query`: 1-indexed document page to display (defaults to 1). With `search_query`: restricts matches to that document page (defaults to searching all pages; pass `page='all'` to be explicit). Note: pages are synthetic, length-based content chunks sized for LLM consumption — they do NOT correspond to printed Word pages or explicit page breaks.",
         ),
       outline_max_level: z.coerce
         .number()
@@ -374,13 +334,40 @@ registerAppTool(
         );
         return res as any;
       }
+      // In full mode, page='all' returns the entire document without page
+      // chrome — the round-trip artifact for text-based apply/diff
+      // (QA 2026-07-17 F1 parity with the Python CLI's --page all).
+      if (
+        mode === "full" &&
+        page !== undefined &&
+        page !== null &&
+        String(page).trim().toLowerCase() === "all"
+      ) {
+        const res = build_full_document_response(text, file_path);
+        return res as any;
+      }
       // In non-search mode, `page` defaults to 1 (show document page 1).
-      const resolvedPage =
-        page === undefined || page === null
-          ? 1
-          : typeof page === "number"
-            ? page
-            : parseInt(String(page), 10) || 1;
+      // Non-numeric values must error, not silently fall back to page 1
+      // (QA L1 parity with the Python CLI).
+      let resolvedPage = 1;
+      if (page !== undefined && page !== null) {
+        const parsed =
+          typeof page === "number" ? page : parseInt(String(page).trim(), 10);
+        if (!Number.isFinite(parsed)) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text:
+                  `Invalid page value: '${page}'. Provide a positive integer ` +
+                  `(pages are 1-indexed; 'all' is valid for mode='full' and together with search_query).`,
+              },
+            ],
+          };
+        }
+        resolvedPage = parsed;
+      }
       if (mode === "appendix") {
         const res = build_appendix_response(text, resolvedPage, file_path);
         return res as any;
@@ -488,7 +475,7 @@ server.registerTool(
       changes: z
         .array(z.union([z.string(), CHANGE_ITEM_SCHEMA]))
         .describe(
-          "Ordered list of changes to apply. Each item is an object carrying a `type` discriminator plus that type's fields (see the per-field docs and the tool description). All items evaluate against the ORIGINAL document state.",
+          "Ordered list of changes to apply. Each item is an object carrying a `type` discriminator plus that type's fields (see the per-field docs and the tool description). Items apply SEQUENTIALLY: each one evaluates against the document state produced by the items before it, so later items may target text an earlier item introduced.",
         ),
       output_path: z.string().optional().describe("Optional output path."),
       dry_run: z
@@ -516,6 +503,18 @@ server.registerTool(
             { type: "text", text: "Error: author_name cannot be empty." },
           ],
         };
+      const author_ctrl = describe_illegal_control_chars(author_name);
+      if (author_ctrl)
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `Error: author_name contains control character(s) (${author_ctrl}) ` +
+                `that cannot be stored in a DOCX. Remove them and retry.`,
+            },
+          ],
+        };
       if (!changes || changes.length === 0)
         return {
           content: [{ type: "text", text: "Error: No changes provided." }],
@@ -627,10 +626,29 @@ server.registerTool(
 
       if (!dry_run) {
         const outBuf = await doc.save();
-        fs.writeFileSync(outPath, outBuf);
+        try {
+          fs.writeFileSync(outPath, outBuf);
+        } catch (e: any) {
+          // Filesystem failures (name too long, missing directory, perms)
+          // must surface as a clear, actionable error (QA H3 parity).
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Could not write output file '${outPath}': ${e.message}`,
+              },
+            ],
+          };
+        }
       }
 
-      const res = formatBatchResult(stats, outPath, !!dry_run);
+      let res = formatBatchResult(stats, outPath, !!dry_run);
+      if (sanitizedChanges.length === 0) {
+        res =
+          `⚠️ 0 changes provided — nothing to do. The output is an unmodified copy of the original.\n\n` +
+          res;
+      }
       return { content: [{ type: "text", text: res }] };
     } catch (e: any) {
       return {
@@ -834,188 +852,6 @@ 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. The mailbox used in the original search is remembered with the short ID and re-applied automatically when you fetch or reply without specifying `mailbox_address`.\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; the directory is created automatically if it does not exist. This directory path refers to the user's native operating system, not the LLM's sandbox environment.",
-      inputSchema: z.object({
-        reasoning: z
-          .string()
-          .describe(
-            "Why do I need to search or fetch these emails? State this reason before any other parameter.",
-          ),
-        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.coerce.number().optional(),
-        folder: z.enum(["inbox", "sent", "all"]).optional(),
-        limit: z.coerce.number().default(10),
-        offset: z.coerce.number().default(0),
-        email_id: z.string().optional(),
-        working_directory: z
-          .string()
-          .optional()
-          .describe(
-            "Optional. The current working directory of the project or task. " +
-              "If provided, attachments will be saved here under an 'adeu_attachments' subfolder; " +
-              "the directory is created automatically if it does not exist. " +
-              "If omitted, attachments are saved to the system temp directory.",
-          ),
-        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.coerce
-          .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",
-    {
-      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.",
-      inputSchema: {
-        reasoning: z
-          .string()
-          .describe(
-            "Why do I need to log in to Adeu Cloud? State this reason before any other parameter.",
-          ),
-      },
-    },
-    async () => {
-      try {
-        return (await login_to_adeu_cloud()) as any;
-      } catch (e: any) {
-        return { isError: true, content: [{ type: "text", text: e.message }] };
-      }
-    },
-  );
-
-  server.registerTool(
-    "logout_of_adeu_cloud",
-    {
-      description: "Logs out of the Adeu Cloud backend.",
-      inputSchema: {
-        reasoning: z
-          .string()
-          .describe(
-            "Why do I need to log out of Adeu Cloud? State this reason before any other parameter.",
-          ),
-      },
-    },
-    async () => {
-      try {
-        return (await logout_of_adeu_cloud()) as any;
-      } catch (e: any) {
-        return { isError: true, content: [{ type: "text", text: e.message }] };
-      }
-    },
-  );
-  server.registerTool(
-    "create_email_draft",
-    {
-      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: {
-        reasoning: z
-          .string()
-          .describe(
-            "Why do I need to create this email draft? State this reason before any other parameter.",
-          ),
-        body_markdown: z.string(),
-        reply_to_email_id: z.string().optional(),
-        subject: z.string().optional(),
-        to_recipients: z.array(z.string()).optional(),
-        attachment_paths: z.array(z.string()).optional(),
-        mailbox_address: z
-          .string()
-          .optional()
-          .describe(
-            "Optional target mailbox email address to create the draft in.",
-          ),
-      },
-    },
-    async (args) => {
-      try {
-        return (await create_email_draft(args)) as any;
-      } catch (e: any) {
-        return { isError: true, content: [{ type: "text", text: e.message }] };
-      }
-    },
-  );
-  server.registerTool(
-    "list_available_mailboxes",
-    {
-      description:
-        "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: {
-        reasoning: z
-          .string()
-          .describe(
-            "Why do I need to list available mailboxes? State this reason before any other parameter.",
-          ),
-      },
-    },
-    async () => {
-      try {
-        return (await list_available_mailboxes()) as any;
-      } catch (e: any) {
-        return { isError: true, content: [{ type: "text", text: e.message }] };
-      }
-    },
-  );
-}
-
 // --- Formatter for process_document_batch ---
 export function formatBatchResult(
   stats: any,

package/src/response-builders.ts

@@ -5,6 +5,8 @@ import {
   split_structural_appendix,
   extract_outline,
   OutlineNode,
+  RegexTimeoutError,
+  userFindAllMatches,
 } from "@adeu/core";
 
 export interface ToolResult {
@@ -64,6 +66,26 @@ export function render_outline_tree(
   return lines.join("\n");
 }
 
+export function build_full_document_response(
+  text: string,
+  file_path: string,
+): ToolResult {
+  // The ENTIRE document body with no page banner, continuation footer, or
+  // appendix pointer — the round-trip artifact for text-based apply/diff
+  // (QA 2026-07-17 F1; mirrors Python's build_full_document_response).
+  const [body] = split_structural_appendix(text);
+  const ui_markdown = body;
+  const llm_content = `> **File Path:** \`${resolve(file_path)}\`\n\n${ui_markdown}`;
+  return {
+    content: [{ type: "text", text: llm_content }],
+    structuredContent: {
+      markdown: ui_markdown,
+      file_path: resolve(file_path),
+      title: basename(file_path),
+    },
+  };
+}
+
 export function build_paginated_response(
   text: string,
   page: number,
@@ -112,6 +134,11 @@ export function build_outline_response(
   outline_verbose: boolean = false,
   paragraph_offsets: Map<any, [number, number]> | null = null,
 ): ToolResult {
+  // Levels outside 1-6 are meaningless (0/negative would render a
+  // nonsensical "L1-L0" range label, QA L2). Clamp to the nearest sensible
+  // depth, mirroring the Python builder.
+  outline_max_level = Math.max(1, Math.min(outline_max_level, 6));
+
   const [body] = split_structural_appendix(projected_text);
   const pagination_result = paginate(body, "");
 
@@ -229,9 +256,11 @@ export function build_search_response(
   // the same broken regex.
   let regexDowngradedNote = "";
   let regex: RegExp;
+  let isUserRegex = false;
   if (search_regex) {
     try {
       regex = new RegExp(search_query, flags);
+      isUserRegex = true;
     } catch (e: any) {
       regexDowngradedNote =
         `> **Note:** \`${search_query}\` is not a valid regular expression ` +
@@ -243,7 +272,26 @@ export function build_search_response(
     regex = new RegExp(escapeRegExp(search_query), flags);
   }
 
-  const allMatches = Array.from(body.matchAll(regex));
+  // Patterns that blow the matching time budget (catastrophic backtracking,
+  // QA 2026-07-17 F5) get the same literal downgrade as invalid patterns —
+  // for a read-only search, degraded results beat a hung event loop.
+  let allMatches: Array<{ 0: string; index?: number }>;
+  if (isUserRegex) {
+    try {
+      allMatches = userFindAllMatches(search_query, body, flags).map((m) => ({
+        0: body.slice(m.start, m.end),
+        index: m.start,
+      }));
+    } catch (e: any) {
+      if (!(e instanceof RegexTimeoutError)) throw e;
+      regexDowngradedNote =
+        `> **Note:** \`${search_query}\` was searched as literal text instead of as ` +
+        `a regular expression: ${e.message}`;
+      allMatches = Array.from(body.matchAll(new RegExp(escapeRegExp(search_query), flags)));
+    }
+  } else {
+    allMatches = Array.from(body.matchAll(regex));
+  }
 
   // Compute document pagination once — needed for both annotation and filtering.
   const pag_res = paginate(body, "");

package/src/shared.ts

@@ -1,7 +1,2 @@
 // FILE: node/packages/mcp-server/src/shared.ts
-export const FRONTEND_URL =
-  process.env.ADEU_FRONTEND_URL || "https://app.adeu.ai";
-export const BACKEND_URL =
-  process.env.ADEU_BACKEND_URL || "https://app.adeu.ai";
 export const MARKDOWN_UI_URI = "ui://adeu/markdown-ui";
-export const EMAIL_UI_URI = "ui://adeu/email-ui";