mcp-scraper 0.3.24 → 0.3.26

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

@@ -36,10 +36,10 @@ var CLIENT_OVER_SERVER_MARGIN_MS = 15e3;
 function harvestTimeoutBudget(maxQuestions, serpOnly = false) {
   const requested = Number.isFinite(maxQuestions) && maxQuestions > 0 ? Math.trunc(maxQuestions) : 30;
   let serverMs;
-  if (serpOnly || requested <= 50) serverMs = 11e4;
-  else if (requested <= 100) serverMs = 18e4;
-  else if (requested <= 150) serverMs = 24e4;
-  else serverMs = 28e4;
+  if (serpOnly) serverMs = 11e4;
+  else if (requested <= 50) serverMs = 17e4;
+  else if (requested <= 100) serverMs = 23e4;
+  else serverMs = 285e3;
   const clientMs = Math.min(serverMs + CLIENT_OVER_SERVER_MARGIN_MS, VERCEL_FUNCTION_MAX_MS - 5e3);
   return { serverMs, clientMs };
 }
@@ -261,6 +261,9 @@ var HttpMcpToolExecutor = class {
   facebookAdSearch(input) {
     return this.call("/facebook/search", input);
   }
+  redditThread(input) {
+    return this.call("/reddit/thread", input, this.httpTimeoutOverrideMs ?? 24e4);
+  }
   facebookAdTranscribe(input) {
     return this.call("/facebook/transcribe", input);
   }
@@ -456,7 +459,7 @@ render();
 }
 
 // src/version.ts
-var PACKAGE_VERSION = "0.3.24";
+var PACKAGE_VERSION = "0.3.26";
 
 // src/mcp/browser-agent-tool-schemas.ts
 var import_zod = require("zod");
@@ -1872,6 +1875,17 @@ var WORKFLOW_RECIPES = [
     produces: ["city summary", "competitor CSV", "review insight CSV", "market difficulty/opportunity notes", "HTML report"],
     runHint: "Use workflow_run with workflowId local-competitive-audit for state-wide market batches, or map-comparison for one city/location comparison."
   },
+  {
+    id: "lead_generation",
+    title: "Lead Generation",
+    description: "Build an outreach-ready local lead list for a niche in one market: Google Maps businesses with confirmed review counts and booking URLs, enriched with email and social links scraped from each business website (proxy/browser-backed so blocked sites still resolve).",
+    primaryWorkflowId: "get-leads",
+    recommendedTools: ["workflow_run", "maps_search", "maps_place_intel", "extract_url"],
+    requiredInputs: ["query", "location"],
+    optionalInputs: ["maxResults", "enrichWebsites", "hydrateReviewCounts", "concurrency", "proxyMode"],
+    produces: ["leads CSV (name, phone, website, email, socials, review count, booking URL)", "evidence JSON", "HTML report", "outreach task list"],
+    runHint: 'Use workflow_run with workflowId get-leads. Put the niche in query (e.g. "roofers") and the market in location (e.g. "Houston, TX"); do not combine them.'
+  },
   {
     id: "icp_research",
     title: "ICP Research",
@@ -2817,6 +2831,16 @@ ${bodyMd.slice(0, 3e3)}${bodyMd.length > 3e3 ? `
   const bodySectionFull = bodyMd ? `
 ## Page Content
 ${bodyMd}` : "";
+  const mem = d.memory ?? null;
+  const memSection = mem?.deposited ? `
+## \u2705 Saved to memory
+Full content stored in vault \`${mem.vault ?? "\u2014"}\` as note \`${mem.noteId ?? "\u2014"}\`${mem.chunks !== void 0 ? ` (${mem.chunks} chunks indexed)` : ""}. Recall it later with memory search \u2014 no need to re-scrape.` : mem?.fileUrl ? `
+## \u{1F4C4} Saved as a temporary file
+Memory vault was unavailable${mem.error ? ` (${mem.error})` : ""}, so the full content was saved to a download link instead:
+- **Link:** ${mem.fileUrl}
+- **Expires:** ${mem.fileExpiresAt ?? "in 24 hours"} (auto-deleted)` : mem ? `
+## \u26A0\uFE0F Memory deposit skipped
+${mem.error ?? "unknown error"} \u2014 the page content is still in the truncated preview above.` : "";
   const screenshotSection = screenshotMeta ? `
 ## Screenshot
 - **File:** ${screenshotPath ?? "(returned inline only \u2014 disk write unavailable in this environment)"}
@@ -2846,10 +2870,10 @@ ${bodyMd}` : "";
 - ${schemaCount} JSON-LD schema block(s) detected`;
   const full = `# URL Extract: ${url}
 **${title}**
-${headingSection}${kpoSection}${brandingSection}${bodySection}${screenshotSection}${mediaSection}${tips}`;
+${headingSection}${kpoSection}${brandingSection}${bodySection}${memSection}${screenshotSection}${mediaSection}${tips}`;
   const diskReport = `# URL Extract: ${url}
 **${title}**
-${headingSection}${kpoSection}${brandingSection}${bodySectionFull}${screenshotSection}${mediaSection}${tips}`;
+${headingSection}${kpoSection}${brandingSection}${bodySectionFull}${memSection}${screenshotSection}${mediaSection}${tips}`;
   const textResult = oneBlock(full, diskReport);
   const structuredContent = {
     url,
@@ -2862,7 +2886,8 @@ ${headingSection}${kpoSection}${brandingSection}${bodySectionFull}${screenshotSe
     missingSchemaFields: kpo?.missingFields ?? [],
     screenshotSaved: screenshotPath ?? null,
     branding: branding ?? null,
-    mediaAssets: media?.assets ?? null
+    mediaAssets: media?.assets ?? null,
+    memory: mem ?? void 0
   };
   if (screenshotMeta?.base64) {
     return {
@@ -3248,6 +3273,38 @@ ${adBlocks}`,
     }
   };
 }
