@adeu/mcp-server 1.15.0 → 1.15.2

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");
@@ -1211,8 +1256,8 @@ var READ_DOCX_TAIL = "Modes:\n- 'full' (default): paginated body content. Use pa
 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 = "fa47c47";
-var packageVersion = "1.15.0";
+var gitSha = "23b2879";
+var packageVersion = "1.15.2";
 var buildTag = ` [Adeu v${packageVersion}+${gitSha}]`;
 var args = process.argv.slice(2);
 var scopeIdx = args.indexOf("--scope");
@@ -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.literal("all")]).default(1).describe("Page number (1-indexed) for mode='full', or 'all' to return unpaginated."),
-      outline_max_level: z.number().default(2).describe("For mode='outline' only: cap on heading depth."),
+      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 {
@@ -1611,15 +1675,15 @@ if (!isDocxOnly) {
         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.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().describe(
+        max_attachment_size_mb: z.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."
         )
       }),
@@ -1707,7 +1771,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 +1827,8 @@ ${stats.skipped_details.join("\n")}`;
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  const gitSha2 = "fa47c47";
-  const buildTs = "2026-06-25T10:39:47.565Z";
+  const gitSha2 = "23b2879";
+  const buildTs = "2026-06-25T13:51:23.036Z";
   console.error(
     `Adeu MCP Server (Node.js Engine: ${identifyEngine()}) running on stdio build=${gitSha2}@${buildTs}`
   );