mcp-scraper 0.2.15 → 0.2.17

package/dist/bin/mcp-scraper-cli.js

@@ -9,7 +9,7 @@ import {
 } from "../chunk-F44RBOJ5.js";
 import {
   PACKAGE_VERSION
-} from "../chunk-2CQXHSWC.js";
+} from "../chunk-NZG2K6CJ.js";
 
 // src/cli/human-cli.ts
 import { Command } from "commander";

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

@@ -76,6 +76,57 @@ var HttpMcpToolExecutor = class {
       return { content: [{ type: "text", text: msg }], isError: true };
     }
   }
+  async getJson(path, timeoutMs = this.timeoutMs) {
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method: "GET",
+        headers: {
+          "x-api-key": this.apiKey
+        },
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        return { content: [{ type: "text", text: JSON.stringify(data) }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: "text", text: msg }], isError: true };
+    }
+  }
+  async getTextArtifact(path, maxBytes, timeoutMs = this.timeoutMs) {
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method: "GET",
+        headers: {
+          "x-api-key": this.apiKey
+        },
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(async () => ({ error: await res.text().catch(() => `HTTP ${res.status}`) }));
+        return { content: [{ type: "text", text: JSON.stringify(data) }], isError: true };
+      }
+      const bytes = Buffer.from(await res.arrayBuffer());
+      const sliced = bytes.subarray(0, Math.min(maxBytes, bytes.length));
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            contentType: res.headers.get("content-type") ?? "application/octet-stream",
+            bytes: bytes.length,
+            truncated: sliced.length < bytes.length,
+            maxBytes,
+            text: sliced.toString("utf8")
+          })
+        }]
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: "text", text: msg }], isError: true };
+    }
+  }
   harvestPaa(input) {
     const timeoutMs = this.httpTimeoutOverrideMs ?? harvestTimeoutBudget(input.maxQuestions ?? 30).clientMs;
     return this.call("/harvest/sync", input, timeoutMs);
@@ -123,6 +174,26 @@ var HttpMcpToolExecutor = class {
     const timeoutMs = this.httpTimeoutOverrideMs ?? Math.min(9e5, Math.max(18e4, Math.ceil(cityCount / concurrency) * 12e4));
     return this.call("/directory/run", input, timeoutMs);
   }
+  workflowList(_input) {
+    return this.getJson("/workflows/definitions");
+  }
+  workflowRun(input) {
+    const timeoutMs = this.httpTimeoutOverrideMs ?? Number(process.env.MCP_SCRAPER_WORKFLOW_TIMEOUT_MS ?? 9e5);
+    return this.call("/workflows/run", {
+      workflowId: input.workflowId,
+      input: input.input ?? {},
+      webhookUrl: input.webhookUrl
+    }, Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 9e5);
+  }
+  workflowStatus(input) {
+    return this.getJson(`/workflows/runs/${encodeURIComponent(input.runId)}`);
+  }
+  workflowArtifactRead(input) {
+    return this.getTextArtifact(
+      `/workflows/runs/${encodeURIComponent(input.runId)}/artifacts/${encodeURIComponent(input.artifactId)}`,
+      input.maxBytes ?? 2e5
+    );
+  }
   creditsInfo(input) {
     return this.call("/billing/credits", input);
   }
@@ -141,7 +212,7 @@ var import_node_os2 = require("os");
 var import_node_path2 = require("path");
 
 // src/version.ts
-var PACKAGE_VERSION = "0.2.15";
+var PACKAGE_VERSION = "0.2.17";
 
 // src/mcp/browser-agent-tool-schemas.ts
 var import_zod = require("zod");
@@ -931,6 +1002,121 @@ function sanitizeVendorName(message) {
   return message.replace(/kernel\.sh\s+sessions?/gi, "sessions").replace(/kernel\.sh\s+session/gi, "this session").replace(/kernel\.sh/gi, "the service").replace(/kernel\s+sessions?/gi, "sessions").replace(/kernel\s+session/gi, "this session").replace(/\bkernel\b/gi, "the service").replace(/  +/g, " ").trim();
 }
 
+// src/mcp/workflow-catalog.ts
+var WORKFLOW_RECIPES = [
+  {
+    id: "market_analysis",
+    title: "Market Analysis",
+    description: "Compare a niche across a city, state, or market set using Google Maps competitors, SERP evidence, review counts, categories, and opportunity signals.",
+    primaryWorkflowId: "local-competitive-audit",
+    recommendedTools: ["workflow_run", "directory_workflow", "maps_search", "maps_place_intel", "search_serp", "harvest_paa"],
+    requiredInputs: ["query", "state or location"],
+    optionalInputs: ["domain", "minPopulation", "maxCities", "maxResultsPerCity", "hydrateTop", "maxReviews"],
+    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: "icp_research",
+    title: "ICP Research",
+    description: "Build an evidence packet for ideal-customer-profile research from real search demand, PAA language, competing pages, AI Overview citations, and source domains.",
+    primaryWorkflowId: "agent-packet",
+    recommendedTools: ["workflow_run", "harvest_paa", "search_serp", "extract_url", "youtube_harvest", "facebook_ad_search"],
+    requiredInputs: ["keyword or audience problem"],
+    optionalInputs: ["domain", "location", "maxQuestions"],
+    produces: ["evidence JSON", "sources CSV", "competitor CSV", "brief markdown", "agent task list"],
+    runHint: "Use workflow_run with workflowId agent-packet. Treat keyword as the buyer problem, job-to-be-done, niche, or service category."
+  },
+  {
+    id: "forum_review_research",
+    title: "Forum And Review Research",
+    description: "Acquire customer language from Google PAA, forum/Perspectives SERP surfaces, Google Maps reviews, review topics, Facebook ads, and video transcripts.",
+    primaryWorkflowId: "local-competitive-audit",
+    recommendedTools: ["workflow_run", "harvest_paa", "maps_search", "maps_place_intel", "facebook_page_intel", "facebook_video_transcribe", "youtube_transcribe"],
+    requiredInputs: ["query", "state or location"],
+    optionalInputs: ["maxReviews", "maxQuestions", "competitors", "facebookUrl", "youtubeVideoId"],
+    produces: ["review insight CSV", "PAA/source language", "competitor review topics", "transcripts where supplied", "pain/theme summary"],
+    runHint: "Use local-competitive-audit for review acquisition, then harvest_paa for forum/Perspectives language and transcript tools for supplied videos."
+  },
+  {
+    id: "brand_design_brief",
+    title: "Brand Design Brief",
+    description: "Create a design briefing grounded in a brand site, competitor pages, SERP language, audience pains, visual assets, colors, fonts, screenshots, and positioning evidence.",
+    primaryWorkflowId: "serp-comparison",
+    recommendedTools: ["workflow_run", "extract_url", "extract_site", "capture_serp_page_snapshots", "search_serp", "harvest_paa", "browser_open"],
+    requiredInputs: ["url or domain", "keyword or market category"],
+    optionalInputs: ["competitorUrls", "location", "extractTop"],
+    produces: ["page comparison CSV", "content gaps", "branding/asset evidence", "SERP positioning evidence", "designer-ready brief"],
+    runHint: "Use workflow_run with workflowId serp-comparison for market/page evidence, then extract_url with extractBranding:true for brand assets and colors."
+  },
+  {
+    id: "cro_audit",
+    title: "CRO Audit",
+    description: "Audit conversion clarity using page extraction, screenshots, browser DOM inspection, competitor SERP/page comparisons, forms/buttons, proof, offer, trust, and friction evidence.",
+    primaryWorkflowId: "serp-comparison",
+    recommendedTools: ["workflow_run", "extract_url", "extract_site", "capture_serp_page_snapshots", "browser_open", "browser_screenshot", "browser_locate"],
+    requiredInputs: ["url"],
+    optionalInputs: ["keyword", "domain", "location", "competitorUrls"],
+    produces: ["page extraction", "SERP/page comparison", "screenshot evidence", "friction checklist", "CRO recommendations"],
+    runHint: "Use workflow_run with workflowId serp-comparison when a keyword/domain is known; use extract_url and browser tools for page-level CRO evidence."
+  },
+  {
+    id: "competitive_positioning_brief",
+    title: "Competitive Positioning Brief",
+    description: "Compare competitors across SERP, PAA, AI Overview citations, page headings, Facebook ads, YouTube angles, Maps proof, and website claims.",
+    primaryWorkflowId: "serp-comparison",
+    recommendedTools: ["workflow_run", "facebook_ad_search", "facebook_page_intel", "youtube_harvest", "youtube_transcribe", "maps_search", "extract_url"],
+    requiredInputs: ["keyword or query", "domain or url"],
+    optionalInputs: ["location", "extractTop", "competitorUrls", "brandNames"],
+    produces: ["SERP comparison", "content gap CSV", "AI Overview citation table", "competitor message map", "positioning brief"],
+    runHint: "Use workflow_run with workflowId serp-comparison, then enrich with Facebook, YouTube, and Maps tools when the user asks for campaign or offer positioning."
+  },
+  {
+    id: "content_gap_brief",
+    title: "Content Gap Brief",
+    description: "Turn live SERP, page extraction, PAA questions, AI Overview citations, and source-domain evidence into a writer-ready content brief.",
+    primaryWorkflowId: "serp-comparison",
+    recommendedTools: ["workflow_run", "paa-expansion-brief", "harvest_paa", "extract_url"],
+    requiredInputs: ["keyword"],
+    optionalInputs: ["domain", "url", "location", "maxQuestions", "extractTop"],
+    produces: ["content gaps", "page comparison CSV", "PAA questions CSV", "section map", "writer brief"],
+    runHint: "Use workflow_run with workflowId serp-comparison for competitor gaps or paa-expansion-brief when the user mainly wants a section map from PAA data."
+  },
+  {
+    id: "ai_search_visibility_audit",
+    title: "AI Search Visibility Audit",
+    description: "Audit whether a brand/domain appears in AI Overview citations, PAA sources, organic results, local pack, and source pages, then produce language guidance.",
+    primaryWorkflowId: "ai-overview-language",
+    recommendedTools: ["workflow_run", "search_serp", "harvest_paa", "extract_url", "capture_serp_snapshot"],
+    requiredInputs: ["keyword", "domain or url"],
+    optionalInputs: ["location", "maxQuestions", "extractTop"],
+    produces: ["AI Overview citations CSV", "claim patterns", "language guidance", "citation hooks", "visibility gaps"],
+    runHint: "Use workflow_run with workflowId ai-overview-language. Use serp-comparison when the user also wants ranking-page gaps."
+  }
+];
+function normalize(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+function suggestWorkflowRecipes(goal, limit = 3) {
+  const normalized = normalize(goal);
+  const scored = WORKFLOW_RECIPES.map((recipe) => {
+    const haystack = normalize([
+      recipe.id,
+      recipe.title,
+      recipe.description,
+      recipe.requiredInputs.join(" "),
+      recipe.optionalInputs.join(" "),
+      recipe.produces.join(" ")
+    ].join(" "));
+    let score = 0;
+    for (const token of normalized.split(/\s+/).filter(Boolean)) {
+      if (haystack.includes(token)) score += 1;
+    }
+    if (haystack.includes(normalized)) score += 5;
+    return { recipe, score };
+  });
+  return scored.sort((a, b) => b.score - a.score || a.recipe.title.localeCompare(b.recipe.title)).slice(0, Math.max(1, limit)).map((item) => item.recipe);
+}
+
 // src/mcp/mcp-response-formatter.ts
 var reportSavingEnabled = true;
 function sanitizeVendorText(text) {
@@ -982,6 +1168,14 @@ function oneBlock(content) {
 \u{1F4C4} Saved: \`${filePath}\`` : content;
   return { content: [{ type: "text", text }] };
 }
+function workflowRecipeTable(recipes) {
+  if (!recipes.length) return "";
+  return [
+    "| Recipe | Best workflow | What it produces |",
+    "|---|---|---|",
+    ...recipes.map((recipe) => `| ${cell(recipe.title)} | ${recipe.primaryWorkflowId ? `\`${recipe.primaryWorkflowId}\`` : "tool chain"} | ${cell(recipe.produces.slice(0, 4).join(", "))} |`)
+  ].join("\n");
+}
 function formatStructuredError(body, fallback) {
   if (body.error === "insufficient_balance") {
     return `Insufficient credits. Balance: ${body.balance_credits} credits. This call requires ${body.required_credits} credits. Top up at ${body.topup_url}`;
@@ -1471,7 +1665,8 @@ ${adBlocks}`,
     `
 ---
 \u{1F4A1} **Tips**
-- Transcribe video ads: use \`facebook_ad_transcribe\` with the \`videoUrl\` above
+- Transcribe video ads: use \`facebook_ad_transcribe\` with the direct \`videoUrl\` above
+- Transcribe organic Facebook reels/posts: use \`facebook_video_transcribe\` with the public Facebook URL
 - Find other advertisers: use \`facebook_ad_search\``
   ].filter(Boolean).join("\n");
   return {
@@ -1553,6 +1748,163 @@ function normalizeMapsAttempts(value) {
     observedRegion: attempt.observedRegion ?? attempt.observed_region ?? null
   }));
 }
+function workflowArtifactsFrom(run) {
+  return Array.isArray(run?.artifacts) ? run.artifacts : [];
+}
+function workflowArtifactRows(artifacts) {
+  if (!artifacts.length) return "";
+  return [
+    "| Artifact | Type | ID | Rows/Bytes |",
+    "|---|---|---|---|",
+    ...artifacts.map((artifact) => {
+      const rows = artifact.rows_count ?? artifact.rows ?? "";
+      const bytes = artifact.bytes ?? "";
+      const size = [rows ? `${rows} rows` : "", bytes ? `${bytes} bytes` : ""].filter(Boolean).join(" / ");
+      return `| ${cell(String(artifact.label ?? artifact.path ?? "artifact"))} | ${cell(String(artifact.kind ?? artifact.content_type ?? "file"))} | \`${String(artifact.id ?? "")}\` | ${cell(size || "\u2014")} |`;
+    })
+  ].join("\n");
+}
+function formatWorkflowList(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const workflows = Array.isArray(parsed.data.workflows) ? parsed.data.workflows : [];
+  const workflowRows = [
+    "| Workflow ID | Title | Use |",
+    "|---|---|---|",
+    ...workflows.map((workflow) => `| \`${String(workflow.id ?? "")}\` | ${cell(String(workflow.title ?? ""))} | ${cell(String(workflow.description ?? ""))} |`)
+  ].join("\n");
+  const recipes = input.includeRecipes === false ? [] : WORKFLOW_RECIPES;
+  const full = [
+    "# MCP Scraper Workflows",
+    "Use `workflow_suggest` when the user describes a high-level job. Use `workflow_run` when the workflow id and input are known. Use `workflow_status` and `workflow_artifact_read` to inspect completed runs and pull evidence back into context.",
+    workflows.length ? `
+## Runnable Workflows
+${workflowRows}` : "",
+    recipes.length ? `
+## High-Level Recipes
+${workflowRecipeTable(recipes)}` : "",
+    recipes.length ? "\nThese recipes cover market analysis, ICP research, forum and review acquisition, brand design briefings, CRO audits, competitive positioning, content gaps, and AI search visibility audits." : ""
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      workflows: workflows.map((workflow) => ({
+        id: String(workflow.id ?? ""),
+        title: String(workflow.title ?? ""),
+        description: String(workflow.description ?? "")
+      })),
+      recipes
+    }
+  };
+}
+function formatWorkflowSuggest(input) {
+  const suggestions = suggestWorkflowRecipes(input.goal, input.maxSuggestions ?? 3);
+  const full = [
+    `# Workflow Suggestions`,
+    `**Goal:** ${input.goal}`,
+    "",
+    workflowRecipeTable(suggestions),
+    "",
+    "## How To Execute",
+    "1. Pick the closest recipe.",
+    "2. If it has a `primaryWorkflowId`, call `workflow_run` with that id and the required inputs.",
+    "3. After the run completes, use `workflow_artifact_read` on the most relevant CSV/JSON/Markdown artifacts before writing the final answer."
+  ].join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      goal: input.goal,
+      suggestions
+    }
+  };
+}
+function formatWorkflowRun(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const run = parsed.data.run;
+  const summary = parsed.data.summary;
+  const artifacts = workflowArtifactsFrom(run);
+  const runId = String(run?.id ?? "");
+  const status = String(run?.status ?? summary?.status ?? "unknown");
+  const full = [
+    `# Workflow Run: ${input.workflowId}`,
+    `**Run ID:** \`${runId || "unknown"}\``,
+    `**Status:** ${status}`,
+    summary?.title ? `**Title:** ${summary.title}` : "",
+    summary?.summary ? `
+## Summary
+${summary.summary}` : "",
+    artifacts.length ? `
+## Artifacts
+${workflowArtifactRows(artifacts)}` : "",
+    artifacts.length ? "\nUse `workflow_artifact_read` with the run id and artifact id to pull CSV, JSON, Markdown, or report content into context." : ""
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      workflowId: input.workflowId,
+      input: input.input ?? {},
+      run,
+      summary,
+      artifacts
+    }
+  };
+}
+function formatWorkflowStatus(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const run = parsed.data.run;
+  const artifacts = workflowArtifactsFrom(run);
+  const full = [
+    `# Workflow Status`,
+    `**Run ID:** \`${input.runId}\``,
+    `**Workflow:** ${run?.workflow_id ?? "unknown"}`,
+    `**Status:** ${run?.status ?? "unknown"}`,
+    run?.error_message ? `
+## Error
+${run.error_message}` : "",
+    artifacts.length ? `
+## Artifacts
+${workflowArtifactRows(artifacts)}` : ""
+  ].filter(Boolean).join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      run,
+      artifacts
+    }
+  };
+}
+function formatWorkflowArtifactRead(raw, input) {
+  const parsed = parseData(raw);
+  if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
+  const text = typeof parsed.data.text === "string" ? parsed.data.text : "";
+  const contentType = String(parsed.data.contentType ?? "text/plain");
+  const bytes = Number(parsed.data.bytes ?? 0);
+  const truncated = parsed.data.truncated === true;
+  const full = [
+    `# Workflow Artifact`,
+    `**Run ID:** \`${input.runId}\``,
+    `**Artifact ID:** \`${input.artifactId}\``,
+    `**Content-Type:** ${contentType}`,
+    `**Bytes:** ${bytes}${truncated ? ` (truncated to ${input.maxBytes ?? 2e5})` : ""}`,
+    "",
+    "```",
+    text,
+    "```"
+  ].join("\n");
+  return {
+    ...oneBlock(full),
+    structuredContent: {
+      runId: input.runId,
+      artifactId: input.artifactId,
+      contentType,
+      bytes,
+      truncated,
+      text
+    }
+  };
+}
 function formatCreditsInfo(raw, input) {
   const parsed = parseData(raw);
   if ("error" in parsed) return { content: [{ type: "text", text: parsed.error }], isError: true };
@@ -1917,7 +2269,7 @@ ${text}`,
 ${chunkRows}` : "",
     `
 ---
-\u{1F4A1} Get more ads from this advertiser: use \`facebook_page_intel\``
+\u{1F4A1} Get more ads from this advertiser: use \`facebook_page_intel\`. For public Facebook reel/post URLs, use \`facebook_video_transcribe\`.`
   ].filter(Boolean).join("\n");
   return oneBlock(full);
 }
