@adeu/mcp-server 1.15.1 → 1.15.2

package/src/response-builders.ts

@@ -214,12 +214,11 @@ export function build_search_response(
   search_query: string,
   search_regex: boolean,
   search_case_sensitive: boolean,
-  page: number | string,
+  page: number | string | undefined,
   file_path: string,
 ): ToolResult {
   const [body] = split_structural_appendix(text);
-  const escapeRegExp = (s: string) =>
-    s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const flags = search_case_sensitive ? "g" : "gi";
   const patternStr = search_regex ? search_query : escapeRegExp(search_query);
 
@@ -230,54 +229,123 @@ export function build_search_response(
     throw new Error(`Invalid regex pattern: ${e.message}`);
   }
 
-  const matches = Array.from(body.matchAll(regex));
+  const allMatches = Array.from(body.matchAll(regex));
 
+  // Compute document pagination once — needed for both annotation and filtering.
+  const pag_res = paginate(body, "");
+  const page_offsets = pag_res.body_page_offsets;
+  const total_doc_pages = pag_res.total_pages;
+
+  // Resolve `page` parameter to either "all" or a concrete document-page number.
+  // Undefined → "all" (search across the whole document).
+  // "all" (case-insensitive) → "all".
+  // A positive integer N → filter matches to document page N.
+  // Anything else → hard error.
+  let filter_doc_page: number | null = null; // null means "all"
+  if (page !== undefined && 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 — 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;
+    }
+  }
+
+  // Helper: which document page does an offset live on?
+  const pageOfOffset = (offset: number): number => {
+    let p = 1;
+    for (let j = 0; j < page_offsets.length; j++) {
+      if (offset >= page_offsets[j]) p = j + 1;
+      else break;
+    }
+    return p;
+  };
+
+  // Apply the filter (if any), but keep a record of all pages that had hits
+  // so we can show a useful summary even when filtered.
+  const pagesWithHits = new Set<number>();
+  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);
+
+  // --- Empty result ---
   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}`;
+    let body_msg: string;
+    if (filter_doc_page !== null) {
+      if (allMatches.length === 0) {
+        body_msg = `> **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.`;
+      } else {
+        const hitPages = Array.from(pagesWithHits).sort((a, b) => a - b);
+        body_msg = `> **Search Results** — No matches for \`${search_query}\` on document page ${filter_doc_page}.\n\nThe 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** — 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${body_msg}`;
     return {
       content: [{ type: "text", text: llm_content }],
       structuredContent: {
-        markdown: ui_markdown,
+        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).`);
-    }
-    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);
+  // --- Build the response ---
+  const ui_parts: string[] = [];
 
-  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}\`.`);
+  if (filter_doc_page !== null) {
+    ui_parts.push(
+      `> **Search Results** — 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(", ")} — omit \`page\` or pass \`page='all'\` to see them.`,
+      );
+    }
+  } else {
+    ui_parts.push(
+      `> **Search Results** — Found ${matches.length} match${matches.length !== 1 ? "es" : ""} for \`${search_query}\` in \`${basename(file_path)}\`.`,
+    );
+    if (total_doc_pages > 1) {
+      // Build a per-page hit distribution: "p1: 3, p3: 1, p7: 12"
+      const counts = new Map<number, number>();
+      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 — ${distribution}. Pass \`page=N\` to filter to a specific document page.`,
+      );
+    }
   }
 
+  // Per-match occurrence counts use the FULL match set, not the filtered one —
+  // this gives the LLM accurate global counts even when filtering.
   const occurrences_map: Record<string, number> = {};
-  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;
   }
