@adeu/mcp-server 1.14.0 → 1.15.1

package/src/formatter.qa.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { formatBatchResult } from "./index.js";
+
+describe("QA Report V2: Formatter Parity", () => {
+  it("F3 & F4: Formats match_mode, occurrences_modified, heading_path, and pages correctly", () => {
+    // Mock the stats object that the engine produces when `all` mode is successful
+    const stats = {
+      actions_applied: 0,
+      actions_skipped: 0,
+      edits_applied: 1,
+      edits_skipped: 0,
+      edits: [
+        {
+          status: "applied",
+          target_text: "the Board of Directors",
+          new_text: "the Governing Body",
+          warning: null,
+          error: null,
+          critic_markup: "the {--Board of Directors--}{++Governing Body++}",
+          clean_text: "the Governing Body",
+          pages: [3, 12],
+          heading_path: "6. Term > 6.1",
+          occurrences_modified: 33,
+          match_mode: "all"
+        }
+      ],
+      skipped_details: []
+    };
+
+    const res = formatBatchResult(stats, "dummy.docx", false);
+
+    // Verify the new §5.4.2 visual format
+    expect(res).toContain("### Edit 1 ✅ [applied] (p3, p12)");
+    expect(res).toContain("**Path:** `6. Term > 6.1`");
+    expect(res).toContain("**Mode:** `all` (33 occurrences modified)");
+    expect(res).toContain("*Preview (CriticMarkup):*");
+    expect(res).toContain("> the {--Board of Directors--}{++Governing Body++}");
+    expect(res).toContain("*Preview (Clean):*");
+    expect(res).toContain("> the Governing Body");
+  });
+
+  it("R1: Formats dry-run with full enrichment fields identical to real writes", () => {
+    const stats = {
+      actions_applied: 0,
+      actions_skipped: 0,
+      edits_applied: 1,
+      edits_skipped: 0,
+      edits: [
+        {
+          status: "applied",
+          target_text: "Target",
+          new_text: "Replaced",
+          warning: null,
+          error: null,
+          critic_markup: "{--Target--}{++Replaced++}",
+          clean_text: "Replaced",
+          pages: [1],
+          heading_path: "1. Intro",
+          occurrences_modified: 1,
+          match_mode: "all"
+        }
+      ],
+      skipped_details: []
+    };
+
+    const res = formatBatchResult(stats, "dummy.docx", true);
+    expect(res).toContain("**Path:** `1. Intro`");
+    expect(res).toContain("**Mode:** `all` (1 occurrence modified)");
+    expect(res).toContain("(p1)");
+  });
+});

package/src/formatter.test.ts

@@ -16,7 +16,11 @@ describe("MCP Server Tool Output Formatter", () => {
           warning: "Warning: target_text contains punctuation.",
           error: null,
           critic_markup: "The {--quick brown fox--}{++fast red fox++} jumps over",
-          clean_text: "The fast red fox jumps over"
+          clean_text: "The fast red fox jumps over",
+          match_mode: "strict",
+          occurrences_modified: 1,
+          pages: [1],
+          heading_path: "1. Intro"
         }
       ],
       skipped_details: []
@@ -29,9 +33,11 @@ describe("MCP Server Tool Output Formatter", () => {
     expect(res).toContain("Actions: 0 applied");
     expect(res).toContain("Edits: 1 applied");
     expect(res).toContain("Detailed Edit Reports:");
-    expect(res).toContain("✅ [applied]");
-    expect(res).toContain("Warning: Warning: target_text contains punctuation.");
-    expect(res).toContain("Preview (CriticMarkup): The {--quick brown fox--}{++fast red fox++} jumps over");
+    expect(res).toContain("### Edit 1 ✅ [applied] (p1)");
+    expect(res).toContain("**Path:** `1. Intro`");
+    expect(res).toContain("**Mode:** `strict` (1 occurrence modified)");
+    expect(res).toContain("*Warning:* Warning: target_text contains punctuation.");
+    expect(res).toContain("*Preview (CriticMarkup):*\n> The {--quick brown fox--}{++fast red fox++} jumps over");
   });
 
   it("formats a failed batch result correctly", () => {
@@ -57,8 +63,8 @@ describe("MCP Server Tool Output Formatter", () => {
     const res = formatBatchResult(stats, "dummy_processed.docx", false);
 
     expect(res).toContain("Batch complete. Saved to: dummy_processed.docx");
-    expect(res).toContain("❌ [failed]");
-    expect(res).toContain("Error: Target text not found in document");
+    expect(res).toContain("### Edit 1 ❌ [failed]");
+    expect(res).toContain("*Error:* Target text not found in document");
     expect(res).toContain("Skipped Details:\n- Failed to apply edit targeting: 'NON_EXISTENT...'");
   });
 });

