mcp-scraper 0.1.0 → 0.1.2

package/dist/chunk-JQKZWEON.js

@@ -0,0 +1,1000 @@
+// src/mcp/paa-mcp-server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/mcp/mcp-tool-schemas.ts
+import { z } from "zod";
+var HarvestPaaInputSchema = {
+  query: 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: 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: z.number().int().min(1).max(150).default(30).describe("Number of PAA questions to extract. Default 30. Maximum 150. Use 10 for quick probes, 30 for normal research, 100-150 when the user asks for everything/full/deep research. Credits are charged by extracted question; unused request hold is refunded."),
+  gl: 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: 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: 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: z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default so city/state searches create or reuse a matching residential proxy. Use configured for the static configured proxy. Use none only for direct-network debugging."),
+  proxyZip: z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only when the user gives a specific ZIP or city-center proxy targeting needs to be forced."),
+  debug: 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: z.string().url().describe("Public http/https URL to extract. Use this when the user provides one specific page URL."),
+  screenshot: 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: z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport for screenshot. desktop = 1440\xD7900. mobile = 390\xD7844. Default desktop."),
+  extractBranding: 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: 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: z.array(z.enum(["image", "video", "audio"])).default(["image", "video", "audio"]).describe("Which media types to download. Default all three."),
+  allowLocal: z.boolean().default(false).describe("Allow localhost and private-network URLs. For local development only.")
+};
+var MapSiteUrlsInputSchema = {
+  url: 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: 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: 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: 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: z.enum(["search", "channel"]).describe("Use search for topic/keyword requests. Use channel when the user provides @handle, channel ID, or channel URL."),
+  query: z.string().optional().describe("Required when mode is search. The YouTube search topic in the user\u2019s words."),
+  channelHandle: z.string().optional().describe("YouTube channel handle, channel ID, or URL. Examples: @mkbhd, UC..., https://youtube.com/@mkbhd."),
+  maxVideos: 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: z.string().min(1).describe("YouTube video ID, e.g. dQw4w9WgXcQ")
+};
+var FacebookPageIntelInputSchema = {
+  pageId: z.string().optional(),
+  libraryId: z.string().optional(),
+  query: z.string().optional().describe("Advertiser or brand name when pageId/libraryId is not known. One of pageId, libraryId, or query is required."),
+  maxAds: z.number().int().min(1).max(200).default(50),
+  country: z.string().length(2).default("US")
+};
+var FacebookAdSearchInputSchema = {
+  query: z.string().min(1).describe("Advertiser, brand, competitor, niche, or keyword to search in Facebook Ad Library."),
+  country: z.string().length(2).default("US"),
+  maxResults: z.number().int().min(1).max(20).default(10)
+};
+var FacebookAdTranscribeInputSchema = {
+  videoUrl: z.string().url().describe("Facebook CDN video URL from a facebook_page_intel result")
+};
+var MapsPlaceIntelInputSchema = {
+  businessName: z.string().min(1).describe('Business name only. If user says "Elite Roofing Denver CO", use businessName="Elite Roofing" and location="Denver, CO".'),
+  location: 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: z.string().length(2).default("us").describe("Google country code inferred from location."),
+  hl: z.string().length(2).default("en").describe("Language inferred from user request."),
+  includeReviews: z.boolean().default(false).describe("Whether to fetch individual review cards"),
+  maxReviews: z.number().int().min(1).max(500).default(50).describe("Max review cards to return (requires includeReviews: true)")
+};
+var CreditsInfoInputSchema = {
+  item: z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", or "YouTube transcription"'),
+  includeLedger: z.boolean().default(false).describe("Whether to include recent credit ledger entries")
+};
+var SearchSerpInputSchema = {
+  query: 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: z.string().optional().describe("City, region, or country for geo-targeted results, inferred from user request when present."),
+  gl: z.string().length(2).default("us").describe("Google country code inferred from location or user language."),
+  hl: z.string().default("en").describe("Google interface/content language inferred from user request."),
+  device: 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: z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default so city/state searches create or reuse a matching residential proxy. Use configured for the static configured proxy. Use none only for direct-network debugging."),
+  proxyZip: z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only when the user gives a specific ZIP or city-center proxy targeting needs to be forced."),
+  debug: z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior."),
+  pages: z.number().int().min(1).max(2).default(1).describe("Number of result pages to fetch (1\u20132)")
+};
+var CaptureSerpSnapshotInputSchema = {
+  query: 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: 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: z.string().length(2).default("us").describe("Google country code inferred from the requested market, e.g. us, gb, ca, au."),
+  hl: z.string().default("en").describe("Google interface/content language inferred from the user request."),
+  device: 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: z.enum(["location", "configured", "none"]).default("location").describe("Proxy behavior for capture. Use location for localized residential proxy targeting, configured for the static residential proxy, and none only for direct-network debugging."),
+  proxyZip: 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."),
+  pages: 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: z.boolean().default(false).describe("Include sanitized browser, proxy, and location diagnostics. Use true when debugging localization, CAPTCHA, proxy selection, or capture reliability."),
+  includePageSnapshots: z.boolean().default(false).describe("Also capture ranking-page snapshots for selected SERP URLs through the same product capture path."),
+  pageSnapshotLimit: 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: 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: 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: 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: z.array(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: z.array(z.object({
+    url: z.string().url().describe("Public HTTP/HTTPS URL to capture."),
+    sourceKind: 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: 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: z.number().int().min(1).max(5).default(2).describe("Parallel page captures. Use 2 normally; higher values can increase proxy/browser pressure."),
+  timeoutMs: 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: z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics for page snapshot debugging. Use true for capture, network, or proxy troubleshooting.")
+};
+
+// src/mcp/mcp-response-formatter.ts
+import { mkdirSync, writeFileSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+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 saveFullReport(full) {
+  if (process.env.MCP_SCRAPER_SAVE_REPORTS === "false") return null;
+  const outDir = process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || join(homedir(), "Downloads", "mcp-scraper");
+  try {
+    mkdirSync(outDir, { recursive: true });
+    const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const file = join(outDir, `${stamp}-${slugifyReportName(reportTitle(full))}.md`);
+    writeFileSync(file, full, "utf8");
+    return file;
+  } 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: formatStructuredError(parsed, text) };
+    const data = parsed.result ?? parsed;
+    return { data };
+  } catch {
+    if (raw.isError) return { error: 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 entityIdsSummaryLine(ids) {
+  if (!ids) return "";
+  const parts = [];
+  if (ids.kgIds?.length) parts.push(`KG MID: ${ids.kgIds[0]}`);
+  if (ids.cids?.length) parts.push(`CID: ${ids.cids[0]}`);
+  if (ids.gcids?.length) parts.push(`GCID: ${ids.gcids[0]}`);
+  return parts.length ? `
+**Entity IDs:** ${parts.join(" \xB7 ")}` : "";
+}
+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.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 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.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";
+    return `- Attempt ${attempt.attempt_number ?? "?"}: ${attempt.outcome ?? attempt.status ?? "unknown"} \xB7 session ${attempt.kernel_session_id ?? kernel.sessionId ?? "unknown"} \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 deleted ${attempt.kernel_delete_succeeded === true ? "yes" : attempt.kernel_delete_succeeded === 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: 150\` (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}`;
+  const topQ = flat.slice(0, 10).map((r, i) => `${i + 1}. ${r.question}`).join("\n");
+  const topO = organic.slice(0, 5).map((r) => `${r.position}. [${r.title}](${r.url}) \u2014 ${r.domain}`).join("\n");
+  const summary = [
+    `**PAA: "${input.query}"** \u2014 ${flat.length} questions extracted`,
+    topQ ? `
+**Top questions:**
+${topQ}` : "",
+    organic.length ? `
+**Top organic results:**
+${topO}` : "",
+    entityIdsSummaryLine(entityIds),
+    `
+\u{1F4A1} \`maxQuestions\` up to 150 \xB7Use \`extract_url\` to dig into any result`
+  ].filter(Boolean).join("\n");
+  return oneBlock(full);
+}
+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}`;
+  const topO = organic.slice(0, 5).map((r) => `${r.position}. [${r.title}](${r.url}) \u2014 ${r.domain}`).join("\n");
+  const summary = [
+    `**SERP: "${input.query}"** \u2014 ${organic.length} organic results`,
+    topO ? `
+**Top results:**
+${topO}` : "",
+    localPack.length ? `
+**Local Pack:** ${localPack.map((b) => b.name).join(", ")}` : "",
+    entityIdsSummaryLine(entityIds),
+    `
+\u{1F4A1} Use \`harvest_paa\` for questions \xB7 \`extract_url\` to scrape any result`
+  ].filter(Boolean).join("\n");
+  return oneBlock(full);
+}
+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 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:** ${screenshotMeta.savedPath}
+- **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 textResult = oneBlock(full);
+  if (screenshotMeta?.savedPath) {
+    try {
+      const imgBuf = readFileSync(screenshotMeta.savedPath);
+      return {
+        content: [
+          ...textResult.content,
+          { type: "image", data: imgBuf.toString("base64"), mimeType: "image/png" }
+        ]
+      };
+    } catch {
+    }
+  }
+  return textResult;
+}
+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");
+  const summary = [
+    `**URL Map: ${input.url}**`,
+    `${d.totalFound} URLs \u2014 ${ok.length} OK \xB7 ${broken.length} broken \xB7 ${redirects.length} redirects`,
+    broken.length ? `
+**Broken URLs:** ${broken.slice(0, 3).map((u) => u.url).join(", ")}` : "",
+    `
+\u{1F4A1} Use \`extract_site\` to extract content from all pages`
+  ].filter(Boolean).join("\n");
+  return oneBlock(full);
+}
+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");
+  const summary = [
+    `**Site Extract: ${input.url}** \u2014 ${pages.length} pages`,
+    pages.slice(0, 5).map((p) => `- ${p.title ?? p.url}`).join("\n"),
+    pages.length > 5 ? `- \u2026 and ${pages.length - 5} more` : "",
+    `
+\u{1F4A1} Use \`extract_url\` to inspect any individual page`
+  ].filter(Boolean).join("\n");
+  return oneBlock(full);
+}
+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");
+  const top5 = videos.slice(0, 5).map((v, i) => `${i + 1}. ${v.title} (\`${v.videoId}\`)`).join("\n");
+  const summary = [
+    `**YouTube: ${label}** \u2014 ${videos.length} videos`,
+    `
+**Top videos:**
+${top5}`,
+    `
+\u{1F4A1} Transcribe any video: \`youtube_transcribe\` with its videoId`
+  ].join("\n");
+  return oneBlock(full);
+}
+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");
+  const summary = [
+    `**YouTube Transcript: \`${input.videoId}\`** \u2014 ${text.split(" ").length} words \xB7 ${durSec}s`,
+    `
+**Preview:**
+> ${truncate(text, 300)}`,
+    `
+\u{1F4A1} Full transcript in artifact above`
+  ].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");
+  const activeAds = ads.filter((a) => a.status?.toLowerCase() === "active").slice(0, 5);
+  const adSummary = activeAds.map((a, i) => `${i + 1}. ${truncate(a.headline ?? a.primaryText, 80)} (${a.creativeType ?? "\u2014"})`).join("\n");
+  const videoCount = ads.filter((a) => a.videoUrl).length;
+  const summary = [
+    `**Facebook Ads: ${advertiser}** \u2014 ${s.totalAds} ads (${s.activeCount} active)`,
+    adSummary ? `
+**Active ads:**
+${adSummary}` : "",
+    `**Creative mix:** ${s.videoCount} video \xB7 ${s.imageCount} image`,
+    videoCount ? `
+\u{1F4A1} ${videoCount} video ads \u2014 transcribe with \`facebook_ad_transcribe\` using the videoUrl` : ""
+  ].filter(Boolean).join("\n");
+  return oneBlock(full);
+}
+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.name)} | ${a.adCount ?? "\u2014"} | \`${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");
+  const summary = [
+    `**Facebook Ad Search: "${input.query}"** \u2014 ${advertisers.length} advertisers`,
+    advertisers.slice(0, 5).map(
+      (a, i) => `${i + 1}. ${a.name}${a.adCount ? ` (${a.adCount} ads)` : ""} \u2014 \`${a.libraryId ?? "\u2014"}\``
+    ).join("\n"),
+    `
+\u{1F4A1} Scan ads with \`facebook_page_intel\` using \`libraryId\``
+  ].filter(Boolean).join("\n");
+  return oneBlock(full);
+}
+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");
+  const summary = [
+    `**Credit balance:** ${balance ?? "unknown"} credits`,
+    matched ? `
+**${matched.label}:** ${matched.credits} credits ${matched.unit}` : null,
+    input.includeLedger && ledger.length ? `
+Recent ledger entries included in the full report.` : null
+  ].filter(Boolean).join("\n");
+  return oneBlock(full);
+}
+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");
+  const summary = [
+    `**${name}** \u2014 ${category ?? "Business"} \xB7 ${ratingLine || "No rating"}`,
+    address ? `\u{1F4CD} ${address}` : null,
+    phone ? `\u{1F4DE} ${phone}` : null,
+    hoursSummary ? `\u{1F550} ${hoursSummary}` : null,
+    website ? `\u{1F310} ${website}` : null,
+    reviewsStatus === "collected" && reviews.length ? `
+\u{1F4AC} ${reviews.length} reviews fetched \u2014 full list in artifact above` : null,
+    reviewsStatus === "unavailable" ? `
+\u26A0\uFE0F Reviews could not be retrieved this run` : null,
+    reviewsStatus === "none_exist" ? `
+\u{1F4AC} No reviews on Google Maps` : null
+  ].filter(Boolean).join("\n");
+  return oneBlock(full);
+}
+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");
+  const summary = [
+    `**Facebook Ad Transcript** \u2014 ${text.split(" ").length} words \xB7 ${durSec}s`,
+    `
+**Preview:**
+> ${truncate(text, 300)}`,
+    `
+\u{1F4A1} Full transcript in artifact above`
+  ].join("\n");
+  return oneBlock(full);
+}
+
+// src/mcp/paa-mcp-server.ts
+function buildPaaExtractorMcpServer(executor) {
+  const server = new McpServer({ name: "mcp-scraper", version: "1.0.0" });
+  server.registerTool("harvest_paa", {
+    description: '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"). Use maxQuestions 30 normally, 100-150 for "full", "deep", "all", or comprehensive research. Credits are charged by extracted question; unused request hold is refunded. Saves a full Markdown report locally.',
+    inputSchema: HarvestPaaInputSchema
+  }, async (input) => formatHarvestPaa(await executor.harvestPaa(input), input));
+  server.registerTool("search_serp", {
+    description: "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. Saves a full Markdown report locally.",
+    inputSchema: SearchSerpInputSchema
+  }, async (input) => formatSearchSerp(await executor.searchSerp(input), input));
+  server.registerTool("extract_url", {
+    description: "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. Saves a full Markdown report locally.",
+    inputSchema: ExtractUrlInputSchema
+  }, async (input) => formatExtractUrl(await executor.extractUrl(input), input));
+  server.registerTool("map_site_urls", {
+    description: "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. Saves a full Markdown report locally.",
+    inputSchema: MapSiteUrlsInputSchema
+  }, async (input) => formatMapSiteUrls(await executor.mapSiteUrls(input), input));
+  server.registerTool("extract_site", {
+    description: "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. Saves a full Markdown report locally.",
+    inputSchema: ExtractSiteInputSchema
+  }, async (input) => formatExtractSite(await executor.extractSite(input), input));
+  server.registerTool("youtube_harvest", {
+    description: '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. Saves a full Markdown report locally.',
+    inputSchema: YoutubeHarvestInputSchema
+  }, async (input) => formatYoutubeHarvest(await executor.youtubeHarvest(input), input));
+  server.registerTool("youtube_transcribe", {
+    description: "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. Saves a full Markdown report locally.",
+    inputSchema: YoutubeTranscribeInputSchema
+  }, async (input) => formatYoutubeTranscribe(await executor.youtubeTranscribe(input), input));
+  server.registerTool("facebook_page_intel", {
+    description: "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. Saves a full Markdown report locally.",
+    inputSchema: FacebookPageIntelInputSchema
+  }, async (input) => formatFacebookPageIntel(await executor.facebookPageIntel(input), input));
+  server.registerTool("facebook_ad_search", {
+    description: "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. Saves a full Markdown report locally.",
+    inputSchema: FacebookAdSearchInputSchema
+  }, async (input) => formatFacebookAdSearch(await executor.facebookAdSearch(input), input));
+  server.registerTool("facebook_ad_transcribe", {
+    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
+  }, async (input) => formatFacebookAdTranscribe(await executor.facebookAdTranscribe(input), input));
+  server.registerTool("maps_place_intel", {
+    description: 'Extract Google Maps business intelligence for a named business: rating, review count, category, address, phone, website, hours, booking URL, review histogram, review topics, about attributes, entity IDs, and optional review cards. 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. Saves a full Markdown report locally.',
+    inputSchema: MapsPlaceIntelInputSchema
+  }, async (input) => formatMapsPlaceIntel(await executor.mapsPlaceIntel(input), input));
+  server.registerTool("credits_info", {
+    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
+  }, async (input) => formatCreditsInfo(await executor.creditsInfo(input), input));
+  return server;
+}
+
+// src/mcp/http-mcp-tool-executor.ts
+var HttpMcpToolExecutor = class {
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  serpIntelligenceTimeoutMs;
+  constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = apiKey;
+    const configuredTimeoutMs = Number(process.env.MCP_SCRAPER_HTTP_TIMEOUT_MS ?? 11e4);
+    this.timeoutMs = Number.isFinite(configuredTimeoutMs) && configuredTimeoutMs > 0 ? configuredTimeoutMs : 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) {
+    return this.call("/harvest/sync", input);
+  }
+  searchSerp(input) {
+    return this.call("/harvest/sync", { ...input, serpOnly: true });
+  }
+  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);
+  }
+  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);
+  }
+};
+
+export {
+  CaptureSerpSnapshotInputSchema,
+  CaptureSerpPageSnapshotsInputSchema,
+  buildPaaExtractorMcpServer,
+  HttpMcpToolExecutor
+};
+//# sourceMappingURL=chunk-JQKZWEON.js.map