@adeu/mcp-server 1.15.1 → 1.16.0

package/dist/index.js

@@ -211,50 +211,100 @@ function build_search_response(text, search_query, search_regex, search_case_sen
   } catch (e) {
     throw new Error(`Invalid regex pattern: ${e.message}`);
   }
-  const matches = Array.from(body.matchAll(regex));
+  const allMatches = Array.from(body.matchAll(regex));
+  const pag_res = paginate(body, "");
+  const page_offsets = pag_res.body_page_offsets;
+  const total_doc_pages = pag_res.total_pages;
+  let filter_doc_page = null;
+  if (page !== void 0 && page !== null) {
+    const pageStr = String(page).toLowerCase();
+    if (pageStr !== "all") {
+      const parsed = parseInt(pageStr, 10);
+      if (isNaN(parsed) || parsed < 1) {
+        throw new Error(
+          `Invalid page value: \`${page}\`. Pass a positive integer to restrict the search to that document page, omit \`page\` to search all pages, or pass \`page='all'\` explicitly.`
+        );
+      }
+      if (parsed > total_doc_pages) {
+        throw new Error(
+          `Document page ${parsed} is out of range \u2014 the document has ${total_doc_pages} page(s). In search mode, \`page\` filters matches to a specific document page; omit it or pass \`page='all'\` to search the whole document.`
+        );
+      }
+      filter_doc_page = parsed;
+    }
+  }
+  const pageOfOffset = (offset) => {
+    let p = 1;
+    for (let j = 0; j < page_offsets.length; j++) {
+      if (offset >= page_offsets[j]) p = j + 1;
+      else break;
+    }
+    return p;
+  };
+  const pagesWithHits = /* @__PURE__ */ new Set();
+  for (const m of allMatches) {
+    pagesWithHits.add(pageOfOffset(m.index));
+  }
+  const matches = filter_doc_page === null ? allMatches : allMatches.filter((m) => pageOfOffset(m.index) === filter_doc_page);
   if (matches.length === 0) {
-    const ui_markdown2 = `> **Search Results** \u2014 No matches found for query \`${search_query}\` in \`${basename(file_path)}\`.
+    let body_msg;
+    if (filter_doc_page !== null) {
+      if (allMatches.length === 0) {
+        body_msg = `> **Search Results** \u2014 No matches found for query \`${search_query}\` in \`${basename(file_path)}\`.
+
+Verify your search spelling, or try setting \`search_case_sensitive\` to false or enabling \`search_regex\` if you used pattern wildcards.`;
+      } else {
+        const hitPages = Array.from(pagesWithHits).sort((a, b) => a - b);
+        body_msg = `> **Search Results** \u2014 No matches for \`${search_query}\` on document page ${filter_doc_page}.
+
+The query DOES appear elsewhere in the document (${allMatches.length} match${allMatches.length !== 1 ? "es" : ""} on page${hitPages.length !== 1 ? "s" : ""} ${hitPages.join(", ")}). Omit \`page\` or pass \`page='all'\` to see them.`;
+      }
+    } else {
+      body_msg = `> **Search Results** \u2014 No matches found for query \`${search_query}\` in \`${basename(file_path)}\`.
 
 Verify your search spelling, or try setting \`search_case_sensitive\` to false or enabling \`search_regex\` if you used pattern wildcards.`;
+    }
     const llm_content2 = `> **File Path:** \`${resolve(file_path)}\`
 
-${ui_markdown2}`;
+${body_msg}`;
     return {
       content: [{ type: "text", text: llm_content2 }],
       structuredContent: {
-        markdown: ui_markdown2,
+        markdown: body_msg,
         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).`);
