@adeu/mcp-server 1.18.0 → 1.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adeu/mcp-server",
-  "version": "1.18.0",
+  "version": "1.18.2",
   "description": "",
   "mcpName": "ai.adeu/adeu",
   "main": "./dist/index.js",
@@ -31,7 +31,7 @@
   "license": "MIT",
   "type": "module",
   "dependencies": {
-    "@adeu/core": "^1.18.0",
+    "@adeu/core": "^1.18.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@modelcontextprotocol/ext-apps": "^1.0.0",
     "zod": "^3.23.8"

package/scripts/verify-reasoning-order.mjs

@@ -0,0 +1,113 @@
+// FILE: node/packages/mcp-server/scripts/verify-reasoning-order.mjs
+// Boots the compiled MCP server over stdio, runs initialize + tools/list, and
+// asserts that EVERY tool declares `reasoning` as (a) the first property and
+// (b) a required field. Exit code 0 = all good, 1 = at least one violation.
+//
+// Usage: node scripts/verify-reasoning-order.mjs
+// Requires: npm run build (dist/index.js must exist).
+
+import { spawn } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverPath = resolve(__dirname, "../dist/index.js");
+
+if (!existsSync(serverPath)) {
+  console.error(
+    `❌ Server not built: ${serverPath}. Run 'npm run build' first.`,
+  );
+  process.exit(1);
+}
+
+const proc = spawn("node", [serverPath]);
+const pending = new Map();
+let rpcId = 100;
+let buf = "";
+
+proc.stdout.on("data", (data) => {
+  buf += data.toString();
+  let idx;
+  while ((idx = buf.indexOf("\n")) !== -1) {
+    const line = buf.slice(0, idx).trim();
+    buf = buf.slice(idx + 1);
+    if (!line.startsWith("{")) continue;
+    try {
+      const msg = JSON.parse(line);
+      if (msg.id !== undefined && pending.has(msg.id)) {
+        const cb = pending.get(msg.id);
+        pending.delete(msg.id);
+        cb(msg);
+      }
+    } catch {
+      /* ignore partial/non-JSON */
+    }
+  }
+});
+
+function rpc(method, params) {
+  const id = ++rpcId;
+  return new Promise((res, rej) => {
+    const t = setTimeout(() => rej(new Error(`RPC timeout: ${method}`)), 15000);
+    pending.set(id, (m) => {
+      clearTimeout(t);
+      res(m);
+    });
+    proc.stdin.write(
+      JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n",
+    );
+  });
+}
+
+function notify(method, params) {
+  proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+}
+
+try {
+  await rpc("initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "verify-reasoning", version: "0.0.0" },
+  });
+  notify("notifications/initialized", {});
+
+  const list = await rpc("tools/list", {});
+  const tools = list.result?.tools ?? [];
+
+  if (tools.length === 0) {
+    console.error("❌ tools/list returned no tools.");
+    process.exit(1);
+  }
+
+  let failures = 0;
+  for (const tool of tools) {
+    const schema = tool.inputSchema ?? {};
+    const props = schema.properties ?? {};
+    const keys = Object.keys(props);
+    const required = schema.required ?? [];
+
+    const firstKey = keys[0];
+    const isFirst = firstKey === "reasoning";
+    const isRequired = required.includes("reasoning");
+    const isString = props.reasoning?.type === "string";
+
+    if (isFirst && isRequired && isString) {
+      console.log(`✅ ${tool.name}: reasoning is first + required (string)`);
+    } else {
+      failures++;
+      console.error(
+        `❌ ${tool.name}: reasoning check failed ` +
+          `(firstKey=${firstKey}, required=${isRequired}, string=${isString})`,
+      );
+    }
+  }
+
+  console.error(`\n${tools.length - failures}/${tools.length} tools passed.`);
+  proc.kill();
+  process.exit(failures === 0 ? 0 : 1);
+} catch (e) {
+  console.error(`❌ ${e.message}`);
+  proc.kill();
+  process.exit(1);
+}

package/src/index.ts

