pagesight 0.12.1 → 0.13.0

package/src/tools/crux.ts

@@ -1,296 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import {
-  type CruxFormFactor,
-  type CruxHistoryResponse,
-  type CruxResponse,
-  queryCrux,
-  queryCruxHistory,
-} from "../lib/crux.js";
-
-function formatDate(d: { year: number; month: number; day: number }): string {
-  return `${d.year}-${String(d.month).padStart(2, "0")}-${String(d.day).padStart(2, "0")}`;
-}
-
-const METRIC_LABELS: Record<string, string> = {
-  cumulative_layout_shift: "CLS",
-  first_contentful_paint: "FCP",
-  interaction_to_next_paint: "INP",
-  largest_contentful_paint: "LCP",
-  experimental_time_to_first_byte: "TTFB",
-  round_trip_time: "RTT",
-  navigation_types: "Navigation Types",
-  form_factors: "Form Factors",
-};
-
-function formatCrux(target: string, result: CruxResponse): string {
-  const r = result.record;
-  const period = r.collectionPeriod;
-  const lines: string[] = [
-    `=== CrUX: ${target} ===`,
-    `Form factor: ${r.key.formFactor ?? "all"}`,
-    `Period: ${formatDate(period.firstDate)} to ${formatDate(period.lastDate)}`,
-    "",
-  ];
-
-  if (result.urlNormalizationDetails) {
-    const norm = result.urlNormalizationDetails;
-    if (norm.originalUrl !== norm.normalizedUrl) {
-      lines.push(`Normalized: ${norm.originalUrl} → ${norm.normalizedUrl}`, "");
-    }
-  }
-
-  lines.push("--- Metrics (p75) ---", "");
-
-  for (const [key, metric] of Object.entries(r.metrics)) {
-    const label = METRIC_LABELS[key] ?? key;
-
-    if (metric.percentiles) {
-      const val = metric.percentiles.p75;
-      const unit = key === "cumulative_layout_shift" ? "" : "ms";
-      lines.push(`${label}: ${val}${unit}`);
-
-      if (metric.histogram) {
-        const buckets = metric.histogram.map((b) => `${Math.round(b.density * 100)}%`).join(" / ");
-        lines.push(`  Distribution (good/needs improvement/poor): ${buckets}`);
-      }
-    } else if (metric.fractions) {
-      lines.push(`${label}:`);
-      for (const [fKey, fVal] of Object.entries(metric.fractions)) {
-        lines.push(`  ${fKey}: ${(fVal * 100).toFixed(1)}%`);
-      }
-    }
-  }
-
-  return lines.join("\n");
-}
-
-function formatCruxHistory(target: string, result: CruxHistoryResponse): string {
-  const r = result.record;
-  const periods = r.collectionPeriods;
-  const lines: string[] = [
-    `=== CrUX History: ${target} ===`,
-    `Form factor: ${r.key.formFactor ?? "all"}`,
-    `Periods: ${periods.length} (${formatDate(periods[0].firstDate)} to ${formatDate(periods[periods.length - 1].lastDate)})`,
-    "",
-  ];
-
-  if (result.urlNormalizationDetails) {
-    const norm = result.urlNormalizationDetails;
-    if (norm.originalUrl !== norm.normalizedUrl) {
-      lines.push(`Normalized: ${norm.originalUrl} → ${norm.normalizedUrl}`, "");
-    }
-  }
-
-  lines.push("--- p75 Trend ---", "");
-
-  for (const [key, metric] of Object.entries(r.metrics)) {
-    const label = METRIC_LABELS[key] ?? key;
-
-    if (metric.percentilesTimeseries) {
-      const values = metric.percentilesTimeseries.p75s;
-      const first = values[0];
-      const last = values[values.length - 1];
-      const unit = key === "cumulative_layout_shift" ? "" : "ms";
-
-      if (first === null && last === null) {
-        lines.push(`${label}: insufficient data`);
-        continue;
-      }
-
-      lines.push(
-        `${label}: ${first ?? "N/A"}${first !== null ? unit : ""} → ${last ?? "N/A"}${last !== null ? unit : ""} (${values.length} points)`,
-      );
-
-      // Show trend direction
-      if (first !== null && last !== null) {
-        const f = Number(first);
-        const l = Number(last);
-        if (!Number.isNaN(f) && !Number.isNaN(l)) {
-          const change = ((l - f) / f) * 100;
-          const dir = change > 5 ? "worse" : change < -5 ? "improved" : "stable";
-          lines.push(`  Trend: ${change > 0 ? "+" : ""}${change.toFixed(1)}% (${dir})`);
-        }
-      }
-    } else if (metric.fractionTimeseries) {
-      lines.push(`${label}: (fraction timeseries, ${periods.length} points)`);
-      for (const [fKey, fData] of Object.entries(metric.fractionTimeseries)) {
-        const fracs = fData.fractions;
-        const first = fracs[0];
-        const last = fracs[fracs.length - 1];
-        if (first !== null && last !== null && !Number.isNaN(first) && !Number.isNaN(last)) {
-          lines.push(`  ${fKey}: ${(first * 100).toFixed(1)}% → ${(last * 100).toFixed(1)}%`);
-        }
-      }
-    }
-  }
-
-  // Show last 5 data points as table for core metrics
-  const coreMetrics = ["largest_contentful_paint", "interaction_to_next_paint", "cumulative_layout_shift"];
-  const available = coreMetrics.filter((m) => r.metrics[m]?.percentilesTimeseries);
-
-  if (available.length > 0 && periods.length >= 5) {
-    lines.push("", "--- Recent Data Points ---", "");
-    const lastN = 5;
-    const startIdx = periods.length - lastN;
-
-    lines.push(`${"Date".padEnd(12)} ${available.map((m) => (METRIC_LABELS[m] ?? m).padEnd(10)).join(" ")}`);
-    for (let i = startIdx; i < periods.length; i++) {
-      const date = formatDate(periods[i].lastDate);
-      const vals = available.map((m) => {
-        const v = r.metrics[m].percentilesTimeseries?.p75s[i];
-        return String(v ?? "N/A").padEnd(10);
-      });
-      lines.push(`${date.padEnd(12)} ${vals.join(" ")}`);
-    }
-  }
-
-  return lines.join("\n");
-}
-
-export function registerCruxTool(server: McpServer): void {
-  server.tool(
-    "crux",
-    "Query Chrome UX Report (CrUX) for real-world Core Web Vitals data. Returns p75 metrics from actual Chrome users over a 28-day rolling window.",
-    {
-      url: z.string().optional().describe("Specific page URL. Provide either url or origin."),
-      origin: z.string().optional().describe("Origin URL (e.g., 'https://example.com'). Provide either url or origin."),
-      form_factor: z
-        .enum(["DESKTOP", "PHONE", "TABLET"])
-        .optional()
-        .describe("Filter by device type. Omit for all devices."),
-      metrics: z
-        .array(
-          z.enum([
-            "cumulative_layout_shift",
-            "first_contentful_paint",
-            "interaction_to_next_paint",
-            "largest_contentful_paint",
-            "experimental_time_to_first_byte",
-            "round_trip_time",
-            "navigation_types",
-            "form_factors",
-          ]),
-        )
-        .optional()
-        .describe("Specific metrics to return. Default: all available."),
-    },
-    async ({ url, origin, form_factor, metrics }) => {
-      if (!url && !origin) {
-        return { content: [{ type: "text", text: "Error: provide either url or origin, not both." }] };
-      }
-      if (url && origin) {
-        return { content: [{ type: "text", text: "Error: provide either url or origin, not both." }] };
-      }
-      try {
-        const result = await queryCrux({
-          url,
-          origin,
-          formFactor: form_factor as CruxFormFactor | undefined,
-          metrics,
-        });
-        return { content: [{ type: "text", text: formatCrux(url ?? origin ?? "", result) }] };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg.includes("404")) {
-          const target = url ?? origin ?? "";
-          const lines = [`No CrUX data for ${target}.`, ""];
-          lines.push("CrUX requires sufficient Chrome user traffic (roughly 1,000+ monthly visits).");
-          if (url) {
-            const originUrl = new URL(url).origin;
-            lines.push(`Try origin-level data instead: origin "${originUrl}"`);
-          }
-          lines.push("For lab metrics without traffic requirements, use the pagespeed tool.");
-          return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-        if (msg.includes("SERVICE_DISABLED") || msg.includes("API_KEY_SERVICE_BLOCKED")) {
-          return {
-            content: [
-              {
-                type: "text",
-                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", text: `Error querying CrUX: ${msg}` }] };
-      }
-    },
-  );
-
-  server.tool(
-    "crux_history",
-    "Query CrUX History API for Core Web Vitals trends over time. Returns up to 40 weekly data points (~10 months) of real-world performance data.",
-    {
-      url: z.string().optional().describe("Specific page URL. Provide either url or origin."),
-      origin: z.string().optional().describe("Origin URL (e.g., 'https://example.com'). Provide either url or origin."),
-      form_factor: z
-        .enum(["DESKTOP", "PHONE", "TABLET"])
-        .optional()
-        .describe("Filter by device type. Omit for all devices."),
-      metrics: z
-        .array(
-          z.enum([
-            "cumulative_layout_shift",
-            "first_contentful_paint",
-            "interaction_to_next_paint",
-            "largest_contentful_paint",
-            "experimental_time_to_first_byte",
-            "round_trip_time",
-            "navigation_types",
-            "form_factors",
-          ]),
-        )
-        .optional()
-        .describe("Specific metrics to return. Default: all available."),
-      periods: z
-        .number()
-        .min(1)
-        .max(40)
-        .optional()
-        .describe("Number of collection periods (1-40). Default: 25. Each is a 28-day window."),
-    },
-    async ({ url, origin, form_factor, metrics, periods }) => {
-      if (!url && !origin) {
-        return { content: [{ type: "text", text: "Error: provide either url or origin, not both." }] };
-      }
-      if (url && origin) {
-        return { content: [{ type: "text", text: "Error: provide either url or origin, not both." }] };
-      }
-      try {
-        const result = await queryCruxHistory({
-          url,
-          origin,
-          formFactor: form_factor as CruxFormFactor | undefined,
-          metrics,
-          collectionPeriodCount: periods,
-        });
-        return { content: [{ type: "text", text: formatCruxHistory(url ?? origin ?? "", result) }] };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg.includes("404")) {
-          const target = url ?? origin ?? "";
-          const lines = [`No CrUX history data for ${target}.`, ""];
-          lines.push("CrUX requires sufficient Chrome user traffic (roughly 1,000+ monthly visits).");
-          if (url) {
-            const originUrl = new URL(url).origin;
-            lines.push(`Try origin-level data instead: origin "${originUrl}"`);
-          }
-          lines.push("For lab metrics without traffic requirements, use the pagespeed tool.");
-          return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-        if (msg.includes("SERVICE_DISABLED")) {
-          return {
-            content: [
-              {
-                type: "text",
-                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", text: `Error querying CrUX History: ${msg}` }] };
-      }
-    },
-  );
-}

package/src/tools/inspect.ts

@@ -1,121 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { type InspectionResult, inspectUrl } from "../lib/gsc.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}`);
-          }
-        }
-      }
-    }
-  }
-
-  // Mobile Usability (deprecated but still returned)
-  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 registerInspectTool(server: McpServer): void {
-  server.tool(
-    "inspect",
-    "Inspect a URL using Google Search Console. Returns index status, canonical, crawl status, rich results validation, and more — directly from Google's index.",
-    {
-      url: z.string().url().describe("The URL to inspect"),
-      site_url: z.string().describe("The GSC property (e.g., 'https://example.com/' or 'sc-domain:example.com')"),
-    },
-    async ({ url, site_url }) => {
-      try {
-        const result = await inspectUrl(url, site_url);
-        return { content: [{ type: "text", text: 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 {
-            content: [
-              {
-                type: "text",
-                text: [
-                  `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 { content: [{ type: "text", text: `Error inspecting URL: ${msg}` }] };
-      }
-    },
-  );
-}

package/src/tools/links.ts

@@ -1,183 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-
-interface LinkResult {
-  href: string;
-  status: number | null;
-  redirectChain: Array<{ url: string; status: number }>;
-  finalUrl: string | null;
-  error: string | null;
-}
-
-async function checkLink(href: string): Promise<LinkResult> {
-  const chain: Array<{ url: string; status: number }> = [];
-  let current = href;
-
-  try {
-    for (let i = 0; i < 10; i++) {
-      const res = await fetch(current, {
-        method: "GET",
-        headers: { "User-Agent": "Mozilla/5.0 (compatible; Googlebot/2.1)", Accept: "text/html" },
-        redirect: "manual",
-      });
-
-      chain.push({ url: current, status: res.status });
-
-      if (res.status >= 300 && res.status < 400) {
-        const location = res.headers.get("location");
-        if (!location) break;
-        current = new URL(location, current).href;
-        continue;
-      }
-
-      return {
-        href,
-        status: res.status,
-        redirectChain: chain,
-        finalUrl: chain.length > 1 ? current : null,
-        error: null,
-      };
-    }
-
-    return {
-      href,
-      status: chain[chain.length - 1]?.status ?? null,
-      redirectChain: chain,
-      finalUrl: current,
-      error: "Too many redirects",
-    };
-  } catch (err) {
-    return {
-      href,
-      status: null,
-      redirectChain: chain,
-      finalUrl: null,
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-function extractInternalLinks(html: string, origin: string): string[] {
-  const links = new Set<string>();
-
-  for (const match of html.matchAll(/<a\s[^>]*href=["']([^"'#]+)/gi)) {
-    const raw = match[1].trim();
-    if (!raw || raw.startsWith("javascript:") || raw.startsWith("mailto:") || raw.startsWith("tel:")) continue;
-
-    try {
-      const resolved = new URL(raw, origin).href;
-      if (resolved.startsWith(origin) && !resolved.includes("/cdn-cgi/")) {
-        links.add(resolved);
-      }
-    } catch {
-      // Invalid URL, skip
-    }
-  }
-
-  return [...links];
-}
-
-function formatResults(url: string, results: LinkResult[]): string {
-  const lines: string[] = [`=== Internal Links: ${url} ===`, `Found ${results.length} internal links`, ""];
-
-  const broken = results.filter((r) => r.error || (r.status && r.status >= 400));
-  const redirected = results.filter((r) => !r.error && r.redirectChain.length > 1 && r.status && r.status < 400);
-  const ok = results.filter((r) => !r.error && r.redirectChain.length === 1 && r.status && r.status < 400);
-
-  // Summary
-  lines.push("--- Summary ---", "");
-  lines.push(`OK: ${ok.length}`);
-  if (redirected.length > 0) lines.push(`Redirected: ${redirected.length}`);
-  if (broken.length > 0) lines.push(`Broken: ${broken.length}`);
-  lines.push("");
-
-  // Broken links
-  if (broken.length > 0) {
-    lines.push("--- Broken Links ---", "");
-    for (const r of broken) {
-      if (r.error) {
-        lines.push(`FAIL  ${r.href}`);
-        lines.push(`      Error: ${r.error}`);
-      } else {
-        lines.push(`FAIL  ${r.href} → ${r.status}`);
-      }
-    }
-    lines.push("");
-  }
-
-  // Redirect chains
-  if (redirected.length > 0) {
-    lines.push("--- Redirect Chains ---", "");
-    for (const r of redirected) {
-      const hops = r.redirectChain.length - 1;
-      const chainStr = r.redirectChain.map((h) => `${h.status}`).join(" → ");
-      lines.push(`REDIRECT  ${r.href}`);
-      lines.push(`          ${chainStr} → ${r.finalUrl} (${hops} hop${hops > 1 ? "s" : ""})`);
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-export function registerLinksTool(server: McpServer): void {
-  server.tool(
-    "links",
-    "Check internal links on a page. Fetches the page, extracts all internal <a href> links, and checks each for broken links (404/5xx), redirect chains, and errors.",
-    {
-      url: z.string().url().describe("The page URL to check internal links for."),
-    },
-    async ({ url }) => {
-      try {
-        const origin = new URL(url).origin;
-
-        // Fetch the page
-        const res = await fetch(url, {
-          headers: { "User-Agent": "Mozilla/5.0 (compatible; Googlebot/2.1)", Accept: "text/html" },
-          redirect: "follow",
-        });
-
-        if (!res.ok) {
-          return {
-            content: [{ type: "text", text: `Error fetching ${url}: HTTP ${res.status}` }],
-          };
-        }
-
-        const html = await res.text();
-        const links = extractInternalLinks(html, origin);
-
-        if (links.length === 0) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `No internal links found on ${url}\nNote: this page may use client-side rendering (SPA). Only static <a href> links in the HTML are detected.`,
-              },
-            ],
-          };
-        }
-
-        // Check links with concurrency 5
-        const concurrency = 5;
-        const results: LinkResult[] = [];
-        let i = 0;
-
-        while (i < links.length) {
-          const batch = links.slice(i, i + concurrency);
-          const settled = await Promise.all(batch.map((href) => checkLink(href)));
-          results.push(...settled);
-          i += concurrency;
-        }
-
-        return {
-          content: [{ type: "text", text: formatResults(url, results) }],
-        };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{ type: "text", text: `Error checking links: ${msg}` }],
-        };
-      }
-    },
-  );
-}