@adeu/mcp-server 1.15.2 → 1.16.0

package/package.json

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

package/src/index.ts

@@ -83,10 +83,10 @@ const READ_DOCX_TAIL =
 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";
 const PROCESS_BATCH_OPERATIONS_DESC =
-  "Each item in `changes` must specify a `type`:\n1. 'modify': Search-and-replace. `target_text` must uniquely match — include surrounding context if the phrase is ambiguous. `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.\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.\n\n`author_name` is used for attribution on all tracked changes and comments, in both disk and Live Word modes.";
+  "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.\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.\n\n`author_name` is used for attribution on all tracked changes and comments, in both disk and Live Word modes.";
 
 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.";
+  "Compares two DOCX files and returns a compact `@@ Word Patch @@` diff — Adeu's token-level, sub-word patch format — of their text content. Useful for analyzing differences between versions before editing.";
 
 const gitSha = process.env.GIT_SHA || "unknown";
 const packageVersion = process.env.PACKAGE_VERSION || "unknown";
@@ -110,7 +110,9 @@ const server = new McpServer({
 const originalRegisterTool = server.registerTool.bind(server);
 server.registerTool = (name: string, schema: any, handler?: any) => {
   if (schema && typeof schema === "object") {
-    if (schema.description) {
+    // Idempotent: UI tools route through BOTH this wrapper and the
+    // registerAppTool wrapper, so guard against stamping the tag twice.
+    if (schema.description && !schema.description.includes(buildTag.trim())) {
       schema.description = schema.description.trim() + buildTag;
     }
   }
@@ -344,6 +346,69 @@ registerAppTool(
 // 3. HEADLESS TOOLS (No UI)
 // ==========================================
 
+// Typed shape for a single `process_document_batch` change. This makes the six
+// DocumentChange variants — and the modify-only `match_mode`/`regex` options —
+// discoverable from the tool schema itself, instead of prose alone. A bare
+// string is still accepted (and normalized in-handler) so double-serialized
+// payloads from some LLM clients keep working; only `type` is required, all
+// other fields are optional, and unknown keys pass through untouched.
+const CHANGE_ITEM_SCHEMA = z
+  .object({
+    type: z
+      .enum(["modify", "accept", "reject", "reply", "insert_row", "delete_row"])
+      .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).",
+      ),
+    target_text: z
+      .string()
+      .optional()
+      .describe(
+        "modify / insert_row / delete_row: the existing text to locate (interpreted as a regex when regex=true).",
+      ),
+    new_text: z
+      .string()
+      .optional()
+      .describe(
+        "modify: replacement text. Supports Markdown (headings, **bold**, _italic_, '\\n\\n' paragraph splits); empty string deletes. Regex capture groups are available as $1, $2…",
+      ),
+    target_id: z
+      .string()
+      .optional()
+      .describe(
+        "accept / reject / reply: the 'Chg:N' or 'Com:N' id taken from a fresh read_docx.",
+      ),
+    text: z.string().optional().describe("reply: the reply body."),
+    comment: z
+      .string()
+      .optional()
+      .describe(
+        "modify / accept / reject: attach a margin comment to the change (no manual CriticMarkup).",
+      ),
+    match_mode: z
+      .enum(["strict", "first", "all"])
+      .optional()
+      .describe(
+        "modify only: 'strict' (default — target must match uniquely), 'first' (first occurrence), or 'all' (every occurrence).",
+      ),
+    regex: z
+      .boolean()
+      .optional()
+      .describe(
+        "modify only: treat target_text as a regular expression (default false).",
+      ),
+    position: z
+      .enum(["above", "below"])
+      .optional()
+      .describe(
+        "insert_row: place the new row above or below the matched row.",
+      ),
+    cells: z
+      .array(z.string())
+      .optional()
+      .describe("insert_row: the cell values for the new row, left to right."),
+  })
+  .passthrough();
+
 server.registerTool(
   "process_document_batch",
   {
@@ -356,8 +421,10 @@ server.registerTool(
         .string()
         .describe("Name to appear in Track Changes (e.g., 'Reviewer AI')."),
       changes: z
-        .array(z.any())
-        .describe("List of changes to apply. Each change must specify 'type'."),
+        .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.",
+        ),
       output_path: z.string().optional().describe("Optional output path."),
       dry_run: z
         .boolean()
@@ -549,7 +616,7 @@ server.registerTool(
   "finalize_document",
   {
     description:
-      "Prepares a document for external distribution or e-signature.",
+      "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: {
       file_path: z.string().describe("Absolute path to the DOCX file."),
       output_path: z.string().optional().describe("Optional output path."),
@@ -566,7 +633,9 @@ server.registerTool(
       protection_mode: z
         .enum(["read_only", "encrypt"])
         .optional()
-        .describe("Native OOXML document locking."),
+        .describe(
+          "Native OOXML document locking. Note: 'encrypt' is unsupported in this zero-dependency build and falls back to 'read_only'.",
+        ),
       password: z.string().optional().describe("Ignored in this environment."),
       author: z
         .string()

package/src/mcp.bugs.test.ts

@@ -189,6 +189,29 @@ describe("Resolved Bugs MCP Server Verification", () => {
     expect(res.result.content[0].text).toContain("Dry-run simulation complete.");
   });
 
+  it("Unparseable String: process_document_batch gracefully rejects raw strings instead of crashing", async () => {
+    const res = await sendRpc(
+      "tools/call",
+      {
+        name: "process_document_batch",
+        arguments: {
+          original_docx_path: cleanDocPath,
+          author_name: "Agent",
+          changes: [
+            "modify document to be clean document" // Raw unparseable string
+          ],
+          dry_run: false,
+        },
+      },
+      110,
+    );
+
+    expect(res.result.isError).toBe(true);
+    expect(res.result.content[0].text).toContain("Batch rejected. Some edits failed validation");
+    expect(res.result.content[0].text).toContain("Invalid change format");
+    expect(res.result.content[0].text).toContain("received a primitive string");
+  });
+
   it("BUG-12: Accepts stringified numbers for numeric arguments without Zod validation errors", async () => {
     const res = await sendRpc(
       "tools/call",

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

@@ -0,0 +1,384 @@
+// FILE: node/packages/mcp-server/src/mcp.schema-gaps.test.ts
+//
+// Guards the MCP boundary's HONESTY: what the server advertises over `tools/list`
+// (the schema + documentation an LLM sees) must match what the tools really do.
+// Each block below closed a gap where an agent, behaving exactly as documented,
+// was either misled or kept from a capability that exists — "under-documented
+// power is unused power." These tests now assert the corrected state and fail if
+// any gap regresses.
+//
+// Gaps closed:
+//   • process_document_batch — `changes` now publishes a typed item schema so the
+//     six DocumentChange variants are discoverable (ADEU_TOOL_ISSUES #1), and the
+//     real `match_mode`/`regex` options are documented in both schema and prose
+//     (#10). Both are still proven honored at the live boundary.
+//   • read_docx — its description carries the build stamp exactly once (UI tools
+//     were previously double-wrapped and stamped twice).
+//   • diff_docx_files — described as the custom `@@ Word Patch @@` format it
+//     actually emits, no longer mislabeled a "unified diff".
+//   • finalize_document — discloses that `protection_mode:'encrypt'` is unsupported
+//     in the zero-dependency Node build and falls back to a read-only lock.
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { spawn, ChildProcess } from "node:child_process";
+import { resolve, join } from "node:path";
+import { tmpdir } from "node:os";
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { DocumentObject } from "@adeu/core";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+
+const CHANGE_VARIANTS = [
+  "modify",
+  "accept",
+  "reject",
+  "reply",
+  "insert_row",
+  "delete_row",
+] as const;
+
+const BUILD_STAMP_RE = /\[Adeu v[^\]]*\]/g;
+
+describe("MCP tools — advertised schema/docs match real capability", () => {
+  let serverProc: ChildProcess;
+  let allTools: any[] = [];
+  const tempPaths: string[] = [];
+
+  // Fixtures
+  let pdbFixture: string; // repeated phrase + currency, for match_mode/regex proofs
+  let diffOrig: string;
+  let diffMod: string;
+  let finalizeInput: string;
+
+  const getTool = (name: string) => allTools.find((t) => t.name === name);
+
+  // --- Robust line-buffered JSON-RPC plumbing over stdio ---
+  const pending = new Map<number, (msg: any) => void>();
+  let rpcId = 100;
+  let stdoutBuffer = "";
+
+  function rpc(method: string, params: any): Promise<any> {
+    const id = ++rpcId;
+    return new Promise((resolveRpc, rejectRpc) => {
+      const timeout = setTimeout(
+        () => rejectRpc(new Error(`RPC timeout for ${method}`)),
+        15000,
+      );
+      pending.set(id, (msg) => {
+        clearTimeout(timeout);
+        resolveRpc(msg);
+      });
+      serverProc.stdin?.write(
+        JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n",
+      );
+    });
+  }
+
+  function notify(method: string, params: any): void {
+    serverProc.stdin?.write(
+      JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n",
+    );
+  }
+
+  // Build a docx from a list of paragraph strings (cloning the empty fixture and
+  // clearing its body — `@adeu/core` does not export its test-utils). Tracks the
+  // path for cleanup.
+  async function buildDoc(paragraphs: string[]): Promise<string> {
+    const initialPath = resolve(
+      __dirname,
+      "../../../../shared/fixtures/initial.docx",
+    );
+    const doc = await DocumentObject.load(readFileSync(initialPath));
+    const body = doc.element;
+    while (body.firstChild) body.removeChild(body.firstChild);
+
+    for (const text of paragraphs) {
+      const xmlDoc = body.ownerDocument!;
+      const p = xmlDoc.createElement("w:p");
+      const r = xmlDoc.createElement("w:r");
+      const t = xmlDoc.createElement("w:t");
+      t.textContent = text;
+      if (/\s/.test(text)) t.setAttribute("xml:space", "preserve");
+      r.appendChild(t);
+      p.appendChild(r);
+      body.appendChild(p);
+    }
+
+    const outPath = join(
+      tmpdir(),
+      `adeu_schemagap_${Date.now()}_${tempPaths.length}.docx`,
+    );
+    writeFileSync(outPath, await doc.save());
+    tempPaths.push(outPath);
+    return outPath;
+  }
+
+  function tempOut(label: string): string {
+    const p = join(
+      tmpdir(),
+      `adeu_schemagap_out_${label}_${Date.now()}_${tempPaths.length}.docx`,
+    );
+    tempPaths.push(p);
+    return p;
+  }
+
+  beforeAll(async () => {
+    const serverPath = resolve(__dirname, "../dist/index.js");
+    if (!existsSync(serverPath)) {
+      throw new Error(
+        "MCP server not built. Run 'npm run build' before tests.",
+      );
+    }
+
+    serverProc = spawn("node", [serverPath]);
+    serverProc.stdout?.on("data", (data: Buffer) => {
+      stdoutBuffer += data.toString();
+      let idx: number;
+      while ((idx = stdoutBuffer.indexOf("\n")) !== -1) {
+        const line = stdoutBuffer.slice(0, idx).trim();
+        stdoutBuffer = stdoutBuffer.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 non-JSON / partial lines
+        }
+      }
+    });
+
+    // Proper MCP handshake, then snapshot the advertised tool list.
+    await rpc("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "schema-gap-test", version: "0.0.0" },
+    });
+    notify("notifications/initialized", {});
+
+    const list = await rpc("tools/list", {});
+    allTools = list.result.tools ?? [];
+
+    pdbFixture = await buildDoc([
+      "The Confidential Information shall remain protected.",
+      "Some unrelated clause about delivery schedules.",
+      "The Confidential Information shall not be disclosed.",
+      "Setup fee is $500 due on signing.",
+    ]);
+    diffOrig = await buildDoc(["The quick brown fox.", "Second clause stays."]);
+    diffMod = await buildDoc([
+      "The slow green turtle.",
+      "Second clause stays.",
+    ]);
+    finalizeInput = await buildDoc(["Some content to finalize."]);
+  });
+
+  afterAll(() => {
+    if (serverProc && !serverProc.killed) serverProc.kill();
+    for (const p of tempPaths) {
+      if (existsSync(p)) {
+        try {
+          unlinkSync(p);
+        } catch {
+          // best-effort cleanup
+        }
+      }
+    }
+  });
+
+  // ======================================================================
+  // process_document_batch — ADEU_TOOL_ISSUES #1: `changes` items are typed
+  // ======================================================================
+  describe("process_document_batch #1: `changes` publishes a typed item schema", () => {
+    it("exposes a `changes.items` schema enumerating all six change variants", () => {
+      const pdbTool = getTool("process_document_batch");
+      expect(
+        pdbTool,
+        "process_document_batch must be advertised",
+      ).toBeDefined();
+
+      const changesProp = pdbTool.inputSchema?.properties?.changes;
+      expect(changesProp?.type).toBe("array");
+
+      const items = changesProp.items;
+      expect(
+        items,
+        "changes.items must describe the change shape",
+      ).toBeTruthy();
+
+      // Every DocumentChange discriminator is now machine-discoverable.
+      const itemsJson = JSON.stringify(items);
+      for (const variant of CHANGE_VARIANTS) {
+        expect(
+          itemsJson,
+          `variant '${variant}' should be discoverable`,
+        ).toContain(variant);
+      }
+    });
+
+    it("exposes the per-variant fields (target_text / new_text / target_id / text), not just prose", () => {
+      const itemsJson = JSON.stringify(
+        getTool("process_document_batch").inputSchema.properties.changes.items,
+      );
+      for (const field of ["target_text", "new_text", "target_id", "text"]) {
+        expect(itemsJson).toContain(field);
+      }
+    });
+  });
+
+  // ======================================================================
+  // process_document_batch — ADEU_TOOL_ISSUES #10: match_mode / regex surfaced
+  // ======================================================================
+  describe("process_document_batch #10: match_mode / regex are documented and honored", () => {
+    it("documents `match_mode` and `regex` in both the schema and the description", () => {
+      const pdbTool = getTool("process_document_batch");
+      const schemaJson = JSON.stringify(pdbTool.inputSchema).toLowerCase();
+      const description: string = (pdbTool.description ?? "").toLowerCase();
+
+      // Discoverable from the schema (the typed change item)...
+      expect(schemaJson).toContain("match_mode");
+      expect(schemaJson).toContain("regex");
+      // ...and called out in the prose guidance too.
+      expect(description).toContain("match_mode");
+      expect(description).toContain("regex");
+    });
+
+    it("honors match_mode:'all' at the live MCP boundary — edits every occurrence (2)", async () => {
+      const res = await rpc("tools/call", {
+        name: "process_document_batch",
+        arguments: {
+          original_docx_path: pdbFixture,
+          author_name: "Schema Gap Test",
+          changes: [
+            {
+              type: "modify",
+              target_text: "The Confidential Information",
+              new_text: "The Proprietary Data",
+              match_mode: "all",
+            },
+          ],
+          dry_run: true,
+        },
+      });
+
+      const text: string = res.result.content[0].text;
+      expect(res.result.isError).toBeFalsy();
+      expect(text).toMatch(/2 occurrences/);
+      expect(text).toContain("`all`");
+    });
+
+    it("honors regex:true (with a capture group) at the live MCP boundary", async () => {
+      const res = await rpc("tools/call", {
+        name: "process_document_batch",
+        arguments: {
+          original_docx_path: pdbFixture,
+          author_name: "Schema Gap Test",
+          changes: [
+            {
+              type: "modify",
+              // A regex, not a literal — `target_text` never appears verbatim in
+              // the doc, so a successful edit proves regex mode was honored.
+              target_text: "\\$(\\d+)",
+              new_text: "USD $1",
+              regex: true,
+            },
+          ],
+          dry_run: true,
+        },
+      });
+
+      const text: string = res.result.content[0].text;
+      expect(res.result.isError).toBeFalsy();
+      expect(text).toContain("USD 500"); // capture group $1 substituted
+    });
+  });
+
+  // ======================================================================
+  // read_docx — build stamp appears exactly once
+  // ======================================================================
+  describe("read_docx: build stamp appears exactly once", () => {
+    it("stamps the build tag once — UI tools are no longer double-wrapped", () => {
+      const readDocx = getTool("read_docx");
+      expect(readDocx, "read_docx must be advertised").toBeDefined();
+
+      const stamps = readDocx.description.match(BUILD_STAMP_RE) ?? [];
+      expect(stamps.length).toBe(1);
+
+      // Parity with a plain (non-UI) tool, which was always stamped once.
+      const pdbStamps =
+        getTool("process_document_batch").description.match(BUILD_STAMP_RE) ??
+        [];
+      expect(pdbStamps.length).toBe(1);
+    });
+  });
+
+  // ======================================================================
+  // diff_docx_files — described as the Word Patch format it actually emits
+  // ======================================================================
+  describe("diff_docx_files: described as the Word Patch format it emits", () => {
+    it("describes its output as a Word Patch, not a 'unified diff'", () => {
+      const desc = getTool("diff_docx_files").description.toLowerCase();
+      expect(desc).not.toContain("unified diff");
+      expect(desc).toContain("word patch");
+    });
+
+    it("emits the custom `@@ Word Patch @@` format at runtime (matching its description)", async () => {
+      const res = await rpc("tools/call", {
+        name: "diff_docx_files",
+        arguments: {
+          original_path: diffOrig,
+          modified_path: diffMod,
+          compare_clean: true,
+        },
+      });
+
+      const text: string = res.result.content[0].text;
+      expect(res.result.isError).toBeFalsy();
+      expect(text).toContain("@@ Word Patch @@");
+      // It is NOT a standard line-based unified diff (no `@@ -l,s +l,s @@` header).
+      expect(text).not.toMatch(/@@ -\d+(,\d+)? \+\d+(,\d+)? @@/);
+    });
+  });
+
+  // ======================================================================
+  // finalize_document — encrypt fallback is disclosed
+  // ======================================================================
+  describe("finalize_document: discloses the encrypt → read-only fallback", () => {
+    it("advertises `encrypt` honestly — dropped from the enum, or its fallback disclosed", () => {
+      const finalizeTool = getTool("finalize_document");
+      const enumVals: string[] =
+        finalizeTool.inputSchema.properties.protection_mode.enum;
+      const desc: string = (finalizeTool.description ?? "").toLowerCase();
+
+      const honest =
+        !enumVals.includes("encrypt") ||
+        (desc.includes("encrypt") &&
+          /read-only|falls back|fallback|unsupported/.test(desc));
+      expect(
+        honest,
+        "encrypt must be dropped from the Node enum or its read-only fallback disclosed",
+      ).toBe(true);
+    });
+
+    it("downgrades encrypt to a read-only lock at runtime, with a warning (matching the disclosure)", async () => {
+      const res = await rpc("tools/call", {
+        name: "finalize_document",
+        arguments: {
+          file_path: finalizeInput,
+          output_path: tempOut("finalize_encrypt"),
+          protection_mode: "encrypt",
+        },
+      });
+
+      const text: string = res.result.content[0].text;
+      expect(res.result.isError).toBeFalsy();
+      expect(text).toContain("Encryption mode");
+      expect(text.toLowerCase()).toContain("unsupported");
+      expect(text).toMatch(/read-only/i);
+    });
+  });
+});