mcp-scraper 0.2.16 → 0.2.18

package/README.md

@@ -22,7 +22,7 @@ Run this when you want the designed terminal install experience:
 npx -y -p mcp-scraper@latest mcp-scraper-install
 ```
 
-It prints the MCP Scraper banner, loaded tool groups, Desktop Extension download, Claude Code command, and Codex config. The MCP server commands stay silent so stdout remains valid JSON-RPC for MCP clients.
+It prints the MCP Scraper banner, loaded tool groups, Desktop Extension download, Claude Code command, and Codex config. This is the command to use when you want the ASCII terminal card. The MCP server commands, including `mcp-scraper-combined`, stay silent so stdout remains valid JSON-RPC for MCP clients.
 
 ### Human CLI
 
@@ -81,7 +81,7 @@ Build the branded one-click bundle:
 npm run build:mcpb
 ```
 
-The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb` and copied to `public/downloads/` for the hosted download. The current public bundle is `https://mcpscraper.dev/downloads/mcp-scraper.mcpb` (`0.2.16`, SHA-256 `a581f0ddb12d3cebd03d90dfb657cc9127a1f7ef995fb0934d5428faf8aec58b`). Install it by opening or dragging it into Claude Desktop. Claude displays the `MCP Scraper` install card, icon, and API-key configuration field from the bundle manifest.
+The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb` and copied to `public/downloads/` for the hosted download. The current public bundle is `https://mcpscraper.dev/downloads/mcp-scraper.mcpb` (`0.2.18`, SHA-256 `3b94a39bf23712005a1a04accdefcf3ee24978995033b92e4488390d47350ea0`). Install it by opening or dragging it into Claude Desktop. Claude displays the `MCP Scraper` install card, icon, and API-key configuration field from the bundle manifest.
 
 The MCPB install exposes the same web-intelligence tools as `mcp-scraper` plus all `browser_*` tools from `browser-agent` through one server.
 
@@ -159,6 +159,11 @@ env = { MCP_SCRAPER_API_KEY = "sk_live_your_key" }
 - `maps_search` — search Google Maps for multiple business/profile candidates. Use for GMB/GBP prospect lists, competitors, categories, and anything needing more than the Google 3-pack. In default `proxyMode: "location"`, retryable failures rotate to a new residential proxy and new browser session for up to 5 attempts. `maxResults` defaults to 10 and is capped at 50.
 - `maps_place_intel` — hydrate one known/named Google Maps business with profile details and optional reviews. Use after `maps_search` when a selected candidate needs full details.
 - `directory_workflow` — build city-by-city directory/prospecting datasets from Census place selection plus Google Maps searches. Use it for requests like "all cities over 100k population in Tennessee, then get 20 roofers from Maps." In default `proxyMode: "location"`, each city search rotates retryable failures to a new residential proxy and new browser session for up to 5 attempts. The saved CSV includes `source_location`, `result_position`, `business_name`, `review_stars`, `review_count`, `category`, `address`, `phone`, `hours_status`, `website_url`, `directions_url`, `place_url`, `cid`, `cid_decimal`, Census population, and ZIP groups.
+- `workflow_list` — list higher-level workflow IDs plus AI-facing recipes for market analysis, ICP research, forum/review acquisition, brand design briefings, CRO audits, positioning briefs, content gaps, and AI search visibility audits.
+- `workflow_suggest` — route a high-level business goal to the right workflow/tool chain before spending credits.
+- `workflow_run` — run hosted workflows such as `agent-packet`, `local-competitive-audit`, `map-comparison`, `serp-comparison`, `paa-expansion-brief`, and `ai-overview-language`; returns run metadata, summary, and artifact IDs.
+- `workflow_status` — reopen a workflow run and list its current status and artifacts.
+- `workflow_artifact_read` — pull generated workflow artifacts such as `evidence.json`, CSVs, Markdown briefs, and reports back into MCP context.
 - `rank_tracker_blueprint` — generate a database schema, cron/heartbeat plan, ingestion workflow, metrics list, and implementation prompt for building rank trackers. It has modes for Maps rankings via `directory_workflow`/`maps_search`, organic rankings via `search_serp`, AI Overview citation tracking, and PAA source presence tracking. This is a local planning tool and does not spend credits.
 - `credits_info`
 
