pagesight 0.2.3 → 0.3.0

package/package.json

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

package/src/index.ts

@@ -3,6 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerCruxTool } from "./tools/crux.js";
 import { registerInspectTool } from "./tools/inspect.js";
+import { registerMetatagsTool } from "./tools/metatags.js";
 import { registerPagespeedTool } from "./tools/pagespeed.js";
 import { registerPerformanceTool } from "./tools/performance.js";
 import { registerRobotsTool } from "./tools/robots.js";
@@ -18,6 +19,7 @@ const server = new McpServer({
 
 registerCruxTool(server);
 registerInspectTool(server);
+registerMetatagsTool(server);
 registerPagespeedTool(server);
 registerPerformanceTool(server);
 registerRobotsTool(server);

package/src/lib/auth.ts

@@ -133,6 +133,10 @@ export async function getAccessToken(): Promise<string> {
   );
 }
 
+export function clearTokenCache(): void {
+  cachedToken = null;
+}
+
 export function getAuthMethod(): string {
   if (process.env.GSC_SERVICE_ACCOUNT_KEY) return "service_account";
   if (process.env.GSC_REFRESH_TOKEN) return "oauth";

package/src/lib/gsc.ts

@@ -1,4 +1,4 @@
-import { getAccessToken } from "./auth.js";
+import { clearTokenCache, getAccessToken } from "./auth.js";
 
 const GSC_API = "https://searchconsole.googleapis.com/v1";
 const WEBMASTERS_API = "https://www.googleapis.com/webmasters/v3";
@@ -15,6 +15,8 @@ async function gscFetch(url: string, body?: unknown): Promise<Record<string, unk
   });
 
   if (!res.ok) {
+    // Clear cached token on 401 so next call gets a fresh one
+    if (res.status === 401) clearTokenCache();
     const err = await res.text();
     throw new Error(`GSC API error (${res.status}): ${err}`);
   }

package/src/lib/psi.ts

