pagesight 0.1.0

package/src/tools/pagespeed.ts

@@ -0,0 +1,189 @@
+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";
+
+function scoreLabel(score: number | null): string {
+  if (score === null) return "N/A";
+  const pct = Math.round(score * 100);
+  if (pct >= 90) return `${pct} (good)`;
+  if (pct >= 50) return `${pct} (needs improvement)`;
+  return `${pct} (poor)`;
+}
+
+function cwvRating(category: string): string {
+  if (category === "FAST") return "good";
+  if (category === "AVERAGE") return "needs improvement";
+  if (category === "SLOW") return "poor";
+  return category;
+}
+
+function formatLoadingExperience(label: string, exp: PsiResult["loadingExperience"]): string[] {
+  if (!exp?.metrics || Object.keys(exp.metrics).length === 0) return [];
+
+  const lines: string[] = [`--- ${label} (CrUX Field Data) ---`, ""];
+  lines.push(`Overall: ${cwvRating(exp.overall_category)}`, "");
+
+  const metricNames: Record<string, string> = {
+    CUMULATIVE_LAYOUT_SHIFT_SCORE: "CLS",
+    EXPERIMENTAL_TIME_TO_FIRST_BYTE: "TTFB",
+    FIRST_CONTENTFUL_PAINT_MS: "FCP",
+    FIRST_INPUT_DELAY_MS: "FID",
+    INTERACTION_TO_NEXT_PAINT: "INP",
+    LARGEST_CONTENTFUL_PAINT_MS: "LCP",
+  };
+
+  for (const [key, metric] of Object.entries(exp.metrics)) {
+    const name = metricNames[key] ?? key;
+    const unit = key.includes("LAYOUT_SHIFT") ? "" : "ms";
+    const value = key.includes("LAYOUT_SHIFT") ? (metric.percentile / 100).toFixed(2) : `${metric.percentile}${unit}`;
+    lines.push(`${name}: ${value} (${cwvRating(metric.category)})`);
+  }
+
+  return lines;
+}
+
+function formatOpportunities(audits: Record<string, PsiAudit>): string[] {
+  const opportunities: Array<{ title: string; savings: string; score: number }> = [];
+
+  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 });
+      }
+    }
+  }
+
+  if (opportunities.length === 0) return [];
+
+  opportunities.sort((a, b) => a.score - b.score);
+
+  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}`);
+  }
+
+  return lines;
+}
+
+function formatDiagnostics(audits: Record<string, PsiAudit>): string[] {
+  const failing: Array<{ title: string; displayValue: string }> = [];
+
+  for (const audit of Object.values(audits)) {
+    if (audit.score !== null && audit.score < 0.5 && audit.scoreDisplayMode === "numeric" && audit.displayValue) {
+      failing.push({ title: audit.title, displayValue: audit.displayValue });
+    }
+  }
+
+  if (failing.length === 0) return [];
+
+  const lines: string[] = ["--- Diagnostics ---", ""];
+  for (const item of failing.slice(0, 10)) {
+    lines.push(`${item.title}: ${item.displayValue}`);
+  }
+
+  return lines;
+}
+
+function formatPagespeed(url: string, result: PsiResult): string {
+  const lhr = result.lighthouseResult;
+  const lines: string[] = [
+    `=== PageSpeed: ${url} ===`,
+    `Strategy: ${lhr.configSettings.emulatedFormFactor}`,
+    `Lighthouse: ${lhr.lighthouseVersion}`,
+    `Analyzed: ${result.analysisUTCTimestamp}`,
+    "",
+  ];
+
+  // Runtime errors
+  if (lhr.runtimeError) {
+    lines.push(`ERROR: ${lhr.runtimeError.code} — ${lhr.runtimeError.message}`, "");
+  }
+
+  // Warnings
+  if (lhr.runWarnings && lhr.runWarnings.length > 0) {
+    for (const w of lhr.runWarnings) {
+      lines.push(`WARNING: ${w}`);
+    }
+    lines.push("");
+  }
+
+  // Category scores
+  lines.push("--- Scores ---", "");
+  for (const cat of Object.values(lhr.categories)) {
+    lines.push(`${cat.title}: ${scoreLabel(cat.score)}`);
+  }
+  lines.push("");
+
+  // Core Web Vitals from audits
+  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 audit = lhr.audits[id];
+    if (audit?.displayValue) {
+      cwvLines.push(`${audit.title}: ${audit.displayValue} ${scoreLabel(audit.score)}`);
+    }
+  }
+  if (cwvLines.length > 0) {
+    lines.push("--- Core Web Vitals (Lab) ---", "", ...cwvLines, "");
+  }
+
+  // CrUX field data
+  const pageExp = formatLoadingExperience("Page", result.loadingExperience);
+  if (pageExp.length > 0) lines.push(...pageExp, "");
+
+  const originExp = formatLoadingExperience("Origin", result.originLoadingExperience);
+  if (originExp.length > 0) lines.push(...originExp, "");
+
+  // Opportunities
+  const opps = formatOpportunities(lhr.audits);
+  if (opps.length > 0) lines.push(...opps, "");
+
+  // Diagnostics
+  const diags = formatDiagnostics(lhr.audits);
+  if (diags.length > 0) lines.push(...diags, "");
+
+  // Timing
+  lines.push(`Analysis took ${(lhr.timing.total / 1000).toFixed(1)}s`);
+
+  return lines.join("\n");
+}
+
+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.",
+    {
+      url: z.string().url().describe("The URL to analyze."),
+      strategy: z.enum(["mobile", "desktop"]).optional().describe("Device strategy. Default: 'mobile'."),
+      categories: z
+        .array(z.enum(["performance", "accessibility", "best-practices", "seo"]))
+        .optional()
+        .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}` }] };
+      }
+    },
+  );
+}

