mcp-scraper 0.2.6 → 0.2.8

package/dist/bin/mcp-scraper-combined-stdio-server.cjs

@@ -3,8 +3,8 @@
 
 // bin/mcp-scraper-combined-stdio-server.ts
 var import_node_fs4 = require("fs");
-var import_node_os3 = require("os");
-var import_node_path4 = require("path");
+var import_node_os4 = require("os");
+var import_node_path5 = require("path");
 var import_mcp3 = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
@@ -134,11 +134,11 @@ var HttpMcpToolExecutor = class {
 // src/mcp/browser-agent-mcp-server.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_node_fs = require("fs");
-var import_node_os = require("os");
-var import_node_path = require("path");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
 
 // src/version.ts
-var PACKAGE_VERSION = "0.2.6";
+var PACKAGE_VERSION = "0.2.8";
 
 // src/mcp/browser-agent-tool-schemas.ts
 var import_zod = require("zod");
@@ -151,6 +151,19 @@ var BrowserOpenInputSchema = {
 var BrowserSessionInputSchema = {
   session_id: import_zod.z.string().describe("The session id returned by browser_open.")
 };
+var BrowserLocateTargetSchema = import_zod.z.object({
+  name: import_zod.z.string().optional().describe("Optional label for this target, echoed in the result."),
+  selector: import_zod.z.string().optional().describe('CSS selector for the exact DOM element to locate, for example h1, input[name="q"], or [data-testid="result"].'),
+  text: import_zod.z.string().optional().describe("Visible text to locate when a selector is not known. The tool returns the text range bounds when possible."),
+  match: import_zod.z.enum(["contains", "exact"]).default("contains").describe("How to match text targets. Defaults to contains."),
+  index: import_zod.z.number().int().min(0).default(0).describe("Zero-based match index when multiple elements match.")
+}).refine((value) => Boolean(value.selector || value.text), {
+  message: "target requires selector or text"
+});
+var BrowserLocateInputSchema = {
+  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  targets: import_zod.z.array(BrowserLocateTargetSchema).min(1).max(20).describe("DOM targets to locate in the current viewport. Use selectors for exact elements, or text for visible text ranges.")
+};
 var BrowserGotoInputSchema = {
   session_id: import_zod.z.string().describe("The session id returned by browser_open."),
   url: import_zod.z.string().url().describe("URL to navigate the browser to.")
@@ -187,16 +200,315 @@ var BrowserReplayDownloadInputSchema = {
   replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays."),
   filename: import_zod.z.string().optional().describe("Optional local MP4 filename. Defaults to a timestamped replay filename.")
 };
+var BrowserReplayAnnotationSchema = import_zod.z.object({
+  type: import_zod.z.enum(["box", "circle", "underline", "arrow", "label"]).default("box").describe("Annotation style to draw over the replay."),
+  start_seconds: import_zod.z.number().min(0).default(0).describe("When the annotation should appear in the replay."),
+  end_seconds: import_zod.z.number().min(0).optional().describe("When the annotation should disappear. Defaults to two seconds after start_seconds."),
+  left: import_zod.z.number().optional().describe("Target left edge in browser screenshot pixels. Use element.left from browser_screenshot/browser_read."),
+  top: import_zod.z.number().optional().describe("Target top edge in browser screenshot pixels. Use element.top from browser_screenshot/browser_read."),
+  width: import_zod.z.number().positive().optional().describe("Target width in browser screenshot pixels. Use element.width from browser_screenshot/browser_read."),
+  height: import_zod.z.number().positive().optional().describe("Target height in browser screenshot pixels. Use element.height from browser_screenshot/browser_read."),
+  x: import_zod.z.number().optional().describe("Point target x coordinate in browser screenshot pixels when no box is available."),
+  y: import_zod.z.number().optional().describe("Point target y coordinate in browser screenshot pixels when no box is available."),
+  from_x: import_zod.z.number().optional().describe("Arrow start x coordinate in browser screenshot pixels. Defaults near the target."),
+  from_y: import_zod.z.number().optional().describe("Arrow start y coordinate in browser screenshot pixels. Defaults near the target."),
+  to_x: import_zod.z.number().optional().describe("Arrow target x coordinate in browser screenshot pixels. Defaults to the target box center."),
+  to_y: import_zod.z.number().optional().describe("Arrow target y coordinate in browser screenshot pixels. Defaults to the target box center."),
+  label: import_zod.z.string().max(120).optional().describe("Optional text callout to render near the annotation."),
+  color: import_zod.z.string().regex(/^#?[0-9a-fA-F]{6}$/).optional().describe("Annotation color as hex, for example #ff3b30."),
+  thickness: import_zod.z.number().min(1).max(24).optional().describe("Stroke thickness in pixels. Defaults to 5.")
+});
+var BrowserReplayMarkInputSchema = {
+  session_id: import_zod.z.string().describe("The session id returned by browser_open. A replay must already be recording."),
+  target: BrowserLocateTargetSchema.describe("The exact DOM element or text range to mark in the current viewport."),
+  type: import_zod.z.enum(["box", "circle", "underline", "arrow"]).default("box").describe("Annotation style to generate. Labels are included on the returned annotation when label is provided."),
+  label: import_zod.z.string().max(120).optional().describe("Optional callout text to render near the target."),
+  color: import_zod.z.string().regex(/^#?[0-9a-fA-F]{6}$/).optional().describe("Annotation color as hex, for example #ff3b30."),
+  thickness: import_zod.z.number().min(1).max(24).optional().describe("Stroke thickness in pixels. Defaults to 5."),
+  padding: import_zod.z.number().min(0).max(80).default(8).describe("Pixels to expand the DOM bounds so the highlight does not touch the text edge."),
+  start_offset_seconds: import_zod.z.number().min(-5).max(10).default(-0.25).describe("Offset from the current replay time. Negative values make the callout appear just before the mark action is captured."),
+  duration_seconds: import_zod.z.number().min(0.5).max(30).default(4).describe("How long the generated annotation should remain visible.")
+};
+var BrowserReplayAnnotateInputSchema = {
+  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  replay_id: import_zod.z.string().describe("The replay id returned by browser_replay_start or browser_list_replays."),
+  annotations: import_zod.z.array(BrowserReplayAnnotationSchema).min(1).max(50).describe("Timed overlay annotations to render on the replay. Prefer annotations returned by browser_replay_mark; otherwise use exact DOM bounds from browser_locate/browser_screenshot/browser_read."),
+  filename: import_zod.z.string().optional().describe("Optional output MP4 filename. Defaults to a timestamped annotated replay filename."),
+  source_width: import_zod.z.number().positive().optional().describe("Width of the screenshot coordinate space used for annotations. Defaults to the replay video width."),
+  source_height: import_zod.z.number().positive().optional().describe("Height of the coordinate space used for annotations. When this is a page viewport height smaller than the replay video height, the annotator infers the browser chrome top offset."),
+  source_left_offset: import_zod.z.number().min(0).optional().describe("Optional explicit X offset from annotation coordinates to replay video coordinates. Usually omitted."),
+  source_top_offset: import_zod.z.number().min(0).optional().describe("Optional explicit Y offset from annotation coordinates to replay video coordinates. Usually omitted because browser chrome offset is inferred when source_height is a page viewport height.")
+};
 var BrowserListInputSchema = {
   include_closed: import_zod.z.boolean().default(false).describe("Include closed sessions in the list.")
 };
 
+// src/mcp/replay-annotator.ts
+var import_node_child_process = require("child_process");
+var import_promises = require("fs/promises");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var import_node_util = require("util");
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function formatAssTime(seconds) {
+  const safe = Math.max(0, seconds);
+  const hours = Math.floor(safe / 3600);
+  const minutes = Math.floor(safe % 3600 / 60);
+  const wholeSeconds = Math.floor(safe % 60);
+  const centiseconds = Math.floor((safe - Math.floor(safe)) * 100);
+  return `${hours}:${String(minutes).padStart(2, "0")}:${String(wholeSeconds).padStart(2, "0")}.${String(centiseconds).padStart(2, "0")}`;
+}
+function cssHexToAssColor(color) {
+  const normalized = color?.trim().match(/^#?([0-9a-fA-F]{6})$/)?.[1] ?? "ff3b30";
+  const red = normalized.slice(0, 2);
+  const green = normalized.slice(2, 4);
+  const blue = normalized.slice(4, 6);
+  return `&H${blue}${green}${red}&`;
+}
+function escapeAssText(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\{/g, "\\{").replace(/\}/g, "\\}").replace(/\r?\n/g, "\\N");
+}
+function resolveCoordinateTransform(video, source, options) {
+  const explicitOffsetX = finiteNumber(options.sourceLeftOffset) ? options.sourceLeftOffset : null;
+  const explicitOffsetY = finiteNumber(options.sourceTopOffset) ? options.sourceTopOffset : null;
+  const inferredTopOffset = explicitOffsetY == null && Math.round(source.width) === Math.round(video.width) && source.height < video.height && video.height - source.height <= 220 ? video.height - source.height : 0;
+  const offsetX = explicitOffsetX ?? 0;
+  const offsetY = explicitOffsetY ?? inferredTopOffset;
+  return {
+    scaleX: (video.width - offsetX) / source.width,
+    scaleY: (video.height - offsetY) / source.height,
+    offsetX,
+    offsetY
+  };
+}
+function transformPoint(x, y, transform) {
+  return {
+    x: x * transform.scaleX + transform.offsetX,
+    y: y * transform.scaleY + transform.offsetY
+  };
+}
+function scaleRect(annotation, transform) {
+  if (finiteNumber(annotation.left) && finiteNumber(annotation.top) && finiteNumber(annotation.width) && finiteNumber(annotation.height)) {
+    const origin = transformPoint(annotation.left, annotation.top, transform);
+    return {
+      left: origin.x,
+      top: origin.y,
+      width: annotation.width * transform.scaleX,
+      height: annotation.height * transform.scaleY
+    };
+  }
+  if (finiteNumber(annotation.x) && finiteNumber(annotation.y)) {
+    const radius = finiteNumber(annotation.width) ? annotation.width / 2 : 28;
+    const point = transformPoint(annotation.x, annotation.y, transform);
+    return {
+      left: point.x - radius * transform.scaleX,
+      top: point.y - radius * transform.scaleY,
+      width: radius * 2 * transform.scaleX,
+      height: radius * 2 * transform.scaleY
+    };
+  }
+  throw new Error("annotation needs either left/top/width/height or x/y");
+}
+function rectPath(rect) {
+  const x1 = Math.round(rect.left);
+  const y1 = Math.round(rect.top);
+  const x2 = Math.round(rect.left + rect.width);
+  const y2 = Math.round(rect.top + rect.height);
+  return `m ${x1} ${y1} l ${x2} ${y1} l ${x2} ${y2} l ${x1} ${y2} l ${x1} ${y1}`;
+}
+function ellipsePath(rect) {
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+  const rx = Math.max(4, rect.width / 2);
+  const ry = Math.max(4, rect.height / 2);
+  const points = [];
+  for (let i = 0; i <= 32; i += 1) {
+    const t = Math.PI * 2 * i / 32;
+    const x = Math.round(cx + Math.cos(t) * rx);
+    const y = Math.round(cy + Math.sin(t) * ry);
+    points.push(`${i === 0 ? "m" : "l"} ${x} ${y}`);
+  }
+  return points.join(" ");
+}
+function filledRectPath(left, top, width, height) {
+  return rectPath({ left, top, width, height });
+}
+function arrowPath(fromX, fromY, toX, toY, thickness) {
+  const dx = toX - fromX;
+  const dy = toY - fromY;
+  const length = Math.max(1, Math.hypot(dx, dy));
+  const ux = dx / length;
+  const uy = dy / length;
+  const px = -uy;
+  const py = ux;
+  const half = thickness / 2;
+  const head = Math.max(14, thickness * 4);
+  const baseX = toX - ux * head;
+  const baseY = toY - uy * head;
+  const p1x = Math.round(fromX + px * half);
+  const p1y = Math.round(fromY + py * half);
+  const p2x = Math.round(baseX + px * half);
+  const p2y = Math.round(baseY + py * half);
+  const p3x = Math.round(baseX + px * head * 0.55);
+  const p3y = Math.round(baseY + py * head * 0.55);
+  const p4x = Math.round(toX);
+  const p4y = Math.round(toY);
+  const p5x = Math.round(baseX - px * head * 0.55);
+  const p5y = Math.round(baseY - py * head * 0.55);
+  const p6x = Math.round(baseX - px * half);
+  const p6y = Math.round(baseY - py * half);
+  const p7x = Math.round(fromX - px * half);
+  const p7y = Math.round(fromY - py * half);
+  return `m ${p1x} ${p1y} l ${p2x} ${p2y} l ${p3x} ${p3y} l ${p4x} ${p4y} l ${p5x} ${p5y} l ${p6x} ${p6y} l ${p7x} ${p7y} l ${p1x} ${p1y}`;
+}
+function eventLine(start, end, body) {
+  return `Dialogue: 0,${formatAssTime(start)},${formatAssTime(end)},Default,,0,0,0,,${body}`;
+}
+function labelLine(start, end, x, y, label) {
+  const safeX = Math.round(x);
+  const safeY = Math.round(y);
+  return eventLine(
+    start,
+    end,
+    `{\\an7\\pos(${safeX},${safeY})\\fs30\\bord4\\shad0\\c&HFFFFFF&\\3c&H000000&}${escapeAssText(label)}`
+  );
+}
+function shapeLine(start, end, path, color, thickness, filled = false) {
+  const fillAlpha = filled ? "&H00&" : "&HFF&";
+  const border = filled ? 0 : thickness;
+  return eventLine(
+    start,
+    end,
+    `{\\an7\\pos(0,0)\\p1\\bord${border}\\shad0\\1a${fillAlpha}\\1c${color}\\3c${color}}${path}`
+  );
+}
+function buildAssSubtitle(options, video) {
+  const source = {
+    width: options.sourceWidth && options.sourceWidth > 0 ? options.sourceWidth : video.width,
+    height: options.sourceHeight && options.sourceHeight > 0 ? options.sourceHeight : video.height
+  };
+  const transform = resolveCoordinateTransform(video, source, options);
+  const lines = [];
+  for (const annotation of options.annotations) {
+    const start = Math.max(0, annotation.start_seconds ?? 0);
+    const end = annotation.end_seconds && annotation.end_seconds > start ? annotation.end_seconds : start + 2;
+    const type = annotation.type ?? "box";
+    const color = cssHexToAssColor(annotation.color);
+    const thickness = Math.round(clamp(annotation.thickness ?? 5, 2, 24));
+    if (type === "label") {
+      if (!annotation.label) throw new Error("label annotation needs label");
+      const rect2 = scaleRect(annotation, transform);
+      lines.push(labelLine(start, end, rect2.left, Math.max(8, rect2.top), annotation.label));
+      continue;
+    }
+    if (type === "arrow") {
+      const rect2 = finiteNumber(annotation.to_x) && finiteNumber(annotation.to_y) ? null : scaleRect(annotation, transform);
+      const toPoint = finiteNumber(annotation.to_x) && finiteNumber(annotation.to_y) ? transformPoint(annotation.to_x, annotation.to_y, transform) : null;
+      const toX = toPoint ? toPoint.x : rect2.left + rect2.width / 2;
+      const toY = toPoint ? toPoint.y : rect2.top + rect2.height / 2;
+      const fromPoint = finiteNumber(annotation.from_x) && finiteNumber(annotation.from_y) ? transformPoint(annotation.from_x, annotation.from_y, transform) : null;
+      const fromX = fromPoint ? fromPoint.x : clamp(toX - 120, 12, video.width - 12);
+      const fromY = fromPoint ? fromPoint.y : clamp(toY - 90, 12, video.height - 12);
+      lines.push(shapeLine(start, end, arrowPath(fromX, fromY, toX, toY, thickness), color, thickness, true));
+      if (annotation.label) lines.push(labelLine(start, end, fromX + 8, Math.max(96, fromY - 36), annotation.label));
+      continue;
+    }
+    const rect = scaleRect(annotation, transform);
+    if (type === "underline") {
+      const underlineTop = rect.top + rect.height + thickness;
+      lines.push(shapeLine(start, end, filledRectPath(rect.left, underlineTop, rect.width, thickness), color, 0, true));
+    } else if (type === "circle") {
+      lines.push(shapeLine(start, end, ellipsePath(rect), color, thickness));
+    } else {
+      lines.push(shapeLine(start, end, rectPath(rect), color, thickness));
+    }
+    if (annotation.label) lines.push(labelLine(start, end, rect.left, Math.max(8, rect.top - 38), annotation.label));
+  }
+  return [
+    "[Script Info]",
+    "ScriptType: v4.00+",
+    `PlayResX: ${Math.round(video.width)}`,
+    `PlayResY: ${Math.round(video.height)}`,
+    "ScaledBorderAndShadow: yes",
+    "",
+    "[V4+ Styles]",
+    "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
+    "Style: Default,Arial,30,&H00FFFFFF,&H000000FF,&H00000000,&H90000000,0,0,0,0,100,100,0,0,1,2,0,7,0,0,0,1",
+    "",
+    "[Events]",
+    "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
+    ...lines,
+    ""
+  ].join("\n");
+}
+async function videoSize(inputFilePath) {
+  const { stdout } = await execFileAsync("ffprobe", [
+    "-v",
+    "error",
+    "-select_streams",
+    "v:0",
+    "-show_entries",
+    "stream=width,height",
+    "-of",
+    "json",
+    inputFilePath
+  ], { maxBuffer: 1024 * 1024 });
+  const parsed = JSON.parse(stdout);
+  const stream = parsed.streams?.[0];
+  if (!stream?.width || !stream.height) throw new Error("could not read replay video dimensions");
+  return { width: stream.width, height: stream.height };
+}
+function ffmpegFilterPath(path) {
+  return path.replace(/\\/g, "\\\\").replace(/:/g, "\\:");
+}
+async function annotateReplayVideo(inputFilePath, outputFilePath, options) {
+  if (!options.annotations.length) throw new Error("annotations must include at least one item");
+  const size = await videoSize(inputFilePath);
+  const tmp = await (0, import_promises.mkdtemp)((0, import_node_path.join)((0, import_node_os.tmpdir)(), "mcp-scraper-ass-"));
+  const assPath = (0, import_node_path.join)(tmp, "annotations.ass");
+  try {
+    await (0, import_promises.writeFile)(assPath, buildAssSubtitle(options, size), "utf8");
+    await execFileAsync("ffmpeg", [
+      "-y",
+      "-i",
+      inputFilePath,
+      "-vf",
+      `ass=${ffmpegFilterPath(assPath)}`,
+      "-c:v",
+      "libx264",
+      "-pix_fmt",
+      "yuv420p",
+      "-movflags",
+      "+faststart",
+      "-c:a",
+      "copy",
+      outputFilePath
+    ], { maxBuffer: 1024 * 1024 * 20 });
+    const out = await (0, import_promises.stat)(outputFilePath);
+    return {
+      filePath: outputFilePath,
+      bytes: out.size,
+      width: size.width,
+      height: size.height,
+      annotationCount: options.annotations.length
+    };
+  } finally {
+    await (0, import_promises.rm)(tmp, { recursive: true, force: true });
+  }
+}
+
 // src/mcp/browser-agent-mcp-server.ts
 function textResult(value, isError = false) {
   return { content: [{ type: "text", text: JSON.stringify(value) }], isError };
 }
 function outputBaseDir() {
-  return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path.join)((0, import_node_os.homedir)(), "Downloads", "mcp-scraper");
+  return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path2.join)((0, import_node_os2.homedir)(), "Downloads", "mcp-scraper");
 }
 function safeFilePart(value) {
   return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120) || "replay";
@@ -205,7 +517,32 @@ function replayFilePath(sessionId, replayId, filename) {
   const requested = filename?.trim();
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   const name = requested ? safeFilePart(requested).replace(/\.mp4$/i, "") : `${stamp}-${safeFilePart(sessionId)}-${safeFilePart(replayId)}`;
-  return (0, import_node_path.join)(outputBaseDir(), "browser-replays", `${name}.mp4`);
+  return (0, import_node_path2.join)(outputBaseDir(), "browser-replays", `${name}.mp4`);
+}
+function annotatedReplayFilePath(sessionId, replayId, filename) {
+  const requested = filename?.trim();
+  if (requested) return replayFilePath(sessionId, replayId, requested);
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  return replayFilePath(sessionId, replayId, `${stamp}-${safeFilePart(sessionId)}-${safeFilePart(replayId)}-annotated`);
+}
+function finiteNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function expandElementBounds(element, viewport, padding) {
+  const sourceWidth = finiteNumber2(viewport?.width) && viewport.width > 0 ? viewport.width : 1920;
+  const sourceHeight = finiteNumber2(viewport?.height) && viewport.height > 0 ? viewport.height : 1080;
+  const left = Math.max(0, element.left - padding);
+  const top = Math.max(0, element.top - padding);
+  const right = Math.min(sourceWidth, element.left + element.width + padding);
+  const bottom = Math.min(sourceHeight, element.top + element.height + padding);
+  return {
+    left,
+    top,
+    width: Math.max(1, right - left),
+    height: Math.max(1, bottom - top),
+    sourceWidth,
+    sourceHeight
+  };
 }
 function registerBrowserAgentMcpTools(server2, opts) {
   const baseUrl2 = opts.baseUrl.replace(/\/$/, "");
@@ -239,7 +576,7 @@ function registerBrowserAgentMcpTools(server2, opts) {
       }
       const bytes = Buffer.from(await res.arrayBuffer());
       const filePath = replayFilePath(sessionId, replayId, filename);
-      (0, import_node_fs.mkdirSync)((0, import_node_path.join)(outputBaseDir(), "browser-replays"), { recursive: true });
+      (0, import_node_fs.mkdirSync)((0, import_node_path2.join)(outputBaseDir(), "browser-replays"), { recursive: true });
       (0, import_node_fs.writeFileSync)(filePath, bytes);
       return {
         ok: true,
@@ -323,6 +660,19 @@ function registerBrowserAgentMcpTools(server2, opts) {
       return textResult(res.data, !res.ok);
     }
   );
+  server2.registerTool(
+    "browser_locate",
+    {
+      title: "Locate DOM Targets",
+      description: "Locate exact visible DOM elements or text ranges in the current browser viewport and return left/top/width/height bounds in screenshot pixels. Use this before drawing annotations or when a callout must literally circle, box, underline, or point to a real element. Prefer CSS selectors for exact UI elements; use text when selector is unknown. When a replay is actively recording, the result includes replay_elapsed_seconds for timing.",
+      inputSchema: BrowserLocateInputSchema,
+      annotations: annotations("Locate DOM Targets", true)
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/locate`, { targets: input.targets });
+      return textResult(res.data, !res.ok);
+    }
+  );
   server2.registerTool(
     "browser_goto",
     {
@@ -450,6 +800,89 @@ function registerBrowserAgentMcpTools(server2, opts) {
       return textResult(res.data, !res.ok);
     }
   );
+  server2.registerTool(
+    "browser_replay_mark",
+    {
+      title: "Mark Replay Annotation",
+      description: "While a replay is actively recording, locate one exact DOM target and return a ready-to-use annotation object with DOM bounds and replay-relative timing. Use this instead of guessing start_seconds or drawing rough rectangles. Workflow: start browser_replay_start, navigate until the target is visible and stable, call browser_replay_mark for each callout, then stop the replay and pass the returned annotations to browser_replay_annotate.",
+      inputSchema: BrowserReplayMarkInputSchema,
+      annotations: annotations("Mark Replay Annotation", true)
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/locate`, { targets: [input.target] });
+      if (!res.ok) return textResult(res.data, true);
+      const target = res.data?.targets?.[0];
+      const element = target?.element;
+      const elapsed = res.data?.replay?.replay_elapsed_seconds;
+      if (!target?.found || !element) {
+        return textResult({ error: target?.error ?? "target not found in current viewport", target }, true);
+      }
+      if (!finiteNumber2(elapsed)) {
+        return textResult({ error: "no active replay clock found; call browser_replay_start before browser_replay_mark" }, true);
+      }
+      const padded = expandElementBounds(element, res.data?.viewport, input.padding ?? 8);
+      const start = Math.max(0, elapsed + (input.start_offset_seconds ?? -0.25));
+      const duration = input.duration_seconds ?? 4;
+      const annotation = {
+        type: input.type ?? "box",
+        start_seconds: Number(start.toFixed(3)),
+        end_seconds: Number((start + duration).toFixed(3)),
+        left: Math.round(padded.left),
+        top: Math.round(padded.top),
+        width: Math.round(padded.width),
+        height: Math.round(padded.height),
+        ...input.label ? { label: input.label } : {},
+        ...input.color ? { color: input.color } : {},
+        ...input.thickness ? { thickness: input.thickness } : {}
+      };
+      return textResult({
+        annotation,
+        source_width: padded.sourceWidth,
+        source_height: padded.sourceHeight,
+        replay: res.data.replay,
+        target,
+        hint: "Append annotation to your annotations array. Use source_width/source_height with browser_replay_annotate."
+      });
+    }
+  );
+  server2.registerTool(
+    "browser_replay_annotate",
+    {
+      title: "Annotate Replay MP4",
+      description: "Download a browser replay MP4, render visual annotations over it, and save a new annotated MP4 locally. Use this after browser_replay_stop when the user wants proof videos with circles, boxes, arrows, underlines, or labels. For accurate timing and placement, prefer annotations returned by browser_replay_mark while the replay is recording; otherwise use exact left/top/width/height bounds from browser_locate. If the replay video size differs from the screenshot coordinate space, pass source_width and source_height.",
+      inputSchema: BrowserReplayAnnotateInputSchema,
+      annotations: annotations("Annotate Replay MP4", true)
+    },
+    async (input) => {
+      const sourceName = input.filename ? `${input.filename}-source` : void 0;
+      const downloaded = await downloadReplay(input.session_id, input.replay_id, sourceName);
+      if (!downloaded.ok) return textResult(downloaded.data, true);
+      try {
+        const sourcePath = String(downloaded.data.file_path);
+        const outputPath = annotatedReplayFilePath(input.session_id, input.replay_id, input.filename);
+        (0, import_node_fs.mkdirSync)((0, import_node_path2.join)(outputBaseDir(), "browser-replays"), { recursive: true });
+        const result = await annotateReplayVideo(sourcePath, outputPath, {
+          annotations: input.annotations,
+          sourceWidth: input.source_width,
+          sourceHeight: input.source_height,
+          sourceLeftOffset: input.source_left_offset,
+          sourceTopOffset: input.source_top_offset
+        });
+        return textResult({
+          replay_id: input.replay_id,
+          source_file_path: sourcePath,
+          annotated_file_path: result.filePath,
+          bytes: result.bytes,
+          width: result.width,
+          height: result.height,
+          annotation_count: result.annotationCount,
+          mime_type: "video/mp4"
+        });
+      } catch (err) {
+        return textResult({ error: err instanceof Error ? err.message : String(err) }, true);
+      }
+    }
+  );
   server2.registerTool(
     "browser_close",
     {
@@ -483,12 +916,12 @@ function registerBrowserAgentMcpTools(server2, opts) {
 // src/mcp/paa-mcp-server.ts
 var import_mcp2 = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_node_fs3 = require("fs");
-var import_node_path3 = require("path");
+var import_node_path4 = require("path");
 
 // src/mcp/mcp-response-formatter.ts
 var import_node_fs2 = require("fs");
-var import_node_os2 = require("os");
-var import_node_path2 = require("path");
+var import_node_os3 = require("os");
+var import_node_path3 = require("path");
 
 // src/errors.ts
 function sanitizeVendorName(message) {
@@ -510,7 +943,7 @@ function reportTitle(full) {
   return title?.replace(/^#\s+/, "").trim() || "MCP Scraper Report";
 }
 function outputBaseDir2() {
-  return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path2.join)((0, import_node_os2.homedir)(), "Downloads", "mcp-scraper");
+  return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path3.join)((0, import_node_os3.homedir)(), "Downloads", "mcp-scraper");
 }
 function saveFullReport(full) {
   if (!reportSavingEnabled || process.env.MCP_SCRAPER_SAVE_REPORTS === "false") return null;
@@ -518,7 +951,7 @@ function saveFullReport(full) {
   try {
     (0, import_node_fs2.mkdirSync)(outDir, { recursive: true });
     const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const file = (0, import_node_path2.join)(outDir, `${stamp}-${slugifyReportName(reportTitle(full))}.md`);
+    const file = (0, import_node_path3.join)(outDir, `${stamp}-${slugifyReportName(reportTitle(full))}.md`);
     (0, import_node_fs2.writeFileSync)(file, full, "utf8");
     return file;
   } catch {
@@ -528,11 +961,11 @@ function saveFullReport(full) {
 function persistScreenshotLocally(base64, url) {
   if (!reportSavingEnabled || process.env.MCP_SCRAPER_SAVE_REPORTS === "false") return null;
   try {
-    const dir = (0, import_node_path2.join)(outputBaseDir2(), "screenshots");
+    const dir = (0, import_node_path3.join)(outputBaseDir2(), "screenshots");
     (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
     const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
     const slug = url.replace(/^https?:\/\//, "").replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "").slice(0, 60);
-    const filePath = (0, import_node_path2.join)(dir, `${stamp}-${slug}.png`);
+    const filePath = (0, import_node_path3.join)(dir, `${stamp}-${slug}.png`);
     (0, import_node_fs2.writeFileSync)(filePath, Buffer.from(base64, "base64"));
     return filePath;
   } catch {
@@ -623,12 +1056,17 @@ function errorAttemptsSection(body) {
     const browser = debug.browser ?? {};
     const kernel = browser.browserRuntime ?? browser.kernel ?? {};
     const proxyResolution = kernel.proxyResolution ?? {};
-    const network = browser.networkLocation ?? {};
+    const network = browser.networkLocation ?? {
+      ip: attempt.observedIp ?? attempt.observed_ip,
+      city: attempt.observedCity ?? attempt.observed_city,
+      region: attempt.observedRegion ?? attempt.observed_region
+    };
     const nav = browser.serpNavigation ?? {};
     const geo = [network.ip, network.city, network.region].filter(Boolean).join(" / ") || "geo unknown";
-    const sessionId = attempt.browser_session_id ?? attempt.kernel_session_id ?? kernel.sessionId ?? "unknown";
+    const sessionId = attempt.browser_session_id ?? attempt.browserSessionIdSuffix ?? attempt.kernel_session_id ?? kernel.sessionId ?? "unknown";
     const cleanupSucceeded = attempt.session_cleanup_succeeded ?? attempt.kernel_delete_succeeded;
-    return `- Attempt ${attempt.attempt_number ?? "?"}: ${attempt.outcome ?? attempt.status ?? "unknown"} \xB7 session ${sessionId} \xB7 proxy ${debug.request?.proxyMode ?? kernel.proxyMode ?? "unknown"}${proxyResolution.source ? `/${proxyResolution.source}` : ""} \xB7 ${geo} \xB7 CAPTCHA ${nav.captchaDetected === true ? "yes" : nav.captchaDetected === false ? "no" : "unknown"} \xB7 cleanup ${cleanupSucceeded === true ? "yes" : cleanupSucceeded === false ? "no" : "unknown"}`;
+    const proxySource = proxyResolution.source ?? attempt.proxyResolutionSource;
+    return `- Attempt ${attempt.attempt_number ?? attempt.attemptNumber ?? "?"}: ${attempt.outcome ?? attempt.status ?? "unknown"} \xB7 session ${sessionId} \xB7 proxy ${debug.request?.proxyMode ?? kernel.proxyMode ?? attempt.proxyMode ?? "unknown"}${proxySource ? `/${proxySource}` : ""} \xB7 ${geo} \xB7 CAPTCHA ${nav.captchaDetected === true ? "yes" : nav.captchaDetected === false ? "no" : "unknown"} \xB7 cleanup ${cleanupSucceeded === true ? "yes" : cleanupSucceeded === false ? "no" : "unknown"}`;
   });
   return `
 
@@ -1089,6 +1527,29 @@ ${rows}`,
     }
   };
 }
+function normalizeMapsAttempts(value) {
+  const attempts = Array.isArray(value) ? value : [];
+  return attempts.map((attempt, index) => ({
+    attemptNumber: attempt.attemptNumber ?? attempt.attempt_number ?? index + 1,
+    maxAttempts: attempt.maxAttempts ?? attempt.max_attempts ?? attempts.length,
+    status: attempt.status === "ok" ? "ok" : "failed",
+    outcome: attempt.outcome ?? attempt.status ?? "unknown",
+    willRetry: attempt.willRetry ?? attempt.will_retry ?? false,
+    durationMs: attempt.durationMs ?? attempt.duration_ms ?? 0,
+    resultCount: attempt.resultCount ?? attempt.result_count ?? 0,
+    error: attempt.error ? sanitizeVendorText(attempt.error) : null,
+    proxyMode: attempt.proxyMode ?? attempt.proxy_mode ?? "location",
+    proxyResolutionSource: attempt.proxyResolutionSource ?? attempt.proxy_resolution_source ?? null,
+    proxyIdSuffix: attempt.proxyIdSuffix ?? attempt.proxy_id_suffix ?? null,
+    proxyTargetLevel: attempt.proxyTargetLevel ?? attempt.proxy_target_level ?? null,
+    proxyTargetLocation: attempt.proxyTargetLocation ?? attempt.proxy_target_location ?? null,
+    proxyTargetZip: attempt.proxyTargetZip ?? attempt.proxy_target_zip ?? null,
+    browserSessionIdSuffix: attempt.browserSessionIdSuffix ?? attempt.browser_session_id ?? null,
+    observedIp: attempt.observedIp ?? attempt.observed_ip ?? null,
+    observedCity: attempt.observedCity ?? attempt.observed_city ?? null,
+    observedRegion: attempt.observedRegion ?? attempt.observed_region ?? null
+  }));
+}
 function formatCreditsInfo(raw, input) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
@@ -1161,6 +1622,8 @@ function formatMapsSearch(raw, input) {
   const searchQuery = d.searchQuery ?? [input.query, input.location].filter(Boolean).join(" ");
   const requestedMax = d.requestedMaxResults ?? input.maxResults ?? 10;
   const durationMs = d.durationMs;
+  const attempts = normalizeMapsAttempts(d.attempts);
+  const lastAttempt = attempts.at(-1);
   const rows = results.map((r) => {
     const rating = [r.rating, r.reviewCount ? `(${r.reviewCount})` : null].filter(Boolean).join(" ");
     return `| ${r.position} | ${cell(r.name)} | ${cell(r.category)} | ${cell(rating)} | ${cell(r.address)} | ${r.cidDecimal ? `\`${r.cidDecimal}\`` : "\u2014"} | ${r.websiteUrl ? `[site](${r.websiteUrl})` : "\u2014"} | [maps](${r.placeUrl}) |`;
@@ -1175,6 +1638,7 @@ ${meta}`;
   const full = [
     `# Google Maps Search: "${searchQuery}"`,
     `**Returned:** ${results.length} profile candidate${results.length === 1 ? "" : "s"} \xB7 **Requested max:** ${requestedMax} \xB7 **Limit:** 50`,
+    attempts.length ? `**Attempts:** ${attempts.length}/${lastAttempt?.maxAttempts ?? attempts.length} \xB7 **Proxy:** ${lastAttempt?.proxyMode ?? "unknown"}${lastAttempt?.proxyResolutionSource ? `/${lastAttempt.proxyResolutionSource}` : ""} \xB7 **Observed:** ${[lastAttempt?.observedCity, lastAttempt?.observedRegion].filter(Boolean).join(", ") || "unknown"}` : null,
     `
 ## Results
 | # | Name | Category | Rating | Address | CID | Website | Maps |
@@ -1198,6 +1662,7 @@ ${rows}`,
       requestedMaxResults: requestedMax,
       resultCount: results.length,
       results: normalizedResults,
+      attempts,
       durationMs: durationMs ?? 0
     }
   };
@@ -1208,6 +1673,7 @@ function formatDirectoryWorkflow(raw, input) {
   const d = parsed.data;
   const cities = (d.cities ?? []).map((city) => ({
     ...city,
+    attempts: normalizeMapsAttempts(city.attempts),
     results: city.results.map((result) => ({
       ...result,
       phone: result.phone ?? null,
@@ -1435,7 +1901,7 @@ var HarvestPaaInputSchema = {
   gl: import_zod2.z.string().length(2).default("us").describe("Google country code inferred from location or user language. Examples: United States us, United Kingdom gb, Japan jp, Canada ca, Australia au."),
   hl: import_zod2.z.string().default("en").describe("Google interface/content language inferred from the user request. Use en unless the user asks for another language or locale."),
   device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt and retries CAPTCHA, proxy tunnel failure, and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
   proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
   debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior.")
 };
@@ -1494,7 +1960,7 @@ var MapsSearchInputSchema = {
   gl: import_zod2.z.string().length(2).default("us").describe("Google country code inferred from location."),
   hl: import_zod2.z.string().length(2).default("en").describe("Language inferred from user request."),
   maxResults: import_zod2.z.number().int().min(1).max(50).default(10).describe("Number of Google Maps business/profile candidates to return. Default 10. Maximum 50. Use 10 unless the user asks for more."),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state Maps searches; it creates a fresh residential proxy ID when the browser service is available. Use configured for the server proxy ID, and none only for local direct-network debugging."),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state Maps searches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts. Use configured for the server proxy ID, and none only for local direct-network debugging."),
   proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or city-center ZIP."),
   debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics when debugging Maps localization, CAPTCHA, or proxy behavior.")
 };
@@ -1509,7 +1975,7 @@ var DirectoryWorkflowInputSchema = {
   includeZipGroups: import_zod2.z.boolean().default(true).describe("Attach ZIP groups from a configured US ZIPS CSV when available. Set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath in local/test mode."),
   usZipsCsvPath: import_zod2.z.string().optional().describe("Local/test-only path to a US ZIPS CSV with state_abbr, zipcode, county, city columns, such as Lead Magician tools/analytics/data/uszips.csv. Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead."),
   saveCsv: import_zod2.z.boolean().default(true).describe("Save a directory-ready CSV to the MCP Scraper output directory and return its path. CSV rows include source_location, result_position, business_name, review_stars, category, address, phone, hours_status, website_url, directions_url, place_url, CID fields, population, and ZIP groups."),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode for every city Maps search. Use location by default for US city/state batches; it creates fresh residential proxy IDs when the browser service is available. Use configured for the server proxy ID, and none only for local direct-network debugging."),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode for every city Maps search. Use location by default for US city/state batches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts per city. Use configured for the server proxy ID, and none only for local direct-network debugging."),
   proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting. Normally omit it so each city can use its Lead Magician ZIP group or city/state location."),
   debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics in each Maps browser session when supported.")
 };
@@ -1532,6 +1998,26 @@ var RankTrackerBlueprintInputSchema = {
   notes: import_zod2.z.string().max(4e3).optional().describe("Extra product, client, stack, or hosting requirements to include in the implementation prompt.")
 };
 var NullableString = import_zod2.z.string().nullable();
+var MapsSearchAttemptOutput = import_zod2.z.object({
+  attemptNumber: import_zod2.z.number().int().min(1),
+  maxAttempts: import_zod2.z.number().int().min(1),
+  status: import_zod2.z.enum(["ok", "failed"]),
+  outcome: import_zod2.z.string(),
+  willRetry: import_zod2.z.boolean(),
+  durationMs: import_zod2.z.number().int().min(0),
+  resultCount: import_zod2.z.number().int().min(0),
+  error: NullableString,
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]),
+  proxyResolutionSource: import_zod2.z.enum(["disabled", "location_reused", "location_created", "configured_fallback", "unavailable"]).nullable(),
+  proxyIdSuffix: NullableString,
+  proxyTargetLevel: import_zod2.z.enum(["zip", "city", "state"]).nullable(),
+  proxyTargetLocation: NullableString,
+  proxyTargetZip: NullableString,
+  browserSessionIdSuffix: NullableString,
+  observedIp: NullableString,
+  observedCity: NullableString,
+  observedRegion: NullableString
+});
 var MapsSearchOutputSchema = {
   query: import_zod2.z.string(),
   location: import_zod2.z.string().nullable(),
@@ -1556,6 +2042,7 @@ var MapsSearchOutputSchema = {
     directionsUrl: NullableString,
     metadata: import_zod2.z.array(import_zod2.z.string())
   })),
+  attempts: import_zod2.z.array(MapsSearchAttemptOutput),
   durationMs: import_zod2.z.number().int().min(0)
 };
 var DirectoryMapsBusinessOutput = import_zod2.z.object({
@@ -1602,6 +2089,7 @@ var DirectoryWorkflowOutputSchema = {
     error: NullableString,
     resultCount: import_zod2.z.number().int().min(0),
     durationMs: import_zod2.z.number().int().min(0),
+    attempts: import_zod2.z.array(MapsSearchAttemptOutput),
     results: import_zod2.z.array(DirectoryMapsBusinessOutput)
   })),
   durationMs: import_zod2.z.number().int().min(0)
@@ -1818,7 +2306,7 @@ var SearchSerpInputSchema = {
   gl: import_zod2.z.string().length(2).default("us").describe("Google country code inferred from location or user language."),
   hl: import_zod2.z.string().default("en").describe("Google interface/content language inferred from user request."),
   device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt and retries CAPTCHA, proxy tunnel failure, and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
   proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
   debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior."),
   pages: import_zod2.z.number().int().min(1).max(2).default(1).describe("Number of result pages to fetch (1\u20132)")
@@ -1829,7 +2317,7 @@ var CaptureSerpSnapshotInputSchema = {
   gl: import_zod2.z.string().length(2).default("us").describe("Google country code inferred from the requested market, e.g. us, gb, ca, au."),
   hl: import_zod2.z.string().default("en").describe("Google interface/content language inferred from the user request."),
   device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use mobile only when the user asks for mobile rankings or mobile SERP evidence."),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy behavior for capture. Use location for localized US residential evidence; it creates a fresh proxy ID per attempt and retries CAPTCHA, proxy tunnel failure, and wrong-location evidence before returning. Use configured only for the static residential proxy, and none only for direct-network debugging."),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location").describe("Proxy behavior for capture. Use location for localized US residential evidence; it creates a fresh proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static residential proxy, and none only for direct-network debugging."),
   proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting when a precise city-center or ZIP proxy is needed. With proxyMode location this ZIP is used for each fresh proxy attempt."),
   pages: import_zod2.z.number().int().min(1).max(2).default(1).describe("Number of Google result pages to capture. Use 1 normally and 2 only when the user needs deeper ranking evidence."),
   debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser, proxy, and location diagnostics. Use true when debugging localization, CAPTCHA, proxy selection, or capture reliability."),
@@ -2198,7 +2686,7 @@ function localPlanningToolAnnotations(title) {
 function listSavedReports() {
   try {
     const dir = outputBaseDir2();
-    return (0, import_node_fs3.readdirSync)(dir).filter((f) => f.endsWith(".md")).map((f) => ({ filename: f, mtimeMs: (0, import_node_fs3.statSync)((0, import_node_path3.join)(dir, f)).mtimeMs })).sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, 100);
+    return (0, import_node_fs3.readdirSync)(dir).filter((f) => f.endsWith(".md")).map((f) => ({ filename: f, mtimeMs: (0, import_node_fs3.statSync)((0, import_node_path4.join)(dir, f)).mtimeMs })).sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, 100);
   } catch {
     return [];
   }
@@ -2222,9 +2710,9 @@ function registerSavedReportResources(server2) {
     },
     async (uri, variables) => {
       const requested = Array.isArray(variables.filename) ? variables.filename[0] : variables.filename;
-      const filename = (0, import_node_path3.basename)(decodeURIComponent(String(requested ?? "")));
+      const filename = (0, import_node_path4.basename)(decodeURIComponent(String(requested ?? "")));
       if (!filename.endsWith(".md")) throw new Error("Only saved .md reports can be read");
-      const text = (0, import_node_fs3.readFileSync)((0, import_node_path3.join)(outputBaseDir2(), filename), "utf8");
+      const text = (0, import_node_fs3.readFileSync)((0, import_node_path4.join)(outputBaseDir2(), filename), "utf8");
       return { contents: [{ uri: uri.href, mimeType: "text/markdown", text }] };
     }
   );
@@ -2236,14 +2724,14 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
   if (savesReports) registerSavedReportResources(server2);
   server2.registerTool("harvest_paa", {
     title: "Google PAA + SERP Harvest",
-    description: withReportNote('Best default tool for Google search research. Extracts People Also Ask questions plus answers/source URLs, organic SERP, local pack when present, entity IDs (CID/GCID/KG MID), and AI Overview. Infer the user language: split topic from location (e.g. "best hvac company in Denver CO" => query "best hvac company", location "Denver, CO", gl "us", hl "en"). For US local SERPs, leave proxyMode as location so the service uses fresh residential proxy IDs across retries and rejects wrong-location evidence instead of returning a bad market. Use maxQuestions 30 normally, 100-200 for "full", "deep", "all", or comprehensive research. Deep harvests above 100 questions can run for several minutes with no interim progress \u2014 warn the user before starting one and keep maxQuestions at or below 100 unless they explicitly want a deep harvest. Credits are charged by extracted question; unused request hold is refunded.'),
+    description: withReportNote('Best default tool for Google search research. Extracts People Also Ask questions plus answers/source URLs, organic SERP, local pack when present, entity IDs (CID/GCID/KG MID), and AI Overview. Infer the user language: split topic from location (e.g. "best hvac company in Denver CO" => query "best hvac company", location "Denver, CO", gl "us", hl "en"). For US local SERPs, leave proxyMode as location so the service uses fresh residential proxy IDs across retries, briefly waits for browser-service automatic CAPTCHA/challenge solving when Google blocks a page, and rotates to a new proxy/session if the challenge does not clear or the market evidence is wrong. Use maxQuestions 30 normally, 100-200 for "full", "deep", "all", or comprehensive research. Deep harvests above 100 questions can run for several minutes with no interim progress \u2014 warn the user before starting one and keep maxQuestions at or below 100 unless they explicitly want a deep harvest. Credits are charged by extracted question; unused request hold is refunded.'),
     inputSchema: HarvestPaaInputSchema,
     outputSchema: HarvestPaaOutputSchema,
     annotations: liveWebToolAnnotations("Google PAA + SERP Harvest")
   }, async (input) => formatHarvestPaa(await executor.harvestPaa(input), input));
   server2.registerTool("search_serp", {
     title: "Google SERP Lookup",
-    description: withReportNote("Fast Google SERP lookup without PAA expansion. Use when the user asks for rankings, organic results, local pack, quick SERP, or positions. Split topic from location and infer gl/hl from the user request. For US city/state rankings, keep proxyMode as location and pass proxyZip when a city-center ZIP is known; location mode uses fresh residential proxy IDs and retries CAPTCHA, proxy tunnel failures, and wrong-location evidence before returning."),
+    description: withReportNote("Fast Google SERP lookup without PAA expansion. Use when the user asks for rankings, organic results, local pack, quick SERP, or positions. Split topic from location and infer gl/hl from the user request. For US city/state rankings, keep proxyMode as location and pass proxyZip when a city-center ZIP is known; location mode uses fresh residential proxy IDs, briefly waits for browser-service automatic CAPTCHA/challenge solving when Google blocks a page, and rotates to a new proxy/session if the challenge does not clear, the proxy tunnel fails, or location evidence is wrong."),
     inputSchema: SearchSerpInputSchema,
     outputSchema: SearchSerpOutputSchema,
     annotations: liveWebToolAnnotations("Google SERP Lookup")
@@ -2311,14 +2799,14 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
   }, async (input) => formatMapsPlaceIntel(await executor.mapsPlaceIntel(input), input));
   server2.registerTool("maps_search", {
     title: "Google Maps Business Search",
-    description: withReportNote('Search Google Maps for multiple businesses/profiles by category, niche, keyword, or local market. Use this when the user asks for several Google Business Profiles, GMBs, GBPs, leads, prospects, competitors, or "more than the 3-pack." For US city/state Maps searches, keep proxyMode as location so the browser service can create a fresh residential proxy ID for that market; pass proxyZip only when a specific ZIP or city-center ZIP is known. Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, and profile metadata. Default maxResults is 10; maximum is 50. Use maps_place_intel afterward only when a selected business needs full details and reviews.'),
+    description: withReportNote('Search Google Maps for multiple businesses/profiles by category, niche, keyword, or local market. Use this when the user asks for several Google Business Profiles, GMBs, GBPs, leads, prospects, competitors, or "more than the 3-pack." For US city/state Maps searches, keep proxyMode as location so the browser service creates a fresh residential proxy ID and browser session for the market; retryable failures rotate to a new proxy and new browser session for up to 5 attempts. Pass proxyZip only when a specific ZIP or city-center ZIP is known. Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, profile metadata, and sanitized attempt telemetry. Default maxResults is 10; maximum is 50. Use maps_place_intel afterward only when a selected business needs full details and reviews.'),
     inputSchema: MapsSearchInputSchema,
     outputSchema: MapsSearchOutputSchema,
     annotations: liveWebToolAnnotations("Google Maps Business Search")
   }, async (input) => formatMapsSearch(await executor.mapsSearch(input), input));
   server2.registerTool("directory_workflow", {
     title: "Directory Workflow: Markets + Maps",
-    description: withReportNote('Build directory/prospecting datasets by selecting US city markets from the free Census Population Estimates city/place dataset, optionally joining configured US ZIPS/Lead Magician ZIP groups, then running Google Maps business searches for each city in parallel. Use this when the user wants "all cities over 100k population in a state", "build a directory CSV", "find markets then get Maps data", or similar location-database + Maps workflows. Set minPopulation, state, query, maxResultsPerCity, and concurrency. Use concurrency up to 5 for parallel city sessions. Keep proxyMode as location so each city can use a fresh residential proxy ID when the browser service is available; retryable city failures use fresh proxies across attempts. Saved CSV rows include source_location, result_position, business_name, review_stars, category, address, phone, hours_status, website_url, directions_url, place_url, cid, cid_decimal, city population, and ZIP groups. This workflow captures star ratings from Maps list cards, not profile review counts; use maps_place_intel only when a selected profile needs deeper review details. For local Lead Magician ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath only in local/test mode.'),
+    description: withReportNote('Build directory/prospecting datasets by selecting US city markets from the free Census Population Estimates city/place dataset, optionally joining configured US ZIPS/Lead Magician ZIP groups, then running Google Maps business searches for each city in parallel. Use this when the user wants "all cities over 100k population in a state", "build a directory CSV", "find markets then get Maps data", or similar location-database + Maps workflows. Set minPopulation, state, query, maxResultsPerCity, and concurrency. Use concurrency up to 5 for parallel city sessions. Keep proxyMode as location so each city search creates fresh residential proxy IDs and browser sessions; retryable city failures rotate to a new proxy and new browser session for up to 5 attempts. Saved CSV rows include source_location, result_position, business_name, review_stars, category, address, phone, hours_status, website_url, directions_url, place_url, cid, cid_decimal, city population, and ZIP groups. Structured city results include sanitized attempt telemetry. This workflow captures star ratings from Maps list cards, not profile review counts; use maps_place_intel only when a selected profile needs deeper review details. For local Lead Magician ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath only in local/test mode.'),
     inputSchema: DirectoryWorkflowInputSchema,
     outputSchema: DirectoryWorkflowOutputSchema,
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
@@ -2348,7 +2836,7 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
 // bin/mcp-scraper-combined-stdio-server.ts
 function readApiKeyFile() {
   const explicitPath = process.env.MCP_SCRAPER_KEY_PATH?.trim();
-  const paths = [explicitPath, (0, import_node_path4.join)((0, import_node_os3.homedir)(), ".mcp-scraper-key")].filter(Boolean);
+  const paths = [explicitPath, (0, import_node_path5.join)((0, import_node_os4.homedir)(), ".mcp-scraper-key")].filter(Boolean);
   for (const path of paths) {
     try {
       const value = (0, import_node_fs4.readFileSync)(path, "utf8").trim();