mcp-scraper 0.1.5 → 0.1.7

package/dist/bin/api-server.js

@@ -17,8 +17,8 @@ loadDotEnv();
 async function main() {
   const [{ serve }, { app }, { startWorker }, { migrate }] = await Promise.all([
     import("@hono/node-server"),
-    import("../server-V5XMVRYE.js"),
-    import("../worker-UT4ZQU2T.js"),
+    import("../server-YNJHP5PU.js"),
+    import("../worker-PBG6LGET.js"),
     import("../db-YWCNHBLH.js")
   ]);
   const PORT = parseInt(process.env.PORT ?? "3001");

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

@@ -110,6 +110,9 @@ var HttpMcpToolExecutor = class {
   mapsPlaceIntel(input) {
     return this.call("/maps/place", input);
   }
+  mapsSearch(input) {
+    return this.call("/maps/search", input);
+  }
   creditsInfo(input) {
     return this.call("/billing/credits", input);
   }
@@ -124,12 +127,15 @@ var HttpMcpToolExecutor = class {
 // src/mcp/paa-mcp-server.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 
+// src/version.ts
+var PACKAGE_VERSION = "0.1.7";
+
 // src/mcp/mcp-tool-schemas.ts
 var import_zod = require("zod");
 var HarvestPaaInputSchema = {
   query: import_zod.z.string().min(1).describe('Core search topic only. If the user says "best hvac company in Denver CO", use query="best hvac company" and location="Denver, CO". Do not include the location in query when it can be separated.'),
   location: import_zod.z.string().optional().describe('City, region, or country for geo-targeted results, inferred from the user request when present, e.g. "Denver, CO", "Tokyo, Japan", "London, UK".'),
-  maxQuestions: import_zod.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."),
+  maxQuestions: import_zod.z.number().int().min(1).max(200).default(30).describe("Number of PAA questions to extract. Default 30. Maximum 200. Use 10 for quick probes, 30 for normal research, 100-200 when the user asks for everything/full/deep research. Larger harvests get a longer server time budget (151-200 questions \u2192 up to 280s). Credits are charged by extracted question; unused request hold is refunded."),
   gl: import_zod.z.string().length(2).default("us").describe("Google country code inferred from location or user language. Examples: United States us, United Kingdom gb, Japan jp, Canada ca, Australia au."),
   hl: import_zod.z.string().default("en").describe("Google interface/content language inferred from the user request. Use en unless the user asks for another language or locale."),
   device: import_zod.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
@@ -186,6 +192,93 @@ var MapsPlaceIntelInputSchema = {
   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 MapsSearchInputSchema = {
+  query: import_zod.z.string().min(1).describe('Business category, niche, keyword, or search term. If the user says "roofers in Denver CO", use query="roofers" and location="Denver, CO". Do not put the location here when it can be separated.'),
+  location: import_zod.z.string().optional().describe('City, region, country, or service area for the Maps search, e.g. "Denver, CO". Infer from the user request when present.'),
+  gl: import_zod.z.string().length(2).default("us").describe("Google country code inferred from location."),
+  hl: import_zod.z.string().length(2).default("en").describe("Language inferred from user request."),
+  maxResults: import_zod.z.number().int().min(1).max(50).default(10).describe("Number of Google Maps business/profile candidates to return. Default 10. Maximum 50. Use 10 unless the user asks for more.")
+};
+var NullableString = import_zod.z.string().nullable();
+var MapsSearchOutputSchema = {
+  query: import_zod.z.string(),
+  location: import_zod.z.string().nullable(),
+  searchQuery: import_zod.z.string(),
+  searchUrl: import_zod.z.string().url(),
+  extractedAt: import_zod.z.string(),
+  requestedMaxResults: import_zod.z.number().int().min(1).max(50),
+  resultCount: import_zod.z.number().int().min(0).max(50),
+  results: import_zod.z.array(import_zod.z.object({
+    position: import_zod.z.number().int().min(1),
+    name: import_zod.z.string(),
+    placeUrl: import_zod.z.string().url(),
+    cid: NullableString,
+    cidDecimal: NullableString,
+    rating: NullableString,
+    reviewCount: NullableString,
+    category: NullableString,
+    address: NullableString,
+    websiteUrl: NullableString,
+    directionsUrl: NullableString,
+    metadata: import_zod.z.array(import_zod.z.string())
+  })),
+  durationMs: import_zod.z.number().int().min(0)
+};
+var MapSiteUrlsOutputSchema = {
+  startUrl: import_zod.z.string(),
+  totalFound: import_zod.z.number().int().min(0),
+  truncated: import_zod.z.boolean(),
+  okCount: import_zod.z.number().int().min(0),
+  redirectCount: import_zod.z.number().int().min(0),
+  brokenCount: import_zod.z.number().int().min(0),
+  urls: import_zod.z.array(import_zod.z.object({
+    url: import_zod.z.string(),
+    status: import_zod.z.number().int().nullable()
+  })),
+  durationMs: import_zod.z.number().min(0)
+};
+var YoutubeHarvestOutputSchema = {
+  mode: import_zod.z.string(),
+  videoCount: import_zod.z.number().int().min(0),
+  channel: import_zod.z.object({
+    title: NullableString,
+    subscriberCount: NullableString
+  }).nullable(),
+  videos: import_zod.z.array(import_zod.z.object({
+    videoId: import_zod.z.string(),
+    title: import_zod.z.string(),
+    channelName: NullableString,
+    views: NullableString,
+    duration: NullableString,
+    url: NullableString
+  }))
+};
+var FacebookAdSearchOutputSchema = {
+  query: import_zod.z.string(),
+  advertiserCount: import_zod.z.number().int().min(0),
+  advertisers: import_zod.z.array(import_zod.z.object({
+    name: NullableString,
+    adCount: import_zod.z.number().int().nullable(),
+    libraryId: NullableString
+  }))
+};
+var FacebookPageIntelOutputSchema = {
+  advertiserName: NullableString,
+  totalAds: import_zod.z.number().int().min(0),
+  activeCount: import_zod.z.number().int().min(0),
+  videoCount: import_zod.z.number().int().min(0),
+  imageCount: import_zod.z.number().int().min(0),
+  ads: import_zod.z.array(import_zod.z.object({
+    libraryId: NullableString,
+    status: NullableString,
+    creativeType: NullableString,
+    headline: NullableString,
+    cta: NullableString,
+    startDate: NullableString,
+    videoUrl: NullableString,
+    variations: import_zod.z.number().int().nullable()
+  }))
+};
 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")
@@ -235,6 +328,19 @@ var CaptureSerpPageSnapshotsInputSchema = {
 var import_node_fs = require("fs");
 var import_node_os = require("os");
 var import_node_path = require("path");
+
+// src/errors.ts
+function sanitizeVendorName(message) {
+  return message.replace(/kernel\.sh\s+sessions?/gi, "sessions").replace(/kernel\.sh\s+session/gi, "this session").replace(/kernel\.sh/gi, "the service").replace(/kernel\s+sessions?/gi, "sessions").replace(/kernel\s+session/gi, "this session").replace(/\bkernel\b/gi, "the service").replace(/  +/g, " ").trim();
+}
+
+// src/mcp/mcp-response-formatter.ts
+var reportSavingEnabled = true;
+function sanitizeVendorText(text) {
+  return sanitizeVendorName(
+    text.replace(/kernel_session_id/gi, "browser_session_id").replace(/kernel_delete_succeeded/gi, "session_cleanup_succeeded").replace(/kernel_delete_started/gi, "session_cleanup_started").replace(/kernel_delete_error/gi, "session_cleanup_error").replace(/kernelSessionId/g, "browserSessionId").replace(/kernelProxyId/g, "proxyId").replace(/KERNEL_API_KEY/g, "BROWSER_SERVICE_API_KEY").replace(/"kernel"\s*:/gi, '"browserRuntime":')
+  );
+}
 function slugifyReportName(input) {
   return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "mcp-scraper-report";
 }
@@ -246,7 +352,7 @@ function outputBaseDir() {
   return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path.join)((0, import_node_os.homedir)(), "Downloads", "mcp-scraper");
 }
 function saveFullReport(full) {
-  if (process.env.MCP_SCRAPER_SAVE_REPORTS === "false") return null;
+  if (!reportSavingEnabled || process.env.MCP_SCRAPER_SAVE_REPORTS === "false") return null;
   const outDir = outputBaseDir();
   try {
     (0, import_node_fs.mkdirSync)(outDir, { recursive: true });
@@ -259,7 +365,7 @@ function saveFullReport(full) {
   }
 }
 function persistScreenshotLocally(base64, url) {
-  if (process.env.MCP_SCRAPER_SAVE_REPORTS === "false") return null;
+  if (!reportSavingEnabled || process.env.MCP_SCRAPER_SAVE_REPORTS === "false") return null;
   try {
     const dir = (0, import_node_path.join)(outputBaseDir(), "screenshots");
     (0, import_node_fs.mkdirSync)(dir, { recursive: true });
@@ -299,11 +405,11 @@ function parseData(raw) {
   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) };
+    if (raw.isError || parsed.error || parsed.error_code) return { error: sanitizeVendorText(formatStructuredError(parsed, text)) };
     const data = parsed.result ?? parsed;
     return { data };
   } catch {
-    if (raw.isError) return { error: text || "Tool error" };
+    if (raw.isError) return { error: sanitizeVendorText(text || "Tool error") };
     return { error: "Failed to parse tool response" };
   }
 }
@@ -317,15 +423,6 @@ function entityIdsSection(ids) {
 ## 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;
@@ -355,7 +452,7 @@ function debugSection(debug) {
   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");
+  return sanitizeVendorText(lines.join("\n"));
 }
 function errorAttemptsSection(body) {
   const attempts = Array.isArray(body.attempts) ? body.attempts : [];
@@ -409,26 +506,12 @@ ${serpRows}` : "";
   const tips = `
 ---
 \u{1F4A1} **Tips**
-- Max questions: \`maxQuestions: 150\` (current: ${input.maxQuestions ?? 30})
+- Max questions: \`maxQuestions: 200\` (current: ${input.maxQuestions ?? 30})
 - Organic results only: use \`search_serp\`
 - Dig into a result: use \`extract_url\` on any organic URL`;
   const full = `# PAA Report: "${input.query}"${input.location ? ` \xB7 ${input.location}` : ""}
 
 ${paaTable}${serpTable}${entityIdsSection(entityIds)}${aiSection}${statsLine}${debugSection(diagnostics?.debug)}${tips}`;
-  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) {
@@ -467,18 +550,6 @@ ${localRows}` : "";
   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) {
@@ -589,15 +660,19 @@ ${broken.map((u) => `- ${u.url} (${u.status})`).join("\n")}` : "",
 - 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);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      startUrl: d.startUrl ?? input.url,
+      totalFound: d.totalFound ?? urls.length,
+      truncated: d.truncated === true,
+      okCount: ok.length,
+      redirectCount: redirects.length,
+      brokenCount: broken.length,
+      urls: urls.map((u) => ({ url: u.url, status: u.status ?? null })),
+      durationMs: d.durationMs ?? 0
+    }
+  };
 }
 function formatExtractSite(raw, input) {
   const parsed = parseData(raw);
@@ -622,13 +697,6 @@ ${pageRows}`,
 - 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) {
@@ -659,16 +727,22 @@ ${videoRows}`,
 - 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);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      mode: input.mode,
+      videoCount: videos.length,
+      channel: d.channelMeta ? { title: d.channelMeta.title ?? null, subscriberCount: d.channelMeta.subscriberCount ?? null } : null,
+      videos: videos.map((v) => ({
+        videoId: String(v.videoId ?? ""),
+        title: String(v.title ?? ""),
+        channelName: v.channelName ?? null,
+        views: v.views ?? null,
+        duration: v.duration ?? null,
+        url: v.url ?? null
+      }))
+    }
+  };
 }
 function formatYoutubeTranscribe(raw, input) {
   const parsed = parseData(raw);
@@ -698,14 +772,6 @@ ${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) {
@@ -734,19 +800,26 @@ ${adBlocks}`,
 - 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);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      advertiserName: d.advertiserName ?? null,
+      totalAds: s.totalAds ?? 0,
+      activeCount: s.activeCount ?? 0,
+      videoCount: s.videoCount ?? 0,
+      imageCount: s.imageCount ?? 0,
+      ads: ads.map((ad) => ({
+        libraryId: ad.libraryId ?? null,
+        status: ad.status ?? null,
+        creativeType: ad.creativeType ?? null,
+        headline: ad.headline ?? null,
+        cta: ad.cta ?? null,
+        startDate: ad.startDate ?? null,
+        videoUrl: ad.videoUrl ?? null,
+        variations: typeof ad.variations === "number" ? ad.variations : null
+      }))
+    }
+  };
 }
 function formatFacebookAdSearch(raw, input) {
   const parsed = parseData(raw);
@@ -770,15 +843,18 @@ ${rows}`,
 - 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);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      query: input.query,
+      advertiserCount: advertisers.length,
+      advertisers: advertisers.map((a) => ({
+        name: a.pageName ?? a.name ?? null,
+        adCount: typeof a.adCount === "number" ? a.adCount : null,
+        libraryId: a.sampleLibraryId ?? a.libraryId ?? null
+      }))
+    }
+  };
 }
 function formatCreditsInfo(raw, input) {
   const parsed = parseData(raw);
@@ -817,16 +893,58 @@ ${costRows}` : "",
 | 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 formatMapsSearch(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const results = d.results ?? [];
+  const searchQuery = d.searchQuery ?? [input.query, input.location].filter(Boolean).join(" ");
+  const requestedMax = d.requestedMaxResults ?? input.maxResults ?? 10;
+  const durationMs = d.durationMs;
+  const rows = results.map((r) => {
+    const rating = [r.rating, r.reviewCount ? `(${r.reviewCount})` : null].filter(Boolean).join(" ");
+    return `| ${r.position} | ${cell(r.name)} | ${cell(r.category)} | ${cell(rating)} | ${cell(r.address)} | ${r.cidDecimal ? `\`${r.cidDecimal}\`` : "\u2014"} | ${r.websiteUrl ? `[site](${r.websiteUrl})` : "\u2014"} | [maps](${r.placeUrl}) |`;
+  }).join("\n");
+  const metadataSection = results.length ? `
+## Candidate Metadata
+${results.map((r) => {
+    const meta = r.metadata?.length ? r.metadata.slice(0, 8).map((m) => `  - ${m}`).join("\n") : "  - none";
+    return `### ${r.position}. ${r.name}
+${meta}`;
+  }).join("\n\n")}` : "";
+  const full = [
+    `# Google Maps Search: "${searchQuery}"`,
+    `**Returned:** ${results.length} profile candidate${results.length === 1 ? "" : "s"} \xB7 **Requested max:** ${requestedMax} \xB7 **Limit:** 50`,
+    `
+## Results
+| # | Name | Category | Rating | Address | CID | Website | Maps |
+|---|------|----------|--------|---------|-----|---------|------|
+${rows}`,
+    metadataSection,
+    `
+---
+\u{1F4A1} **Next step:** use \`maps_place_intel\` with a selected business name and location to hydrate full hours, phone, review topics, and optional review cards.`,
+    durationMs != null ? `
+*Extracted in ${(durationMs / 1e3).toFixed(1)}s*` : null
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      query: d.query,
+      location: d.location ?? null,
+      searchQuery: d.searchQuery,
+      searchUrl: d.searchUrl,
+      extractedAt: d.extractedAt,
+      requestedMaxResults: requestedMax,
+      resultCount: results.length,
+      results,
+      durationMs: durationMs ?? 0
+    }
+  };
+}
 function formatMapsPlaceIntel(raw, input) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
