pagesight 0.13.1 → 0.14.1

package/README.md

@@ -8,34 +8,40 @@ See your site the way search engines and AI see it.
 npm install pagesight
 ```
 
-Your AI assistant can write your code. Now it can see your site. Index status, performance, real-user metrics, search traffic, meta tags, structured data, AI crawler access — one package, one call.
+Your AI assistant can write your code. Now it can see your site. Index status, performance, real-user metrics, search traffic, meta tags, structured data, AI crawler access, link health — one package, one call.
 
 ```
 === Site Audit: https://example.com ===
 
+2 checks failed — results below are partial:
+
+  FAIL  PageSpeed: quota exceeded
+  FAIL  Sitemaps: permission denied
+
+5 findings:
+
 HIGH    Missing canonical URL
-HIGH    7,772 sitemap URLs submitted, 0 indexed
+HIGH    22 sitemap URLs submitted, 0 indexed
+        Auto-inspected 5 URLs:
+        - 2/5 indexed
+        - 3/5 Discovered - currently not indexed: /docs/, /pricing/, /about/
 MEDIUM  Missing og:image — no social preview image
-MEDIUM  Accessibility score: 89/100
 LOW     Missing Twitter Card tags
-LOW     No structured data (JSON-LD) found
+LOW     6/139 AI crawlers blocked
 ```
 
 ## Tools
 
-| Tool | What it does |
-|------|-------------|
-| `audit` | One-call site audit. Runs all checks in parallel. Returns prioritized findings. |
-| `pagespeed` | Lighthouse scores, Core Web Vitals, opportunities, failing audits with fix links. |
-| `metatags` | OG, Twitter Card, canonical, JSON-LD with schema validation, redirect chain, image validation. |
-| `inspect` | Google index status, canonical choice, crawl state, rich results. |
-| `sample_inspect` | Sample URLs from a sitemap and batch-inspect. Diagnoses indexing patterns. |
-| `performance` | Search analytics — clicks, impressions, CTR, position. `compare: true` for period-over-period. |
-| `crux` | Real-user Core Web Vitals (p75, histograms). |
-| `crux_history` | CWV trends over time — up to 40 weekly data points. |
-| `robots` | robots.txt validation (RFC 9309) + AI crawler audit (139+ bots). |
-| `sitemaps` | Search Console properties and sitemaps with submitted/indexed counts. |
-| `setup` | Auth status and OAuth setup. |
+6 tools organized by intent:
+
+| Tool | Intent | What it does |
+|------|--------|-------------|
+| `audit` | How's my site? | One-call site audit. Runs all checks in parallel. Prioritized findings with auto-drill-down on indexing issues. |
+| `page` | What's on this URL? | Meta tags, OG, Twitter Card, JSON-LD validation (19 schema types), internal link health, redirect chains, WCAG contrast checker. Batch mode for multiple URLs. |
+| `speed` | How fast is it? | PageSpeed single/batch/compare with Lighthouse scores and opportunities. CrUX real-user metrics (snapshot + history trends). |
+| `search` | How's Google seeing me? | URL inspection, sample-inspect from sitemaps, sitemap management, search analytics with period-over-period comparison. |
+| `ai` | How's AI seeing me? | AI crawler audit (139+ bots by category), robots.txt validation (RFC 9309), llms.txt detection, path access checks. |
+| `setup` | Auth config | Auth status check and OAuth setup flow. |
 
 ## Setup
 
@@ -58,7 +64,7 @@ Add to your MCP config:
 }
 ```
 
