mcp-scraper 0.1.6 → 0.1.8

package/dist/bin/api-server.cjs

@@ -50,6 +50,109 @@ var init_harvest_timeout = __esm({
   }
 });
 
+// src/lib/browser-service-env.ts
+function browserServiceApiKey() {
+  const value = (process.env.BROWSER_SERVICE_API_KEY ?? process.env.KERNEL_API_KEY)?.trim();
+  return value || void 0;
+}
+function browserServiceProxyId() {
+  const value = (process.env.BROWSER_SERVICE_PROXY_ID ?? process.env.KERNEL_PROXY_ID)?.trim();
+  return value || void 0;
+}
+var init_browser_service_env = __esm({
+  "src/lib/browser-service-env.ts"() {
+    "use strict";
+  }
+});
+
+// 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();
+}
+var RECAPTCHA_INSTRUCTIONS, CaptchaError, ExtractionError, RequestAbortedError;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    "use strict";
+    RECAPTCHA_INSTRUCTIONS = "Google returned a CAPTCHA. Run with --headless=false to re-warm the browser profile, then retry.";
+    CaptchaError = class extends Error {
+      constructor(instructions) {
+        super(`CAPTCHA detected. ${instructions}`);
+        this.instructions = instructions;
+      }
+      instructions;
+      name = "CaptchaError";
+    };
+    ExtractionError = class extends Error {
+      constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+      }
+      cause;
+      name = "ExtractionError";
+    };
+    RequestAbortedError = class extends Error {
+      name = "RequestAbortedError";
+      constructor(message = "Request aborted before harvest completed") {
+        super(message);
+      }
+    };
+  }
+});
+
+// src/api/outbound-sanitize.ts
+function sanitizeOutboundDiagnostics(value, parentKey = "") {
+  if (typeof value === "string") {
+    if (SANITIZED_VALUE_KEYS.test(parentKey) && /kernel/i.test(value)) {
+      return sanitizeVendorName(value);
+    }
+    return value;
+  }
+  if (Array.isArray(value)) return value.map((v) => sanitizeOutboundDiagnostics(v, parentKey));
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+      const renamed = KEY_RENAMES[key] ?? key;
+      out[renamed] = sanitizeOutboundDiagnostics(val, key);
+    }
+    return out;
+  }
+  return value;
+}
+function sanitizeAttempts(attempts) {
+  return attempts.map((a) => sanitizeOutboundDiagnostics(a));
+}
+function sanitizeHarvestResult(result) {
+  const diagnostics = result?.diagnostics;
+  if (!diagnostics?.debug) return result;
+  return {
+    ...result,
+    diagnostics: {
+      ...diagnostics,
+      debug: sanitizeOutboundDiagnostics(diagnostics.debug)
+    }
+  };
+}
+var KEY_RENAMES, SANITIZED_VALUE_KEYS;
+var init_outbound_sanitize = __esm({
+  "src/api/outbound-sanitize.ts"() {
+    "use strict";
+    init_errors();
+    KEY_RENAMES = {
+      kernel: "browserRuntime",
+      kernel_session_id: "browser_session_id",
+      kernel_delete_started: "session_cleanup_started",
+      kernel_delete_succeeded: "session_cleanup_succeeded",
+      kernel_delete_error: "session_cleanup_error",
+      kernelSessionId: "browserSessionId",
+      kernelDeleteStarted: "sessionCleanupStarted",
+      kernelDeleteSucceeded: "sessionCleanupSucceeded",
+      kernelDeleteError: "sessionCleanupError",
+      kernelProxyId: "proxyId"
+    };
+    SANITIZED_VALUE_KEYS = /error|message/i;
+  }
+});
+
 // src/blog/registry.ts
 var posts;
 var init_registry = __esm({
@@ -3425,7 +3528,7 @@ var init_url_utils = __esm({
 
 // src/api/kernel-fetch.ts
 async function fetchWithKernel(url) {
-  const apiKey = process.env.KERNEL_API_KEY;
+  const apiKey = browserServiceApiKey();
   if (!apiKey) throw new Error("Browser backend API key not set");
   const client = new import_sdk.default({ apiKey });
   const kb = await client.browsers.create({ stealth: true, timeout_seconds: 60 });
@@ -3450,6 +3553,7 @@ var init_kernel_fetch = __esm({
   "src/api/kernel-fetch.ts"() {
     "use strict";
     import_sdk = __toESM(require("@onkernel/sdk"), 1);
+    init_browser_service_env();
     import_playwright = require("playwright");
   }
 });
@@ -3468,9 +3572,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 +8320,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 +8382,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 +8451,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",
@@ -8484,40 +8598,6 @@ var init_selectors = __esm({
   }
 });
 
-// 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();
-}
-var RECAPTCHA_INSTRUCTIONS, CaptchaError, ExtractionError, RequestAbortedError;
-var init_errors = __esm({
-  "src/errors.ts"() {
-    "use strict";
-    RECAPTCHA_INSTRUCTIONS = "Google returned a CAPTCHA. Run with --headless=false to re-warm the browser profile, then retry.";
-    CaptchaError = class extends Error {
-      constructor(instructions) {
-        super(`CAPTCHA detected. ${instructions}`);
-        this.instructions = instructions;
-      }
-      instructions;
-      name = "CaptchaError";
-    };
-    ExtractionError = class extends Error {
-      constructor(message, cause) {
-        super(message);
-        this.cause = cause;
-      }
-      cause;
-      name = "ExtractionError";
-    };
-    RequestAbortedError = class extends Error {
-      name = "RequestAbortedError";
-      constructor(message = "Request aborted before harvest completed") {
-        super(message);
-      }
-    };
-  }
-});
-
 // src/driver/BrowserDriver.ts
 function positiveIntFromEnv(name, fallback) {
   const raw = process.env[name];
@@ -9499,7 +9579,7 @@ async function writeOutputs(result, outputDir) {
   }
 }
 async function ytHarvest(rawOptions) {
-  const kernelApiKey = process.env.KERNEL_API_KEY;
+  const kernelApiKey = browserServiceApiKey();
   if (!kernelApiKey) {
     throw new Error("A browser backend API key is required \u2014 YouTube harvesting requires a stealth session.");
   }
@@ -9533,6 +9613,7 @@ var init_youtube_harvest = __esm({
   "src/youtube/youtube-harvest.ts"() {
     "use strict";
     import_node_fs2 = require("fs");
+    init_browser_service_env();
     import_node_path4 = __toESM(require("path"), 1);
     import_papaparse = __toESM(require("papaparse"), 1);
     init_schemas2();
@@ -9610,7 +9691,7 @@ function parseTimedtextXml(xml) {
   return results;
 }
 async function fetchViaKernelInnertube(videoId) {
-  const kernelApiKey = process.env.KERNEL_API_KEY;
+  const kernelApiKey = browserServiceApiKey();
   if (!kernelApiKey) return null;
   const driver = new BrowserDriver();
   const start = Date.now();
@@ -9753,7 +9834,7 @@ async function attemptKernelWhisper(videoId, kernelApiKey, falKey, start) {
   }
 }
 async function fetchViaKernelWhisper(videoId) {
-  const kernelApiKey = process.env.KERNEL_API_KEY;
+  const kernelApiKey = browserServiceApiKey();
   const falKey = process.env.FAL_KEY;
   if (!kernelApiKey || !falKey) return null;
   const start = Date.now();
@@ -9793,6 +9874,7 @@ var init_CaptionFetcher = __esm({
   "src/youtube/CaptionFetcher.ts"() {
     "use strict";
     init_BrowserDriver();
+    init_browser_service_env();
     import_client2 = require("@fal-ai/client");
     WHISPER_RECORD_SECONDS = 90;
   }
@@ -10034,6 +10116,7 @@ var init_screenshot_routes = __esm({
   "src/api/screenshot-routes.ts"() {
     "use strict";
     import_hono3 = require("hono");
+    init_browser_service_env();
     import_zod14 = require("zod");
     init_screenshot();
     init_api_auth();
@@ -10068,7 +10151,7 @@ var init_screenshot_routes = __esm({
         }
         const device2 = body.device === "mobile" ? "mobile" : "desktop";
         try {
-          const buf = await captureScreenshot(parsedFallback.href, process.env.KERNEL_API_KEY?.trim(), device2);
+          const buf = await captureScreenshot(parsedFallback.href, browserServiceApiKey(), device2);
           return new Response(new Uint8Array(buf), {
             status: 200,
             headers: {
@@ -10084,7 +10167,7 @@ var init_screenshot_routes = __esm({
       }
       const device = body.device === "mobile" ? "mobile" : "desktop";
       try {
-        const buf = await captureScreenshot(urlCheck.parsed.href, process.env.KERNEL_API_KEY?.trim(), device);
+        const buf = await captureScreenshot(urlCheck.parsed.href, browserServiceApiKey(), device);
         return new Response(new Uint8Array(buf), {
           status: 200,
           headers: {
@@ -11034,9 +11117,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);
@@ -11369,29 +11452,30 @@ function buildPageIntelUrl(body, country) {
   return `https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=${country}&q=${encodeURIComponent(body.query.trim())}&search_type=keyword_unordered`;
 }
 function kernelLaunchOpts() {
-  return { headless: true, kernelApiKey: process.env.KERNEL_API_KEY?.trim(), kernelProxyId: process.env.KERNEL_PROXY_ID?.trim(), viewport: { width: 1280, height: 900 }, locale: "en-US" };
+  return { headless: true, kernelApiKey: browserServiceApiKey(), kernelProxyId: browserServiceProxyId(), viewport: { width: 1280, height: 900 }, locale: "en-US" };
 }
 async function kernelLaunchOptsResidential() {
-  let proxyId = process.env.KERNEL_PROXY_ID?.trim();
+  let proxyId = browserServiceProxyId();
   try {
     const resolution2 = await resolveKernelProxyId({
-      kernelApiKey: process.env.KERNEL_API_KEY?.trim(),
+      kernelApiKey: browserServiceApiKey(),
       proxyMode: "location",
-      configuredKernelProxyId: process.env.KERNEL_PROXY_ID?.trim(),
+      configuredKernelProxyId: browserServiceProxyId(),
       location: "New York, NY",
       gl: "us"
     });
     if (resolution2.kernelProxyId) proxyId = resolution2.kernelProxyId;
   } catch {
-    proxyId = process.env.KERNEL_PROXY_ID?.trim();
+    proxyId = browserServiceProxyId();
   }
-  return { headless: true, kernelApiKey: process.env.KERNEL_API_KEY?.trim(), kernelProxyId: proxyId, viewport: { width: 1280, height: 900 }, locale: "en-US" };
+  return { headless: true, kernelApiKey: browserServiceApiKey(), kernelProxyId: proxyId, viewport: { width: 1280, height: 900 }, locale: "en-US" };
 }
 var import_hono4, import_zod15, import_client3, FacebookAdBodySchema, FacebookPageIntelBodySchema, FacebookTranscribeBodySchema, FacebookSearchBodySchema, FacebookMediaBodySchema, facebookAdApp, ALLOWED_MEDIA_HOSTS;
 var init_facebook_ad_routes = __esm({
   "src/api/facebook-ad-routes.ts"() {
     "use strict";
     import_hono4 = require("hono");
+    init_browser_service_env();
     import_zod15 = require("zod");
     init_db();
     init_rates();
@@ -11687,7 +11771,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 +11809,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 +11879,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 +12324,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 +12498,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 +12617,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 +12975,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));
   }
@@ -14079,8 +14395,8 @@ async function harvest(rawOptions) {
   const onAttemptEvent = getAttemptLogSink(rawOptions);
   const requestedProxyMode = raw.proxyMode;
   const proxyMode = requestedProxyMode === "none" ? "none" : requestedProxyMode === "configured" ? "configured" : "location";
-  const kernelApiKey = typeof raw.kernelApiKey === "string" ? raw.kernelApiKey.trim() : process.env.KERNEL_API_KEY?.trim();
-  const configuredKernelProxyId = typeof raw.kernelProxyId === "string" ? raw.kernelProxyId.trim() : process.env.KERNEL_PROXY_ID?.trim();
+  const kernelApiKey = typeof raw.kernelApiKey === "string" ? raw.kernelApiKey.trim() : browserServiceApiKey();
+  const configuredKernelProxyId = typeof raw.kernelProxyId === "string" ? raw.kernelProxyId.trim() : browserServiceProxyId();
   const proxyOpts = {
     kernelApiKey,
     proxyMode,
@@ -14267,6 +14583,7 @@ var init_harvest = __esm({
   "src/harvest.ts"() {
     "use strict";
     init_schemas3();
+    init_browser_service_env();
     init_BrowserDriver();
     init_PAAExtractor();
     init_OutputSerializer();
@@ -14691,8 +15008,8 @@ async function captureSerpIntelligenceSnapshot(rawInput, runtimeOptions = {}) {
       debug,
       serpOnly: true,
       headless: runtimeOptions.headless ?? true,
-      kernelApiKey: runtimeOptions.kernelApiKey ?? process.env.KERNEL_API_KEY?.trim(),
-      kernelProxyId: runtimeOptions.kernelProxyId ?? process.env.KERNEL_PROXY_ID?.trim(),
+      kernelApiKey: runtimeOptions.kernelApiKey ?? browserServiceApiKey(),
+      kernelProxyId: runtimeOptions.kernelProxyId ?? browserServiceProxyId(),
       format: "json",
       outputDir: runtimeOptions.outputDir ?? "/tmp/serp-intelligence-output",
       signal: runtimeOptions.signal,
@@ -14703,7 +15020,7 @@ async function captureSerpIntelligenceSnapshot(rawInput, runtimeOptions = {}) {
     const pageSnapshotLimit = normalizePageSnapshotLimit(parsedInput);
     const pageSnapshotTargets = collectPageSnapshotTargets(harvestResult, pageSnapshotLimit);
     const pageSnapshotArtifacts = pageSnapshotTargets.length > 0 ? (await capturePageSnapshotsFn(pageSnapshotTargets, {
-      kernelApiKey: runtimeOptions.kernelApiKey ?? process.env.KERNEL_API_KEY?.trim(),
+      kernelApiKey: runtimeOptions.kernelApiKey ?? browserServiceApiKey(),
       timeoutMs: runtimeOptions.pageSnapshotTimeoutMs,
       maxConcurrency: runtimeOptions.pageSnapshotMaxConcurrency,
       debug,
@@ -14725,6 +15042,7 @@ var init_serp_capture_service = __esm({
   "src/serp-intelligence/serp-capture-service.ts"() {
     "use strict";
     init_harvest();
+    init_browser_service_env();
     init_harvest_problems();
     init_page_snapshot_extractor();
     init_schemas4();
@@ -14829,6 +15147,7 @@ var init_serp_intelligence_routes = __esm({
   "src/api/serp-intelligence-routes.ts"() {
     "use strict";
     import_hono6 = require("hono");
+    init_browser_service_env();
     init_page_snapshot_extractor();
     init_serp_capture_service();
     init_schemas4();
@@ -14861,8 +15180,8 @@ var init_serp_intelligence_routes = __esm({
       if (!ok) return c.json(insufficientBalanceResponse(balance_mc, cost), 402);
       try {
         const result = await captureSerpIntelligenceSnapshot(parsed.data, {
-          kernelApiKey: process.env.KERNEL_API_KEY?.trim(),
-          kernelProxyId: process.env.KERNEL_PROXY_ID?.trim(),
+          kernelApiKey: browserServiceApiKey(),
+          kernelProxyId: browserServiceProxyId(),
           signal: c.req.raw.signal,
           billing: { creditsUsed: cost / 1e3 }
         });
@@ -14917,7 +15236,7 @@ var init_serp_intelligence_routes = __esm({
       if (!ok) return c.json(insufficientBalanceResponse(balance_mc, cost), 402);
       try {
         const result = await capturePageSnapshots(targets, {
-          kernelApiKey: process.env.KERNEL_API_KEY?.trim(),
+          kernelApiKey: browserServiceApiKey(),
           timeoutMs: parsed.data.timeoutMs,
           maxConcurrency: parsed.data.maxConcurrency,
           debug: parsed.data.debug
@@ -14952,8 +15271,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.8";
+  }
+});
+
 // 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, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, CreditsInfoInputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
 var init_mcp_tool_schemas = __esm({
   "src/mcp/mcp-tool-schemas.ts"() {
     "use strict";
@@ -15018,6 +15346,207 @@ 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)
+    };
+    OrganicResultOutput = import_zod19.z.object({
+      position: import_zod19.z.number().int(),
+      title: import_zod19.z.string(),
+      url: import_zod19.z.string(),
+      domain: import_zod19.z.string(),
+      snippet: NullableString
+    });
+    AiOverviewOutput = import_zod19.z.object({
+      detected: import_zod19.z.boolean(),
+      text: NullableString
+    }).nullable();
+    EntityIdsOutput = import_zod19.z.object({
+      kgIds: import_zod19.z.array(import_zod19.z.string()),
+      cids: import_zod19.z.array(import_zod19.z.string()),
+      gcids: import_zod19.z.array(import_zod19.z.string())
+    }).nullable();
+    HarvestPaaOutputSchema = {
+      query: import_zod19.z.string(),
+      location: NullableString,
+      questionCount: import_zod19.z.number().int().min(0),
+      completionStatus: NullableString,
+      questions: import_zod19.z.array(import_zod19.z.object({
+        question: import_zod19.z.string(),
+        answer: NullableString,
+        sourceTitle: NullableString,
+        sourceSite: NullableString
+      })),
+      organicResults: import_zod19.z.array(OrganicResultOutput),
+      aiOverview: AiOverviewOutput,
+      entityIds: EntityIdsOutput,
+      durationMs: import_zod19.z.number().min(0).nullable()
+    };
+    SearchSerpOutputSchema = {
+      query: import_zod19.z.string(),
+      location: NullableString,
+      organicResults: import_zod19.z.array(OrganicResultOutput),
+      localPack: import_zod19.z.array(import_zod19.z.object({
+        position: import_zod19.z.number().int(),
+        name: import_zod19.z.string(),
+        rating: NullableString,
+        reviewCount: NullableString,
+        websiteUrl: NullableString
+      })),
+      aiOverview: AiOverviewOutput,
+      entityIds: EntityIdsOutput
+    };
+    ExtractUrlOutputSchema = {
+      url: import_zod19.z.string(),
+      title: NullableString,
+      headings: import_zod19.z.array(import_zod19.z.object({
+        level: import_zod19.z.number().int(),
+        text: import_zod19.z.string()
+      })),
+      schemaBlockCount: import_zod19.z.number().int().min(0),
+      entityName: NullableString,
+      entityTypes: import_zod19.z.array(import_zod19.z.string()),
+      napScore: import_zod19.z.number().nullable(),
+      missingSchemaFields: import_zod19.z.array(import_zod19.z.string()),
+      screenshotSaved: NullableString
+    };
+    ExtractSiteOutputSchema = {
+      url: import_zod19.z.string(),
+      pageCount: import_zod19.z.number().int().min(0),
+      pages: import_zod19.z.array(import_zod19.z.object({
+        url: import_zod19.z.string(),
+        title: NullableString,
+        schemaTypes: import_zod19.z.array(import_zod19.z.string())
+      })),
+      durationMs: import_zod19.z.number().min(0)
+    };
+    MapsPlaceIntelOutputSchema = {
+      name: import_zod19.z.string(),
+      rating: NullableString,
+      reviewCount: NullableString,
+      category: NullableString,
+      address: NullableString,
+      phone: NullableString,
+      website: NullableString,
+      hoursSummary: NullableString,
+      bookingUrl: NullableString,
+      kgmid: NullableString,
+      cidDecimal: NullableString,
+      cidUrl: NullableString,
+      lat: import_zod19.z.number().nullable(),
+      lng: import_zod19.z.number().nullable(),
+      reviewsStatus: import_zod19.z.string(),
+      reviewsCollected: import_zod19.z.number().int().min(0),
+      reviewTopics: import_zod19.z.array(import_zod19.z.object({
+        label: import_zod19.z.string(),
+        count: import_zod19.z.string()
+      }))
+    };
+    CreditsInfoOutputSchema = {
+      balanceCredits: import_zod19.z.number().nullable(),
+      matchedCost: import_zod19.z.object({
+        label: import_zod19.z.string(),
+        credits: import_zod19.z.number(),
+        unit: import_zod19.z.string(),
+        notes: NullableString
+      }).nullable(),
+      costs: import_zod19.z.array(import_zod19.z.object({
+        key: import_zod19.z.string(),
+        label: import_zod19.z.string(),
+        credits: import_zod19.z.number(),
+        unit: import_zod19.z.string(),
+        notes: NullableString
+      })),
+      ledger: import_zod19.z.array(import_zod19.z.object({
+        createdAt: import_zod19.z.string(),
+        operation: import_zod19.z.string(),
+        credits: import_zod19.z.number(),
+        description: NullableString
+      }))
+    };
+    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 +15595,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 +15614,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 +15627,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 +15667,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 +15685,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;
@@ -15168,7 +15696,7 @@ function debugSection(debug) {
   if (!debug || typeof debug !== "object") return "";
   const request = debug.request ?? {};
   const browser = debug.browser ?? {};
-  const kernel = browser.kernel ?? {};
+  const kernel = browser.browserRuntime ?? browser.kernel ?? {};
   const network = browser.networkLocation ?? {};
   const nav = browser.serpNavigation ?? {};
   const proxyResolution = kernel.proxyResolution ?? {};
@@ -15186,7 +15714,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 : [];
@@ -15194,12 +15722,14 @@ function errorAttemptsSection(body) {
   const lines = attempts.slice(0, 5).map((attempt) => {
     const debug = attempt.debug ?? {};
     const browser = debug.browser ?? {};
-    const kernel = browser.kernel ?? {};
+    const kernel = browser.browserRuntime ?? browser.kernel ?? {};
     const proxyResolution = kernel.proxyResolution ?? {};
     const network = browser.networkLocation ?? {};
     const nav = browser.serpNavigation ?? {};
     const geo = [network.ip, network.city, network.region].filter(Boolean).join(" / ") || "geo unknown";
-    return `- Attempt ${attempt.attempt_number ?? "?"}: ${attempt.outcome ?? attempt.status ?? "unknown"} \xB7 session ${attempt.kernel_session_id ?? kernel.sessionId ?? "unknown"} \xB7 proxy ${debug.request?.proxyMode ?? kernel.proxyMode ?? "unknown"}${proxyResolution.source ? `/${proxyResolution.source}` : ""} \xB7 ${geo} \xB7 CAPTCHA ${nav.captchaDetected === true ? "yes" : nav.captchaDetected === false ? "no" : "unknown"} \xB7 deleted ${attempt.kernel_delete_succeeded === true ? "yes" : attempt.kernel_delete_succeeded === false ? "no" : "unknown"}`;
+    const sessionId = attempt.browser_session_id ?? attempt.kernel_session_id ?? kernel.sessionId ?? "unknown";
+    const cleanupSucceeded2 = attempt.session_cleanup_succeeded ?? attempt.kernel_delete_succeeded;
+    return `- Attempt ${attempt.attempt_number ?? "?"}: ${attempt.outcome ?? attempt.status ?? "unknown"} \xB7 session ${sessionId} \xB7 proxy ${debug.request?.proxyMode ?? kernel.proxyMode ?? "unknown"}${proxyResolution.source ? `/${proxyResolution.source}` : ""} \xB7 ${geo} \xB7 CAPTCHA ${nav.captchaDetected === true ? "yes" : nav.captchaDetected === false ? "no" : "unknown"} \xB7 cleanup ${cleanupSucceeded2 === true ? "yes" : cleanupSucceeded2 === false ? "no" : "unknown"}`;
   });
   return `
 
@@ -15240,27 +15770,37 @@ ${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);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      query: input.query,
+      location: input.location ?? null,
+      questionCount: flat.length,
+      completionStatus: diagnostics?.completionStatus ?? null,
+      questions: flat.map((r) => ({
+        question: String(r.question ?? ""),
+        answer: r.answer ?? null,
+        sourceTitle: r.source_title ?? null,
+        sourceSite: r.source_site ?? null
+      })),
+      organicResults: organic.map((r) => ({
+        position: Number(r.position) || 0,
+        title: String(r.title ?? ""),
+        url: String(r.url ?? ""),
+        domain: String(r.domain ?? ""),
+        snippet: r.snippet ?? null
+      })),
+      aiOverview: aiOvw ? { detected: aiOvw.detected === true, text: aiOvw.text ?? null } : null,
+      entityIds: entityIds ? { kgIds: entityIds.kgIds ?? [], cids: entityIds.cids ?? [], gcids: entityIds.gcids ?? [] } : null,
+      durationMs: durationMs ?? null
+    }
+  };
 }
 function formatSearchSerp(raw, input) {
   const parsed = parseData(raw);
@@ -15298,19 +15838,29 @@ ${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);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      query: input.query,
+      location: input.location ?? null,
+      organicResults: organic.map((r) => ({
+        position: Number(r.position) || 0,
+        title: String(r.title ?? ""),
+        url: String(r.url ?? ""),
+        domain: String(r.domain ?? ""),
+        snippet: r.snippet ?? null
+      })),
+      localPack: localPack.map((b) => ({
+        position: Number(b.position) || 0,
+        name: String(b.name ?? ""),
+        rating: b.rating ?? null,
+        reviewCount: b.reviewCount ?? null,
+        websiteUrl: b.websiteUrl ?? null
+      })),
+      aiOverview: aiOvw ? { detected: aiOvw.detected === true, text: aiOvw.text ?? null } : null,
+      entityIds: entityIds ? { kgIds: entityIds.kgIds ?? [], cids: entityIds.cids ?? [], gcids: entityIds.gcids ?? [] } : null
+    }
+  };
 }
 function formatExtractUrl(raw, input) {
   const parsed = parseData(raw);
@@ -15379,15 +15929,27 @@ ${bodyMd.slice(0, 3e3)}${bodyMd.length > 3e3 ? "\n\n*(truncated)*" : ""}` : "";
 **${title}**
 ${headingSection}${kpoSection}${brandingSection}${bodySection}${screenshotSection}${mediaSection}${tips}`;
   const textResult = oneBlock(full);
+  const structuredContent = {
+    url,
+    title: d.title ?? null,
+    headings: headings.map((h) => ({ level: Number(h.level) || 0, text: String(h.text ?? "") })),
+    schemaBlockCount: schemaCount,
+    entityName: kpo?.entityName ?? null,
+    entityTypes: kpo?.type ?? [],
+    napScore: kpo?.napScore ?? null,
+    missingSchemaFields: kpo?.missingFields ?? [],
+    screenshotSaved: screenshotPath ?? null
+  };
   if (screenshotMeta?.base64) {
     return {
       content: [
         ...textResult.content,
         { type: "image", data: screenshotMeta.base64, mimeType: "image/png" }
-      ]
+      ],
+      structuredContent
     };
   }
-  return textResult;
+  return { ...textResult, structuredContent };
 }
 function formatMapSiteUrls(raw, input) {
   const parsed = parseData(raw);
@@ -15420,15 +15982,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,14 +16019,19 @@ ${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);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      url: input.url,
+      pageCount: pages.length,
+      pages: pages.map((p) => ({
+        url: String(p.url ?? ""),
+        title: p.title ?? null,
+        schemaTypes: p.kpo?.type ?? []
+      })),
+      durationMs: d.durationMs ?? 0
+    }
+  };
 }
 function formatYoutubeHarvest(raw, input) {
   const parsed = parseData(raw);
@@ -15490,16 +16061,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 +16106,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 +16134,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 +16177,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);
@@ -15649,14 +16228,75 @@ ${costRows}` : "",
 |------|-----------|---------|-------------|
 ${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
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      balanceCredits: typeof balance === "number" ? balance : null,
+      matchedCost: matched ? { label: matched.label, credits: matched.credits, unit: matched.unit, notes: matched.notes ?? null } : null,
+      costs: costs.map((c) => ({
+        key: c.key,
+        label: c.label,
+        credits: c.credits,
+        unit: c.unit,
+        notes: c.notes ?? null
+      })),
+      ledger: ledger.map((row) => ({
+        createdAt: String(row.created_at ?? ""),
+        operation: String(row.operation ?? ""),
+        credits: row.amount_mc / 1e3,
+        description: row.description ?? null
+      }))
+    }
+  };
+}
+function formatMapsSearch(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const results = d.results ?? [];
+  const 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);
+  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);
@@ -15756,20 +16396,28 @@ ${entitySection}` : 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);
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      name,
+      rating: rating ?? null,
+      reviewCount: reviewCount ?? null,
+      category: category ?? null,
+      address: address ?? null,
+      phone: phone ?? null,
+      website: website ?? null,
+      hoursSummary: hoursSummary ?? null,
+      bookingUrl: bookingUrl ?? null,
+      kgmid: kgmid ?? null,
+      cidDecimal: cidDecimal ?? null,
+      cidUrl: cidUrl ?? null,
+      lat: lat ?? null,
+      lng: lng ?? null,
+      reviewsStatus,
+      reviewsCollected: reviews.length,
+      reviewTopics: topics.map((t) => ({ label: String(t.label ?? ""), count: String(t.count ?? "") }))
+    }
+  };
 }
 function formatFacebookAdTranscribe(raw, input) {
   const parsed = parseData(raw);
@@ -15799,76 +16447,129 @@ ${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,
+    outputSchema: HarvestPaaOutputSchema,
+    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,
+    outputSchema: SearchSerpOutputSchema,
+    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,
+    outputSchema: ExtractUrlOutputSchema,
+    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,
+    outputSchema: ExtractSiteOutputSchema,
+    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,
+    outputSchema: MapsPlaceIntelOutputSchema,
+    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,
+    outputSchema: CreditsInfoOutputSchema,
+    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 +16578,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 +16678,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 +16720,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 +16741,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 +16757,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);
@@ -16432,7 +17142,7 @@ async function processJob(job) {
     const opts = typeof job.options === "string" ? JSON.parse(job.options) : job.options;
     const result = await harvest({
       ...opts,
-      kernelApiKey: process.env.KERNEL_API_KEY,
+      kernelApiKey: browserServiceApiKey(),
       headless: true,
       format: "json",
       outputDir: "/tmp/paa-output-api",
@@ -16497,6 +17207,7 @@ var init_worker = __esm({
   "src/api/worker.ts"() {
     "use strict";
     init_db();
+    init_browser_service_env();
     init_harvest();
     init_webhook();
     init_rates();
@@ -16599,6 +17310,8 @@ var init_server = __esm({
   "src/api/server.ts"() {
     "use strict";
     init_harvest_timeout();
+    init_browser_service_env();
+    init_outbound_sanitize();
     init_registry();
     init_template();
     init_og();
@@ -16915,7 +17628,7 @@ var init_server = __esm({
       try {
         const result = await harvest({
           ...options,
-          kernelApiKey: process.env.KERNEL_API_KEY?.trim(),
+          kernelApiKey: browserServiceApiKey(),
           headless: true,
           format: "json",
           outputDir: "/tmp/paa-output-api",
@@ -16930,7 +17643,7 @@ var init_server = __esm({
           if (diff > 0) await creditMc(user.id, diff, LedgerOperation.PAA_REFUND, "overestimate refund");
           else if (diff < 0) await debitMc(user.id, -diff, LedgerOperation.PAA, options.query);
         }
-        return c.json({ job_id: jobId, status: "done", result, attempts });
+        return c.json({ job_id: jobId, status: "done", result: sanitizeHarvestResult(result), attempts: sanitizeAttempts(attempts) });
       } catch (err) {
         const problem = classifyHarvestProblem(err);
         const response = harvestProblemResponse(problem);
@@ -16938,18 +17651,19 @@ var init_server = __esm({
         if (problem.terminalStatus === "cancelled" || c.req.raw.signal.aborted) {
           await cancelJob(jobId, serializeHarvestProblem(problem));
           await creditMc(user.id, syncCost, LedgerOperation.REFUND, "cancelled call");
-          return c.json({ job_id: jobId, status: "cancelled", ...response, attempts }, problem.httpStatus);
+          return c.json({ job_id: jobId, status: "cancelled", ...response, attempts: sanitizeAttempts(attempts) }, problem.httpStatus);
         }
         await failJob(jobId, serializeHarvestProblem(problem));
         await creditMc(user.id, syncCost, LedgerOperation.REFUND, "failed call");
-        return c.json({ job_id: jobId, status: "failed", ...response, attempts }, problem.httpStatus);
+        return c.json({ job_id: jobId, status: "failed", ...response, attempts: sanitizeAttempts(attempts) }, problem.httpStatus);
       }
     });
     app.get("/jobs/:id", auth, async (c) => {
       const job = await getJob(c.req.param("id"), c.get("user").id);
       if (!job) return c.json({ error: "Job not found" }, 404);
       const attempts = await listHarvestAttempts(job.id, c.get("user").id);
-      return c.json({ ...job, attempts });
+      const safeResult = job.result && typeof job.result === "object" ? sanitizeHarvestResult(job.result) : job.result;
+      return c.json({ ...job, result: safeResult, attempts: sanitizeAttempts(attempts) });
     });
     app.get("/jobs", auth, async (c) => {
       return c.json(await listJobs(c.get("user").id));
@@ -17048,7 +17762,7 @@ var init_server = __esm({
       const { ok: euOk, balance_mc: euBal } = await debitMc(user.id, MC_COSTS.page_scrape, LedgerOperation.EXTRACT_URL, new URL(canonicalUrl).hostname);
       if (!euOk) return c.json(insufficientBalanceResponse(euBal, MC_COSTS.page_scrape), 402);
       try {
-        const kernelApiKey = process.env.KERNEL_API_KEY?.trim();
+        const kernelApiKey = browserServiceApiKey();
         const device = screenshotDevice === "mobile" ? "mobile" : "desktop";
         const [result, pageData] = await Promise.all([
           extractKpo({ url: canonicalUrl, kernelApiKey }),
@@ -17086,7 +17800,7 @@ var init_server = __esm({
           startUrl: parsed.href,
           maxUrls: Math.min(2e3, Math.max(1, body.maxUrls ?? 500)),
           concurrency: Math.min(20, Math.max(1, body.concurrency ?? 12)),
-          kernelApiKey: body.browserFallback ?? body.kernelFallback ? process.env.KERNEL_API_KEY : void 0
+          kernelApiKey: body.browserFallback ?? body.kernelFallback ? browserServiceApiKey() : void 0
         });
         await logRequestEvent({
           userId: user.id,
@@ -17126,7 +17840,7 @@ var init_server = __esm({
         const result = await extractSite({
           startUrl: parsed.href,
           maxPages: Math.min(200, Math.max(1, body.maxPages ?? 100)),
-          kernelApiKey: body.browserFallback ?? body.kernelFallback ? process.env.KERNEL_API_KEY : void 0
+          kernelApiKey: body.browserFallback ?? body.kernelFallback ? browserServiceApiKey() : void 0
         });
         const pageCount = result.pages?.length ?? 1;
         const actualSiteMc = pageCount * MC_COSTS.page_scrape;