+function formatRedditThread(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const d = parsed.data;
+  const comments = d.comments ?? [];
+  const commentMd = comments.map((cm) => {
+    const indent = "  ".repeat(Math.min(Number(cm.depth ?? 0), 6));
+    return `${indent}- **u/${cm.author || "[unknown]"}** (${cm.score || "\u2014"}): ${(cm.body || "").replace(/\s+/g, " ").trim()}`;
+  }).join("\n");
+  const full = [
+    `# ${d.title || "Reddit thread"}`,
+    `**u/${d.author || "[unknown]"}** \xB7 ${d.score || "\u2014"} \xB7 ${comments.length} comments captured`,
+    d.postBody ? `
+${d.postBody}` : "",
+    `
+## Comments
+${commentMd || "_No comments captured._"}`
+  ].join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      sourceUrl: d.sourceUrl ?? input.url ?? null,
+      oldRedditUrl: d.oldRedditUrl ?? null,
+      title: d.title ?? null,
+      author: d.author ?? null,
+      score: d.score ?? null,
+      postBody: d.postBody ?? null,
+      numComments: comments.length,
+      comments: comments.map((cm) => ({ author: cm.author ?? null, score: cm.score ?? null, depth: Number(cm.depth ?? 0), body: cm.body ?? "" }))
+    }
+  };
+}
 function formatFacebookAdSearch(raw, input) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
@@ -4179,33 +4236,73 @@ ${limitations.map((l) => `- ${l}`).join("\n")}` : "",
 
 // src/mcp/server-instructions.ts
 var SERVER_INSTRUCTIONS = `