package/src/index.ts

@@ -24,6 +24,7 @@ import {
   build_paginated_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";
@@ -224,17 +225,29 @@ registerAppTool(
           "'full' returns body content. 'outline' returns a structural heading map. 'appendix' returns defined terms.",
         ),
       page: z
-        .number()
+        .union([z.number(), z.string()])
         .default(1)
-        .describe("Page number (1-indexed) for mode='full'. Defaults to 1."),
+        .describe("Page number (1-indexed) for mode='full', or 'all' to return unpaginated."),
       outline_max_level: z
-        .number()
+        .coerce.number()
         .default(2)
         .describe("For mode='outline' only: cap on heading depth."),
       outline_verbose: z
         .boolean()
         .default(false)
         .describe("For mode='outline' only: includes metadata."),
+      search_query: z
+        .string()
+        .optional()
+        .describe("The substring or regex pattern to search for. When provided, filters results to matching paragraphs."),
+      search_regex: z
+        .boolean()
+        .default(false)
+        .describe("Set to true to interpret search_query as a regular expression."),
+      search_case_sensitive: z
+        .boolean()
+        .default(true)
+        .describe("Set to false to perform case-insensitive matching."),
     }),
     _meta: { ui: { resourceUri: MARKDOWN_UI_URI } },
   },
