pagesight 0.10.0 → 0.12.0

package/README.md

@@ -8,26 +8,10 @@ See your site the way search engines and AI see it.
 npm install pagesight
 ```
 
-Google Search Console + PageSpeed Insights + CrUX + 139 AI crawlers. One package.
-
-## Tools
-
-| Tool | What it does |
-|------|-------------|
-| `audit` | One-call site audit. Runs pagespeed + metatags + robots + sitemaps + inspect in parallel. Returns prioritized findings. |
-| `pagespeed` | Lighthouse scores, Core Web Vitals, opportunities with resource URLs, failing audits with selectors and 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 via GSC. Diagnoses indexing patterns. |
-| `performance` | Search analytics — clicks, impressions, CTR, position. `compare: true` for period-over-period deltas. |
-| `crux` | Real-world Core Web Vitals from Chrome users (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` | GSC properties and sitemaps with submitted/indexed counts. |
-| `setup` | Auth status and OAuth setup. |
+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.
 
 ```
-=== Site Audit: https://fipe.chat ===
+=== Site Audit: https://example.com ===
 
 HIGH    Missing canonical URL
 HIGH    7,772 sitemap URLs submitted, 0 indexed
@@ -37,22 +21,25 @@ LOW     Missing Twitter Card tags
 LOW     No structured data (JSON-LD) found
 ```
 