+  const ui_parts = [];
+  if (filter_doc_page !== null) {
+    ui_parts.push(
+      `> **Search Results** \u2014 Found ${matches.length} match${matches.length !== 1 ? "es" : ""} for \`${search_query}\` on document page ${filter_doc_page} of ${total_doc_pages} in \`${basename(file_path)}\`.`
+    );
+    const otherPages = Array.from(pagesWithHits).filter((p) => p !== filter_doc_page).sort((a, b) => a - b);
+    if (otherPages.length > 0) {
+      ui_parts.push(
+        `> Additional matches exist on page${otherPages.length !== 1 ? "s" : ""} ${otherPages.join(", ")} \u2014 omit \`page\` or pass \`page='all'\` to see them.`
+      );
+    }
+  } else {
+    ui_parts.push(
+      `> **Search Results** \u2014 Found ${matches.length} match${matches.length !== 1 ? "es" : ""} for \`${search_query}\` in \`${basename(file_path)}\`.`
+    );
+    if (total_doc_pages > 1) {
+      const counts = /* @__PURE__ */ new Map();
+      for (const m of allMatches) {
+        const p = pageOfOffset(m.index);
+        counts.set(p, (counts.get(p) || 0) + 1);
+      }
+      const distribution = Array.from(counts.entries()).sort((a, b) => a[0] - b[0]).map(([p, n]) => `p${p}: ${n}`).join(", ");
+      ui_parts.push(
+        `> Distribution across ${total_doc_pages} document pages \u2014 ${distribution}. Pass \`page=N\` to filter to a specific document page.`
+      );
     }
-    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 = [
-    `> **Search Results** \u2014 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 = {};
-  for (const m of matches) {
+  for (const m of allMatches) {
     const matched_str = m[0];
     occurrences_map[matched_str] = (occurrences_map[matched_str] || 0) + 1;
   }
@@ -281,19 +331,12 @@ ${ui_markdown2}`;
     }
     return path.join(" > ");
   }
-  let i = start_idx + 1;
-  for (const m of page_matches) {
+  let i = 1;
+  for (const m of 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 p_num = pageOfOffset(m_start);
     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);
@@ -306,7 +349,9 @@ ${ui_markdown2}`;
     }
     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.`);
