mcp-scraper 0.2.18 → 0.2.20

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

@@ -4,11 +4,11 @@
 // src/cli/human-cli.ts
 var import_commander = require("commander");
 var import_node_child_process2 = require("child_process");
-var import_promises3 = require("fs/promises");
+var import_promises4 = require("fs/promises");
 var import_node_path3 = require("path");
 
 // src/version.ts
-var PACKAGE_VERSION = "0.2.18";
+var PACKAGE_VERSION = "0.2.20";
 
 // src/cli/agent-config.ts
 function apiKeyValue(options) {
@@ -441,7 +441,8 @@ async function openWorkflowReport(id, outputDir) {
 }
 
 // src/workflows/registry.ts
-var import_zod5 = require("zod");
+var import_promises3 = require("fs/promises");
+var import_zod6 = require("zod");
 
 // src/workflows/http-client.ts
 var WorkflowHttpClient = class {
@@ -622,115 +623,254 @@ var agentPacketWorkflowDefinition = {
   title: "Agent-Ready SEO Packet",
   description: "Create an evidence folder for AI agents from live SERP/PAA/AI search surfaces.",
   inputSchema: AgentPacketInputSchema,
-  async run(input, ctx) {
-    await ctx.artifacts.writeManifest("running", {}, [], []);
-    const warnings = [];
-    const errors = [];
-    let serp = null;
-    let paa = null;
-    if (input.includeSerp) {
-      try {
-        serp = await ctx.client.post("/harvest/sync", {
-          query: input.keyword,
-          location: input.location,
-          serpOnly: true,
-          maxQuestions: 1,
-          format: "json"
-        }, 18e4);
-      } catch (err) {
-        warnings.push(`SERP evidence unavailable: ${err instanceof Error ? err.message : String(err)}`);
+  createState: () => ({ serp: null, paa: null, warnings: [] }),
+  steps: [
+    {
+      id: "harvest-serp",
+      title: "Harvest organic SERP + AI Overview",
+      async run({ input, state, ctx }) {
+        if (!input.includeSerp) {
+          return { state, output: { skipped: true, reason: "includeSerp is false" } };
+        }
+        try {
+          const serp = await ctx.client.post("/harvest/sync", {
+            query: input.keyword,
+            location: input.location,
+            serpOnly: true,
+            maxQuestions: 1,
+            format: "json"
+          }, 18e4);
+          await ctx.artifacts.writeJson("SERP raw JSON", "raw/serp.json", serp);
+          return {
+            state: { ...state, serp },
+            output: {
+              organicResults: serp.organicResults?.length ?? 0,
+              localPack: serp.localPack?.length ?? 0,
+              aiOverviewDetected: Boolean(serp.aiOverview?.detected),
+              aiOverviewCitations: serp.aiOverview?.citations?.length ?? 0
+            }
+          };
+        } catch (err) {
+          const message = `SERP evidence unavailable: ${err instanceof Error ? err.message : String(err)}`;
+          return { state: { ...state, warnings: [...state.warnings, message] }, output: { error: message }, warnings: [message] };
+        }
       }
-    }
-    if (input.includePaa) {
-      try {
-        paa = await ctx.client.post("/harvest/sync", {
-          query: input.keyword,
-          location: input.location,
-          maxQuestions: input.maxQuestions,
-          format: "json"
-        }, 28e4);
-      } catch (err) {
-        warnings.push(`PAA evidence unavailable: ${err instanceof Error ? err.message : String(err)}`);
+    },
+    {
+      id: "harvest-paa",
+      title: "Harvest People Also Ask",
+      async run({ input, state, ctx }) {
+        if (!input.includePaa) {
+          return { state, output: { skipped: true, reason: "includePaa is false" } };
+        }
+        try {
+          const paa = await ctx.client.post("/harvest/sync", {
+            query: input.keyword,
+            location: input.location,
+            maxQuestions: input.maxQuestions,
+            format: "json"
+          }, 28e4);
+          await ctx.artifacts.writeJson("PAA raw JSON", "raw/paa.json", paa);
+          return {
+            state: { ...state, paa },
+            output: { paaQuestions: paa.flat?.length ?? 0 }
+          };
+        } catch (err) {
+          const message = `PAA evidence unavailable: ${err instanceof Error ? err.message : String(err)}`;
+          return { state: { ...state, warnings: [...state.warnings, message] }, output: { error: message }, warnings: [message] };
+        }
+      }
+    },
+    {
+      id: "assemble",
+      title: "Assemble evidence packet",
+      async run({ input, state, ctx }) {
+        const { serp, paa } = state;
+        const warnings = state.warnings;
+        if (!serp && !paa && !input.returnPartial) throw new Error("No SEO evidence was collected");
+        const rows = sourceRows(input, serp, paa);
+        const target = normalizeDomain(input.domain);
+        const competitors = competitorRows(rows, target);
+        const evidence = {
+          input,
+          serp: serp ?? { status: "skipped" },
+          paa: paa ?? { status: "skipped" },
+          target: {
+            domain: target,
+            organicPositions: rows.filter((r) => r.surface === "organic" && r.is_target).map((r) => Number(r.position)),
+            citedInAiOverview: rows.some((r) => r.surface === "ai_overview" && r.is_target),
+            citedInPaa: rows.some((r) => r.surface === "paa" && r.is_target)
+          },
+          competitors,
+          warnings
+        };
+        await ctx.artifacts.writeJson("Evidence JSON", "evidence.json", evidence);
+        await ctx.artifacts.writeCsv("Sources CSV", "sources.csv", ["surface", "position", "title", "url", "domain", "question", "answer_excerpt", "is_target", "is_competitor"], rows);
+        await ctx.artifacts.writeCsv("Competitors CSV", "competitors.csv", ["domain", "organic_best_position", "organic_count", "paa_mentions", "ai_overview_citations", "source_url_count"], competitors);
+        const brief = [
+          `# SEO Evidence Brief: ${input.keyword}`,
+          "",
+          `Location: ${input.location ?? "not specified"}`,
+          `Target domain: ${target ?? "not specified"}`,
+          "",
+          "## Evidence Summary",
+          `- Organic rows: ${rows.filter((r) => r.surface === "organic").length}`,
+          `- PAA rows: ${rows.filter((r) => r.surface === "paa").length}`,
+          `- AI Overview citations: ${rows.filter((r) => r.surface === "ai_overview").length}`,
+          `- Competitor domains: ${competitors.length}`,
+          "",
+          "## Recommended Use",
+          "Use the CSV files as source of truth. Tie content recommendations to evidence rows and mark unsupported ideas as assumptions."
+        ].join("\n");
+        await ctx.artifacts.writeText("Brief", "brief.md", brief);
+        await ctx.artifacts.writeText("Agent tasks", "tasks.md", [
+          "# Agent Tasks",
+          "",
+          "- [ ] Read `evidence.json` before writing recommendations.",
+          "- [ ] Compare the target domain against `competitors.csv`.",
+          "- [ ] Use `sources.csv` for citations and source-grounded page sections.",
+          "- [ ] Mark unsupported recommendations as assumptions."
+        ].join("\n"));
+        await ctx.artifacts.writeText("Agent instructions", "agent-instructions.md", [
+          "# Agent Instructions",
+          "",
+          "You are working from an MCP Scraper SEO evidence packet. Use `evidence.json` and CSV files as source of truth. Do not invent citations. If a recommendation is not supported by evidence, mark it as an assumption."
+        ].join("\n"));
+        const summary = `${rows.length} evidence rows and ${competitors.length} competitor domains collected.`;
+        const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+          title: "Agent-Ready SEO Packet",
+          subtitle: `${input.keyword}${input.location ? ` \xB7 ${input.location}` : ""}`,
+          summary,
+          warnings,
+          tables: [
+            { title: "Competitor Domains", columns: ["domain", "organic_best_position", "organic_count", "paa_mentions", "ai_overview_citations", "source_url_count"], rows: competitors.slice(0, 50) },
+            { title: "Evidence Sources", columns: ["surface", "position", "title", "domain", "question", "is_target"], rows: rows.slice(0, 100) }
+          ]
+        }));
+        const status2 = warnings.length ? "partial" : "succeeded";
+        const counts = { sources: rows.length, competitors: competitors.length };
+        await ctx.artifacts.writeManifest(status2, counts, warnings, []);
+        return {
+          state,
+          output: { sources: rows.length, competitors: competitors.length, status: status2 },
+          summary: { title: "Agent-Ready SEO Packet", summary, status: status2, counts, warnings, errors: [], reportPath }
+        };
       }
     }
-    if (!serp && !paa && !input.returnPartial) throw new Error("No SEO evidence was collected");
-    const rows = sourceRows(input, serp, paa);
-    const target = normalizeDomain(input.domain);
-    const competitors = competitorRows(rows, target);
-    const evidence = {
-      input,
-      serp: serp ?? { status: "skipped" },
-      paa: paa ?? { status: "skipped" },
-      target: {
-        domain: target,
-        organicPositions: rows.filter((r) => r.surface === "organic" && r.is_target).map((r) => Number(r.position)),
-        citedInAiOverview: rows.some((r) => r.surface === "ai_overview" && r.is_target),
-        citedInPaa: rows.some((r) => r.surface === "paa" && r.is_target)
-      },
-      competitors,
-      warnings
-    };
-    await ctx.artifacts.writeJson("Evidence JSON", "evidence.json", evidence);
-    await ctx.artifacts.writeCsv("Sources CSV", "sources.csv", ["surface", "position", "title", "url", "domain", "question", "answer_excerpt", "is_target", "is_competitor"], rows);
-    await ctx.artifacts.writeCsv("Competitors CSV", "competitors.csv", ["domain", "organic_best_position", "organic_count", "paa_mentions", "ai_overview_citations", "source_url_count"], competitors);
-    const brief = [
-      `# SEO Evidence Brief: ${input.keyword}`,
-      "",
-      `Location: ${input.location ?? "not specified"}`,
-      `Target domain: ${target ?? "not specified"}`,
-      "",
-      "## Evidence Summary",
-      `- Organic rows: ${rows.filter((r) => r.surface === "organic").length}`,
-      `- PAA rows: ${rows.filter((r) => r.surface === "paa").length}`,
-      `- AI Overview citations: ${rows.filter((r) => r.surface === "ai_overview").length}`,
-      `- Competitor domains: ${competitors.length}`,
-      "",
-      "## Recommended Use",
-      "Use the CSV files as source of truth. Tie content recommendations to evidence rows and mark unsupported ideas as assumptions."
-    ].join("\n");
-    await ctx.artifacts.writeText("Brief", "brief.md", brief);
-    await ctx.artifacts.writeText("Agent tasks", "tasks.md", [
-      "# Agent Tasks",
-      "",
-      "- [ ] Read `evidence.json` before writing recommendations.",
-      "- [ ] Compare the target domain against `competitors.csv`.",
-      "- [ ] Use `sources.csv` for citations and source-grounded page sections.",
-      "- [ ] Mark unsupported recommendations as assumptions."
-    ].join("\n"));
-    await ctx.artifacts.writeText("Agent instructions", "agent-instructions.md", [
-      "# Agent Instructions",
-      "",
-      "You are working from an MCP Scraper SEO evidence packet. Use `evidence.json` and CSV files as source of truth. Do not invent citations. If a recommendation is not supported by evidence, mark it as an assumption."
-    ].join("\n"));
-    const summary = `${rows.length} evidence rows and ${competitors.length} competitor domains collected.`;
-    const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
-      title: "Agent-Ready SEO Packet",
-      subtitle: `${input.keyword}${input.location ? ` \xB7 ${input.location}` : ""}`,
-      summary,
-      warnings,
-      tables: [
-        { title: "Competitor Domains", columns: ["domain", "organic_best_position", "organic_count", "paa_mentions", "ai_overview_citations", "source_url_count"], rows: competitors.slice(0, 50) },
-        { title: "Evidence Sources", columns: ["surface", "position", "title", "domain", "question", "is_target"], rows: rows.slice(0, 100) }
-      ]
-    }));
-    const status2 = warnings.length ? "partial" : "succeeded";
-    const counts = { sources: rows.length, competitors: competitors.length };
-    await ctx.artifacts.writeManifest(status2, counts, warnings, errors);
-    return { title: "Agent-Ready SEO Packet", summary, status: status2, counts, warnings, errors, reportPath };
-  }
+  ]
 };
 
 // src/workflows/workflows/directory.ts