@@ -34,7 +34,56 @@ import {
   list_available_mailboxes,
 } from "./tools/email.js";
 import { MARKDOWN_UI_URI, EMAIL_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
+// `match_mode`) succeed instead of failing the whole-array Zod parse with an
+// opaque -32602. Anything still un-inferrable is caught by the handler guard
+// below and reported per-index; anything that doesn't apply to the document is
+// caught by the engine's validate_edits. Mirrors how Python repairs in a
+// BeforeValidator ahead of its (strict) discriminated union.
+const MATCH_MODE_SYNONYMS: Record<string, "strict" | "first" | "all"> = {
+  strict: "strict",
+  first: "first",
+  all: "all",
+  first_only: "first",
+  firstonly: "first",
+  "first-only": "first",
+  all_occurrences: "all",
+  alloccurrences: "all",
+  "all-occurrences": "all",
+  every: "all",
+};
+
+function coerceChangeItemInPlace(item: any): void {
+  if (item === null || typeof item !== "object" || Array.isArray(item)) return;
+
+  // Infer a missing `type` ONLY when exactly one variant fits unambiguously.
+  // Deliberately do NOT infer from `target_id` alone (accept vs reject is a
+  // semantic choice) or `target_text` alone (delete_row vs empty-new_text
+  // modify). Those stay absent and are rejected with a clear message.
+  if (!("type" in item) || item.type === undefined || item.type === null) {
+    if ("cells" in item) item.type = "insert_row";
+    else if ("text" in item && "target_id" in item) item.type = "reply";
+    else if ("target_text" in item && "new_text" in item) item.type = "modify";
+  }
 
+  // Normalize match_mode: canonical passes through, synonyms map, anything else
+  // (help-string echo "strict, first, or all", empty, non-string) is dropped so
+  // the engine's "strict" default applies. Never coerce junk to "all" — that
+  // would silently mass-edit; defaulting to strict fails safe with an
+  // ambiguity error instead.
+  if ("match_mode" in item) {
+    const raw = item.match_mode;
+    if (typeof raw !== "string") {
+      delete item.match_mode;
+    } else {
+      const mapped = MATCH_MODE_SYNONYMS[raw.trim().toLowerCase()];
+      if (mapped === undefined) delete item.match_mode;
+      else item.match_mode = mapped;
+    }
+  }
+}
 function readFileBytesOrThrow(filePath: string): Buffer {
   try {
     return readFileSync(filePath);
@@ -223,6 +272,11 @@ registerAppTool(
     title: "Read DOCX",
     description: READ_DOCX_COMMON_DESC + READ_DOCX_TAIL,
     inputSchema: z.object({
+      reasoning: z
+        .string()
+        .describe(
+          "Why do I need to read this docx document? State this reason before any other parameter.",
+        ),
       file_path: z.string().describe("Absolute path to the DOCX file."),
       clean_view: z
         .boolean()
@@ -270,6 +324,7 @@ registerAppTool(
     _meta: { ui: { resourceUri: MARKDOWN_UI_URI } },
   },
   async ({
+    reasoning,
     file_path,
     clean_view,
     mode,
@@ -281,6 +336,7 @@ registerAppTool(
     search_case_sensitive,
   }) => {
     try {
+      void reasoning;
       const buf = readFileBytesOrThrow(file_path);
 
       if (mode === "outline") {
@@ -359,8 +415,9 @@ const CHANGE_ITEM_SCHEMA = z
   .object({
     type: z
       .enum(["modify", "accept", "reject", "reply", "insert_row", "delete_row"])
+      .optional()
       .describe(
-        "Change kind: 'modify' (search-and-replace), 'accept'/'reject' (resolve a tracked change by id), 'reply' (reply to a comment by id), 'insert_row'/'delete_row' (table edits; disk mode only).",
+        "Change kind: 'modify' (search-and-replace), 'accept'/'reject' (resolve a tracked change by id), 'reply' (reply to a comment by id), 'insert_row'/'delete_row' (table edits; disk mode only). If omitted it is inferred when unambiguous from the other fields.",
       ),
     target_text: z
       .string()
@@ -417,6 +474,11 @@ server.registerTool(
   {
     description: PROCESS_BATCH_COMMON_DESC + PROCESS_BATCH_OPERATIONS_DESC,
     inputSchema: {
+      reasoning: z
+        .string()
+        .describe(
+          "Why do I need to apply these changes to the document? State this reason before any other parameter.",
+        ),
       original_docx_path: z
         .string()
         .describe("Absolute path to the source file."),
@@ -439,6 +501,7 @@ server.registerTool(
     },
   },
   async ({
+    reasoning,
     original_docx_path,
     author_name,
     changes,
@@ -446,6 +509,7 @@ server.registerTool(
     dry_run,
   }) => {
     try {
+      void reasoning;
       if (!author_name || !author_name.trim())
         return {
           content: [
@@ -465,19 +529,63 @@ server.registerTool(
       // bundled. Genuine objects and unparseable strings pass through
       // untouched so validation surfaces a clear error rather than crashing.
       const sanitizedChanges = changes.map((item: any) => {
+        let obj: any = item;
         if (typeof item === "string") {
           try {
             const parsed = JSON.parse(item);
-            if (parsed !== null && typeof parsed === "object") {
-              return parsed;
-            }
-            return item;
+            obj = parsed !== null && typeof parsed === "object" ? parsed : item;
           } catch {
-            return item;
+            obj = item;
           }
         }
-        return item;
+        // Repair recoverable payloads (infer type, normalize match_mode) the
+        // same way Python does before its union validation.
+        if (obj !== null && typeof obj === "object" && !Array.isArray(obj)) {
+          coerceChangeItemInPlace(obj);
+        }
+        return obj;
+      });
+
+      // Boundary guard, scoped narrowly: after inference, reject only an OBJECT
+      // that still carries no resolvable `type`. Strings, nulls, and non-objects
+      // are intentionally left for the engine's validate_edits to report
+      // ("Invalid change format… received a primitive"), keeping the engine the
+      // single authority for those and avoiding a competing error surface.
+      // A typeless object is the one case the engine can't cleanly reject (with
+      // `type` now optional it would fall into the edits bucket as a no-op), so
+      // it is caught here with an actionable, per-index message.
+      const VALID_TYPES = new Set([
+        "modify",
+        "accept",
+        "reject",
+        "reply",
+        "insert_row",
+        "delete_row",
+      ]);
+      const typeErrors: string[] = [];
+      sanitizedChanges.forEach((c: any, i: number) => {
+        if (
+          c !== null &&
+          typeof c === "object" &&
+          !Array.isArray(c) &&
+          (!c.type || !VALID_TYPES.has(c.type))
+        ) {
+          typeErrors.push(
+            `- Change ${i + 1}: missing or unrecognized "type". Use one of: modify (needs target_text + new_text), accept/reject (needs target_id like "Chg:12"), reply (needs target_id like "Com:5" + text), insert_row (needs target_text + cells), delete_row (needs target_text). Received keys: [${Object.keys(c).join(", ")}].`,
+          );
+        }
       });
+      if (typeErrors.length > 0) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Batch rejected. Some changes are malformed:\n\n${typeErrors.join("\n")}`,
+            },
+          ],
+        };
+      }
 
       let outPath = output_path;
       if (!outPath) {
@@ -539,12 +647,18 @@ server.registerTool(
     description:
       "Accepts all tracked changes and removes all comments in a single operation.",
     inputSchema: {
+      reasoning: z
+        .string()
+        .describe(
+          "Why do I need to accept all changes in this document? State this reason before any other parameter.",
+        ),
       docx_path: z.string().describe("Absolute path to the DOCX file."),
       output_path: z.string().optional().describe("Optional output path."),
     },
   },
-  async ({ docx_path, output_path }) => {
+  async ({ reasoning, docx_path, output_path }) => {
     try {
+      void reasoning;
       let outPath = output_path;
       if (!outPath) {
         const ext = extname(docx_path);
@@ -582,6 +696,11 @@ server.registerTool(
   {
     description: DIFF_DOCX_DESC,
     inputSchema: {
+      reasoning: z
+        .string()
+        .describe(
+          "Why do I need to diff these two documents? State this reason before any other parameter.",
+        ),
       original_path: z
         .string()
         .describe("Absolute path to the baseline DOCX file."),
@@ -596,8 +715,9 @@ server.registerTool(
         ),
     },
   },
-  async ({ original_path, modified_path, compare_clean }) => {
+  async ({ reasoning, original_path, modified_path, compare_clean }) => {
     try {
+      void reasoning;
       const origBuf = readFileBytesOrThrow(original_path);
       const modBuf = readFileBytesOrThrow(modified_path);
 
@@ -629,6 +749,11 @@ server.registerTool(
     description:
       "Prepares a document for external distribution or e-signature. Note: in this zero-dependency environment, protection_mode='encrypt' is unsupported and falls back to a native read-only lock; export_pdf and password are ignored.",
     inputSchema: {
+      reasoning: z
+        .string()
+        .describe(
+          "Why do I need to finalize this document? State this reason before any other parameter.",
+        ),
       file_path: z.string().describe("Absolute path to the DOCX file."),
       output_path: z.string().optional().describe("Optional output path."),
       sanitize_mode: z
@@ -659,6 +784,7 @@ server.registerTool(
     },
   },
   async ({
+    reasoning,
     file_path,
     output_path,
     sanitize_mode,
@@ -668,6 +794,7 @@ server.registerTool(
     export_pdf,
   }) => {
     try {
+      void reasoning;
       let outPath = output_path;
       if (!outPath) {
         const ext = extname(file_path);
@@ -726,6 +853,11 @@ if (!isDocxOnly) {
         "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({
+        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(),
@@ -776,6 +908,13 @@ if (!isDocxOnly) {
         "- 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 {
@@ -788,7 +927,16 @@ if (!isDocxOnly) {
 
   server.registerTool(
     "logout_of_adeu_cloud",
-    { description: "Logs out of the Adeu Cloud backend." },
+    {
+      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;
@@ -809,6 +957,11 @@ if (!isDocxOnly) {
         "`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(),
@@ -837,7 +990,13 @@ if (!isDocxOnly) {
         "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: {},
+      inputSchema: {
+        reasoning: z
+          .string()
+          .describe(
+            "Why do I need to list available mailboxes? State this reason before any other parameter.",
+          ),
+      },
     },
     async () => {
       try {

package/src/mcp.bugs.test.ts

@@ -94,6 +94,7 @@ describe("Resolved Bugs MCP Server Verification", () => {
       {
         name: "process_document_batch",
         arguments: {
+          reasoning: "test",
           original_docx_path: cleanDocPath,
           author_name: "Agent",
           changes: [],
@@ -114,6 +115,7 @@ describe("Resolved Bugs MCP Server Verification", () => {
       {
         name: "diff_docx_files",
         arguments: {
+          reasoning: "test",
           original_path: cleanDocPath,
           modified_path: dirtyDocPath,
           compare_clean: true,
@@ -132,6 +134,7 @@ describe("Resolved Bugs MCP Server Verification", () => {
       {
         name: "diff_docx_files",
         arguments: {
+          reasoning: "test",
           original_path: cleanDocPath,
           modified_path: dirtyDocPath,
           compare_clean: false,
@@ -148,7 +151,10 @@ describe("Resolved Bugs MCP Server Verification", () => {
       "tools/call",
       {
         name: "read_docx",
-        arguments: { file_path: join(tmpdir(), "DEF_DOES_NOT_EXIST.docx") },
+        arguments: {
+          reasoning: "test",
+          file_path: join(tmpdir(), "DEF_DOES_NOT_EXIST.docx"),
+        },
       },
       104,
     );
@@ -173,6 +179,7 @@ describe("Resolved Bugs MCP Server Verification", () => {
       {
         name: "process_document_batch",
         arguments: {
+          reasoning: "test",
           original_docx_path: cleanDocPath,
           author_name: "Agent",
           changes: [
@@ -202,6 +209,7 @@ describe("Resolved Bugs MCP Server Verification", () => {
       {
         name: "process_document_batch",
         arguments: {
+          reasoning: "test",
           original_docx_path: cleanDocPath,
           author_name: "Agent",
           changes: [
@@ -227,6 +235,7 @@ describe("Resolved Bugs MCP Server Verification", () => {
       {
         name: "read_docx",
         arguments: {
+          reasoning: "test",
           file_path: cleanDocPath,
           page: "1",
           outline_max_level: "3",

package/src/mcp.cloud.test.ts

@@ -83,7 +83,7 @@ describe("Cloud Auth & Email Tools MCP Verification", () => {
       "tools/call",
       {
         name: "search_and_fetch_emails",
-        arguments: { subject: "Invoice" },
+        arguments: { reasoning: "test", subject: "Invoice" },
       },
       201,
     );
@@ -97,7 +97,7 @@ describe("Cloud Auth & Email Tools MCP Verification", () => {
       "tools/call",
       {
         name: "list_available_mailboxes",
-        arguments: {},
+        arguments: { reasoning: "test" },
       },
       204,
     );
@@ -116,6 +116,7 @@ describe("Cloud Auth & Email Tools MCP Verification", () => {
       {
         name: "create_email_draft",
         arguments: {
+          reasoning: "test",
           body_markdown: "Hello World",
           // Missing reply_to_email_id AND subject/to_recipients
         },
@@ -137,7 +138,7 @@ describe("Cloud Auth & Email Tools MCP Verification", () => {
       "tools/call",
       {
         name: "logout_of_adeu_cloud",
-        arguments: {},
+        arguments: { reasoning: "test" },
       },
       203,
     );

package/src/mcp.schema-gaps.test.ts

@@ -251,6 +251,7 @@ describe("MCP tools — advertised schema/docs match real capability", () => {
       const res = await rpc("tools/call", {
         name: "process_document_batch",
         arguments: {
+          reasoning: "test",
           original_docx_path: pdbFixture,
           author_name: "Schema Gap Test",
           changes: [
@@ -275,6 +276,7 @@ describe("MCP tools — advertised schema/docs match real capability", () => {
       const res = await rpc("tools/call", {
         name: "process_document_batch",
         arguments: {
+          reasoning: "test",
           original_docx_path: pdbFixture,
           author_name: "Schema Gap Test",
           changes: [
@@ -330,6 +332,7 @@ describe("MCP tools — advertised schema/docs match real capability", () => {
       const res = await rpc("tools/call", {
         name: "diff_docx_files",
         arguments: {
+          reasoning: "test",
           original_path: diffOrig,
           modified_path: diffMod,
           compare_clean: true,
@@ -368,6 +371,7 @@ describe("MCP tools — advertised schema/docs match real capability", () => {
       const res = await rpc("tools/call", {
         name: "finalize_document",
         arguments: {
+          reasoning: "test",
           file_path: finalizeInput,
           output_path: tempOut("finalize_encrypt"),
           protection_mode: "encrypt",