pagesight 0.1.0

package/lefthook.yml

@@ -0,0 +1,8 @@
+pre-commit:
+  parallel: true
+  jobs:
+    - name: biome
+      glob: "*.{ts,tsx}"
+      run: bunx biome check --write {staged_files} && git add {staged_files}
+    - name: typecheck
+      run: bunx tsc --noEmit

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "pagesight",
+  "version": "0.1.0",
+  "description": "Google's data + AI crawler intelligence for AI assistants. MCP server for SEO, GEO, and web performance.",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "pagesight": "src/index.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caiopizzol/sitelint.git"
+  },
+  "homepage": "https://github.com/caiopizzol/sitelint",
+  "author": "Caio Pizzol",
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "test": "bun test",
+    "lint": "biome check src/",
+    "format": "biome format --write src/"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/bun": "^1.3.11",
+    "lefthook": "^2.1.4",
+    "semantic-release": "^25.0.3",
+    "semantic-release-ai-notes": "^0.2.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+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 { registerPagespeedTool } from "./tools/pagespeed.js";
+import { registerPerformanceTool } from "./tools/performance.js";
+import { registerRobotsTool } from "./tools/robots.js";
+import { registerSetupTool } from "./tools/setup.js";
+import { registerSitemapsTool } from "./tools/sitemaps.js";
+
+const server = new McpServer({
+  name: "pagesight",
+  version: "0.0.0",
+});
+
+registerCruxTool(server);
+registerInspectTool(server);
+registerPagespeedTool(server);
+registerPerformanceTool(server);
+registerRobotsTool(server);
+registerSitemapsTool(server);
+registerSetupTool(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/lib/auth.ts

@@ -0,0 +1,176 @@
+import { existsSync } from "node:fs";
+
+const SCOPES = ["https://www.googleapis.com/auth/webmasters.readonly"];
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+interface TokenResponse {
+  access_token: string;
+  expires_in: number;
+  token_type: string;
+}
+
+let cachedToken: { token: string; expiresAt: number } | null = null;
+
+// --- Service Account Auth ---
+
+async function getServiceAccountToken(keyPath: string): Promise<string> {
+  const keyFile = JSON.parse(await Bun.file(keyPath).text());
+  const now = Math.floor(Date.now() / 1000);
+
+  const header = btoa(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const payload = btoa(
+    JSON.stringify({
+      iss: keyFile.client_email,
+      scope: SCOPES.join(" "),
+      aud: TOKEN_URL,
+      iat: now,
+      exp: now + 3600,
+    }),
+  );
+
+  const signingInput = `${header}.${payload}`;
+  const key = await crypto.subtle.importKey(
+    "pkcs8",
+    pemToBuffer(keyFile.private_key),
+    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, new TextEncoder().encode(signingInput));
+  const jwt = `${signingInput}.${bufferToBase64Url(signature)}`;
+
+  const res = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=${jwt}`,
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Service account token exchange failed: ${err}`);
+  }
+
+  const data: TokenResponse = await res.json();
+  return data.access_token;
+}
+
+function pemToBuffer(pem: string): ArrayBuffer {
+  const b64 = pem
+    .replace(/-----BEGIN PRIVATE KEY-----/g, "")
+    .replace(/-----END PRIVATE KEY-----/g, "")
+    .replace(/\s/g, "");
+  const binary = atob(b64);
+  const buf = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) buf[i] = binary.charCodeAt(i);
+  return buf.buffer;
+}
+
+function bufferToBase64Url(buf: ArrayBuffer): string {
+  const bytes = new Uint8Array(buf);
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// --- OAuth Refresh Token Auth ---
+
+async function getOAuthToken(clientId: string, clientSecret: string, refreshToken: string): Promise<string> {
+  const res = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: clientId,
+      client_secret: clientSecret,
+      refresh_token: refreshToken,
+    }).toString(),
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`OAuth token refresh failed: ${err}`);
+  }
+
+  const data: TokenResponse = await res.json();
+  return data.access_token;
+}
+
+// --- Public API ---
+
+export async function getAccessToken(): Promise<string> {
+  // Return cached token if still valid
+  if (cachedToken && Date.now() < cachedToken.expiresAt) {
+    return cachedToken.token;
+  }
+
+  // Try service account first
+  const saKeyPath = process.env.GSC_SERVICE_ACCOUNT_KEY;
+  if (saKeyPath && existsSync(saKeyPath)) {
+    const token = await getServiceAccountToken(saKeyPath);
+    cachedToken = { token, expiresAt: Date.now() + 3500_000 }; // ~58 min
+    return token;
+  }
+
+  // Try OAuth refresh token
+  const clientId = process.env.GSC_CLIENT_ID;
+  const clientSecret = process.env.GSC_CLIENT_SECRET;
+  const refreshToken = process.env.GSC_REFRESH_TOKEN;
+
+  if (clientId && clientSecret && refreshToken) {
+    const token = await getOAuthToken(clientId, clientSecret, refreshToken);
+    cachedToken = { token, expiresAt: Date.now() + 3500_000 };
+    return token;
+  }
+
+  throw new Error(
+    "No GSC credentials configured. Set either:\n" +
+      "  - GSC_SERVICE_ACCOUNT_KEY (path to service account JSON)\n" +
+      "  - GSC_CLIENT_ID + GSC_CLIENT_SECRET + GSC_REFRESH_TOKEN (OAuth 2.0)",
+  );
+}
+
+export function getAuthMethod(): string {
+  if (process.env.GSC_SERVICE_ACCOUNT_KEY) return "service_account";
+  if (process.env.GSC_REFRESH_TOKEN) return "oauth";
+  return "none";
+}
+
+// --- OAuth Setup Helper ---
+
+export function getOAuthSetupUrl(clientId: string): string {
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: "urn:ietf:wg:oauth:2.0:oob",
+    response_type: "code",
+    scope: SCOPES.join(" "),
+    access_type: "offline",
+    prompt: "consent",
+  });
+  return `https://accounts.google.com/o/oauth2/auth?${params}`;
+}
+
+export async function exchangeCodeForToken(
+  clientId: string,
+  clientSecret: string,
+  code: string,
+): Promise<{ refreshToken: string; accessToken: string }> {
+  const res = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: clientId,
+      client_secret: clientSecret,
+      code,
+      redirect_uri: "urn:ietf:wg:oauth:2.0:oob",
+    }).toString(),
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Code exchange failed: ${err}`);
+  }
+
+  const data = (await res.json()) as Record<string, string>;
+  return { refreshToken: data.refresh_token, accessToken: data.access_token };
+}

package/src/lib/crux.ts

@@ -0,0 +1,131 @@
+const CRUX_API = "https://chromeuxreport.googleapis.com/v1/records";
+
+function getApiKey(): string {
+  const key = process.env.GOOGLE_API_KEY;
+  if (!key) throw new Error("GOOGLE_API_KEY is required for CrUX API.");
+  return key;
+}
+
+export type CruxFormFactor = "DESKTOP" | "PHONE" | "TABLET";
+
+export type CruxMetric =
+  | "cumulative_layout_shift"
+  | "first_contentful_paint"
+  | "interaction_to_next_paint"
+  | "largest_contentful_paint"
+  | "experimental_time_to_first_byte"
+  | "round_trip_time"
+  | "navigation_types"
+  | "form_factors";
+
+export interface CruxHistogramBin {
+  start: number | string;
+  end?: number | string;
+  density: number;
+}
+
+export interface CruxMetricData {
+  histogram?: CruxHistogramBin[];
+  percentiles?: { p75: number | string };
+  fractions?: Record<string, number>;
+}
+
+export interface CruxRecord {
+  key: { formFactor?: string; origin?: string; url?: string };
+  metrics: Record<string, CruxMetricData>;
+  collectionPeriod: {
+    firstDate: { year: number; month: number; day: number };
+    lastDate: { year: number; month: number; day: number };
+  };
+}
+
+export interface CruxResponse {
+  record: CruxRecord;
+  urlNormalizationDetails?: { originalUrl: string; normalizedUrl: string };
+}
+
+export interface CruxHistoryMetricData {
+  histogramTimeseries?: Array<{
+    start: number | string;
+    end?: number | string;
+    densities: Array<number | null>;
+  }>;
+  percentilesTimeseries?: { p75s: Array<number | string | null> };
+  fractionTimeseries?: Record<string, { fractions: Array<number | null> }>;
+}
+
+export interface CruxHistoryRecord {
+  key: { formFactor?: string; origin?: string; url?: string };
+  metrics: Record<string, CruxHistoryMetricData>;
+  collectionPeriods: Array<{
+    firstDate: { year: number; month: number; day: number };
+    lastDate: { year: number; month: number; day: number };
+  }>;
+}
+
+export interface CruxHistoryResponse {
+  record: CruxHistoryRecord;
+  urlNormalizationDetails?: { originalUrl: string; normalizedUrl: string };
+}
+
+// --- CrUX Daily API ---
+
+export async function queryCrux(options: {
+  url?: string;
+  origin?: string;
+  formFactor?: CruxFormFactor;
+  metrics?: string[];
+}): Promise<CruxResponse> {
+  const key = getApiKey();
+
+  const body: Record<string, unknown> = {};
+  if (options.url) body.url = options.url;
+  if (options.origin) body.origin = options.origin;
+  if (options.formFactor) body.formFactor = options.formFactor;
+  if (options.metrics) body.metrics = options.metrics;
+
+  const res = await fetch(`${CRUX_API}:queryRecord?key=${key}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`CrUX API error (${res.status}): ${err}`);
+  }
+
+  return res.json() as Promise<CruxResponse>;
+}
+
+// --- CrUX History API ---
+
+export async function queryCruxHistory(options: {
+  url?: string;
+  origin?: string;
+  formFactor?: CruxFormFactor;
+  metrics?: string[];
+  collectionPeriodCount?: number;
+}): Promise<CruxHistoryResponse> {
+  const key = getApiKey();
+
+  const body: Record<string, unknown> = {};
+  if (options.url) body.url = options.url;
+  if (options.origin) body.origin = options.origin;
+  if (options.formFactor) body.formFactor = options.formFactor;
+  if (options.metrics) body.metrics = options.metrics;
+  if (options.collectionPeriodCount) body.collectionPeriodCount = options.collectionPeriodCount;
+
+  const res = await fetch(`${CRUX_API}:queryHistoryRecord?key=${key}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`CrUX History API error (${res.status}): ${err}`);
+  }
+
+  return res.json() as Promise<CruxHistoryResponse>;
+}

package/src/lib/gsc.ts

@@ -0,0 +1,173 @@
+import { getAccessToken } from "./auth.js";
+
+const GSC_API = "https://searchconsole.googleapis.com/v1";
+const WEBMASTERS_API = "https://www.googleapis.com/webmasters/v3";
+
+async function gscFetch(url: string, body?: unknown): Promise<Record<string, unknown>> {
+  const token = await getAccessToken();
+  const res = await fetch(url, {
+    method: body ? "POST" : "GET",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`GSC API error (${res.status}): ${err}`);
+  }
+
+  return res.json();
+}
+
+// --- URL Inspection ---
+
+export interface InspectionResult {
+  inspectionResultLink: string;
+  indexStatusResult: {
+    verdict: string;
+    coverageState: string;
+    robotsTxtState: string;
+    indexingState: string;
+    lastCrawlTime?: string;
+    pageFetchState: string;
+    googleCanonical?: string;
+    userCanonical?: string;
+    sitemap?: string[];
+    referringUrls?: string[];
+    crawledAs: string;
+  };
+  richResultsResult?: {
+    verdict: string;
+    detectedItems: Array<{
+      richResultType: string;
+      items: Array<{
+        name?: string;
+        issues: Array<{ issueMessage: string; severity: string }>;
+      }>;
+    }>;
+  };
+  mobileUsabilityResult?: {
+    verdict: string;
+    issues?: Array<{ issueType: string; message?: string }>;
+  };
+}
+
+export async function inspectUrl(inspectionUrl: string, siteUrl: string): Promise<InspectionResult> {
+  const data = await gscFetch(`${GSC_API}/urlInspection/index:inspect`, {
+    inspectionUrl,
+    siteUrl,
+  });
+  return data.inspectionResult as InspectionResult;
+}
+
+// --- Search Analytics ---
+
+export interface SearchAnalyticsRow {
+  keys: string[];
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+
+export interface SearchAnalyticsMetadata {
+  first_incomplete_date?: string;
+  first_incomplete_hour?: string;
+}
+
+export interface SearchAnalyticsResponse {
+  rows: SearchAnalyticsRow[];
+  responseAggregationType: string;
+  metadata?: SearchAnalyticsMetadata;
+}
+
+export interface SearchAnalyticsFilter {
+  dimension: string;
+  operator: string;
+  expression: string;
+}
+
+export interface SearchAnalyticsOptions {
+  startDate: string;
+  endDate: string;
+  dimensions?: string[];
+  type?: string;
+  rowLimit?: number;
+  startRow?: number;
+  dimensionFilterGroups?: Array<{ groupType?: string; filters: SearchAnalyticsFilter[] }>;
+  dataState?: string;
+  aggregationType?: string;
+}
+
+export async function querySearchAnalytics(
+  siteUrl: string,
+  options: SearchAnalyticsOptions,
+): Promise<SearchAnalyticsResponse> {
+  const body: Record<string, unknown> = {
+    startDate: options.startDate,
+    endDate: options.endDate,
+    dimensions: options.dimensions ?? ["query", "page"],
+    type: options.type ?? "web",
+    rowLimit: options.rowLimit ?? 1000,
+    dataState: options.dataState ?? "all",
+  };
+
+  if (options.startRow !== undefined) body.startRow = options.startRow;
+  if (options.aggregationType) body.aggregationType = options.aggregationType;
+  if (options.dimensionFilterGroups) body.dimensionFilterGroups = options.dimensionFilterGroups;
+
+  const data = await gscFetch(`${WEBMASTERS_API}/sites/${encodeURIComponent(siteUrl)}/searchAnalytics/query`, body);
+  return data as unknown as SearchAnalyticsResponse;
+}
+
+// --- Sites ---
+
+export interface GscSite {
+  siteUrl: string;
+  permissionLevel: string;
+}
+
+export async function listSites(): Promise<GscSite[]> {
+  const data = await gscFetch(`${WEBMASTERS_API}/sites`);
+  return (data.siteEntry as GscSite[] | undefined) ?? [];
+}
+
+export async function getSite(siteUrl: string): Promise<GscSite> {
+  const data = await gscFetch(`${WEBMASTERS_API}/sites/${encodeURIComponent(siteUrl)}`);
+  return data as unknown as GscSite;
+}
+
+// --- Sitemaps ---
+
+export interface GscSitemapContent {
+  type: string;
+  submitted?: string;
+  indexed?: string;
+}
+
+export interface GscSitemap {
+  path: string;
+  lastSubmitted?: string;
+  isPending: boolean;
+  isSitemapsIndex: boolean;
+  type?: string;
+  lastDownloaded?: string;
+  warnings?: string;
+  errors?: string;
+  contents?: GscSitemapContent[];
+}
+
+export async function listSitemaps(siteUrl: string): Promise<GscSitemap[]> {
+  const data = await gscFetch(`${WEBMASTERS_API}/sites/${encodeURIComponent(siteUrl)}/sitemaps`);
+  return (data.sitemap as GscSitemap[] | undefined) ?? [];
+}
+
+export async function getSitemap(siteUrl: string, feedpath: string): Promise<GscSitemap> {
+  const data = await gscFetch(
+    `${WEBMASTERS_API}/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`,
+  );
+  return data as unknown as GscSitemap;
+}

package/src/lib/psi.ts

@@ -0,0 +1,90 @@
+const PSI_API = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed";
+
+export interface PsiCategory {
+  id: string;
+  title: string;
+  score: number | null;
+}
+
+export interface PsiAudit {
+  id: string;
+  title: string;
+  description: string;
+  score: number | null;
+  scoreDisplayMode: string;
+  displayValue?: string;
+  numericValue?: number;
+  numericUnit?: string;
+}
+
+export interface PsiMetric {
+  percentile: number;
+  distributions: Array<{ min: number; max?: number; proportion: number }>;
+  category: string;
+}
+
+export interface PsiLoadingExperience {
+  id: string;
+  metrics: Record<string, PsiMetric>;
+  overall_category: string;
+}
+
+export interface PsiResult {
+  id: string;
+  loadingExperience?: PsiLoadingExperience;
+  originLoadingExperience?: PsiLoadingExperience;
+  lighthouseResult: {
+    requestedUrl: string;
+    finalUrl: string;
+    lighthouseVersion: string;
+    fetchTime: string;
+    audits: Record<string, PsiAudit>;
+    categories: Record<string, PsiCategory>;
+    timing: { total: number };
+    runtimeError?: { code: string; message: string };
+    runWarnings?: string[];
+    configSettings: {
+      emulatedFormFactor: string;
+      locale: string;
+    };
+  };
+  analysisUTCTimestamp: string;
+}
+
+export type PsiStrategy = "mobile" | "desktop";
+export type PsiCategoryType = "performance" | "accessibility" | "best-practices" | "seo";
+
+export async function runPagespeed(
+  url: string,
+  options?: {
+    strategy?: PsiStrategy;
+    categories?: PsiCategoryType[];
+    locale?: string;
+  },
+): Promise<PsiResult> {
+  const params = new URLSearchParams({ url });
+
+  const apiKey = process.env.GOOGLE_API_KEY;
+  if (apiKey) params.set("key", apiKey);
+
+  const strategy = options?.strategy ?? "mobile";
+  params.set("strategy", strategy);
+
+  const categories = options?.categories ?? ["performance", "accessibility", "best-practices", "seo"];
+  for (const cat of categories) {
+    params.append("category", cat);
+  }
+
+  if (options?.locale) params.set("locale", options.locale);
+
+  const res = await fetch(`${PSI_API}?${params}`, {
+    headers: { "User-Agent": "Pagesight/0.1" },
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`PageSpeed API error (${res.status}): ${err}`);
+  }
+
+  return res.json() as Promise<PsiResult>;
+}