@@ -924,19 +1042,6 @@ ${entitySection}` : null,
     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);
 }
@@ -968,67 +1073,112 @@ ${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(executor2) {
-  const server2 = new import_mcp.McpServer({ name: "mcp-scraper", version: "1.0.0" });
+function liveWebToolAnnotations(title) {
+  return {
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true
+  };
+}
+function buildPaaExtractorMcpServer(executor2, options = {}) {
+  const savesReports = options.savesReportsLocally !== false;
+  const reportNote = savesReports ? " Saves a full Markdown report locally." : " Reports are returned inline; no files are saved on this hosted endpoint.";
+  const withReportNote = (description) => `${description}${reportNote}`;
+  const server2 = new import_mcp.McpServer({ name: "mcp-scraper", version: PACKAGE_VERSION });
   server2.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
+    title: "Google PAA + SERP Harvest",
+    description: withReportNote('Best default tool for Google search research. Extracts People Also Ask questions plus answers/source URLs, organic SERP, local pack when present, entity IDs (CID/GCID/KG MID), and AI Overview. Infer the user language: split topic from location (e.g. "best hvac company in Denver CO" => query "best hvac company", location "Denver, CO", gl "us", hl "en"). Use maxQuestions 30 normally, 100-150 for "full", "deep", "all", or comprehensive research. Credits are charged by extracted question; unused request hold is refunded.'),
+    inputSchema: HarvestPaaInputSchema,
+    annotations: liveWebToolAnnotations("Google PAA + SERP Harvest")
   }, async (input) => formatHarvestPaa(await executor2.harvestPaa(input), input));
   server2.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
+    title: "Google SERP Lookup",
+    description: withReportNote("Fast Google SERP lookup without PAA expansion. Use when the user asks for rankings, organic results, local pack, quick SERP, or positions. Split topic from location and infer gl/hl from the user request."),
+    inputSchema: SearchSerpInputSchema,
+    annotations: liveWebToolAnnotations("Google SERP Lookup")
   }, async (input) => formatSearchSerp(await executor2.searchSerp(input), input));
   server2.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
+    title: "Single URL Extract",
+    description: withReportNote("Extract structured data from one public URL: page content as Markdown, heading structure, JSON-LD schema, entity details, NAP score, metadata, and missing schema fields. Use when the user provides a single URL or asks to inspect/scrape one page."),
+    inputSchema: ExtractUrlInputSchema,
+    annotations: liveWebToolAnnotations("Single URL Extract")
   }, async (input) => formatExtractUrl(await executor2.extractUrl(input), input));
   server2.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
+    title: "Site URL Map",
+    description: withReportNote("Map/crawl a public website to build a URL inventory with HTTP status codes, broken links, redirects, and site scope. Use before extract_site for audits or when the user asks for a sitemap/URL inventory."),
+    inputSchema: MapSiteUrlsInputSchema,
+    outputSchema: MapSiteUrlsOutputSchema,
+    annotations: liveWebToolAnnotations("Site URL Map")
   }, async (input) => formatMapSiteUrls(await executor2.mapSiteUrls(input), input));
   server2.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
+    title: "Multi-Page Site Extract",
+    description: withReportNote("Run multi-page extraction across a public website. Returns per-page titles, H1s, metadata, headings, schema/entity data, canonical URLs, and content. Use for website audits, competitor audits, and full-site extraction."),
+    inputSchema: ExtractSiteInputSchema,
+    annotations: liveWebToolAnnotations("Multi-Page Site Extract")
   }, async (input) => formatExtractSite(await executor2.extractSite(input), input));
   server2.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
+    title: "YouTube Video Harvest",
+    description: withReportNote('Harvest YouTube video metadata by search query or channel handle/ID/URL. Use mode "search" for keyword/topic requests and mode "channel" for @handles, channel IDs, or channel URLs. Returns titles, views, dates, durations, URLs, thumbnails, and videoIds for follow-up transcription.'),
+    inputSchema: YoutubeHarvestInputSchema,
+    outputSchema: YoutubeHarvestOutputSchema,
+    annotations: liveWebToolAnnotations("YouTube Video Harvest")
   }, async (input) => formatYoutubeHarvest(await 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 or infer it from a YouTube URL if the user provided one. Saves a full Markdown report locally.",
-    inputSchema: YoutubeTranscribeInputSchema
+    title: "YouTube Transcription",
+    description: withReportNote("Fetch and transcribe captions from a YouTube video. Returns full transcript, timestamped chunks, and word count. Pass a videoId from youtube_harvest results or infer it from a YouTube URL if the user provided one."),
+    inputSchema: YoutubeTranscribeInputSchema,
+    annotations: liveWebToolAnnotations("YouTube Transcription")
   }, async (input) => formatYoutubeTranscribe(await executor2.youtubeTranscribe(input), input));
   server2.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
+    title: "Facebook Advertiser Ad Intel",
+    description: withReportNote("Harvest ads from a Facebook advertiser. Returns ad copy, headlines, CTAs, creative type, status, landing URLs, and video URLs ready for transcription. Accepts pageId, libraryId, or a brand/advertiser name as query. Use after facebook_ad_search when possible."),
+    inputSchema: FacebookPageIntelInputSchema,
+    outputSchema: FacebookPageIntelOutputSchema,
+    annotations: liveWebToolAnnotations("Facebook Advertiser Ad Intel")
   }, async (input) => formatFacebookPageIntel(await executor2.facebookPageIntel(input), input));
   server2.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
+    title: "Facebook Ad Library Search",
+    description: withReportNote("Search Facebook Ad Library by brand, advertiser, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs. Use to discover competitors, then pass libraryId to facebook_page_intel."),
+    inputSchema: FacebookAdSearchInputSchema,
+    outputSchema: FacebookAdSearchOutputSchema,
+    annotations: liveWebToolAnnotations("Facebook Ad Library Search")
   }, async (input) => formatFacebookAdSearch(await executor2.facebookAdSearch(input), input));
   server2.registerTool("facebook_ad_transcribe", {
+    title: "Facebook Ad Transcription",
     description: "Transcribe audio from a Facebook ad video. Returns full transcript and timestamped chunks. Use the videoUrl value from facebook_page_intel results.",
-    inputSchema: FacebookAdTranscribeInputSchema
+    inputSchema: FacebookAdTranscribeInputSchema,
+    annotations: liveWebToolAnnotations("Facebook Ad Transcription")
   }, 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, 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
+    title: "Google Maps Business Profile Details",
+    description: withReportNote('Extract Google Maps business intelligence for one known/named business: rating, review count, category, address, phone, website, hours, booking URL, review histogram, review topics, about attributes, entity IDs, and optional review cards. Do not use this for category searches, local market prospect lists, or requests for multiple GMB/GBP profiles; use maps_search first for those. Split business name from location (e.g. "Elite Roofing Denver CO" => businessName "Elite Roofing", location "Denver, CO"). Pass includeReviews true when the user asks for reviews/customer pain.'),
+    inputSchema: MapsPlaceIntelInputSchema,
+    annotations: liveWebToolAnnotations("Google Maps Business Profile Details")
   }, async (input) => formatMapsPlaceIntel(await executor2.mapsPlaceIntel(input), input));
+  server2.registerTool("maps_search", {
+    title: "Google Maps Business Search",
+    description: withReportNote('Search Google Maps for multiple businesses/profiles by category, niche, keyword, or local market. Use this when the user asks for several Google Business Profiles, GMBs, GBPs, leads, prospects, competitors, or "more than the 3-pack." Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, and profile metadata. Default maxResults is 10; maximum is 50. Use maps_place_intel afterward only when a selected business needs full details and reviews.'),
+    inputSchema: MapsSearchInputSchema,
+    outputSchema: MapsSearchOutputSchema,
+    annotations: liveWebToolAnnotations("Google Maps Business Search")
+  }, async (input) => formatMapsSearch(await executor2.mapsSearch(input), input));
   server2.registerTool("credits_info", {
+    title: "MCP Scraper Credits & Costs",
     description: "Answer questions about MCP Scraper credits: current credit balance, what a specific tool/action costs, the full cost table, and optionally recent credit ledger entries. Does not expose payment methods or credit card information.",
-    inputSchema: CreditsInfoInputSchema
+    inputSchema: CreditsInfoInputSchema,
+    annotations: {
+      title: "MCP Scraper Credits & Costs",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
   }, async (input) => formatCreditsInfo(await executor2.creditsInfo(input), input));
   return server2;
 }