@@ -190,9 +195,9 @@ For Google Maps tools (`maps_search` and `directory_workflow`), keep `proxyMode`
 
 The MCPB bundle and `mcp-scraper-combined` expose both sections through one local MCP server. The split `mcp-scraper` entrypoint exposes only the web-intelligence tools, and the split `browser-agent` entrypoint exposes only the browser-agent tools.
 
-Chaining and planning tools (`maps_search`, `directory_workflow`, `rank_tracker_blueprint`, `map_site_urls`, `youtube_harvest`, `facebook_ad_search`, `facebook_page_intel`, `facebook_video_transcribe`) advertise an `outputSchema` and return `structuredContent` with the IDs, URLs, CSV paths, transcripts, or blueprint fields needed by the next step. All tools carry MCP annotations (`readOnlyHint: true`; live-web tools use `openWorldHint: true`, while local planning and credit tools are closed-world/idempotent).
+Chaining and planning tools (`maps_search`, `directory_workflow`, `workflow_list`, `workflow_suggest`, `workflow_run`, `workflow_status`, `workflow_artifact_read`, `rank_tracker_blueprint`, `map_site_urls`, `youtube_harvest`, `facebook_ad_search`, `facebook_page_intel`, `facebook_video_transcribe`) return `structuredContent` with the IDs, URLs, CSV paths, transcripts, artifacts, recipe fields, or blueprint fields needed by the next step. All tools carry MCP annotations (`readOnlyHint: true`; live-web tools use `openWorldHint: true`, while local planning and credit tools are closed-world/idempotent).
 
-The hosted MCP endpoint at `https://mcpscraper.dev/mcp` exposes the 16 web-intelligence tools plus `capture_serp_snapshot` and `capture_serp_page_snapshots` (18 total). Browser-agent tools are local stdio tools backed by the REST API under `https://mcpscraper.dev/agent/*`.
+The hosted MCP endpoint at `https://mcpscraper.dev/mcp` exposes the 21 web-intelligence/workflow tools plus `capture_serp_snapshot` and `capture_serp_page_snapshots` (23 total). Browser-agent tools are local stdio tools backed by the REST API under `https://mcpscraper.dev/agent/*`.
 
 ## Resources
 
@@ -218,6 +223,8 @@ Recommended config for update-friendly installs:
 npx -y -p mcp-scraper@latest mcp-scraper-combined
 ```
 
+This is an MCP stdio server command, not a human-facing terminal UI. If you run it directly, it appears to hang because it is waiting for JSON-RPC input from the MCP client. Use `npx -y -p mcp-scraper@latest mcp-scraper-install` when you want the visible installer and ASCII card.
+
 Split-server config:
 
 ```bash
@@ -236,7 +243,7 @@ Users who do not update can keep using the tools their local package already adv
 
 ## Branded One-Click Installs
 
-Raw `npx` MCP server installs are command/config based. They do not provide a reliable user-facing install card, logo, or setup screen inside MCP clients. Use `mcp-scraper-install` for terminal onboarding text. Do not print marketing text to stdout from an MCP server; stdout is reserved for JSON-RPC protocol messages.
+Raw `npx` MCP server installs are command/config based. They do not provide a reliable user-facing install card, logo, or setup screen inside MCP clients. Use `mcp-scraper-install` for terminal onboarding text and the ASCII card. Do not print marketing text to stdout from an MCP server; stdout is reserved for JSON-RPC protocol messages.
 
 For a branded Claude Desktop install, package MCP Scraper as an MCPB Desktop Extension. The repository now builds one combined MCPB bundle with a generated icon, `manifest.json`, bundled runtime dependencies, and `user_config` fields for API-key setup, API URL, and output folder.
 

package/dist/bin/api-server.cjs

@@ -13814,6 +13814,127 @@ var init_maps_routes = __esm({
   }
 });
 
