@adeu/mcp-server 1.10.1 → 1.12.0

package/src/index.ts

@@ -5,7 +5,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { basename, resolve, extname, dirname, join } from "node:path";
 import { z } from "zod";
 import {
-  registerAppTool,
+  registerAppTool as origRegisterAppTool,
   registerAppResource,
   RESOURCE_MIME_TYPE,
 } from "@modelcontextprotocol/ext-apps/server";
@@ -13,6 +13,7 @@ import fs from "node:fs";
 import {
   identifyEngine,
   extractTextFromBuffer,
+  _extractTextFromDoc,
   DocumentObject,
   RedlineEngine,
   BatchValidationError,
@@ -39,7 +40,12 @@ function readFileBytesOrThrow(filePath: string): Buffer {
     return readFileSync(filePath);
   } catch (err: any) {
     if (err.code === "ENOENT") {
-      throw new Error(`File not found: ${filePath}`);
+      throw new Error(
+        `File not found: ${filePath}. Note: If you are running in a sandboxed/containerized environment, ` +
+        `the host application or MCP server may not have access to your local workspace files. ` +
+        `You can resolve this by installing Adeu directly inside your sandboxed environment using ` +
+        `'uv tool install adeu' and executing the commands via the CLI.`
+      );
     }
     throw err;
   }
@@ -74,12 +80,38 @@ const PROCESS_BATCH_OPERATIONS_DESC =
 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.";
 
+const gitSha = process.env.GIT_SHA || "unknown";
+const buildTs = process.env.BUILD_TIMESTAMP || "unknown";
+const packageVersion = process.env.PACKAGE_VERSION || "unknown";
+const buildTag = ` [Adeu v${packageVersion}+${gitSha}]`;
+
 // --- Server Setup ---
 const server = new McpServer({
   name: "adeu-redlining-service",
-  version: "1.0.0",
+  version: packageVersion,
 });
 
+// Wrap server.registerTool to inject buildTag into descriptions
+const originalRegisterTool = server.registerTool.bind(server);
+server.registerTool = (name: string, schema: any, handler?: any) => {
+  if (schema && typeof schema === "object") {
+    if (schema.description) {
+      schema.description = schema.description.trim() + buildTag;
+    }
+  }
+  return originalRegisterTool(name, schema, handler);
+};
+
+// Wrap registerAppTool to inject buildTag into descriptions
+const registerAppTool: typeof origRegisterAppTool = (mcpServer, name, schema, handler) => {
+  if (schema && typeof schema === "object") {
+    if (schema.description) {
+      schema.description = schema.description.trim() + buildTag;
+    }
+  }
+  return origRegisterAppTool(mcpServer, name, schema, handler);
+};
+
 // Common CSP allowing Google Fonts used by Adeu UI templates
 const UI_CSP = {
   connectDomains: ["https://fonts.googleapis.com", "https://fonts.gstatic.com"],
@@ -205,22 +237,31 @@ registerAppTool(
   }) => {
     try {
       const buf = readFileBytesOrThrow(file_path);
-      const text = await extractTextFromBuffer(buf, clean_view);
 
       if (mode === "outline") {
         const doc = await DocumentObject.load(buf);
-        return build_outline_response(
+        const extract_res = _extractTextFromDoc(doc, clean_view, true, true) as {
+          text: string;
+          paragraph_offsets: Map<any, [number, number]>;
+        };
+        const res = build_outline_response(
           doc,
-          text,
+          extract_res.text,
           file_path,
           outline_max_level,
           outline_verbose,
-        ) as any;
+          extract_res.paragraph_offsets,
+        );
+        return res as any;
       }
+
+      const text = await extractTextFromBuffer(buf, clean_view);
       if (mode === "appendix") {
-        return build_appendix_response(text, page, file_path) as any;
+        const res = build_appendix_response(text, page, file_path);
+        return res as any;
       }
-      return build_paginated_response(text, page, file_path) as any;
+      const res = build_paginated_response(text, page, file_path);
+      return res as any;
     } catch (e: any) {
       return {
         isError: true,
@@ -235,6 +276,8 @@ registerAppTool(
   },
 );
 
+
+
 registerAppTool(
   server,
   "search_and_fetch_emails",
@@ -268,6 +311,10 @@ registerAppTool(
         .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
         .number()
         .optional()
@@ -683,8 +730,10 @@ export function formatBatchResult(
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  const gitSha = process.env.GIT_SHA || "unknown";
+  const buildTs = process.env.BUILD_TIMESTAMP || "unknown";
   console.error(
-    `Adeu MCP Server (Node.js Engine: ${identifyEngine()}) running on stdio`,
+    `Adeu MCP Server (Node.js Engine: ${identifyEngine()}) running on stdio build=${gitSha}@${buildTs}`,
   );
 }
 

package/src/mcp.bugs.test.ts

@@ -157,6 +157,8 @@ describe("Resolved Bugs MCP Server Verification", () => {
     expect(res.result.content[0].text).toContain(
       "Error executing tool read_docx: File not found:",
     );
+    expect(res.result.content[0].text).toContain("sandboxed/containerized environment");
+    expect(res.result.content[0].text).toContain("uv tool install adeu");
     expect(res.result.content[0].text).not.toContain("ENOENT"); // Raw node error must not leak
   });
 });

package/src/parity_live.test.ts

@@ -0,0 +1,265 @@
+// FILE: node/packages/mcp-server/src/parity_live.test.ts
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { spawn, ChildProcess } from "node:child_process";
+import { resolve, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+
+describe("Parity Live Server Integration Verification", () => {
+  let serverProc: ChildProcess;
+  const fixturePath = resolve(__dirname, "../tests/fixtures/gap2_minimal_repro.docx");
+
+  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.",
+      );
+    }
+    if (!existsSync(fixturePath)) {
+      throw new Error(`Fixture not found: ${fixturePath}`);
+    }
+
+    // Spawn server process
+    serverProc = spawn("node", [serverPath]);
+  });
+
+  afterAll(() => {
+    if (serverProc && !serverProc.killed) {
+      serverProc.kill();
+    }
+  });
+
+  // Helper to interact with the stdio JSON-RPC server
+  function sendRpc(method: string, params: any, id: number = 1): Promise<any> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error("RPC Timeout")), 5000);
+
+      const listener = (data: Buffer) => {
+        const lines = data.toString().trim().split("\n");
+        for (const line of lines) {
+          if (!line.startsWith("{")) continue;
+          try {
+            const res = JSON.parse(line);
+            if (res.id === id) {
+              clearTimeout(timeout);
+              serverProc.stdout?.removeListener("data", listener);
+              resolve(res);
+            }
+          } catch (e) {
+            // Ignore incomplete chunks
+          }
+        }
+      };
+
+      serverProc.stdout?.on("data", listener);
+      serverProc.stdin?.write(
+        JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n",
+      );
+    });
+  }
+
+  it("does not expose the server_info tool anymore", async () => {
+    const listRes = await sendRpc("tools/list", {}, 200);
+    expect(listRes.result).toBeDefined();
+    const tools = listRes.result.tools || [];
+    const serverInfoTool = tools.find((t: any) => t.name === "server_info");
+    expect(serverInfoTool).toBeUndefined();
+  });
+
+  it("exposes the build stamp via tool-call descriptions", async () => {
+    const listRes = await sendRpc("tools/list", {}, 201);
+    expect(listRes.result).toBeDefined();
+    const tools = listRes.result.tools || [];
+    const readDocx = tools.find((t: any) => t.name === "read_docx");
+    expect(readDocx).toBeDefined();
+    expect(readDocx.description).toContain("[Adeu v");
+  });
+
+  it("exposes the build stamp via serverInfo.version in initialize", async () => {
+    const initRes = await sendRpc("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "test-client", version: "1.0.0" }
+    }, 202);
+    expect(initRes.result).toBeDefined();
+    expect(initRes.result.serverInfo).toBeDefined();
+    expect(initRes.result.serverInfo.version).not.toBe("1.0.0");
+    expect(initRes.result.serverInfo.version).not.toContain("unknown");
+  });
+
+
+  it("read_docx appends [Debug] build stamp footer to mode=outline and mode=full", async () => {
+    const res = await sendRpc("tools/call", {
+      name: "read_docx",
+      arguments: {
+        file_path: fixturePath,
+        mode: "outline",
+      },
+    }, 202);
+
+    expect(res.result).toBeDefined();
+    expect(res.result.content[0].text).not.toContain("[Debug] build=");
+  });
+
+  it("GAP 2 (Live): process_document_batch modify straddling deleted text returns actionable deletion error", async () => {
+    const outPath = join(resolve(__dirname, "../../../../tmp"), `live_gap2_out_${Date.now()}.docx`);
+    const res = await sendRpc("tools/call", {
+      name: "process_document_batch",
+      arguments: {
+        original_docx_path: fixturePath,
+        author_name: "Ed",
+        changes: [
+          {
+            type: "modify",
+            target_text: "Foo bar old phrase here.",
+            new_text: "X",
+            comment: "c",
+          }
+        ],
+        output_path: outPath,
+        dry_run: true,
+      },
+    }, 203);
+
+    expect(res.result).toBeDefined();
+    const text = res.result.content[0].text;
+    expect(text).toContain("Edit 1 Failed: Target text matches text inside a tracked deletion by Test Negotiator.");
+    expect(text).toContain("Reject/accept that change first or target the active replacement text instead.");
+    expect(text).not.toContain("Target text not found in document.");
+
+    // Run Python engine to assert cross-engine exact error parity
+    const { execSync } = await import("node:child_process");
+    const projectRoot = resolve(__dirname, "../../../..");
+    const pythonCli = process.platform === "win32"
+      ? join(projectRoot, "python/.venv/Scripts/adeu.exe")
+      : join(projectRoot, "python/.venv/bin/adeu");
+    
+    // Create temporary changes JSON for Python CLI
+    const fs = await import("node:fs");
+    const tempJsonPath = join(projectRoot, "tmp", `changes_${Date.now()}.json`);
+    fs.mkdirSync(join(projectRoot, "tmp"), { recursive: true });
+    fs.writeFileSync(tempJsonPath, JSON.stringify([
+      {
+        type: "modify",
+        target_text: "Foo bar old phrase here.",
+        new_text: "X",
+        comment: "c",
+      }
+    ]));
+
+    try {
+      const pythonOut = execSync(`"${pythonCli}" apply "${fixturePath}" "${tempJsonPath}" --dry-run --author Ed`, {
+        encoding: "utf-8",
+      });
+      // Should not succeed normally since dry run exits with code 1 on errors, so we catch in the try block
+    } catch (err: any) {
+      const pyErrorOutput = err.stdout || err.stderr || "";
+      expect(pyErrorOutput).toContain("Edit 1 Failed: Target text matches text inside a tracked deletion by Test Negotiator.");
+      expect(pyErrorOutput).toContain("Reject/accept that change first or target the active replacement text instead.");
+    } finally {
+      if (fs.existsSync(tempJsonPath)) {
+        fs.unlinkSync(tempJsonPath);
+      }
+    }
+  });
+
+  it("GAP 1 (Live): read_docx mode=outline heading count and content parity with Python", async () => {
+    const gap1FixturePath = resolve(__dirname, "../tests/fixtures/gap1_deleted_row_repro.docx");
+    const { execSync } = await import("node:child_process");
+    const projectRoot = resolve(__dirname, "../../../..");
+    const pythonCli = process.platform === "win32"
+      ? join(projectRoot, "python/.venv/Scripts/adeu.exe")
+      : join(projectRoot, "python/.venv/bin/adeu");
+
+    // 1. clean_view = true
+    const nodeResClean = await sendRpc("tools/call", {
+      name: "read_docx",
+      arguments: {
+        file_path: gap1FixturePath,
+        mode: "outline",
+        clean_view: true,
+      },
+    }, 204);
+
+    expect(nodeResClean.result).toBeDefined();
+    const nodeTextClean = nodeResClean.result.content[0].text;
+    
+    // Get Python output for clean_view = true
+    const pythonOutClean = execSync(`"${pythonCli}" extract "${gap1FixturePath}" --mode outline --clean-view`, {
+      encoding: "utf-8",
+    });
+
+    // Extract raw markdown headings (lines starting with #) to assert perfect parity
+    const getHeadings = (text: string) => text.split("\n").filter(line => line.startsWith("#")).map(l => l.trim());
+    
+    const nodeHeadingsClean = getHeadings(nodeTextClean);
+    const pythonHeadingsClean = getHeadings(pythonOutClean);
+
+    expect(nodeHeadingsClean).toEqual(["# Active Heading (p1)"]);
+    expect(pythonHeadingsClean).toEqual(["# Active Heading (p1)"]);
+    expect(nodeHeadingsClean).toEqual(pythonHeadingsClean);
+
+    // 2. clean_view = false
+    const nodeResDirty = await sendRpc("tools/call", {
+      name: "read_docx",
+      arguments: {
+        file_path: gap1FixturePath,
+        mode: "outline",
+        clean_view: false,
+      },
+    }, 205);
+
+    expect(nodeResDirty.result).toBeDefined();
+    const nodeTextDirty = nodeResDirty.result.content[0].text;
+
+    const pythonOutDirty = execSync(`"${pythonCli}" extract "${gap1FixturePath}" --mode outline`, {
+      encoding: "utf-8",
+    });
+
+    const nodeHeadingsDirty = getHeadings(nodeTextDirty);
+    const pythonHeadingsDirty = getHeadings(pythonOutDirty);
+
+    expect(nodeHeadingsDirty).toEqual(["# Active Heading (p1)", "# Deleted Heading (p1)"]);
+    expect(pythonHeadingsDirty).toEqual(["# Active Heading (p1)", "# Deleted Heading (p1)"]);
+    expect(nodeHeadingsDirty).toEqual(pythonHeadingsDirty);
+  });
+
+  it("GAP 1 - Style Def (Live): style-definition outlineLvl on non-heading style classification parity", async () => {
+    const gap1FixturePath = resolve(__dirname, "../tests/fixtures/gap1_minimal_repro.docx");
+    const { execSync } = await import("node:child_process");
+    const projectRoot = resolve(__dirname, "../../../..");
+    const pythonCli = process.platform === "win32"
+      ? join(projectRoot, "python/.venv/Scripts/adeu.exe")
+      : join(projectRoot, "python/.venv/bin/adeu");
+
+    // 1. clean_view = true (both engines must return exactly 2 headings, excluding Subtitle)
+    const nodeResClean = await sendRpc("tools/call", {
+      name: "read_docx",
+      arguments: {
+        file_path: gap1FixturePath,
+        mode: "outline",
+        clean_view: true,
+      },
+    }, 206);
+
+    expect(nodeResClean.result).toBeDefined();
+    const nodeTextClean = nodeResClean.result.content[0].text;
+
+    const pythonOutClean = execSync(`"${pythonCli}" extract "${gap1FixturePath}" --mode outline --clean-view`, {
+      encoding: "utf-8",
+    });
+
+    const getHeadings = (text: string) => text.split("\n").filter(line => line.startsWith("#")).map(l => l.trim());
+
+    const nodeHeadingsClean = getHeadings(nodeTextClean);
+    const pythonHeadingsClean = getHeadings(pythonOutClean);
+
+    // Assert exact count parity (must be exactly 2 for both)
+    expect(nodeHeadingsClean.length).toBe(2);
+    expect(pythonHeadingsClean.length).toBe(2);
+
+    expect(nodeHeadingsClean).toEqual(["# Real Heading One (p1)", "# Real Heading Two (p1)"]);
+    expect(pythonHeadingsClean).toEqual(["# Real Heading One (p1)", "# Real Heading Two (p1)"]);
+    expect(nodeHeadingsClean).toEqual(pythonHeadingsClean);
+  });
+});