-## Setup
-
-1. [Google Cloud Console](https://console.cloud.google.com/) — enable Search Console API, PageSpeed Insights API, Chrome UX Report API
-2. Create OAuth client ID (Desktop app) + API key
-3. Configure:
+## Tools
 
-```env
-GSC_CLIENT_ID=your-client-id.apps.googleusercontent.com
-GSC_CLIENT_SECRET=your-client-secret
-GSC_REFRESH_TOKEN=your-refresh-token
-GOOGLE_API_KEY=your-api-key
-```
+| 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. |
 
-`robots`, `metatags`, and `pagespeed` work without credentials.
+## Setup
 
-### MCP config
+Add to your MCP config:
 
 ```json
 {
@@ -71,15 +58,30 @@ GOOGLE_API_KEY=your-api-key
 }
 ```
 
-## Why not other SEO tools?
+`robots`, `metatags`, and `pagespeed` work without credentials.
+
+### Full setup
+
+1. [Google Cloud Console](https://console.cloud.google.com/) — enable Search Console API, PageSpeed Insights API, Chrome UX Report API
+2. Create OAuth client ID (Desktop app) + API key
+3. Configure:
+
+```env
+GSC_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GSC_CLIENT_SECRET=your-client-secret
+GSC_REFRESH_TOKEN=your-refresh-token
+GOOGLE_API_KEY=your-api-key
+```
+
+## Why Pagesight
 
-We checked every common SEO "rule" against official Google documentation:
+Every data point comes from a verifiable source. Google's APIs, real Chrome users, RFC 9309, schema.org, a community-maintained bot registry. No invented scores. No rules we can't cite.
 
 - **"Title must be under 60 characters"** — Gary Illyes: "an externally made-up metric."
 - **"Only one H1 per page"** — John Mueller: "You can use H1 tags as often as you want."
 - **"Minimum 300 words per page"** — Mueller: "not a quality factor."
 
-Pagesight only reports what the sources actually return.
+Pagesight reports what the sources report. Nothing more.
 
 ## License
 

package/package.json

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

package/src/index.ts

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { registerAuditTool } from "./tools/audit.js";
 import { registerCruxTool } from "./tools/crux.js";
 import { registerInspectTool } from "./tools/inspect.js";
+import { registerLinksTool } from "./tools/links.js";
 import { registerMetatagsTool } from "./tools/metatags.js";
 import { registerPagespeedTool } from "./tools/pagespeed.js";
 import { registerPerformanceTool } from "./tools/performance.js";
@@ -22,6 +23,7 @@ const server = new McpServer({
 registerAuditTool(server);
 registerCruxTool(server);
 registerInspectTool(server);
+registerLinksTool(server);
 registerMetatagsTool(server);
 registerPagespeedTool(server);
 registerPerformanceTool(server);

package/src/tools/audit.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { inspectUrl, listSitemaps } from "../lib/gsc.js";
 import { type PsiCategoryType, type PsiResult, runPagespeed } from "../lib/psi.js";
 import { auditAiCrawlers, fetchRobotsTxt, isAllowed } from "../lib/robots.js";
+import { fetchSitemap, inspectSingle, sampleUrls } from "./sample-inspect.js";
 
 type Severity = "HIGH" | "MEDIUM" | "LOW";
 
@@ -128,9 +129,11 @@ function addPagespeedFindings(result: PsiResult, findings: Finding[]) {
     const fontItems = renderBlocking.details.items.filter((i) => i.url && String(i.url).includes("fonts"));
     if (fontItems.length > 0) {
       const wastedMs = fontItems.reduce((sum, i) => sum + (i.wastedMs ? Number(i.wastedMs) : 0), 0);
+      const isGoogleFonts = fontItems.some((i) => String(i.url).includes("fonts.googleapis.com"));
+      const label = isGoogleFonts ? "Render-blocking Google Fonts" : "Render-blocking font CSS";
       findings.push({
         severity: "MEDIUM",
-        message: `Render-blocking Google Fonts (${Math.round(wastedMs)}ms wasted)`,
+        message: `${label} (${Math.round(wastedMs)}ms wasted)`,
         source: "pagespeed",
       });
     }
@@ -208,6 +211,36 @@ function addSitemapFindings(sitemapCount: number, totalSubmitted: number, totalI
   }
 }
 
+function formatDrillDown(
+  inspections: Array<{ url: string; verdict: string; coverageState: string; error: string | null }>,
+): string {
+  const valid = inspections.filter((r) => !r.error);
+  if (valid.length === 0) return "";
+
+  const indexed = valid.filter((r) => r.verdict === "PASS").length;
+  const lines: string[] = [`        Auto-inspected ${valid.length} URLs:`];
+  lines.push(`        - ${indexed}/${valid.length} indexed`);
+
+  const stateCounts: Record<string, { count: number; urls: string[] }> = {};
+  for (const r of valid) {
+    if (r.verdict !== "PASS") {
+      const path = new URL(r.url).pathname;
+      const existing = stateCounts[r.coverageState];
+      if (existing) {
+        existing.count++;
+        existing.urls.push(path);
+      } else {
+        stateCounts[r.coverageState] = { count: 1, urls: [path] };
+      }
+    }
+  }
+  for (const [state, { count, urls }] of Object.entries(stateCounts)) {
+    lines.push(`        - ${count}/${valid.length} ${state}: ${urls.join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
 function addInspectFindings(verdict: string, coverageState: string, findings: Finding[]) {
   if (verdict === "FAIL") {
     findings.push({ severity: "HIGH", message: `URL not indexed: ${coverageState}`, source: "inspect" });
@@ -310,6 +343,33 @@ export function registerAuditTool(server: McpServer): void {
           }
         }
         addSitemapFindings(sitemaps.length, totalSubmitted, totalIndexed, findings);
+
+        // Auto-drill-down: when indexing is low, sample-inspect to explain why
+        const indexPct = totalSubmitted > 0 ? (totalIndexed / totalSubmitted) * 100 : 100;
+        if (site_url && indexPct < 50 && sitemaps.length > 0) {
+          try {
+            const sitemapPath = (sitemaps.find((s) => !s.isSitemapsIndex) ?? sitemaps[0]).path;
+            let parsed = await fetchSitemap(sitemapPath);
+            if (parsed.isSitemapIndex && parsed.childSitemaps.length > 0) {
+              parsed = await fetchSitemap(parsed.childSitemaps[0]);
+            }
+            if (parsed.urls.length > 0) {
+              const sampled = sampleUrls(parsed.urls, 5, "spread");
+              const inspections = [];
+              for (const u of sampled) {
+                inspections.push(await inspectSingle(u, site_url));
+              }
+              const drillDown = formatDrillDown(inspections);
+              // Append drill-down to the sitemap finding
+              const sitemapFinding = findings.find((f) => f.source === "sitemaps" && f.severity === "HIGH");
+              if (sitemapFinding) {
+                sitemapFinding.message += `\n${drillDown}`;
+              }
+            }
+          } catch {
+            // Drill-down is best-effort — don't fail the audit
+          }
+        }
       } else if (sitemapResult.status === "rejected") {
         errors.push(`Sitemaps: ${sitemapResult.reason}`);
       }

package/src/tools/inspect.ts

@@ -34,6 +34,11 @@ function formatInspection(url: string, siteUrl: string, r: InspectionResult): st
     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 ---", "");

package/src/tools/links.ts

@@ -0,0 +1,183 @@
+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}` }],
+        };
+      }
+    },
+  );
+}