+var import_zod3 = require("zod");
+
+// src/schemas.ts
 var import_zod2 = require("zod");
-var DirectoryWorkflowCliInputSchema = import_zod2.z.object({
+var DEFAULT_PROXY_MODE = "configured";
+var DEFAULT_MAPS_PROXY_MODE = "location";
+var HarvestOptionsSchema = import_zod2.z.object({
   query: import_zod2.z.string().min(1),
-  state: import_zod2.z.string().min(2).default("TN"),
-  minPopulation: import_zod2.z.number().int().min(0).default(1e5),
-  maxCities: import_zod2.z.number().int().min(1).max(100).default(25),
-  maxResultsPerCity: import_zod2.z.number().int().min(1).max(50).default(20),
-  concurrency: import_zod2.z.number().int().min(1).max(5).default(5),
-  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default("location"),
-  saveCsv: import_zod2.z.boolean().default(true)
+  location: import_zod2.z.string().optional(),
+  gl: import_zod2.z.string().length(2).default("us"),
+  hl: import_zod2.z.string().length(2).default("en"),
+  device: import_zod2.z.enum(["desktop", "mobile"]).default("desktop"),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE),
+  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional(),
+  debug: import_zod2.z.boolean().default(false),
+  depth: import_zod2.z.number().int().min(1).max(30).default(3),
+  maxQuestions: import_zod2.z.number().int().min(1).max(1e3).default(100),
+  headless: import_zod2.z.boolean().default(false),
+  profileDir: import_zod2.z.string().optional(),
+  proxy: import_zod2.z.string().url().optional(),
+  kernelApiKey: import_zod2.z.string().optional(),
+  kernelProxyId: import_zod2.z.string().optional(),
+  kernelProxyResolution: import_zod2.z.unknown().optional(),
+  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)
+});
+var MapsPlaceOptionsSchema = import_zod2.z.object({
+  businessName: import_zod2.z.string().min(1),
+  location: import_zod2.z.string().min(1),
+  gl: import_zod2.z.string().length(2).default("us"),
+  hl: import_zod2.z.string().length(2).default("en"),
+  includeReviews: import_zod2.z.boolean().default(false),
+  maxReviews: import_zod2.z.number().int().min(1).max(500).default(50),
+  kernelApiKey: import_zod2.z.string().optional(),
+  kernelProxyId: import_zod2.z.string().optional(),
+  headless: import_zod2.z.boolean().default(true)
+});
+var MapsSearchOptionsSchema = import_zod2.z.object({
+  query: import_zod2.z.string().min(1),
+  location: import_zod2.z.string().optional(),
+  gl: import_zod2.z.string().length(2).default("us"),
+  hl: import_zod2.z.string().length(2).default("en"),
+  maxResults: import_zod2.z.number().int().min(1).max(50).default(10),
+  proxyMode: import_zod2.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  proxyZip: import_zod2.z.string().regex(/^\d{5}$/).optional(),
+  debug: import_zod2.z.boolean().default(false),
+  kernelApiKey: import_zod2.z.string().optional(),
+  kernelProxyId: import_zod2.z.string().optional(),
+  kernelProxyResolution: import_zod2.z.unknown().optional(),
+  headless: import_zod2.z.boolean().default(true)
+});
+var RawPAAItemSchema = import_zod2.z.object({
+  question: import_zod2.z.string().min(1),
+  answer: import_zod2.z.string().optional(),
+  sourceTitle: import_zod2.z.string().optional(),
+  sourceSite: import_zod2.z.string().optional(),
+  sourceCite: import_zod2.z.string().optional()
+});
+var RawMapsOverviewSchema = import_zod2.z.object({
+  name: import_zod2.z.string().nullable(),
+  rating: import_zod2.z.string().nullable(),
+  reviewCount: import_zod2.z.string().nullable(),
+  category: import_zod2.z.string().nullable(),
+  address: import_zod2.z.string().nullable(),
+  hoursSummary: import_zod2.z.string().nullable(),
+  phone: import_zod2.z.string().nullable(),
+  phoneDisplay: import_zod2.z.string().nullable(),
+  website: import_zod2.z.string().nullable(),
+  plusCode: import_zod2.z.string().nullable(),
+  bookingUrl: import_zod2.z.string().nullable()
+});
+var RawMapsHoursRowSchema = import_zod2.z.object({
+  day: import_zod2.z.string(),
+  hours: import_zod2.z.string()
+});
+var RawMapsReviewStatsSchema = import_zod2.z.object({
+  reviewHistogram: import_zod2.z.array(import_zod2.z.object({
+    stars: import_zod2.z.number(),
+    count: import_zod2.z.string()
+  })),
+  reviewTopics: import_zod2.z.array(import_zod2.z.object({
+    label: import_zod2.z.string(),
+    count: import_zod2.z.string()
+  }))
+});
+var RawMapsReviewCardSchema = import_zod2.z.object({
+  reviewId: import_zod2.z.string(),
+  author: import_zod2.z.string().nullable(),
+  stars: import_zod2.z.string().nullable(),
+  date: import_zod2.z.string().nullable(),
+  text: import_zod2.z.string().nullable(),
+  ownerResponse: import_zod2.z.string().nullable()
+});
+var RawMapsAboutAttributeSchema = import_zod2.z.object({
+  section: import_zod2.z.string(),
+  attribute: import_zod2.z.string()
+});
+
+// src/workflows/workflows/directory.ts
+var DirectoryWorkflowCliInputSchema = import_zod3.z.object({
+  query: import_zod3.z.string().min(1),
+  state: import_zod3.z.string().min(2).default("TN"),
+  minPopulation: import_zod3.z.number().int().min(0).default(1e5),
+  maxCities: import_zod3.z.number().int().min(1).max(100).default(25),
+  maxResultsPerCity: import_zod3.z.number().int().min(1).max(50).default(20),
+  concurrency: import_zod3.z.number().int().min(1).max(5).default(5),
+  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  saveCsv: import_zod3.z.boolean().default(true)
 });
 function directoryRows(result) {
   const rows = [];
@@ -854,18 +994,18 @@ ${summary}
 };
 
 // src/workflows/workflows/local-competitive-audit.ts
