pagesight 0.17.0 → 0.19.0

package/src/tools/search/inspection.ts

@@ -0,0 +1,160 @@
+import { type InspectionResult, inspectUrl } from "../../providers/gsc.js";
+import { type SearchOptions } from "./schema.js";
+import { textResult } from "./result.js";
+function formatInspection(url: string, siteUrl: string, r: InspectionResult): string {
+  const idx = r.indexStatusResult;
+  const lines: string[] = [
+    `=== URL Inspection: ${url} ===`,
+    `Property: ${siteUrl}`,
+    "",
+    "--- Index Status ---",
+    "",
+    `Verdict: ${idx.verdict}`,
+    `Coverage: ${idx.coverageState}`,
+    `Page fetch: ${idx.pageFetchState}`,
+    `Robots.txt: ${idx.robotsTxtState}`,
+    `Indexing: ${idx.indexingState}`,
+    `Crawled as: ${idx.crawledAs ?? "unknown"}`,
+  ];
+
+  if (idx.lastCrawlTime) lines.push(`Last crawled: ${idx.lastCrawlTime}`);
+  if (idx.userCanonical) lines.push(`Your canonical: ${idx.userCanonical}`);
+  if (idx.googleCanonical) lines.push(`Google's canonical: ${idx.googleCanonical}`);
+
+  if (idx.userCanonical && idx.googleCanonical && idx.userCanonical !== idx.googleCanonical) {
+    lines.push(`\n⚠ CANONICAL MISMATCH: You declared "${idx.userCanonical}" but Google chose "${idx.googleCanonical}"`);
+  }
+
+  if (idx.sitemap && idx.sitemap.length > 0) {
+    lines.push(`\nSitemaps: ${idx.sitemap.join(", ")}`);
+  }
+
+  if (idx.referringUrls && idx.referringUrls.length > 0) {
+    lines.push(`\nReferring URLs: ${idx.referringUrls.join(", ")}`);
+  }
+
+  if (idx.verdict !== "PASS") {
+    const gscUrl = `https://search.google.com/search-console/inspect?resource_id=${encodeURIComponent(siteUrl)}&id=${encodeURIComponent(url)}`;
+    lines.push("", "→ This page is not indexed. Request indexing manually in Google Search Console:", `  ${gscUrl}`);
+  }
+
+  // Rich Results
+  if (r.richResultsResult) {
+    lines.push("", "--- Rich Results ---", "");
+    lines.push(`Verdict: ${r.richResultsResult.verdict}`);
+
+    for (const item of r.richResultsResult.detectedItems ?? []) {
+      lines.push(`\nType: ${item.richResultType}`);
+      for (const instance of item.items ?? []) {
+        if (instance.name) lines.push(`  Name: ${instance.name}`);
+        const issues = instance.issues ?? [];
+        if (issues.length === 0) {
+          lines.push("  Status: PASS");
+        } else {
+          for (const issue of issues) {
+            lines.push(`  ${issue.severity}: ${issue.issueMessage}`);
+          }
+        }
+      }
+    }
+  }
+
+  // Display deprecated mobile-usability evidence when supplied.
+  if (r.mobileUsabilityResult) {
+    lines.push("", "--- Mobile Usability (deprecated) ---", "");
+    lines.push(`Verdict: ${r.mobileUsabilityResult.verdict}`);
+    if (r.mobileUsabilityResult.issues) {
+      for (const issue of r.mobileUsabilityResult.issues) {
+        lines.push(`  ${issue.issueType}${issue.message ? `: ${issue.message}` : ""}`);
+      }
+    }
+  }
+
+  // Inspection link
+  if (r.inspectionResultLink) {
+    lines.push("", `Full report: ${r.inspectionResultLink}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function humanizeState(state: string): string {
+  const map: Record<string, string> = {
+    PAGE_FETCH_STATE_UNSPECIFIED: "not yet crawled",
+    ROBOTS_TXT_STATE_UNSPECIFIED: "not yet checked",
+    INDEXING_STATE_UNSPECIFIED: "not yet determined",
+  };
+  return map[state] ?? state;
+}
+
+export interface InspectionSummary {
+  url: string;
+  verdict: string;
+  coverageState: string;
+  pageFetchState: string;
+  robotsTxtState: string;
+  indexingState: string;
+  lastCrawlTime: string | null;
+  googleCanonical: string | null;
+  error: string | null;
+}
+
+export async function inspectSingle(url: string, siteUrl: string): Promise<InspectionSummary> {
+  try {
+    const r = await inspectUrl(url, siteUrl);
+    const idx = r.indexStatusResult;
+    return {
+      url,
+      verdict: idx.verdict,
+      coverageState: idx.coverageState,
+      pageFetchState: idx.pageFetchState,
+      robotsTxtState: idx.robotsTxtState,
+      indexingState: idx.indexingState,
+      lastCrawlTime: idx.lastCrawlTime ?? null,
+      googleCanonical: idx.googleCanonical ?? null,
+      error: null,
+    };
+  } catch (err) {
+    return {
+      url,
+      verdict: "ERROR",
+      coverageState: "ERROR",
+      pageFetchState: "ERROR",
+      robotsTxtState: "ERROR",
+      indexingState: "ERROR",
+      lastCrawlTime: null,
+      googleCanonical: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function runInspect(options: SearchOptions) {
+  const { site_url, url } = options;
+  if (!url) return textResult("Error: url is required for inspect.");
+  if (!site_url) return textResult("Error: site_url is required for inspect.");
+
+  try {
+    const result = await inspectUrl(url, site_url);
+    return textResult(formatInspection(url, site_url, result));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("PERMISSION_DENIED")) {
+      const domain = new URL(url).hostname;
+      return textResult(
+        [
+          `Error: Cannot inspect "${url}" — permission denied for property "${site_url}".`,
+          "",
+          "Possible causes:",
+          `  1. ${domain} is not a verified property in Google Search Console`,
+          `  2. The authenticated account does not have access to "${site_url}"`,
+          `  3. The property format is wrong — try "sc-domain:${domain}" or "https://${domain}/"`,
+          "",
+          "To verify a property: https://search.google.com/search-console",
+          "To check your auth: use the setup tool to verify credentials",
+        ].join("\n"),
+      );
+    }
+    return textResult(`Error inspecting URL: ${msg}`);
+  }
+}

package/src/tools/search/result.ts

@@ -0,0 +1,3 @@
+export function textResult(text: string) {
+  return { content: [{ type: "text" as const, text }] };
+}

package/src/tools/search/sample.ts

@@ -0,0 +1,110 @@
+import { listSitemaps } from "../../providers/gsc.js";
+import { type SearchOptions } from "./schema.js";
+import { humanizeState, type InspectionSummary, inspectSingle } from "./inspection.js";
+import { matchesCoverageFilter, formatSampleResults } from "./coverage.js";
+import { fetchSitemap, sampleUrls } from "./sitemap-sampling.js";
+import { textResult } from "./result.js";
+
+export async function runSample(options: SearchOptions) {
+  const { site_url, sitemap_url, sample_size, sample_strategy, filter } = options;
+  if (!site_url) return textResult("Error: site_url is required for sample.");
+
+  const count = sample_size ?? 5;
+  const strategy = sample_strategy ?? "random";
+
+  // Discover sitemap URL if not provided
+  let resolvedSitemapUrl = sitemap_url;
+  if (!resolvedSitemapUrl) {
+    const sitemaps = await listSitemaps(site_url);
+    if (sitemaps.length === 0) {
+      return textResult(`No sitemaps found for ${site_url} in GSC. Provide a sitemap_url directly.`);
+    }
+    const nonIndex = sitemaps.find((s) => !s.isSitemapsIndex);
+    resolvedSitemapUrl = (nonIndex ?? sitemaps[0]).path;
+  }
+
+  // Fetch and parse sitemap
+  let parsed = await fetchSitemap(resolvedSitemapUrl);
+
+  if (parsed.isSitemapIndex && parsed.childSitemaps.length > 0) {
+    const childUrl = parsed.childSitemaps[0];
+    parsed = await fetchSitemap(childUrl);
+    resolvedSitemapUrl = `${resolvedSitemapUrl} → ${childUrl}`;
+  }
+
+  if (parsed.urls.length === 0) {
+    return textResult(`Sitemap ${resolvedSitemapUrl} contains no URLs.`);
+  }
+
+  if (filter) {
+    // Filtered sample: inspect more URLs, return only matches
+    const scanLimit = Math.min(count * 5, 50, parsed.urls.length);
+    const pool = sampleUrls(parsed.urls, scanLimit, strategy);
+    const matched: InspectionSummary[] = [];
+    let scanned = 0;
+
+    for (const u of pool) {
+      const result = await inspectSingle(u, site_url);
+      scanned++;
+      if (matchesCoverageFilter(result, filter)) {
+        matched.push(result);
+        if (matched.length >= count) break;
+      }
+    }
+
+    if (matched.length === 0) {
+      return textResult(
+        [
+          `=== Filtered Sample: ${site_url} ===`,
+          `Sitemap: ${resolvedSitemapUrl} (${parsed.urls.length.toLocaleString()} URLs)`,
+          `Filter: ${filter}`,
+          `Scanned: ${scanned} | Matched: 0`,
+          "",
+          `No URLs matching "${filter}" found in ${scanned} inspected URLs.`,
+          "Try a larger sample_size or a different filter.",
+        ].join("\n"),
+      );
+    }
+
+    const lines: string[] = [
+      `=== Filtered Sample: ${site_url} ===`,
+      `Sitemap: ${resolvedSitemapUrl} (${parsed.urls.length.toLocaleString()} URLs)`,
+      `Filter: ${filter}`,
+      `Scanned: ${scanned} | Matched: ${matched.length}`,
+      "",
+      "--- Matching URLs ---",
+      "",
+    ];
+
+    for (let i = 0; i < matched.length; i++) {
+      const r = matched[i];
+      lines.push(`${i + 1}. ${r.url}`);
+      lines.push(`   Coverage: ${r.coverageState}`);
+      lines.push(`   Page fetch: ${humanizeState(r.pageFetchState)}`);
+      if (r.robotsTxtState !== "ALLOWED") lines.push(`   Robots.txt: ${humanizeState(r.robotsTxtState)}`);
+      if (r.indexingState !== "INDEXING_ALLOWED") lines.push(`   Indexing: ${humanizeState(r.indexingState)}`);
+      if (r.lastCrawlTime) lines.push(`   Last crawled: ${r.lastCrawlTime}`);
+      if (r.googleCanonical && r.googleCanonical !== r.url) {
+        lines.push(`   Google canonical: ${r.googleCanonical}`);
+      }
+      lines.push("");
+    }
+
+    if (matched.length < count && scanned >= scanLimit) {
+      lines.push(
+        `Found ${matched.length}/${count} requested — scanned ${scanned} URLs (limit ${scanLimit}). Increase sample_size for a wider scan.`,
+      );
+    }
+
+    return textResult(lines.join("\n"));
+  }
+
+  const sampled = sampleUrls(parsed.urls, count, strategy);
+
+  const results: InspectionSummary[] = [];
+  for (const u of sampled) {
+    results.push(await inspectSingle(u, site_url));
+  }
+
+  return textResult(formatSampleResults(site_url, resolvedSitemapUrl, parsed.urls.length, results));
+}

package/src/tools/search/schema.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+export const searchSchema = {
+  action: z
+    .enum(["inspect", "sample", "coverage", "sitemaps", "analytics", "gaps", "list_sites", "get_site", "get_sitemap"])
+    .optional()
+    .describe("Action to perform. Auto-detected from params when unambiguous."),
+  site_url: z.string().optional().describe("GSC property (e.g., 'sc-domain:example.com')."),
+  url: z.string().url().optional().describe("URL to inspect in Google's index."),
+  sitemap_url: z.string().url().optional().describe("Sitemap URL for sample/coverage inspection or get_sitemap."),
+  sample_size: z
+    .number()
+    .min(1)
+    .max(50)
+    .optional()
+    .describe("URLs to inspect (1-50). Default: 5 for sample, 20 for coverage."),
+  sample_strategy: z
+    .enum(["random", "first", "spread"])
+    .optional()
+    .describe("Sampling strategy. Default: 'spread' for coverage, 'random' for sample."),
+  filter: z
+    .enum([
+      "not_indexed",
+      "server_error",
+      "redirect",
+      "soft_404",
+      "blocked",
+      "duplicate",
+      "discovered",
+      "crawled_not_indexed",
+    ])
+    .optional()
+    .describe("Filter sample results by coverage issue type. Inspects more URLs internally to find matches."),
+  start_date: z.string().optional().describe("Start date (YYYY-MM-DD) for analytics. Default: 28 days ago."),
+  end_date: z.string().optional().describe("End date (YYYY-MM-DD) for analytics. Default: 3 days ago."),
+  dimensions: z
+    .array(z.enum(["query", "page", "country", "device", "date", "searchAppearance", "hour"]))
+    .optional()
+    .describe("Analytics dimensions. Default: auto."),
+  search_type: z
+    .enum(["web", "image", "video", "news", "discover", "googleNews"])
+    .optional()
+    .describe("Search type for analytics."),
+  data_state: z.enum(["all", "final", "hourly_all"]).optional().describe("Data freshness for analytics."),
+  aggregation_type: z
+    .enum(["auto", "byPage", "byProperty", "byNewsShowcasePanel"])
+    .optional()
+    .describe("Aggregation mode for analytics."),
+  filters: z
+    .array(
+      z.object({
+        dimension: z.enum(["query", "page", "country", "device", "searchAppearance"]),
+        operator: z.enum(["equals", "contains", "notEquals", "notContains", "includingRegex", "excludingRegex"]),
+        expression: z.string(),
+      }),
+    )
+    .optional()
+    .describe("Dimension filters for analytics."),
+  row_limit: z.number().optional().describe("Max rows for analytics (1-25000). Default: 1000."),
+  start_row: z.number().optional().describe("Pagination offset for analytics."),
+  compare: z.boolean().optional().describe("Compare current vs previous period for analytics."),
+};
+export type SearchOptions = z.infer<z.ZodObject<typeof searchSchema>>;

package/src/{lib/sitemap.ts → tools/search/sitemap-sampling.ts}

@@ -1,6 +1,4 @@
-import { inspectUrl } from "./gsc.js";
-
-export interface SitemapParseResult {
+interface SitemapParseResult {
   urls: string[];
   isSitemapIndex: boolean;
   childSitemaps: string[];
@@ -70,45 +68,3 @@ export function sampleUrls(urls: string[], count: number, strategy: string): str
   }
   return shuffled.slice(0, count);
 }
-
-export interface InspectionSummary {
-  url: string;
-  verdict: string;
-  coverageState: string;
-  pageFetchState: string;
-  robotsTxtState: string;
-  indexingState: string;
-  lastCrawlTime: string | null;
-  googleCanonical: string | null;
-  error: string | null;
-}
-
-export async function inspectSingle(url: string, siteUrl: string): Promise<InspectionSummary> {
-  try {
-    const r = await inspectUrl(url, siteUrl);
-    const idx = r.indexStatusResult;
-    return {
-      url,
-      verdict: idx.verdict,
-      coverageState: idx.coverageState,
-      pageFetchState: idx.pageFetchState,
-      robotsTxtState: idx.robotsTxtState,
-      indexingState: idx.indexingState,
-      lastCrawlTime: idx.lastCrawlTime ?? null,
-      googleCanonical: idx.googleCanonical ?? null,
-      error: null,
-    };
-  } catch (err) {
-    return {
-      url,
-      verdict: "ERROR",
-      coverageState: "ERROR",
-      pageFetchState: "ERROR",
-      robotsTxtState: "ERROR",
-      indexingState: "ERROR",
-      lastCrawlTime: null,
-      googleCanonical: null,
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}

package/src/tools/search/sites.ts

@@ -0,0 +1,86 @@
+import { type GscSite, type GscSitemap, getSite, getSitemap, listSitemaps, listSites } from "../../providers/gsc.js";
+import { type SearchOptions } from "./schema.js";
+import { textResult } from "./result.js";
+function formatSites(sites: GscSite[]): string {
+  if (sites.length === 0) return "No Search Console properties found.";
+
+  const lines: string[] = [`=== GSC Properties (${sites.length}) ===`, ""];
+  for (const site of sites) {
+    lines.push(`${site.siteUrl} (${site.permissionLevel})`);
+  }
+  return lines.join("\n");
+}
+
+function formatSite(site: GscSite): string {
+  return [`=== Site: ${site.siteUrl} ===`, "", `Permission: ${site.permissionLevel}`].join("\n");
+}
+
+function formatSitemapDetail(sm: GscSitemap): string {
+  const lines: string[] = [`=== Sitemap: ${sm.path} ===`, ""];
+  if (sm.type) lines.push(`Type: ${sm.type}`);
+  if (sm.lastSubmitted) lines.push(`Submitted: ${sm.lastSubmitted}`);
+  if (sm.lastDownloaded) lines.push(`Downloaded: ${sm.lastDownloaded}`);
+  lines.push(`Pending: ${sm.isPending}`);
+  lines.push(`Index: ${sm.isSitemapsIndex}`);
+  if (sm.warnings) lines.push(`Warnings: ${sm.warnings}`);
+  if (sm.errors) lines.push(`Errors: ${sm.errors}`);
+  if (sm.contents && sm.contents.length > 0) {
+    lines.push("", "Contents:");
+    for (const c of sm.contents) {
+      lines.push(`  ${c.type}: ${c.submitted ?? "?"} submitted; indexed count unavailable (deprecated API field)`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function formatSitemaps(siteUrl: string, sitemaps: GscSitemap[]): string {
+  if (sitemaps.length === 0) return `No sitemaps found for ${siteUrl}.`;
+
+  const lines: string[] = [`=== Sitemaps: ${siteUrl} (${sitemaps.length}) ===`, ""];
+
+  for (const sm of sitemaps) {
+    lines.push(`${sm.path}`);
+    if (sm.type) lines.push(`  Type: ${sm.type}`);
+    if (sm.lastSubmitted) lines.push(`  Submitted: ${sm.lastSubmitted}`);
+    if (sm.lastDownloaded) lines.push(`  Downloaded: ${sm.lastDownloaded}`);
+    lines.push(`  Pending: ${sm.isPending}`);
+    lines.push(`  Index: ${sm.isSitemapsIndex}`);
+    if (sm.warnings) lines.push(`  Warnings: ${sm.warnings}`);
+    if (sm.errors) lines.push(`  Errors: ${sm.errors}`);
+    if (sm.contents) {
+      for (const c of sm.contents) {
+        lines.push(`  ${c.type}: ${c.submitted ?? "?"} submitted; indexed count unavailable (deprecated API field)`);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd();
+}
+
+export async function runListSites() {
+  const sites = await listSites();
+  return textResult(formatSites(sites));
+}
+
+export async function runGetSite(options: SearchOptions) {
+  const { site_url } = options;
+  if (!site_url) return textResult("Error: site_url is required for get_site.");
+  const site = await getSite(site_url);
+  return textResult(formatSite(site));
+}
+
+export async function runGetSitemap(options: SearchOptions) {
+  const { site_url, sitemap_url } = options;
+  if (!site_url) return textResult("Error: site_url is required for get_sitemap.");
+  if (!sitemap_url) return textResult("Error: sitemap_url is required for get_sitemap.");
+  const sm = await getSitemap(site_url, sitemap_url);
+  return textResult(formatSitemapDetail(sm));
+}
+
+export async function runSitemaps(options: SearchOptions) {
+  const { site_url } = options;
+  if (!site_url) return textResult("Error: site_url is required for sitemaps.");
+  const sitemaps = await listSitemaps(site_url);
+  return textResult(formatSitemaps(site_url, sitemaps));
+}

package/src/tools/search/tool.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { searchSchema } from "./schema.js";
+import { runSearch } from "./actions.js";
+export function registerSearchTool(server: McpServer): void {
+  server.tool(
+    "search",
+    "Query Google Search Console. Inspect URL indexing, get coverage breakdown by issue type, sample-inspect with filters, list properties and sitemaps, analyze search traffic, or find keyword gaps.",
+    searchSchema,
+    runSearch,
+  );
+}

package/src/tools/setup.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { exchangeCodeForToken, getAuthMethod, getOAuthSetupUrl } from "../lib/auth.js";
+import { exchangeCodeForToken, getAuthMethod, getOAuthSetupUrl } from "../providers/gsc-auth.js";
 
 export function registerSetupTool(server: McpServer): void {
   server.tool(

package/src/tools/speed/analyze.ts

@@ -0,0 +1,191 @@
+import type { SpeedOptions } from "./schema.js";
+import { hasApiKey, type PsiCategoryType, type PsiResult, runPagespeed } from "../../providers/pagespeed.js";
+import { type CruxFormFactor, queryCrux, queryCruxHistory } from "../../providers/crux.js";
+import { QUOTA_NOTE, formatPagespeed } from "./pagespeed.js";
+import { formatBatchCompare, formatBatchTable, runBatch } from "./batch.js";
+import { formatCrux, formatCruxHistory } from "./crux.js";
+
+export async function analyzeSpeed({
+  action,
+  url,
+  urls,
+  strategy,
+  categories,
+  locale,
+  origin,
+  form_factor,
+  metrics,
+  periods,
+}: SpeedOptions) {
+  // Determine which action to run
+  let resolvedAction = action;
+  if (!resolvedAction) {
+    if (urls) {
+      resolvedAction = "pagespeed";
+    } else if (origin && !url) {
+      resolvedAction = "crux";
+    } else if (periods) {
+      resolvedAction = "crux_history";
+    } else {
+      resolvedAction = "pagespeed";
+    }
+  }
+
+  // --- PageSpeed action ---
+  if (resolvedAction === "pagespeed") {
+    const strat = (strategy as "mobile" | "desktop") ?? "mobile";
+    const cats = categories as PsiCategoryType[] | undefined;
+    const opts = { strategy: strat, categories: cats, locale };
+
+    if (url && urls) {
+      return {
+        content: [{ type: "text" as const, text: "Error: provide either 'url' (single) or 'urls' (batch), not both." }],
+      };
+    }
+    if (!url && !urls) {
+      return {
+        content: [
+          { type: "text" as const, text: "Error: provide 'url' for single analysis or 'urls' for batch analysis." },
+        ],
+      };
+    }
+
+    // Single URL
+    if (url) {
+      try {
+        const result = await runPagespeed(url, opts);
+        const text = formatPagespeed(url, result) + (hasApiKey() ? "" : QUOTA_NOTE);
+        return { content: [{ type: "text" as const, text }] };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text" as const, text: `Error running PageSpeed analysis: ${msg}` }] };
+      }
+    }
+
+    // Batch mode
+    const batchUrls = urls as string[];
+    const results = await runBatch(batchUrls, opts);
+
+    const successes = results.filter((r): r is { url: string; result: PsiResult } => !!r.result);
+    const failures = results.filter((r): r is { url: string; error: string } => !!r.error);
+
+    if (successes.length === 0) {
+      const errorLines = failures.map((f) => `${f.url}: ${f.error}`);
+      return { content: [{ type: "text" as const, text: `All URLs failed:\n${errorLines.join("\n")}` }] };
+    }
+
+    let output: string;
+    if (successes.length === 2) {
+      output = formatBatchCompare(successes, strat);
+    } else {
+      output = formatBatchTable(successes, strat);
+    }
+
+    if (failures.length > 0) {
+      const errorLines = failures.map((f) => `${f.url}: ${f.error}`);
+      output += `\n\n--- Errors ---\n${errorLines.join("\n")}`;
+    }
+
+    if (!hasApiKey()) output += QUOTA_NOTE;
+
+    return { content: [{ type: "text" as const, text: output }] };
+  }
+
+  // --- CrUX action ---
+  if (resolvedAction === "crux") {
+    const cruxUrl = url;
+    const cruxOrigin = origin;
+
+    if (!cruxUrl && !cruxOrigin) {
+      return { content: [{ type: "text" as const, text: "Error: provide url or origin for CrUX data." }] };
+    }
+    if (cruxUrl && cruxOrigin) {
+      return { content: [{ type: "text" as const, text: "Error: provide url or origin, not both." }] };
+    }
+
+    try {
+      const result = await queryCrux({
+        url: cruxUrl,
+        origin: cruxOrigin,
+        formFactor: form_factor as CruxFormFactor | undefined,
+        metrics,
+      });
+      return { content: [{ type: "text" as const, text: formatCrux(cruxUrl ?? cruxOrigin ?? "", result) }] };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("404")) {
+        const target = cruxUrl ?? cruxOrigin ?? "";
+        const lines = [`No CrUX data for ${target}.`, ""];
+        lines.push("CrUX requires sufficient Chrome user traffic (roughly 1,000+ monthly visits).");
+        if (cruxUrl) {
+          const originUrl = new URL(cruxUrl).origin;
+          lines.push(`Try origin-level data instead: origin "${originUrl}"`);
+        }
+        lines.push("For lab metrics without traffic requirements, use speed with a url instead.");
+        return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+      }
+      if (msg.includes("SERVICE_DISABLED") || msg.includes("API_KEY_SERVICE_BLOCKED")) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "Chrome UX Report API is not enabled or the API key doesn't have access. Enable the API at: https://console.cloud.google.com/apis/library/chromeuxreport.googleapis.com — and ensure your API key allows it (Credentials > API key > API restrictions).",
+            },
+          ],
+        };
+      }
+      return { content: [{ type: "text" as const, text: `Error querying CrUX: ${msg}` }] };
+    }
+  }
+
+  // --- CrUX History action ---
+  if (resolvedAction === "crux_history") {
+    const histUrl = url;
+    const histOrigin = origin;
+
+    if (!histUrl && !histOrigin) {
+      return { content: [{ type: "text" as const, text: "Error: provide url or origin for CrUX history." }] };
+    }
+    if (histUrl && histOrigin) {
+      return { content: [{ type: "text" as const, text: "Error: provide url or origin, not both." }] };
+    }
+
+    try {
+      const result = await queryCruxHistory({
+        url: histUrl,
+        origin: histOrigin,
+        formFactor: form_factor as CruxFormFactor | undefined,
+        metrics,
+        collectionPeriodCount: periods,
+      });
+      return { content: [{ type: "text" as const, text: formatCruxHistory(histUrl ?? histOrigin ?? "", result) }] };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("404")) {
+        const target = histUrl ?? histOrigin ?? "";
+        const lines = [`No CrUX history data for ${target}.`, ""];
+        lines.push("CrUX requires sufficient Chrome user traffic (roughly 1,000+ monthly visits).");
+        if (histUrl) {
+          const originUrl = new URL(histUrl).origin;
+          lines.push(`Try origin-level data instead: origin "${originUrl}"`);
+        }
+        lines.push("For lab metrics without traffic requirements, use speed with a url instead.");
+        return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+      }
+      if (msg.includes("SERVICE_DISABLED")) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "Chrome UX Report API is not enabled. Enable it at: https://console.cloud.google.com/apis/library/chromeuxreport.googleapis.com",
+            },
+          ],
+        };
+      }
+      return { content: [{ type: "text" as const, text: `Error querying CrUX History: ${msg}` }] };
+    }
+  }
+
+  const unhandled: never = resolvedAction;
+  return { content: [{ type: "text" as const, text: `Unknown action: ${String(unhandled)}` }] };
+}