@@ -1953,7 +2305,7 @@ ${text}`,
 ${chunkRows}` : "",
     `
 ---
-\u{1F4A1} To download the extracted MP4, call the Facebook media endpoint with the extracted MP4 URL.`
+\u{1F4A1} Use \`videoUrl\` as the extracted MP4 for download or follow-up processing. Use \`facebook_ad_transcribe\` only for Ad Library videoUrl values.`
   ].filter(Boolean).join("\n");
   return {
     ...oneBlock(full),
@@ -2030,10 +2382,10 @@ var FacebookAdSearchInputSchema = {
   maxResults: import_zod2.z.number().int().min(1).max(20).default(10)
 };
 var FacebookAdTranscribeInputSchema = {
-  videoUrl: import_zod2.z.string().url().describe("Facebook CDN video URL from a facebook_page_intel result")
+  videoUrl: import_zod2.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.")
 };
 var FacebookVideoTranscribeInputSchema = {
-  url: import_zod2.z.string().url().describe("Organic Facebook reel, video, watch, or share URL. The tool renders the page, extracts the best public Facebook CDN MP4 URL, then transcribes it."),
+  url: import_zod2.z.string().url().describe("Organic Facebook reel, video, watch, post, or share URL from facebook.com, m.facebook.com, or fb.watch. The tool renders the page, extracts the best matching public Facebook CDN MP4 URL, then transcribes it. Use this when the user pastes a normal Facebook video page URL and asks for the transcript or downloadable MP4."),
   quality: import_zod2.z.enum(["best", "hd", "sd"]).default("best").describe("Preferred progressive MP4 quality. Use best by default; hd prefers the highest HD progressive URL; sd forces the SD URL.")
 };
 var MapsPlaceIntelInputSchema = {
@@ -2423,6 +2775,85 @@ var CreditsInfoInputSchema = {
   item: import_zod2.z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", "YouTube transcription", or "concurrency"'),
   includeLedger: import_zod2.z.boolean().default(false).describe("Whether to include recent credit ledger entries")
 };
+var WorkflowIdSchema = import_zod2.z.enum([
+  "directory",
+  "agent-packet",
+  "local-competitive-audit",
+  "map-comparison",
+  "serp-comparison",
+  "paa-expansion-brief",
+  "ai-overview-language"
+]);
+var WorkflowListInputSchema = {
+  includeRecipes: import_zod2.z.boolean().default(true).describe("Include high-level AI-facing recipes such as market analysis, ICP research, forum/review research, brand design briefings, CRO audits, positioning briefs, content gaps, and AI search visibility audits.")
+};
+var WorkflowSuggestInputSchema = {
+  goal: import_zod2.z.string().min(1).describe('The user goal or job to route, e.g. "market analysis for roofers in Tennessee", "ICP research for med spas", "CRO audit for this URL", or "brand design briefing".'),
+  query: import_zod2.z.string().optional().describe("Business category, niche, or Maps query when known."),
+  keyword: import_zod2.z.string().optional().describe("Search keyword, audience problem, or content topic when known."),
+  domain: import_zod2.z.string().optional().describe("Target domain or brand domain when known."),
+  url: import_zod2.z.string().url().optional().describe("Target URL when the workflow should inspect a specific page."),
+  location: import_zod2.z.string().optional().describe("City/region/country for localized research, e.g. Denver, CO."),
+  state: import_zod2.z.string().optional().describe("US state abbreviation or name for state-wide market research."),
+  maxSuggestions: import_zod2.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. Use workflow_list or workflow_suggest first when unsure."),
+  input: import_zod2.z.record(import_zod2.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?}."),
+  webhookUrl: import_zod2.z.string().url().optional().describe("Optional HTTPS webhook to receive the completed hosted workflow run event.")
+};
+var WorkflowStatusInputSchema = {
+  runId: import_zod2.z.string().min(1).describe("Workflow run id returned by workflow_run.")
+};
+var WorkflowArtifactReadInputSchema = {
+  runId: import_zod2.z.string().min(1).describe("Workflow run id returned by workflow_run or workflow_status."),
+  artifactId: import_zod2.z.string().min(1).describe("Artifact id from the run artifact list."),
+  maxBytes: import_zod2.z.number().int().min(1e3).max(1e6).default(2e5).describe("Maximum bytes of artifact text to return inline. Use lower values for large CSV/JSON artifacts; call again with the downloadUrl if needed outside MCP.")
+};
+var WorkflowRecipeOutput = import_zod2.z.object({
+  id: import_zod2.z.string(),
+  title: import_zod2.z.string(),
+  description: import_zod2.z.string(),
+  primaryWorkflowId: import_zod2.z.string().nullable(),
+  recommendedTools: import_zod2.z.array(import_zod2.z.string()),
+  requiredInputs: import_zod2.z.array(import_zod2.z.string()),
+  optionalInputs: import_zod2.z.array(import_zod2.z.string()),
+  produces: import_zod2.z.array(import_zod2.z.string()),
+  runHint: import_zod2.z.string()
+});
+var WorkflowDefinitionOutput = import_zod2.z.object({
+  id: import_zod2.z.string(),
+  title: import_zod2.z.string(),
+  description: import_zod2.z.string()
+});
+var WorkflowArtifactOutput = import_zod2.z.record(import_zod2.z.unknown());
+var WorkflowListOutputSchema = {
+  workflows: import_zod2.z.array(WorkflowDefinitionOutput),
+  recipes: import_zod2.z.array(WorkflowRecipeOutput)
+};
+var WorkflowSuggestOutputSchema = {
+  goal: import_zod2.z.string(),
+  suggestions: import_zod2.z.array(WorkflowRecipeOutput)
+};
+var WorkflowRunOutputSchema = {
+  workflowId: import_zod2.z.string(),
+  input: import_zod2.z.record(import_zod2.z.unknown()),
+  run: import_zod2.z.record(import_zod2.z.unknown()).optional(),
+  summary: import_zod2.z.record(import_zod2.z.unknown()).optional(),
+  artifacts: import_zod2.z.array(WorkflowArtifactOutput)
+};
+var WorkflowStatusOutputSchema = {
+  run: import_zod2.z.record(import_zod2.z.unknown()).optional(),
+  artifacts: import_zod2.z.array(WorkflowArtifactOutput)
+};
+var WorkflowArtifactReadOutputSchema = {
+  runId: import_zod2.z.string(),
+  artifactId: import_zod2.z.string(),
+  contentType: import_zod2.z.string(),
+  bytes: import_zod2.z.number().int().min(0),
+  truncated: import_zod2.z.boolean(),
+  text: import_zod2.z.string()
+};
 var SearchSerpInputSchema = {
   query: import_zod2.z.string().min(1).describe('Core search topic only. Separate location when possible. If user says "best dentist in Brooklyn NY serp", use query="best dentist" and location="Brooklyn, NY".'),
   location: import_zod2.z.string().optional().describe("City, region, or country for geo-targeted results, inferred from user request when present."),
@@ -2895,7 +3326,7 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
   }, async (input) => formatYoutubeTranscribe(await executor.youtubeTranscribe(input), input));
   server2.registerTool("facebook_page_intel", {
     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."),
+    description: withReportNote("Harvest ads from a Facebook advertiser. Returns ad copy, headlines, CTAs, creative type, status, landing URLs, and direct ad video URLs ready for facebook_ad_transcribe. Accepts pageId, libraryId, or a brand/advertiser name as query. Use after facebook_ad_search when possible. For normal public Facebook reels/posts/watch/share URLs, use facebook_video_transcribe instead."),
     inputSchema: FacebookPageIntelInputSchema,
     outputSchema: FacebookPageIntelOutputSchema,
     annotations: liveWebToolAnnotations("Facebook Advertiser Ad Intel")
@@ -2909,13 +3340,13 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
   }, async (input) => formatFacebookAdSearch(await executor.facebookAdSearch(input), input));
   server2.registerTool("facebook_ad_transcribe", {
     title: "Facebook Ad Transcription",
-    description: "Transcribe audio from a Facebook ad video. Returns full transcript and timestamped chunks. Use the videoUrl value from facebook_page_intel results.",
+    description: "Transcribe audio from a Facebook ad video CDN URL. Returns full transcript and timestamped chunks. Use only with the direct videoUrl value from facebook_page_intel results, not public Facebook post/reel/share URLs.",
     inputSchema: FacebookAdTranscribeInputSchema,
     annotations: liveWebToolAnnotations("Facebook Ad Transcription")
   }, async (input) => formatFacebookAdTranscribe(await executor.facebookAdTranscribe(input), input));
   server2.registerTool("facebook_video_transcribe", {
     title: "Facebook Organic Video Transcription",
-    description: withReportNote("Transcribe audio from an organic Facebook reel, video, watch, or share URL. Renders the Facebook page, extracts the best public Facebook CDN MP4 URL from the page state, then returns the full transcript, timestamped chunks, and extracted MP4 URL."),
+    description: withReportNote("Transcribe audio from an organic Facebook reel, video, watch, post, or share URL, including fb.watch links. Use this when the user pastes a normal Facebook video page URL and wants the transcript or downloadable MP4. Renders the Facebook page in a browser, selects the best matching public Facebook CDN MP4 URL from page state, then returns sourceUrl, resolved pageUrl, videoId, ownerName, selectedQuality, bitrate, videoDurationSec, extracted MP4 URL, full transcript, and timestamped chunks."),
     inputSchema: FacebookVideoTranscribeInputSchema,
     outputSchema: FacebookVideoTranscribeOutputSchema,
     annotations: liveWebToolAnnotations("Facebook Organic Video Transcription")
@@ -2941,6 +3372,41 @@ function registerPaaExtractorMcpTools(server2, executor, options = {}) {
     outputSchema: DirectoryWorkflowOutputSchema,
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
   }, async (input) => formatDirectoryWorkflow(await executor.directoryWorkflow(input), input));
+  server2.registerTool("workflow_list", {
+    title: "Workflow Catalog",
+    description: "List MCP Scraper higher-level workflows and AI-facing recipes. Use this when the user asks what MCP Scraper can do beyond single tools, or asks for market analysis, ICP research, forum/review acquisition, full brand design briefings, CRO audits, competitive positioning, content gap briefs, or AI search visibility audits. Returns runnable workflow ids plus recipe guidance for the best tool chain.",
+    inputSchema: WorkflowListInputSchema,
+    outputSchema: WorkflowListOutputSchema,
+    annotations: localPlanningToolAnnotations("Workflow Catalog")
+  }, async (input) => formatWorkflowList(await executor.workflowList(input), input));
+  server2.registerTool("workflow_suggest", {
+    title: "Workflow Intent Router",
+    description: 'Route a high-level business or research goal to the right MCP Scraper workflow/tool chain. Use before running work when the user says things like "do market analysis", "research my ICP", "acquire forum and review language", "build a brand design brief", "run a CRO audit", "compare competitors", "make a content gap brief", or "audit AI search visibility". This tool does not spend credits; it tells the AI exactly which workflow/tool chain to run next.',
+    inputSchema: WorkflowSuggestInputSchema,
+    outputSchema: WorkflowSuggestOutputSchema,
+    annotations: localPlanningToolAnnotations("Workflow Intent Router")
+  }, async (input) => formatWorkflowSuggest(input));
+  server2.registerTool("workflow_run", {
+    title: "Run Workflow",
+    description: withReportNote("Run a higher-level MCP Scraper workflow and return the run id, summary, and artifacts. Use after workflow_suggest or workflow_list. Runnable workflow ids: directory, agent-packet, local-competitive-audit, map-comparison, serp-comparison, paa-expansion-brief, ai-overview-language. This is the main MCP tool for executing market analysis, ICP evidence packets, local competitive audits, Maps/SERP comparisons, content gap briefs, and AI Overview language guidance."),
+    inputSchema: WorkflowRunInputSchema,
+    outputSchema: WorkflowRunOutputSchema,
+    annotations: liveWebToolAnnotations("Run Workflow")
+  }, async (input) => formatWorkflowRun(await executor.workflowRun(input), input));
+  server2.registerTool("workflow_status", {
+    title: "Workflow Status",
+    description: "Fetch a hosted workflow run by id and list its current status and artifacts. Use after workflow_run when the model needs to re-open a run, inspect artifact ids, or recover from a long workflow.",
+    inputSchema: WorkflowStatusInputSchema,
+    outputSchema: WorkflowStatusOutputSchema,
+    annotations: liveWebToolAnnotations("Workflow Status")
+  }, async (input) => formatWorkflowStatus(await executor.workflowStatus(input), input));
+  server2.registerTool("workflow_artifact_read", {
+    title: "Read Workflow Artifact",
+    description: "Read a workflow artifact back into MCP context by run id and artifact id. Use this before writing final deliverables so the answer is grounded in generated evidence.json, CSVs, Markdown briefs, reports, and task files instead of memory. Use maxBytes to limit large CSV/JSON artifacts.",
+    inputSchema: WorkflowArtifactReadInputSchema,
+    outputSchema: WorkflowArtifactReadOutputSchema,
+    annotations: liveWebToolAnnotations("Read Workflow Artifact")
+  }, async (input) => formatWorkflowArtifactRead(await executor.workflowArtifactRead(input), input));
   server2.registerTool("rank_tracker_blueprint", {
     title: "Rank Tracker Blueprint Builder",
     description: "Generate a build-ready database, cron/heartbeat, ingestion, metrics, and AI implementation prompt for a rank tracker powered by MCP Scraper. Supports Maps rankings through directory_workflow/maps_search, organic rankings through search_serp, AI Overview citation tracking, and People Also Ask source presence tracking. This tool is local planning only; it does not call the web or spend credits.",