mcp-scraper 0.2.5 → 0.2.7

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.5";
+var PACKAGE_VERSION = "0.2.7";
 
 // 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 {
@@ -1513,6 +1946,24 @@ var DirectoryWorkflowInputSchema = {
   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.")
 };
+var RankTrackerModeSchema = import_zod2.z.enum(["maps", "organic", "ai_overview", "paa"]);
+var RankTrackerBlueprintInputSchema = {
+  projectName: import_zod2.z.string().min(1).optional().describe("Optional name for the rank tracker project, client, or campaign."),
+  targetDomain: import_zod2.z.string().min(1).optional().describe("Primary domain to track in organic results, AI Overview citations, and PAA sources, e.g. example.com."),
+  targetBusinessName: import_zod2.z.string().min(1).optional().describe("Primary Google Business Profile or brand/business name to match in Maps results. Required for reliable Maps rank tracking."),
+  trackingModes: import_zod2.z.array(RankTrackerModeSchema).min(1).max(4).default(["maps", "organic", "ai_overview", "paa"]).describe("Rank tracker surfaces to build. maps uses directory_workflow/maps_search. organic uses search_serp. ai_overview uses search_serp/harvest_paa. paa uses harvest_paa source presence."),
+  keywords: import_zod2.z.array(import_zod2.z.string().min(1)).max(200).default([]).describe("Seed keywords or service queries to track. Leave empty when the downstream AI should create the keyword table from user input."),
+  locations: import_zod2.z.array(import_zod2.z.string().min(1)).max(100).default([]).describe("Markets, cities, ZIPs, or service areas to track. Use city/state strings like Denver, CO for localized SERP and Maps checks."),
+  competitors: import_zod2.z.array(import_zod2.z.string().min(1)).max(100).default([]).describe("Optional competitor domains or business names to persist as comparison targets."),
+  database: import_zod2.z.enum(["postgres", "neon", "supabase", "sqlite", "mysql"]).default("postgres").describe("Database family the downstream AI should target when generating migrations."),
+  scheduleCadence: import_zod2.z.enum(["daily", "weekly", "monthly", "custom"]).default("weekly").describe("Default recurring rank check cadence for the generated cron/heartbeat plan."),
+  customCron: import_zod2.z.string().min(1).optional().describe("Cron expression to use when scheduleCadence is custom."),
+  timezone: import_zod2.z.string().min(1).default("UTC").describe("IANA timezone for scheduled rank checks, e.g. America/Denver."),
+  includeCron: import_zod2.z.boolean().default(true).describe("Include a cron or heartbeat worker plan. Keep true for production rank trackers."),
+  includeDashboard: import_zod2.z.boolean().default(true).describe("Include dashboard/reporting requirements in the generated prompt."),
+  includeAlerts: import_zod2.z.boolean().default(true).describe("Include alert rules for rank movement and SERP feature gains/losses."),
+  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 MapsSearchOutputSchema = {
   query: import_zod2.z.string(),
@@ -1588,6 +2039,39 @@ var DirectoryWorkflowOutputSchema = {
   })),
   durationMs: import_zod2.z.number().int().min(0)
 };
