pagesight 0.17.0 → 0.19.0

package/src/providers/gsc-auth.ts

@@ -0,0 +1,93 @@
+import { getOAuthToken, getServiceAccountToken, TOKEN_URL } from "./google-tokens.js";
+import { existsSync } from "node:fs";
+import { RequestError } from "../shared/http.js";
+
+const SCOPES = ["https://www.googleapis.com/auth/webmasters.readonly"];
+let cachedToken: { token: string; expiresAt: number } | null = null;
+
+// --- Service Account Auth ---
+
+// --- Public API ---
+
+export async function getAccessToken(): Promise<string> {
+  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, SCOPES.join(" "));
+    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 RequestError(
+    "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)",
+    null,
+    "not_configured",
+  );
+}
+
+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";
+  return "none";
+}
+
+// --- OAuth Setup Helper ---
+
+export function getOAuthSetupUrl(clientId: string): string {
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: "http://localhost",
+    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: "http://localhost",
+    }).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 → providers}/gsc.ts

@@ -1,30 +1,20 @@
-import { clearTokenCache, getAccessToken } from "./auth.js";
+import { clearTokenCache, getAccessToken } from "./gsc-auth.js";
+import { RequestError, requestJson } from "../shared/http.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) {
-    // 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}`);
-  }
-
   try {
-    return (await res.json()) as Record<string, unknown>;
-  } catch {
-    throw new Error(`GSC API returned invalid JSON (${res.status})`);
+    return await requestJson<Record<string, unknown>>(url, {
+      method: body ? "POST" : "GET",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (error) {
+    if (error instanceof RequestError && error.status === 401) clearTokenCache();
+    throw error;
   }
 }
 
@@ -62,6 +52,11 @@ export interface InspectionResult {
 }
 
 export async function inspectUrl(inspectionUrl: string, siteUrl: string): Promise<InspectionResult> {
+  const data = await inspectUrlResponse(inspectionUrl, siteUrl);
+  return data.inspectionResult as InspectionResult;
+}
+
+export async function inspectUrlResponse(inspectionUrl: string, siteUrl: string): Promise<Record<string, unknown>> {
   const data = await gscFetch(`${GSC_API}/urlInspection/index:inspect`, {
     inspectionUrl,
     siteUrl,
@@ -69,7 +64,7 @@ export async function inspectUrl(inspectionUrl: string, siteUrl: string): Promis
   if (!data.inspectionResult) {
     throw new Error("GSC API returned no inspection result");
   }
-  return data.inspectionResult as InspectionResult;
+  return data;
 }
 
 // --- Search Analytics ---
@@ -121,7 +116,7 @@ export async function querySearchAnalytics(
     dimensions: options.dimensions ?? ["query", "page"],
     type: options.type ?? "web",
     rowLimit: options.rowLimit ?? 1000,
-    dataState: options.dataState ?? "all",
+    dataState: options.dataState ?? "final",
   };
 
   if (options.startRow !== undefined) body.startRow = options.startRow;
@@ -140,10 +135,14 @@ export interface GscSite {
 }
 
 export async function listSites(): Promise<GscSite[]> {
-  const data = await gscFetch(`${WEBMASTERS_API}/sites`);
+  const data = await listSitesResponse();
   return (data.siteEntry as GscSite[] | undefined) ?? [];
 }
 
+export function listSitesResponse(): Promise<Record<string, unknown>> {
+  return gscFetch(`${WEBMASTERS_API}/sites`);
+}
+
 export async function getSite(siteUrl: string): Promise<GscSite> {
   const data = await gscFetch(`${WEBMASTERS_API}/sites/${encodeURIComponent(siteUrl)}`);
   return data as unknown as GscSite;
@@ -170,10 +169,14 @@ export interface GscSitemap {
 }
 
 export async function listSitemaps(siteUrl: string): Promise<GscSitemap[]> {
-  const data = await gscFetch(`${WEBMASTERS_API}/sites/${encodeURIComponent(siteUrl)}/sitemaps`);
+  const data = await listSitemapsResponse(siteUrl);
   return (data.sitemap as GscSitemap[] | undefined) ?? [];
 }
 
+export function listSitemapsResponse(siteUrl: string): Promise<Record<string, unknown>> {
+  return gscFetch(`${WEBMASTERS_API}/sites/${encodeURIComponent(siteUrl)}/sitemaps`);
+}
+
 export async function getSitemap(siteUrl: string, feedpath: string): Promise<GscSitemap> {
   const data = await gscFetch(
     `${WEBMASTERS_API}/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`,

package/src/{lib/psi.ts → providers/pagespeed.ts}

@@ -1,3 +1,5 @@
+import { requestJson } from "../shared/http.js";
+
 const PSI_API = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed";
 
 export interface PsiCategory {
@@ -106,18 +108,5 @@ export async function runPagespeed(
 
   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}`);
-  }
-
-  try {
-    return (await res.json()) as PsiResult;
-  } catch {
-    throw new Error(`PageSpeed API returned invalid JSON (${res.status})`);
-  }
+  return requestJson<PsiResult>(`${PSI_API}?${params}`, { headers: { "User-Agent": "Pagesight/0.17" } }, 60_000);
 }

package/src/shared/dates.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+export const dateSchema = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/)
+  .refine((value) => {
+    const date = new Date(value);
+    return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+  }, "Use a real YYYY-MM-DD date");
+
+export function pacificDate(now = new Date()): string {
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone: "America/Los_Angeles",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(now);
+}
+
+export function defaultDates(now = new Date()): { startDate: string; endDate: string } {
+  const end = new Date(`${pacificDate(now)}T12:00:00Z`);
+  end.setUTCDate(end.getUTCDate() - 3);
+  const start = new Date(end);
+  start.setUTCDate(start.getUTCDate() - 27);
+  return { startDate: start.toISOString().slice(0, 10), endDate: end.toISOString().slice(0, 10) };
+}
+
+export function pacificDaysAgo(days: number, now = new Date()): string {
+  const date = new Date(`${pacificDate(now)}T12:00:00Z`);
+  date.setUTCDate(date.getUTCDate() - days);
+  return date.toISOString().slice(0, 10);
+}

package/src/shared/http.ts

@@ -0,0 +1,63 @@
+export class RequestError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number | null = null,
+    public readonly code = "request_failed",
+  ) {
+    super(message);
+  }
+}
+
+export async function requestJson<T>(url: string, init: RequestInit = {}, timeoutMs = 30_000): Promise<T> {
+  const signal = AbortSignal.timeout(timeoutMs);
+  let response: Response;
+  try {
+    response = await fetch(url, { ...init, signal });
+  } catch {
+    throw new RequestError("Request failed or timed out", null, "network_error");
+  }
+  if (!response.ok) {
+    // Provider bodies and request URLs can contain credentials; never echo them into evidence.
+    const code =
+      response.status === 401
+        ? "unauthenticated"
+        : response.status === 403
+          ? "forbidden"
+          : response.status === 429
+            ? "quota_exceeded"
+            : response.status === 404
+              ? "not_found"
+              : "provider_error";
+    throw new RequestError(`Provider returned HTTP ${response.status}`, response.status, code);
+  }
+  try {
+    return (await response.json()) as T;
+  } catch (error) {
+    if (signal.aborted || !(error instanceof SyntaxError))
+      throw new RequestError("Response body failed or timed out", null, "network_error");
+    throw new RequestError("Provider returned invalid JSON", response.status, "invalid_response");
+  }
+}
+
+export async function readBounded(response: Response, maxBytes: number): Promise<string> {
+  if (Number(response.headers.get("content-length")) > maxBytes) {
+    await response.body?.cancel();
+    throw new RequestError("Response exceeds byte limit", null, "size_limit");
+  }
+  const reader = response.body?.getReader();
+  if (!reader) return "";
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maxBytes) throw new RequestError("Response exceeds byte limit", null, "size_limit");
+      chunks.push(value);
+    }
+  } finally {
+    await reader.cancel();
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}

package/src/tools/ai.ts

@@ -1,8 +1,7 @@
 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";
-
-// --- llms.txt detection ---
+import { readBounded, RequestError } from "../shared/http.js";
+import { auditAiCrawlers, type CrawlerStatus, fetchRobotsTxt, isAllowed, type RobotsTxt } from "../web/robots.js";
 
 interface LlmsTxtResult {
   exists: boolean;
@@ -15,32 +14,20 @@ interface LlmsTxtResult {
 
 async function checkLlmsTxt(origin: string, path: string): Promise<LlmsTxtResult> {
   try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 10_000);
     const res = await fetch(`${origin}${path}`, {
       headers: { "User-Agent": "Pagesight/1.0" },
       redirect: "follow",
-      signal: controller.signal,
+      signal: AbortSignal.timeout(10_000),
     });
-    clearTimeout(timeout);
     if (!res.ok) return { exists: false, size: null, firstLine: null, lineCount: null, sections: [], linkCount: null };
-    // Cap at 1MB to avoid OOM on large responses
-    const contentLength = Number(res.headers.get("content-length") ?? 0);
-    if (contentLength > 1_048_576) {
-      return {
-        exists: true,
-        size: contentLength,
-        firstLine: "(file too large to preview)",
-        lineCount: null,
-        sections: [],
-        linkCount: null,
-      };
-    }
-    const text = await res.text();
-    if (text.length > 1_048_576) {
+    let text: string;
+    try {
+      text = await readBounded(res, 1_048_576);
+    } catch (error) {
+      if (!(error instanceof RequestError) || error.code !== "size_limit") throw error;
       return {
         exists: true,
-        size: text.length,
+        size: null,
         firstLine: "(file too large to preview)",
         lineCount: null,
         sections: [],
@@ -51,7 +38,14 @@ async function checkLlmsTxt(origin: string, path: string): Promise<LlmsTxtResult
     const firstLine = textLines.find((l) => l.trim().length > 0)?.trim() ?? null;
     const sections = textLines.filter((l) => /^##\s/.test(l)).map((l) => l.replace(/^##\s+/, "").trim());
     const linkCount = (text.match(/\[.*?\]\(https?:\/\/[^)]+\)/g) ?? []).length;
-    return { exists: true, size: text.length, firstLine, lineCount: textLines.length, sections, linkCount };
+    return {
+      exists: true,
+      size: new TextEncoder().encode(text).byteLength,
+      firstLine,
+      lineCount: textLines.length,
+      sections,
+      linkCount,
+    };
   } catch {
     return { exists: false, size: null, firstLine: null, lineCount: null, sections: [], linkCount: null };
   }
@@ -84,9 +78,7 @@ function formatLlmsTxt(llmsTxt: LlmsTxtResult, llmsFullTxt: LlmsTxtResult): stri
   return lines;
 }
 
-// --- Category summary ---
-
-function formatCategorySummary(crawlers: CrawlerStatus[]): string[] {
+export function formatCategorySummary(crawlers: CrawlerStatus[]): string[] {
   const categoryOrder = ["Training", "Search", "Assistant", "Agent", "Other"];
   const summary = new Map<string, { blocked: number; allowed: number }>();
 
@@ -245,7 +237,7 @@ function formatRobotsAudit(origin: string, robots: RobotsTxt, statusCode: number
 export function registerAiTool(server: McpServer): void {
   server.tool(
     "ai",
-    "Analyze your site's AI visibility. Audits AI crawler access (training, search, assistant, agent) via robots.txt, checks for llms.txt and llms-full.txt, validates syntax per RFC 9309, and tests specific path access. Shows how AI systems see your site.",
+    "Analyze your site's AI visibility. Audits AI crawler access (training, search, assistant, agent) via robots.txt, checks for llms.txt and llms-full.txt, reports robots.txt parse errors, and tests specific path access. Shows how AI systems see your site.",
     {
       url: z
         .string()

package/src/tools/audit.ts

@@ -1,9 +1,9 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 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 "../lib/sitemap.js";
+import { type GscSitemap, inspectUrl, listSitemaps } from "../providers/gsc.js";
+import { RequestError } from "../shared/http.js";
+import { type PsiCategoryType, type PsiResult, runPagespeed } from "../providers/pagespeed.js";
+import { auditAiCrawlers, fetchRobotsTxt, isAllowed } from "../web/robots.js";
 
 type Severity = "HIGH" | "MEDIUM" | "LOW";
 
@@ -13,8 +13,6 @@ interface Finding {
   source: string;
 }
 
-// --- Metatags (inline, no external dep needed) ---
-
 interface MetaCheckResult {
   title: string | null;
   description: string | null;
@@ -66,7 +64,7 @@ async function checkMeta(url: string): Promise<MetaCheckResult> {
     };
   }
 
-  // Exhausted redirects
+  // The hop limit or a redirect without Location prevented a page response.
   return {
     title: null,
     description: null,
@@ -80,8 +78,6 @@ async function checkMeta(url: string): Promise<MetaCheckResult> {
   };
 }
 
-// --- Audit logic ---
-
 function addMetaFindings(meta: MetaCheckResult, findings: Finding[]) {
   if (!meta.title) findings.push({ severity: "HIGH", message: "Missing <title> tag", source: "metatags" });
   if (!meta.description) findings.push({ severity: "HIGH", message: "Missing meta description", source: "metatags" });
@@ -182,70 +178,30 @@ function addRobotsFindings(
   }
 }
 
-function addSitemapFindings(sitemapCount: number, totalSubmitted: number, totalIndexed: number, findings: Finding[]) {
-  if (sitemapCount === 0) {
+export function addSitemapFindings(sitemaps: GscSitemap[], findings: Finding[]) {
+  if (sitemaps.length === 0) {
     findings.push({ severity: "MEDIUM", message: "No sitemaps submitted to GSC", source: "sitemaps" });
-    return;
   }
-  if (totalSubmitted > 0 && totalIndexed === 0) {
-    findings.push({
-      severity: "HIGH",
-      message: `${totalSubmitted.toLocaleString()} sitemap URLs submitted, 0 indexed`,
-      source: "sitemaps",
-    });
-  } else if (totalSubmitted > 0) {
-    const pct = Math.round((totalIndexed / totalSubmitted) * 100);
-    if (pct < 50) {
+  // contents[].indexed is deprecated; sitemap submission is not indexing evidence.
+  // https://developers.google.com/webmaster-tools/v1/sitemaps
+  for (const sitemap of sitemaps) {
+    if (Number(sitemap.errors) > 0) {
       findings.push({
         severity: "HIGH",
-        message: `${totalSubmitted.toLocaleString()} sitemap URLs, only ${pct}% indexed (${totalIndexed.toLocaleString()})`,
+        message: `${sitemap.path}: ${sitemap.errors} sitemap errors`,
         source: "sitemaps",
       });
-    } else if (pct < 80) {
+    }
+    if (Number(sitemap.warnings) > 0) {
       findings.push({
         severity: "MEDIUM",
-        message: `${totalSubmitted.toLocaleString()} sitemap URLs, ${pct}% indexed (${totalIndexed.toLocaleString()})`,
+        message: `${sitemap.path}: ${sitemap.warnings} sitemap warnings`,
         source: "sitemaps",
       });
     }
   }
 }
 
-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") {
-      let path: string;
-      try {
-        path = new URL(r.url).pathname;
-      } catch {
-        path = r.url;
-      }
-      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" });
@@ -266,7 +222,6 @@ function formatAudit(url: string, findings: Finding[], errors: string[]): string
     lines.push("");
   }
 
-  // Sort: HIGH first, then MEDIUM, then LOW
   const order: Record<string, number> = { HIGH: 0, MEDIUM: 1, LOW: 2 };
   findings.sort((a, b) => order[a.severity] - order[b.severity]);
 
@@ -299,7 +254,6 @@ export function registerAuditTool(server: McpServer): void {
       const errors: string[] = [];
       const origin = new URL(url).origin;
 
-      // Run independent checks in parallel
       const [metaResult, pagespeedResult, robotsResult, sitemapResult, inspectResult] = await Promise.allSettled([
         checkMeta(url),
         runPagespeed(url, {
@@ -312,7 +266,7 @@ export function registerAuditTool(server: McpServer): void {
           return { robotsTxt, crawlers, googlebotAllowed };
         }),
         site_url ? listSitemaps(site_url) : Promise.resolve(null),
-        site_url ? inspectUrl(url, site_url).catch(() => null) : Promise.resolve(null),
+        site_url ? inspectUrl(url, site_url) : Promise.resolve(null),
       ]);
 
       // Process meta
@@ -327,8 +281,7 @@ export function registerAuditTool(server: McpServer): void {
         addPagespeedFindings(pagespeedResult.value, findings);
       } else {
         const psiErr = String(pagespeedResult.reason);
-        const statusMatch = psiErr.match(/\((\d{3})\)/);
-        const status = statusMatch ? Number(statusMatch[1]) : 0;
+        const status = pagespeedResult.reason instanceof RequestError ? pagespeedResult.reason.status : null;
         if (status === 403) {
           errors.push("PageSpeed: SKIPPED (API key not authorized — enable PageSpeed Insights API in Google Cloud)");
         } else if (status === 429) {
@@ -349,40 +302,7 @@ export function registerAuditTool(server: McpServer): void {
 
       // Process sitemaps
       if (sitemapResult.status === "fulfilled" && sitemapResult.value) {
-        const sitemaps = sitemapResult.value;
-        let totalSubmitted = 0;
-        let totalIndexed = 0;
-        for (const sm of sitemaps) {
-          for (const c of sm.contents ?? []) {
-            totalSubmitted += Number(c.submitted ?? 0);
-            totalIndexed += Number(c.indexed ?? 0);
-          }
-        }
-        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 = await Promise.all(sampled.map((u) => 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
-          }
-        }
+        addSitemapFindings(sitemapResult.value, findings);
       } else if (sitemapResult.status === "rejected") {
         errors.push(`Sitemaps: ${sitemapResult.reason}`);
       }

package/src/tools/observe.ts

@@ -0,0 +1,28 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { execute, operationSchema } from "../api/index.js";
+import { RequestError } from "../shared/http.js";
+
+export function registerObserveTool(server: McpServer): void {
+  server.tool(
+    "observe",
+    "Run the shared Pagesight API. Read-only operations: discover; bing.sites/queries/pages/traffic/crawl-stats/crawl-issues/url-info/link-counts/url-links; evidence.import (unverified UI findings); gsc.sites/sitemaps/inspect/report; ga.accounts/property/key-events/report/realtime; page (metadata and image ALT evidence); speed.psi/crux/history; doctor; snapshot; assess (saved evidence summary); compare. Pass the API operation object as request. Returns structured evidence, exact effective requests, provider responses and partial errors. See the CLI --help and README for report/config shapes.",
+    { request: operationSchema },
+    async ({ request }) => {
+      try {
+        const result = await execute(request);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result) }],
+          structuredContent: { ...result },
+          isError: result.status === "error",
+        };
+      } catch (error) {
+        return {
+          content: [
+            { type: "text" as const, text: error instanceof RequestError ? error.message : "Invalid operation" },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+}