package/src/tools/performance.ts

@@ -0,0 +1,167 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { querySearchAnalytics, type SearchAnalyticsFilter, type SearchAnalyticsResponse } from "../lib/gsc.js";
+
+function formatPerformance(
+  siteUrl: string,
+  result: SearchAnalyticsResponse,
+  dimensions: string[],
+  startDate: string,
+  endDate: string,
+): string {
+  const rows = result.rows ?? [];
+  const lines: string[] = [
+    `=== Search Performance: ${siteUrl} ===`,
+    `Period: ${startDate} to ${endDate}`,
+    `Dimensions: ${dimensions.join(", ")}`,
+    `Aggregation: ${result.responseAggregationType ?? "auto"}`,
+    `Results: ${rows.length}`,
+    "",
+  ];
+
+  if (result.metadata) {
+    if (result.metadata.first_incomplete_date)
+      lines.push(`Data incomplete from: ${result.metadata.first_incomplete_date}`);
+    if (result.metadata.first_incomplete_hour)
+      lines.push(`Hourly data incomplete from: ${result.metadata.first_incomplete_hour}`);
+    lines.push("");
+  }
+
+  if (rows.length === 0) {
+    lines.push("No data found for this period and filters.");
+    return lines.join("\n");
+  }
+
+  const totalClicks = rows.reduce((sum, r) => sum + r.clicks, 0);
+  const totalImpressions = rows.reduce((sum, r) => sum + r.impressions, 0);
+  const avgCtr = totalImpressions > 0 ? totalClicks / totalImpressions : 0;
+  const avgPosition =
+    totalImpressions > 0 ? rows.reduce((sum, r) => sum + r.position * r.impressions, 0) / totalImpressions : 0;
+
+  lines.push(
+    "--- Totals ---",
+    "",
+    `Clicks: ${totalClicks.toLocaleString()}`,
+    `Impressions: ${totalImpressions.toLocaleString()}`,
+    `Avg CTR: ${(avgCtr * 100).toFixed(1)}%`,
+    `Avg Position: ${avgPosition.toFixed(1)}`,
+    "",
+    "--- Top Results ---",
+    "",
+  );
+
+  const top = rows.slice(0, 25);
+  for (const row of top) {
+    const keys = row.keys.join(" | ");
+    lines.push(`${keys}`);
+    lines.push(
+      `  Clicks: ${row.clicks} | Impressions: ${row.impressions} | CTR: ${(row.ctr * 100).toFixed(1)}% | Position: ${row.position.toFixed(1)}`,
+    );
+  }
+
+  if (rows.length > 25) {
+    lines.push("", `... and ${rows.length - 25} more rows`);
+  }
+
+  return lines.join("\n");
+}
+
+function daysAgo(n: number): string {
+  const d = new Date();
+  d.setDate(d.getDate() - n);
+  return d.toISOString().split("T")[0];
+}
+
+export function registerPerformanceTool(server: McpServer): void {
+  server.tool(
+    "performance",
+    "Query Google Search Console search analytics. Returns clicks, impressions, CTR, and position data. Supports all dimensions, search types, filter operators, aggregation modes, and pagination.",
+    {
+      site_url: z.string().describe("The GSC property (e.g., 'https://example.com/' or 'sc-domain:example.com')"),
+      start_date: z.string().optional().describe("Start date (YYYY-MM-DD). Default: 28 days ago."),
+      end_date: z.string().optional().describe("End date (YYYY-MM-DD). Default: 3 days ago."),
+      dimensions: z
+        .array(z.enum(["query", "page", "country", "device", "date", "searchAppearance", "hour"]))
+        .optional()
+        .describe(
+          "Dimensions to group by. Default: ['query', 'page']. Use 'hour' for hourly data (requires dataState='hourly_all').",
+        ),
+      search_type: z
+        .enum(["web", "image", "video", "news", "discover", "googleNews"])
+        .optional()
+        .describe("Filter by search type. Default: 'web'."),
+      data_state: z
+        .enum(["all", "final", "hourly_all"])
+        .optional()
+        .describe(
+          "Data freshness. 'all' includes fresh data, 'final' only finalized, 'hourly_all' for hourly granularity. Default: 'all'.",
+        ),
+      aggregation_type: z
+        .enum(["auto", "byPage", "byProperty", "byNewsShowcasePanel"])
+        .optional()
+        .describe("How to aggregate results. Default: 'auto'."),
+      filters: z
+        .array(
+          z.object({
+            dimension: z
+              .enum(["query", "page", "country", "device", "searchAppearance"])
+              .describe("Dimension to filter on."),
+            operator: z
+              .enum(["equals", "contains", "notEquals", "notContains", "includingRegex", "excludingRegex"])
+              .describe("Filter operator."),
+            expression: z
+              .string()
+              .describe(
+                "Filter value. For country use ISO 3166-1 alpha-3 (e.g., 'FRA'). For device: 'DESKTOP', 'MOBILE', 'TABLET'.",
+              ),
+          }),
+        )
+        .optional()
+        .describe("Dimension filters. Combined with AND logic."),
+      row_limit: z.number().optional().describe("Max rows (1-25000). Default: 1000."),
+      start_row: z.number().optional().describe("Zero-based offset for pagination. Default: 0."),
+    },
+    async ({
+      site_url,
+      start_date,
+      end_date,
+      dimensions,
+      search_type,
+      data_state,
+      aggregation_type,
+      filters,
+      row_limit,
+      start_row,
+    }) => {
+      const startDate = start_date ?? daysAgo(28);
+      const endDate = end_date ?? daysAgo(3);
+      const dims = dimensions ?? ["query", "page"];
+
+      const filterGroups =
+        filters && filters.length > 0
+          ? [{ groupType: "and" as const, filters: filters as SearchAnalyticsFilter[] }]
+          : undefined;
+
+      try {
+        const result = await querySearchAnalytics(site_url, {
+          startDate,
+          endDate,
+          dimensions: dims,
+          type: search_type,
+          dataState: data_state,
+          aggregationType: aggregation_type,
+          rowLimit: row_limit ?? 1000,
+          startRow: start_row,
+          dimensionFilterGroups: filterGroups,
+        });
+
+        return {
+          content: [{ type: "text", text: formatPerformance(site_url, result, dims, startDate, endDate) }],
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error querying search analytics: ${msg}` }] };
+      }
+    },
+  );
+}

package/src/tools/robots.ts

@@ -0,0 +1,131 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { auditAiCrawlers, type CrawlerStatus, fetchRobotsTxt, isAllowed, type RobotsTxt } from "../lib/robots.js";
+
+function formatCrawlerStatus(statuses: CrawlerStatus[]): string {
+  const lines: string[] = [];
+
+  // Group by category
+  const categories = new Map<string, CrawlerStatus[]>();
+  for (const s of statuses) {
+    const cat = s.category;
+    if (!categories.has(cat)) categories.set(cat, []);
+    categories.get(cat)?.push(s);
+  }
+
+  for (const [cat, bots] of categories) {
+    lines.push(`--- ${cat} (${bots.length}) ---`, "");
+
+    for (const bot of bots) {
+      const status = bot.allowed ? "ALLOWED" : "BLOCKED";
+      lines.push(`  ${status}  ${bot.name} (${bot.company})`);
+      if (bot.matchedRule) {
+        lines.push(`          Rule: ${bot.matchedRule.type}: ${bot.matchedRule.path} (group: ${bot.matchedGroup})`);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd();
+}
+
+function formatRobotsAudit(origin: string, robots: RobotsTxt, statusCode: number, crawlers: CrawlerStatus[]): string {
+  const lines: string[] = [`=== robots.txt: ${origin} ===`, `Status: ${statusCode}`, ""];
+
+  const totalRules = robots.groups.reduce((sum, g) => sum + g.rules.length, 0);
+  lines.push(`Groups: ${robots.groups.length}`);
+  lines.push(`Rules: ${totalRules}`);
+  lines.push(`Sitemaps: ${robots.sitemaps.length}`);
+
+  if (robots.errors.length > 0) {
+    lines.push(`Parse errors: ${robots.errors.length}`, "");
+    lines.push("--- Parse Errors ---", "");
+    for (const err of robots.errors) {
+      lines.push(`  ${err}`);
+    }
+  }
+
+  if (robots.sitemaps.length > 0) {
+    lines.push("", "--- Sitemaps ---", "");
+    for (const sm of robots.sitemaps) {
+      lines.push(`  ${sm}`);
+    }
+  }
+
+  if (robots.groups.length > 0) {
+    lines.push("", "--- User-Agent Groups ---", "");
+    for (const group of robots.groups) {
+      const agents = group.userAgents.join(", ");
+      const allows = group.rules.filter((r) => r.type === "allow").length;
+      const disallows = group.rules.filter((r) => r.type === "disallow").length;
+      lines.push(`  ${agents}: ${disallows} disallow, ${allows} allow`);
+    }
+  }
+
+  // AI Crawler audit
+  const allowed = crawlers.filter((c) => c.allowed);
+  const blocked = crawlers.filter((c) => !c.allowed);
+
+  lines.push(
+    "",
+    `--- AI Crawlers: ${blocked.length} blocked, ${allowed.length} allowed (of ${crawlers.length} known) ---`,
+    "",
+    `Source: github.com/ai-robots-txt/ai.robots.txt (${crawlers.length} bots)`,
+    "",
+  );
+  lines.push(formatCrawlerStatus(crawlers));
+
+  return lines.join("\n");
+}
+
+export function registerRobotsTool(server: McpServer): void {
+  server.tool(
+    "robots",
+    "Fetch and analyze a site's robots.txt. Validates syntax per RFC 9309, audits AI crawler access (130+ bots from ai-robots-txt registry), lists sitemaps, and reports blocked vs allowed bots by category.",
+    {
+      url: z
+        .string()
+        .describe("Site URL or origin (e.g., 'https://example.com'). Fetches /robots.txt from this origin."),
+      check_path: z
+        .string()
+        .optional()
+        .describe("Optional: check if a specific path is allowed/blocked for a given user-agent."),
+      user_agent: z
+        .string()
+        .optional()
+        .describe("Optional: user-agent to check path access for. Default: 'Googlebot'."),
+    },
+    async ({ url, check_path, user_agent }) => {
+      try {
+        const origin = new URL(url).origin;
+        const { robotsTxt, statusCode } = await fetchRobotsTxt(origin);
+
+        if (check_path) {
+          const ua = user_agent ?? "Googlebot";
+          const result = isAllowed(robotsTxt, ua, check_path);
+          const status = result.allowed ? "ALLOWED" : "BLOCKED";
+          const lines = [
+            "=== robots.txt path check ===",
+            `Origin: ${origin}`,
+            `User-Agent: ${ua}`,
+            `Path: ${check_path}`,
+            `Result: ${status}`,
+          ];
+          if (result.matchedRule) {
+            lines.push(`Matched rule: ${result.matchedRule.type}: ${result.matchedRule.path}`);
+            lines.push(`Matched group: ${result.matchedGroup}`);
+          } else {
+            lines.push("No matching rule found (default: allowed)");
+          }
+          return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+
+        const crawlers = await auditAiCrawlers(robotsTxt);
+        return { content: [{ type: "text", text: formatRobotsAudit(origin, robotsTxt, statusCode, crawlers) }] };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error analyzing robots.txt: ${msg}` }] };
+      }
+    },
+  );
+}