+var RankTrackerToolPlanOutput = import_zod2.z.object({
+  tool: import_zod2.z.string(),
+  purpose: import_zod2.z.string()
+});
+var RankTrackerTableOutput = import_zod2.z.object({
+  name: import_zod2.z.string(),
+  purpose: import_zod2.z.string(),
+  keyColumns: import_zod2.z.array(import_zod2.z.string())
+});
+var RankTrackerCronJobOutput = import_zod2.z.object({
+  name: import_zod2.z.string(),
+  purpose: import_zod2.z.string(),
+  modes: import_zod2.z.array(RankTrackerModeSchema),
+  recommendedTools: import_zod2.z.array(import_zod2.z.string())
+});
+var RankTrackerBlueprintOutputSchema = {
+  projectName: import_zod2.z.string(),
+  targetDomain: NullableString,
+  targetBusinessName: NullableString,
+  trackingModes: import_zod2.z.array(RankTrackerModeSchema),
+  database: import_zod2.z.string(),
+  recommendedTools: import_zod2.z.array(RankTrackerToolPlanOutput),
+  tables: import_zod2.z.array(RankTrackerTableOutput),
+  cron: import_zod2.z.object({
+    enabled: import_zod2.z.boolean(),
+    cadence: import_zod2.z.string(),
+    expression: import_zod2.z.string(),
+    timezone: import_zod2.z.string(),
+    jobs: import_zod2.z.array(RankTrackerCronJobOutput)
+  }),
+  metrics: import_zod2.z.array(import_zod2.z.string()),
+  implementationPrompt: import_zod2.z.string()
+};
 var OrganicResultOutput = import_zod2.z.object({
   position: import_zod2.z.number().int(),
   title: import_zod2.z.string(),
@@ -1802,6 +2286,329 @@ var CaptureSerpPageSnapshotsInputSchema = {
   debug: import_zod2.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics for page snapshot debugging. Use true for capture, network, or proxy troubleshooting.")
 };
 
+// src/mcp/rank-tracker-blueprint.ts
+var DEFAULT_MODES = ["maps", "organic", "ai_overview", "paa"];
+function normalizeDomain(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  try {
+    const url = new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`);
+    return url.hostname.replace(/^www\./, "").toLowerCase();
+  } catch {
+    return trimmed.replace(/^https?:\/\//, "").replace(/^www\./, "").split("/")[0]?.toLowerCase() || trimmed;
+  }
+}
+function uniqueModes(input) {
+  const modes = input?.length ? input : DEFAULT_MODES;
+  return [...new Set(modes)];
+}
+function cronExpression(cadence, customCron) {
+  if (cadence === "daily") return "15 6 * * *";
+  if (cadence === "monthly") return "15 6 1 * *";
+  if (cadence === "custom") return customCron?.trim() || "CUSTOM_CRON_EXPRESSION_REQUIRED";
+  return "15 6 * * 1";
+}
+function includes(modes, mode) {
+  return modes.includes(mode);
+}
+function buildToolPlan(modes) {
+  const plans = [];
+  const push = (tool, purpose) => {
+    if (!plans.some((plan) => plan.tool === tool)) plans.push({ tool, purpose });
+  };
+  push("credits_info", "Check account balance and rates before scheduling recurring rank checks.");
+  if (includes(modes, "maps")) {
+    push("directory_workflow", "Seed or refresh city-by-city Maps datasets when building local market coverage.");
+    push("maps_search", "Run recurring Google Maps category checks for each keyword and location.");
+    push("maps_place_intel", "Hydrate selected target or competitor GBP details when profile-level evidence is needed.");
+  }
+  if (includes(modes, "organic")) {
+    push("search_serp", "Capture localized organic rankings, local pack data, and AI Overview status without PAA expansion.");
+  }
+  if (includes(modes, "ai_overview")) {
+    push("search_serp", "Capture quick AI Overview detection and organic context for each tracked query.");
+    push("harvest_paa", "Use when AI Overview text, PAA context, or source-level evidence needs deeper capture.");
+  }
+  if (includes(modes, "paa")) {
+    push("harvest_paa", "Capture People Also Ask questions, answers, and source sites for PAA presence tracking.");
+  }
+  return plans;
+}
+function buildTables(modes, includeDashboard, includeAlerts, hasCompetitors) {
+  const tables = [
+    {
+      name: "rank_tracker_projects",
+      purpose: "One row per client, campaign, or tracked property.",
+      keyColumns: ["id", "name", "target_domain", "target_business_name", "database_mode", "timezone", "created_at"]
+    },
+    {
+      name: "rank_tracker_targets",
+      purpose: "Normalized target identities and match rules for domains, URLs, business names, CIDs, and competitors.",
+      keyColumns: ["id", "project_id", "kind", "value", "display_name", "match_rules_json", "active"]
+    },
+    {
+      name: "rank_tracker_keywords",
+      purpose: "Tracked keywords or service queries, separated from location so calls can localize correctly.",
+      keyColumns: ["id", "project_id", "keyword", "intent", "tags_json", "active"]
+    },
+    {
+      name: "rank_tracker_locations",
+      purpose: "Markets, cities, ZIPs, country/language settings, and proxy targeting hints.",
+      keyColumns: ["id", "project_id", "label", "gl", "hl", "proxy_zip", "device", "active"]
+    },
+    {
+      name: "rank_tracker_runs",
+      purpose: "Heartbeat table for every scheduled or manual rank check batch.",
+      keyColumns: ["id", "project_id", "scheduled_for", "started_at", "completed_at", "status", "idempotency_key", "error_message"]
+    }
+  ];
+  if (includes(modes, "organic")) {
+    tables.push({
+      name: "rank_tracker_organic_results",
+      purpose: "SERP organic result rows from search_serp, including target-domain matches and competitor rows.",
+      keyColumns: ["id", "run_id", "keyword_id", "location_id", "device", "position", "title", "url", "domain", "is_target"]
+    });
+  }
+  if (includes(modes, "maps")) {
+    tables.push({
+      name: "rank_tracker_maps_results",
+      purpose: "Google Maps result rows from maps_search and directory_workflow, including GBP identity fields.",
+      keyColumns: ["id", "run_id", "keyword_id", "location_id", "position", "business_name", "place_url", "cid", "website_url", "rating", "review_count", "is_target"]
+    });
+    tables.push({
+      name: "rank_tracker_market_seeds",
+      purpose: "Directory workflow city, population, ZIP-group, and market seed records used to build local tracking coverage.",
+      keyColumns: ["id", "project_id", "query", "city", "state", "population", "zip_group_json", "last_seeded_run_id"]
+    });
+  }
+  if (includes(modes, "ai_overview")) {
+    tables.push({
+      name: "rank_tracker_ai_overviews",
+      purpose: "AI Overview detection, text snapshot, citation domains, and target citation status per query/location.",
+      keyColumns: ["id", "run_id", "keyword_id", "location_id", "detected", "target_cited", "cited_domains_json", "overview_text"]
+    });
+  }
+  if (includes(modes, "paa")) {
+    tables.push({
+      name: "rank_tracker_paa_sources",
+      purpose: "People Also Ask questions, answers, and source sites, with target source presence flags.",
+      keyColumns: ["id", "run_id", "keyword_id", "location_id", "question", "answer", "source_title", "source_site", "target_present"]
+    });
+  }
+  if (hasCompetitors) {
+    tables.push({
+      name: "rank_tracker_competitor_snapshots",
+      purpose: "Per-run competitor visibility summaries across organic, Maps, AI Overview, and PAA surfaces.",
+      keyColumns: ["id", "run_id", "target_id", "surface", "best_position", "presence_count", "share_of_surface"]
+    });
+  }
+  if (includeDashboard) {
+    tables.push({
+      name: "rank_tracker_daily_metrics",
+      purpose: "Rollup table for dashboard charts, trend lines, and share-of-visibility summaries.",
+      keyColumns: ["id", "project_id", "metric_date", "keyword_id", "location_id", "surface", "metric_name", "metric_value"]
+    });
+  }
+  if (includeAlerts) {
+    tables.push({
+      name: "rank_tracker_alert_events",
+      purpose: "Deduplicated gain/loss events for rank movement, Maps top 3, AI Overview citations, and PAA source presence.",
+      keyColumns: ["id", "project_id", "run_id", "surface", "severity", "event_key", "message", "created_at", "acknowledged_at"]
+    });
+  }
+  return tables;
+}
+function buildCronJobs(modes, includeDashboard, includeAlerts) {
+  const jobs = [
+    {
+      name: "rank-tracker-dispatch",
+      purpose: "Find due keyword/location/mode combinations, create a rank_tracker_runs row, and enqueue idempotent work items.",
+      modes,
+      recommendedTools: ["credits_info"]
+    }
+  ];
+  if (includes(modes, "maps")) {
+    jobs.push({
+      name: "maps-rank-check",
+      purpose: "Run maps_search per keyword/location and optionally directory_workflow for market seed refreshes.",
+      modes: ["maps"],
+      recommendedTools: ["maps_search", "directory_workflow", "maps_place_intel"]
+    });
+  }
+  if (includes(modes, "organic") || includes(modes, "ai_overview")) {
+    jobs.push({
+      name: "serp-rank-check",
+      purpose: "Run search_serp per keyword/location/device and persist organic ranks, local pack, and AI Overview status.",
+      modes: modes.filter((mode) => mode === "organic" || mode === "ai_overview"),
+      recommendedTools: ["search_serp"]
+    });
+  }
+  if (includes(modes, "paa") || includes(modes, "ai_overview")) {
+    jobs.push({
+      name: "paa-ai-evidence-check",
+      purpose: "Run harvest_paa for PAA source presence and deeper AI Overview/PAA evidence where needed.",
+      modes: modes.filter((mode) => mode === "paa" || mode === "ai_overview"),
+      recommendedTools: ["harvest_paa"]
+    });
+  }
+  if (includeDashboard) {
+    jobs.push({
+      name: "rank-tracker-rollups",
+      purpose: "Aggregate raw rows into daily metrics for charts, comparison tables, and trend lines.",
+      modes,
+      recommendedTools: []
+    });
+  }
+  if (includeAlerts) {
+    jobs.push({
+      name: "rank-tracker-alerts",
+      purpose: "Compare latest run against prior snapshots and emit deduplicated visibility gain/loss events.",
+      modes,
+      recommendedTools: []
+    });
+  }
+  return jobs;
+}
+function buildMetrics(modes, includeDashboard, includeAlerts) {
+  const metrics = ["run_success_rate", "last_successful_run_at", "stale_keyword_location_count"];
+  if (includes(modes, "maps")) {
+    metrics.push("maps_best_position", "maps_top_3_presence", "maps_target_found", "maps_competitor_count_above_target");
+  }
+  if (includes(modes, "organic")) {
+    metrics.push("organic_best_position", "organic_top_3_presence", "organic_top_10_presence", "organic_best_url");
+  }
+  if (includes(modes, "ai_overview")) {
+    metrics.push("ai_overview_detected", "target_ai_overview_cited", "ai_overview_citation_domain_count");
+  }
+  if (includes(modes, "paa")) {
+    metrics.push("paa_question_count", "target_paa_source_count", "paa_presence_rate", "paa_source_domains");
+  }
+  if (includeDashboard) metrics.push("share_of_visibility", "position_delta_7d", "position_delta_30d");
+  if (includeAlerts) metrics.push("visibility_gain_events", "visibility_loss_events");
+  return metrics;
+}
+function listOrPlaceholder(values, fallback) {
+  const clean = values?.map((value) => value.trim()).filter(Boolean) ?? [];
+  if (!clean.length) return fallback;
+  return clean.map((value) => `- ${value}`).join("\n");
+}
+function buildPrompt(input, modes, tools, tables, jobs, metrics, expression, targetDomain, targetBusinessName) {
+  const keywords = listOrPlaceholder(input.keywords, "- TODO: add tracked keywords");
+  const locations = listOrPlaceholder(input.locations, "- TODO: add tracked markets/locations");
+  const competitors = listOrPlaceholder(input.competitors, "- Optional: add competitor domains or GBP names");
+  const notes = input.notes?.trim() || "No extra implementation notes.";
+  return [
+    "You are building a production rank tracker powered by MCP Scraper. Create the database migrations, scheduled worker, ingestion functions, and dashboard/query layer described below.",
+    "",
+    `Project: ${input.projectName || "MCP Scraper Rank Tracker"}`,
+    `Target domain: ${targetDomain || "TODO_TARGET_DOMAIN"}`,
+    `Target business/GBP name: ${targetBusinessName || "TODO_TARGET_BUSINESS_NAME"}`,
+    `Database target: ${input.database || "postgres"}`,
+    `Tracking modes: ${modes.join(", ")}`,
+    "",
+    "Seed keywords:",
+    keywords,
+    "",
+    "Seed locations:",
+    locations,
+    "",
+    "Competitors:",
+    competitors,
+    "",
+    "MCP Scraper calls to use:",
+    tools.map((tool) => `- ${tool.tool}: ${tool.purpose}`).join("\n"),
+    "",
+    "Database tables to create:",
+    tables.map((table) => `- ${table.name}: ${table.keyColumns.join(", ")}`).join("\n"),
+    "",
+    "Scheduler and heartbeat requirements:",
+    `- Use cron expression "${expression}" in timezone "${input.timezone || "UTC"}" unless the user changes cadence.`,
+    "- Every scheduled batch must insert or update rank_tracker_runs before calling MCP tools.",
+    "- Use idempotency_key = project_id + keyword_id + location_id + mode + device + scheduled_date.",
+    "- Mark runs as running, succeeded, failed, or skipped; persist error_message on failures.",
+    "- Run MCP calls sequentially by default because accounts have one concurrency slot unless the user bought more.",
+    "- Retry retryable upstream failures with backoff, but do not duplicate rows for the same idempotency key.",
+    "",
+    "Mode-specific ingestion rules:",
+    "- maps: Use directory_workflow to seed/refresh market coverage and maps_search for recurring keyword/location rank checks. Match the target by targetBusinessName, website domain, CID, and place URL when available.",
+    "- organic: Use search_serp and persist every organic result row. Compute the best targetDomain position and best ranking URL per keyword/location/device.",
+    "- ai_overview: Use search_serp for quick detection and harvest_paa when deeper text/source evidence is needed. Track detected, overview_text, cited domains, and whether targetDomain is cited.",
+    "- paa: Use harvest_paa and persist each question/source pair. Track whether sourceSite or answer/source evidence matches targetDomain, then compute PAA presence rate.",
+    "",
+    "Metrics to expose:",
+    metrics.map((metric) => `- ${metric}`).join("\n"),
+    "",
+    "Alert requirements:",
+    input.includeAlerts ? "- Emit deduplicated alert_events when target gains/loses Maps top 3, organic top 10, AI Overview citation, or PAA source presence." : "- Alerts are out of scope for this build unless the user asks for them.",
+    "",
+    "Dashboard requirements:",
+    input.includeDashboard ? "- Build views for latest position by keyword/location, trend deltas, competitors above target, AI Overview citations, and PAA source wins/losses." : "- Dashboard is out of scope for this build unless the user asks for it.",
+    "",
+    "Extra notes:",
+    notes
+  ].join("\n");
+}
+function buildRankTrackerBlueprint(input) {
+  const trackingModes = uniqueModes(input.trackingModes);
+  const targetDomain = normalizeDomain(input.targetDomain);
+  const targetBusinessName = input.targetBusinessName?.trim() || null;
+  const projectName = input.projectName?.trim() || "MCP Scraper Rank Tracker";
+  const database = input.database || "postgres";
+  const expression = cronExpression(input.scheduleCadence || "weekly", input.customCron);
+  const tools = buildToolPlan(trackingModes);
+  const tables = buildTables(trackingModes, input.includeDashboard !== false, input.includeAlerts !== false, Boolean(input.competitors?.length));
+  const jobs = input.includeCron === false ? [] : buildCronJobs(trackingModes, input.includeDashboard !== false, input.includeAlerts !== false);
+  const metrics = buildMetrics(trackingModes, input.includeDashboard !== false, input.includeAlerts !== false);
+  const implementationPrompt = buildPrompt(input, trackingModes, tools, tables, jobs, metrics, expression, targetDomain, targetBusinessName);
+  const blueprint = {
+    projectName,
+    targetDomain,
+    targetBusinessName,
+    trackingModes,
+    database,
+    recommendedTools: tools,
+    tables,
+    cron: {
+      enabled: input.includeCron !== false,
+      cadence: input.scheduleCadence || "weekly",
+      expression: input.includeCron === false ? "disabled" : expression,
+      timezone: input.timezone || "UTC",
+      jobs
+    },
+    metrics,
+    implementationPrompt
+  };
+  const text = [
+    `# ${projectName}`,
+    "",
+    "Rank tracker build blueprint generated from MCP Scraper tool capabilities.",
+    "",
+    "## Modes",
+    trackingModes.map((mode) => `- ${mode}`).join("\n"),
+    "",
+    "## Recommended MCP Tools",
+    tools.map((tool) => `- \`${tool.tool}\` - ${tool.purpose}`).join("\n"),
+    "",
+    "## Database Tables",
+    tables.map((table) => `- \`${table.name}\` - ${table.purpose}`).join("\n"),
+    "",
+    "## Cron / Heartbeat",
+    blueprint.cron.enabled ? `- Cadence: ${blueprint.cron.cadence}
+- Cron: \`${blueprint.cron.expression}\`
+- Timezone: ${blueprint.cron.timezone}
+- Jobs: ${jobs.map((job) => job.name).join(", ")}` : "- Disabled by input. Still create rank_tracker_runs for manual runs.",
+    "",
+    "## Implementation Prompt",
+    "```text",
+    implementationPrompt,
+    "```"
+  ].join("\n");
+  return {
+    content: [{ type: "text", text }],
+    structuredContent: blueprint
+  };
+}
+
 // src/mcp/paa-mcp-server.ts
 function liveWebToolAnnotations(title) {
   return {
@@ -1812,10 +2619,19 @@ function liveWebToolAnnotations(title) {
     openWorldHint: true
   };
 }
+function localPlanningToolAnnotations(title) {
+  return {
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  };
+}
 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 [];
   }
@@ -1839,9 +2655,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 }] };
     }
   );
@@ -1940,6 +2756,13 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
     outputSchema: DirectoryWorkflowOutputSchema,
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
   }, async (input) => formatDirectoryWorkflow(await executor.directoryWorkflow(input), input));
+  server2.registerTool("rank_tracker_blueprint", {
+    title: "Rank Tracker Blueprint Builder",
+    description: "Generate a build-ready database, cron/heartbeat, ingestion, metrics, and AI implementation prompt for a rank tracker powered by MCP Scraper. Supports Maps rankings through directory_workflow/maps_search, organic rankings through search_serp, AI Overview citation tracking, and People Also Ask source presence tracking. This tool is local planning only; it does not call the web or spend credits.",
+    inputSchema: RankTrackerBlueprintInputSchema,
+    outputSchema: RankTrackerBlueprintOutputSchema,
+    annotations: localPlanningToolAnnotations("Rank Tracker Blueprint Builder")
+  }, async (input) => buildRankTrackerBlueprint(input));
   server2.registerTool("credits_info", {
     title: "MCP Scraper Credits & Costs",
     description: "Answer questions about MCP Scraper credits: current credit balance, what a specific tool/action costs, the full cost table, and optionally recent credit ledger entries. Does not expose payment methods or credit card information.",
@@ -1958,7 +2781,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();