+    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");
@@ -1209,10 +1254,10 @@ function getAssetContent(folder, filename, fallbackMessage) {
 var READ_DOCX_COMMON_DESC = "Reads a DOCX file. Returns text with inline CriticMarkup for Tracked Changes and Comments: {++inserted++}, {--deleted--}, {==highlighted==}{>>comment<<}. Set clean_view=True for the finalized 'Accepted' text without markup.\n\n";
 var READ_DOCX_TAIL = "Modes:\n- 'full' (default): paginated body content. Use page=N to navigate.\n- 'outline': heading map only \u2014 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.";
 var PROCESS_BATCH_COMMON_DESC = "Applies a batch of edits and review actions to a DOCX.\n\nAll changes evaluate against the ORIGINAL document state \u2014 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";
-var PROCESS_BATCH_OPERATIONS_DESC = "Each item in `changes` must specify a `type`:\n1. 'modify': Search-and-replace. `target_text` must uniquely match \u2014 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 \u2014 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 \u2014 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 \u2014 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.";
-var DIFF_DOCX_DESC = "Compares two DOCX files and returns a unified diff of their text content. Useful for analyzing differences between versions before editing.";
-var gitSha = "8fc8371";
-var packageVersion = "1.15.1";
+var 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') \u2014 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\u2026). `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 \u2014 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 \u2014 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 \u2014 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.";
+var DIFF_DOCX_DESC = "Compares two DOCX files and returns a compact `@@ Word Patch @@` diff \u2014 Adeu's token-level, sub-word patch format \u2014 of their text content. Useful for analyzing differences between versions before editing.";
+var gitSha = "2179c76";
+var packageVersion = "1.16.0";
 var buildTag = ` [Adeu v${packageVersion}+${gitSha}]`;
 var args = process.argv.slice(2);
 var scopeIdx = args.indexOf("--scope");
@@ -1225,7 +1270,7 @@ var server = new McpServer({
 var originalRegisterTool = server.registerTool.bind(server);
 server.registerTool = (name, schema, handler) => {
   if (schema && typeof schema === "object") {
-    if (schema.description) {
+    if (schema.description && !schema.description.includes(buildTag.trim())) {
       schema.description = schema.description.trim() + buildTag;
     }
   }
@@ -1315,11 +1360,17 @@ registerAppTool(
       mode: z.enum(["full", "outline", "appendix"]).default("full").describe(
         "'full' returns body content. 'outline' returns a structural heading map. 'appendix' returns defined terms."
       ),
-      page: z.union([z.number(), z.string()]).default(1).describe("Page number (1-indexed) for mode='full', or 'all' to return unpaginated."),
+      page: z.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)."
+      ),
       outline_max_level: z.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_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 } }
@@ -1339,7 +1390,12 @@ registerAppTool(
       const buf = readFileBytesOrThrow(file_path);
       if (mode === "outline") {
         const doc = await DocumentObject2.load(buf);
-        const extract_res = _extractTextFromDoc(doc, clean_view, true, true);
+        const extract_res = _extractTextFromDoc(
+          doc,
+          clean_view,
+          true,
+          true
+        );
         const res2 = build_outline_response(
           doc,
           extract_res.text,
@@ -1352,14 +1408,22 @@ registerAppTool(
       }
       const text = await extractTextFromBuffer(buf, clean_view);
       if (search_query !== void 0 && search_query !== null) {
-        const res2 = build_search_response(text, search_query, search_regex, search_case_sensitive, page, file_path);
+        const res2 = build_search_response(
+          text,
+          search_query,
+          search_regex,
+          search_case_sensitive,
+          page,
+          file_path
+        );
         return res2;
       }
+      const resolvedPage = page === void 0 || page === null ? 1 : typeof page === "number" ? page : parseInt(String(page), 10) || 1;
       if (mode === "appendix") {
-        const res2 = build_appendix_response(text, typeof page === "number" ? page : parseInt(page, 10) || 1, file_path);
+        const res2 = build_appendix_response(text, resolvedPage, file_path);
         return res2;
       }
-      const res = build_paginated_response(text, typeof page === "number" ? page : parseInt(page, 10) || 1, file_path);
+      const res = build_paginated_response(text, resolvedPage, file_path);
       return res;
     } catch (e) {
       return {
@@ -1374,6 +1438,34 @@ registerAppTool(
     }
   }
 );
+var 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\u2026"
+  ),
+  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 \u2014 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",
   {
@@ -1381,7 +1473,9 @@ server.registerTool(
     inputSchema: {
       original_docx_path: z.string().describe("Absolute path to the source file."),
       author_name: z.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'."),
+      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."
+      ),
       output_path: z.string().optional().describe("Optional output path."),
       dry_run: z.boolean().optional().default(false).describe(
         "If True, simulates the changes and returns a detailed preview report without modifying any files."
@@ -1538,7 +1632,7 @@ server.registerTool(
 server.registerTool(
   "finalize_document",
   {
-    description: "Prepares a document for external distribution or e-signature.",
+    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: {
       file_path: z.string().describe("Absolute path to the DOCX file."),
       output_path: z.string().optional().describe("Optional output path."),
@@ -1546,7 +1640,9 @@ server.registerTool(
       accept_all: z.boolean().optional().describe(
         "If true, auto-accepts all unresolved track changes before finalizing."
       ),
-      protection_mode: z.enum(["read_only", "encrypt"]).optional().describe("Native OOXML document locking."),
+      protection_mode: z.enum(["read_only", "encrypt"]).optional().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().optional().describe("Replace all remaining markup authorship with this name."),
       export_pdf: z.boolean().optional().describe("Ignored in this environment.")
@@ -1707,7 +1803,10 @@ function formatBatchResult(stats, outPath, dry_run) {
     res = `Batch complete. Saved to: ${outPath}
 `;
   }
-  const total_occurrences = stats.edits ? stats.edits.reduce((acc, e) => acc + (e.status === "applied" ? e.occurrences_modified || 1 : 0), 0) : 0;
+  const total_occurrences = stats.edits ? stats.edits.reduce(
+    (acc, e) => 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.
 `;
@@ -1760,8 +1859,8 @@ ${stats.skipped_details.join("\n")}`;
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  const gitSha2 = "8fc8371";
-  const buildTs = "2026-06-25T11:57:32.023Z";
+  const gitSha2 = "2179c76";
+  const buildTs = "2026-06-26T07:48:21.832Z";
   console.error(
     `Adeu MCP Server (Node.js Engine: ${identifyEngine()}) running on stdio build=${gitSha2}@${buildTs}`
   );