-This server scrapes and analyzes web, social, search, maps, and site data. Pick a tool by NAME using
-this routing map, then load its schema before calling.
+# MCP Scraper
+
+Scrapes and analyzes web, search, maps, social, and site data. **Pick a tool by NAME from the map
+below, then load its schema before calling.** Where a tool needs a value another tool produces, the
+seam is noted so you can chain them.
+
+## Search & research
+- Organic Google results, rankings, local pack -> **search_serp**.
+- Full SERP plus People-Also-Ask and AI-Overview detail -> **harvest_paa**.
+- \`search_serp\` returns \`organicResults[].url\` (often including reddit.com threads) \u2014 feed those into
+  \`extract_url\` or \`reddit_thread\`.
+
+## Pages & sites
+- One page -> **extract_url** (takes a url).
+- Whole site, crawl + SEO report -> **extract_site** (takes a url).
+- Just the URL list/inventory -> **map_site_urls** (takes a url).
+- \`map_site_urls\` returns urls you can feed straight into \`extract_url\`.
+
+## Google Maps
+- Find multiple places/competitors/prospects -> **maps_search** (returns \`results[]\` with name,
+  placeUrl, cid).
+- One business deep-dive + reviews -> **maps_place_intel** (takes businessName + location, NOT an id \u2014
+  call it directly with a name from a \`maps_search\` result or from the user).
+
+## YouTube
+- Find or list videos -> **youtube_harvest** (returns \`videos[].videoId\`).
+- Transcribe one video -> **youtube_transcribe** (takes a videoId from \`youtube_harvest\`, or a url).
+
+## Facebook
+- Find advertisers -> **facebook_ad_search** (returns \`advertisers[]\` with pageId, libraryId).
+- One advertiser's ads -> **facebook_page_intel** (takes pageId, libraryId, or query; returns
+  \`ads[].videoUrl\`).
+- Transcribe an ad video -> **facebook_ad_transcribe** (takes a videoUrl from \`facebook_page_intel\`).
+- Transcribe an organic reel/video/post -> **facebook_video_transcribe** (takes the Facebook url directly).
+
+## Instagram
+- Profile inventory -> **instagram_profile_content** (returns post/reel/tv urls).
+- One post or reel -> **instagram_media_download** (takes a url from \`instagram_profile_content\`, or a
+  url the user gives).
 
-ROUTING
-- One web page -> extract_url. Whole site (crawl + SEO report) -> extract_site. Just the URL list -> map_site_urls.
-- Web search (organic SERP) -> search_serp. Full SERP + People-Also-Ask / AI-Overview detail -> harvest_paa.
-- Google Maps: find places -> maps_search; one place deep-dive + reviews -> maps_place_intel.
-- YouTube: find or list videos -> youtube_harvest; transcribe one video -> youtube_transcribe.
-- Facebook: find ads -> facebook_ad_search; transcribe an ad -> facebook_ad_transcribe; transcribe a
-  video -> facebook_video_transcribe; page profile/intel -> facebook_page_intel.
-- Instagram: profile inventory -> instagram_profile_content; one post or reel -> instagram_media_download.
-- Workflows (multi-step): local directory build -> directory_workflow; rank blueprint -> rank_tracker_workflow;
-  AI-answer citation fan-out (AEO) -> query_fanout_workflow; deep research -> deep_research_workflow.
-- Anything without a dedicated tool (e.g. Reddit, arbitrary logged-in sites) -> the browser_* agent
-  (browser_open, then navigate/read).
-- Logged-in sites (ChatGPT, Claude, Reddit, any account): save the login first -> browser_profile_connect
-  (returns an mcpscraper.dev sign-in link for the user; one profile holds MANY logins, call it again with
-  the same profile + a new domain to add accounts) -> poll browser_profile_list until AUTHENTICATED ->
-  browser_open with that profile. browser_profile_list also shows what a profile is connected to.
+## Reddit
+- A reddit.com thread/post URL -> **reddit_thread**. Returns the post plus its comment tree and handles
+  Reddit's bot wall itself (no login needed). Find threads first with \`search_serp\`.
 
-NOTES
-- Bulk / full-site crawls: call extract_site with rotateProxies:true for blocked or rate-limited sites.
-  It discovers URLs and returns a saved folder/artifact plus a summary, not the full content inline.
-- Tools that open a browser session or transcribe media cost credits and take longer. Prefer the
-  cheapest tool that answers the question (plain search/extract before browser agents).
-- Large results are saved to disk or an artifact and returned as a summary plus a path; read the path
-  for full detail rather than expecting the whole payload inline.
+## Other sites & logins (browser agent)
+For an arbitrary site or a logged-in dashboard with no dedicated tool, use the browser_* agent. **First
+decide whether the site needs a login:**
+- **Needs a login** (ChatGPT, Claude, any account) -> save it first: **browser_profile_connect** returns
+  an mcpscraper.dev sign-in link for the user; one profile holds MANY logins (call it again with the same
+  profile + a new domain to add accounts). Poll **browser_profile_list** until AUTHENTICATED, then
+  **browser_open** with that profile.
+- **No login** -> **browser_open**, then navigate/read.
+
+## Workflows
+Multi-step orchestrations \u2014 prefer these over hand-chaining primitives when the whole job is one of these:
+- Build a local business directory for a niche across a state/region -> **directory_workflow**.
+- Stand up a rank-tracking blueprint (database + cron + ingestion plan) -> **rank_tracker_workflow**.
+- Find which sources an AI answer cites for a query (AEO) -> **query_fanout_workflow** (open a browser
+  session on chatgpt.com or claude.ai FIRST, then run it against that session).
+
+## Notes
+- Bulk / full-site crawls: call \`extract_site\` with \`rotateProxies:true\` for blocked or rate-limited
+  sites. It returns a saved folder/artifact plus a summary, not the full content inline.
+- Browser sessions and media transcription cost credits and take longer \u2014 prefer the cheapest tool that
+  answers the question (plain search/extract before browser agents).
+- Large results are saved to disk or an artifact and returned as a summary plus a path; read the path for
+  full detail rather than expecting the whole payload inline.
 `.trim();
 
 // src/mcp/mcp-tool-schemas.ts