-var import_zod3 = require("zod");
-var LocalCompetitiveAuditInputSchema = import_zod3.z.object({
-  query: import_zod3.z.string().min(1),
-  state: import_zod3.z.string().min(2).default("TN"),
-  minPopulation: import_zod3.z.number().int().min(0).default(1e5),
-  maxCities: import_zod3.z.number().int().min(1).max(100).default(25),
-  maxResultsPerCity: import_zod3.z.number().int().min(1).max(50).default(20),
-  hydrateTop: import_zod3.z.number().int().min(0).max(10).default(5),
-  maxReviews: import_zod3.z.number().int().min(0).max(500).default(50),
-  concurrency: import_zod3.z.number().int().min(1).max(5).default(5),
-  proxyMode: import_zod3.z.enum(["location", "configured", "none"]).default("location"),
-  returnPartial: import_zod3.z.boolean().default(true)
+var import_zod4 = require("zod");
+var LocalCompetitiveAuditInputSchema = import_zod4.z.object({
+  query: import_zod4.z.string().min(1),
+  state: import_zod4.z.string().min(2).default("TN"),
+  minPopulation: import_zod4.z.number().int().min(0).default(1e5),
+  maxCities: import_zod4.z.number().int().min(1).max(100).default(25),
+  maxResultsPerCity: import_zod4.z.number().int().min(1).max(50).default(20),
+  hydrateTop: import_zod4.z.number().int().min(0).max(10).default(5),
+  maxReviews: import_zod4.z.number().int().min(0).max(500).default(50),
+  concurrency: import_zod4.z.number().int().min(1).max(5).default(5),
+  proxyMode: import_zod4.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  returnPartial: import_zod4.z.boolean().default(true)
 });
 async function mapLimit(items, limit, fn) {
   const out = new Array(items.length);
@@ -1053,7 +1193,7 @@ ${summary}
 };
 
 // src/workflows/workflows/comparison-briefs.ts
-var import_zod4 = require("zod");
+var import_zod5 = require("zod");
 
 // src/workflows/workflows/seo-workflow-utils.ts
 var STOP_WORDS = /* @__PURE__ */ new Set([
@@ -1211,49 +1351,49 @@ async function mapLimit2(items, limit, fn) {
 }
 
 // src/workflows/workflows/comparison-briefs.ts
-var ProxyModeSchema = import_zod4.z.enum(["location", "configured", "none"]);
-var MapComparisonInputSchema = import_zod4.z.object({
-  query: import_zod4.z.string().min(1),
-  location: import_zod4.z.string().optional(),
-  state: import_zod4.z.string().optional(),
-  minPopulation: import_zod4.z.number().int().min(0).default(1e5),
-  maxCities: import_zod4.z.number().int().min(1).max(100).default(5),
-  maxResultsPerCity: import_zod4.z.number().int().min(1).max(50).default(20),
-  hydrateTop: import_zod4.z.number().int().min(0).max(10).default(5),
-  maxReviews: import_zod4.z.number().int().min(0).max(500).default(25),
-  concurrency: import_zod4.z.number().int().min(1).max(5).default(5),
-  proxyMode: ProxyModeSchema.default("location"),
-  returnPartial: import_zod4.z.boolean().default(true)
+var ProxyModeSchema = import_zod5.z.enum(["location", "configured", "none"]);
+var MapComparisonInputSchema = import_zod5.z.object({
+  query: import_zod5.z.string().min(1),
+  location: import_zod5.z.string().optional(),
+  state: import_zod5.z.string().optional(),
+  minPopulation: import_zod5.z.number().int().min(0).default(1e5),
+  maxCities: import_zod5.z.number().int().min(1).max(100).default(5),
+  maxResultsPerCity: import_zod5.z.number().int().min(1).max(50).default(20),
+  hydrateTop: import_zod5.z.number().int().min(0).max(10).default(5),
+  maxReviews: import_zod5.z.number().int().min(0).max(500).default(25),
+  concurrency: import_zod5.z.number().int().min(1).max(5).default(5),
+  proxyMode: ProxyModeSchema.default(DEFAULT_MAPS_PROXY_MODE),
+  returnPartial: import_zod5.z.boolean().default(true)
 }).refine((input) => input.location || input.state, {
   message: "Either location or state is required for map-comparison"
 });
-var SerpComparisonInputSchema = import_zod4.z.object({
-  keyword: import_zod4.z.string().min(1),
-  domain: import_zod4.z.string().optional(),
-  url: import_zod4.z.string().url().optional(),
-  location: import_zod4.z.string().optional(),
-  maxResults: import_zod4.z.number().int().min(1).max(20).default(10),
-  maxQuestions: import_zod4.z.number().int().min(1).max(200).default(40),
-  extractTop: import_zod4.z.number().int().min(0).max(10).default(5),
-  includePaa: import_zod4.z.boolean().default(true),
-  includeAiOverview: import_zod4.z.boolean().default(true),
-  returnPartial: import_zod4.z.boolean().default(true)
+var SerpComparisonInputSchema = import_zod5.z.object({
+  keyword: import_zod5.z.string().min(1),
+  domain: import_zod5.z.string().optional(),
+  url: import_zod5.z.string().url().optional(),
+  location: import_zod5.z.string().optional(),
+  maxResults: import_zod5.z.number().int().min(1).max(20).default(10),
+  maxQuestions: import_zod5.z.number().int().min(1).max(200).default(40),
+  extractTop: import_zod5.z.number().int().min(0).max(10).default(5),
+  includePaa: import_zod5.z.boolean().default(true),
+  includeAiOverview: import_zod5.z.boolean().default(true),
+  returnPartial: import_zod5.z.boolean().default(true)
 });
-var PaaExpansionBriefInputSchema = import_zod4.z.object({
-  keyword: import_zod4.z.string().min(1),
-  location: import_zod4.z.string().optional(),
-  maxQuestions: import_zod4.z.number().int().min(1).max(300).default(80),
-  depth: import_zod4.z.number().int().min(1).max(6).default(3),
-  returnPartial: import_zod4.z.boolean().default(true)
+var PaaExpansionBriefInputSchema = import_zod5.z.object({
+  keyword: import_zod5.z.string().min(1),
+  location: import_zod5.z.string().optional(),
+  maxQuestions: import_zod5.z.number().int().min(1).max(300).default(80),
+  depth: import_zod5.z.number().int().min(1).max(6).default(3),
+  returnPartial: import_zod5.z.boolean().default(true)
 });
-var AiOverviewLanguageInputSchema = import_zod4.z.object({
-  keyword: import_zod4.z.string().min(1),
-  domain: import_zod4.z.string().optional(),
-  url: import_zod4.z.string().url().optional(),
-  location: import_zod4.z.string().optional(),
-  maxQuestions: import_zod4.z.number().int().min(1).max(200).default(40),
-  extractTop: import_zod4.z.number().int().min(0).max(8).default(3),
-  returnPartial: import_zod4.z.boolean().default(true)
+var AiOverviewLanguageInputSchema = import_zod5.z.object({
+  keyword: import_zod5.z.string().min(1),
+  domain: import_zod5.z.string().optional(),
+  url: import_zod5.z.string().url().optional(),
+  location: import_zod5.z.string().optional(),
+  maxQuestions: import_zod5.z.number().int().min(1).max(200).default(40),
+  extractTop: import_zod5.z.number().int().min(0).max(8).default(3),
+  returnPartial: import_zod5.z.boolean().default(true)
 });
 function businessRowsFromMaps(location, query, results) {
   return results.map((result) => ({
@@ -1769,22 +1909,36 @@ function workflowDefinition(id) {
   if (!definition) throw new Error(`Unknown workflow "${id}". Available: ${DEFINITIONS.map((def) => def.id).join(", ")}`);
   return definition;
 }
+function resolveApiKey(options) {
+  const apiKey = options.apiKey?.trim() || process.env.MCP_SCRAPER_API_KEY?.trim();
+  if (!apiKey) throw new Error("MCP_SCRAPER_API_KEY is required for workflow runs. Pass --api-key or set the environment variable.");
+  return apiKey;
+}
+function resolveApiUrl(options) {
+  return options.apiUrl?.trim() || process.env.MCP_SCRAPER_API_URL?.trim() || "https://mcpscraper.dev";
+}
 async function runWorkflow(id, rawInput, options = {}) {
   const definition = workflowDefinition(id);
   const input = definition.inputSchema.parse(rawInput);
-  const apiKey = options.apiKey?.trim() || process.env.MCP_SCRAPER_API_KEY?.trim();
-  if (!apiKey) throw new Error("MCP_SCRAPER_API_KEY is required for workflow runs. Pass --api-key or set the environment variable.");
-  const apiUrl = options.apiUrl?.trim() || process.env.MCP_SCRAPER_API_URL?.trim() || "https://mcpscraper.dev";
+  const apiKey = resolveApiKey(options);
+  const apiUrl = resolveApiUrl(options);
   const artifacts = await ArtifactWriter.create(definition.id, definition.title, input, options.outputDir, options.runId);
   const client = new WorkflowHttpClient(apiUrl, apiKey, options.fetchImpl, options.headers);
+  const ctx = { runId: artifacts.runId, startedAt: artifacts.startedAt, client, artifacts, signal: options.signal };
   try {
-    return await definition.run(input, {
-      runId: artifacts.runId,
-      startedAt: artifacts.startedAt,
-      client,
-      artifacts,
-      signal: options.signal
-    });
+    if (definition.steps && definition.steps.length > 0) {
+      let state = definition.createState ? definition.createState(input) : {};
+      let summary = null;
+      for (const step of definition.steps) {
+        const outcome = await step.run({ input, state, ctx });
+        state = outcome.state;
+        if (outcome.summary) summary = outcome.summary;
+      }
+      if (!summary) throw new Error(`Workflow "${id}" produced no terminal step summary`);
+      return summary;
+    }
+    if (definition.run) return await definition.run(input, ctx);
+    throw new Error(`Workflow "${id}" has neither steps nor a run() implementation`);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     await artifacts.writeText("Failure", "summary.md", `# ${definition.title}
@@ -2038,13 +2192,13 @@ ${summary.warnings.map((w) => `- ${w}`).join("\n")}` : ""
     const result = await apiRequest(`/workflows/runs/${id}`, "GET", opts);
     const { apiUrl, apiKey } = apiOptions(opts);
     const outDir = (0, import_node_path3.join)(opts.outputDir ?? workflowOutputBaseDir(), "workflow-downloads", id);
-    await (0, import_promises3.mkdir)(outDir, { recursive: true });
+    await (0, import_promises4.mkdir)(outDir, { recursive: true });
     const downloaded = [];
     for (const artifact of result.run.artifacts ?? []) {
       const res = await fetch(`${apiUrl}/workflows/runs/${id}/artifacts/${artifact.id}`, { headers: { "x-api-key": apiKey } });
       if (!res.ok) throw new Error(`Failed to download ${artifact.label}: HTTP ${res.status}`);
       const file = (0, import_node_path3.join)(outDir, (0, import_node_path3.basename)(artifact.path));
-      await (0, import_promises3.writeFile)(file, Buffer.from(await res.arrayBuffer()));
+      await (0, import_promises4.writeFile)(file, Buffer.from(await res.arrayBuffer()));
       downloaded.push(file);
     }
     writeOutput(opts.json ? { runId: id, files: downloaded } : downloaded.join("\n"), opts.json);