package/src/response-builders.ts

@@ -110,6 +110,7 @@ export function build_outline_response(
   file_path: string,
   outline_max_level: number = 2,
   outline_verbose: boolean = false,
+  paragraph_offsets: Map<any, [number, number]> | null = null,
 ): ToolResult {
   const [body] = split_structural_appendix(projected_text);
   const pagination_result = paginate(body, "");
@@ -119,6 +120,7 @@ export function build_outline_response(
     body,
     pagination_result.body_pages,
     pagination_result.body_page_offsets,
+    paragraph_offsets,
   );
 
   const rendered = render_outline_tree(

package/src/tools/email.test.ts

@@ -1,4 +1,3 @@
-// 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";
 
@@ -255,4 +254,108 @@ describe("Node Email Tools Finding #2 and Finding #6 tests", () => {
       "You can now use tools like `read_docx`, `diff_docx_files`, or `finalize_document`",
     );
   });
+
+  describe("Stateful Polling symmetry with Validation", () => {
+    const sleepMock = vi.spyOn(global, "setTimeout");
+
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it("should handle async task initiation upon searching", async () => {
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        status: 202,
+        json: async () => ({
+          status: "pending",
+          task_id: "email_task_typescript_123",
+          message: "Queued"
+        }),
+      } as Response);
+
+      const result = await search_and_fetch_emails({ subject: "heavy search" });
+
+      expect(result.content[0].text).toContain("Email processing task started successfully");
+      expect(result.content[0].text).toContain("task_id=email_task_typescript_123");
+      expect(result.structuredContent?.status).toBe("pending");
+      expect(result.structuredContent?.task_id).toBe("email_task_typescript_123");
+    });
+
+    it("should poll and resolve when a task completes successfully", async () => {
+      let callCount = 0;
+      global.fetch = vi.fn().mockImplementation(async () => {
+        callCount++;
+        if (callCount === 1) {
+          return {
+            ok: true,
+            status: 200,
+            json: async () => ({ status: "PENDING" }),
+          } as Response;
+        }
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            status: "COMPLETED",
+            type: "previews",
+            previews: [],
+          }),
+        } as Response;
+      });
+
+      const promise = search_and_fetch_emails({ task_id: "email_task_typescript_123" });
+      promise.catch(() => {}); // Suppress Vitest's unhandled rejection warnings during timer advance
+      await vi.runAllTimersAsync();
+      
+      const result = await promise;
+
+      expect(callCount).toBe(2);
+      expect(result.content[0].text).toContain("No emails found matching your search criteria.");
+    });
+
+    it("should throw standard ToolError on task failure", async () => {
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          status: "FAILED",
+          error: "API authorization revoked.",
+        }),
+      } as Response);
+
+      const promise = search_and_fetch_emails({ task_id: "email_task_typescript_123" });
+      const caughtPromise = promise.catch((err) => err);
+      await vi.runAllTimersAsync();
+
+      await expect(promise).rejects.toThrowError(
+        "Validation task failed on the server: API authorization revoked."
+      );
+    });
+
+    it("should gracefully return a pending status on polling timeout (50s)", async () => {
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({ status: "PENDING" }),
+      } as Response);
+
+      const promise = search_and_fetch_emails({ task_id: "email_task_typescript_123" });
+
+      // Advance all 10 polling intervals
+      for (let i = 0; i < 10; i++) {
+        await vi.advanceTimersByTimeAsync(5000);
+      }
+      await vi.runAllTimersAsync();
+
+      const result = await promise;
+      expect(result.content[0].text).toContain("is still processing");
+      expect(result.content[0].text).toContain("task_id=email_task_typescript_123");
+      expect(result.structuredContent?.status).toBe("pending");
+      expect(result.structuredContent?.task_id).toBe("email_task_typescript_123");
+    });
+  });
 });