@@ -4,6 +4,30 @@ export interface PsiCategory {
   id: string;
   title: string;
   score: number | null;
+  auditRefs?: Array<{ id: string; weight: number }>;
+}
+
+export interface PsiAuditDetailItem {
+  node?: {
+    selector: string;
+    snippet?: string;
+    nodeLabel?: string;
+    explanation?: string;
+  };
+  // Table-style items (performance opportunities, SEO, etc.)
+  url?: string;
+  wastedBytes?: number;
+  wastedMs?: number;
+  totalBytes?: number;
+  // Generic key-value items
+  [key: string]: unknown;
+}
+
+export interface PsiAuditDetails {
+  type: string;
+  items?: PsiAuditDetailItem[];
+  overallSavingsMs?: number;
+  overallSavingsBytes?: number;
 }
 
 export interface PsiAudit {
@@ -15,6 +39,7 @@ export interface PsiAudit {
   displayValue?: string;
   numericValue?: number;
   numericUnit?: string;
+  details?: PsiAuditDetails;
 }
 
 export interface PsiMetric {

package/src/tools/crux.ts

@@ -177,7 +177,10 @@ export function registerCruxTool(server: McpServer): void {
     },
     async ({ url, origin, form_factor, metrics }) => {
       if (!url && !origin) {
-        return { content: [{ type: "text", text: "Error: provide either url or 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({
@@ -248,7 +251,10 @@ export function registerCruxTool(server: McpServer): void {
     },
     async ({ url, origin, form_factor, metrics, periods }) => {
       if (!url && !origin) {
-        return { content: [{ type: "text", text: "Error: provide either url or 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({

package/src/tools/inspect.ts

@@ -89,11 +89,22 @@ export function registerInspectTool(server: McpServer): void {
       } 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: URL "${url}" is not part of property "${site_url}", or you don't have access.`,
+                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"),
               },
             ],
           };

package/src/tools/metatags.ts

@@ -0,0 +1,273 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+interface MetaTag {
+  name?: string;
+  property?: string;
+  content: string;
+}
+
+interface ParsedHead {
+  title: string | null;
+  charset: string | null;
+  canonical: string | null;
+  meta: MetaTag[];
+  hreflang: Array<{ lang: string; href: string }>;
+  jsonLd: unknown[];
+}
+
+function parseHead(html: string): ParsedHead {
+  // Extract <head> content (case-insensitive, handles attributes on <head>)
+  const headMatch = html.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
+  const head = headMatch?.[1] ?? html;
+
+  // Title
+  const titleMatch = head.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  const title = titleMatch ? titleMatch[1].trim() : null;
+
+  // Charset
+  const charsetMatch = head.match(/<meta\s+charset=["']([^"']+)["']/i) ?? head.match(/charset=["']?([^"'\s;>]+)/i);
+  const charset = charsetMatch ? charsetMatch[1] : null;
+
+  // Canonical
+  const canonicalMatch = head.match(/<link[^>]*rel=["']canonical["'][^>]*href=["']([^"']+)["']/i);
+  const canonical = canonicalMatch ? canonicalMatch[1] : null;
+
+  // Meta tags (name=... content=... and property=... content=...)
+  const meta: MetaTag[] = [];
+  for (const m of head.matchAll(/<meta\s+([^>]*?)>/gi)) {
+    const attrs = m[1];
+    const nameMatch = attrs.match(/name=["']([^"']+)["']/i);
+    const propMatch = attrs.match(/property=["']([^"']+)["']/i);
+    const contentMatch = attrs.match(/content=["']([^"']*?)["']/i);
+    if (contentMatch && (nameMatch || propMatch)) {
+      meta.push({
+        name: nameMatch?.[1],
+        property: propMatch?.[1],
+        content: contentMatch[1],
+      });
+    }
+  }
+
+  // Hreflang
+  const hreflang: Array<{ lang: string; href: string }> = [];
+  const hreflangRegex =
+    /<link[^>]*rel=["']alternate["'][^>]*hreflang=["']([^"']+)["'][^>]*href=["']([^"']+)["'][^>]*>/gi;
+  const hreflangRegex2 =
+    /<link[^>]*hreflang=["']([^"']+)["'][^>]*href=["']([^"']+)["'][^>]*rel=["']alternate["'][^>]*>/gi;
+  const hreflangRegex3 =
+    /<link[^>]*href=["']([^"']+)["'][^>]*hreflang=["']([^"']+)["'][^>]*rel=["']alternate["'][^>]*>/gi;
+  for (const rx of [hreflangRegex, hreflangRegex2]) {
+    for (const hm of head.matchAll(rx)) {
+      hreflang.push({ lang: hm[1], href: hm[2] });
+    }
+  }
+  for (const hm of head.matchAll(hreflangRegex3)) {
+    hreflang.push({ lang: hm[2], href: hm[1] });
+  }
+
+  // JSON-LD
+  const jsonLd: unknown[] = [];
+  for (const ld of html.matchAll(/<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)) {
+    try {
+      jsonLd.push(JSON.parse(ld[1]));
+    } catch {
+      // malformed JSON-LD, skip
+    }
+  }
+
+  return { title, charset, canonical, meta, hreflang, jsonLd };
+}
+
+function getMeta(meta: MetaTag[], key: string): string | null {
+  const tag = meta.find(
+    (m) => m.name?.toLowerCase() === key.toLowerCase() || m.property?.toLowerCase() === key.toLowerCase(),
+  );
+  return tag?.content ?? null;
+}
+
+function getAllMeta(meta: MetaTag[], prefix: string): Array<{ key: string; value: string }> {
+  const results: Array<{ key: string; value: string }> = [];
+  for (const tag of meta) {
+    const key = tag.property ?? tag.name ?? "";
+    if (key.toLowerCase().startsWith(prefix.toLowerCase())) {
+      results.push({ key, value: tag.content });
+    }
+  }
+  return results;
+}
+
+function formatJsonLd(data: unknown, indent = 0): string[] {
+  const lines: string[] = [];
+  const pad = "  ".repeat(indent);
+
+  if (Array.isArray(data)) {
+    for (const item of data) {
+      lines.push(...formatJsonLd(item, indent));
+    }
+    return lines;
+  }
+
+  if (data && typeof data === "object") {
+    const obj = data as Record<string, unknown>;
+    const type = obj["@type"];
+    if (type) lines.push(`${pad}@type: ${Array.isArray(type) ? type.join(", ") : type}`);
+
+    for (const [key, val] of Object.entries(obj)) {
+      if (key.startsWith("@") && key !== "@type") continue;
+      if (key === "@type") continue;
+      if (typeof val === "string" || typeof val === "number" || typeof val === "boolean") {
+        const str = String(val);
+        lines.push(`${pad}${key}: ${str.length > 100 ? `${str.slice(0, 100)}...` : str}`);
+      } else if (Array.isArray(val)) {
+        lines.push(`${pad}${key}: [${val.length} items]`);
+      } else if (val && typeof val === "object") {
+        const nested = val as Record<string, unknown>;
+        if (nested["@type"]) {
+          lines.push(`${pad}${key}:`);
+          lines.push(...formatJsonLd(nested, indent + 1));
+        }
+      }
+    }
+  }
+
+  return lines;
+}
+
+function formatMetatags(url: string, parsed: ParsedHead): string {
+  const lines: string[] = [`=== Meta Tags: ${url} ===`, ""];
+
+  // Document
+  lines.push("--- Document ---", "");
+  lines.push(`Title: ${parsed.title ? `"${parsed.title}"` : "(missing)"}`);
+  lines.push(
+    `Description: ${getMeta(parsed.meta, "description") ? `"${getMeta(parsed.meta, "description")}"` : "(missing)"}`,
+  );
+  lines.push(`Charset: ${parsed.charset ?? "(missing)"}`);
+  lines.push(`Viewport: ${getMeta(parsed.meta, "viewport") ?? "(missing)"}`);
+  lines.push(`Canonical: ${parsed.canonical ?? "(not set)"}`);
+  const robots = getMeta(parsed.meta, "robots");
+  if (robots) lines.push(`Robots: ${robots}`);
+  const author = getMeta(parsed.meta, "author");
+  if (author) lines.push(`Author: ${author}`);
+  lines.push("");
+
+  // Open Graph
+  const ogTags = getAllMeta(parsed.meta, "og:");
+  lines.push("--- Open Graph ---", "");
+  if (ogTags.length > 0) {
+    for (const tag of ogTags) {
+      lines.push(`${tag.key}: ${tag.value}`);
+    }
+  } else {
+    lines.push("(none found)");
+  }
+  lines.push("");
+
+  // Twitter Card
+  const twitterTags = getAllMeta(parsed.meta, "twitter:");
+  lines.push("--- Twitter Card ---", "");
+  if (twitterTags.length > 0) {
+    for (const tag of twitterTags) {
+      lines.push(`${tag.key}: ${tag.value}`);
+    }
+  } else {
+    lines.push("(none found)");
+  }
+  lines.push("");
+
+  // Structured Data
+  lines.push("--- Structured Data (JSON-LD) ---", "");
+  if (parsed.jsonLd.length > 0) {
+    for (let i = 0; i < parsed.jsonLd.length; i++) {
+      if (i > 0) lines.push("");
+      lines.push(`Block ${i + 1}:`);
+      lines.push(...formatJsonLd(parsed.jsonLd[i], 1));
+    }
+  } else {
+    lines.push("(none found)");
+  }
+  lines.push("");
+
+  // Hreflang
+  if (parsed.hreflang.length > 0) {
+    lines.push("--- Alternate Languages ---", "");
+    for (const h of parsed.hreflang) {
+      lines.push(`${h.lang}: ${h.href}`);
+    }
+    lines.push("");
+  }
+
+  // Summary of missing tags relevant to search and social
+  const missing: string[] = [];
+  if (!parsed.title) missing.push("title");
+  if (!getMeta(parsed.meta, "description")) missing.push("meta description");
+  if (!parsed.canonical) missing.push("canonical URL");
+  if (ogTags.length === 0) missing.push("Open Graph tags");
+  else {
+    if (!getMeta(parsed.meta, "og:image")) missing.push("og:image");
+  }
+  if (twitterTags.length === 0) missing.push("Twitter Card tags");
+  if (parsed.jsonLd.length === 0) missing.push("structured data (JSON-LD)");
+
+  if (missing.length > 0) {
+    lines.push("--- Not Found ---", "");
+    for (const m of missing) {
+      lines.push(`- ${m}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function registerMetatagsTool(server: McpServer): void {
+  server.tool(
+    "metatags",
+    "Fetch a page and report its meta tags, Open Graph, Twitter Card, canonical URL, structured data (JSON-LD), and hreflang. Shows what search engines and social platforms see.",
+    {
+      url: z.string().url().describe("The URL to fetch and analyze."),
+      user_agent: z.string().optional().describe("Custom User-Agent string. Default: Googlebot-compatible."),
+    },
+    async ({ url, user_agent }) => {
+      try {
+        const ua = user_agent ?? "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)";
+        const res = await fetch(url, {
+          headers: {
+            "User-Agent": ua,
+            Accept: "text/html",
+          },
+          redirect: "follow",
+        });
+
+        if (!res.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error fetching ${url}: HTTP ${res.status} ${res.statusText}`,
+              },
+            ],
+          };
+        }
+
+        const html = await res.text();
+        const parsed = parseHead(html);
+        const finalUrl = res.url !== url ? `(redirected to ${res.url})\n\n` : "";
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${finalUrl}${formatMetatags(res.url, parsed)}`,
+            },
+          ],
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error fetching meta tags: ${msg}` }],
+        };
+      }
+    },
+  );
+}

package/src/tools/pagespeed.ts

@@ -1,6 +1,12 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { type PsiAudit, type PsiCategoryType, type PsiResult, runPagespeed } from "../lib/psi.js";
+import {
+  type PsiAudit,
+  type PsiAuditDetailItem,
+  type PsiCategoryType,
+  type PsiResult,
+  runPagespeed,
+} from "../lib/psi.js";
 
 function scoreLabel(score: number | null): string {
   if (score === null) return "N/A";
@@ -43,27 +49,38 @@ function formatLoadingExperience(label: string, exp: PsiResult["loadingExperienc
 }
 
 function formatOpportunities(audits: Record<string, PsiAudit>): string[] {
-  const opportunities: Array<{ title: string; savings: string; score: number }> = [];
+  const opportunities: PsiAudit[] = [];
 
   for (const audit of Object.values(audits)) {
     if (audit.score !== null && audit.score < 1 && audit.numericValue && audit.numericValue > 0) {
       if (audit.scoreDisplayMode === "numeric" || audit.scoreDisplayMode === "binary") {
-        const unit = audit.numericUnit === "millisecond" ? "ms" : audit.numericUnit === "byte" ? " bytes" : "";
-        const savings = audit.displayValue ?? `${Math.round(audit.numericValue)}${unit}`;
-        opportunities.push({ title: audit.title, savings, score: audit.score });
+        opportunities.push(audit);
       }
     }
   }
 
   if (opportunities.length === 0) return [];
 
-  opportunities.sort((a, b) => a.score - b.score);
+  opportunities.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
 
   const lines: string[] = ["--- Opportunities ---", ""];
-  for (const opp of opportunities.slice(0, 10)) {
-    const severity = opp.score < 0.5 ? "HIGH" : opp.score < 0.9 ? "MEDIUM" : "LOW";
-    lines.push(`${severity}  ${opp.title}`);
-    lines.push(`  Potential savings: ${opp.savings}`);
+  for (const audit of opportunities.slice(0, 10)) {
+    const severity = (audit.score ?? 0) < 0.5 ? "HIGH" : (audit.score ?? 0) < 0.9 ? "MEDIUM" : "LOW";
+    const unit = audit.numericUnit === "millisecond" ? "ms" : audit.numericUnit === "byte" ? " bytes" : "";
+    const savings = audit.displayValue ?? `${Math.round(audit.numericValue ?? 0)}${unit}`;
+    lines.push(`${severity}  ${audit.title}`);
+    lines.push(`  Potential savings: ${savings}`);
+
+    const items = audit.details?.items;
+    if (items && items.length > 0) {
+      for (const item of items.slice(0, 3)) {
+        lines.push(...formatDetailItem(item));
+      }
+      if (items.length > 3) {
+        lines.push(`  ... and ${items.length - 3} more resources`);
+      }
+    }
+    lines.push("");
   }
 
   return lines;
@@ -88,6 +105,66 @@ function formatDiagnostics(audits: Record<string, PsiAudit>): string[] {
   return lines;
 }
 
+function formatDetailItem(item: PsiAuditDetailItem): string[] {
+  const lines: string[] = [];
+
+  if (item.node) {
+    const n = item.node;
+    if (n.nodeLabel) lines.push(`  Element: "${n.nodeLabel}"`);
+    if (n.selector) lines.push(`  Selector: ${n.selector}`);
+    if (n.snippet) lines.push(`  HTML: ${n.snippet}`);
+    if (n.explanation) lines.push(`  Issue: ${n.explanation}`);
+  } else if (item.url) {
+    const parts = [`  ${item.url}`];
+    if (item.wastedMs) parts.push(`wastedMs=${Math.round(item.wastedMs)}`);
+    if (item.wastedBytes) parts.push(`wastedBytes=${Math.round(item.wastedBytes)}`);
+    if (item.totalBytes) parts.push(`totalBytes=${Math.round(item.totalBytes)}`);
+    lines.push(parts.join("  "));
+  }
+
+  return lines;
+}
+
+function formatFailingAudits(audits: Record<string, PsiAudit>, categoryRefs: string[]): string[] {
+  const failing: PsiAudit[] = [];
+
+  for (const ref of categoryRefs) {
+    const audit = audits[ref];
+    if (audit && audit.score !== null && audit.score < 1) {
+      failing.push(audit);
+    }
+  }
+
+  if (failing.length === 0) return [];
+
+  failing.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
+
+  const lines: string[] = [];
+  for (const audit of failing) {
+    const severity = audit.score === 0 ? "FAIL" : (audit.score ?? 0) < 0.5 ? "WARN" : "INFO";
+    lines.push(`[${severity}] ${audit.title}`);
+    if (audit.displayValue) lines.push(`  Value: ${audit.displayValue}`);
+
+    // Extract learn-more URL from description markdown
+    const linkMatch = audit.description?.match(/\[.*?\]\((https?:\/\/[^)]+)\)/);
+    if (linkMatch) lines.push(`  Learn more: ${linkMatch[1]}`);
+
+    const items = audit.details?.items;
+    if (items && items.length > 0) {
+      const maxItems = 5;
+      for (const item of items.slice(0, maxItems)) {
+        lines.push(...formatDetailItem(item));
+      }
+      if (items.length > maxItems) {
+        lines.push(`  ... and ${items.length - maxItems} more`);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines;
+}
+
 function formatPagespeed(url: string, result: PsiResult): string {
   const lhr = result.lighthouseResult;
   const lines: string[] = [
@@ -153,6 +230,19 @@ function formatPagespeed(url: string, result: PsiResult): string {
   const diags = formatDiagnostics(lhr.audits);
   if (diags.length > 0) lines.push(...diags, "");
 
+  // Failing audits per non-performance category (a11y, SEO, best practices)
+  for (const cat of Object.values(lhr.categories)) {
+    if (cat.id === "performance" || !cat.auditRefs) continue;
+    const score = cat.score !== null ? Math.round(cat.score * 100) : null;
+    if (score === null || score >= 100) continue;
+
+    const refs = cat.auditRefs.map((r) => r.id);
+    const details = formatFailingAudits(lhr.audits, refs);
+    if (details.length > 0) {
+      lines.push(`--- ${cat.title} Issues ---`, "", ...details);
+    }
+  }
+
   // Timing
   lines.push(`Analysis took ${(lhr.timing.total / 1000).toFixed(1)}s`);
 

package/src/tools/performance.ts

@@ -52,7 +52,7 @@ function formatPerformance(
 
   const top = rows.slice(0, 25);
   for (const row of top) {
-    const keys = row.keys.join(" | ");
+    const keys = row.keys.map((k, i) => `${dimensions[i] ?? "key"}=${k}`).join(" | ");
     lines.push(`${keys}`);
     lines.push(
       `  Clicks: ${row.clicks} | Impressions: ${row.impressions} | CTR: ${(row.ctr * 100).toFixed(1)}% | Position: ${row.position.toFixed(1)}`,