package/src/tools/setup.ts

@@ -0,0 +1,114 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { exchangeCodeForToken, getAuthMethod, getOAuthSetupUrl } from "../lib/auth.js";
+
+export function registerSetupTool(server: McpServer): void {
+  server.tool(
+    "setup",
+    "Check authentication status or get OAuth setup instructions for Google Search Console.",
+    {
+      action: z
+        .enum(["status", "get_auth_url", "exchange_code"])
+        .describe("'status' to check auth, 'get_auth_url' to start OAuth flow, 'exchange_code' to complete it."),
+      client_id: z.string().optional().describe("Google OAuth client ID (for get_auth_url and exchange_code)."),
+      client_secret: z.string().optional().describe("Google OAuth client secret (for exchange_code)."),
+      code: z.string().optional().describe("Authorization code from Google (for exchange_code)."),
+    },
+    async ({ action, client_id, client_secret, code }) => {
+      if (action === "status") {
+        const method = getAuthMethod();
+        if (method === "none") {
+          return {
+            content: [
+              {
+                type: "text",
+                text: [
+                  "=== Pagesight Auth Status ===",
+                  "",
+                  "Status: NOT CONFIGURED",
+                  "",
+                  "To use Pagesight, configure one of:",
+                  "",
+                  "Option 1: OAuth 2.0 (recommended for personal use)",
+                  "  1. Create a Google Cloud project",
+                  "  2. Enable 'Google Search Console API'",
+                  "  3. Create OAuth 2.0 credentials (Desktop app)",
+                  "  4. Call: setup(action='get_auth_url', client_id='YOUR_ID')",
+                  "  5. Visit the URL, authorize, copy the code",
+                  "  6. Call: setup(action='exchange_code', client_id='YOUR_ID', client_secret='YOUR_SECRET', code='THE_CODE')",
+                  "  7. Set env vars: GSC_CLIENT_ID, GSC_CLIENT_SECRET, GSC_REFRESH_TOKEN",
+                  "",
+                  "Option 2: Service Account",
+                  "  1. Create a service account in Google Cloud",
+                  "  2. Download the JSON key file",
+                  "  3. Add the service account email as a user in Search Console",
+                  "  4. Set env var: GSC_SERVICE_ACCOUNT_KEY=/path/to/key.json",
+                ].join("\n"),
+              },
+            ],
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `=== Pagesight Auth Status ===\n\nStatus: CONFIGURED\nMethod: ${method}`,
+            },
+          ],
+        };
+      }
+
+      if (action === "get_auth_url") {
+        if (!client_id) {
+          return { content: [{ type: "text", text: "Error: client_id is required for get_auth_url." }] };
+        }
+        const url = getOAuthSetupUrl(client_id);
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                "=== OAuth Setup ===",
+                "",
+                "1. Open this URL in your browser:",
+                "",
+                url,
+                "",
+                "2. Sign in and authorize access to Search Console",
+                "3. Copy the authorization code",
+                "4. Call: setup(action='exchange_code', client_id='...', client_secret='...', code='THE_CODE')",
+              ].join("\n"),
+            },
+          ],
+        };
+      }
+
+      if (action === "exchange_code") {
+        if (!client_id || !client_secret || !code) {
+          return { content: [{ type: "text", text: "Error: client_id, client_secret, and code are all required." }] };
+        }
+        const tokens = await exchangeCodeForToken(client_id, client_secret, code);
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                "=== OAuth Setup Complete ===",
+                "",
+                "Add these environment variables to your MCP server config:",
+                "",
+                `GSC_CLIENT_ID=${client_id}`,
+                `GSC_CLIENT_SECRET=${client_secret}`,
+                `GSC_REFRESH_TOKEN=${tokens.refreshToken}`,
+                "",
+                "Then restart Pagesight.",
+              ].join("\n"),
+            },
+          ],
+        };
+      }
+
+      return { content: [{ type: "text", text: "Unknown action." }] };
+    },
+  );
+}