mcp-scraper 0.1.5 → 0.1.7

package/dist/bin/api-server.cjs

@@ -3468,9 +3468,9 @@ async function extractKpo(opts) {
           redirect: "manual"
         });
         if (res.status >= 300 && res.status < 400) {
-          const location = res.headers.get("location");
-          if (!location) return null;
-          const next = new URL(location, target).href;
+          const location2 = res.headers.get("location");
+          if (!location2) return null;
+          const next = new URL(location2, target).href;
           const checkedRedirect = await validatePublicHttpUrl(next, { field: "redirect URL" });
           if (checkedRedirect.error || !checkedRedirect.parsed) return null;
           target = checkedRedirect.parsed.href;
@@ -8216,6 +8216,7 @@ var init_rates = __esm({
       yt_channel: 50,
       yt_transcription: 200,
       fb_ad: 50,
+      maps_search: 2e3,
       maps_place: 2e3,
       maps_review: 50,
       fb_search: 50,
@@ -8277,6 +8278,14 @@ var init_rates = __esm({
         credits: mcToCredits(MC_COSTS.fb_ad),
         unit: "per call"
       },
+      {
+        key: "maps_search",
+        label: "Maps business search",
+        aliases: ["maps_search", "google maps search", "gmb search", "gbp search", "business profiles"],
+        credits: mcToCredits(MC_COSTS.maps_search),
+        unit: "per search",
+        notes: "Returns up to 50 Google Maps business/profile candidates. Use maps_place_intel to hydrate selected businesses."
+      },
       {
         key: "maps_place",
         label: "Maps business lookup",
@@ -8338,6 +8347,7 @@ var init_rates = __esm({
       TRANSCRIPTION_REFUND: "transcription_refund",
       YT_CHANNEL: "yt_channel",
       FB_AD: "fb_ad",
+      MAPS_SEARCH: "maps_search",
       MAPS_PLACE: "maps_place",
       MAPS_REVIEW: "maps_review",
       MAPS_REVIEW_REFUND: "maps_review_refund",
@@ -11034,9 +11044,9 @@ function proxyName(country, state, city) {
 function zipProxyName(zip) {
   return `mcp-serp-residential-us-zip-${zip}`;
 }
-function parseKernelLocationProxyTarget(location, gl) {
-  if (!location || gl.toLowerCase() !== "us") return null;
-  const canonicalLocation = normalizeLocation(location);
+function parseKernelLocationProxyTarget(location2, gl) {
+  if (!location2 || gl.toLowerCase() !== "us") return null;
+  const canonicalLocation = normalizeLocation(location2);
   let parts = canonicalLocation.split(",").map((part) => part.trim()).filter(Boolean);
   if (parts.length > 1 && isUnitedStates(parts[parts.length - 1])) {
     parts = parts.slice(0, -1);
@@ -11687,7 +11697,7 @@ var init_facebook_ad_routes = __esm({
 });
 
 // src/schemas.ts
-var import_zod16, HarvestOptionsSchema, MapsPlaceOptionsSchema, RawPAAItemSchema, RawMapsOverviewSchema, RawMapsHoursRowSchema, RawMapsReviewStatsSchema, RawMapsReviewCardSchema, RawMapsAboutAttributeSchema;
+var import_zod16, HarvestOptionsSchema, MapsPlaceOptionsSchema, MapsSearchOptionsSchema, RawPAAItemSchema, RawMapsOverviewSchema, RawMapsHoursRowSchema, RawMapsReviewStatsSchema, RawMapsReviewCardSchema, RawMapsAboutAttributeSchema;
 var init_schemas3 = __esm({
   "src/schemas.ts"() {
     "use strict";
@@ -11725,6 +11735,16 @@ var init_schemas3 = __esm({
       kernelProxyId: import_zod16.z.string().optional(),
       headless: import_zod16.z.boolean().default(true)
     });
+    MapsSearchOptionsSchema = import_zod16.z.object({
+      query: import_zod16.z.string().min(1),
+      location: import_zod16.z.string().optional(),
+      gl: import_zod16.z.string().length(2).default("us"),
+      hl: import_zod16.z.string().length(2).default("en"),
+      maxResults: import_zod16.z.number().int().min(1).max(50).default(10),
+      kernelApiKey: import_zod16.z.string().optional(),
+      kernelProxyId: import_zod16.z.string().optional(),
+      headless: import_zod16.z.boolean().default(true)
+    });
     RawPAAItemSchema = import_zod16.z.object({
       question: import_zod16.z.string().min(1),
       answer: import_zod16.z.string().optional(),
@@ -11785,8 +11805,8 @@ var init_MapsNavigator = __esm({
         this.page = page;
       }
       page;
-      async navigateToPlacePage(businessName, location) {
-        const query = `${businessName} ${location}`;
+      async navigateToPlacePage(businessName, location2) {
+        const query = `${businessName} ${location2}`;
         const searchUrl = `https://www.google.com/maps/search/${encodeURIComponent(query)}`;
         await this.page.goto(searchUrl, { waitUntil: "domcontentloaded", timeout: 45e3 });
         const onPlacePage = await this.page.evaluate(() => /\/maps\/place\//.test(window.location.href));
@@ -12230,7 +12250,172 @@ var init_MapsExtractor = __esm({
   }
 });
 
+// src/extractor/MapsSearchExtractor.ts
+var MAPS_SEARCH_SCROLL_BUDGET_MS, MAPS_SEARCH_SCROLL_STEP_MS, MAPS_SEARCH_MAX_NO_GROWTH_ROUNDS, MapsSearchExtractor;
+var init_MapsSearchExtractor = __esm({
+  "src/extractor/MapsSearchExtractor.ts"() {
+    "use strict";
+    init_errors();
+    MAPS_SEARCH_SCROLL_BUDGET_MS = 6e4;
+    MAPS_SEARCH_SCROLL_STEP_MS = 1200;
+    MAPS_SEARCH_MAX_NO_GROWTH_ROUNDS = 4;
+    MapsSearchExtractor = class {
+      constructor(driver) {
+        this.driver = driver;
+      }
+      driver;
+      async extract(options) {
+        const startMs = Date.now();
+        const searchQuery = [options.query, options.location].filter(Boolean).join(" ");
+        const searchUrl = `https://www.google.com/maps/search/${encodeURIComponent(searchQuery)}?hl=${encodeURIComponent(options.hl)}`;
+        const config = {
+          headless: options.headless,
+          kernelApiKey: options.kernelApiKey,
+          kernelProxyId: options.kernelProxyId,
+          viewport: { width: 1280, height: 900 },
+          locale: `${options.hl}-${options.gl.toUpperCase()}`
+        };
+        try {
+          await this.driver.launch(config);
+          const page = this.driver.getPage();
+          await page.goto(searchUrl, { waitUntil: "domcontentloaded", timeout: 6e4 });
+          await page.waitForTimeout(3e3);
+          const blocked = await this.detectBlock(page);
+          if (blocked) throw new CaptchaError(RECAPTCHA_INSTRUCTIONS);
+          const results = await this.collectResults(page, options.maxResults);
+          return {
+            query: options.query,
+            location: options.location ?? null,
+            searchQuery,
+            searchUrl,
+            extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            requestedMaxResults: options.maxResults,
+            resultCount: results.length,
+            results,
+            durationMs: Date.now() - startMs
+          };
+        } finally {
+          await this.driver.close();
+        }
+      }
+      async detectBlock(page) {
+        return page.evaluate(() => {
+          const text = document.body.innerText.slice(0, 2e3);
+          return /unusual traffic|captcha|recaptcha|about this page/i.test(text) || /\/sorry\//.test(location.href);
+        });
+      }
+      async collectResults(page, maxResults) {
+        const seen = /* @__PURE__ */ new Map();
+        const started = Date.now();
+        let noGrowthRounds = 0;
+        while (Date.now() - started < MAPS_SEARCH_SCROLL_BUDGET_MS) {
+          const before = seen.size;
+          const batch = await this.extractVisibleResults(page);
+          for (const result of batch) {
+            const key = this.resultKey(result);
+            if (!seen.has(key)) seen.set(key, { ...result, position: seen.size + 1 });
+            if (seen.size >= maxResults) break;
+          }
+          if (seen.size >= maxResults) break;
+          if (seen.size === before) noGrowthRounds += 1;
+          else noGrowthRounds = 0;
+          if (noGrowthRounds >= MAPS_SEARCH_MAX_NO_GROWTH_ROUNDS) break;
+          await page.evaluate(() => {
+            const feed = document.querySelector('[role="feed"]');
+            if (feed) {
+              feed.scrollTop = feed.scrollHeight;
+            } else {
+              window.scrollTo(0, document.body.scrollHeight);
+            }
+          });
+          await page.waitForTimeout(MAPS_SEARCH_SCROLL_STEP_MS);
+        }
+        return [...seen.values()].slice(0, maxResults);
+      }
+      resultKey(result) {
+        return result.cidDecimal ?? result.placeUrl.replace(/[?&].*$/, "") ?? result.name;
+      }
+      async extractVisibleResults(page) {
+        return page.evaluate(() => {
+          function normalizeText(value) {
+            const text = value?.replace(/\s+/g, " ").trim() ?? "";
+            return text || null;
+          }
+          function cidFromUrl(url) {
+            const fid = url.match(/!1s(0x[0-9a-f]+):(0x[0-9a-f]+)/i);
+            if (!fid) return { cid: null, cidDecimal: null };
+            let cidDecimal = null;
+            try {
+              cidDecimal = BigInt(fid[2]).toString();
+            } catch {
+            }
+            return { cid: `${fid[1]}:${fid[2]}`, cidDecimal };
+          }
+          function textParts(card) {
+            if (!card) return [];
+            const parts = [];
+            card.querySelectorAll("div, span").forEach((el2) => {
+              const text = Array.from(el2.childNodes).filter((node) => node.nodeType === 3).map((node) => node.textContent?.trim() ?? "").filter((text2) => text2.length > 1 && text2.length < 140).join(" ");
+              if (text && !parts.includes(text)) parts.push(text);
+            });
+            return parts;
+          }
+          function firstMatching(parts, pattern) {
+            const value = parts.find((part) => pattern.test(part));
+            return value ?? null;
+          }
+          const out = [];
+          const seen = /* @__PURE__ */ new Set();
+          const anchors = Array.from(document.querySelectorAll('a[href*="/maps/place/"]'));
+          for (const anchor of anchors) {
+            const placeUrl = anchor.href;
+            const stableUrl = placeUrl.replace(/[?&].*$/, "");
+            if (seen.has(stableUrl)) continue;
+            seen.add(stableUrl);
+            const card = anchor.closest('.Nv2PK, [role="article"], .bfdHYd') ?? anchor.parentElement;
+            const parts = textParts(card);
+            const aria = normalizeText(anchor.getAttribute("aria-label"));
+            const heading = normalizeText(card?.querySelector('.qBF1Pd, .fontHeadlineSmall, [role="heading"]')?.textContent);
+            const name = aria ?? heading ?? parts[0] ?? stableUrl;
+            const links = Array.from(card?.querySelectorAll("a[href]") ?? []);
+            const websiteUrl = links.find((link) => link.href.startsWith("http") && !link.href.includes("google."))?.href ?? null;
+            const directionsUrl = links.find((link) => /google\.[^/]+\/maps\/dir|\/dir\//i.test(link.href))?.href ?? null;
+            const rating = firstMatching(parts, /^\d(?:\.\d)?$/);
+            const reviewCountRaw = firstMatching(parts, /^\(?[\d,]+\)?$/);
+            const category = parts.find((part) => !/^\d(?:\.\d)?$|^\(?[\d,]+\)?$|open|closed|directions|website/i.test(part)) ?? null;
+            const address = parts.find((part) => /\b[A-Z]{2}\s+\d{5}\b|\b(?:St|Street|Ave|Avenue|Rd|Road|Blvd|Drive|Dr)\b/i.test(part)) ?? null;
+            const { cid, cidDecimal } = cidFromUrl(placeUrl);
+            out.push({
+              position: out.length + 1,
+              name,
+              placeUrl,
+              cid,
+              cidDecimal,
+              rating,
+              reviewCount: reviewCountRaw ? reviewCountRaw.replace(/[()]/g, "") : null,
+              category,
+              address,
+              websiteUrl,
+              directionsUrl,
+              metadata: parts.slice(0, 20)
+            });
+          }
+          return out;
+        });
+      }
+    };
+  }
+});
+
 // src/api/maps-routes.ts
+function mapsErrorResponse(c, msg, errorCode) {
+  const blocked = msg.includes("CAPTCHA") || msg.includes("blocked");
+  return c.json({
+    error: sanitizeVendorName(msg),
+    error_code: blocked ? "captcha_or_blocked" : errorCode,
+    retryable: blocked
+  }, blocked ? 503 : 500);
+}
 var import_hono5, mapsApp;
 var init_maps_routes = __esm({
   "src/api/maps-routes.ts"() {
@@ -12239,10 +12424,59 @@ var init_maps_routes = __esm({
     init_db();
     init_rates();
     init_MapsExtractor();
+    init_MapsSearchExtractor();
     init_BrowserDriver();
     init_schemas3();
     init_api_auth();
+    init_errors();
     mapsApp = new import_hono5.Hono();
+    mapsApp.post("/search", createApiKeyAuth(), async (c) => {
+      const user = c.get("user");
+      const body = await c.req.json().catch(() => ({}));
+      const parsed = MapsSearchOptionsSchema.safeParse({
+        kernelApiKey: process.env.KERNEL_API_KEY,
+        ...body
+      });
+      if (!parsed.success) {
+        return c.json({ error: parsed.error.issues[0]?.message ?? "Invalid request" }, 400);
+      }
+      const { ok, balance_mc } = await debitMc(
+        user.id,
+        MC_COSTS.maps_search,
+        LedgerOperation.MAPS_SEARCH,
+        [parsed.data.query, parsed.data.location].filter(Boolean).join(" ")
+      );
+      if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.maps_search), 402);
+      const driver = new BrowserDriver();
+      const extractor = new MapsSearchExtractor(driver);
+      try {
+        const result = await extractor.extract(parsed.data);
+        await logRequestEvent({
+          userId: user.id,
+          source: "maps_search",
+          status: "done",
+          query: result.searchQuery,
+          location: parsed.data.location,
+          resultCount: result.resultCount,
+          result
+        });
+        return c.json(result);
+      } catch (err) {
+        await creditMc(user.id, MC_COSTS.maps_search, LedgerOperation.REFUND, "failed maps_search call");
+        const msg = err instanceof Error ? err.message : String(err);
+        await logRequestEvent({
+          userId: user.id,
+          source: "maps_search",
+          status: "failed",
+          query: [parsed.data.query, parsed.data.location].filter(Boolean).join(" "),
+          location: parsed.data.location,
+          error: msg
+        });
+        return mapsErrorResponse(c, msg, "maps_search_failed");
+      } finally {
+        await driver.close();
+      }
+    });
     mapsApp.post("/place", createApiKeyAuth(), async (c) => {
       const user = c.get("user");
       const body = await c.req.json().catch(() => ({}));
@@ -12309,10 +12543,7 @@ var init_maps_routes = __esm({
           location: parsed.data.location,
           error: msg
         });
-        if (msg.includes("CAPTCHA") || msg.includes("blocked")) {
-          return c.json({ error: msg }, 503);
-        }
-        return c.json({ error: msg }, 500);
+        return mapsErrorResponse(c, msg, "maps_place_failed");
       } finally {
         await driver.close();
       }
@@ -12670,8 +12901,19 @@ function addCandidate(candidates, city, region, example) {
   }
   candidates.set(key, { city: normalizedCity, regionCode, count: 1, examples: [example] });
 }
+function decodeSerpText(text) {
+  try {
+    return decodeURIComponent(text);
+  } catch {
+  }
+  try {
+    return decodeURIComponent(text.replace(/%(?![0-9a-fA-F]{2})/g, "%25"));
+  } catch {
+    return text;
+  }
+}
 function scanText(candidates, text) {
-  const normalized = decodeURIComponent(text).replace(/[+/|_-]+/g, " ");
+  const normalized = decodeSerpText(text).replace(/[+/|_-]+/g, " ");
   for (const match of normalized.matchAll(CITY_STATE_RE)) {
     addCandidate(candidates, match[1] ?? "", match[2] ?? "", normalized.slice(0, 180));
   }
@@ -14952,8 +15194,17 @@ var init_serp_intelligence_routes = __esm({
   }
 });
 
+// src/version.ts
+var PACKAGE_VERSION;
+var init_version = __esm({
+  "src/version.ts"() {
+    "use strict";
+    PACKAGE_VERSION = "0.1.7";
+  }
+});
+
 // src/mcp/mcp-tool-schemas.ts
-var import_zod19, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, MapsPlaceIntelInputSchema, CreditsInfoInputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
+var import_zod19, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, NullableString, MapsSearchOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, CreditsInfoInputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
 var init_mcp_tool_schemas = __esm({
   "src/mcp/mcp-tool-schemas.ts"() {
     "use strict";
@@ -14961,7 +15212,7 @@ var init_mcp_tool_schemas = __esm({
     HarvestPaaInputSchema = {
       query: import_zod19.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_zod19.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_zod19.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_zod19.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_zod19.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_zod19.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_zod19.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
@@ -15018,6 +15269,93 @@ var init_mcp_tool_schemas = __esm({
       includeReviews: import_zod19.z.boolean().default(false).describe("Whether to fetch individual review cards"),
       maxReviews: import_zod19.z.number().int().min(1).max(500).default(50).describe("Max review cards to return (requires includeReviews: true)")
     };
+    MapsSearchInputSchema = {
+      query: import_zod19.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_zod19.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_zod19.z.string().length(2).default("us").describe("Google country code inferred from location."),
+      hl: import_zod19.z.string().length(2).default("en").describe("Language inferred from user request."),
+      maxResults: import_zod19.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.")
+    };
+    NullableString = import_zod19.z.string().nullable();
+    MapsSearchOutputSchema = {
+      query: import_zod19.z.string(),
+      location: import_zod19.z.string().nullable(),
+      searchQuery: import_zod19.z.string(),
+      searchUrl: import_zod19.z.string().url(),
+      extractedAt: import_zod19.z.string(),
+      requestedMaxResults: import_zod19.z.number().int().min(1).max(50),
+      resultCount: import_zod19.z.number().int().min(0).max(50),
+      results: import_zod19.z.array(import_zod19.z.object({
+        position: import_zod19.z.number().int().min(1),
+        name: import_zod19.z.string(),
+        placeUrl: import_zod19.z.string().url(),
+        cid: NullableString,
+        cidDecimal: NullableString,
+        rating: NullableString,
+        reviewCount: NullableString,
+        category: NullableString,
+        address: NullableString,
+        websiteUrl: NullableString,
+        directionsUrl: NullableString,
+        metadata: import_zod19.z.array(import_zod19.z.string())
+      })),
+      durationMs: import_zod19.z.number().int().min(0)
+    };
+    MapSiteUrlsOutputSchema = {
+      startUrl: import_zod19.z.string(),
+      totalFound: import_zod19.z.number().int().min(0),
+      truncated: import_zod19.z.boolean(),
+      okCount: import_zod19.z.number().int().min(0),
+      redirectCount: import_zod19.z.number().int().min(0),
+      brokenCount: import_zod19.z.number().int().min(0),
+      urls: import_zod19.z.array(import_zod19.z.object({
+        url: import_zod19.z.string(),
+        status: import_zod19.z.number().int().nullable()
+      })),
+      durationMs: import_zod19.z.number().min(0)
+    };
+    YoutubeHarvestOutputSchema = {
+      mode: import_zod19.z.string(),
+      videoCount: import_zod19.z.number().int().min(0),
+      channel: import_zod19.z.object({
+        title: NullableString,
+        subscriberCount: NullableString
+      }).nullable(),
+      videos: import_zod19.z.array(import_zod19.z.object({
+        videoId: import_zod19.z.string(),
+        title: import_zod19.z.string(),
+        channelName: NullableString,
+        views: NullableString,
+        duration: NullableString,
+        url: NullableString
+      }))
+    };
+    FacebookAdSearchOutputSchema = {
+      query: import_zod19.z.string(),
+      advertiserCount: import_zod19.z.number().int().min(0),
+      advertisers: import_zod19.z.array(import_zod19.z.object({
+        name: NullableString,
+        adCount: import_zod19.z.number().int().nullable(),
+        libraryId: NullableString
+      }))
+    };
+    FacebookPageIntelOutputSchema = {
+      advertiserName: NullableString,
+      totalAds: import_zod19.z.number().int().min(0),
+      activeCount: import_zod19.z.number().int().min(0),
+      videoCount: import_zod19.z.number().int().min(0),
+      imageCount: import_zod19.z.number().int().min(0),
+      ads: import_zod19.z.array(import_zod19.z.object({
+        libraryId: NullableString,
+        status: NullableString,
+        creativeType: NullableString,
+        headline: NullableString,
+        cta: NullableString,
+        startDate: NullableString,
+        videoUrl: NullableString,
+        variations: import_zod19.z.number().int().nullable()
+      }))
+    };
     CreditsInfoInputSchema = {
       item: import_zod19.z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", or "YouTube transcription"'),
       includeLedger: import_zod19.z.boolean().default(false).describe("Whether to include recent credit ledger entries")
@@ -15066,6 +15404,14 @@ var init_mcp_tool_schemas = __esm({
 });
 
 // src/mcp/mcp-response-formatter.ts
+function configureReportSaving(enabled) {
+  reportSavingEnabled = enabled;
+}
+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";
 }
@@ -15077,7 +15423,7 @@ function outputBaseDir() {
   return process.env.MCP_SCRAPER_OUTPUT_DIR?.trim() || (0, import_node_path6.join)((0, import_node_os3.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_fs4.mkdirSync)(outDir, { recursive: true });
@@ -15090,7 +15436,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_path6.join)(outputBaseDir(), "screenshots");
     (0, import_node_fs4.mkdirSync)(dir, { recursive: true });
@@ -15130,11 +15476,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" };
   }
 }
@@ -15148,15 +15494,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;
@@ -15186,7 +15523,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 : [];
@@ -15240,26 +15577,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) {
@@ -15298,18 +15621,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) {
@@ -15420,15 +15731,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);
@@ -15453,13 +15768,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) {
@@ -15490,16 +15798,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);
@@ -15529,14 +15843,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) {
@@ -15565,19 +15871,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);
@@ -15601,15 +15914,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);
@@ -15648,16 +15964,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 };
@@ -15755,19 +16113,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);
 }
@@ -15799,76 +16144,123 @@ ${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);
 }
-var import_node_fs4, import_node_os3, import_node_path6;
+var import_node_fs4, import_node_os3, import_node_path6, reportSavingEnabled;
 var init_mcp_response_formatter = __esm({
   "src/mcp/mcp-response-formatter.ts"() {
     "use strict";
     import_node_fs4 = require("fs");
     import_node_os3 = require("os");
     import_node_path6 = require("path");
+    init_errors();
+    reportSavingEnabled = true;
   }
 });
 
 // src/mcp/paa-mcp-server.ts
-function buildPaaExtractorMcpServer(executor) {
-  const server = 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(executor, options = {}) {
+  const savesReports = options.savesReportsLocally !== false;
+  const reportNote = savesReports ? " Saves a full Markdown report locally." : " Reports are returned inline; no files are saved on this hosted endpoint.";
+  const withReportNote = (description) => `${description}${reportNote}`;
+  const server = new import_mcp.McpServer({ name: "mcp-scraper", version: PACKAGE_VERSION });
   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
+    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 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
+    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 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
+    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 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
+    title: "Site URL Map",
+    description: withReportNote("Map/crawl a public website to build a URL inventory with HTTP status codes, broken links, redirects, and site scope. Use before extract_site for audits or when the user asks for a sitemap/URL inventory."),
+    inputSchema: MapSiteUrlsInputSchema,
+    outputSchema: MapSiteUrlsOutputSchema,
+    annotations: liveWebToolAnnotations("Site URL Map")
   }, async (input) => formatMapSiteUrls(await executor.mapSiteUrls(input), input));
   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
+    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 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
+    title: "YouTube Video Harvest",
+    description: withReportNote('Harvest YouTube video metadata by search query or channel handle/ID/URL. Use mode "search" for keyword/topic requests and mode "channel" for @handles, channel IDs, or channel URLs. Returns titles, views, dates, durations, URLs, thumbnails, and videoIds for follow-up transcription.'),
+    inputSchema: YoutubeHarvestInputSchema,
+    outputSchema: YoutubeHarvestOutputSchema,
+    annotations: liveWebToolAnnotations("YouTube Video Harvest")
   }, async (input) => formatYoutubeHarvest(await executor.youtubeHarvest(input), input));
   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
+    title: "YouTube Transcription",
+    description: withReportNote("Fetch and transcribe captions from a YouTube video. Returns full transcript, timestamped chunks, and word count. Pass a videoId from youtube_harvest results or infer it from a YouTube URL if the user provided one."),
+    inputSchema: YoutubeTranscribeInputSchema,
+    annotations: liveWebToolAnnotations("YouTube Transcription")
   }, async (input) => formatYoutubeTranscribe(await executor.youtubeTranscribe(input), input));
   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
+    title: "Facebook Advertiser Ad Intel",
+    description: withReportNote("Harvest ads from a Facebook advertiser. Returns ad copy, headlines, CTAs, creative type, status, landing URLs, and video URLs ready for transcription. Accepts pageId, libraryId, or a brand/advertiser name as query. Use after facebook_ad_search when possible."),
+    inputSchema: FacebookPageIntelInputSchema,
+    outputSchema: FacebookPageIntelOutputSchema,
+    annotations: liveWebToolAnnotations("Facebook Advertiser Ad Intel")
   }, async (input) => formatFacebookPageIntel(await executor.facebookPageIntel(input), input));
   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
+    title: "Facebook Ad Library Search",
+    description: withReportNote("Search Facebook Ad Library by brand, advertiser, competitor, niche, or keyword. Returns advertisers with ad counts and library IDs. Use to discover competitors, then pass libraryId to facebook_page_intel."),
+    inputSchema: FacebookAdSearchInputSchema,
+    outputSchema: FacebookAdSearchOutputSchema,
+    annotations: liveWebToolAnnotations("Facebook Ad Library Search")
   }, async (input) => formatFacebookAdSearch(await executor.facebookAdSearch(input), input));
   server.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 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
+    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 executor.mapsPlaceIntel(input), input));
+  server.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 executor.mapsSearch(input), input));
   server.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 executor.creditsInfo(input), input));
   return server;
 }
@@ -15877,6 +16269,7 @@ var init_paa_mcp_server = __esm({
   "src/mcp/paa-mcp-server.ts"() {
     "use strict";
     import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+    init_version();
     init_mcp_tool_schemas();
     init_mcp_response_formatter();
   }
@@ -15976,6 +16369,9 @@ var init_http_mcp_tool_executor = __esm({
       mapsPlaceIntel(input) {
         return this.call("/maps/place", input);
       }
+      mapsSearch(input) {
+        return this.call("/maps/search", input);
+      }
       creditsInfo(input) {
         return this.call("/billing/credits", input);
       }
@@ -16015,15 +16411,18 @@ async function requireMcpCallerKey(c) {
   return callerKey;
 }
 function registerSerpIntelligenceCaptureTools(server, executor) {
-  const serpExecutor = executor;
   server.registerTool("capture_serp_snapshot", {
+    title: "SERP Intelligence Snapshot",
     description: "Capture a structured SERP Intelligence Google snapshot through POST /serp-intelligence/capture, the same product capture path used by Phoenix. Split query from location, infer gl/hl, use proxyMode location for localized residential proxy evidence, configured for the static residential proxy, and none only for direct-network debugging. Set debug true when investigating location evidence, proxy behavior, CAPTCHA, or capture reliability.",
-    inputSchema: CaptureSerpSnapshotInputSchema
-  }, async (input) => serpExecutor.captureSerpSnapshot ? serpExecutor.captureSerpSnapshot(input) : Promise.resolve({ content: [{ type: "text", text: "{}" }], isError: true }));
+    inputSchema: CaptureSerpSnapshotInputSchema,
+    annotations: liveWebToolAnnotations("SERP Intelligence Snapshot")
+  }, async (input) => executor.captureSerpSnapshot(input));
   server.registerTool("capture_serp_page_snapshots", {
+    title: "SERP Intelligence Page Snapshots",
     description: "Capture public ranking-page evidence through POST /serp-intelligence/page-snapshots, the same product page snapshot path used by Phoenix. Provide urls for simple captures or targets when preserving organic, AI citation, local-pack, configured target, or site-subject source metadata. Private IPs, localhost, file URLs, and internal URLs are rejected by the service. Use timeoutMs for slow pages and debug true for sanitized proxy/browser diagnostics.",
-    inputSchema: CaptureSerpPageSnapshotsInputSchema
-  }, async (input) => serpExecutor.captureSerpPageSnapshots ? serpExecutor.captureSerpPageSnapshots(input) : Promise.resolve({ content: [{ type: "text", text: "{}" }], isError: true }));
+    inputSchema: CaptureSerpPageSnapshotsInputSchema,
+    annotations: liveWebToolAnnotations("SERP Intelligence Page Snapshots")
+  }, async (input) => executor.captureSerpPageSnapshots(input));
 }
 var import_hono7, import_webStandardStreamableHttp, mcpApp;
 var init_mcp_routes = __esm({
@@ -16033,8 +16432,10 @@ var init_mcp_routes = __esm({
     import_webStandardStreamableHttp = require("@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js");
     init_paa_mcp_server();
     init_http_mcp_tool_executor();
+    init_mcp_response_formatter();
     init_db();
     init_mcp_tool_schemas();
+    configureReportSaving(false);
     mcpApp = new import_hono7.Hono();
     mcpApp.all("/", async (c) => {
       try {
@@ -16047,7 +16448,7 @@ var init_mcp_routes = __esm({
           sessionIdGenerator: void 0,
           enableJsonResponse: true
         });
-        const server = buildPaaExtractorMcpServer(executor);
+        const server = buildPaaExtractorMcpServer(executor, { savesReportsLocally: false });
         registerSerpIntelligenceCaptureTools(server, executor);
         await server.connect(transport);
         return transport.handleRequest(c.req.raw);