@@ -245,6 +258,9 @@ registerAppTool(
     page,
     outline_max_level,
     outline_verbose,
+    search_query,
+    search_regex,
+    search_case_sensitive,
   }) => {
     try {
       const buf = readFileBytesOrThrow(file_path);
@@ -267,11 +283,15 @@ registerAppTool(
       }
 
       const text = await extractTextFromBuffer(buf, clean_view);
+      if (search_query !== undefined && search_query !== null) {
+        const res = build_search_response(text, search_query, search_regex, search_case_sensitive, page, file_path);
+        return res as any;
+      }
       if (mode === "appendix") {
-        const res = build_appendix_response(text, page, file_path);
+        const res = build_appendix_response(text, typeof page === "number" ? page : parseInt(page, 10) || 1, file_path);
         return res as any;
       }
-      const res = build_paginated_response(text, page, file_path);
+      const res = build_paginated_response(text, typeof page === "number" ? page : parseInt(page, 10) || 1, file_path);
       return res as any;
     } catch (e: any) {
       return {
@@ -598,10 +618,10 @@ registerAppTool(
       has_attachments: z.boolean().optional(),
       attachment_name: z.string().optional(),
       is_unread: z.boolean().optional(),
-      days_ago: z.number().optional(),
+      days_ago: z.coerce.number().optional(),
       folder: z.enum(["inbox", "sent", "all"]).optional(),
-      limit: z.number().default(10),
-      offset: z.number().default(0),
+      limit: z.coerce.number().default(10),
+      offset: z.coerce.number().default(0),
       email_id: z.string().optional(),
       working_directory: z.string().optional(),
       mailbox_address: z
@@ -613,7 +633,7 @@ registerAppTool(
         .optional()
         .describe("If resuming a pending check, provide the task ID here."),
       max_attachment_size_mb: z
-        .number()
+        .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.",
@@ -728,8 +748,11 @@ export function formatBatchResult(
   } else {
     res = `Batch complete. Saved to: ${outPath}\n`;
   }
+  const total_occurrences = stats.edits ? stats.edits.reduce((acc: number, e: any) => acc + (e.status === "applied" ? (e.occurrences_modified || 1) : 0), 0) : 0;
+  const occ_text = total_occurrences > stats.edits_applied ? ` (${total_occurrences} occurrences)` : "";
+
   res += `Actions: ${stats.actions_applied} applied, ${stats.actions_skipped} skipped.\n`;
-  res += `Edits: ${stats.edits_applied} applied, ${stats.edits_skipped} skipped.\n`;
+  res += `Edits: ${stats.edits_applied} applied${occ_text}, ${stats.edits_skipped} skipped.\n`;
 
   if (stats.edits && stats.edits.length > 0) {
     res += "\nDetailed Edit Reports:\n";
@@ -737,28 +760,43 @@ export function formatBatchResult(
       const report = stats.edits[i];
       const status_indicator =
         report.status === "applied" ? "✅ [applied]" : "❌ [failed]";
-      res += `Edit ${i + 1} ${status_indicator}:\n`;
-      res += `  Target: '${report.target_text}'\n`;
-      res += `  New text: '${report.new_text}'\n`;
-      if (report.warning) {
-        res += `  Warning: ${report.warning}\n`;
+        
+      const pagesStr = report.pages && report.pages.length > 0 
+        ? ` (p${report.pages.join(", p")})` 
+        : "";
+        
+      res += `### Edit ${i + 1} ${status_indicator}${pagesStr}\n`;
+      
+      if (report.heading_path) {
+        res += `**Path:** \`${report.heading_path}\`\n`;
+      }
+      
+      if (report.match_mode) {
+         const occ = report.occurrences_modified || (report.status === "applied" ? 1 : 0);
+         res += `**Mode:** \`${report.match_mode}\` (${occ} occurrence${occ !== 1 ? 's' : ''} modified)\n`;
       }
+
       if (report.error) {
-        res += `  Error: ${report.error}\n`;
+        res += `*Error:* ${report.error}\n`;
+      }
+      if (report.warning) {
+        res += `*Warning:* ${report.warning}\n`;
       }
+      
       if (report.critic_markup) {
-        res += `  Preview (CriticMarkup): ${report.critic_markup}\n`;
+        res += `*Preview (CriticMarkup):*\n> ${report.critic_markup.split('\\n').join('\\n> ')}\n`;
       }
       if (report.clean_text) {
-        res += `  Clean text preview: ${report.clean_text}\n`;
+        res += `*Preview (Clean):*\n> ${report.clean_text.split('\\n').join('\\n> ')}\n`;
       }
+      res += "\n";
     }
   }
 
   if (stats.skipped_details && stats.skipped_details.length > 0) {
-    res += `\n\nSkipped Details:\n${stats.skipped_details.join("\n")}`;
+    res += `Skipped Details:\n${stats.skipped_details.join("\n")}`;
   }
-  return res;
+  return res.trim();
 }
 
 // --- Startup ---

package/src/mcp.bugs.test.ts

@@ -188,5 +188,26 @@ describe("Resolved Bugs MCP Server Verification", () => {
     expect(res.result.isError).toBeUndefined();
     expect(res.result.content[0].text).toContain("Dry-run simulation complete.");
   });
-});
 
+  it("BUG-12: Accepts stringified numbers for numeric arguments without Zod validation errors", async () => {
+    const res = await sendRpc(
+      "tools/call",
+      {
+        name: "read_docx",
+        arguments: {
+          file_path: cleanDocPath,
+          page: "1",
+          outline_max_level: "3",
+        },
+      },
+      106,
+    );
+
+    // If Zod validation failed, we would get an error payload back or `res.error` 
+    // from the MCP protocol (error code -32602).
+    expect(res.error).toBeUndefined();
+    expect(res.result).toBeDefined();
+    expect(res.result.isError).toBeUndefined();
+    expect(res.result.content[0].text).toContain("golden");
+  });
+});

package/src/response-builders.ts

@@ -208,3 +208,154 @@ export function build_appendix_response(
     },
   };
 }
