pagesight 0.16.0 → 0.18.0

package/src/tools/search/schema.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+export const searchSchema = {
+  action: z
+    .enum(["inspect", "sample", "coverage", "sitemaps", "analytics", "gaps", "list_sites", "get_site", "get_sitemap"])
+    .optional()
+    .describe("Action to perform. Auto-detected from params when unambiguous."),
+  site_url: z.string().optional().describe("GSC property (e.g., 'sc-domain:example.com')."),
+  url: z.string().url().optional().describe("URL to inspect in Google's index."),
+  sitemap_url: z.string().url().optional().describe("Sitemap URL for sample/coverage inspection or get_sitemap."),
+  sample_size: z
+    .number()
+    .min(1)
+    .max(50)
+    .optional()
+    .describe("URLs to inspect (1-50). Default: 5 for sample, 20 for coverage."),
+  sample_strategy: z
+    .enum(["random", "first", "spread"])
+    .optional()
+    .describe("Sampling strategy. Default: 'spread' for coverage, 'random' for sample."),
+  filter: z
+    .enum([
+      "not_indexed",
+      "server_error",
+      "redirect",
+      "soft_404",
+      "blocked",
+      "duplicate",
+      "discovered",
+      "crawled_not_indexed",
+    ])
+    .optional()
+    .describe("Filter sample results by coverage issue type. Inspects more URLs internally to find matches."),
+  start_date: z.string().optional().describe("Start date (YYYY-MM-DD) for analytics. Default: 28 days ago."),
+  end_date: z.string().optional().describe("End date (YYYY-MM-DD) for analytics. Default: 3 days ago."),
+  dimensions: z
+    .array(z.enum(["query", "page", "country", "device", "date", "searchAppearance", "hour"]))
+    .optional()
+    .describe("Analytics dimensions. Default: auto."),
+  search_type: z
+    .enum(["web", "image", "video", "news", "discover", "googleNews"])
+    .optional()
+    .describe("Search type for analytics."),
+  data_state: z.enum(["all", "final", "hourly_all"]).optional().describe("Data freshness for analytics."),
+  aggregation_type: z
+    .enum(["auto", "byPage", "byProperty", "byNewsShowcasePanel"])
+    .optional()
+    .describe("Aggregation mode for analytics."),
+  filters: z
+    .array(
+      z.object({
+        dimension: z.enum(["query", "page", "country", "device", "searchAppearance"]),
+        operator: z.enum(["equals", "contains", "notEquals", "notContains", "includingRegex", "excludingRegex"]),
+        expression: z.string(),
+      }),
+    )
+    .optional()
+    .describe("Dimension filters for analytics."),
+  row_limit: z.number().optional().describe("Max rows for analytics (1-25000). Default: 1000."),
+  start_row: z.number().optional().describe("Pagination offset for analytics."),
+  compare: z.boolean().optional().describe("Compare current vs previous period for analytics."),
+};
+export type SearchOptions = z.infer<z.ZodObject<typeof searchSchema>>;

package/src/{lib/sitemap.ts → tools/search/sitemap-sampling.ts}

@@ -1,6 +1,4 @@
-import { inspectUrl } from "./gsc.js";
-
-export interface SitemapParseResult {
+interface SitemapParseResult {
   urls: string[];
   isSitemapIndex: boolean;
   childSitemaps: string[];
@@ -70,45 +68,3 @@ export function sampleUrls(urls: string[], count: number, strategy: string): str
   }
   return shuffled.slice(0, count);
 }