@@ -294,7 +362,10 @@ export function build_search_response(
       if (m) {
         const level = m[1].length;
         if (level < current_level) {
-          let cleanHeading = m[2].replace(/\*\*|__|[*_]/g, "").replace(/\{#[^}]+\}/g, "").trim();
+          let cleanHeading = m[2]
+            .replace(/\*\*|__|[*_]/g, "")
+            .replace(/\{#[^}]+\}/g, "")
+            .trim();
           if (cleanHeading.length > 80) {
             cleanHeading = cleanHeading.substring(0, 80) + "...";
           }
@@ -307,24 +378,19 @@ export function build_search_response(
     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);
+    const snippet =
+      body.substring(snippet_start, m_start) +
+      `**${matched_str}**` +
+      body.substring(m_end, snippet_end);
 
     const snippet_lines = snippet
       .split("\n")
@@ -342,7 +408,9 @@ export function build_search_response(
 
     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++;
   }

package/src/response_builders.test.ts

@@ -0,0 +1,266 @@
+// FILE: packages/mcp-server/src/response_builders.test.ts
+import { describe, it, expect } from "vitest";
+import { build_search_response } from "./response-builders.js";
+
+describe("build_search_response — page-as-document-filter semantics", () => {
+  // Small body: 3 matches all in one paragraph → all on document page 1.
+  function makeSmallBody(count: number): string {
+    const lines: string[] = ["# Section One"];
+    for (let i = 0; i < count; i++) {
+      lines.push(`Paragraph ${i} mentions the TARGET_PHRASE here.`);
+    }
+    return lines.join("\n\n");
+  }
+
+  // Large body designed to span multiple document pages (PAGE_TARGET_CHARS=19000).
+  // Each filler paragraph is ~500 chars, so ~40 paragraphs per document page.
+  // We seed TARGET_PHRASE at known intervals so we can predict page distribution.
+  function makeMultiPageBody(): string {
+    const filler =
+      "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.";
+    const blocks: string[] = [];
+    // ~50 paragraphs of filler before each marker, with TARGET_PHRASE injected at known places.
+    for (let i = 0; i < 200; i++) {
+      if (i === 10 || i === 11 || i === 12) {
+        blocks.push(`Paragraph ${i}: TARGET_PHRASE appears here.`);
+      } else if (i === 80) {
+        blocks.push(`Paragraph ${i}: TARGET_PHRASE appears here.`);
+      } else if (i === 150) {
+        blocks.push(`Paragraph ${i}: TARGET_PHRASE appears here.`);
+      } else {
+        blocks.push(`Paragraph ${i}: ${filler}`);
+      }
+    }
+    return blocks.join("\n\n");
+  }
+
+  it("page omitted with single-page doc: searches all, shows all matches", () => {
+    const body = makeSmallBody(3);
+    const res = build_search_response(
+      body,
+      "TARGET_PHRASE",
+      false,
+      true,
+      undefined,
+      "dummy.docx",
+    );
+    const text = res.content[0].text;
+
+    expect(text).toContain("Found 3 matches");
+    expect(text).toContain("### Match 1 (p1)");
+    expect(text).toContain("### Match 2 (p1)");
+    expect(text).toContain("### Match 3 (p1)");
+    // No clamp warning, no result-pagination hint.
+    expect(text).not.toContain("exceeds available result pages");
+    expect(text).not.toContain("Showing page");
+  });
+
+  it("page='all' explicit: same behavior as omitting", () => {
+    const body = makeSmallBody(3);
+    const res = build_search_response(
+      body,
+      "TARGET_PHRASE",
+      false,
+      true,
+      "all",
+      "dummy.docx",
+    );
+    expect(res.content[0].text).toContain("Found 3 matches");
+  });
+
+  it("page omitted with multi-page doc: shows distribution summary", () => {
+    const body = makeMultiPageBody();
+    const res = build_search_response(
+      body,
+      "TARGET_PHRASE",
+      false,
+      true,
+      undefined,
+      "dummy.docx",
+    );
+    const text = res.content[0].text;
+
+    expect(text).toContain("Found 5 matches");
+    expect(text).toContain("Distribution across");
+    expect(text).toMatch(/p\d+: \d+/);
+    expect(text).toContain("Pass `page=N` to filter");
+  });
+
+  it("page=N as document-page filter: only returns matches on that page", () => {
+    const body = makeMultiPageBody();
+
+    // First find out which doc pages actually have hits by doing an "all" search.
+    const allRes = build_search_response(
+      body,
+      "TARGET_PHRASE",
+      false,
+      true,
+      "all",
+      "dummy.docx",
+    );
+    const allText = allRes.content[0].text;
+    // Extract the first hit page from the Match annotations.
+    const firstMatchPageMatch = allText.match(/### Match 1 \(p(\d+)\)/);
+    expect(firstMatchPageMatch).not.toBeNull();
+    const firstHitPage = parseInt(firstMatchPageMatch![1], 10);
+
+    // Now filter to that page.
+    const res = build_search_response(
+      body,
+      "TARGET_PHRASE",
+      false,
+      true,
+      firstHitPage,
+      "dummy.docx",
+    );
+    const text = res.content[0].text;
+
+    expect(text).toContain(`on document page ${firstHitPage}`);
+    // All shown matches must be on the filtered page.
+    const matchPageRegex = /### Match \d+ \(p(\d+)\)/g;
+    const matches = Array.from(text.matchAll(matchPageRegex));
+    expect(matches.length).toBeGreaterThan(0);
+    for (const m of matches) {
+      expect(parseInt(m[1], 10)).toBe(firstHitPage);
+    }
+  });
+
+  it("page=N where N has no hits but query exists elsewhere: helpful message", () => {
+    const body = makeMultiPageBody();
+    // Find a page that has no hits. Multi-page body has hits on a few pages
+    // but several pages in between have none. Page 2 should be safe if hits
+    // are on early pages or much later pages.
+    // First, identify a hit-less page by checking the "all" output.
+    const allRes = build_search_response(
+      body,
+      "TARGET_PHRASE",
+      false,
+      true,
+      "all",
+      "dummy.docx",
+    );
+    const allText = allRes.content[0].text;
+    const hitPages = new Set<number>();
+    const matchPageRegex = /### Match \d+ \(p(\d+)\)/g;
+    for (const m of allText.matchAll(matchPageRegex)) {
+      hitPages.add(parseInt(m[1], 10));
+    }
+
+    // Find the total page count from the distribution line.
+    const distMatch = allText.match(/Distribution across (\d+) document pages/);
+    expect(distMatch).not.toBeNull();
+    const totalPages = parseInt(distMatch![1], 10);
+
+    // Find a page with no hits.
+    let emptyPage: number | null = null;
+    for (let p = 1; p <= totalPages; p++) {
+      if (!hitPages.has(p)) {
+        emptyPage = p;
+        break;
+      }
+    }
+    expect(emptyPage).not.toBeNull();
+
+    const res = build_search_response(
+      body,
+      "TARGET_PHRASE",
+      false,
+      true,
+      emptyPage!,
+      "dummy.docx",
+    );
+    const text = res.content[0].text;
+
+    expect(text).toContain(
+      `No matches for \`TARGET_PHRASE\` on document page ${emptyPage}`,
+    );
+    expect(text).toContain("The query DOES appear elsewhere");
+    expect(text).toContain("Omit `page` or pass `page='all'`");
+  });
+
+  it("page=N where N exceeds total document pages: hard error", () => {
+    const body = makeSmallBody(3); // Single-page document.
+    expect(() =>
+      build_search_response(
+        body,
+        "TARGET_PHRASE",
+        false,
+        true,
+        99,
+        "dummy.docx",
+      ),
+    ).toThrow(/Document page 99 is out of range/);
+  });
+
+  it("invalid page values throw with actionable message", () => {
+    const body = makeSmallBody(3);
+    expect(() =>
+      build_search_response(
+        body,
+        "TARGET_PHRASE",
+        false,
+        true,
+        0,
+        "dummy.docx",
+      ),
+    ).toThrow(/Invalid page value/);
+    expect(() =>
+      build_search_response(
+        body,
+        "TARGET_PHRASE",
+        false,
+        true,
+        "garbage",
+        "dummy.docx",
+      ),
+    ).toThrow(/Invalid page value/);
+  });
+
+  it("no matches anywhere: standard empty message", () => {
+    const body = makeSmallBody(3);
+    const res = build_search_response(
+      body,
+      "NONEXISTENT_TOKEN",
+      false,
+      true,
+      undefined,
+      "dummy.docx",
+    );
+    expect(res.content[0].text).toContain("No matches found");
+  });
+
+  it("occurrence counts are global, not filtered", () => {
+    const body = makeMultiPageBody();
+    // Filter to one specific page and verify the occurrence count reflects the full document.
+    const allRes = build_search_response(
+      body,
+      "TARGET_PHRASE",
+      false,
+      true,
+      "all",
+      "dummy.docx",
+    );
+    const totalMatches = (allRes.content[0].text.match(/### Match /g) || [])
+      .length;
+    expect(totalMatches).toBe(5);
+
+    // Now filter to the first hit page.
+    const firstPageMatch = allRes.content[0].text.match(
+      /### Match 1 \(p(\d+)\)/,
+    );
+    const firstHitPage = parseInt(firstPageMatch![1], 10);
+
+    const filteredRes = build_search_response(
+      body,
+      "TARGET_PHRASE",
+      false,
+      true,
+      firstHitPage,
+      "dummy.docx",
+    );
+    // The "Occurrences" line should still report the global count of 5.
+    expect(filteredRes.content[0].text).toContain(
+      "This exact phrasing appears 5 times in the document",
+    );
+  });
+});