+
+export function build_search_response(
+  text: string,
+  search_query: string,
+  search_regex: boolean,
+  search_case_sensitive: boolean,
+  page: number | string,
+  file_path: string,
+): ToolResult {
+  const [body] = split_structural_appendix(text);
+  const escapeRegExp = (s: string) =>
+    s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const flags = search_case_sensitive ? "g" : "gi";
+  const patternStr = search_regex ? search_query : escapeRegExp(search_query);
+
+  let regex: RegExp;
+  try {
+    regex = new RegExp(patternStr, flags);
+  } catch (e: any) {
+    throw new Error(`Invalid regex pattern: ${e.message}`);
+  }
+
+  const matches = Array.from(body.matchAll(regex));
+
+  if (matches.length === 0) {
+    const ui_markdown = `> **Search Results** — No matches found for query \`${search_query}\` in \`${basename(file_path)}\`.\n\nVerify your search spelling, or try setting \`search_case_sensitive\` to false or enabling \`search_regex\` if you used pattern wildcards.`;
+    const llm_content = `> **File Path:** \`${resolve(file_path)}\`\n\n${ui_markdown}`;
+    return {
+      content: [{ type: "text", text: llm_content }],
+      structuredContent: {
+        markdown: ui_markdown,
+        title: `Search: ${basename(file_path)}`,
+        file_path: resolve(file_path),
+      },
+    };
+  }
+
+  const pag_res = paginate(body, "");
+  const page_offsets = pag_res.body_page_offsets;
+  const total_matches = matches.length;
+  const total_pages = Math.ceil(total_matches / 10);
+
+  let start_idx = 0;
+  let end_idx = total_matches;
+  let page_text = "all";
+
+  const pageStr = String(page).toLowerCase();
+  if (pageStr !== "all") {
+    const page_num = parseInt(pageStr, 10);
+    if (isNaN(page_num) || page_num < 1 || page_num > total_pages) {
+      throw new Error(`Page ${page} out of range (search has ${total_pages} pages).`);
+    }
+    start_idx = (page_num - 1) * 10;
+    end_idx = Math.min(start_idx + 10, total_matches);
+    page_text = `${page_num} of ${total_pages}`;
+  }
+
+  const page_matches = matches.slice(start_idx, end_idx);
+
+  const ui_parts: string[] = [
+    `> **Search Results** — Found ${total_matches} matches for query \`${search_query}\` in \`${basename(file_path)}\`.`,
+  ];
+
+  if (total_pages > 1 && pageStr !== "all") {
+    const nextPage = parseInt(pageStr, 10) + 1;
+    ui_parts.push(`> Showing page ${page_text} (matches ${start_idx + 1}-${end_idx}). To see more matches, call \`read_docx\` with \`search_query='${search_query}'\`, \`search_regex=${search_regex ? "true" : "false"}\`, and \`page=${nextPage}\`.`);
+  }
+
+  const occurrences_map: Record<string, number> = {};
+  for (const m of matches) {
+    const matched_str = m[0];
+    occurrences_map[matched_str] = (occurrences_map[matched_str] || 0) + 1;
+  }
+
+  function get_heading(idx: number, txt: string): string {
+    const txtBefore = txt.substring(0, idx);
+    const lines = txtBefore.split("\n");
+    const path: string[] = [];
+    let current_level = 999;
+
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i];
+      const m = line.match(/^(#{1,6})\s+(.*)/);
+      if (m) {
+        const level = m[1].length;
+        if (level < current_level) {
+          let cleanHeading = m[2].replace(/\*\*|__|[*_]/g, "").replace(/\{#[^}]+\}/g, "").trim();
+          if (cleanHeading.length > 80) {
+            cleanHeading = cleanHeading.substring(0, 80) + "...";
+          }
+          path.unshift(cleanHeading);
+          current_level = level;
+          if (level === 1) break;
+        }
+      }
+    }
+    return path.join(" > ");
+  }
+
+  let i = start_idx + 1;
+  for (const m of page_matches) {
+    const matched_str = m[0];
+    const m_start = m.index!;
+    const m_end = m_start + matched_str.length;
+
+    let p_num = 1;
+    for (let j = 0; j < page_offsets.length; j++) {
+      if (m_start >= page_offsets[j]) {
+        p_num = j + 1;
+      } else {
+        break;
+      }
+    }
+
+    const snippet_start = Math.max(0, m_start - 100);
+    const snippet_end = Math.min(body.length, m_end + 100);
+    const snippet = body.substring(snippet_start, m_start) + `**${matched_str}**` + body.substring(m_end, snippet_end);
+
+    const snippet_lines = snippet
+      .split("\n")
+      .filter((line) => line.trim().length > 0)
+      .map((line) => `> ${line}`)
+      .join("\n");
+
+    ui_parts.push("---");
+    ui_parts.push(`### Match ${i} (p${p_num})`);
+
+    const h_path = get_heading(m_start, body);
+    if (h_path) {
+      ui_parts.push(`**Path:** \`${h_path}\``);
+    }
+
+    const count = occurrences_map[matched_str];
+    ui_parts.push(snippet_lines);
+    ui_parts.push(`*Occurrences:* This exact phrasing appears ${count} time${count !== 1 ? "s" : ""} in the document.`);
+
+    i++;
+  }
+
+  const ui_markdown = ui_parts.join("\n\n");
+  const llm_content = `> **File Path:** \`${resolve(file_path)}\`\n\n${ui_markdown}`;
+
+  return {
+    content: [{ type: "text", text: llm_content }],
+    structuredContent: {
+      markdown: ui_markdown,
+      title: `Search: ${basename(file_path)}`,
+      file_path: resolve(file_path),
+    },
+  };
+}