mcp-scraper 0.2.1 → 0.2.3

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

@@ -0,0 +1,1990 @@
+#!/usr/bin/env node
+"use strict";
+
+// 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_mcp3 = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+
+// src/harvest-timeout.ts
+var VERCEL_FUNCTION_MAX_MS = 3e5;
+var CLIENT_OVER_SERVER_MARGIN_MS = 15e3;
+function harvestTimeoutBudget(maxQuestions, serpOnly = false) {
+  const requested = Number.isFinite(maxQuestions) && maxQuestions > 0 ? Math.trunc(maxQuestions) : 30;
+  let serverMs;
+  if (serpOnly || requested <= 50) serverMs = 11e4;
+  else if (requested <= 100) serverMs = 18e4;
+  else if (requested <= 150) serverMs = 24e4;
+  else serverMs = 28e4;
+  const clientMs = Math.min(serverMs + CLIENT_OVER_SERVER_MARGIN_MS, VERCEL_FUNCTION_MAX_MS - 5e3);
+  return { serverMs, clientMs };
+}
+
+// src/mcp/http-mcp-tool-executor.ts
+var HttpMcpToolExecutor = class {
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  httpTimeoutOverrideMs;
+  serpIntelligenceTimeoutMs;
+  constructor(baseUrl2, apiKey2) {
+    this.baseUrl = baseUrl2.replace(/\/$/, "");
+    this.apiKey = apiKey2;
+    const rawOverride = process.env.MCP_SCRAPER_HTTP_TIMEOUT_MS;
+    const parsedOverride = rawOverride === void 0 ? NaN : Number(rawOverride);
+    this.httpTimeoutOverrideMs = Number.isFinite(parsedOverride) && parsedOverride > 0 ? parsedOverride : null;
+    this.timeoutMs = this.httpTimeoutOverrideMs ?? 11e4;
+    const configuredSerpIntelligenceTimeoutMs = Number(process.env.MCP_SCRAPER_SERP_INTELLIGENCE_HTTP_TIMEOUT_MS ?? this.timeoutMs);
+    this.serpIntelligenceTimeoutMs = Number.isFinite(configuredSerpIntelligenceTimeoutMs) && configuredSerpIntelligenceTimeoutMs > 0 ? configuredSerpIntelligenceTimeoutMs : this.timeoutMs;
+  }
+  async call(path, body, timeoutMs = this.timeoutMs) {
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        return { content: [{ type: "text", text: JSON.stringify(data) }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (err instanceof DOMException && err.name === "TimeoutError") {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              error: "mcp_request_timeout",
+              error_type: "timeout",
+              retryable: true,
+              path,
+              timeoutMs,
+              message: `MCP Scraper request exceeded ${Math.round(timeoutMs / 1e3)}s and was cancelled. Retry with fewer results or use the async API for deep harvests.`
+            })
+          }],
+          isError: true
+        };
+      }
+      return { content: [{ type: "text", text: msg }], isError: true };
+    }
+  }
+  harvestPaa(input) {
+    const timeoutMs = this.httpTimeoutOverrideMs ?? harvestTimeoutBudget(input.maxQuestions ?? 30).clientMs;
+    return this.call("/harvest/sync", input, timeoutMs);
+  }
+  searchSerp(input) {
+    const timeoutMs = this.httpTimeoutOverrideMs ?? harvestTimeoutBudget(0, true).clientMs;
+    return this.call("/harvest/sync", { ...input, serpOnly: true }, timeoutMs);
+  }
+  extractUrl(input) {
+    return this.call("/extract-url", input);
+  }
+  mapSiteUrls(input) {
+    return this.call("/map-urls", input);
+  }
+  extractSite(input) {
+    return this.call("/extract-site", input);
+  }
+  youtubeHarvest(input) {
+    return this.call("/youtube/harvest", input);
+  }
+  youtubeTranscribe(input) {
+    return this.call("/youtube/transcribe", input);
+  }
+  facebookPageIntel(input) {
+    return this.call("/facebook/page-intel", input);
+  }
+  facebookAdSearch(input) {
+    return this.call("/facebook/search", input);
+  }
+  facebookAdTranscribe(input) {
+    return this.call("/facebook/transcribe", input);
+  }
+  mapsPlaceIntel(input) {
+    return this.call("/maps/place", input);
+  }
+  mapsSearch(input) {
+    return this.call("/maps/search", input);
+  }
+  directoryWorkflow(input) {
+    const cityCount = typeof input.maxCities === "number" ? input.maxCities : 25;
+    const concurrency = typeof input.concurrency === "number" && input.concurrency > 0 ? input.concurrency : 5;
+    const timeoutMs = this.httpTimeoutOverrideMs ?? Math.min(9e5, Math.max(18e4, Math.ceil(cityCount / concurrency) * 12e4));
+    return this.call("/directory/run", input, timeoutMs);
+  }
+  creditsInfo(input) {
+    return this.call("/billing/credits", input);
+  }
+  captureSerpSnapshot(input) {
+    return this.call("/serp-intelligence/capture", input, this.serpIntelligenceTimeoutMs);
+  }
+  captureSerpPageSnapshots(input) {
+    return this.call("/serp-intelligence/page-snapshots", input, this.serpIntelligenceTimeoutMs);
+  }
+};
+
+// 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");
+
+// src/version.ts
+var PACKAGE_VERSION = "0.2.3";
+
+// src/mcp/browser-agent-tool-schemas.ts
+var import_zod = require("zod");
+var BrowserOpenInputSchema = {
+  label: import_zod.z.string().optional().describe("Optional human label for this session, shown in the watch console."),
+  url: import_zod.z.string().url().optional().describe("Optional URL to navigate to immediately after opening."),
+  profile: import_zod.z.string().optional().describe("Optional saved profile name to load a logged-in session for a site."),
+  timeout_seconds: import_zod.z.number().int().min(60).max(259200).optional().describe("How long the session may live before auto-termination. Defaults to 600. The browser idles into a zero-cost standby between actions, so a longer timeout is cheap.")
+};
+var BrowserSessionInputSchema = {
+  session_id: import_zod.z.string().describe("The session id returned by browser_open.")
+};
+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.")
+};
+var BrowserClickInputSchema = {
+  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  x: import_zod.z.number().describe("X coordinate to click, in screenshot pixels. Use the x of an element from the latest screenshot."),
+  y: import_zod.z.number().describe("Y coordinate to click, in screenshot pixels."),
+  button: import_zod.z.enum(["left", "right", "middle"]).default("left").describe("Mouse button."),
+  num_clicks: import_zod.z.number().int().min(1).max(3).optional().describe("Number of clicks, e.g. 2 for double-click.")
+};
+var BrowserTypeInputSchema = {
+  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  text: import_zod.z.string().describe("Text to type at the current focus. Click a field first to focus it."),
+  delay: import_zod.z.number().int().min(0).max(500).optional().describe("Optional per-keystroke delay in ms for human-like typing.")
+};
+var BrowserScrollInputSchema = {
+  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  delta_y: import_zod.z.number().default(5).describe("Vertical scroll in wheel units. Positive scrolls down, negative up."),
+  delta_x: import_zod.z.number().default(0).describe("Horizontal scroll in wheel units."),
+  x: import_zod.z.number().optional().describe("X position to scroll at. Defaults to screen center."),
+  y: import_zod.z.number().optional().describe("Y position to scroll at. Defaults to screen center.")
+};
+var BrowserPressInputSchema = {
+  session_id: import_zod.z.string().describe("The session id returned by browser_open."),
+  keys: import_zod.z.array(import_zod.z.string()).min(1).describe('Keys or combinations to press, e.g. ["Return"], ["Ctrl+a"], ["Ctrl+Shift+Tab"].')
+};
+var BrowserReplayStopInputSchema = {
+  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.")
+};
+var BrowserReplayDownloadInputSchema = {
+  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."),
+  filename: import_zod.z.string().optional().describe("Optional local MP4 filename. Defaults to a timestamped replay filename.")
+};
+var BrowserListInputSchema = {
+  include_closed: import_zod.z.boolean().default(false).describe("Include closed sessions in the list.")
+};
+
+// 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");
+}
+function safeFilePart(value) {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120) || "replay";
+}
+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`);
+}
+function registerBrowserAgentMcpTools(server2, opts) {
+  const baseUrl2 = opts.baseUrl.replace(/\/$/, "");
+  const consoleBase = (opts.consoleBaseUrl ?? opts.baseUrl).replace(/\/$/, "");
+  const timeoutMs = opts.timeoutMs ?? 9e4;
+  async function req(method, path, body) {
+    try {
+      const res = await fetch(`${baseUrl2}${path}`, {
+        method,
+        headers: { "Content-Type": "application/json", "x-api-key": opts.apiKey },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      const data = await res.json().catch(() => ({}));
+      return { ok: res.ok, data };
+    } catch (err) {
+      return { ok: false, data: { error: err instanceof Error ? err.message : String(err) } };
+    }
+  }
+  async function downloadReplay(sessionId, replayId, filename) {
+    const path = `/agent/sessions/${encodeURIComponent(sessionId)}/replays/${encodeURIComponent(replayId)}/download`;
+    try {
+      const res = await fetch(`${baseUrl2}${path}`, {
+        method: "GET",
+        headers: { "x-api-key": opts.apiKey },
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(async () => ({ error: await res.text().catch(() => `HTTP ${res.status}`) }));
+        return { ok: false, data };
+      }
+      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.writeFileSync)(filePath, bytes);
+      return {
+        ok: true,
+        data: {
+          replay_id: replayId,
+          file_path: filePath,
+          bytes: bytes.length,
+          mime_type: res.headers.get("content-type") ?? "video/mp4",
+          download_url: `${baseUrl2}${path}`
+        }
+      };
+    } catch (err) {
+      return { ok: false, data: { error: err instanceof Error ? err.message : String(err) } };
+    }
+  }
+  const annotations = (title, readOnly = false) => ({
+    title,
+    readOnlyHint: readOnly,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  });
+  server2.registerTool(
+    "browser_open",
+    {
+      title: "Open Browser Session",
+      description: "Open a fresh cloud browser you can drive. Returns a session_id used by all other browser_* tools, and a watch_url where a human can watch live or take over. Anti-bot stealth and automatic CAPTCHA/Cloudflare solving are on by default: if a Cloudflare or CAPTCHA challenge appears, do NOT click it \u2014 wait a few seconds and call browser_screenshot again; it is solved automatically. Billing: metered per second of active browser work at ~4 credits per minute; idle and standby time are free. Call browser_close when done to stop the meter. After opening, call browser_screenshot to see the page.",
+      inputSchema: BrowserOpenInputSchema,
+      annotations: annotations("Open Browser Session")
+    },
+    async (input) => {
+      const open = await req("POST", "/agent/sessions", {
+        label: input.label,
+        profile: input.profile,
+        timeout_seconds: input.timeout_seconds
+      });
+      if (!open.ok) return textResult(open.data, true);
+      const session = open.data;
+      if (input.url) {
+        await req("POST", `/agent/sessions/${session.session_id}/goto`, { url: input.url });
+      }
+      return textResult({
+        session_id: session.session_id,
+        watch_url: `${consoleBase}/console/${session.session_id}`,
+        live_view_url: session.live_view_url ?? null,
+        hint: "Call browser_screenshot to see the page. Click by the x,y of an element from the snapshot."
+      });
+    }
+  );
+  server2.registerTool(
+    "browser_screenshot",
+    {
+      title: "See Page (Screenshot + Elements)",
+      description: "Capture what the browser currently shows. Returns a screenshot image PLUS a text snapshot listing interactive elements with their center x,y coordinates, the page url and title, and visible text. This is your primary way to perceive the page. Click elements by their listed x,y. If a Cloudflare/CAPTCHA challenge is visible, wait and screenshot again rather than clicking it.",
+      inputSchema: BrowserSessionInputSchema,
+      annotations: annotations("See Page", true)
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/screenshot`);
+      if (!res.ok) return textResult(res.data, true);
+      const { image_base64, mime_type, url, title, elements, text } = res.data;
+      const content = [];
+      if (image_base64) content.push({ type: "image", data: image_base64, mimeType: mime_type ?? "image/png" });
+      content.push({
+        type: "text",
+        text: JSON.stringify({ url, title, elements, text })
+      });
+      return { content };
+    }
+  );
+  server2.registerTool(
+    "browser_read",
+    {
+      title: "Read Page Text + Elements",
+      description: "Return the page url, title, visible text, and the list of interactive elements (with x,y) without an image. Cheaper than browser_screenshot when you only need to read content or find a target element to click.",
+      inputSchema: BrowserSessionInputSchema,
+      annotations: annotations("Read Page", true)
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/read`);
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_goto",
+    {
+      title: "Navigate To URL",
+      description: "Navigate the browser to a URL. Follow with browser_screenshot to see the result.",
+      inputSchema: BrowserGotoInputSchema,
+      annotations: annotations("Navigate To URL")
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/goto`, { url: input.url });
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_click",
+    {
+      title: "Click",
+      description: "Click at x,y (screenshot pixel coordinates). Use the x,y of a target element from the latest browser_screenshot or browser_read.",
+      inputSchema: BrowserClickInputSchema,
+      annotations: annotations("Click")
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/click`, {
+        x: input.x,
+        y: input.y,
+        button: input.button,
+        num_clicks: input.num_clicks
+      });
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_type",
+    {
+      title: "Type Text",
+      description: 'Type text at the current focus. Click an input field first to focus it. Use browser_press with ["Return"] to submit.',
+      inputSchema: BrowserTypeInputSchema,
+      annotations: annotations("Type Text")
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/type`, { text: input.text, delay: input.delay });
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_scroll",
+    {
+      title: "Scroll",
+      description: "Scroll the page. Positive delta_y scrolls down. Follow with browser_screenshot to see newly revealed content.",
+      inputSchema: BrowserScrollInputSchema,
+      annotations: annotations("Scroll")
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/scroll`, {
+        delta_y: input.delta_y,
+        delta_x: input.delta_x,
+        x: input.x,
+        y: input.y
+      });
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_press",
+    {
+      title: "Press Keys",
+      description: 'Press keys or combinations, e.g. ["Return"] to submit, ["Ctrl+a"] to select all, ["Ctrl+Shift+Tab"] to switch tabs.',
+      inputSchema: BrowserPressInputSchema,
+      annotations: annotations("Press Keys")
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/press`, { keys: input.keys });
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_replay_start",
+    {
+      title: "Start Recording",
+      description: "Start recording an MP4 replay of the session. Returns replay_id, view_url when available, and a download_url. Use to capture a task for later review; stop with browser_replay_stop.",
+      inputSchema: BrowserSessionInputSchema,
+      annotations: annotations("Start Recording")
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/replay/start`);
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_replay_stop",
+    {
+      title: "Stop Recording",
+      description: "Stop a replay recording and expose the final view_url and download_url. Use browser_replay_download to save the MP4 locally.",
+      inputSchema: BrowserReplayStopInputSchema,
+      annotations: annotations("Stop Recording")
+    },
+    async (input) => {
+      const res = await req("POST", `/agent/sessions/${input.session_id}/replay/stop`, { replay_id: input.replay_id });
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_list_replays",
+    {
+      title: "List Replay Videos",
+      description: "List replay recordings for a browser session, including final view_url and authenticated download_url values when available.",
+      inputSchema: BrowserSessionInputSchema,
+      annotations: annotations("List Replay Videos", true)
+    },
+    async (input) => {
+      const res = await req("GET", `/agent/sessions/${input.session_id}/replays`);
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_replay_download",
+    {
+      title: "Download Replay MP4",
+      description: "Download a replay recording through MCP Scraper and save the MP4 locally under MCP_SCRAPER_OUTPUT_DIR/browser-replays. Use after browser_replay_stop or browser_list_replays.",
+      inputSchema: BrowserReplayDownloadInputSchema,
+      annotations: annotations("Download Replay MP4", true)
+    },
+    async (input) => {
+      const res = await downloadReplay(input.session_id, input.replay_id, input.filename);
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_close",
+    {
+      title: "Close Browser Session",
+      description: "Close and release the browser session when the task is done.",
+      inputSchema: BrowserSessionInputSchema,
+      annotations: { title: "Close Browser Session", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    async (input) => {
+      const res = await req("DELETE", `/agent/sessions/${input.session_id}`);
+      return textResult(res.data, !res.ok);
+    }
+  );
+  server2.registerTool(
+    "browser_list_sessions",
+    {
+      title: "List Browser Sessions",
+      description: "List your browser sessions and their status, with a watch_url for each.",
+      inputSchema: BrowserListInputSchema,
+      annotations: annotations("List Browser Sessions", true)
+    },
+    async (input) => {
+      const res = await req("GET", `/agent/sessions${input.include_closed ? "?all=1" : ""}`);
+      if (!res.ok) return textResult(res.data, true);
+      const sessions = (res.data.sessions ?? []).map((s) => ({ ...s, watch_url: `${consoleBase}/console/${s.session_id}` }));
+      return textResult({ sessions });
+    }
+  );
+}
+
+// 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");
+
+// src/mcp/mcp-response-formatter.ts
+var import_node_fs2 = require("fs");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+
+// src/errors.ts
+function sanitizeVendorName(message) {
+  return message.replace(/kernel\.sh\s+sessions?/gi, "sessions").replace(/kernel\.sh\s+session/gi, "this session").replace(/kernel\.sh/gi, "the service").replace(/kernel\s+sessions?/gi, "sessions").replace(/kernel\s+session/gi, "this session").replace(/\bkernel\b/gi, "the service").replace(/  +/g, " ").trim();
+}
+
+// src/mcp/mcp-response-formatter.ts
+var reportSavingEnabled = true;
+function sanitizeVendorText(text) {
+  return sanitizeVendorName(
+    text.replace(/kernel_session_id/gi, "browser_session_id").replace(/kernel_delete_succeeded/gi, "session_cleanup_succeeded").replace(/kernel_delete_started/gi, "session_cleanup_started").replace(/kernel_delete_error/gi, "session_cleanup_error").replace(/kernelSessionId/g, "browserSessionId").replace(/kernelProxyId/g, "proxyId").replace(/KERNEL_API_KEY/g, "BROWSER_SERVICE_API_KEY").replace(/"kernel"\s*:/gi, '"browserRuntime":')
+  );
+}
+function slugifyReportName(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "mcp-scraper-report";
+}
+function reportTitle(full) {
+  const title = full.split("\n").find((line) => line.startsWith("# "));
+  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");
+}
+function saveFullReport(full) {
+  if (!reportSavingEnabled || process.env.MCP_SCRAPER_SAVE_REPORTS === "false") return null;
+  const outDir = outputBaseDir2();
+  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`);
+    (0, import_node_fs2.writeFileSync)(file, full, "utf8");
+    return file;
+  } catch {
+    return null;
+  }
+}
+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");
+    (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`);
+    (0, import_node_fs2.writeFileSync)(filePath, Buffer.from(base64, "base64"));
+    return filePath;
+  } catch {
+    return null;
+  }
+}
+function oneBlock(content) {
+  const filePath = saveFullReport(content);
+  const text = filePath ? `${content}
+
+\u{1F4C4} Saved: \`${filePath}\`` : content;
+  return { content: [{ type: "text", text }] };
+}
+function formatStructuredError(body, fallback) {
+  if (body.error === "insufficient_balance") {
+    return `Insufficient credits. Balance: ${body.balance_credits} credits. This call requires ${body.required_credits} credits. Top up at ${body.topup_url}`;
+  }
+  if (body.error === "mcp_request_timeout") {
+    return typeof body.message === "string" ? body.message : "MCP Scraper request timed out and was cancelled.";
+  }
+  if (typeof body.error_code === "string") {
+    const message = typeof body.error === "string" ? body.error : typeof body.message === "string" ? body.message : fallback;
+    const retryable = body.retryable === true ? " Retryable: yes." : "";
+    return `${body.error_code}: ${message}${retryable}${errorAttemptsSection(body)}`;
+  }
+  if (typeof body.error === "string") return body.error;
+  return fallback || "Tool error";
+}
+function parseData(raw) {
+  const first = raw.content.find((b) => b.type === "text");
+  const text = first?.type === "text" ? first.text : "";
+  try {
+    const parsed = JSON.parse(text || "{}");
+    if (raw.isError || parsed.error || parsed.error_code) return { error: sanitizeVendorText(formatStructuredError(parsed, text)) };
+    const data = parsed.result ?? parsed;
+    return { data };
+  } catch {
+    if (raw.isError) return { error: sanitizeVendorText(text || "Tool error") };
+    return { error: "Failed to parse tool response" };
+  }
+}
+function entityIdsSection(ids) {
+  if (!ids) return "";
+  const lines = [];
+  if (ids.kgIds?.length) lines.push(`- **Knowledge Graph MID:** ${ids.kgIds.join(", ")}`);
+  if (ids.cids?.length) lines.push(`- **CID:** ${ids.cids.join(", ")}`);
+  if (ids.gcids?.length) lines.push(`- **GCID:** ${ids.gcids.join(", ")}`);
+  return lines.length ? `
+## Entity IDs
+${lines.join("\n")}` : "";
+}
+function truncate(s, max) {
+  if (!s) return "";
+  return s.length > max ? s.slice(0, max) + "\u2026" : s;
+}
+function cell(s) {
+  return String(s ?? "").replace(/\r?\n+/g, " ").replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+}
+function debugSection(debug) {
+  if (!debug || typeof debug !== "object") return "";
+  const request = debug.request ?? {};
+  const browser = debug.browser ?? {};
+  const kernel = browser.browserRuntime ?? browser.kernel ?? {};
+  const network = browser.networkLocation ?? {};
+  const nav = browser.serpNavigation ?? {};
+  const proxyResolution = kernel.proxyResolution ?? {};
+  const locationEvidence = debug.locationEvidence;
+  const candidates = Array.isArray(locationEvidence?.candidates) ? locationEvidence.candidates.slice(0, 4).map((c) => `${c.city}, ${c.regionCode} (${c.count})`).join(", ") : "";
+  const lines = [
+    "\n## Debug",
+    `- Proxy mode: ${request.proxyMode ?? kernel.proxyMode ?? "unknown"} \xB7 requested proxy: ${kernel.requestedProxyIdPresent === true ? `yes (${kernel.requestedProxyIdSuffix ?? "redacted"})` : "no"}`,
+    `- Proxy resolution: ${proxyResolution.source ?? "unknown"}${proxyResolution.target ? ` \xB7 ${proxyResolution.target.level ?? "city"} ${proxyResolution.target.city}, ${proxyResolution.target.state}` : ""}${proxyResolution.error ? ` \xB7 ${truncate(proxyResolution.error, 180)}` : ""}`,
+    `- Browser session: ${kernel.sessionId ?? "unknown"} \xB7 retrieved proxy: ${kernel.retrievedProxyIdPresent === true ? `yes (${kernel.retrievedProxyIdSuffix ?? "redacted"})` : kernel.retrievedProxyIdPresent === false ? "no" : "unknown"}`,
+    `- Browser IP geo: ${[network.ip, network.city, network.region, network.country].filter(Boolean).join(" \xB7 ") || network.error || "unknown"}`,
+    `- Google URL: ${truncate(nav.requestedUrl, 240) || "unknown"}`,
+    `- Final URL: ${truncate(nav.finalUrl, 240) || "unknown"} \xB7 CAPTCHA: ${nav.captchaDetected === true ? "yes" : nav.captchaDetected === false ? "no" : "unknown"} \xB7 redirected: ${nav.redirected === true ? "yes" : nav.redirected === false ? "no" : "unknown"}`
+  ];
+  if (locationEvidence) {
+    lines.push(`- Location evidence: ${locationEvidence.status}${locationEvidence.expected ? ` \xB7 expected ${locationEvidence.expected.city}${locationEvidence.expected.regionCode ? `, ${locationEvidence.expected.regionCode}` : ""}` : ""}${candidates ? ` \xB7 candidates ${candidates}` : ""}`);
+  }
+  return sanitizeVendorText(lines.join("\n"));
+}
+function errorAttemptsSection(body) {
+  const attempts = Array.isArray(body.attempts) ? body.attempts : [];
+  if (attempts.length === 0) return "";
+  const lines = attempts.slice(0, 5).map((attempt) => {
+    const debug = attempt.debug ?? {};
+    const browser = debug.browser ?? {};
+    const kernel = browser.browserRuntime ?? browser.kernel ?? {};
+    const proxyResolution = kernel.proxyResolution ?? {};
+    const network = browser.networkLocation ?? {};
+    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 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"}`;
+  });
+  return `
+
+Attempts:
+${lines.join("\n")}`;
+}
+function formatHarvestPaa(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const flat = d.flat ?? [];
+  const organic = d.organicResults ?? [];
+  const entityIds = d.entityIds;
+  const aiOvw = d.aiOverview;
+  const diagnostics = d.diagnostics;
+  const durationMs = d.stats?.durationMs;
+  const paaRows = flat.map(
+    (r, i) => `| ${i + 1} | ${cell(r.question)} | ${cell(truncate(r.answer, 120))} | ${cell(r.source_title || r.source_site || "")} |`
+  ).join("\n");
+  const paaTable = flat.length ? `## People Also Ask (${flat.length} questions)
+| # | Question | Answer | Source |
+|---|----------|--------|--------|
+${paaRows}` : "## People Also Ask\n*Google did not return a People Also Ask block for this query/location. SERP data was extracted successfully when available.*";
+  const serpRows = organic.map(
+    (r) => `| ${r.position} | ${cell(r.title)} | [${cell(r.domain)}](${r.url}) | ${cell(truncate(r.snippet, 100))} |`
+  ).join("\n");
+  const serpTable = organic.length ? `
+## Organic Results (${organic.length})
+| # | Title | URL | Snippet |
+|---|-------|-----|----------|
+${serpRows}` : "";
+  const aiSection = aiOvw?.detected && aiOvw.text ? `
+## AI Overview
+> ${truncate(aiOvw.text, 600)}` : "";
+  const statsLine = durationMs ? `
+## Stats
+- Status: ${diagnostics?.completionStatus ?? (flat.length ? "paa_found" : "no_paa")} \xB7 Questions: ${flat.length} \xB7 Duration: ${(durationMs / 1e3).toFixed(1)}s` : "";
+  const tips = `
+---
+\u{1F4A1} **Tips**
+- Max questions: \`maxQuestions: 200\` (current: ${input.maxQuestions ?? 30})
+- Organic results only: use \`search_serp\`
+- Dig into a result: use \`extract_url\` on any organic URL`;
+  const full = `# PAA Report: "${input.query}"${input.location ? ` \xB7 ${input.location}` : ""}
+
+${paaTable}${serpTable}${entityIdsSection(entityIds)}${aiSection}${statsLine}${debugSection(diagnostics?.debug)}${tips}`;
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      query: input.query,
+      location: input.location ?? null,
+      questionCount: flat.length,
+      completionStatus: diagnostics?.completionStatus ?? null,
+      questions: flat.map((r) => ({
+        question: String(r.question ?? ""),
+        answer: r.answer ?? null,
+        sourceTitle: r.source_title ?? null,
+        sourceSite: r.source_site ?? null
+      })),
+      organicResults: organic.map((r) => ({
+        position: Number(r.position) || 0,
+        title: String(r.title ?? ""),
+        url: String(r.url ?? ""),
+        domain: String(r.domain ?? ""),
+        snippet: r.snippet ?? null
+      })),
+      aiOverview: aiOvw ? { detected: aiOvw.detected === true, text: aiOvw.text ?? null } : null,
+      entityIds: entityIds ? { kgIds: entityIds.kgIds ?? [], cids: entityIds.cids ?? [], gcids: entityIds.gcids ?? [] } : null,
+      durationMs: durationMs ?? null
+    }
+  };
+}
+function formatSearchSerp(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const organic = d.organicResults ?? [];
+  const localPack = d.localPack ?? [];
+  const entityIds = d.entityIds;
+  const aiOvw = d.aiOverview;
+  const diagnostics = d.diagnostics;
+  const serpRows = organic.map(
+    (r) => `| ${r.position} | ${cell(r.title)} | [${cell(r.domain)}](${r.url}) | ${cell(truncate(r.snippet, 100))} |`
+  ).join("\n");
+  const serpTable = organic.length ? `## Organic Results (${organic.length})
+| # | Title | URL | Snippet |
+|---|-------|-----|----------|
+${serpRows}` : "## Organic Results\n*None found*";
+  const localRows = localPack.map(
+    (b) => `| ${b.position} | ${cell(b.name)} | ${b.rating ?? "\u2014"} (${b.reviewCount ?? "0"}) | ${b.websiteUrl ? `[link](${b.websiteUrl})` : "\u2014"} |`
+  ).join("\n");
+  const localSection = localPack.length ? `
+## Local Pack (${localPack.length})
+| # | Name | Rating | Website |
+|---|------|--------|---------|
+${localRows}` : "";
+  const aiSection = aiOvw?.detected && aiOvw.text ? `
+## AI Overview
+> ${truncate(aiOvw.text, 600)}` : "";
+  const tips = `
+---
+\u{1F4A1} **Tips**
+- Get PAA questions: use \`harvest_paa\` for this query
+- Scrape any result: use \`extract_url\`
+- Business entity IDs (CID/GCID/KG MID) shown above if found`;
+  const full = `# SERP Report: "${input.query}"${input.location ? ` \xB7 ${input.location}` : ""}
+
+${serpTable}${localSection}${entityIdsSection(entityIds)}${aiSection}${debugSection(diagnostics?.debug)}${tips}`;
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      query: input.query,
+      location: input.location ?? null,
+      organicResults: organic.map((r) => ({
+        position: Number(r.position) || 0,
+        title: String(r.title ?? ""),
+        url: String(r.url ?? ""),
+        domain: String(r.domain ?? ""),
+        snippet: r.snippet ?? null
+      })),
+      localPack: localPack.map((b) => ({
+        position: Number(b.position) || 0,
+        name: String(b.name ?? ""),
+        rating: b.rating ?? null,
+        reviewCount: b.reviewCount ?? null,
+        websiteUrl: b.websiteUrl ?? null
+      })),
+      aiOverview: aiOvw ? { detected: aiOvw.detected === true, text: aiOvw.text ?? null } : null,
+      entityIds: entityIds ? { kgIds: entityIds.kgIds ?? [], cids: entityIds.cids ?? [], gcids: entityIds.gcids ?? [] } : null
+    }
+  };
+}
+function formatExtractUrl(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const url = d.url ?? input.url;
+  const title = d.title ?? "Untitled";
+  const headings = d.headings ?? [];
+  const kpo = d.kpo;
+  const bodyMd = d.bodyMarkdown ?? "";
+  const schema = d.schema;
+  const screenshotMeta = d.screenshot;
+  const screenshotPath = screenshotMeta?.base64 ? persistScreenshotLocally(screenshotMeta.base64, url) : null;
+  const branding = d.branding;
+  const media = d.media;
+  const h1Lines = headings.filter((h) => h.level === 1).map((h) => `- ${h.text}`).join("\n");
+  const h2Lines = headings.filter((h) => h.level === 2).map((h) => `  - ${h.text}`).join("\n");
+  const headingSection = h1Lines || h2Lines ? `
+## Heading Structure
+${[h1Lines, h2Lines].filter(Boolean).join("\n")}` : "";
+  const kpoSection = kpo ? [
+    `
+## Entity / Schema`,
+    kpo.entityName ? `- **Entity:** ${kpo.entityName}` : "",
+    kpo.type?.length ? `- **@type:** ${kpo.type.join(", ")}` : "",
+    kpo.napScore !== void 0 ? `- **NAP Score:** ${kpo.napScore}/5` : "",
+    kpo.address ? `- **Address:** ${kpo.address}` : "",
+    kpo.phone ? `- **Phone:** ${kpo.phone}` : "",
+    kpo.email ? `- **Email:** ${kpo.email}` : "",
+    kpo.faqCount ? `- **FAQ items:** ${kpo.faqCount}` : "",
+    kpo.sameAs?.length ? `- **sameAs:** ${kpo.sameAs.slice(0, 5).join(", ")}` : "",
+    kpo.missingFields?.length ? `
+**Missing schema fields:** ${kpo.missingFields.slice(0, 5).join(", ")}` : ""
+  ].filter(Boolean).join("\n") : "";
+  const bodySection = bodyMd ? `
+## Page Content
+${bodyMd.slice(0, 3e3)}${bodyMd.length > 3e3 ? "\n\n*(truncated)*" : ""}` : "";
+  const screenshotSection = screenshotMeta ? `
+## Screenshot
+- **File:** ${screenshotPath ?? "(returned inline only \u2014 disk write unavailable in this environment)"}
+- **Size:** ${(screenshotMeta.sizeBytes / 1024).toFixed(1)} KB
+- **Device:** ${screenshotMeta.device}` : "";
+  const brandingSection = branding ? [
+    `
+## Branding`,
+    branding.colorScheme ? `- **Color scheme:** ${branding.colorScheme}` : "",
+    `- **Colors:**${Object.entries(branding.colors ?? {}).filter(([, v]) => v).map(([k, v]) => ` ${k}=${v}`).join(",") || " (none extracted)"}`,
+    `- **Fonts:**${Object.entries(branding.fonts ?? {}).filter(([, v]) => v).map(([k, v]) => ` ${k}=${v}`).join(",") || " (none extracted)"}`,
+    branding.assets?.logo ? `- **Logo:** ${branding.assets.logo}` : "",
+    branding.assets?.favicon ? `- **Favicon:** ${branding.assets.favicon}` : ""
+  ].filter(Boolean).join("\n") : "";
+  const mediaSection = media ? [
+    `
+## Media Assets`,
+    `- **Found:** ${media.totalFound} total, ${media.filteredCount} filtered (ads/noise), ${media.assets.length} downloaded`,
+    media.outputDir ? `- **Saved to:** ${media.outputDir}` : ""
+  ].filter(Boolean).join("\n") : "";
+  const schemaCount = Array.isArray(schema) ? schema.length : 0;
+  const tips = `
+---
+\u{1F4A1} **Tips**
+- Crawl entire site: use \`extract_site\`
+- Map all URLs: use \`map_site_urls\`
+- ${schemaCount} JSON-LD schema block(s) detected`;
+  const full = `# URL Extract: ${url}
+**${title}**
+${headingSection}${kpoSection}${brandingSection}${bodySection}${screenshotSection}${mediaSection}${tips}`;
+  const textResult2 = oneBlock(full);
+  const structuredContent = {
+    url,
+    title: d.title ?? null,
+    headings: headings.map((h) => ({ level: Number(h.level) || 0, text: String(h.text ?? "") })),
+    schemaBlockCount: schemaCount,
+    entityName: kpo?.entityName ?? null,
+    entityTypes: kpo?.type ?? [],
+    napScore: kpo?.napScore ?? null,
+    missingSchemaFields: kpo?.missingFields ?? [],
+    screenshotSaved: screenshotPath ?? null
+  };
+  if (screenshotMeta?.base64) {
+    return {
+      content: [
+        ...textResult2.content,
+        { type: "image", data: screenshotMeta.base64, mimeType: "image/png" }
+      ],
+      structuredContent
+    };
+  }
+  return { ...textResult2, structuredContent };
+}
+function formatMapSiteUrls(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const urls = d.urls ?? [];
+  const ok = urls.filter((u) => (u.status ?? 0) >= 200 && (u.status ?? 0) < 300);
+  const broken = urls.filter((u) => u.status !== null && u.status >= 400);
+  const redirects = urls.filter((u) => u.status !== null && u.status >= 300 && u.status < 400);
+  const urlRows = urls.slice(0, 200).map((u, i) => `| ${i + 1} | ${u.url} | ${u.status ?? "\u2014"} |`).join("\n");
+  const full = [
+    `# URL Map: ${input.url}`,
+    `**${d.totalFound} URLs** \xB7 ${(d.durationMs / 1e3).toFixed(1)}s${d.truncated ? " \xB7 *truncated*" : ""}`,
+    `
+## Summary
+- \u2705 2xx: ${ok.length}
+- \u{1F500} 3xx: ${redirects.length}
+- \u274C 4xx+: ${broken.length}`,
+    `
+## URL Inventory
+| # | URL | Status |
+|---|-----|--------|
+${urlRows}`,
+    broken.length ? `
+## Broken URLs
+${broken.map((u) => `- ${u.url} (${u.status})`).join("\n")}` : "",
+    `
+---
+\u{1F4A1} **Tips**
+- Extract content from all pages: use \`extract_site\`
+- Scrape a single page: use \`extract_url\``
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      startUrl: d.startUrl ?? input.url,
+      totalFound: d.totalFound ?? urls.length,
+      truncated: d.truncated === true,
+      okCount: ok.length,
+      redirectCount: redirects.length,
+      brokenCount: broken.length,
+      urls: urls.map((u) => ({ url: u.url, status: u.status ?? null })),
+      durationMs: d.durationMs ?? 0
+    }
+  };
+}
+function formatExtractSite(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const pages = d.pages ?? [];
+  const pageRows = pages.map((p, i) => {
+    const schemaInfo = p.kpo?.type?.join(", ") ?? (Array.isArray(p.schema) && p.schema.length ? `${p.schema.length} block(s)` : "\u2014");
+    return `| ${i + 1} | ${cell(p.title ?? "Untitled")} | ${p.url} | ${schemaInfo} |`;
+  }).join("\n");
+  const full = [
+    `# Site Extract: ${input.url}`,
+    `**${pages.length} pages** \xB7 ${((d.durationMs ?? 0) / 1e3).toFixed(1)}s`,
+    `
+## Pages
+| # | Title | URL | Schema |
+|---|-------|-----|--------|
+${pageRows}`,
+    `
+---
+\u{1F4A1} **Tips**
+- Map URLs first: use \`map_site_urls\`
+- Inspect a single page: use \`extract_url\``
+  ].join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      url: input.url,
+      pageCount: pages.length,
+      pages: pages.map((p) => ({
+        url: String(p.url ?? ""),
+        title: p.title ?? null,
+        schemaTypes: p.kpo?.type ?? []
+      })),
+      durationMs: d.durationMs ?? 0
+    }
+  };
+}
+function formatYoutubeHarvest(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const videos = d.videos ?? [];
+  const label = input.mode === "channel" ? input.channelHandle ?? "channel" : `"${input.query ?? ""}"`;
+  const videoRows = videos.map(
+    (v, i) => `| ${i + 1} | ${cell(truncate(v.title, 70))} | ${cell(v.channelName)} | ${v.views ?? "\u2014"} | ${v.duration ?? "\u2014"} | \`${v.videoId}\` |`
+  ).join("\n");
+  const channelSection = d.channelMeta ? `
+## Channel
+- **Name:** ${d.channelMeta.title ?? "\u2014"}
+- **Subscribers:** ${d.channelMeta.subscriberCount ?? "\u2014"}` : "";
+  const full = [
+    `# YouTube Harvest: ${label}`,
+    `**${videos.length} videos** \xB7 ${(d.stats.durationMs / 1e3).toFixed(1)}s`,
+    channelSection,
+    `
+## Videos
+| # | Title | Channel | Views | Duration | Video ID |
+|---|-------|---------|-------|----------|----------|
+${videoRows}`,
+    `
+---
+\u{1F4A1} **Tips**
+- Transcribe a video: use \`youtube_transcribe\` with the \`videoId\` above
+- Switch mode: \`mode: "channel"\` with \`channelHandle\` or \`mode: "search"\` with \`query\``
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      mode: input.mode,
+      videoCount: videos.length,
+      channel: d.channelMeta ? { title: d.channelMeta.title ?? null, subscriberCount: d.channelMeta.subscriberCount ?? null } : null,
+      videos: videos.map((v) => ({
+        videoId: String(v.videoId ?? ""),
+        title: String(v.title ?? ""),
+        channelName: v.channelName ?? null,
+        views: v.views ?? null,
+        duration: v.duration ?? null,
+        url: v.url ?? null
+      }))
+    }
+  };
+}
+function formatYoutubeTranscribe(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const text = d.text ?? "";
+  const chunks = d.chunks ?? [];
+  const durSec = d.durationMs ? (d.durationMs / 1e3).toFixed(0) : "\u2014";
+  const chunkRows = chunks.slice(0, 50).map((c) => {
+    const sec = Number.isFinite(c.timestamp[0]) ? Math.floor(c.timestamp[0]) : 0;
+    const mm = String(Math.floor(sec / 60)).padStart(2, "0");
+    const ss = String(sec % 60).padStart(2, "0");
+    return `| ${mm}:${ss} | ${cell(truncate(c.text, 120))} |`;
+  }).join("\n");
+  const full = [
+    `# YouTube Transcript: \`${input.videoId}\``,
+    `**Duration:** ${durSec}s \xB7 **${text.split(" ").length} words**`,
+    `
+## Full Transcript
+${text}`,
+    chunks.length ? `
+## Timestamped Chunks
+| Time | Text |
+|------|------|
+${chunkRows}` : "",
+    `
+---
+\u{1F4A1} Harvest more from this channel: use \`youtube_harvest\` with \`mode: "channel"\``
+  ].filter(Boolean).join("\n");
+  return oneBlock(full);
+}
+function formatFacebookPageIntel(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const advertiser = d.advertiserName ?? input.query ?? input.pageId ?? input.libraryId ?? "Advertiser";
+  const ads = d.ads ?? [];
+  const s = d.summary ?? { totalAds: 0, activeCount: 0, videoCount: 0, imageCount: 0 };
+  const adBlocks = ads.map((ad, i) => [
+    `### Ad ${i + 1}${ad.libraryId ? ` \xB7 \`${ad.libraryId}\`` : ""} \u2014 ${ad.status ?? "\u2014"} \xB7 ${ad.creativeType ?? "\u2014"} \xB7 ${ad.startDate ?? "\u2014"}`,
+    ad.headline ? `**Headline:** ${ad.headline}` : "",
+    ad.primaryText ? `**Copy:** ${truncate(ad.primaryText, 200)}` : "",
+    ad.cta ? `**CTA:** ${ad.cta}` : "",
+    ad.videoUrl ? `**Video URL:** \`${ad.videoUrl}\`` : "",
+    ad.variations ? `**Variations:** ${ad.variations}` : ""
+  ].filter(Boolean).join("\n")).join("\n\n---\n\n");
+  const full = [
+    `# Facebook Ad Intel: ${advertiser}`,
+    `**${s.totalAds} ads** \xB7 ${s.activeCount} active \xB7 ${s.videoCount} video \xB7 ${s.imageCount} image`,
+    `
+${adBlocks}`,
+    `
+---
+\u{1F4A1} **Tips**
+- Transcribe video ads: use \`facebook_ad_transcribe\` with the \`videoUrl\` above
+- Find other advertisers: use \`facebook_ad_search\``
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      advertiserName: d.advertiserName ?? null,
+      totalAds: s.totalAds ?? 0,
+      activeCount: s.activeCount ?? 0,
+      videoCount: s.videoCount ?? 0,
+      imageCount: s.imageCount ?? 0,
+      ads: ads.map((ad) => ({
+        libraryId: ad.libraryId ?? null,
+        status: ad.status ?? null,
+        creativeType: ad.creativeType ?? null,
+        headline: ad.headline ?? null,
+        cta: ad.cta ?? null,
+        startDate: ad.startDate ?? null,
+        videoUrl: ad.videoUrl ?? null,
+        variations: typeof ad.variations === "number" ? ad.variations : null
+      }))
+    }
+  };
+}
+function formatFacebookAdSearch(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const advertisers = d.results ?? d.advertisers ?? [];
+  const rows = advertisers.map(
+    (a, i) => `| ${i + 1} | ${cell(a.pageName ?? a.name)} | ${a.adCount ?? "\u2014"} | \`${a.sampleLibraryId ?? a.libraryId ?? "\u2014"}\` |`
+  ).join("\n");
+  const full = [
+    `# Facebook Ad Library Search: "${input.query}"`,
+    `**${advertisers.length} advertisers found**`,
+    `
+## Advertisers
+| # | Name | Ad Count | Library ID |
+|---|------|----------|------------|
+${rows}`,
+    `
+---
+\u{1F4A1} **Tips**
+- Scan all ads: use \`facebook_page_intel\` with \`libraryId\`
+- Or pass the advertiser name as \`query\` in \`facebook_page_intel\``
+  ].join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      query: input.query,
+      advertiserCount: advertisers.length,
+      advertisers: advertisers.map((a) => ({
+        name: a.pageName ?? a.name ?? null,
+        adCount: typeof a.adCount === "number" ? a.adCount : null,
+        libraryId: a.sampleLibraryId ?? a.libraryId ?? null
+      }))
+    }
+  };
+}
+function formatCreditsInfo(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const balance = d.balance_credits;
+  const costs = d.costs ?? [];
+  const matched = d.matched_cost;
+  const ledger = d.ledger ?? [];
+  const costRows = costs.map((c) => {
+    const notes = c.notes ? ` ${c.notes}` : "";
+    return `| ${c.label} | ${c.credits} | ${c.unit}${notes} |`;
+  }).join("\n");
+  const ledgerRows = ledger.map((row) => {
+    const credits = row.amount_mc / 1e3;
+    return `| ${row.created_at} | ${row.operation} | ${credits} | ${row.description ?? ""} |`;
+  }).join("\n");
+  const matchedSection = matched ? `
+## Matched Cost
+**${matched.label}:** ${matched.credits} credits ${matched.unit}${matched.notes ? `
+
+${matched.notes}` : ""}` : input.item ? `
+## Matched Cost
+No exact cost match found for "${input.item}". See the full cost table below.` : "";
+  const full = [
+    `# Credits`,
+    `**Balance:** ${balance ?? "unknown"} credits`,
+    matchedSection,
+    costs.length ? `
+## Cost Table
+| Item | Credits | Unit |
+|------|---------|------|
+${costRows}` : "",
+    ledger.length ? `
+## Recent Ledger
+| Date | Operation | Credits | Description |
+|------|-----------|---------|-------------|
+${ledgerRows}` : ""
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      balanceCredits: typeof balance === "number" ? balance : null,
+      matchedCost: matched ? { label: matched.label, credits: matched.credits, unit: matched.unit, notes: matched.notes ?? null } : null,
+      costs: costs.map((c) => ({
+        key: c.key,
+        label: c.label,
+        credits: c.credits,
+        unit: c.unit,
+        notes: c.notes ?? null
+      })),
+      ledger: ledger.map((row) => ({
+        createdAt: String(row.created_at ?? ""),
+        operation: String(row.operation ?? ""),
+        credits: row.amount_mc / 1e3,
+        description: row.description ?? null
+      }))
+    }
+  };
+}
+function formatMapsSearch(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const results = d.results ?? [];
+  const normalizedResults = results.map((result) => ({
+    ...result,
+    phone: result.phone ?? null,
+    hoursStatus: result.hoursStatus ?? null
+  }));
+  const searchQuery = d.searchQuery ?? [input.query, input.location].filter(Boolean).join(" ");
+  const requestedMax = d.requestedMaxResults ?? input.maxResults ?? 10;
+  const durationMs = d.durationMs;
+  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}) |`;
+  }).join("\n");
+  const metadataSection = results.length ? `
+## Candidate Metadata
+${results.map((r) => {
+    const meta = r.metadata?.length ? r.metadata.slice(0, 8).map((m) => `  - ${m}`).join("\n") : "  - none";
+    return `### ${r.position}. ${r.name}
+${meta}`;
+  }).join("\n\n")}` : "";
+  const full = [
+    `# Google Maps Search: "${searchQuery}"`,
+    `**Returned:** ${results.length} profile candidate${results.length === 1 ? "" : "s"} \xB7 **Requested max:** ${requestedMax} \xB7 **Limit:** 50`,
+    `
+## Results
+| # | Name | Category | Rating | Address | CID | Website | Maps |
+|---|------|----------|--------|---------|-----|---------|------|
+${rows}`,
+    metadataSection,
+    `
+---
+\u{1F4A1} **Next step:** use \`maps_place_intel\` with a selected business name and location to hydrate full hours, phone, review topics, and optional review cards.`,
+    durationMs != null ? `
+*Extracted in ${(durationMs / 1e3).toFixed(1)}s*` : null
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      query: d.query,
+      location: d.location ?? null,
+      searchQuery: d.searchQuery,
+      searchUrl: d.searchUrl,
+      extractedAt: d.extractedAt,
+      requestedMaxResults: requestedMax,
+      resultCount: results.length,
+      results: normalizedResults,
+      durationMs: durationMs ?? 0
+    }
+  };
+}
+function formatDirectoryWorkflow(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const cities = (d.cities ?? []).map((city) => ({
+    ...city,
+    results: city.results.map((result) => ({
+      ...result,
+      phone: result.phone ?? null,
+      hoursStatus: result.hoursStatus ?? null
+    }))
+  }));
+  const warnings = d.warnings ?? [];
+  const csvPath = d.csvPath ?? null;
+  const totalResultCount = d.totalResultCount ?? cities.reduce((sum, city) => sum + city.resultCount, 0);
+  const durationMs = d.durationMs;
+  const marketRows = cities.map((city) => {
+    const zips = city.zips?.length ? city.zips.slice(0, 8).join(" ") + (city.zips.length > 8 ? ` +${city.zips.length - 8}` : "") : "\u2014";
+    return `| ${cell(city.city)} | ${city.population.toLocaleString()} | ${city.zips?.length ?? 0} | ${city.resultCount} | ${city.status} | ${cell(zips)} |`;
+  }).join("\n");
+  const businessRows = cities.flatMap((city) => city.results.slice(0, 3).map((result) => ({ city, result }))).map(({ city, result }) => {
+    const rating = [result.rating, result.reviewCount ? `(${result.reviewCount})` : null].filter(Boolean).join(" ");
+    return `| ${cell(city.city)} | ${result.position} | ${cell(result.name)} | ${cell(result.category)} | ${cell(rating)} | ${result.websiteUrl ? `[site](${result.websiteUrl})` : "\u2014"} | [maps](${result.placeUrl}) |`;
+  }).join("\n");
+  const warningText = warnings.length ? `
+## Warnings
+${warnings.map((w) => `- ${w}`).join("\n")}` : "";
+  const csvText = csvPath ? `
+**CSV:** \`${csvPath}\`` : "";
+  const full = [
+    `# Directory Workflow: ${input.query}`,
+    `**Markets:** ${cities.length} \xB7 **Maps results:** ${totalResultCount} \xB7 **State:** ${d.state ?? input.state ?? "US"} \xB7 **Population threshold:** ${d.minPopulation ?? input.minPopulation ?? 1e5}`,
+    csvText,
+    `
+## Markets
+| City | Population | ZIPs | Maps Results | Status | ZIP Sample |
+|---|---:|---:|---:|---|---|
+${marketRows}`,
+    businessRows ? `
+## Top Candidates By City
+| City | # | Name | Category | Rating | Website | Maps |
+|---|---:|---|---|---|---|---|
+${businessRows}` : null,
+    warningText,
+    `
+## Sources
+- Population: ${d.censusSourceUrl ?? "Census Population Estimates Program"}
+- ZIP groups: ${d.usZipsSourcePath ?? "not configured"}`,
+    durationMs != null ? `
+*Completed in ${(durationMs / 1e3).toFixed(1)}s*` : null
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      query: d.query,
+      state: d.state,
+      minPopulation: d.minPopulation,
+      populationYear: d.populationYear,
+      maxResultsPerCity: d.maxResultsPerCity,
+      concurrency: d.concurrency,
+      censusSourceUrl: d.censusSourceUrl,
+      usZipsSourcePath: d.usZipsSourcePath ?? null,
+      warnings,
+      extractedAt: d.extractedAt,
+      selectedCityCount: d.selectedCityCount,
+      totalResultCount,
+      csvPath,
+      cities,
+      durationMs: durationMs ?? 0
+    }
+  };
+}
+function formatMapsPlaceIntel(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const name = d.name ?? input.businessName;
+  const rating = d.rating;
+  const reviewCount = d.reviewCount;
+  const category = d.category;
+  const address = d.address;
+  const phone = d.phoneDisplay;
+  const website = d.website;
+  const hoursSummary = d.hoursSummary;
+  const plusCode = d.plusCode;
+  const bookingUrl = d.bookingUrl;
+  const kgmid = d.kgmid;
+  const cidDecimal = d.cidDecimal;
+  const cidUrl = d.cidUrl;
+  const lat = d.lat;
+  const lng = d.lng;
+  const durationMs = d.durationMs;
+  const histogram = d.reviewHistogram ?? [];
+  const topics = d.reviewTopics ?? [];
+  const about = d.aboutAttributes ?? [];
+  const reviews = d.reviews ?? [];
+  const reviewsStatus = d.reviewsStatus ?? "not_requested";
+  const hoursTable = d.hoursTable ?? [];
+  const ratingLine = [rating, reviewCount ? `(${reviewCount} reviews)` : null].filter(Boolean).join(" ");
+  const basicLines = [
+    address ? `- **Address:** ${address}` : null,
+    phone ? `- **Phone:** ${phone}` : null,
+    website ? `- **Website:** ${website}` : null,
+    hoursSummary ? `- **Hours:** ${hoursSummary}` : null,
+    plusCode ? `- **Plus Code:** ${plusCode}` : null,
+    bookingUrl ? `- **Book:** ${bookingUrl}` : null
+  ].filter(Boolean).join("\n");
+  const hoursSection = hoursTable.length ? `
+## Hours
+| Day | Hours |
+|-----|-------|
+${hoursTable.map((r) => `| ${r.day} | ${r.hours} |`).join("\n")}` : "";
+  const histSection = histogram.length ? `
+## Rating Distribution
+| Stars | Count |
+|-------|-------|
+${histogram.map((r) => `| ${"\u2605".repeat(r.stars)}${"\u2606".repeat(5 - r.stars)} | ${r.count} |`).join("\n")}` : "";
+  const topicsSection = topics.length ? `
+## Review Topics
+${topics.map((t) => `- **${t.label}:** ${t.count} mentions`).join("\n")}` : "";
+  const aboutBySection = {};
+  for (const a of about) {
+    if (!aboutBySection[a.section]) aboutBySection[a.section] = [];
+    aboutBySection[a.section].push(a.attribute);
+  }
+  const aboutSection = Object.keys(aboutBySection).length ? `
+## About
+${Object.entries(aboutBySection).map(([s, attrs]) => `**${s}**
+${attrs.map((a) => `- ${a}`).join("\n")}`).join("\n\n")}` : "";
+  const entitySection = [
+    kgmid ? `- **KGMID:** \`${kgmid}\`` : null,
+    cidDecimal ? `- **CID:** \`${cidDecimal}\`` : null,
+    cidUrl ? `- **Maps CID URL:** ${cidUrl}` : null,
+    lat != null && lng != null ? `- **Coordinates:** ${lat}, ${lng}` : null
+  ].filter(Boolean).join("\n");
+  const reviewsSection = (() => {
+    if (reviewsStatus === "not_requested") return "";
+    if (reviewsStatus === "unavailable") return "\n## Reviews\n> Reviews could not be retrieved this run \u2014 retry with `includeReviews: true`.";
+    if (reviewsStatus === "none_exist") return "\n## Reviews\n*This business has no reviews on Google Maps.*";
+    if (reviews.length === 0) return "\n## Reviews\n*0 reviews collected.*";
+    return `
+## Reviews (${reviews.length})
+${reviews.map((r, i) => {
+      const starsN = parseInt(r.stars ?? "0");
+      const stars = "\u2605".repeat(starsN) + "\u2606".repeat(5 - starsN);
+      return `### ${i + 1}. ${r.author ?? "Anonymous"} \u2014 ${stars}
+*${r.date ?? ""}*
+
+${r.text ?? ""}`;
+    }).join("\n\n")}`;
+  })();
+  const full = [
+    `# ${name}`,
+    category ? `*${category}*` : null,
+    ratingLine ? `
+**Rating:** ${ratingLine}` : null,
+    basicLines ? `
+${basicLines}` : null,
+    hoursSection,
+    histSection,
+    topicsSection,
+    aboutSection,
+    entitySection ? `
+## Entity IDs
+${entitySection}` : null,
+    reviewsSection,
+    durationMs != null ? `
+---
+*Extracted in ${(durationMs / 1e3).toFixed(1)}s*` : null
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      name,
+      rating: rating ?? null,
+      reviewCount: reviewCount ?? null,
+      category: category ?? null,
+      address: address ?? null,
+      phone: phone ?? null,
+      website: website ?? null,
+      hoursSummary: hoursSummary ?? null,
+      bookingUrl: bookingUrl ?? null,
+      kgmid: kgmid ?? null,
+      cidDecimal: cidDecimal ?? null,
+      cidUrl: cidUrl ?? null,
+      lat: lat ?? null,
+      lng: lng ?? null,
+      reviewsStatus,
+      reviewsCollected: reviews.length,
+      reviewTopics: topics.map((t) => ({ label: String(t.label ?? ""), count: String(t.count ?? "") }))
+    }
+  };
+}
+function formatFacebookAdTranscribe(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const text = d.text ?? "";
+  const chunks = d.chunks ?? [];
+  const durSec = d.durationMs ? (d.durationMs / 1e3).toFixed(0) : "\u2014";
+  const chunkRows = chunks.slice(0, 50).map((c) => {
+    const sec = Number.isFinite(c.timestamp[0]) ? Math.floor(c.timestamp[0]) : 0;
+    const mm = String(Math.floor(sec / 60)).padStart(2, "0");
+    const ss = String(sec % 60).padStart(2, "0");
+    return `| ${mm}:${ss} | ${cell(truncate(c.text, 120))} |`;
+  }).join("\n");
+  const full = [
+    `# Facebook Ad Transcript`,
+    `**Duration:** ${durSec}s \xB7 **${text.split(" ").length} words**`,
+    `
+## Full Transcript
+${text}`,
+    chunks.length ? `
+## Timestamped Chunks
+| Time | Text |
+|------|------|
+${chunkRows}` : "",
+    `
+---
+\u{1F4A1} Get more ads from this advertiser: use \`facebook_page_intel\``
+  ].filter(Boolean).join("\n");
+  return oneBlock(full);
+}
+
+// src/mcp/mcp-tool-schemas.ts
+var import_zod2 = require("zod");
+var HarvestPaaInputSchema = {
+  query: import_zod2.z.string().min(1).describe('Core search topic only. If the user says "best hvac company in Denver CO", use query="best hvac company" and location="Denver, CO". Do not include the location in query when it can be separated.'),
+  location: import_zod2.z.string().optional().describe('City, region, or country for geo-targeted results, inferred from the user request when present, e.g. "Denver, CO", "Tokyo, Japan", "London, UK".'),
+  maxQuestions: import_zod2.z.number().int().min(1).max(200).default(30).describe("Number of PAA questions to extract. Default 30. Maximum 200. Use 10 for quick probes, 30 for normal research, 100-200 when the user asks for everything/full/deep research. Larger harvests get a longer server time budget (151-200 questions \u2192 up to 280s). Credits are charged by extracted question; unused request hold is refunded."),
+  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."),
+  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.")
+};
+var ExtractUrlInputSchema = {
+  url: import_zod2.z.string().url().describe("Public http/https URL to extract. Use this when the user provides one specific page URL."),
+  screenshot: import_zod2.z.boolean().default(false).describe("Also capture a full-page screenshot of the URL. Saved to ~/Downloads/mcp-scraper/screenshots/ and returned inline. Use when the user asks to see or capture the page visually."),
+  screenshotDevice: import_zod2.z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport for screenshot. desktop = 1440\xD7900. mobile = 390\xD7844. Default desktop."),
+  extractBranding: import_zod2.z.boolean().default(false).describe("Extract brand colors, fonts, logo, and favicon using a rendered browser session. Returns colorScheme (light/dark), colors (primary/accent/background/text/heading as hex), fonts (heading/body family names), and assets (logo URL, favicon URL). Use when the user asks about brand colors, site theme, or brand assets."),
+  downloadMedia: import_zod2.z.boolean().default(false).describe("Extract and download all page media (images, video, audio) to ~/Downloads/mcp-scraper/media/. Ad networks, tracking pixels, and noise URLs are filtered automatically. Use when the user asks to download or harvest assets from a page."),
+  mediaTypes: import_zod2.z.array(import_zod2.z.enum(["image", "video", "audio"])).default(["image", "video", "audio"]).describe("Which media types to download. Default all three."),
+  allowLocal: import_zod2.z.boolean().default(false).describe("Allow localhost and private-network URLs. For local development only.")
+};
+var MapSiteUrlsInputSchema = {
+  url: import_zod2.z.string().url().describe("Public website URL or domain to crawl for internal URLs. Use before extract_site when the user asks to audit/map/crawl a site."),
+  maxUrls: import_zod2.z.number().int().min(1).max(500).optional().describe("Maximum URLs to discover. Use 100 for normal maps, higher when the user asks for a full inventory.")
+};
+var ExtractSiteInputSchema = {
+  url: import_zod2.z.string().url().describe("Public website URL or domain to extract across multiple pages. Use when the user asks for a site audit, website crawl, or full-site content/schema extraction."),
+  maxPages: import_zod2.z.number().int().min(1).max(50).optional().describe("Maximum pages to extract. Use 50 when the user asks for full results or a complete crawl within MCP limits.")
+};
+var YoutubeHarvestInputSchema = {
+  mode: import_zod2.z.enum(["search", "channel"]).describe("Use search for topic/keyword requests. Use channel when the user provides @handle, channel ID, or channel URL."),
+  query: import_zod2.z.string().optional().describe("Required when mode is search. The YouTube search topic in the user\u2019s words."),
+  channelHandle: import_zod2.z.string().optional().describe("YouTube channel handle, channel ID, or URL. Examples: @mkbhd, UC..., https://youtube.com/@mkbhd."),
+  maxVideos: import_zod2.z.number().int().min(1).max(500).default(50).describe("Number of videos to return. Default 50. Increase when user asks for full channel/history.")
+};
+var YoutubeTranscribeInputSchema = {
+  videoId: import_zod2.z.string().min(1).describe("YouTube video ID, e.g. dQw4w9WgXcQ")
+};
+var FacebookPageIntelInputSchema = {
+  pageId: import_zod2.z.string().optional(),
+  libraryId: import_zod2.z.string().optional(),
+  query: import_zod2.z.string().optional().describe("Advertiser or brand name when pageId/libraryId is not known. One of pageId, libraryId, or query is required."),
+  maxAds: import_zod2.z.number().int().min(1).max(200).default(50),
+  country: import_zod2.z.string().length(2).default("US")
+};
+var FacebookAdSearchInputSchema = {
+  query: import_zod2.z.string().min(1).describe("Advertiser, brand, competitor, niche, or keyword to search in Facebook Ad Library."),
+  country: import_zod2.z.string().length(2).default("US"),
+  maxResults: import_zod2.z.number().int().min(1).max(20).default(10)
+};
+var FacebookAdTranscribeInputSchema = {
+  videoUrl: import_zod2.z.string().url().describe("Facebook CDN video URL from a facebook_page_intel result")
+};
+var MapsPlaceIntelInputSchema = {
+  businessName: import_zod2.z.string().min(1).describe('Business name only. If user says "Elite Roofing Denver CO", use businessName="Elite Roofing" and location="Denver, CO".'),
+  location: import_zod2.z.string().min(1).describe('City/region/country where the business should be searched, e.g. "Denver, CO". Infer from the user request when possible.'),
+  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."),
+  includeReviews: import_zod2.z.boolean().default(false).describe("Whether to fetch individual review cards"),
+  maxReviews: import_zod2.z.number().int().min(1).max(500).default(50).describe("Max review cards to return (requires includeReviews: true)")
+};
+var MapsSearchInputSchema = {
+  query: import_zod2.z.string().min(1).describe('Business category, niche, keyword, or search term. If the user says "roofers in Denver CO", use query="roofers" and location="Denver, CO". Do not put the location here when it can be separated.'),
+  location: import_zod2.z.string().optional().describe('City, region, country, or service area for the Maps search, e.g. "Denver, CO". Infer from the user request when present.'),
+  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."),
+  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.")
+};
+var DirectoryWorkflowInputSchema = {
+  query: import_zod2.z.string().min(1).describe("Business category, niche, or keyword to search on Google Maps for every selected market, e.g. roofers, dentists, med spas. Do not include the city here."),
+  state: import_zod2.z.string().min(2).default("TN").describe("US state abbreviation or state name used to select Census places, e.g. TN or Tennessee."),
+  minPopulation: import_zod2.z.number().int().min(0).default(1e5).describe('Minimum Census place population for market selection. Use 100000 for "cities above 100k population".'),
+  populationYear: import_zod2.z.number().int().min(2020).max(2025).default(2025).describe("Census population estimate year from the 2020-2025 Population Estimates Program city/place dataset."),
+  maxCities: import_zod2.z.number().int().min(1).max(100).default(25).describe("Maximum number of markets to process after sorting by population descending."),
+  maxResultsPerCity: import_zod2.z.number().int().min(1).max(50).default(50).describe("Google Maps business/profile candidates to collect for each city. Maximum 50."),
+  concurrency: import_zod2.z.number().int().min(1).max(5).default(5).describe("How many city Maps searches to run in parallel. Use 5 for broad directory batches unless debugging."),
+  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."),
+  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 NullableString = import_zod2.z.string().nullable();
+var MapsSearchOutputSchema = {
+  query: import_zod2.z.string(),
+  location: import_zod2.z.string().nullable(),
+  searchQuery: import_zod2.z.string(),
+  searchUrl: import_zod2.z.string().url(),
+  extractedAt: import_zod2.z.string(),
+  requestedMaxResults: import_zod2.z.number().int().min(1).max(50),
+  resultCount: import_zod2.z.number().int().min(0).max(50),
+  results: import_zod2.z.array(import_zod2.z.object({
+    position: import_zod2.z.number().int().min(1),
+    name: import_zod2.z.string(),
+    placeUrl: import_zod2.z.string().url(),
+    cid: NullableString,
+    cidDecimal: NullableString,
+    rating: NullableString,
+    reviewCount: NullableString,
+    category: NullableString,
+    address: NullableString,
+    phone: NullableString,
+    hoursStatus: NullableString,
+    websiteUrl: NullableString,
+    directionsUrl: NullableString,
+    metadata: import_zod2.z.array(import_zod2.z.string())
+  })),
+  durationMs: import_zod2.z.number().int().min(0)
+};
+var DirectoryMapsBusinessOutput = import_zod2.z.object({
+  position: import_zod2.z.number().int().min(1),
+  name: import_zod2.z.string(),
+  placeUrl: import_zod2.z.string().url(),
+  cid: NullableString,
+  cidDecimal: NullableString,
+  rating: NullableString,
+  reviewCount: NullableString,
+  category: NullableString,
+  address: NullableString,
+  phone: NullableString,
+  hoursStatus: NullableString,
+  websiteUrl: NullableString,
+  directionsUrl: NullableString,
+  metadata: import_zod2.z.array(import_zod2.z.string())
+});
+var DirectoryWorkflowOutputSchema = {
+  query: import_zod2.z.string(),
+  state: import_zod2.z.string(),
+  minPopulation: import_zod2.z.number().int().min(0),
+  populationYear: import_zod2.z.number().int().min(2020).max(2025),
+  maxResultsPerCity: import_zod2.z.number().int().min(1).max(50),
+  concurrency: import_zod2.z.number().int().min(1).max(5),
+  censusSourceUrl: import_zod2.z.string().url(),
+  usZipsSourcePath: NullableString,
+  warnings: import_zod2.z.array(import_zod2.z.string()),
+  extractedAt: import_zod2.z.string(),
+  selectedCityCount: import_zod2.z.number().int().min(0),
+  totalResultCount: import_zod2.z.number().int().min(0),
+  csvPath: NullableString,
+  cities: import_zod2.z.array(import_zod2.z.object({
+    city: import_zod2.z.string(),
+    state: import_zod2.z.string(),
+    location: import_zod2.z.string(),
+    cityKey: import_zod2.z.string(),
+    censusName: import_zod2.z.string(),
+    population: import_zod2.z.number().int().min(0),
+    populationYear: import_zod2.z.number().int().min(2020).max(2025),
+    zips: import_zod2.z.array(import_zod2.z.string()),
+    counties: import_zod2.z.array(import_zod2.z.string()),
+    status: import_zod2.z.enum(["ok", "empty", "failed"]),
+    error: NullableString,
+    resultCount: import_zod2.z.number().int().min(0),
+    durationMs: import_zod2.z.number().int().min(0),
+    results: import_zod2.z.array(DirectoryMapsBusinessOutput)
+  })),
+  durationMs: import_zod2.z.number().int().min(0)
+};
+var OrganicResultOutput = import_zod2.z.object({
+  position: import_zod2.z.number().int(),
+  title: import_zod2.z.string(),
+  url: import_zod2.z.string(),
+  domain: import_zod2.z.string(),
+  snippet: NullableString
+});
+var AiOverviewOutput = import_zod2.z.object({
+  detected: import_zod2.z.boolean(),
+  text: NullableString
+}).nullable();
+var EntityIdsOutput = import_zod2.z.object({
+  kgIds: import_zod2.z.array(import_zod2.z.string()),
+  cids: import_zod2.z.array(import_zod2.z.string()),
+  gcids: import_zod2.z.array(import_zod2.z.string())
+}).nullable();
+var HarvestPaaOutputSchema = {
+  query: import_zod2.z.string(),
+  location: NullableString,
+  questionCount: import_zod2.z.number().int().min(0),
+  completionStatus: NullableString,
+  questions: import_zod2.z.array(import_zod2.z.object({
+    question: import_zod2.z.string(),
+    answer: NullableString,
+    sourceTitle: NullableString,
+    sourceSite: NullableString
+  })),
+  organicResults: import_zod2.z.array(OrganicResultOutput),
+  aiOverview: AiOverviewOutput,
+  entityIds: EntityIdsOutput,
+  durationMs: import_zod2.z.number().min(0).nullable()
+};
+var SearchSerpOutputSchema = {
+  query: import_zod2.z.string(),
+  location: NullableString,
+  organicResults: import_zod2.z.array(OrganicResultOutput),
+  localPack: import_zod2.z.array(import_zod2.z.object({
+    position: import_zod2.z.number().int(),
+    name: import_zod2.z.string(),
+    rating: NullableString,
+    reviewCount: NullableString,
+    websiteUrl: NullableString
+  })),
+  aiOverview: AiOverviewOutput,
+  entityIds: EntityIdsOutput
+};
+var ExtractUrlOutputSchema = {
+  url: import_zod2.z.string(),
+  title: NullableString,
+  headings: import_zod2.z.array(import_zod2.z.object({
+    level: import_zod2.z.number().int(),
+    text: import_zod2.z.string()
+  })),
+  schemaBlockCount: import_zod2.z.number().int().min(0),
+  entityName: NullableString,
+  entityTypes: import_zod2.z.array(import_zod2.z.string()),
+  napScore: import_zod2.z.number().nullable(),
+  missingSchemaFields: import_zod2.z.array(import_zod2.z.string()),
+  screenshotSaved: NullableString
+};
+var ExtractSiteOutputSchema = {
+  url: import_zod2.z.string(),
+  pageCount: import_zod2.z.number().int().min(0),
+  pages: import_zod2.z.array(import_zod2.z.object({
+    url: import_zod2.z.string(),
+    title: NullableString,
+    schemaTypes: import_zod2.z.array(import_zod2.z.string())
+  })),
+  durationMs: import_zod2.z.number().min(0)
+};
+var MapsPlaceIntelOutputSchema = {
+  name: import_zod2.z.string(),
+  rating: NullableString,
+  reviewCount: NullableString,
+  category: NullableString,
+  address: NullableString,
+  phone: NullableString,
+  website: NullableString,
+  hoursSummary: NullableString,
+  bookingUrl: NullableString,
+  kgmid: NullableString,
+  cidDecimal: NullableString,
+  cidUrl: NullableString,
+  lat: import_zod2.z.number().nullable(),
+  lng: import_zod2.z.number().nullable(),
+  reviewsStatus: import_zod2.z.string(),
+  reviewsCollected: import_zod2.z.number().int().min(0),
+  reviewTopics: import_zod2.z.array(import_zod2.z.object({
+    label: import_zod2.z.string(),
+    count: import_zod2.z.string()
+  }))
+};
+var CreditsInfoOutputSchema = {
+  balanceCredits: import_zod2.z.number().nullable(),
+  matchedCost: import_zod2.z.object({
+    label: import_zod2.z.string(),
+    credits: import_zod2.z.number(),
+    unit: import_zod2.z.string(),
+    notes: NullableString
+  }).nullable(),
+  costs: import_zod2.z.array(import_zod2.z.object({
+    key: import_zod2.z.string(),
+    label: import_zod2.z.string(),
+    credits: import_zod2.z.number(),
+    unit: import_zod2.z.string(),
+    notes: NullableString
+  })),
+  ledger: import_zod2.z.array(import_zod2.z.object({
+    createdAt: import_zod2.z.string(),
+    operation: import_zod2.z.string(),
+    credits: import_zod2.z.number(),
+    description: NullableString
+  }))
+};
+var MapSiteUrlsOutputSchema = {
+  startUrl: import_zod2.z.string(),
+  totalFound: import_zod2.z.number().int().min(0),
+  truncated: import_zod2.z.boolean(),
+  okCount: import_zod2.z.number().int().min(0),
+  redirectCount: import_zod2.z.number().int().min(0),
+  brokenCount: import_zod2.z.number().int().min(0),
+  urls: import_zod2.z.array(import_zod2.z.object({
+    url: import_zod2.z.string(),
+    status: import_zod2.z.number().int().nullable()
+  })),
+  durationMs: import_zod2.z.number().min(0)
+};
+var YoutubeHarvestOutputSchema = {
+  mode: import_zod2.z.string(),
+  videoCount: import_zod2.z.number().int().min(0),
+  channel: import_zod2.z.object({
+    title: NullableString,
+    subscriberCount: NullableString
+  }).nullable(),
+  videos: import_zod2.z.array(import_zod2.z.object({
+    videoId: import_zod2.z.string(),
+    title: import_zod2.z.string(),
+    channelName: NullableString,
+    views: NullableString,
+    duration: NullableString,
+    url: NullableString
+  }))
+};
+var FacebookAdSearchOutputSchema = {
+  query: import_zod2.z.string(),
+  advertiserCount: import_zod2.z.number().int().min(0),
+  advertisers: import_zod2.z.array(import_zod2.z.object({
+    name: NullableString,
+    adCount: import_zod2.z.number().int().nullable(),
+    libraryId: NullableString
+  }))
+};
+var FacebookPageIntelOutputSchema = {
+  advertiserName: NullableString,
+  totalAds: import_zod2.z.number().int().min(0),
+  activeCount: import_zod2.z.number().int().min(0),
+  videoCount: import_zod2.z.number().int().min(0),
+  imageCount: import_zod2.z.number().int().min(0),
+  ads: import_zod2.z.array(import_zod2.z.object({
+    libraryId: NullableString,
+    status: NullableString,
+    creativeType: NullableString,
+    headline: NullableString,
+    cta: NullableString,
+    startDate: NullableString,
+    videoUrl: NullableString,
+    variations: import_zod2.z.number().int().nullable()
+  }))
+};
+var CreditsInfoInputSchema = {
+  item: import_zod2.z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", or "YouTube transcription"'),
+  includeLedger: import_zod2.z.boolean().default(false).describe("Whether to include recent credit ledger entries")
+};
+var SearchSerpInputSchema = {
+  query: import_zod2.z.string().min(1).describe('Core search topic only. Separate location when possible. If user says "best dentist in Brooklyn NY serp", use query="best dentist" and location="Brooklyn, NY".'),
+  location: import_zod2.z.string().optional().describe("City, region, or country for geo-targeted results, inferred from user request when present."),
+  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."),
+  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)")
+};
+var CaptureSerpSnapshotInputSchema = {
+  query: import_zod2.z.string().min(1).describe("Core search query to capture as a structured SERP Intelligence snapshot. Separate the place into location when the user gives a city, region, country, or ZIP."),
+  location: import_zod2.z.string().optional().describe("City, region, country, or service area used for localized Google results. MCP Scraper records location evidence; UULE alone is not proof of localization."),
+  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."),
+  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."),
+  includePageSnapshots: import_zod2.z.boolean().default(false).describe("Also capture ranking-page snapshots for selected SERP URLs through the same product capture path."),
+  pageSnapshotLimit: import_zod2.z.number().int().min(0).max(10).default(0).describe("Maximum ranking-page snapshots to capture when includePageSnapshots is true. Use 0 when only SERP evidence is needed.")
+};
+var ScreenshotInputSchema = {
+  url: import_zod2.z.string().url().describe("URL to capture as a full-page screenshot. Use http or https. Pass allowLocal: true to capture localhost or private-network URLs during development."),
+  device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport profile. desktop = 1440\xD7900. mobile = 390\xD7844. Use desktop by default; use mobile when the user asks for a mobile view."),
+  allowLocal: import_zod2.z.boolean().default(false).describe("Allow localhost and private-network URLs (127.x, 192.168.x, 10.x, etc.). For local development only \u2014 not for production use.")
+};
+var CaptureSerpPageSnapshotsInputSchema = {
+  urls: import_zod2.z.array(import_zod2.z.string().url()).min(1).max(25).describe("Public HTTP/HTTPS URLs to capture as SERP Intelligence page snapshots. Do not pass localhost, private IPs, file URLs, or internal admin URLs."),
+  targets: import_zod2.z.array(import_zod2.z.object({
+    url: import_zod2.z.string().url().describe("Public HTTP/HTTPS URL to capture."),
+    sourceKind: import_zod2.z.enum(["organic", "ai_citation", "local_pack_website", "configured_target", "site_subject"]).default("configured_target").describe("Why this page is being captured for SERP Intelligence evidence."),
+    sourcePosition: import_zod2.z.number().int().min(1).optional().describe("Ranking or citation position when the page came from SERP evidence.")
+  }).strict()).min(1).max(25).optional().describe("Structured page snapshot targets. Use this instead of urls when source kind or position should be preserved."),
+  maxConcurrency: import_zod2.z.number().int().min(1).max(5).default(2).describe("Parallel page captures. Use 2 normally; higher values can increase proxy/browser pressure."),
+  timeoutMs: import_zod2.z.number().int().min(1e3).max(6e4).default(15e3).describe("Per-page capture timeout in milliseconds. Increase for slow pages; timeout artifacts are returned as structured capture failures."),
+  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/paa-mcp-server.ts
+function liveWebToolAnnotations(title) {
+  return {
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  };
+}
+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);
+  } catch {
+    return [];
+  }
+}
+function registerSavedReportResources(server2) {
+  server2.registerResource(
+    "saved-report",
+    new import_mcp2.ResourceTemplate("report://{filename}", {
+      list: () => ({
+        resources: listSavedReports().map((r) => ({
+          uri: `report://${encodeURIComponent(r.filename)}`,
+          name: r.filename,
+          mimeType: "text/markdown"
+        }))
+      })
+    }),
+    {
+      title: "Saved MCP Scraper Reports",
+      description: "Markdown research reports saved by previous MCP Scraper tool calls. Read a report to reuse prior research without re-scraping or spending credits.",
+      mimeType: "text/markdown"
+    },
+    async (uri, variables) => {
+      const requested = Array.isArray(variables.filename) ? variables.filename[0] : variables.filename;
+      const filename = (0, import_node_path3.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");
+      return { contents: [{ uri: uri.href, mimeType: "text/markdown", text }] };
+    }
+  );
+}
+function registerPaaExtractorMcpTools(server2, executor, options = {}) {
+  const savesReports = options.savesReportsLocally !== false;
+  const reportNote = savesReports ? " Saves a full Markdown report locally." : " Reports are returned inline; no files are saved on this hosted endpoint.";
+  const withReportNote = (description) => `${description}${reportNote}`;
+  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.'),
+    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."),
+    inputSchema: SearchSerpInputSchema,
+    outputSchema: SearchSerpOutputSchema,
+    annotations: liveWebToolAnnotations("Google SERP Lookup")
+  }, async (input) => formatSearchSerp(await executor.searchSerp(input), input));
+  server2.registerTool("extract_url", {
+    title: "Single URL Extract",
+    description: withReportNote("Extract structured data from one public URL: page content as Markdown, heading structure, JSON-LD schema, entity details, NAP score, metadata, and missing schema fields. Use when the user provides a single URL or asks to inspect/scrape one page."),
+    inputSchema: ExtractUrlInputSchema,
+    outputSchema: ExtractUrlOutputSchema,
+    annotations: liveWebToolAnnotations("Single URL Extract")
+  }, async (input) => formatExtractUrl(await executor.extractUrl(input), input));
+  server2.registerTool("map_site_urls", {
+    title: "Site URL Map",
+    description: withReportNote("Map/crawl a public website to build a URL inventory with HTTP status codes, broken links, redirects, and site scope. Use before extract_site for audits or when the user asks for a sitemap/URL inventory."),
+    inputSchema: MapSiteUrlsInputSchema,
+    outputSchema: MapSiteUrlsOutputSchema,
+    annotations: liveWebToolAnnotations("Site URL Map")
+  }, async (input) => formatMapSiteUrls(await executor.mapSiteUrls(input), input));
+  server2.registerTool("extract_site", {
+    title: "Multi-Page Site Extract",
+    description: withReportNote("Run multi-page extraction across a public website. Returns per-page titles, H1s, metadata, headings, schema/entity data, canonical URLs, and content. Use for website audits, competitor audits, and full-site extraction."),
+    inputSchema: ExtractSiteInputSchema,
+    outputSchema: ExtractSiteOutputSchema,
+    annotations: liveWebToolAnnotations("Multi-Page Site Extract")
+  }, async (input) => formatExtractSite(await executor.extractSite(input), input));
+  server2.registerTool("youtube_harvest", {
+    title: "YouTube Video Harvest",
+    description: withReportNote('Harvest YouTube video metadata by search query or channel handle/ID/URL. Use mode "search" for keyword/topic requests and mode "channel" for @handles, channel IDs, or channel URLs. Returns titles, views, dates, durations, URLs, thumbnails, and videoIds for follow-up transcription.'),
+    inputSchema: YoutubeHarvestInputSchema,
+    outputSchema: YoutubeHarvestOutputSchema,
+    annotations: liveWebToolAnnotations("YouTube Video Harvest")
+  }, async (input) => formatYoutubeHarvest(await executor.youtubeHarvest(input), input));
+  server2.registerTool("youtube_transcribe", {
+    title: "YouTube Transcription",
+    description: withReportNote("Fetch and transcribe captions from a YouTube video. Returns full transcript, timestamped chunks, and word count. Pass a videoId from youtube_harvest results or infer it from a YouTube URL if the user provided one."),
+    inputSchema: YoutubeTranscribeInputSchema,
+    annotations: liveWebToolAnnotations("YouTube Transcription")
+  }, async (input) => formatYoutubeTranscribe(await executor.youtubeTranscribe(input), input));
+  server2.registerTool("facebook_page_intel", {
+    title: "Facebook Advertiser Ad Intel",
+    description: withReportNote("Harvest ads from a Facebook advertiser. Returns ad copy, headlines, CTAs, creative type, status, landing URLs, and video URLs ready for transcription. Accepts pageId, libraryId, or a brand/advertiser name as query. Use after facebook_ad_search when possible."),
+    inputSchema: FacebookPageIntelInputSchema,
+    outputSchema: FacebookPageIntelOutputSchema,
+    annotations: liveWebToolAnnotations("Facebook Advertiser Ad Intel")
+  }, async (input) => formatFacebookPageIntel(await executor.facebookPageIntel(input), input));
+  server2.registerTool("facebook_ad_search", {
+    title: "Facebook Ad Library Search",
+    description: withReportNote("Search Facebook Ad Library by brand, advertiser, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs. Use to discover competitors, then pass libraryId to facebook_page_intel."),
+    inputSchema: FacebookAdSearchInputSchema,
+    outputSchema: FacebookAdSearchOutputSchema,
+    annotations: liveWebToolAnnotations("Facebook Ad Library Search")
+  }, async (input) => formatFacebookAdSearch(await executor.facebookAdSearch(input), input));
+  server2.registerTool("facebook_ad_transcribe", {
+    title: "Facebook Ad Transcription",
+    description: "Transcribe audio from a Facebook ad video. Returns full transcript and timestamped chunks. Use the videoUrl value from facebook_page_intel results.",
+    inputSchema: FacebookAdTranscribeInputSchema,
+    annotations: liveWebToolAnnotations("Facebook Ad Transcription")
+  }, async (input) => formatFacebookAdTranscribe(await executor.facebookAdTranscribe(input), input));
+  server2.registerTool("maps_place_intel", {
+    title: "Google Maps Business Profile Details",
+    description: withReportNote('Extract Google Maps business intelligence for one known/named business: rating, review count, category, address, phone, website, hours, booking URL, review histogram, review topics, about attributes, entity IDs, and optional review cards. Do not use this for category searches, local market prospect lists, or requests for multiple GMB/GBP profiles; use maps_search first for those. Split business name from location (e.g. "Elite Roofing Denver CO" => businessName "Elite Roofing", location "Denver, CO"). Pass includeReviews true when the user asks for reviews/customer pain.'),
+    inputSchema: MapsPlaceIntelInputSchema,
+    outputSchema: MapsPlaceIntelOutputSchema,
+    annotations: liveWebToolAnnotations("Google Maps Business Profile Details")
+  }, 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.'),
+    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.'),
+    inputSchema: DirectoryWorkflowInputSchema,
+    outputSchema: DirectoryWorkflowOutputSchema,
+    annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
+  }, async (input) => formatDirectoryWorkflow(await executor.directoryWorkflow(input), 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.",
+    inputSchema: CreditsInfoInputSchema,
+    outputSchema: CreditsInfoOutputSchema,
+    annotations: {
+      title: "MCP Scraper Credits & Costs",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }, async (input) => formatCreditsInfo(await executor.creditsInfo(input), input));
+}
+
+// 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);
+  for (const path of paths) {
+    try {
+      const value = (0, import_node_fs4.readFileSync)(path, "utf8").trim();
+      if (value) return value;
+    } catch {
+    }
+  }
+  return void 0;
+}
+var apiKey = (process.env.MCP_SCRAPER_API_KEY ?? process.env.MCP_SCRAPER_KEY ?? process.env.MCP_API_KEY ?? readApiKeyFile())?.trim();
+if (!apiKey) {
+  process.stderr.write("MCP_SCRAPER_API_KEY env var or ~/.mcp-scraper-key is required\n");
+  process.exit(1);
+}
+var baseUrl = process.env.MCP_SCRAPER_BASE_URL?.trim() || process.env.MCP_BASE_URL?.trim() || "https://mcpscraper.dev";
+var consoleBaseUrl = process.env.BROWSER_AGENT_CONSOLE_URL?.trim() || baseUrl;
+var server = new import_mcp3.McpServer({ name: "mcp-scraper", version: PACKAGE_VERSION });
+registerPaaExtractorMcpTools(server, new HttpMcpToolExecutor(baseUrl, apiKey));
+registerBrowserAgentMcpTools(server, { baseUrl, apiKey, consoleBaseUrl });
+var transport = new import_stdio.StdioServerTransport();
+async function main() {
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=mcp-scraper-combined-stdio-server.cjs.map