mcp-scraper 0.2.5 → 0.2.7

package/dist/bin/api-server.cjs

@@ -17082,12 +17082,12 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.2.5";
+    PACKAGE_VERSION = "0.2.7";
   }
 });
 
 // src/mcp/mcp-tool-schemas.ts
-var import_zod20, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, NullableString, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, CreditsInfoInputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
+var import_zod20, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, CreditsInfoInputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
 var init_mcp_tool_schemas = __esm({
   "src/mcp/mcp-tool-schemas.ts"() {
     "use strict";
@@ -17177,6 +17177,24 @@ var init_mcp_tool_schemas = __esm({
       proxyZip: import_zod20.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting. Normally omit it so each city can use its Lead Magician ZIP group or city/state location."),
       debug: import_zod20.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics in each Maps browser session when supported.")
     };
+    RankTrackerModeSchema = import_zod20.z.enum(["maps", "organic", "ai_overview", "paa"]);
+    RankTrackerBlueprintInputSchema = {
+      projectName: import_zod20.z.string().min(1).optional().describe("Optional name for the rank tracker project, client, or campaign."),
+      targetDomain: import_zod20.z.string().min(1).optional().describe("Primary domain to track in organic results, AI Overview citations, and PAA sources, e.g. example.com."),
+      targetBusinessName: import_zod20.z.string().min(1).optional().describe("Primary Google Business Profile or brand/business name to match in Maps results. Required for reliable Maps rank tracking."),
+      trackingModes: import_zod20.z.array(RankTrackerModeSchema).min(1).max(4).default(["maps", "organic", "ai_overview", "paa"]).describe("Rank tracker surfaces to build. maps uses directory_workflow/maps_search. organic uses search_serp. ai_overview uses search_serp/harvest_paa. paa uses harvest_paa source presence."),
+      keywords: import_zod20.z.array(import_zod20.z.string().min(1)).max(200).default([]).describe("Seed keywords or service queries to track. Leave empty when the downstream AI should create the keyword table from user input."),
+      locations: import_zod20.z.array(import_zod20.z.string().min(1)).max(100).default([]).describe("Markets, cities, ZIPs, or service areas to track. Use city/state strings like Denver, CO for localized SERP and Maps checks."),
+      competitors: import_zod20.z.array(import_zod20.z.string().min(1)).max(100).default([]).describe("Optional competitor domains or business names to persist as comparison targets."),
+      database: import_zod20.z.enum(["postgres", "neon", "supabase", "sqlite", "mysql"]).default("postgres").describe("Database family the downstream AI should target when generating migrations."),
+      scheduleCadence: import_zod20.z.enum(["daily", "weekly", "monthly", "custom"]).default("weekly").describe("Default recurring rank check cadence for the generated cron/heartbeat plan."),
+      customCron: import_zod20.z.string().min(1).optional().describe("Cron expression to use when scheduleCadence is custom."),
+      timezone: import_zod20.z.string().min(1).default("UTC").describe("IANA timezone for scheduled rank checks, e.g. America/Denver."),
+      includeCron: import_zod20.z.boolean().default(true).describe("Include a cron or heartbeat worker plan. Keep true for production rank trackers."),
+      includeDashboard: import_zod20.z.boolean().default(true).describe("Include dashboard/reporting requirements in the generated prompt."),
+      includeAlerts: import_zod20.z.boolean().default(true).describe("Include alert rules for rank movement and SERP feature gains/losses."),
+      notes: import_zod20.z.string().max(4e3).optional().describe("Extra product, client, stack, or hosting requirements to include in the implementation prompt.")
+    };
     NullableString = import_zod20.z.string().nullable();
     MapsSearchOutputSchema = {
       query: import_zod20.z.string(),
@@ -17252,6 +17270,39 @@ var init_mcp_tool_schemas = __esm({
       })),
       durationMs: import_zod20.z.number().int().min(0)
     };
+    RankTrackerToolPlanOutput = import_zod20.z.object({
+      tool: import_zod20.z.string(),
+      purpose: import_zod20.z.string()
+    });
+    RankTrackerTableOutput = import_zod20.z.object({
+      name: import_zod20.z.string(),
+      purpose: import_zod20.z.string(),
+      keyColumns: import_zod20.z.array(import_zod20.z.string())
+    });
+    RankTrackerCronJobOutput = import_zod20.z.object({
+      name: import_zod20.z.string(),
+      purpose: import_zod20.z.string(),
+      modes: import_zod20.z.array(RankTrackerModeSchema),
+      recommendedTools: import_zod20.z.array(import_zod20.z.string())
+    });
+    RankTrackerBlueprintOutputSchema = {
+      projectName: import_zod20.z.string(),
+      targetDomain: NullableString,
+      targetBusinessName: NullableString,
+      trackingModes: import_zod20.z.array(RankTrackerModeSchema),
+      database: import_zod20.z.string(),
+      recommendedTools: import_zod20.z.array(RankTrackerToolPlanOutput),
+      tables: import_zod20.z.array(RankTrackerTableOutput),
+      cron: import_zod20.z.object({
+        enabled: import_zod20.z.boolean(),
+        cadence: import_zod20.z.string(),
+        expression: import_zod20.z.string(),
+        timezone: import_zod20.z.string(),
+        jobs: import_zod20.z.array(RankTrackerCronJobOutput)
+      }),
+      metrics: import_zod20.z.array(import_zod20.z.string()),
+      implementationPrompt: import_zod20.z.string()
+    };
     OrganicResultOutput = import_zod20.z.object({
       position: import_zod20.z.number().int(),
       title: import_zod20.z.string(),
@@ -17468,6 +17519,335 @@ var init_mcp_tool_schemas = __esm({
   }
 });
 
+// src/mcp/rank-tracker-blueprint.ts
+function normalizeDomain(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  try {
+    const url = new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`);
+    return url.hostname.replace(/^www\./, "").toLowerCase();
+  } catch {
+    return trimmed.replace(/^https?:\/\//, "").replace(/^www\./, "").split("/")[0]?.toLowerCase() || trimmed;
+  }
+}
+function uniqueModes(input) {
+  const modes = input?.length ? input : DEFAULT_MODES;
+  return [...new Set(modes)];
+}
+function cronExpression(cadence, customCron) {
+  if (cadence === "daily") return "15 6 * * *";
+  if (cadence === "monthly") return "15 6 1 * *";
+  if (cadence === "custom") return customCron?.trim() || "CUSTOM_CRON_EXPRESSION_REQUIRED";
+  return "15 6 * * 1";
+}
+function includes(modes, mode) {
+  return modes.includes(mode);
+}
+function buildToolPlan(modes) {
+  const plans = [];
+  const push = (tool, purpose) => {
+    if (!plans.some((plan) => plan.tool === tool)) plans.push({ tool, purpose });
+  };
+  push("credits_info", "Check account balance and rates before scheduling recurring rank checks.");
+  if (includes(modes, "maps")) {
+    push("directory_workflow", "Seed or refresh city-by-city Maps datasets when building local market coverage.");
+    push("maps_search", "Run recurring Google Maps category checks for each keyword and location.");
+    push("maps_place_intel", "Hydrate selected target or competitor GBP details when profile-level evidence is needed.");
+  }
+  if (includes(modes, "organic")) {
+    push("search_serp", "Capture localized organic rankings, local pack data, and AI Overview status without PAA expansion.");
+  }
+  if (includes(modes, "ai_overview")) {
+    push("search_serp", "Capture quick AI Overview detection and organic context for each tracked query.");
+    push("harvest_paa", "Use when AI Overview text, PAA context, or source-level evidence needs deeper capture.");
+  }
+  if (includes(modes, "paa")) {
+    push("harvest_paa", "Capture People Also Ask questions, answers, and source sites for PAA presence tracking.");
+  }
+  return plans;
+}
+function buildTables(modes, includeDashboard, includeAlerts, hasCompetitors) {
+  const tables = [
+    {
+      name: "rank_tracker_projects",
+      purpose: "One row per client, campaign, or tracked property.",
+      keyColumns: ["id", "name", "target_domain", "target_business_name", "database_mode", "timezone", "created_at"]
+    },
+    {
+      name: "rank_tracker_targets",
+      purpose: "Normalized target identities and match rules for domains, URLs, business names, CIDs, and competitors.",
+      keyColumns: ["id", "project_id", "kind", "value", "display_name", "match_rules_json", "active"]
+    },
+    {
+      name: "rank_tracker_keywords",
+      purpose: "Tracked keywords or service queries, separated from location so calls can localize correctly.",
+      keyColumns: ["id", "project_id", "keyword", "intent", "tags_json", "active"]
+    },
+    {
+      name: "rank_tracker_locations",
+      purpose: "Markets, cities, ZIPs, country/language settings, and proxy targeting hints.",
+      keyColumns: ["id", "project_id", "label", "gl", "hl", "proxy_zip", "device", "active"]
+    },
+    {
+      name: "rank_tracker_runs",
+      purpose: "Heartbeat table for every scheduled or manual rank check batch.",
+      keyColumns: ["id", "project_id", "scheduled_for", "started_at", "completed_at", "status", "idempotency_key", "error_message"]
+    }
+  ];
+  if (includes(modes, "organic")) {
+    tables.push({
+      name: "rank_tracker_organic_results",
+      purpose: "SERP organic result rows from search_serp, including target-domain matches and competitor rows.",
+      keyColumns: ["id", "run_id", "keyword_id", "location_id", "device", "position", "title", "url", "domain", "is_target"]
+    });
+  }
+  if (includes(modes, "maps")) {
+    tables.push({
+      name: "rank_tracker_maps_results",
+      purpose: "Google Maps result rows from maps_search and directory_workflow, including GBP identity fields.",
+      keyColumns: ["id", "run_id", "keyword_id", "location_id", "position", "business_name", "place_url", "cid", "website_url", "rating", "review_count", "is_target"]
+    });
+    tables.push({
+      name: "rank_tracker_market_seeds",
+      purpose: "Directory workflow city, population, ZIP-group, and market seed records used to build local tracking coverage.",
+      keyColumns: ["id", "project_id", "query", "city", "state", "population", "zip_group_json", "last_seeded_run_id"]
+    });
+  }
+  if (includes(modes, "ai_overview")) {
+    tables.push({
+      name: "rank_tracker_ai_overviews",
+      purpose: "AI Overview detection, text snapshot, citation domains, and target citation status per query/location.",
+      keyColumns: ["id", "run_id", "keyword_id", "location_id", "detected", "target_cited", "cited_domains_json", "overview_text"]
+    });
+  }
+  if (includes(modes, "paa")) {
+    tables.push({
+      name: "rank_tracker_paa_sources",
+      purpose: "People Also Ask questions, answers, and source sites, with target source presence flags.",
+      keyColumns: ["id", "run_id", "keyword_id", "location_id", "question", "answer", "source_title", "source_site", "target_present"]
+    });
+  }
+  if (hasCompetitors) {
+    tables.push({
+      name: "rank_tracker_competitor_snapshots",
+      purpose: "Per-run competitor visibility summaries across organic, Maps, AI Overview, and PAA surfaces.",
+      keyColumns: ["id", "run_id", "target_id", "surface", "best_position", "presence_count", "share_of_surface"]
+    });
+  }
+  if (includeDashboard) {
+    tables.push({
+      name: "rank_tracker_daily_metrics",
+      purpose: "Rollup table for dashboard charts, trend lines, and share-of-visibility summaries.",
+      keyColumns: ["id", "project_id", "metric_date", "keyword_id", "location_id", "surface", "metric_name", "metric_value"]
+    });
+  }
+  if (includeAlerts) {
+    tables.push({
+      name: "rank_tracker_alert_events",
+      purpose: "Deduplicated gain/loss events for rank movement, Maps top 3, AI Overview citations, and PAA source presence.",
+      keyColumns: ["id", "project_id", "run_id", "surface", "severity", "event_key", "message", "created_at", "acknowledged_at"]
+    });
+  }
+  return tables;
+}
+function buildCronJobs(modes, includeDashboard, includeAlerts) {
+  const jobs = [
+    {
+      name: "rank-tracker-dispatch",
+      purpose: "Find due keyword/location/mode combinations, create a rank_tracker_runs row, and enqueue idempotent work items.",
+      modes,
+      recommendedTools: ["credits_info"]
+    }
+  ];
+  if (includes(modes, "maps")) {
+    jobs.push({
+      name: "maps-rank-check",
+      purpose: "Run maps_search per keyword/location and optionally directory_workflow for market seed refreshes.",
+      modes: ["maps"],
+      recommendedTools: ["maps_search", "directory_workflow", "maps_place_intel"]
+    });
+  }
+  if (includes(modes, "organic") || includes(modes, "ai_overview")) {
+    jobs.push({
+      name: "serp-rank-check",
+      purpose: "Run search_serp per keyword/location/device and persist organic ranks, local pack, and AI Overview status.",
+      modes: modes.filter((mode) => mode === "organic" || mode === "ai_overview"),
+      recommendedTools: ["search_serp"]
+    });
+  }
+  if (includes(modes, "paa") || includes(modes, "ai_overview")) {
+    jobs.push({
+      name: "paa-ai-evidence-check",
+      purpose: "Run harvest_paa for PAA source presence and deeper AI Overview/PAA evidence where needed.",
+      modes: modes.filter((mode) => mode === "paa" || mode === "ai_overview"),
+      recommendedTools: ["harvest_paa"]
+    });
+  }
+  if (includeDashboard) {
+    jobs.push({
+      name: "rank-tracker-rollups",
+      purpose: "Aggregate raw rows into daily metrics for charts, comparison tables, and trend lines.",
+      modes,
+      recommendedTools: []
+    });
+  }
+  if (includeAlerts) {
+    jobs.push({
+      name: "rank-tracker-alerts",
+      purpose: "Compare latest run against prior snapshots and emit deduplicated visibility gain/loss events.",
+      modes,
+      recommendedTools: []
+    });
+  }
+  return jobs;
+}
+function buildMetrics(modes, includeDashboard, includeAlerts) {
+  const metrics = ["run_success_rate", "last_successful_run_at", "stale_keyword_location_count"];
+  if (includes(modes, "maps")) {
+    metrics.push("maps_best_position", "maps_top_3_presence", "maps_target_found", "maps_competitor_count_above_target");
+  }
+  if (includes(modes, "organic")) {
+    metrics.push("organic_best_position", "organic_top_3_presence", "organic_top_10_presence", "organic_best_url");
+  }
+  if (includes(modes, "ai_overview")) {
+    metrics.push("ai_overview_detected", "target_ai_overview_cited", "ai_overview_citation_domain_count");
+  }
+  if (includes(modes, "paa")) {
+    metrics.push("paa_question_count", "target_paa_source_count", "paa_presence_rate", "paa_source_domains");
+  }
+  if (includeDashboard) metrics.push("share_of_visibility", "position_delta_7d", "position_delta_30d");
+  if (includeAlerts) metrics.push("visibility_gain_events", "visibility_loss_events");
+  return metrics;
+}
+function listOrPlaceholder(values, fallback) {
+  const clean2 = values?.map((value) => value.trim()).filter(Boolean) ?? [];
+  if (!clean2.length) return fallback;
+  return clean2.map((value) => `- ${value}`).join("\n");
+}
+function buildPrompt(input, modes, tools, tables, jobs, metrics, expression, targetDomain, targetBusinessName) {
+  const keywords = listOrPlaceholder(input.keywords, "- TODO: add tracked keywords");
+  const locations = listOrPlaceholder(input.locations, "- TODO: add tracked markets/locations");
+  const competitors = listOrPlaceholder(input.competitors, "- Optional: add competitor domains or GBP names");
+  const notes = input.notes?.trim() || "No extra implementation notes.";
+  return [
+    "You are building a production rank tracker powered by MCP Scraper. Create the database migrations, scheduled worker, ingestion functions, and dashboard/query layer described below.",
+    "",
+    `Project: ${input.projectName || "MCP Scraper Rank Tracker"}`,
+    `Target domain: ${targetDomain || "TODO_TARGET_DOMAIN"}`,
+    `Target business/GBP name: ${targetBusinessName || "TODO_TARGET_BUSINESS_NAME"}`,
+    `Database target: ${input.database || "postgres"}`,
+    `Tracking modes: ${modes.join(", ")}`,
+    "",
+    "Seed keywords:",
+    keywords,
+    "",
+    "Seed locations:",
+    locations,
+    "",
+    "Competitors:",
+    competitors,
+    "",
+    "MCP Scraper calls to use:",
+    tools.map((tool) => `- ${tool.tool}: ${tool.purpose}`).join("\n"),
+    "",
+    "Database tables to create:",
+    tables.map((table) => `- ${table.name}: ${table.keyColumns.join(", ")}`).join("\n"),
+    "",
+    "Scheduler and heartbeat requirements:",
+    `- Use cron expression "${expression}" in timezone "${input.timezone || "UTC"}" unless the user changes cadence.`,
+    "- Every scheduled batch must insert or update rank_tracker_runs before calling MCP tools.",
+    "- Use idempotency_key = project_id + keyword_id + location_id + mode + device + scheduled_date.",
+    "- Mark runs as running, succeeded, failed, or skipped; persist error_message on failures.",
+    "- Run MCP calls sequentially by default because accounts have one concurrency slot unless the user bought more.",
+    "- Retry retryable upstream failures with backoff, but do not duplicate rows for the same idempotency key.",
+    "",
+    "Mode-specific ingestion rules:",
+    "- maps: Use directory_workflow to seed/refresh market coverage and maps_search for recurring keyword/location rank checks. Match the target by targetBusinessName, website domain, CID, and place URL when available.",
+    "- organic: Use search_serp and persist every organic result row. Compute the best targetDomain position and best ranking URL per keyword/location/device.",
+    "- ai_overview: Use search_serp for quick detection and harvest_paa when deeper text/source evidence is needed. Track detected, overview_text, cited domains, and whether targetDomain is cited.",
+    "- paa: Use harvest_paa and persist each question/source pair. Track whether sourceSite or answer/source evidence matches targetDomain, then compute PAA presence rate.",
+    "",
+    "Metrics to expose:",
+    metrics.map((metric) => `- ${metric}`).join("\n"),
+    "",
+    "Alert requirements:",
+    input.includeAlerts ? "- Emit deduplicated alert_events when target gains/loses Maps top 3, organic top 10, AI Overview citation, or PAA source presence." : "- Alerts are out of scope for this build unless the user asks for them.",
+    "",
+    "Dashboard requirements:",
+    input.includeDashboard ? "- Build views for latest position by keyword/location, trend deltas, competitors above target, AI Overview citations, and PAA source wins/losses." : "- Dashboard is out of scope for this build unless the user asks for it.",
+    "",
+    "Extra notes:",
+    notes
+  ].join("\n");
+}
+function buildRankTrackerBlueprint(input) {
+  const trackingModes = uniqueModes(input.trackingModes);
+  const targetDomain = normalizeDomain(input.targetDomain);
+  const targetBusinessName = input.targetBusinessName?.trim() || null;
+  const projectName = input.projectName?.trim() || "MCP Scraper Rank Tracker";
+  const database = input.database || "postgres";
+  const expression = cronExpression(input.scheduleCadence || "weekly", input.customCron);
+  const tools = buildToolPlan(trackingModes);
+  const tables = buildTables(trackingModes, input.includeDashboard !== false, input.includeAlerts !== false, Boolean(input.competitors?.length));
+  const jobs = input.includeCron === false ? [] : buildCronJobs(trackingModes, input.includeDashboard !== false, input.includeAlerts !== false);
+  const metrics = buildMetrics(trackingModes, input.includeDashboard !== false, input.includeAlerts !== false);
+  const implementationPrompt = buildPrompt(input, trackingModes, tools, tables, jobs, metrics, expression, targetDomain, targetBusinessName);
+  const blueprint = {
+    projectName,
+    targetDomain,
+    targetBusinessName,
+    trackingModes,
+    database,
+    recommendedTools: tools,
+    tables,
+    cron: {
+      enabled: input.includeCron !== false,
+      cadence: input.scheduleCadence || "weekly",
+      expression: input.includeCron === false ? "disabled" : expression,
+      timezone: input.timezone || "UTC",
+      jobs
+    },
+    metrics,
+    implementationPrompt
+  };
+  const text = [
+    `# ${projectName}`,
+    "",
+    "Rank tracker build blueprint generated from MCP Scraper tool capabilities.",
+    "",
+    "## Modes",
+    trackingModes.map((mode) => `- ${mode}`).join("\n"),
+    "",
+    "## Recommended MCP Tools",
+    tools.map((tool) => `- \`${tool.tool}\` - ${tool.purpose}`).join("\n"),
+    "",
+    "## Database Tables",
+    tables.map((table) => `- \`${table.name}\` - ${table.purpose}`).join("\n"),
+    "",
+    "## Cron / Heartbeat",
+    blueprint.cron.enabled ? `- Cadence: ${blueprint.cron.cadence}
+- Cron: \`${blueprint.cron.expression}\`
+- Timezone: ${blueprint.cron.timezone}
+- Jobs: ${jobs.map((job) => job.name).join(", ")}` : "- Disabled by input. Still create rank_tracker_runs for manual runs.",
+    "",
+    "## Implementation Prompt",
+    "```text",
+    implementationPrompt,
+    "```"
+  ].join("\n");
+  return {
+    content: [{ type: "text", text }],
+    structuredContent: blueprint
+  };
+}
+var DEFAULT_MODES;
+var init_rank_tracker_blueprint = __esm({
+  "src/mcp/rank-tracker-blueprint.ts"() {
+    "use strict";
+    DEFAULT_MODES = ["maps", "organic", "ai_overview", "paa"];
+  }
+});
+
 // src/mcp/paa-mcp-server.ts
 function liveWebToolAnnotations(title) {
   return {
@@ -17478,6 +17858,15 @@ function liveWebToolAnnotations(title) {
     openWorldHint: true
   };
 }
+function localPlanningToolAnnotations(title) {
+  return {
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  };
+}
 function listSavedReports() {
   try {
     const dir = outputBaseDir();
@@ -17611,6 +18000,13 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
     outputSchema: DirectoryWorkflowOutputSchema,
     annotations: liveWebToolAnnotations("Directory Workflow: Markets + Maps")
   }, async (input) => formatDirectoryWorkflow(await executor.directoryWorkflow(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.",
+    inputSchema: RankTrackerBlueprintInputSchema,
+    outputSchema: RankTrackerBlueprintOutputSchema,
+    annotations: localPlanningToolAnnotations("Rank Tracker Blueprint Builder")
+  }, async (input) => buildRankTrackerBlueprint(input));
   server.registerTool("credits_info", {
     title: "MCP Scraper Credits & Costs",
     description: "Answer questions about MCP Scraper credits: current credit balance, what a specific tool/action costs, the full cost table, and optionally recent credit ledger entries. Does not expose payment methods or credit card information.",
@@ -17635,6 +18031,7 @@ var init_paa_mcp_server = __esm({
     init_version();
     init_mcp_response_formatter();
     init_mcp_tool_schemas();
+    init_rank_tracker_blueprint();
     init_mcp_response_formatter();
   }
 });
@@ -17954,18 +18351,26 @@ async function recordAction(input) {
 async function recordReplayStart(input) {
   const db = getDb();
   await db.execute({
-    sql: `INSERT INTO browser_agent_replays (replay_id, session_id, view_url, label)
-          VALUES (?, ?, ?, ?)`,
-    args: [input.replayId, input.sessionId, input.viewUrl, input.label]
+    sql: `INSERT INTO browser_agent_replays (replay_id, session_id, view_url, label, started_at)
+          VALUES (?, ?, ?, ?, ?)`,
+    args: [input.replayId, input.sessionId, input.viewUrl, input.label, (/* @__PURE__ */ new Date()).toISOString()]
   });
 }
 async function recordReplayStop(replayId, viewUrl) {
   const db = getDb();
   await db.execute({
-    sql: `UPDATE browser_agent_replays SET stopped_at = datetime('now'), view_url = COALESCE(?, view_url) WHERE replay_id = ?`,
-    args: [viewUrl, replayId]
+    sql: `UPDATE browser_agent_replays SET stopped_at = ?, view_url = COALESCE(?, view_url) WHERE replay_id = ?`,
+    args: [(/* @__PURE__ */ new Date()).toISOString(), viewUrl, replayId]
   });
 }
+async function getActiveReplayRow(sessionId) {
+  const db = getDb();
+  const res = await db.execute({
+    sql: `SELECT * FROM browser_agent_replays WHERE session_id = ? AND stopped_at IS NULL ORDER BY started_at DESC LIMIT 1`,
+    args: [sessionId]
+  });
+  return res.rows[0] ?? null;
+}
 async function listReplayRows(sessionId) {
   const db = getDb();
   const res = await db.execute({
@@ -18085,7 +18490,13 @@ async function readPage(cdpWsUrl) {
           role: el2.getAttribute("role") || el2.tagName.toLowerCase(),
           name,
           x: Math.round(r.left + r.width / 2),
-          y: Math.round(r.top + r.height / 2)
+          y: Math.round(r.top + r.height / 2),
+          left: Math.round(r.left),
+          top: Math.round(r.top),
+          width: Math.round(r.width),
+          height: Math.round(r.height),
+          right: Math.round(r.right),
+          bottom: Math.round(r.bottom)
         });
       }
       const text = (document.body?.innerText || "").replace(/\n{3,}/g, "\n\n").trim().slice(0, 6e3);
@@ -18095,13 +18506,168 @@ async function readPage(cdpWsUrl) {
       url,
       title,
       text: data.text,
-      elements: data.els.map((e, i) => ({ ref: i + 1, role: e.role, name: e.name, x: e.x, y: e.y }))
+      elements: data.els.map((e, i) => ({
+        ref: i + 1,
+        role: e.role,
+        name: e.name,
+        x: e.x,
+        y: e.y,
+        left: e.left,
+        top: e.top,
+        width: e.width,
+        height: e.height,
+        right: e.right,
+        bottom: e.bottom
+      }))
     };
   } finally {
     await browser.close().catch(() => {
     });
   }
 }
+async function locatePageTargets(cdpWsUrl, targets) {
+  const browser = await import_playwright4.chromium.connectOverCDP(cdpWsUrl);
+  try {
+    const context = browser.contexts()[0] ?? await browser.newContext();
+    const page = context.pages()[0] ?? await context.newPage();
+    const url = page.url();
+    const title = await page.title().catch(() => "");
+    await page.evaluate(() => {
+      ;
+      globalThis.__name = (target) => target;
+    }).catch(() => {
+    });
+    const data = await page.evaluate((rawTargets) => {
+      const normalize = (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(
+          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 unionRects = (rects) => {
+        const visible = rects.filter(isVisibleRect);
+        if (!visible.length) return null;
+        const left = Math.min(...visible.map((r) => r.left));
+        const top = Math.min(...visible.map((r) => r.top));
+        const right = Math.max(...visible.map((r) => r.right));
+        const bottom = Math.max(...visible.map((r) => r.bottom));
+        return {
+          left,
+          top,
+          right,
+          bottom,
+          width: right - left,
+          height: bottom - top,
+          x: left,
+          y: top,
+          toJSON: () => ({})
+        };
+      };
+      const elementPayload = (el2, rect) => ({
+        role: roleOf(el2),
+        tag: el2.tagName.toLowerCase(),
+        name: nameOf(el2),
+        text: textOf(el2),
+        x: Math.round(rect.left + rect.width / 2),
+        y: Math.round(rect.top + rect.height / 2),
+        left: Math.round(rect.left),
+        top: Math.round(rect.top),
+        width: Math.round(rect.width),
+        height: Math.round(rect.height),
+        right: Math.round(rect.right),
+        bottom: Math.round(rect.bottom)
+      });
+      const selectorMatches = (selector) => {
+        const nodes = Array.from(document.querySelectorAll(selector));
+        return nodes.map((el2) => ({ el: el2, rect: el2.getBoundingClientRect() })).filter((item) => isVisibleRect(item.rect));
+      };
+      const textMatches = (needle, match) => {
+        const wanted = normalize(needle);
+        const wantedLower = wanted.toLowerCase();
+        if (!wantedLower) return [];
+        const matches = [];
+        const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+        let node = walker.nextNode();
+        while (node) {
+          const raw = node.textContent || "";
+          const normalizedRaw = normalize(raw);
+          const rawLower = raw.toLowerCase();
+          const normalizedLower = normalizedRaw.toLowerCase();
+          const ok = match === "exact" ? normalizedLower === wantedLower : normalizedLower.includes(wantedLower);
+          if (ok) {
+            const start = match === "exact" ? 0 : rawLower.indexOf(wantedLower);
+            const parent = node.parentElement;
+            if (parent && start >= 0) {
+              try {
+                const range = document.createRange();
+                range.setStart(node, Math.min(start, raw.length));
+                range.setEnd(node, Math.min(raw.length, start + needle.length));
+                const rect = unionRects(Array.from(range.getClientRects()));
+                range.detach();
+                if (rect) matches.push({ el: parent, rect });
+              } catch {
+                const rect = parent.getBoundingClientRect();
+                if (isVisibleRect(rect)) matches.push({ el: parent, rect });
+              }
+            }
+          }
+          node = walker.nextNode();
+        }
+        if (matches.length) return matches;
+        const fallback = Array.from(document.querySelectorAll("body *")).map((el2) => ({ el: el2, rect: el2.getBoundingClientRect(), text: textOf(el2) })).filter((item) => isVisibleRect(item.rect)).filter((item) => {
+          const value = item.text.toLowerCase();
+          return match === "exact" ? value === wantedLower : value.includes(wantedLower);
+        }).sort((a, b) => a.rect.width * a.rect.height - b.rect.width * b.rect.height);
+        return fallback.map(({ el: el2, rect }) => ({ el: el2, rect }));
+      };
+      const viewport = {
+        width: window.innerWidth,
+        height: window.innerHeight,
+        devicePixelRatio: window.devicePixelRatio || 1
+      };
+      const results = rawTargets.map((target) => {
+        const index = Math.max(0, Math.floor(target.index ?? 0));
+        const match = target.match === "exact" ? "exact" : "contains";
+        try {
+          const selector = target.selector?.trim();
+          const text = target.text?.trim();
+          const candidates = selector ? selectorMatches(selector) : text ? textMatches(text, match) : [];
+          const selected = candidates[index];
+          return {
+            name: target.name ?? null,
+            selector: selector || null,
+            text: text || null,
+            match,
+            index,
+            found: Boolean(selected),
+            element: selected ? elementPayload(selected.el, selected.rect) : null,
+            ...selected ? {} : { error: "target not found in current viewport" }
+          };
+        } catch (err) {
+          return {
+            name: target.name ?? null,
+            selector: target.selector ?? null,
+            text: target.text ?? null,
+            match,
+            index,
+            found: false,
+            element: null,
+            error: err instanceof Error ? err.message : String(err)
+          };
+        }
+      });
+      return { viewport, targets: results };
+    }, targets);
+    return { url, title, viewport: data.viewport, targets: data.targets };
+  } finally {
+    await browser.close().catch(() => {
+    });
+  }
+}
 async function replayStart(runtimeSessionId) {
   const k = client();
   const res = await k.browsers.replays.start(runtimeSessionId);
@@ -18164,6 +18730,22 @@ function failure(err) {
   const msg = err instanceof Error ? err.message : String(err);
   return { error: sanitizeVendorName(msg) };
 }
+function parseAgentDate(value) {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  if (Number.isFinite(parsed)) return parsed;
+  const legacyParsed = Date.parse(`${value.replace(" ", "T")}Z`);
+  return Number.isFinite(legacyParsed) ? legacyParsed : null;
+}
+function replayClock(row) {
+  if (!row) return null;
+  const startedAtMs = parseAgentDate(row.started_at);
+  return {
+    replay_id: row.replay_id,
+    started_at: row.started_at,
+    replay_elapsed_seconds: startedAtMs == null ? null : Math.max(0, (Date.now() - startedAtMs) / 1e3)
+  };
+}
 function replayDownloadUrl(sessionId, replayId) {
   return `/agent/sessions/${encodeURIComponent(sessionId)}/replays/${encodeURIComponent(replayId)}/download`;
 }
@@ -18274,13 +18856,15 @@ function buildBrowserAgentRoutes() {
       }
       await charge(row.id, user.id, t0);
       await recordAction({ sessionId: row.id, type: "screenshot", params: null, ok: true });
+      const activeReplay = await getActiveReplayRow(row.id);
       return c.json({
         image_base64: shot.base64,
         mime_type: shot.mimeType,
         url: page?.url ?? null,
         title: page?.title ?? null,
         elements: page?.elements ?? [],
-        text: page?.text ?? null
+        text: page?.text ?? null,
+        replay: replayClock(activeReplay)
       });
     } catch (err) {
       await charge(row.id, user.id, t0);
@@ -18297,7 +18881,8 @@ function buildBrowserAgentRoutes() {
       const page = await readPage(row.cdp_ws_url);
       await charge(row.id, user.id, t0);
       await recordAction({ sessionId: row.id, type: "read", params: null, ok: true });
-      return c.json(page);
+      const activeReplay = await getActiveReplayRow(row.id);
+      return c.json({ ...page, replay: replayClock(activeReplay) });
     } catch (err) {
       await charge(row.id, user.id, t0);
       return c.json(failure(err), 502);
@@ -18326,6 +18911,27 @@ function buildBrowserAgentRoutes() {
       return c.json(failure(err), 502);
     }
   });
+  app2.post("/sessions/:id/locate", async (c) => {
+    const user = c.get("user");
+    const row = await loadOpenSession(c.req.param("id"), user.id);
+    if (!row) return c.json({ error: "not found" }, 404);
+    const body = await c.req.json().catch(() => ({}));
+    const rawTargets = Array.isArray(body.targets) ? body.targets : [];
+    const targets = rawTargets.filter((value) => value && typeof value === "object").slice(0, 20).map((value) => value);
+    if (!targets.length) return c.json({ error: "targets is required" }, 400);
+    const t0 = Date.now();
+    try {
+      const result = await locatePageTargets(row.cdp_ws_url, targets);
+      await charge(row.id, user.id, t0);
+      await recordAction({ sessionId: row.id, type: "locate", params: { targets: targets.length }, ok: true });
+      const activeReplay = await getActiveReplayRow(row.id);
+      return c.json({ ...result, replay: replayClock(activeReplay) });
+    } catch (err) {
+      await charge(row.id, user.id, t0);
+      await recordAction({ sessionId: row.id, type: "locate", params: { targets: targets.length }, ok: false, error: String(err) });
+      return c.json(failure(err), 502);
+    }
+  });
   app2.post("/sessions/:id/type", async (c) => {
     const user = c.get("user");
     const row = await loadOpenSession(c.req.param("id"), user.id);