@@ -4213,7 +4310,7 @@ var import_zod3 = require("zod");
 
 // src/schemas.ts
 var import_zod2 = require("zod");
-var DEFAULT_PROXY_MODE = "configured";
+var DEFAULT_PROXY_MODE = "none";
 var DEFAULT_MAPS_PROXY_MODE = "location";
 var HarvestOptionsSchema = import_zod2.z.object({
   query: import_zod2.z.string().min(1),
@@ -4235,7 +4332,8 @@ var HarvestOptionsSchema = import_zod2.z.object({
   outputDir: import_zod2.z.string().default("./paa-output"),
   format: import_zod2.z.enum(["json", "csv", "both"]).default("both"),
   serpOnly: import_zod2.z.boolean().default(false),
-  pages: import_zod2.z.number().int().min(1).max(2).default(1)
+  pages: import_zod2.z.number().int().min(1).max(2).default(1),
+  softDeadlineMs: import_zod2.z.number().optional()
 });
 var MapsPlaceOptionsSchema = import_zod2.z.object({
   businessName: import_zod2.z.string().min(1),
@@ -4317,7 +4415,7 @@ var HarvestPaaInputSchema = {
   gl: import_zod3.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_zod3.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_zod3.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe("Proxy targeting mode. Default configured uses the service proxy without city/ZIP targeting for the highest general success rate. Use location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use none only for direct-network debugging."),
+  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe('Leave unset \u2014 routing is automatic (clean egress by default; residential only when a location is given, with fallback). Set "location" only to force local-pack targeting.'),
   proxyZip: import_zod3.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only with proxyMode location when the user gives a specific ZIP or city-center targeting needs to be forced."),
   debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior.")
 };
@@ -4328,7 +4426,9 @@ var ExtractUrlInputSchema = {
   extractBranding: import_zod3.z.boolean().default(false).describe("Extract brand colors, fonts, logo, and favicon using a rendered browser session. Returns colorScheme (light/dark), colors (primary/accent/background/text/heading as hex), fonts (heading/body family names), and assets (logo URL, favicon URL). Use when the user asks about brand colors, site theme, or brand assets."),
   downloadMedia: import_zod3.z.boolean().default(false).describe("Extract and download all page media (images, video, audio) to ~/Downloads/mcp-scraper/media/. Ad networks, tracking pixels, and noise URLs are filtered automatically. Use when the user asks to download or harvest assets from a page."),
   mediaTypes: import_zod3.z.array(import_zod3.z.enum(["image", "video", "audio"])).default(["image", "video", "audio"]).describe("Which media types to download. Default all three."),
-  allowLocal: import_zod3.z.boolean().default(false).describe("Allow localhost and private-network URLs. For local development only.")
+  allowLocal: import_zod3.z.boolean().default(false).describe("Allow localhost and private-network URLs. For local development only."),
+  depositToVault: import_zod3.z.boolean().default(false).describe("Also save the full page content into the user's MCP Memory Library vault, server-side. The complete body is stored and embedded for semantic recall WITHOUT passing through this conversation \u2014 the tool result only confirms the saved note. Use when the user asks to save/remember/store a page, or to build a knowledge base from scrapes."),
+  vaultName: import_zod3.z.string().trim().min(1).max(120).optional().describe("Optional vault to deposit into. Defaults to the user's personal vault.")
 };
 var MapSiteUrlsInputSchema = {
   url: import_zod3.z.string().url().describe("Public website URL or domain to crawl for internal URLs. Use before extract_site when the user asks to audit/map/crawl a site."),
@@ -4369,6 +4469,10 @@ var FacebookAdSearchInputSchema = {
   country: import_zod3.z.string().length(2).default("US").describe("Two-letter Ad Library country code. Default US. Examples: US, CA, GB, AU."),
   maxResults: import_zod3.z.number().int().min(1).max(20).default(10).describe("Maximum advertisers to return. Default 10, maximum 20. Prefer tighter search terms over maxing this out.")
 };
+var RedditThreadInputSchema = {
+  url: import_zod3.z.string().min(1).describe("A reddit.com thread/post URL (www, old, or new Reddit, or a redd.it link). The service fetches it via old.reddit through a residential proxy and returns the post plus its comment tree."),
+  maxComments: import_zod3.z.number().int().min(1).max(2e3).optional().describe("Optional cap on comments returned. Omit to return all captured comments.")
+};
 var FacebookAdTranscribeInputSchema = {
   videoUrl: import_zod3.z.string().url().describe("Direct Facebook CDN video URL from a facebook_page_intel ad result. Do not pass a public Facebook reel/post/share URL here; use facebook_video_transcribe for organic Facebook URLs.")
 };
@@ -4635,7 +4739,17 @@ var ExtractUrlOutputSchema = {
   entityTypes: import_zod3.z.array(import_zod3.z.string()),
   napScore: import_zod3.z.number().nullable(),
   missingSchemaFields: import_zod3.z.array(import_zod3.z.string()),
-  screenshotSaved: NullableString2
+  screenshotSaved: NullableString2,
+  memory: import_zod3.z.object({
+    deposited: import_zod3.z.boolean(),
+    vault: import_zod3.z.string().optional(),
+    noteId: import_zod3.z.string().optional(),
+    path: import_zod3.z.string().optional(),
+    chunks: import_zod3.z.number().int().optional(),
+    fileUrl: import_zod3.z.string().optional(),
+    fileExpiresAt: import_zod3.z.string().optional(),
+    error: import_zod3.z.string().optional()
+  }).optional()
 };
 var ExtractSiteOutputSchema = {
   url: import_zod3.z.string(),
@@ -4767,6 +4881,21 @@ var FacebookAdSearchOutputSchema = {
     sampleLibraryId: NullableString2
   }))
 };
+var RedditThreadOutputSchema = {
+  sourceUrl: NullableString2,
+  oldRedditUrl: NullableString2,
+  title: NullableString2,
+  author: NullableString2,
+  score: NullableString2,
+  postBody: NullableString2,
+  numComments: import_zod3.z.number().int().min(0),
+  comments: import_zod3.z.array(import_zod3.z.object({
+    author: NullableString2,
+    score: NullableString2,
+    depth: import_zod3.z.number().int().min(0),
+    body: import_zod3.z.string()
+  }))
+};
 var FacebookPageIntelOutputSchema = {
   advertiserName: NullableString2,
   totalAds: import_zod3.z.number().int().min(0),
@@ -4960,6 +5089,7 @@ var CreditsInfoInputSchema = {
 };
 var WorkflowIdSchema = import_zod3.z.enum([
   "directory",
+  "get-leads",
   "agent-packet",
   "local-competitive-audit",
   "map-comparison",
@@ -4981,8 +5111,8 @@ var WorkflowSuggestInputSchema = {
   maxSuggestions: import_zod3.z.number().int().min(1).max(8).default(3).describe("Number of matching workflow recipes to return.")
 };
 var WorkflowRunInputSchema = {
-  workflowId: WorkflowIdSchema.describe("Workflow to run: directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language. Use only these values; call workflow_list or workflow_suggest first when unsure."),
-  input: import_zod3.z.record(import_zod3.z.unknown()).default({}).describe("Workflow-specific input object. Examples: agent-packet uses {keyword, domain?, location?, maxQuestions?}; local-competitive-audit uses {query, state, minPopulation?, maxCities?, maxResultsPerCity?, hydrateTop?, maxReviews?}; serp-comparison uses {keyword, domain?, url?, location?, extractTop?}."),
+  workflowId: WorkflowIdSchema.describe("Workflow to run: directory, get-leads, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language. Use only these values; call workflow_list or workflow_suggest first when unsure."),
+  input: import_zod3.z.record(import_zod3.z.unknown()).default({}).describe("Workflow-specific input object. Examples: get-leads uses {query, location, maxResults?, enrichWebsites?, hydrateReviewCounts?}; agent-packet uses {keyword, domain?, location?, maxQuestions?}; local-competitive-audit uses {query, state, minPopulation?, maxCities?, maxResultsPerCity?, hydrateTop?, maxReviews?}; serp-comparison uses {keyword, domain?, url?, location?, extractTop?}."),
   webhookUrl: import_zod3.z.string().url().optional().describe("Optional HTTPS webhook to receive the completed hosted workflow run event.")
 };
 var WorkflowStepInputSchema = {
@@ -5058,7 +5188,7 @@ var SearchSerpInputSchema = {
   gl: import_zod3.z.string().length(2).default("us").describe("Google country code inferred from location or user language."),
   hl: import_zod3.z.string().default("en").describe("Google interface/content language inferred from user request."),
   device: import_zod3.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe("Proxy targeting mode. Default configured uses the service proxy without city/ZIP targeting for the highest general SERP success rate. Use location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use none only for direct-network debugging."),
+  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe('Leave unset \u2014 routing is automatic. Set "location" only to force local-pack targeting.'),
   proxyZip: import_zod3.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only with proxyMode location when the user gives a specific ZIP or city-center targeting needs to be forced."),
   debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior."),
   pages: import_zod3.z.number().int().min(1).max(2).default(1).describe("Number of result pages to fetch (1\u20132)")
@@ -5069,7 +5199,7 @@ var CaptureSerpSnapshotInputSchema = {
   gl: import_zod3.z.string().length(2).default("us").describe("Google country code inferred from the requested market, e.g. us, gb, ca, au."),
   hl: import_zod3.z.string().default("en").describe("Google interface/content language inferred from the user request."),
   device: import_zod3.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use mobile only when the user asks for mobile rankings or mobile SERP evidence."),
-  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe("Proxy behavior for capture. Default configured uses the service proxy without city/ZIP targeting for the highest general capture success rate. Use location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use none only for direct-network debugging."),
+  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE).describe('Leave unset \u2014 routing is automatic. Set "location" only to force city/ZIP targeting.'),
   proxyZip: import_zod3.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use only with proxyMode location when a precise city-center or ZIP proxy is needed."),
   pages: import_zod3.z.number().int().min(1).max(2).default(1).describe("Number of Google result pages to capture. Use 1 normally and 2 only when the user needs deeper ranking evidence."),
   debug: import_zod3.z.boolean().default(false).describe("Include sanitized browser, proxy, and location diagnostics. Use true when debugging localization, CAPTCHA, proxy selection, or capture reliability."),
@@ -5476,21 +5606,21 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
   if (savesReports) registerSavedReportResources(server2);
   server2.registerTool("harvest_paa", {
     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"). Omit proxyMode for normal use; the service defaults to the configured browser-service proxy without city/ZIP targeting for the highest general success rate. Use proxyMode location only when the user explicitly needs city/ZIP-targeted residential proxy evidence. Use maxQuestions 30 normally, 100-200 for "full", "deep", "all", or comprehensive research. Deep harvests above 100 questions can run for several minutes with no interim progress \u2014 warn the user before starting one and keep maxQuestions at or below 100 unless they explicitly want a deep harvest. Credits are charged by extracted question; unused request hold is refunded.'),
+    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"). Routing is automatic \u2014 leave proxyMode unset. If a deep harvest exceeds the time budget it returns the questions gathered so far (partial), billed per returned question. Use maxQuestions 30 normally, 100-200 for "full", "deep", "all", or comprehensive research. Deep harvests above 100 questions can run for several minutes with no interim progress \u2014 warn the user before starting one and keep maxQuestions at or below 100 unless they explicitly want a deep harvest. 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));
   server2.registerTool("search_serp", {
     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. Omit proxyMode for normal use; the service defaults to the configured browser-service proxy without city/ZIP targeting. Use proxyMode location and proxyZip only when the user explicitly needs city/ZIP-targeted residential proxy evidence."),
+    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. Routing is automatic \u2014 leave proxyMode unset; set location only to force local-pack targeting."),
     inputSchema: SearchSerpInputSchema,
     outputSchema: SearchSerpOutputSchema,
     annotations: liveWebToolAnnotations("Google SERP Lookup")
   }, async (input) => formatSearchSerp(await executor.searchSerp(input), input));
   server2.registerTool("extract_url", {
     title: "Single URL Extract",
-    description: withReportNote("Extract structured data from one public URL when the user provides one page, asks to inspect/scrape a page, or needs page content, schema, headings, metadata, screenshots, branding, or media assets. Returns structured page fields plus artifact handles for saved reports/screenshots/media when requested. Use map_site_urls before extracting a site inventory; use extract_site for multi-page crawling."),
+    description: withReportNote("Extract structured data from one public URL when the user provides one page, asks to inspect/scrape a page, or needs page content, schema, headings, metadata, screenshots, branding, or media assets. Returns structured page fields plus artifact handles for saved reports/screenshots/media when requested. Set depositToVault:true to also save the full page into the user's MCP Memory vault server-side (the full body is NOT returned to chat). Use map_site_urls before extracting a site inventory; use extract_site for multi-page crawling."),
     inputSchema: ExtractUrlInputSchema,
     outputSchema: ExtractUrlOutputSchema,
     annotations: liveWebToolAnnotations("Single URL Extract")
@@ -5544,6 +5674,13 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
     outputSchema: FacebookAdSearchOutputSchema,
     annotations: liveWebToolAnnotations("Facebook Ad Library Search")
   }, async (input) => formatFacebookAdSearch(await executor.facebookAdSearch(input), input));
+  server2.registerTool("reddit_thread", {
+    title: "Reddit Thread + Comments",
+    description: withReportNote("Capture a Reddit post and its comment tree from any reddit.com thread URL. Use this when the user wants Reddit comments, opinions, discussion, or audience voice from a specific thread (find threads first with search_serp, which surfaces reddit.com/comments links). Returns the post title, author, score, body, and a list of comments with author, score, nesting depth, and text. Handles Reddit's bot protection automatically (fetches via old.reddit through a residential proxy with retries); pass maxComments to cap the list."),
+    inputSchema: RedditThreadInputSchema,
+    outputSchema: RedditThreadOutputSchema,
+    annotations: liveWebToolAnnotations("Reddit Thread + Comments")
+  }, async (input) => formatRedditThread(await executor.redditThread(input), input));
   server2.registerTool("facebook_ad_transcribe", {
     title: "Facebook Ad Transcription",
     description: "Transcribe audio from a Facebook ad video CDN URL. Use this when facebook_page_intel returned a direct videoUrl and the user asks what the ad says, what claims it makes, or wants ad-message extraction. Returns full transcript, timestamped chunks, word count, and resolvedInputs. Use only with the direct videoUrl value from facebook_page_intel results; do not pass public Facebook post/reel/share URLs. Use facebook_video_transcribe for organic Facebook URLs, and facebook_page_intel first when you only have a brand/page/ad library handle.",
@@ -5581,14 +5718,14 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
   }, async (input) => formatMapsPlaceIntel(await executor.mapsPlaceIntel(input), input));
   server2.registerTool("maps_search", {
     title: "Google Maps Business Search",
-    description: withReportNote('Search Google Maps for multiple businesses/profiles by category, niche, keyword, or local market. Use this when the user asks for several Google Business Profiles, GMBs, GBPs, leads, prospects, competitors, or "more than the 3-pack." Maps is the default location-targeted surface: omit proxyMode for normal Maps use so the service creates residential proxy evidence for the requested market and rotates on retryable failures. Pass proxyZip only when a specific ZIP or city-center ZIP is known. Use proxyMode configured only when you explicitly do not want city/ZIP proxy targeting. Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, profile metadata, and sanitized attempt telemetry. Default maxResults is 10; maximum is 50. Use maps_place_intel afterward only when a selected business needs full details and reviews.'),
+    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." Routing is automatic and location-aware \u2014 leave proxyMode unset; pass proxyZip only to force a specific ZIP. Returns up to 50 candidates with names, place URLs, CIDs when available, ratings, review counts, profile metadata, and sanitized attempt telemetry. 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));
   server2.registerTool("directory_workflow", {
     title: "Directory Workflow: Markets + Maps",
-    description: withReportNote('Build directory/prospecting datasets by selecting US city markets from the free Census Population Estimates city/place dataset, optionally joining configured US ZIPS/Lead Magician ZIP groups, then running Google Maps business searches for each city in parallel. Use this when the user wants "all cities over 100k population in a state", "build a directory CSV", "find markets then get Maps data", or similar location-database + Maps workflows. Set minPopulation, state, query, maxResultsPerCity, and concurrency. Maps workflows default to location-targeted proxying so each city can use city/state or ZIP-group residential proxy evidence; use proxyMode configured only when you explicitly do not want city/ZIP proxy targeting. Saved CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, cid, cid_decimal, city population, and ZIP groups. Structured city results include sanitized attempt telemetry. Use maps_place_intel only when a selected profile needs deeper review topics, profile review count confirmation, or review cards. For local Lead Magician ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath only in local/test mode.'),
+    description: withReportNote('Build directory/prospecting datasets by selecting US city markets from the free Census Population Estimates city/place dataset, optionally joining configured US ZIPS/Lead Magician ZIP groups, then running Google Maps business searches for each city in parallel. Use this when the user wants "all cities over 100k population in a state", "build a directory CSV", "find markets then get Maps data", or similar location-database + Maps workflows. Set minPopulation, state, query, maxResultsPerCity, and concurrency. Routing is automatic per city. Saved CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, cid, cid_decimal, city population, and ZIP groups. Structured city results include sanitized attempt telemetry. Use maps_place_intel only when a selected profile needs deeper review topics, profile review count confirmation, or review cards. For local Lead Magician ZIP enrichment, set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath only in local/test mode.'),
     inputSchema: DirectoryWorkflowInputSchema,
     outputSchema: DirectoryWorkflowOutputSchema,
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
@@ -5709,11 +5846,11 @@ function renderInstallTerminal(options) {
     "1/1 install surfaces ready",
     colorize("Newest: saved browser profiles that hold MANY site logins. Share the watch_url, user signs in, then verify with browser_profile_list. Browser sessions are direct/no-proxy by default.", "lime", color),
     "",
-    `${colorize("Tools", "cyan", color)}  ${colorize("(45 MCP tools)", "muted", color)}`,
+    `${colorize("Tools", "cyan", color)}  ${colorize("(46 MCP tools)", "muted", color)}`,
     toolRow("search", ["harvest_paa", "search_serp", "maps_search", "maps_place_intel"], color),
     toolRow("extract", ["extract_url", "map_site_urls", "extract_site", "audit_site", "directory_workflow"], color),
     toolRow("build", ["rank_tracker_workflow", "cron plan", "database prompt"], color),
-    toolRow("media", ["youtube_harvest", "youtube_transcribe", "facebook_ad_search", "facebook_page_intel", "facebook_ad_transcribe", "facebook_video_transcribe", "instagram_profile_content", "instagram_media_download"], color),
+    toolRow("media", ["youtube_harvest", "youtube_transcribe", "facebook_ad_search", "facebook_page_intel", "facebook_ad_transcribe", "facebook_video_transcribe", "instagram_profile_content", "instagram_media_download", "reddit_thread"], color),
     toolRow("browser", ["browser_open", "browser_profile_connect", "browser_profile_list", "browser_close", "browser_screenshot", "browser_read", "browser_locate", "browser_replay_mark", "browser_replay_annotate"], color),
     toolRow("account", ["credits_info", "reports", "MCP resources"], color),
     `${colorize("Workflows", "cyan", color)}  ${colorize("(MCP + CLI + API)", "muted", color)}`,