package/src/tools/metatags.ts

@@ -140,6 +140,7 @@ interface SchemaRule {
   required: string[];
   recommended: string[];
   imageFields: string[];
+  nestedRequired?: Record<string, string[]>;
 }
 
 // Required/recommended fields sourced from Google's Rich Results documentation
@@ -169,6 +170,7 @@ const SCHEMA_RULES: Record<string, SchemaRule> = {
     required: ["name", "image"],
     recommended: ["description", "offers", "brand", "review", "aggregateRating"],
     imageFields: ["image"],
+    nestedRequired: { offers: ["price", "priceCurrency"] },
   },
   LocalBusiness: {
     required: ["name", "address"],
@@ -200,6 +202,43 @@ const SCHEMA_RULES: Record<string, SchemaRule> = {
     recommended: ["duration", "contentUrl", "embedUrl"],
     imageFields: ["thumbnailUrl"],
   },
+  SoftwareApplication: {
+    required: ["name", "offers"],
+    recommended: ["applicationCategory", "operatingSystem", "review", "aggregateRating"],
+    imageFields: ["image"],
+    nestedRequired: { offers: ["price", "priceCurrency"] },
+  },
+  Dataset: {
+    required: ["name", "description"],
+    recommended: ["distribution", "creator", "license"],
+    imageFields: [],
+    nestedRequired: { distribution: ["contentUrl", "encodingFormat"] },
+  },
+  TechArticle: {
+    required: ["headline", "image", "datePublished", "author"],
+    recommended: ["dateModified", "publisher"],
+    imageFields: ["image"],
+  },
+  BlogPosting: {
+    required: ["headline", "image", "datePublished", "author"],
+    recommended: ["dateModified", "publisher"],
+    imageFields: ["image"],
+  },
+  HowTo: {
+    required: ["name", "step"],
+    recommended: ["image", "totalTime", "estimatedCost"],
+    imageFields: ["image"],
+  },
+  Course: {
+    required: ["name", "description"],
+    recommended: ["provider", "offers"],
+    imageFields: [],
+  },
+  JobPosting: {
+    required: ["title", "description", "datePosted", "hiringOrganization"],
+    recommended: ["employmentType", "jobLocation", "baseSalary", "validThrough"],
+    imageFields: [],
+  },
 };
 
 interface ValidationIssue {
@@ -216,9 +255,14 @@ function getNestedValue(obj: Record<string, unknown>, field: string): unknown {
   return undefined;
 }
 
-function validateJsonLd(blocks: unknown[]): { issues: ValidationIssue[]; imageUrls: string[] } {
+function validateJsonLd(blocks: unknown[]): {
+  issues: ValidationIssue[];
+  imageUrls: string[];
+  validatedTypes: Set<string>;
+} {
   const issues: ValidationIssue[] = [];
   const imageUrls: string[] = [];
+  const validatedTypes = new Set<string>();
 
   function validateBlock(data: unknown) {
     if (Array.isArray(data)) {
@@ -234,6 +278,7 @@ function validateJsonLd(blocks: unknown[]): { issues: ValidationIssue[]; imageUr
     for (const type of types) {
       const rule = SCHEMA_RULES[String(type)];
       if (!rule) continue;
+      validatedTypes.add(String(type));
 
       for (const field of rule.required) {
         if (getNestedValue(obj, field) === undefined) {
@@ -247,6 +292,27 @@ function validateJsonLd(blocks: unknown[]): { issues: ValidationIssue[]; imageUr
         }
       }
 
+      // Check nested required fields (e.g., offers.price inside Product)
+      if (rule.nestedRequired) {
+        for (const [parent, fields] of Object.entries(rule.nestedRequired)) {
+          const parentVal = obj[parent];
+          if (parentVal && typeof parentVal === "object") {
+            const targets = Array.isArray(parentVal) ? parentVal : [parentVal];
+            for (const target of targets) {
+              if (target && typeof target === "object") {
+                const nested = target as Record<string, unknown>;
+                for (const field of fields) {
+                  if (nested[field] === undefined || nested[field] === null || nested[field] === "") {
+                    issues.push({ type: String(type), level: "required", field: `${parent}.${field}` });
+                  }
+                }
+                break; // Only check the first item in arrays
+              }
+            }
+          }
+        }
+      }
+
       // Collect image URLs for validation
       for (const field of rule.imageFields) {
         const val = obj[field];
@@ -262,17 +328,18 @@ function validateJsonLd(blocks: unknown[]): { issues: ValidationIssue[]; imageUr
       }
     }
 
-    // Recurse into nested objects
+    // Recurse into nested objects and arrays (e.g., @graph)
     for (const val of Object.values(obj)) {
-      if (val && typeof val === "object" && !Array.isArray(val)) {
-        const nested = val as Record<string, unknown>;
-        if (nested["@type"]) validateBlock(nested);
+      if (Array.isArray(val)) {
+        for (const item of val) validateBlock(item);
+      } else if (val && typeof val === "object") {
+        validateBlock(val);
       }
     }
   }
 
   for (const block of blocks) validateBlock(block);
-  return { issues, imageUrls };
+  return { issues, imageUrls, validatedTypes };
 }
 
 // What each recommended field enables (sourced from Google Rich Results docs)
@@ -293,12 +360,31 @@ const FIELD_HINTS: Record<string, string> = {
   "Event.offers": "shows ticket prices in search",
   "Recipe.author": "shown in recipe rich results",
   "VideoObject.duration": "shown in video rich results",
+  "SoftwareApplication.applicationCategory": "shown in software rich results",
+  "SoftwareApplication.operatingSystem": "shown in software rich results",
+  "SoftwareApplication.review": "enables star ratings",
+  "SoftwareApplication.aggregateRating": "enables aggregate star ratings",
+  "Dataset.distribution": "enables dataset download in search",
+  "Dataset.creator": "shown in dataset rich results",
+  "Dataset.license": "shown in dataset rich results",
+  "Course.provider": "shown in course rich results",
+  "Course.offers": "enables price display for courses",
+  "JobPosting.employmentType": "shown in job search results",
+  "JobPosting.jobLocation": "shown in job search results",
+  "JobPosting.baseSalary": "enables salary display in job search",
 };
 
-function formatValidation(issues: ValidationIssue[]): string[] {
-  if (issues.length === 0) return ["All validated types have their required fields."];
-
+function formatValidation(issues: ValidationIssue[], validatedTypes: Set<string>): string[] {
   const lines: string[] = [];
+
+  // Show PASS for types with no required issues
+  const typesWithRequiredIssues = new Set(issues.filter((i) => i.level === "required").map((i) => i.type));
+  for (const type of validatedTypes) {
+    if (!typesWithRequiredIssues.has(type)) {
+      lines.push(`PASS     ${type} — all required fields present`);
+    }
+  }
+
   const required = issues.filter((i) => i.level === "required");
   const recommended = issues.filter((i) => i.level === "recommended");
 
@@ -404,6 +490,20 @@ function formatMetatags(url: string, parsed: ParsedHead): string {
   if (robots) lines.push(`Robots: ${robots}`);
   const author = getMeta(parsed.meta, "author");
   if (author) lines.push(`Author: ${author}`);
+
+  // HTML entity warnings
+  const entityCheck = [
+    { label: "title", value: parsed.title },
+    { label: "description", value: getMeta(parsed.meta, "description") },
+    { label: "og:title", value: getMeta(parsed.meta, "og:title") },
+    { label: "og:description", value: getMeta(parsed.meta, "og:description") },
+  ];
+  for (const { label, value } of entityCheck) {
+    if (value && /&(?:amp|lt|gt|quot|apos|#\d+|#x[\da-f]+);/i.test(value)) {
+      lines.push(`WARN: ${label} contains HTML entities — may render incorrectly in social previews`);
+    }
+  }
+
   lines.push("");
 
   // Open Graph
@@ -566,10 +666,10 @@ export function registerMetatagsTool(server: McpServer): void {
 
         // Structured data validation
         if (parsed.jsonLd.length > 0) {
-          const { issues, imageUrls } = validateJsonLd(parsed.jsonLd);
-          if (issues.length > 0 || imageUrls.length > 0) {
+          const { issues, imageUrls, validatedTypes } = validateJsonLd(parsed.jsonLd);
+          if (validatedTypes.size > 0 || imageUrls.length > 0) {
             output.push("", "--- Structured Data Validation ---", "");
-            output.push(...formatValidation(issues));
+            output.push(...formatValidation(issues, validatedTypes));
 
             // HEAD-check image URLs from structured data
             if (imageUrls.length > 0) {

package/src/tools/pagespeed.ts

@@ -16,6 +16,10 @@ function scoreLabel(score: number | null): string {
   return `${pct} (poor)`;
 }
 
+function scorePct(score: number | null): number | null {
+  return score === null ? null : Math.round(score * 100);
+}
+
 function cwvRating(category: string): string {
   if (category === "FAST") return "good";
   if (category === "AVERAGE") return "needs improvement";
@@ -190,6 +194,8 @@ function formatFailingAudits(audits: Record<string, PsiAudit>, categoryRefs: str
   return lines;
 }
 
+// --- Single URL formatting (existing) ---
+
 function formatPagespeed(url: string, result: PsiResult): string {
   const lhr = result.lighthouseResult;
   const lines: string[] = [
@@ -274,12 +280,234 @@ function formatPagespeed(url: string, result: PsiResult): string {
   return lines.join("\n");
 }
 
+// --- Batch formatting ---
+
+function shortUrl(url: string, allUrls: string[]): string {
+  try {
+    const u = new URL(url);
+    const path = u.pathname + u.search;
+    const hasDuplicate = allUrls.some(
+      (other) => other !== url && new URL(other).pathname + new URL(other).search === path,
+    );
+    return hasDuplicate ? u.hostname + path : path;
+  } catch {
+    return url;
+  }
+}
+
+function formatDelta(a: number | null, b: number | null): string {
+  if (a === null || b === null) return "";
+  const diff = b - a;
+  if (diff === 0) return "  (=)";
+  return diff > 0 ? `  (+${diff})` : `  (${diff})`;
+}
+
+function formatBatchCompare(results: Array<{ url: string; result: PsiResult }>, strategy: string): string {
+  const [a, b] = results;
+  const lhrA = a.result.lighthouseResult;
+  const lhrB = b.result.lighthouseResult;
+
+  const lines: string[] = [
+    `=== PageSpeed Compare (${strategy}) ===`,
+    ``,
+    `A: ${a.url}`,
+    `B: ${b.url}`,
+    `Lighthouse: ${lhrA.lighthouseVersion}`,
+    "",
+    "--- Scores ---",
+    "",
+  ];
+
+  // Score comparison
+  const catIds = Object.keys(lhrA.categories);
+  for (const id of catIds) {
+    const catA = lhrA.categories[id];
+    const catB = lhrB.categories[id];
+    if (!catA || !catB) continue;
+    const pA = scorePct(catA.score);
+    const pB = scorePct(catB.score);
+    const delta = formatDelta(pA, pB);
+    lines.push(`${catA.title}: ${pA ?? "N/A"} → ${pB ?? "N/A"}${delta}`);
+  }
+  lines.push("");
+
+  // CWV comparison
+  const cwvIds = [
+    "first-contentful-paint",
+    "largest-contentful-paint",
+    "total-blocking-time",
+    "cumulative-layout-shift",
+    "speed-index",
+    "interactive",
+  ];
+  const cwvLines: string[] = [];
+  for (const id of cwvIds) {
+    const auditA = lhrA.audits[id];
+    const auditB = lhrB.audits[id];
+    if (!auditA?.displayValue || !auditB?.displayValue) continue;
+    cwvLines.push(`${auditA.title}: ${auditA.displayValue} → ${auditB.displayValue}`);
+  }
+  if (cwvLines.length > 0) {
+    lines.push("--- Core Web Vitals (Lab) ---", "", ...cwvLines, "");
+  }
+
+  // Opportunities unique to each / shared
+  const oppsA = collectOpportunityIds(lhrA.audits);
+  const oppsB = collectOpportunityIds(lhrB.audits);
+  const onlyA = [...oppsA].filter((id) => !oppsB.has(id));
+  const onlyB = [...oppsB].filter((id) => !oppsA.has(id));
+  const shared = [...oppsA].filter((id) => oppsB.has(id));
+
+  if (onlyA.length > 0) {
+    lines.push(`--- Opportunities (A only) ---`, "");
+    for (const id of onlyA) lines.push(`  ${lhrA.audits[id].title}: ${lhrA.audits[id].displayValue ?? ""}`);
+    lines.push("");
+  }
+  if (onlyB.length > 0) {
+    lines.push(`--- Opportunities (B only) ---`, "");
+    for (const id of onlyB) lines.push(`  ${lhrB.audits[id].title}: ${lhrB.audits[id].displayValue ?? ""}`);
+    lines.push("");
+  }
+  if (shared.length > 0) {
+    lines.push(`--- Shared Opportunities ---`, "");
+    for (const id of shared) {
+      lines.push(
+        `  ${lhrA.audits[id].title}: ${lhrA.audits[id].displayValue ?? ""} → ${lhrB.audits[id].displayValue ?? ""}`,
+      );
+    }
+    lines.push("");
+  }
+
+  const timeA = (lhrA.timing.total / 1000).toFixed(1);
+  const timeB = (lhrB.timing.total / 1000).toFixed(1);
+  lines.push(`Analysis took ${timeA}s + ${timeB}s`);
+
+  return lines.join("\n");
+}
+
+function formatBatchTable(results: Array<{ url: string; result: PsiResult }>, strategy: string): string {
+  const lines: string[] = [`=== Batch PageSpeed (${results.length} URLs, ${strategy}) ===`, ""];
+
+  // Collect all category IDs from first result
+  const catIds = Object.keys(results[0].result.lighthouseResult.categories);
+  const catNames = catIds.map((id) => results[0].result.lighthouseResult.categories[id].title);
+
+  // Score table
+  lines.push("--- Scores ---", "");
+
+  // Header
+  const urlCol = "URL";
+  const allUrls = results.map((r) => r.url);
+  const urlWidth = Math.max(urlCol.length, ...results.map((r) => shortUrl(r.url, allUrls).length));
+  const colWidth = Math.max(...catNames.map((n) => n.length), 4);
+  lines.push(`${urlCol.padEnd(urlWidth)}  ${catNames.map((n) => n.padEnd(colWidth)).join("  ")}`);
+
+  // Rows
+  let bestPerf: { url: string; score: number } | null = null;
+  let worstPerf: { url: string; score: number } | null = null;
+
+  for (const { url, result } of results) {
+    const lhr = result.lighthouseResult;
+    const scores = catIds.map((id) => {
+      const s = scorePct(lhr.categories[id]?.score);
+      return s !== null ? String(s) : "N/A";
+    });
+    lines.push(`${shortUrl(url, allUrls).padEnd(urlWidth)}  ${scores.map((s) => s.padEnd(colWidth)).join("  ")}`);
+
+    const perf = scorePct(lhr.categories.performance?.score);
+    if (perf !== null) {
+      if (!bestPerf || perf > bestPerf.score) bestPerf = { url: shortUrl(url, allUrls), score: perf };
+      if (!worstPerf || perf < worstPerf.score) worstPerf = { url: shortUrl(url, allUrls), score: perf };
+    }
+  }
+
+  lines.push("");
+  if (bestPerf) lines.push(`Best: ${bestPerf.url} (${bestPerf.score})`);
+  if (worstPerf && worstPerf.url !== bestPerf?.url) lines.push(`Worst: ${worstPerf.url} (${worstPerf.score})`);
+  lines.push("");
+
+  // Shared opportunities across pages
+  const oppCounts = new Map<string, { title: string; count: number }>();
+  for (const { result } of results) {
+    for (const id of collectOpportunityIds(result.lighthouseResult.audits)) {
+      const existing = oppCounts.get(id);
+      if (existing) {
+        existing.count++;
+      } else {
+        oppCounts.set(id, { title: result.lighthouseResult.audits[id].title, count: 1 });
+      }
+    }
+  }
+
+  const sharedOpps = [...oppCounts.entries()].filter(([, v]) => v.count >= 2).sort((a, b) => b[1].count - a[1].count);
+  if (sharedOpps.length > 0) {
+    lines.push("--- Shared Opportunities ---", "");
+    for (const [, { title, count }] of sharedOpps.slice(0, 10)) {
+      lines.push(`  ${title} (${count}/${results.length} pages)`);
+    }
+    lines.push("");
+  }
+
+  const totalTime = results.reduce((sum, r) => sum + r.result.lighthouseResult.timing.total, 0);
+  lines.push(`Total analysis time: ${(totalTime / 1000).toFixed(1)}s`);
+
+  return lines.join("\n");
+}
+
+function collectOpportunityIds(audits: Record<string, PsiAudit>): Set<string> {
+  const ids = new Set<string>();
+  for (const [id, audit] of Object.entries(audits)) {
+    if (audit.score === null || audit.score >= 1) continue;
+    const mode = audit.scoreDisplayMode;
+    const hasNumeric = audit.numericValue && audit.numericValue > 0;
+    if (mode === "metricSavings" || ((mode === "numeric" || mode === "binary") && hasNumeric)) {
+      if (hasNumeric || (audit.details?.items?.length ?? 0) > 0) {
+        ids.add(id);
+      }
+    }
+  }
+  return ids;
+}
+
+async function runBatch(
+  urls: string[],
+  options: { strategy?: "mobile" | "desktop"; categories?: PsiCategoryType[]; locale?: string },
+): Promise<Array<{ url: string; result?: PsiResult; error?: string }>> {
+  const concurrency = 2;
+  const results: Array<{ url: string; result?: PsiResult; error?: string }> = [];
+  let i = 0;
+
+  while (i < urls.length) {
+    const batch = urls.slice(i, i + concurrency);
+    const settled = await Promise.all(
+      batch.map(async (url) => {
+        try {
+          const result = await runPagespeed(url, options);
+          return { url, result };
+        } catch (err) {
+          return { url, error: err instanceof Error ? err.message : String(err) };
+        }
+      }),
+    );
+    results.push(...settled);
+    i += concurrency;
+  }
+
+  return results;
+}
+
 export function registerPagespeedTool(server: McpServer): void {
   server.tool(
     "pagespeed",
-    "Analyze a page's performance using Google PageSpeed Insights API. Returns Lighthouse scores, Core Web Vitals (lab + field), opportunities, and diagnostics.",
+    "Analyze page performance using Google PageSpeed Insights. Accepts a single URL or multiple URLs (batch mode). With 2 URLs, returns a side-by-side comparison with deltas. With 3-10 URLs, returns a summary table with shared opportunities.",
     {
-      url: z.string().url().describe("The URL to analyze."),
+      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("Multiple URLs (2-10) for batch analysis. 2 URLs = compare mode, 3+ = summary table."),
       strategy: z.enum(["mobile", "desktop"]).optional().describe("Device strategy. Default: 'mobile'."),
       categories: z
         .array(z.enum(["performance", "accessibility", "best-practices", "seo"]))
@@ -287,18 +515,61 @@ export function registerPagespeedTool(server: McpServer): void {
         .describe("Lighthouse categories to run. Default: all four."),
       locale: z.string().optional().describe("Locale for localized results (e.g., 'pt-BR', 'en')."),
     },
-    async ({ url, strategy, categories, locale }) => {
-      try {
-        const result = await runPagespeed(url, {
-          strategy: strategy as "mobile" | "desktop" | undefined,
-          categories: categories as PsiCategoryType[] | undefined,
-          locale,
-        });
-        return { content: [{ type: "text", text: formatPagespeed(url, result) }] };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: `Error running PageSpeed analysis: ${msg}` }] };
+    async ({ url, urls, strategy, categories, locale }) => {
+      const strat = (strategy as "mobile" | "desktop") ?? "mobile";
+      const cats = categories as PsiCategoryType[] | undefined;
+      const opts = { strategy: strat, categories: cats, locale };
+
+      // Validate: must provide url or urls, not both
+      if (url && urls) {
+        return {
+          content: [{ type: "text", text: "Error: provide either 'url' (single) or 'urls' (batch), not both." }],
+        };
+      }
+      if (!url && !urls) {
+        return {
+          content: [{ type: "text", text: "Error: provide 'url' for single analysis or 'urls' for batch analysis." }],
+        };
       }
+
+      // Single URL — existing behavior
+      if (url) {
+        try {
+          const result = await runPagespeed(url, opts);
+          return { content: [{ type: "text", text: formatPagespeed(url, result) }] };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          return { content: [{ type: "text", text: `Error running PageSpeed analysis: ${msg}` }] };
+        }
+      }
+
+      // Batch mode
+      const batchUrls = urls as string[];
+      const results = await runBatch(batchUrls, opts);
+
+      // Separate successes and failures
+      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", text: `All URLs failed:\n${errorLines.join("\n")}` }] };
+      }
+
+      let output: string;
+      if (successes.length === 2) {
+        output = formatBatchCompare(successes, strat);
+      } else {
+        output = formatBatchTable(successes, strat);
+      }
+
+      // Append any failures
+      if (failures.length > 0) {
+        const errorLines = failures.map((f) => `${f.url}: ${f.error}`);
+        output += `\n\n--- Errors ---\n${errorLines.join("\n")}`;
+      }
+
+      return { content: [{ type: "text", text: output }] };
     },
   );
 }

package/src/tools/sample-inspect.ts

@@ -2,13 +2,13 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { inspectUrl, listSitemaps } from "../lib/gsc.js";
 
-interface SitemapParseResult {
+export interface SitemapParseResult {
   urls: string[];
   isSitemapIndex: boolean;
   childSitemaps: string[];
 }
 
-function parseSitemapXml(xml: string): SitemapParseResult {
+export function parseSitemapXml(xml: string): SitemapParseResult {
   const urls: string[] = [];
   const childSitemaps: string[] = [];
 
@@ -28,7 +28,7 @@ function parseSitemapXml(xml: string): SitemapParseResult {
   return { urls, isSitemapIndex, childSitemaps };
 }
 
-async function fetchSitemap(sitemapUrl: string): Promise<SitemapParseResult> {
+export async function fetchSitemap(sitemapUrl: string): Promise<SitemapParseResult> {
   const res = await fetch(sitemapUrl, {
     headers: { "User-Agent": "Pagesight/1.0" },
   });
@@ -41,7 +41,7 @@ async function fetchSitemap(sitemapUrl: string): Promise<SitemapParseResult> {
   return parseSitemapXml(xml);
 }
 
-function sampleUrls(urls: string[], count: number, strategy: string): string[] {
+export function sampleUrls(urls: string[], count: number, strategy: string): string[] {
   if (urls.length <= count) return [...urls];
 
   if (strategy === "first") {
@@ -66,7 +66,7 @@ function sampleUrls(urls: string[], count: number, strategy: string): string[] {
   return shuffled.slice(0, count);
 }
 
-interface InspectionSummary {
+export interface InspectionSummary {
   url: string;
   verdict: string;
   coverageState: string;
@@ -78,7 +78,7 @@ interface InspectionSummary {
   error: string | null;
 }
 
-async function inspectSingle(url: string, siteUrl: string): Promise<InspectionSummary> {
+export async function inspectSingle(url: string, siteUrl: string): Promise<InspectionSummary> {
   try {
     const r = await inspectUrl(url, siteUrl);
     const idx = r.indexStatusResult;