+// src/mcp/workflow-catalog.ts
+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);
+}
+var WORKFLOW_RECIPES;
+var init_workflow_catalog = __esm({
+  "src/mcp/workflow-catalog.ts"() {
+    "use strict";
+    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."
+      }
+    ];
+  }
+});
+
 // src/mcp/mcp-response-formatter.ts
 function configureReportSaving(enabled) {
   reportSavingEnabled = enabled;
@@ -13867,6 +13988,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}`;
@@ -14439,6 +14568,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 };
@@ -14871,6 +15157,7 @@ var init_mcp_response_formatter = __esm({
     import_node_os3 = require("os");
     import_node_path5 = require("path");
     init_errors();
+    init_workflow_catalog();
     reportSavingEnabled = true;
   }
 });
@@ -20146,12 +20433,12 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.2.16";
+    PACKAGE_VERSION = "0.2.18";
   }
 });
 
 // src/mcp/mcp-tool-schemas.ts
-var import_zod26, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, FacebookVideoTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, FacebookVideoTranscribeOutputSchema, CreditsInfoInputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
+var import_zod26, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, FacebookVideoTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, FacebookVideoTranscribeOutputSchema, CreditsInfoInputSchema, WorkflowIdSchema2, WorkflowListInputSchema, WorkflowSuggestInputSchema, WorkflowRunInputSchema, WorkflowStatusInputSchema, WorkflowArtifactReadInputSchema, WorkflowRecipeOutput, WorkflowDefinitionOutput, WorkflowArtifactOutput, WorkflowListOutputSchema, WorkflowSuggestOutputSchema, WorkflowRunOutputSchema, WorkflowStatusOutputSchema, WorkflowArtifactReadOutputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
 var init_mcp_tool_schemas = __esm({
   "src/mcp/mcp-tool-schemas.ts"() {
     "use strict";
@@ -20599,6 +20886,85 @@ var init_mcp_tool_schemas = __esm({
       item: import_zod26.z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", "YouTube transcription", or "concurrency"'),
       includeLedger: import_zod26.z.boolean().default(false).describe("Whether to include recent credit ledger entries")
     };
+    WorkflowIdSchema2 = import_zod26.z.enum([
+      "directory",
+      "agent-packet",
+      "local-competitive-audit",
+      "map-comparison",
+      "serp-comparison",
+      "paa-expansion-brief",
+      "ai-overview-language"
+    ]);
+    WorkflowListInputSchema = {
+      includeRecipes: import_zod26.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.")
+    };
+    WorkflowSuggestInputSchema = {
+      goal: import_zod26.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_zod26.z.string().optional().describe("Business category, niche, or Maps query when known."),
+      keyword: import_zod26.z.string().optional().describe("Search keyword, audience problem, or content topic when known."),
+      domain: import_zod26.z.string().optional().describe("Target domain or brand domain when known."),
+      url: import_zod26.z.string().url().optional().describe("Target URL when the workflow should inspect a specific page."),
+      location: import_zod26.z.string().optional().describe("City/region/country for localized research, e.g. Denver, CO."),
+      state: import_zod26.z.string().optional().describe("US state abbreviation or name for state-wide market research."),
+      maxSuggestions: import_zod26.z.number().int().min(1).max(8).default(3).describe("Number of matching workflow recipes to return.")
+    };
+    WorkflowRunInputSchema = {
+      workflowId: WorkflowIdSchema2.describe("Workflow to run. Use workflow_list or workflow_suggest first when unsure."),
+      input: import_zod26.z.record(import_zod26.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_zod26.z.string().url().optional().describe("Optional HTTPS webhook to receive the completed hosted workflow run event.")
+    };
+    WorkflowStatusInputSchema = {
+      runId: import_zod26.z.string().min(1).describe("Workflow run id returned by workflow_run.")
+    };
+    WorkflowArtifactReadInputSchema = {
+      runId: import_zod26.z.string().min(1).describe("Workflow run id returned by workflow_run or workflow_status."),
+      artifactId: import_zod26.z.string().min(1).describe("Artifact id from the run artifact list."),
+      maxBytes: import_zod26.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.")
+    };
+    WorkflowRecipeOutput = import_zod26.z.object({
+      id: import_zod26.z.string(),
+      title: import_zod26.z.string(),
+      description: import_zod26.z.string(),
+      primaryWorkflowId: import_zod26.z.string().nullable(),
+      recommendedTools: import_zod26.z.array(import_zod26.z.string()),
+      requiredInputs: import_zod26.z.array(import_zod26.z.string()),
+      optionalInputs: import_zod26.z.array(import_zod26.z.string()),
+      produces: import_zod26.z.array(import_zod26.z.string()),
+      runHint: import_zod26.z.string()
+    });
+    WorkflowDefinitionOutput = import_zod26.z.object({
+      id: import_zod26.z.string(),
+      title: import_zod26.z.string(),
+      description: import_zod26.z.string()
+    });
+    WorkflowArtifactOutput = import_zod26.z.record(import_zod26.z.unknown());
+    WorkflowListOutputSchema = {
+      workflows: import_zod26.z.array(WorkflowDefinitionOutput),
+      recipes: import_zod26.z.array(WorkflowRecipeOutput)
+    };
+    WorkflowSuggestOutputSchema = {
+      goal: import_zod26.z.string(),
+      suggestions: import_zod26.z.array(WorkflowRecipeOutput)
+    };
+    WorkflowRunOutputSchema = {
+      workflowId: import_zod26.z.string(),
+      input: import_zod26.z.record(import_zod26.z.unknown()),
+      run: import_zod26.z.record(import_zod26.z.unknown()).optional(),
+      summary: import_zod26.z.record(import_zod26.z.unknown()).optional(),
+      artifacts: import_zod26.z.array(WorkflowArtifactOutput)
+    };
+    WorkflowStatusOutputSchema = {
+      run: import_zod26.z.record(import_zod26.z.unknown()).optional(),
+      artifacts: import_zod26.z.array(WorkflowArtifactOutput)
+    };
+    WorkflowArtifactReadOutputSchema = {
+      runId: import_zod26.z.string(),
+      artifactId: import_zod26.z.string(),
+      contentType: import_zod26.z.string(),
+      bytes: import_zod26.z.number().int().min(0),
+      truncated: import_zod26.z.boolean(),
+      text: import_zod26.z.string()
+    };
     SearchSerpInputSchema = {
       query: import_zod26.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_zod26.z.string().optional().describe("City, region, or country for geo-targeted results, inferred from user request when present."),
@@ -21130,6 +21496,41 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
     outputSchema: DirectoryWorkflowOutputSchema,
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
   }, async (input) => formatDirectoryWorkflow(await executor.directoryWorkflow(input), input));
+  server.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));
+  server.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));
+  server.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));
+  server.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));
+  server.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));
   server.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.",
@@ -21225,6 +21626,57 @@ var init_http_mcp_tool_executor = __esm({
           return { content: [{ type: "text", text: msg }], isError: true };
         }
       }
+      async getJson(path6, timeoutMs = this.timeoutMs) {
+        try {
+          const res = await fetch(`${this.baseUrl}${path6}`, {
+            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(path6, maxBytes, timeoutMs = this.timeoutMs) {
+        try {
+          const res = await fetch(`${this.baseUrl}${path6}`, {
+            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);
@@ -21272,6 +21724,26 @@ var init_http_mcp_tool_executor = __esm({
         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);
       }
@@ -21677,16 +22149,16 @@ async function locatePageTargets(cdpWsUrl, targets) {
     }).catch(() => {
     });
     const data = await page.evaluate((rawTargets) => {
-      const normalize = (value) => value.replace(/\s+/g, " ").trim();
+      const normalize2 = (value) => value.replace(/\s+/g, " ").trim();
       const isVisibleRect = (r) => r.width >= 1 && r.height >= 1 && r.bottom >= 0 && r.right >= 0 && r.top <= window.innerHeight && r.left <= window.innerWidth;
       const roleOf = (el2) => el2.getAttribute("role") || el2.tagName.toLowerCase();
       const nameOf = (el2) => {
         const e = el2;
-        return normalize(
+        return normalize2(
           e.getAttribute("aria-label") || e.placeholder || e.innerText || e.getAttribute("value") || e.getAttribute("title") || ""
         ).slice(0, 160);
       };
-      const textOf = (el2) => normalize(el2.innerText || el2.textContent || "").slice(0, 500);
+      const textOf = (el2) => normalize2(el2.innerText || el2.textContent || "").slice(0, 500);
       const unionRects = (rects) => {
         const visible = rects.filter(isVisibleRect);
         if (!visible.length) return null;
@@ -21725,7 +22197,7 @@ async function locatePageTargets(cdpWsUrl, targets) {
         return nodes.map((el2) => ({ el: el2, rect: el2.getBoundingClientRect() })).filter((item) => isVisibleRect(item.rect));
       };
       const textMatches = (needle, match) => {
-        const wanted = normalize(needle);
+        const wanted = normalize2(needle);
         const wantedLower = wanted.toLowerCase();
         if (!wantedLower) return [];
         const matches = [];
@@ -21733,7 +22205,7 @@ async function locatePageTargets(cdpWsUrl, targets) {
         let node = walker.nextNode();
         while (node) {
           const raw = node.textContent || "";
-          const normalizedRaw = normalize(raw);
+          const normalizedRaw = normalize2(raw);
           const rawLower = raw.toLowerCase();
           const normalizedLower = normalizedRaw.toLowerCase();
           const ok = match === "exact" ? normalizedLower === wantedLower : normalizedLower.includes(wantedLower);