mcp-scraper 0.1.0

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

@@ -0,0 +1,840 @@
+#!/usr/bin/env node
+"use strict";
+
+// bin/mcp-stdio-server.ts
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+
+// src/mcp/http-mcp-tool-executor.ts
+var HttpMcpToolExecutor = class {
+  baseUrl;
+  apiKey;
+  constructor(baseUrl2, apiKey2) {
+    this.baseUrl = baseUrl2.replace(/\/$/, "");
+    this.apiKey = apiKey2;
+  }
+  async call(path, body) {
+    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(29e4)
+      });
+      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);
+      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);
+  }
+};
+
+// src/mcp/paa-mcp-server.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+
+// src/mcp/mcp-tool-schemas.ts
+var import_zod = require("zod");
+var HarvestPaaInputSchema = {
+  query: import_zod.z.string().min(1).describe("Search query to harvest PAA questions for"),
+  location: import_zod.z.string().optional().describe("Location name for geo-targeted results"),
+  maxQuestions: import_zod.z.number().int().min(1).max(100).default(30).describe("Number of PAA questions to extract (max 100)"),
+  gl: import_zod.z.string().length(2).default("us"),
+  hl: import_zod.z.string().default("en")
+};
+var ExtractUrlInputSchema = {
+  url: import_zod.z.string().url()
+};
+var MapSiteUrlsInputSchema = {
+  url: import_zod.z.string().url(),
+  maxUrls: import_zod.z.number().int().min(1).max(500).optional()
+};
+var ExtractSiteInputSchema = {
+  url: import_zod.z.string().url(),
+  maxPages: import_zod.z.number().int().min(1).max(50).optional()
+};
+var YoutubeHarvestInputSchema = {
+  mode: import_zod.z.enum(["search", "channel"]),
+  query: import_zod.z.string().optional().describe("Required when mode is search"),
+  channelHandle: import_zod.z.string().optional().describe("YouTube channel handle, e.g. @mkbhd"),
+  maxVideos: import_zod.z.number().int().min(1).max(500).default(50)
+};
+var YoutubeTranscribeInputSchema = {
+  videoId: import_zod.z.string().min(1).describe("YouTube video ID, e.g. dQw4w9WgXcQ")
+};
+var FacebookPageIntelInputSchema = {
+  pageId: import_zod.z.string().optional(),
+  libraryId: import_zod.z.string().optional(),
+  query: import_zod.z.string().optional().describe("One of pageId, libraryId, or query is required"),
+  maxAds: import_zod.z.number().int().min(1).max(200).default(50),
+  country: import_zod.z.string().length(2).default("US")
+};
+var FacebookAdSearchInputSchema = {
+  query: import_zod.z.string().min(1),
+  country: import_zod.z.string().length(2).default("US"),
+  maxResults: import_zod.z.number().int().min(1).max(20).default(10)
+};
+var FacebookAdTranscribeInputSchema = {
+  videoUrl: import_zod.z.string().url().describe("Facebook CDN video URL from a facebook_page_intel result")
+};
+var MapsPlaceIntelInputSchema = {
+  businessName: import_zod.z.string().min(1).describe("Business name to search for on Google Maps"),
+  location: import_zod.z.string().min(1).describe('City and state, e.g. "Denver, CO"'),
+  gl: import_zod.z.string().length(2).default("us"),
+  hl: import_zod.z.string().length(2).default("en"),
+  includeReviews: import_zod.z.boolean().default(false).describe("Whether to fetch individual review cards"),
+  maxReviews: import_zod.z.number().int().min(1).max(500).default(50).describe("Max review cards to return (requires includeReviews: true)")
+};
+var CreditsInfoInputSchema = {
+  item: import_zod.z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", or "YouTube transcription"'),
+  includeLedger: import_zod.z.boolean().default(false).describe("Whether to include recent credit ledger entries")
+};
+var SearchSerpInputSchema = {
+  query: import_zod.z.string().min(1).describe("Search query to retrieve organic Google results for"),
+  location: import_zod.z.string().optional().describe("Location name for geo-targeted results"),
+  gl: import_zod.z.string().length(2).default("us"),
+  hl: import_zod.z.string().default("en"),
+  pages: import_zod.z.number().int().min(1).max(2).default(1).describe("Number of result pages to fetch (1\u20132)")
+};
+
+// src/mcp/mcp-response-formatter.ts
+function twoBlocks(full, summary) {
+  return { content: [{ type: "text", text: full }, { type: "text", text: summary }] };
+}
+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 (parsed.error === "insufficient_balance") {
+      return { error: `Insufficient credits. Balance: ${parsed.balance_credits} credits. This call requires ${parsed.required_credits} credits. Top up at ${parsed.topup_url}` };
+    }
+    if (raw.isError) return { error: text || "Tool error" };
+    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;
+}
+var DIRECTIVE_FULL = "> \u{1F4C4} **FULL REPORT** \u2014 render as artifact or expandable block\n\n";
+var DIRECTIVE_SUMMARY = "> \u{1F4AC} **SUMMARY** \u2014 present this inline; offer the full report above as an artifact\n\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 durationMs = d.stats?.durationMs;
+  const paaRows = flat.map(
+    (r, i) => `| ${i + 1} | ${r.question} | ${truncate(r.answer, 120)} | ${r.source_site ?? ""} |`
+  ).join("\n");
+  const paaTable = flat.length ? `## People Also Ask (${flat.length} questions)
+| # | Question | Answer | Source |
+|---|----------|--------|--------|
+${paaRows}` : "## People Also Ask\n*No questions extracted*";
+  const serpRows = organic.map(
+    (r) => `| ${r.position} | ${r.title} | [${r.domain}](${r.url}) | ${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
+- Questions: ${flat.length} \xB7 Duration: ${(durationMs / 1e3).toFixed(1)}s` : "";
+  const tips = `
+---
+\u{1F4A1} **Tips**
+- Max questions: \`maxQuestions: 100\` (current: ${input.maxQuestions ?? 30})
+- Organic results only: use \`search_serp\`
+- Dig into a result: use \`extract_url\` on any organic URL`;
+  const full = `${DIRECTIVE_FULL}# PAA Report: "${input.query}"${input.location ? ` \xB7 ${input.location}` : ""}
+
+${paaTable}${serpTable}${entityIdsSection(entityIds)}${aiSection}${statsLine}${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 = [
+    `${DIRECTIVE_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 100 \xB7Use \`extract_url\` to dig into any result`
+  ].filter(Boolean).join("\n");
+  return twoBlocks(full, summary);
+}
+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 serpRows = organic.map(
+    (r) => `| ${r.position} | ${r.title} | [${r.domain}](${r.url}) | ${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} | ${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 = `${DIRECTIVE_FULL}# SERP Report: "${input.query}"${input.location ? ` \xB7 ${input.location}` : ""}
+
+${serpTable}${localSection}${entityIdsSection(entityIds)}${aiSection}${tips}`;
+  const topO = organic.slice(0, 5).map((r) => `${r.position}. [${r.title}](${r.url}) \u2014 ${r.domain}`).join("\n");
+  const summary = [
+    `${DIRECTIVE_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 twoBlocks(full, summary);
+}
+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 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 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 = `${DIRECTIVE_FULL}# URL Extract: ${url}
+**${title}**
+${headingSection}${kpoSection}${bodySection}${tips}`;
+  const summary = [
+    `${DIRECTIVE_SUMMARY}**Extracted:** ${title}`,
+    `**URL:** ${url}`,
+    kpo?.entityName ? `**Entity:** ${kpo.entityName} (${kpo.type?.join(", ") ?? "unknown"})` : "",
+    kpo?.napScore !== void 0 ? `**NAP Score:** ${kpo.napScore}/5` : "",
+    headings.length ? `**${headings.length} headings**` : "",
+    `
+\u{1F4A1} Use \`extract_site\` to crawl the full domain`
+  ].filter(Boolean).join("\n");
+  return twoBlocks(full, summary);
+}
+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 = [
+    `${DIRECTIVE_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 = [
+    `${DIRECTIVE_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 twoBlocks(full, summary);
+}
+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} | ${p.title ?? "Untitled"} | ${p.url} | ${schemaInfo} |`;
+  }).join("\n");
+  const full = [
+    `${DIRECTIVE_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 = [
+    `${DIRECTIVE_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 twoBlocks(full, summary);
+}
+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} | ${truncate(v.title, 70)} | ${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 = [
+    `${DIRECTIVE_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 = [
+    `${DIRECTIVE_SUMMARY}**YouTube: ${label}** \u2014 ${videos.length} videos`,
+    `
+**Top videos:**
+${top5}`,
+    `
+\u{1F4A1} Transcribe any video: \`youtube_transcribe\` with its videoId`
+  ].join("\n");
+  return twoBlocks(full, summary);
+}
+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 = Math.floor(c.startMs / 1e3);
+    const mm = String(Math.floor(sec / 60)).padStart(2, "0");
+    const ss = String(sec % 60).padStart(2, "0");
+    return `| ${mm}:${ss} | ${truncate(c.text, 120)} |`;
+  }).join("\n");
+  const full = [
+    `${DIRECTIVE_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 = [
+    `${DIRECTIVE_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 twoBlocks(full, summary);
+}
+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 = [
+    `${DIRECTIVE_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 = [
+    `${DIRECTIVE_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 twoBlocks(full, summary);
+}
+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} | ${a.name} | ${a.adCount ?? "\u2014"} | \`${a.libraryId ?? "\u2014"}\` |`
+  ).join("\n");
+  const full = [
+    `${DIRECTIVE_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 = [
+    `${DIRECTIVE_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 twoBlocks(full, summary);
+}
+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 = [
+    `${DIRECTIVE_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 = [
+    `${DIRECTIVE_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 twoBlocks(full, summary);
+}
+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 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 = reviews.length ? `
+## 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 = [
+    `${DIRECTIVE_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 = [
+    `${DIRECTIVE_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,
+    reviews.length ? `
+\u{1F4AC} ${reviews.length} reviews fetched \u2014 full list in artifact above` : null
+  ].filter(Boolean).join("\n");
+  return twoBlocks(full, summary);
+}
+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 = Math.floor(c.startMs / 1e3);
+    const mm = String(Math.floor(sec / 60)).padStart(2, "0");
+    const ss = String(sec % 60).padStart(2, "0");
+    return `| ${mm}:${ss} | ${truncate(c.text, 120)} |`;
+  }).join("\n");
+  const full = [
+    `${DIRECTIVE_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 = [
+    `${DIRECTIVE_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 twoBlocks(full, summary);
+}
+
+// src/mcp/paa-mcp-server.ts
+function buildPaaExtractorMcpServer(executor2) {
+  const server2 = new import_mcp.McpServer({ name: "paa-extractor", version: "1.0.0" });
+  server2.registerTool("harvest_paa", {
+    description: "Extract PAA (People Also Ask) questions from Google Search. Returns full question list with answers, organic SERP, entity IDs (CID/GCID/KG MID), and AI Overview. Use maxQuestions to control volume (up to 40).",
+    inputSchema: HarvestPaaInputSchema
+  }, async (input) => formatHarvestPaa(await executor2.harvestPaa(input), input));
+  server2.registerTool("search_serp", {
+    description: "Fetch organic Google search results. Returns ranked URLs, titles, snippets, local pack, entity IDs (CID/GCID/KG MID), and AI Overview. Use when you need SERP positions without PAA expansion.",
+    inputSchema: SearchSerpInputSchema
+  }, async (input) => formatSearchSerp(await executor2.searchSerp(input), input));
+  server2.registerTool("extract_url", {
+    description: "Extract structured data from a single URL: page content as Markdown, heading structure, JSON-LD schema, entity details, NAP score, and missing schema fields. Use for SEO audits and entity validation.",
+    inputSchema: ExtractUrlInputSchema
+  }, async (input) => formatExtractUrl(await executor2.extractUrl(input), input));
+  server2.registerTool("map_site_urls", {
+    description: "Spider a website to build a complete URL inventory with HTTP status codes. Identifies broken links and redirect chains. Use before extract_site to understand site scope.",
+    inputSchema: MapSiteUrlsInputSchema
+  }, async (input) => formatMapSiteUrls(await executor2.mapSiteUrls(input), input));
+  server2.registerTool("extract_site", {
+    description: "Run multi-page extraction across an entire website. Returns schema, entity data, headings, and content from each page. Use map_site_urls first to check scope.",
+    inputSchema: ExtractSiteInputSchema
+  }, async (input) => formatExtractSite(await executor2.extractSite(input), input));
+  server2.registerTool("youtube_harvest", {
+    description: 'Harvest YouTube video metadata by search query or channel handle. Returns titles, view counts, durations, and videoIds. Use mode "search" for keyword results or "channel" for a specific creator.',
+    inputSchema: YoutubeHarvestInputSchema
+  }, async (input) => formatYoutubeHarvest(await executor2.youtubeHarvest(input), input));
+  server2.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.",
+    inputSchema: YoutubeTranscribeInputSchema
+  }, async (input) => formatYoutubeTranscribe(await executor2.youtubeTranscribe(input), input));
+  server2.registerTool("facebook_page_intel", {
+    description: "Harvest all ads from a Facebook advertiser. Returns ad copy, headlines, CTAs, creative type, status, and video URLs ready for transcription. Accepts pageId, libraryId, or a brand name as query.",
+    inputSchema: FacebookPageIntelInputSchema
+  }, async (input) => formatFacebookPageIntel(await executor2.facebookPageIntel(input), input));
+  server2.registerTool("facebook_ad_search", {
+    description: "Search Facebook Ad Library by keyword. Returns advertisers with ad counts and library IDs. Use to discover competitors, then pass libraryId to facebook_page_intel to get their full ad list.",
+    inputSchema: FacebookAdSearchInputSchema
+  }, async (input) => formatFacebookAdSearch(await executor2.facebookAdSearch(input), input));
+  server2.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 executor2.facebookAdTranscribe(input), input));
+  server2.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, and optional review cards. Pass includeReviews: true and maxReviews to fetch individual review text.",
+    inputSchema: MapsPlaceIntelInputSchema
+  }, async (input) => formatMapsPlaceIntel(await executor2.mapsPlaceIntel(input), input));
+  server2.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 executor2.creditsInfo(input), input));
+  return server2;
+}
+
+// bin/mcp-stdio-server.ts
+function readApiKeyFile() {
+  const explicitPath = process.env.MCP_SCRAPER_KEY_PATH?.trim();
+  const paths = [explicitPath, (0, import_node_path.join)((0, import_node_os.homedir)(), ".mcp-scraper-key")].filter(Boolean);
+  for (const path of paths) {
+    try {
+      const value = (0, import_node_fs.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 executor = new HttpMcpToolExecutor(baseUrl, apiKey);
+var server = buildPaaExtractorMcpServer(executor);
+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-stdio-server.cjs.map