-
-export interface InspectionSummary {
-  url: string;
-  verdict: string;
-  coverageState: string;
-  pageFetchState: string;
-  robotsTxtState: string;
-  indexingState: string;
-  lastCrawlTime: string | null;
-  googleCanonical: string | null;
-  error: string | null;
-}
-
-export async function inspectSingle(url: string, siteUrl: string): Promise<InspectionSummary> {
-  try {
-    const r = await inspectUrl(url, siteUrl);
-    const idx = r.indexStatusResult;
-    return {
-      url,
-      verdict: idx.verdict,
-      coverageState: idx.coverageState,
-      pageFetchState: idx.pageFetchState,
-      robotsTxtState: idx.robotsTxtState,
-      indexingState: idx.indexingState,
-      lastCrawlTime: idx.lastCrawlTime ?? null,
-      googleCanonical: idx.googleCanonical ?? null,
-      error: null,
-    };
-  } catch (err) {
-    return {
-      url,
-      verdict: "ERROR",
-      coverageState: "ERROR",
-      pageFetchState: "ERROR",
-      robotsTxtState: "ERROR",
-      indexingState: "ERROR",
-      lastCrawlTime: null,
-      googleCanonical: null,
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}

package/src/tools/search/sites.ts

@@ -0,0 +1,86 @@
+import { type GscSite, type GscSitemap, getSite, getSitemap, listSitemaps, listSites } from "../../providers/gsc.js";
+import { type SearchOptions } from "./schema.js";
+import { textResult } from "./result.js";
+function formatSites(sites: GscSite[]): string {
+  if (sites.length === 0) return "No Search Console properties found.";
+
+  const lines: string[] = [`=== GSC Properties (${sites.length}) ===`, ""];
+  for (const site of sites) {
+    lines.push(`${site.siteUrl} (${site.permissionLevel})`);
+  }
+  return lines.join("\n");
+}
+
+function formatSite(site: GscSite): string {
+  return [`=== Site: ${site.siteUrl} ===`, "", `Permission: ${site.permissionLevel}`].join("\n");
+}
+
+function formatSitemapDetail(sm: GscSitemap): string {
+  const lines: string[] = [`=== Sitemap: ${sm.path} ===`, ""];
+  if (sm.type) lines.push(`Type: ${sm.type}`);
+  if (sm.lastSubmitted) lines.push(`Submitted: ${sm.lastSubmitted}`);
+  if (sm.lastDownloaded) lines.push(`Downloaded: ${sm.lastDownloaded}`);
+  lines.push(`Pending: ${sm.isPending}`);
+  lines.push(`Index: ${sm.isSitemapsIndex}`);
+  if (sm.warnings) lines.push(`Warnings: ${sm.warnings}`);
+  if (sm.errors) lines.push(`Errors: ${sm.errors}`);
+  if (sm.contents && sm.contents.length > 0) {
+    lines.push("", "Contents:");
+    for (const c of sm.contents) {
+      lines.push(`  ${c.type}: ${c.submitted ?? "?"} submitted; indexed count unavailable (deprecated API field)`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function formatSitemaps(siteUrl: string, sitemaps: GscSitemap[]): string {
+  if (sitemaps.length === 0) return `No sitemaps found for ${siteUrl}.`;
+
+  const lines: string[] = [`=== Sitemaps: ${siteUrl} (${sitemaps.length}) ===`, ""];
+
+  for (const sm of sitemaps) {
+    lines.push(`${sm.path}`);
+    if (sm.type) lines.push(`  Type: ${sm.type}`);
+    if (sm.lastSubmitted) lines.push(`  Submitted: ${sm.lastSubmitted}`);
+    if (sm.lastDownloaded) lines.push(`  Downloaded: ${sm.lastDownloaded}`);
+    lines.push(`  Pending: ${sm.isPending}`);
+    lines.push(`  Index: ${sm.isSitemapsIndex}`);
+    if (sm.warnings) lines.push(`  Warnings: ${sm.warnings}`);
+    if (sm.errors) lines.push(`  Errors: ${sm.errors}`);
+    if (sm.contents) {
+      for (const c of sm.contents) {
+        lines.push(`  ${c.type}: ${c.submitted ?? "?"} submitted; indexed count unavailable (deprecated API field)`);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd();
+}
+
+export async function runListSites() {
+  const sites = await listSites();
+  return textResult(formatSites(sites));
+}
+
+export async function runGetSite(options: SearchOptions) {
+  const { site_url } = options;
+  if (!site_url) return textResult("Error: site_url is required for get_site.");
+  const site = await getSite(site_url);
+  return textResult(formatSite(site));
+}
+
+export async function runGetSitemap(options: SearchOptions) {
+  const { site_url, sitemap_url } = options;
+  if (!site_url) return textResult("Error: site_url is required for get_sitemap.");
+  if (!sitemap_url) return textResult("Error: sitemap_url is required for get_sitemap.");
+  const sm = await getSitemap(site_url, sitemap_url);
+  return textResult(formatSitemapDetail(sm));
+}
+
+export async function runSitemaps(options: SearchOptions) {
+  const { site_url } = options;
+  if (!site_url) return textResult("Error: site_url is required for sitemaps.");
+  const sitemaps = await listSitemaps(site_url);
+  return textResult(formatSitemaps(site_url, sitemaps));
+}

package/src/tools/search/tool.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { searchSchema } from "./schema.js";
+import { runSearch } from "./actions.js";
+export function registerSearchTool(server: McpServer): void {
+  server.tool(
+    "search",
+    "Query Google Search Console. Inspect URL indexing, get coverage breakdown by issue type, sample-inspect with filters, list properties and sitemaps, analyze search traffic, or find keyword gaps.",
+    searchSchema,
+    runSearch,
+  );
+}

package/src/tools/setup.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { exchangeCodeForToken, getAuthMethod, getOAuthSetupUrl } from "../lib/auth.js";
+import { exchangeCodeForToken, getAuthMethod, getOAuthSetupUrl } from "../providers/gsc-auth.js";
 
 export function registerSetupTool(server: McpServer): void {
   server.tool(
@@ -17,7 +17,33 @@ export function registerSetupTool(server: McpServer): void {
     async ({ action, client_id, client_secret, code }) => {
       if (action === "status") {
         const method = getAuthMethod();
-        if (method === "none") {
+        if (method !== "none") {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `=== Pagesight Auth Status ===\n\nStatus: CONFIGURED\nMethod: ${method}`,
+              },
+            ],
+          };
+        }
+
+        // Check for partial OAuth config
+        const hasClientId = !!process.env.GSC_CLIENT_ID;
+        const hasClientSecret = !!process.env.GSC_CLIENT_SECRET;
+        const hasPartial = hasClientId || hasClientSecret;
+
+        if (hasPartial) {
+          const present = [hasClientId && "GSC_CLIENT_ID", hasClientSecret && "GSC_CLIENT_SECRET"]
+            .filter(Boolean)
+            .join(", ");
+          const missing = [
+            !hasClientId && "GSC_CLIENT_ID",
+            !hasClientSecret && "GSC_CLIENT_SECRET",
+            "GSC_REFRESH_TOKEN",
+          ]
+            .filter(Boolean)
+            .join(", ");
           return {
             content: [
               {
@@ -25,34 +51,47 @@ export function registerSetupTool(server: McpServer): void {
                 text: [
                   "=== Pagesight Auth Status ===",
                   "",
-                  "Status: NOT CONFIGURED",
+                  "Status: PARTIAL",
+                  `  Present: ${present}`,
+                  `  Missing: ${missing}`,
                   "",
-                  "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",
+                  "Complete OAuth setup:",
+                  "  1. Call: setup(action='get_auth_url', client_id='YOUR_ID')",
+                  "  2. Visit the URL, authorize, copy the code",
+                  "  3. Call: setup(action='exchange_code', client_id='YOUR_ID', client_secret='YOUR_SECRET', code='THE_CODE')",
+                  "  4. Set GSC_REFRESH_TOKEN from the response",
                 ].join("\n"),
               },
             ],
           };
         }
+
         return {
           content: [
             {
               type: "text",
-              text: `=== Pagesight Auth Status ===\n\nStatus: CONFIGURED\nMethod: ${method}`,
+              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"),
             },
           ],
         };

package/src/tools/speed/analyze.ts

@@ -0,0 +1,191 @@
+import type { SpeedOptions } from "./schema.js";
+import { hasApiKey, type PsiCategoryType, type PsiResult, runPagespeed } from "../../providers/pagespeed.js";
+import { type CruxFormFactor, queryCrux, queryCruxHistory } from "../../providers/crux.js";
+import { QUOTA_NOTE, formatPagespeed } from "./pagespeed.js";
+import { formatBatchCompare, formatBatchTable, runBatch } from "./batch.js";
+import { formatCrux, formatCruxHistory } from "./crux.js";
+
+export async function analyzeSpeed({
+  action,
+  url,
+  urls,
+  strategy,
+  categories,
+  locale,
+  origin,
+  form_factor,
+  metrics,
+  periods,
+}: SpeedOptions) {
+  // Determine which action to run
+  let resolvedAction = action;
+  if (!resolvedAction) {
+    if (urls) {
+      resolvedAction = "pagespeed";
+    } else if (origin && !url) {
+      resolvedAction = "crux";
+    } else if (periods) {
+      resolvedAction = "crux_history";
+    } else {
+      resolvedAction = "pagespeed";
+    }
+  }
+
+  // --- PageSpeed action ---
+  if (resolvedAction === "pagespeed") {
+    const strat = (strategy as "mobile" | "desktop") ?? "mobile";
+    const cats = categories as PsiCategoryType[] | undefined;
+    const opts = { strategy: strat, categories: cats, locale };
+
+    if (url && urls) {
+      return {
+        content: [{ type: "text" as const, text: "Error: provide either 'url' (single) or 'urls' (batch), not both." }],
+      };
+    }
+    if (!url && !urls) {
+      return {
+        content: [
+          { type: "text" as const, text: "Error: provide 'url' for single analysis or 'urls' for batch analysis." },
+        ],
+      };
+    }
+
+    // Single URL
+    if (url) {
+      try {
+        const result = await runPagespeed(url, opts);
+        const text = formatPagespeed(url, result) + (hasApiKey() ? "" : QUOTA_NOTE);
+        return { content: [{ type: "text" as const, text }] };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text" as const, text: `Error running PageSpeed analysis: ${msg}` }] };
+      }
+    }
+
+    // Batch mode
+    const batchUrls = urls as string[];
+    const results = await runBatch(batchUrls, opts);
+
+    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" as const, text: `All URLs failed:\n${errorLines.join("\n")}` }] };
+    }
+
+    let output: string;
+    if (successes.length === 2) {
+      output = formatBatchCompare(successes, strat);
+    } else {
+      output = formatBatchTable(successes, strat);
+    }
+
+    if (failures.length > 0) {
+      const errorLines = failures.map((f) => `${f.url}: ${f.error}`);
+      output += `\n\n--- Errors ---\n${errorLines.join("\n")}`;
+    }
+
+    if (!hasApiKey()) output += QUOTA_NOTE;
+
+    return { content: [{ type: "text" as const, text: output }] };
+  }
+
+  // --- CrUX action ---
+  if (resolvedAction === "crux") {
+    const cruxUrl = url;
+    const cruxOrigin = origin;
+
+    if (!cruxUrl && !cruxOrigin) {
+      return { content: [{ type: "text" as const, text: "Error: provide url or origin for CrUX data." }] };
+    }
+    if (cruxUrl && cruxOrigin) {
+      return { content: [{ type: "text" as const, text: "Error: provide url or origin, not both." }] };
+    }
+
+    try {
+      const result = await queryCrux({
+        url: cruxUrl,
+        origin: cruxOrigin,
+        formFactor: form_factor as CruxFormFactor | undefined,
+        metrics,
+      });
+      return { content: [{ type: "text" as const, text: formatCrux(cruxUrl ?? cruxOrigin ?? "", result) }] };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("404")) {
+        const target = cruxUrl ?? cruxOrigin ?? "";
+        const lines = [`No CrUX data for ${target}.`, ""];
+        lines.push("CrUX requires sufficient Chrome user traffic (roughly 1,000+ monthly visits).");
+        if (cruxUrl) {
+          const originUrl = new URL(cruxUrl).origin;
+          lines.push(`Try origin-level data instead: origin "${originUrl}"`);
+        }
+        lines.push("For lab metrics without traffic requirements, use speed with a url instead.");
+        return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+      }
+      if (msg.includes("SERVICE_DISABLED") || msg.includes("API_KEY_SERVICE_BLOCKED")) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "Chrome UX Report API is not enabled or the API key doesn't have access. Enable the API at: https://console.cloud.google.com/apis/library/chromeuxreport.googleapis.com — and ensure your API key allows it (Credentials > API key > API restrictions).",
+            },
+          ],
+        };
+      }
+      return { content: [{ type: "text" as const, text: `Error querying CrUX: ${msg}` }] };
+    }
+  }
+
+  // --- CrUX History action ---
+  if (resolvedAction === "crux_history") {
+    const histUrl = url;
+    const histOrigin = origin;
+
+    if (!histUrl && !histOrigin) {
+      return { content: [{ type: "text" as const, text: "Error: provide url or origin for CrUX history." }] };
+    }
+    if (histUrl && histOrigin) {
+      return { content: [{ type: "text" as const, text: "Error: provide url or origin, not both." }] };
+    }
+
+    try {
+      const result = await queryCruxHistory({
+        url: histUrl,
+        origin: histOrigin,
+        formFactor: form_factor as CruxFormFactor | undefined,
+        metrics,
+        collectionPeriodCount: periods,
+      });
+      return { content: [{ type: "text" as const, text: formatCruxHistory(histUrl ?? histOrigin ?? "", result) }] };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("404")) {
+        const target = histUrl ?? histOrigin ?? "";
+        const lines = [`No CrUX history data for ${target}.`, ""];
+        lines.push("CrUX requires sufficient Chrome user traffic (roughly 1,000+ monthly visits).");
+        if (histUrl) {
+          const originUrl = new URL(histUrl).origin;
+          lines.push(`Try origin-level data instead: origin "${originUrl}"`);
+        }
+        lines.push("For lab metrics without traffic requirements, use speed with a url instead.");
+        return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+      }
+      if (msg.includes("SERVICE_DISABLED")) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: "Chrome UX Report API is not enabled. Enable it at: https://console.cloud.google.com/apis/library/chromeuxreport.googleapis.com",
+            },
+          ],
+        };
+      }
+      return { content: [{ type: "text" as const, text: `Error querying CrUX History: ${msg}` }] };
+    }
+  }
+
+  const unhandled: never = resolvedAction;
+  return { content: [{ type: "text" as const, text: `Unknown action: ${String(unhandled)}` }] };
+}