-`robots`, `metatags`, and `pagespeed` work without credentials.
+`page`, `speed`, and `ai` work without credentials. `search` and `audit` (for GSC checks) require OAuth or a service account.
 
 ### Full setup
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagesight",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "See your site the way search engines and AI see it.",
   "keywords": [
     "seo",

package/src/tools/ai.ts

@@ -12,12 +12,24 @@ interface LlmsTxtResult {
 
 async function checkLlmsTxt(origin: string, path: string): Promise<LlmsTxtResult> {
   try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10_000);
     const res = await fetch(`${origin}${path}`, {
       headers: { "User-Agent": "Pagesight/1.0" },
       redirect: "follow",
+      signal: controller.signal,
     });
+    clearTimeout(timeout);
     if (!res.ok) return { exists: false, size: null, firstLine: null };
+    // Cap at 1MB to avoid OOM on large responses
+    const contentLength = Number(res.headers.get("content-length") ?? 0);
+    if (contentLength > 1_048_576) {
+      return { exists: true, size: contentLength, firstLine: "(file too large to preview)" };
+    }
     const text = await res.text();
+    if (text.length > 1_048_576) {
+      return { exists: true, size: text.length, firstLine: "(file too large to preview)" };
+    }
     const firstLine =
       text
         .split("\n")
@@ -215,6 +227,7 @@ export function registerAiTool(server: McpServer): void {
     {
       url: z
         .string()
+        .url()
         .describe("Site URL or origin (e.g., 'https://example.com'). Fetches /robots.txt from this origin."),
       check_path: z
         .string()

package/src/tools/page.ts

@@ -571,6 +571,17 @@ function formatMetatags(url: string, parsed: ParsedHead): string {
       lines.push(`${h.lang}: ${h.href}`);
     }
     lines.push("");
+  } else {
+    // Warn if URL suggests locale-specific content but no hreflang
+    const localePattern =
+      /\/(?:en|es|fr|de|ja|ko|pt|zh|ru|it|nl|sv|da|fi|nb|pl|tr|ar|hi|th|vi|id|ms|uk|cs|ro|hu|el|he|bg|hr|sk|sl|sr|lt|lv|et|ca|gl|eu|cy)(?:[-_][a-z]{2,4})?(?:\/|$)/i;
+    const checkUrl = parsed.canonical ?? url;
+    if (localePattern.test(checkUrl)) {
+      lines.push(
+        "WARN: URL appears locale-specific but no hreflang tags found — search engines may not discover alternate language versions",
+      );
+      lines.push("");
+    }
   }
 
   // Summary of missing tags relevant to search and social
@@ -604,7 +615,7 @@ async function checkLink(href: string): Promise<LinkResult> {
   try {
     for (let i = 0; i < 10; i++) {
       const res = await fetch(current, {
-        method: "GET",
+        method: "HEAD",
         headers: { "User-Agent": "Mozilla/5.0 (compatible; Googlebot/2.1)", Accept: "text/html" },
         redirect: "manual",
       });
@@ -798,15 +809,19 @@ export function registerPageTool(server: McpServer): void {
     "page",
     "Analyze what's on a page — meta tags, Open Graph, Twitter Card, structured data (JSON-LD), internal links, and redirect chains. Also includes a WCAG contrast checker for accessibility fixes.",
     {
-      url: z
-        .string()
-        .url()
+      url: z.string().url().optional().describe("Single URL to analyze. Use this OR urls, not both."),
+      urls: z
+        .array(z.string().url())
+        .min(2)
+        .max(10)
         .optional()
-        .describe("Page URL to analyze. Returns meta tags, structured data, and optionally internal links."),
+        .describe(
+          "Multiple URLs (2-10) for batch analysis. Returns a summary table of meta tags, structured data, and link health per page.",
+        ),
       check_links: z
         .boolean()
         .optional()
-        .describe("Also check all internal links for broken links and redirect chains. Default: false."),
+        .describe("Check internal links for broken links and redirect chains. Default: true. Set false to skip."),
       user_agent: z.string().optional().describe("Custom User-Agent for page fetch. Default: Googlebot-compatible."),
       foreground: z
         .string()
@@ -818,7 +833,129 @@ export function registerPageTool(server: McpServer): void {
         .optional()
         .describe("Whether text is large (≥18pt or ≥14pt bold). Lowers AA threshold to 3:1."),
     },
-    async ({ url, check_links, user_agent, foreground, background, large_text }) => {
+    async ({ url, urls, check_links, user_agent, foreground, background, large_text }) => {
+      // --- Batch mode ---
+      if (urls) {
+        const ua = user_agent ?? "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)";
+        const results: Array<{
+          url: string;
+          title: string;
+          description: string;
+          canonical: string;
+          jsonLd: string;
+          links: string;
+          issues: string[];
+          error?: string;
+        }> = [];
+
+        for (const pageUrl of urls) {
+          try {
+            const { chain, response: res } = await followRedirects(pageUrl, ua);
+            if (!res.ok) {
+              results.push({
+                url: pageUrl,
+                title: "-",
+                description: "-",
+                canonical: "-",
+                jsonLd: "-",
+                links: "-",
+                issues: [`HTTP ${res.status}`],
+              });
+              continue;
+            }
+            const html = await res.text();
+            const parsed = parseHead(html);
+            const finalUrl = chain.length > 1 ? chain[chain.length - 1].url : pageUrl;
+
+            const issues: string[] = [];
+            if (!parsed.title) issues.push("no title");
+            if (!getMeta(parsed.meta, "description")) issues.push("no description");
+            else if ((getMeta(parsed.meta, "description") ?? "").length > 155) issues.push("description >155 chars");
+            if (!parsed.canonical) issues.push("no canonical");
+            if (parsed.jsonLd.length === 0) issues.push("no JSON-LD");
+            if (chain.length > 2) issues.push(`${chain.length - 1} redirects`);
+
+            // Quick link check
+            let linkSummary = "-";
+            if (check_links !== false) {
+              const origin = new URL(finalUrl).origin;
+              const links = extractInternalLinks(html, origin);
+              if (links.length > 0) {
+                const checked = await Promise.all(links.slice(0, 20).map((href) => checkLink(href)));
+                const broken = checked.filter((r) => r.error || (r.status && r.status >= 400)).length;
+                const redirected = checked.filter(
+                  (r) => !r.error && r.redirectChain.length > 1 && r.status && r.status < 400,
+                ).length;
+                const parts: string[] = [`${links.length} found`];
+                if (broken > 0) parts.push(`${broken} broken`);
+                if (redirected > 0) parts.push(`${redirected} redirected`);
+                if (broken === 0 && redirected === 0) parts.push("all OK");
+                linkSummary = parts.join(", ");
+                if (broken > 0) issues.push(`${broken} broken links`);
+                if (redirected > 0) issues.push(`${redirected} redirect chains`);
+              } else {
+                linkSummary = "0 (SPA?)";
+              }
+            }
+
+            const jsonLdTypes = parsed.jsonLd
+              .map((block) => {
+                if (block && typeof block === "object" && "@type" in block)
+                  return String((block as Record<string, unknown>)["@type"]);
+                return null;
+              })
+              .filter(Boolean);
+
+            results.push({
+              url: finalUrl,
+              title: parsed.title
+                ? parsed.title.length > 40
+                  ? `${parsed.title.slice(0, 40)}...`
+                  : parsed.title
+                : "(missing)",
+              description: getMeta(parsed.meta, "description") ? "yes" : "no",
+              canonical: parsed.canonical ? "yes" : "no",
+              jsonLd: jsonLdTypes.length > 0 ? jsonLdTypes.join(", ") : "none",
+              links: linkSummary,
+              issues,
+            });
+          } catch (err) {
+            results.push({
+              url: pageUrl,
+              title: "-",
+              description: "-",
+              canonical: "-",
+              jsonLd: "-",
+              links: "-",
+              issues: [err instanceof Error ? err.message : String(err)],
+            });
+          }
+        }
+
+        const lines: string[] = [`=== Batch Page Analysis (${results.length} URLs) ===`, ""];
+
+        for (const r of results) {
+          const u = new URL(r.url);
+          const allSameHost = results.every((x) => new URL(x.url).hostname === u.hostname);
+          const label = allSameHost ? u.pathname : `${u.hostname}${u.pathname}`;
+          lines.push(label);
+          lines.push(`  Title: ${r.title}`);
+          lines.push(`  Description: ${r.description}  Canonical: ${r.canonical}  JSON-LD: ${r.jsonLd}`);
+          if (check_links !== false) lines.push(`  Links: ${r.links}`);
+          if (r.issues.length > 0) {
+            lines.push(`  Issues: ${r.issues.join(", ")}`);
+          } else {
+            lines.push("  Issues: none");
+          }
+          lines.push("");
+        }
+
+        const issueCount = results.reduce((sum, r) => sum + r.issues.length, 0);
+        lines.push(`Total: ${results.length} pages, ${issueCount} issues`);
+
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+
       // --- Contrast-only mode (no URL) ---
       if (foreground && background && !url) {
         const fg = parseHex(foreground);
@@ -971,8 +1108,34 @@ export function registerPageTool(server: McpServer): void {
             }
           }
 
-          // --- Link check (appended after metatags output) ---
-          if (check_links) {
+          // Contrast check (before links, after structured data)
+          if (foreground && background) {
+            const fg = parseHex(foreground);
+            const bg = parseHex(background);
+            if (fg && bg) {
+              const fgLum = relativeLuminance(...fg);
+              const bgLum = relativeLuminance(...bg);
+              const ratio = contrastRatio(fgLum, bgLum);
+              const isLarge = large_text ?? false;
+              const level = wcagLevel(ratio, isLarge);
+              const aaThreshold = isLarge ? 3 : 4.5;
+              const aaaThreshold = isLarge ? 4.5 : 7;
+              output.push(
+                "",
+                "--- Contrast Check ---",
+                "",
+                `Foreground: ${toHex(...fg)}  Background: ${toHex(...bg)}`,
+                `Ratio: ${ratio.toFixed(2)}:1  AA: ${ratio >= aaThreshold ? "PASS" : "FAIL"}  AAA: ${ratio >= aaaThreshold ? "PASS" : "FAIL"}  Result: ${level}`,
+              );
+              if (ratio < aaThreshold) {
+                const suggested = findNearestPassing(fg, bg, aaThreshold);
+                output.push(`Nearest AA-passing foreground: ${suggested}`);
+              }
+            }
+          }
+
+          // --- Link check (last section) ---
+          if (check_links !== false) {
             const origin = new URL(url).origin;
             const links = extractInternalLinks(html, origin);
 
@@ -1001,32 +1164,6 @@ export function registerPageTool(server: McpServer): void {
             }
           }
 
-          // Append contrast check if colors were also provided
-          if (foreground && background) {
-            const fg = parseHex(foreground);
-            const bg = parseHex(background);
-            if (fg && bg) {
-              const fgLum = relativeLuminance(...fg);
-              const bgLum = relativeLuminance(...bg);
-              const ratio = contrastRatio(fgLum, bgLum);
-              const isLarge = large_text ?? false;
-              const level = wcagLevel(ratio, isLarge);
-              const aaThreshold = isLarge ? 3 : 4.5;
-              const aaaThreshold = isLarge ? 4.5 : 7;
-              output.push(
-                "",
-                "--- Contrast Check ---",
-                "",
-                `Foreground: ${toHex(...fg)}  Background: ${toHex(...bg)}`,
-                `Ratio: ${ratio.toFixed(2)}:1  AA: ${ratio >= aaThreshold ? "PASS" : "FAIL"}  AAA: ${ratio >= aaaThreshold ? "PASS" : "FAIL"}  Result: ${level}`,
-              );
-              if (ratio < aaThreshold) {
-                const suggested = findNearestPassing(fg, bg, aaThreshold);
-                output.push(`Nearest AA-passing foreground: ${suggested}`);
-              }
-            }
-          }
-
           return {
             content: [{ type: "text", text: output.join("\n") }],
           };

package/src/tools/search.ts

@@ -413,25 +413,33 @@ function formatComparison(
     lines.push("");
   }
 
+  lines.push("--- Regressed ---", "");
   if (regressed.length > 0) {
-    lines.push("--- Regressed ---", "");
     for (const m of regressed) {
       const keys = m.keys.map((k, i) => `${dimensions[i] ?? "key"}=${k}`).join(" | ");
       const posChange = m.prevPos > 0 ? ` | Position: ${m.prevPos.toFixed(1)} → ${m.curPos.toFixed(1)}` : "";
       lines.push(`${keys}`);
       lines.push(`  Clicks: ${m.prevClicks} → ${m.curClicks} (${pctChange(m.curClicks, m.prevClicks)})${posChange}`);
     }
-    lines.push("");
+  } else {
+    lines.push("(none)");
   }
+  lines.push("");
 
   return lines.join("\n");
 }
 
 function daysAgo(n: number): string {
-  // GSC dates are in PT (Pacific Time). Use UTC-8 as a stable approximation.
-  const now = new Date(Date.now() - 8 * 60 * 60 * 1000);
-  now.setDate(now.getDate() - n);
-  return now.toISOString().split("T")[0];
+  // GSC dates are in Pacific Time. Use Intl to handle DST correctly.
+  const d = new Date();
+  d.setDate(d.getDate() - n);
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: "America/Los_Angeles",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(d);
+  return parts; // en-CA formats as YYYY-MM-DD
 }
 
 // ── Tool registration ──

package/src/tools/speed.ts

@@ -813,10 +813,10 @@ export function registerSpeedTool(server: McpServer): void {
         const cruxOrigin = origin;
 
         if (!cruxUrl && !cruxOrigin) {
-          return { content: [{ type: "text" as const, text: "Error: provide either url or origin, not both." }] };
+          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 either url or origin, not both." }] };
+          return { content: [{ type: "text" as const, text: "Error: provide url or origin, not both." }] };
         }
 
         try {
@@ -860,10 +860,10 @@ export function registerSpeedTool(server: McpServer): void {
         const histOrigin = origin;
 
         if (!histUrl && !histOrigin) {
-          return { content: [{ type: "text" as const, text: "Error: provide either url or origin, not both." }] };
+          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 either url or origin, not both." }] };
+          return { content: [{ type: "text" as const, text: "Error: provide url or origin, not both." }] };
         }
 
         try {