@getmcpads/google-search-console-mcp-server 1.0.0

package/dist/cli.js

@@ -0,0 +1,3073 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+import { z } from "zod";
+
+// src/core/logger.ts
+var LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+var currentLevel = process.env["LOG_LEVEL"] ?? "info";
+function log(level, platform, msg, data) {
+  if (LEVEL_ORDER[level] < LEVEL_ORDER[currentLevel]) return;
+  console.error(JSON.stringify({
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    ...platform && { platform },
+    msg,
+    ...data !== void 0 && { data }
+  }));
+}
+var logger = {
+  debug: (p, m, d) => log("debug", p, m, d),
+  info: (p, m, d) => log("info", p, m, d),
+  warn: (p, m, d) => log("warn", p, m, d),
+  error: (p, m, d) => log("error", p, m, d),
+  system: (m, d) => log("info", null, m, d),
+  setLevel: (l) => {
+    currentLevel = l;
+  }
+};
+
+// src/config.ts
+var configSchema = z.object({
+  clientId: z.string().optional(),
+  clientSecret: z.string().optional(),
+  refreshToken: z.string().optional(),
+  accessToken: z.string().optional(),
+  defaultSiteUrl: z.string().optional(),
+  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info")
+});
+function loadConfig() {
+  const raw = {
+    clientId: process.env["GSC_CLIENT_ID"] || void 0,
+    clientSecret: process.env["GSC_CLIENT_SECRET"] || void 0,
+    refreshToken: process.env["GSC_REFRESH_TOKEN"] || void 0,
+    accessToken: process.env["GSC_ACCESS_TOKEN"] || void 0,
+    defaultSiteUrl: process.env["GSC_SITE_URL"] || void 0,
+    logLevel: process.env["LOG_LEVEL"] ?? "info"
+  };
+  const result = configSchema.safeParse(raw);
+  if (!result.success) {
+    const missing = result.error.issues.map((issue) => issue.message).join(", ");
+    logger.error("config", `Invalid GSC config: ${missing}`);
+    throw new Error(`Invalid GSC config: ${missing}`);
+  }
+  const config = result.data;
+  const canRefresh = Boolean(config.refreshToken && config.clientId && config.clientSecret);
+  if (!config.accessToken && !canRefresh) {
+    throw new Error(
+      "Missing GSC credentials: set GSC_ACCESS_TOKEN, or set GSC_CLIENT_ID, GSC_CLIENT_SECRET, and GSC_REFRESH_TOKEN."
+    );
+  }
+  return config;
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/platforms/gsc/tools.ts
+import { z as z2 } from "zod";
+
+// src/core/errors.ts
+var PlatformApiError = class extends Error {
+  constructor(platform, code, message, isRateLimit = false, isAuth = false, isPermission = false, suggestion = "", retryAfter) {
+    super(message);
+    this.platform = platform;
+    this.code = code;
+    this.isRateLimit = isRateLimit;
+    this.isAuth = isAuth;
+    this.isPermission = isPermission;
+    this.suggestion = suggestion;
+    this.retryAfter = retryAfter;
+    this.name = "PlatformApiError";
+  }
+  platform;
+  code;
+  isRateLimit;
+  isAuth;
+  isPermission;
+  suggestion;
+  retryAfter;
+  toMcpError() {
+    return {
+      error: this.message,
+      platform: this.platform,
+      code: this.code,
+      isRateLimit: this.isRateLimit,
+      isAuth: this.isAuth,
+      isPermission: this.isPermission,
+      suggestion: this.suggestion,
+      ...this.retryAfter !== void 0 && { retryAfter: this.retryAfter }
+    };
+  }
+};
+function formatMcpToolError(error) {
+  if (error instanceof PlatformApiError) {
+    return {
+      content: [{ type: "text", text: JSON.stringify(error.toMcpError(), null, 2) }],
+      isError: true
+    };
+  }
+  const apiError = error;
+  if (typeof apiError?.code === "number" || apiError?.status) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          error: apiError.message ?? "Google Search Console API error",
+          platform: "gsc",
+          code: apiError.code,
+          status: apiError.status,
+          isAuth: Boolean(apiError.isAuthError),
+          isRateLimit: Boolean(apiError.isRateLimitError || apiError.isQuotaError),
+          suggestion: apiError.suggestion
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+  const msg = error instanceof Error ? error.message : String(error);
+  return { content: [{ type: "text", text: JSON.stringify({ error: msg }, null, 2) }], isError: true };
+}
+
+// src/core/rate-limiter.ts
+var RateLimiter = class {
+  timestamps = [];
+  async acquire() {
+    const now = Date.now();
+    this.timestamps = this.timestamps.filter((t) => now - t < 6e4);
+    const lastSecond = this.timestamps.filter((t) => now - t < 1e3);
+    if (lastSecond.length >= 10) {
+      const waitMs = 1e3 - (now - lastSecond[0]) + 50;
+      logger.debug("gsc", `Rate limit wait: ${waitMs}ms`);
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+    if (this.timestamps.length >= 600) {
+      const waitMs = 6e4 - (now - this.timestamps[0]) + 100;
+      logger.debug("gsc", `Minute rate limit wait: ${waitMs}ms`);
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+    this.timestamps.push(Date.now());
+  }
+  async execute(fn) {
+    for (let i = 0; i <= 3; i++) {
+      await this.acquire();
+      try {
+        return await fn();
+      } catch (error) {
+        const message = error instanceof Error ? error.message.toLowerCase() : "";
+        const code = typeof error?.code === "number" ? error.code : void 0;
+        const isRateLimit = code === 429 || message.includes("rate limit") || message.includes("quota");
+        if (isRateLimit && i < 3) {
+          const waitMs = Math.min(1e3 * Math.pow(2, i) + Math.floor(Math.random() * 500), 3e4);
+          await new Promise((resolve) => setTimeout(resolve, waitMs));
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error("Rate limiter exhausted retries");
+  }
+};
+
+// src/platforms/gsc/types.ts
+var GSCApiException = class extends Error {
+  code;
+  status;
+  constructor(message, code, status) {
+    super(message);
+    this.name = "GSCApiException";
+    this.code = code;
+    this.status = status || "UNKNOWN";
+  }
+  get isAuthError() {
+    return this.code === 401 || this.code === 403;
+  }
+  get isRateLimitError() {
+    return this.code === 429;
+  }
+  get isQuotaError() {
+    return this.code === 429 || this.status === "RESOURCE_EXHAUSTED";
+  }
+  get suggestion() {
+    if (this.isAuthError) return "Re-authenticate with Google Search Console";
+    if (this.isRateLimitError) return "Wait and retry. Rate limit exceeded";
+    if (this.isQuotaError) return "Quota exceeded. Reduce query frequency";
+    return "Check the error details for more information";
+  }
+};
+var GSC_API_BASE = "https://searchconsole.googleapis.com";
+var GSC_WEBMASTERS_API_BASE = "https://www.googleapis.com/webmasters/v3";
+var GOOGLE_OAUTH_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+var GOOGLE_OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+var GSC_OAUTH_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly";
+function resolveDatePreset(preset) {
+  const now = /* @__PURE__ */ new Date();
+  const today = now.toISOString().split("T")[0];
+  const daysAgo = (n) => {
+    const d = new Date(now);
+    d.setDate(d.getDate() - n);
+    return d.toISOString().split("T")[0];
+  };
+  switch (preset) {
+    case "today":
+      return { startDate: today, endDate: today };
+    case "yesterday":
+      return { startDate: daysAgo(1), endDate: daysAgo(1) };
+    case "last7days":
+      return { startDate: daysAgo(6), endDate: today };
+    case "last28days":
+      return { startDate: daysAgo(27), endDate: today };
+    case "last3months":
+      return { startDate: daysAgo(89), endDate: today };
+    case "last6months":
+      return { startDate: daysAgo(179), endDate: today };
+    case "last12months":
+      return { startDate: daysAgo(364), endDate: today };
+    case "last16months":
+      return { startDate: daysAgo(489), endDate: today };
+    default:
+      return { startDate: daysAgo(30), endDate: today };
+  }
+}
+function flattenSearchAnalyticsResponse(response, dimensions) {
+  if (!response.rows || response.rows.length === 0) {
+    return [];
+  }
+  return response.rows.map((row) => {
+    const flat = {};
+    if (dimensions && row.keys) {
+      for (let i = 0; i < dimensions.length; i++) {
+        flat[dimensions[i]] = row.keys[i] ?? null;
+      }
+    }
+    flat.clicks = row.clicks;
+    flat.impressions = row.impressions;
+    flat.ctr = Math.round(row.ctr * 1e4) / 100;
+    flat.position = Math.round(row.position * 100) / 100;
+    return flat;
+  });
+}
+
+// src/platforms/gsc/gscClient.ts
+function getAuthorizationUrl(clientId, redirectUri, state) {
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: "code",
+    scope: GSC_OAUTH_SCOPE,
+    access_type: "offline",
+    prompt: "consent",
+    state
+  });
+  return `${GOOGLE_OAUTH_AUTH_URL}?${params.toString()}`;
+}
+async function exchangeCodeForToken(code, clientId, clientSecret, redirectUri) {
+  const response = await fetch(GOOGLE_OAUTH_TOKEN_URL, {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded"
+    },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      client_id: clientId,
+      client_secret: clientSecret,
+      redirect_uri: redirectUri
+    })
+  });
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new GSCApiException(
+      error.error_description || error.error || "Failed to exchange code for token",
+      response.status,
+      error.error
+    );
+  }
+  return response.json();
+}
+async function refreshAccessToken(refreshToken, clientId, clientSecret) {
+  const response = await fetch(GOOGLE_OAUTH_TOKEN_URL, {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded"
+    },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: clientId,
+      client_secret: clientSecret
+    })
+  });
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new GSCApiException(
+      error.error_description || error.error || "Failed to refresh token",
+      response.status,
+      error.error
+    );
+  }
+  return response.json();
+}
+var GSCClient = class {
+  accessToken;
+  constructor(accessToken) {
+    this.accessToken = accessToken;
+  }
+  // Static methods
+  static getAuthorizationUrl = getAuthorizationUrl;
+  static exchangeCodeForToken = exchangeCodeForToken;
+  static refreshAccessToken = refreshAccessToken;
+  // ============================================
+  // PRIVATE METHODS
+  // ============================================
+  async request(url, options = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 9e4);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+        // Forced after the spread: once a bearer token is attached, a redirect
+        // must never be followed, or the credential would be forwarded to
+        // whatever host the redirect names.
+        redirect: "error",
+        headers: {
+          Authorization: `Bearer ${this.accessToken}`,
+          "Content-Type": "application/json",
+          ...options.headers
+        }
+      });
+      if (!response.ok) {
+        const errorBody = await response.json().catch(() => ({}));
+        const errorDetails = errorBody?.error;
+        console.error("[GSCClient] API Error:", response.status, JSON.stringify(errorBody, null, 2));
+        const detailedMessage = errorDetails?.message || `Request failed: ${response.statusText}`;
+        throw new GSCApiException(
+          detailedMessage,
+          response.status,
+          errorDetails?.status
+        );
+      }
+      return response.json();
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new GSCApiException(
+          "GSC API request timed out after 90 seconds",
+          408,
+          "TIMEOUT"
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  // ============================================
+  // SITE MANAGEMENT
+  // ============================================
+  /**
+   * List all verified sites accessible to the authenticated user
+   * GET https://www.googleapis.com/webmasters/v3/sites
+   */
+  async listSites() {
+    const response = await this.request(
+      `${GSC_WEBMASTERS_API_BASE}/sites`
+    );
+    return (response.siteEntry || []).map((entry) => ({
+      siteUrl: entry.siteUrl,
+      permissionLevel: entry.permissionLevel
+    }));
+  }
+  /** Get a single Search Console property and its permission level. */
+  async getSite(siteUrl) {
+    const encodedSiteUrl = encodeURIComponent(siteUrl);
+    const entry = await this.request(
+      `${GSC_WEBMASTERS_API_BASE}/sites/${encodedSiteUrl}`
+    );
+    return {
+      siteUrl: entry.siteUrl,
+      permissionLevel: entry.permissionLevel
+    };
+  }
+  // ============================================
+  // SEARCH ANALYTICS
+  // ============================================
+  /**
+   * Query search analytics data with automatic pagination
+   * POST https://searchconsole.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query
+   * Max 25,000 rows per request
+   */
+  async querySearchAnalytics(siteUrl, request) {
+    const encodedSiteUrl = encodeURIComponent(siteUrl);
+    const url = `${GSC_API_BASE}/webmasters/v3/sites/${encodedSiteUrl}/searchAnalytics/query`;
+    const MAX_ROWS_PER_REQUEST = 25e3;
+    const rowLimit = request.rowLimit ?? MAX_ROWS_PER_REQUEST;
+    const initialOffset = request.startRow ?? 0;
+    const firstResponse = await this.request(url, {
+      method: "POST",
+      body: JSON.stringify({
+        ...request,
+        rowLimit: Math.min(rowLimit, MAX_ROWS_PER_REQUEST),
+        startRow: initialOffset
+      })
+    });
+    const returnedRows = firstResponse.rows?.length ?? 0;
+    if (request.rowLimit || returnedRows < MAX_ROWS_PER_REQUEST) {
+      return firstResponse;
+    }
+    const allRows = [...firstResponse.rows ?? []];
+    let currentOffset = initialOffset + returnedRows;
+    while (true) {
+      const pageResponse = await this.request(url, {
+        method: "POST",
+        body: JSON.stringify({
+          ...request,
+          rowLimit: MAX_ROWS_PER_REQUEST,
+          startRow: currentOffset
+        })
+      });
+      const pageRows = pageResponse.rows?.length ?? 0;
+      if (pageRows === 0) break;
+      allRows.push(...pageResponse.rows ?? []);
+      currentOffset += pageRows;
+      if (pageRows < MAX_ROWS_PER_REQUEST) break;
+    }
+    return {
+      ...firstResponse,
+      rows: allRows
+    };
+  }
+  // ============================================
+  // URL INSPECTION
+  // ============================================
+  /**
+   * Inspect a URL for indexing status
+   * POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
+   * Quota: 2000 requests/day/property
+   */
+  async inspectUrl(inspectionUrl, siteUrl, languageCode) {
+    const url = `${GSC_API_BASE}/v1/urlInspection/index:inspect`;
+    const body = {
+      inspectionUrl,
+      siteUrl,
+      ...languageCode && { languageCode }
+    };
+    return this.request(url, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  // ============================================
+  // SITEMAPS
+  // ============================================
+  /**
+   * List sitemaps for a site
+   * GET https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/sitemaps
+   */
+  async listSitemaps(siteUrl, sitemapIndex) {
+    const encodedSiteUrl = encodeURIComponent(siteUrl);
+    const params = sitemapIndex ? `?sitemapIndex=${encodeURIComponent(sitemapIndex)}` : "";
+    const url = `${GSC_WEBMASTERS_API_BASE}/sites/${encodedSiteUrl}/sitemaps${params}`;
+    return this.request(url);
+  }
+  /** Get one submitted sitemap by its full feed path. */
+  async getSitemap(siteUrl, feedpath) {
+    const encodedSiteUrl = encodeURIComponent(siteUrl);
+    const encodedFeedpath = encodeURIComponent(feedpath);
+    return this.request(
+      `${GSC_WEBMASTERS_API_BASE}/sites/${encodedSiteUrl}/sitemaps/${encodedFeedpath}`
+    );
+  }
+};
+
+// src/platforms/gsc/dimensionCatalog.ts
+var GSC_DIMENSION_CATALOG = [
+  {
+    key: "query",
+    name: "Search Query",
+    description: "The search query (keyword) that triggered an impression. Not available for Discover and Google News search types.",
+    category: "query",
+    apiField: "query"
+  },
+  {
+    key: "page",
+    name: "Page URL",
+    description: "The final URL of the page that appeared in search results",
+    category: "page",
+    apiField: "page"
+  },
+  {
+    key: "country",
+    name: "Country",
+    description: "Country where the search originated. Uses ISO 3166-1 alpha-3 codes (e.g., USA, FRA, GBR, DEU, JPN)",
+    category: "geography",
+    apiField: "country"
+  },
+  {
+    key: "device",
+    name: "Device",
+    description: "Device type used for the search: DESKTOP, MOBILE, or TABLET",
+    category: "device",
+    apiField: "device"
+  },
+  {
+    key: "date",
+    name: "Date",
+    description: "Date of the search impression in YYYY-MM-DD format",
+    category: "time",
+    apiField: "date"
+  },
+  {
+    key: "hour",
+    name: "Hour",
+    description: "Hour of the search impression. Use with dataState=hourly_all; recent hourly rows can be incomplete.",
+    category: "time",
+    apiField: "hour"
+  },
+  {
+    key: "searchAppearance",
+    name: "Search Appearance",
+    description: "Special search result features: AMP_ARTICLE, INSTANT_APP, PRODUCT_LISTING, REVIEW_SNIPPET, SEARCH_ACTION, etc. One URL can have multiple appearances, inflating row count.",
+    category: "appearance",
+    apiField: "searchAppearance"
+  }
+];
+function getDimensionByKey(key) {
+  return GSC_DIMENSION_CATALOG.find((d) => d.key === key);
+}
+function validateDimensions(keys) {
+  const valid = [];
+  const invalid = [];
+  for (const key of keys) {
+    const dim = getDimensionByKey(key);
+    if (dim) {
+      valid.push(dim.key);
+    } else {
+      invalid.push(key);
+    }
+  }
+  return { valid, invalid };
+}
+
+// src/platforms/gsc/filterCatalog.ts
+var GSC_FILTER_OPERATORS = [
+  "contains",
+  "equals",
+  "notContains",
+  "notEquals",
+  "includingRegex",
+  "excludingRegex"
+];
+var GSC_FILTER_CATALOG = [
+  {
+    key: "query",
+    name: "Search Query",
+    description: "Filter by search query/keyword",
+    dimension: "query",
+    operators: GSC_FILTER_OPERATORS
+  },
+  {
+    key: "page",
+    name: "Page URL",
+    description: "Filter by page URL",
+    dimension: "page",
+    operators: GSC_FILTER_OPERATORS
+  },
+  {
+    key: "country",
+    name: "Country",
+    description: "Filter by country (ISO 3166-1 alpha-3 code, e.g., USA, FRA, GBR)",
+    dimension: "country",
+    operators: ["equals", "notEquals"]
+  },
+  {
+    key: "device",
+    name: "Device",
+    description: "Filter by device type: DESKTOP, MOBILE, TABLET",
+    dimension: "device",
+    operators: ["equals", "notEquals"]
+  },
+  {
+    key: "searchAppearance",
+    name: "Search Appearance",
+    description: "Filter by search appearance type",
+    dimension: "searchAppearance",
+    operators: ["equals", "notEquals"]
+  }
+];
+function buildFiltersFromParams(filters) {
+  return filters.filter((f) => f.field && f.operator && f.value != null).map((f) => ({
+    dimension: f.field,
+    operator: f.operator,
+    expression: String(f.value)
+  }));
+}
+
+// src/platforms/gsc/calculatedMetrics.ts
+var GSC_CALCULATED_METRIC_DEFINITIONS = [
+  {
+    key: "ctrOpportunity",
+    name: "CTR Opportunity",
+    description: "Potential CTR improvement: pages with high impressions but low CTR (positions 1-10). Score = impressions * (expectedCTR - actualCTR). Higher score = bigger opportunity.",
+    category: "calculated",
+    format: "number",
+    apiField: "",
+    type: "calculated",
+    formula: "impressions * (expectedCTR(position) - ctr)",
+    dependencies: ["impressions", "ctr", "position"]
+  },
+  {
+    key: "clicksPerImpression",
+    name: "Clicks per 1K Impressions",
+    description: "Number of clicks per 1,000 impressions. Alternative view of CTR.",
+    category: "calculated",
+    format: "number",
+    apiField: "",
+    type: "calculated",
+    formula: "(clicks / impressions) * 1000",
+    dependencies: ["clicks", "impressions"]
+  },
+  {
+    key: "impressionShare",
+    name: "Impression Share %",
+    description: "This row's share of total impressions (percentage). Useful for distribution analysis.",
+    category: "calculated",
+    format: "percent",
+    apiField: "",
+    type: "calculated",
+    formula: "(rowImpressions / totalImpressions) * 100",
+    dependencies: ["impressions"]
+  },
+  {
+    key: "clickShare",
+    name: "Click Share %",
+    description: "This row's share of total clicks (percentage). Useful for distribution analysis.",
+    category: "calculated",
+    format: "percent",
+    apiField: "",
+    type: "calculated",
+    formula: "(rowClicks / totalClicks) * 100",
+    dependencies: ["clicks"]
+  }
+];
+function expectedCTRByPosition(position) {
+  if (position <= 1) return 30;
+  if (position <= 2) return 15;
+  if (position <= 3) return 10;
+  if (position <= 4) return 7;
+  if (position <= 5) return 5;
+  if (position <= 6) return 4;
+  if (position <= 7) return 3;
+  if (position <= 8) return 2.5;
+  if (position <= 9) return 2;
+  if (position <= 10) return 1.5;
+  return 0.5;
+}
+function calcCtrOpportunity(row) {
+  const impressions = row.impressions;
+  const ctr = row.ctr;
+  const position = row.position;
+  if (typeof impressions !== "number" || typeof ctr !== "number" || typeof position !== "number") return null;
+  if (position > 20) return 0;
+  const expected = expectedCTRByPosition(position);
+  const gap = expected - ctr;
+  if (gap <= 0) return 0;
+  return Math.round(impressions * gap / 100);
+}
+function calcClicksPerImpression(row) {
+  const clicks = row.clicks;
+  const impressions = row.impressions;
+  if (typeof clicks !== "number" || typeof impressions !== "number" || impressions === 0) return null;
+  return clicks / impressions * 1e3;
+}
+function calculateMetrics(row) {
+  return {
+    ctrOpportunity: calcCtrOpportunity(row),
+    clicksPerImpression: calcClicksPerImpression(row)
+    // impressionShare and clickShare need totals, computed in enrichWithCalculatedMetrics
+  };
+}
+function enrichWithCalculatedMetrics(rows, requestedCalculated) {
+  if (rows.length === 0) return rows;
+  let totalImpressions = 0;
+  let totalClicks = 0;
+  for (const row of rows) {
+    if (typeof row.impressions === "number") totalImpressions += row.impressions;
+    if (typeof row.clicks === "number") totalClicks += row.clicks;
+  }
+  return rows.map((row) => {
+    const calculated = calculateMetrics(row);
+    if (typeof row.impressions === "number" && totalImpressions > 0) {
+      calculated.impressionShare = row.impressions / totalImpressions * 100;
+    }
+    if (typeof row.clicks === "number" && totalClicks > 0) {
+      calculated.clickShare = row.clicks / totalClicks * 100;
+    }
+    const enriched = { ...row };
+    for (const [key, value] of Object.entries(calculated)) {
+      if (value === null) continue;
+      if (requestedCalculated && !requestedCalculated.includes(key)) continue;
+      enriched[key] = Math.round(value * 100) / 100;
+    }
+    return enriched;
+  });
+}
+function isCalculatedMetric(key) {
+  return GSC_CALCULATED_METRIC_DEFINITIONS.some((m) => m.key === key);
+}
+
+// src/platforms/gsc/compatibilityRules.ts
+var MAX_DIMENSIONS = 5;
+var MAX_HISTORY_DAYS = 490;
+var SEARCH_TYPES_WITHOUT_QUERY = /* @__PURE__ */ new Set([
+  "discover",
+  "googleNews"
+]);
+function validateGSCQuerySelection(dimensions, searchType, dateRange) {
+  const errors = [];
+  const warnings = [];
+  if (dimensions.length > MAX_DIMENSIONS) {
+    errors.push(
+      `GSC supports a maximum of ${MAX_DIMENSIONS} dimensions per request. You selected ${dimensions.length}.`
+    );
+  }
+  if (searchType && SEARCH_TYPES_WITHOUT_QUERY.has(searchType) && dimensions.includes("query")) {
+    errors.push(
+      `The 'query' dimension is not available for '${searchType}' search type. Discover and Google News do not expose search queries.`
+    );
+  }
+  if (dimensions.includes("searchAppearance")) {
+    warnings.push(
+      "The 'searchAppearance' dimension can inflate results: a single page URL may appear multiple times with different search features (e.g., AMP, review snippet). Totals may exceed what you see without this dimension."
+    );
+  }
+  if (dimensions.includes("query") && dimensions.includes("page")) {
+    warnings.push(
+      "Combining 'query' and 'page' dimensions produces high-cardinality results (each unique query-page pair is a row). Consider using a limit or filtering to keep results manageable."
+    );
+  }
+  if (dateRange) {
+    const start = new Date(dateRange.startDate);
+    const end = new Date(dateRange.endDate);
+    const daysDiff = Math.ceil((end.getTime() - start.getTime()) / (1e3 * 60 * 60 * 24));
+    if (daysDiff > MAX_HISTORY_DAYS) {
+      errors.push(
+        `GSC data is available for a maximum of ~16 months. Your date range spans ${daysDiff} days (max ${MAX_HISTORY_DAYS}).`
+      );
+    }
+    if (start > end) {
+      errors.push("Start date must be before end date.");
+    }
+  }
+  if (!dimensions.includes("date") && !dimensions.includes("hour")) {
+    if (dimensions.length > 0) {
+      warnings.push(
+        "No 'date' dimension selected. Results will be aggregated over the entire date range."
+      );
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+// src/platforms/gsc/queryPlanner.ts
+function planGSCQuery(params) {
+  const warnings = [];
+  const errors = [];
+  const requestedMetrics = params.metrics || ["clicks", "impressions", "ctr", "position"];
+  const calculatedMetrics = requestedMetrics.filter(isCalculatedMetric);
+  let resolvedDimensions = [];
+  if (params.dimensions && params.dimensions.length > 0) {
+    const { valid, invalid } = validateDimensions(params.dimensions);
+    resolvedDimensions = valid;
+    if (invalid.length > 0) {
+      warnings.push(`Unknown dimensions ignored: ${invalid.join(", ")}. Valid: query, page, country, device, date, hour, searchAppearance.`);
+    }
+  }
+  const searchType = params.searchType;
+  const validSearchTypes = ["web", "image", "video", "news", "discover", "googleNews"];
+  if (searchType && !validSearchTypes.includes(searchType)) {
+    warnings.push(`Unknown search type '${searchType}'. Valid: ${validSearchTypes.join(", ")}. Defaulting to 'web'.`);
+  }
+  const validation = validateGSCQuerySelection(
+    resolvedDimensions,
+    searchType,
+    params.dateRange
+  );
+  errors.push(...validation.errors);
+  warnings.push(...validation.warnings);
+  let dateRange;
+  if (params.dateRange) {
+    dateRange = params.dateRange;
+  } else if (params.datePreset) {
+    dateRange = resolveDatePreset(params.datePreset);
+  } else {
+    dateRange = resolveDatePreset("last28days");
+  }
+  const gscFilters = params.filters ? buildFiltersFromParams(params.filters) : [];
+  const request = {
+    startDate: dateRange.startDate,
+    endDate: dateRange.endDate,
+    ...resolvedDimensions.length > 0 && { dimensions: resolvedDimensions },
+    ...searchType && { type: searchType },
+    ...gscFilters.length > 0 && {
+      dimensionFilterGroups: [
+        {
+          groupType: "and",
+          filters: gscFilters
+        }
+      ]
+    },
+    ...params.limit && { rowLimit: params.limit },
+    ...params.aggregationType && { aggregationType: params.aggregationType },
+    dataState: params.dataState ?? "all"
+    // Include fresh (non-final) data by default
+  };
+  const requestFilters = request.dimensionFilterGroups?.flatMap((group) => group.filters) ?? [];
+  const filtersPage = requestFilters.some((filter) => filter.dimension === "page");
+  if (request.aggregationType === "byProperty" && (request.dimensions?.includes("page") || filtersPage)) {
+    errors.push("aggregationType=byProperty cannot be used when grouping or filtering by page; use auto or byPage.");
+  }
+  if (request.aggregationType === "byProperty" && (request.type === "discover" || request.type === "googleNews")) {
+    errors.push("aggregationType=byProperty is not supported for Discover or Google News.");
+  }
+  if (request.aggregationType === "byNewsShowcasePanel") {
+    const searchAppearanceFilters = requestFilters.filter((filter) => filter.dimension === "searchAppearance");
+    const isNewsShowcaseFilter = (filter) => filter.operator === "equals" && filter.expression === "NEWS_SHOWCASE";
+    if (request.type !== "discover" && request.type !== "googleNews") {
+      errors.push("aggregationType=byNewsShowcasePanel requires searchType=discover or googleNews.");
+    }
+    if (request.dimensions?.includes("page") || filtersPage) {
+      errors.push("aggregationType=byNewsShowcasePanel cannot be used when grouping or filtering by page.");
+    }
+    if (!searchAppearanceFilters.some(isNewsShowcaseFilter)) {
+      errors.push("aggregationType=byNewsShowcasePanel requires a searchAppearance equals NEWS_SHOWCASE filter.");
+    }
+    if (searchAppearanceFilters.some((filter) => !isNewsShowcaseFilter(filter))) {
+      errors.push("aggregationType=byNewsShowcasePanel cannot filter to a searchAppearance other than NEWS_SHOWCASE.");
+    }
+  }
+  if (request.dataState === "hourly_all" && !request.dimensions?.includes("hour")) {
+    warnings.push("dataState=hourly_all is most useful with the hour dimension; add hour to receive hourly breakdown and incomplete-hour metadata.");
+  }
+  if (request.dimensions?.includes("hour") && request.dataState !== "hourly_all") {
+    errors.push("The hour dimension requires dataState=hourly_all.");
+  }
+  if (request.dataState === "hourly_all") {
+    const start = /* @__PURE__ */ new Date(`${dateRange.startDate}T00:00:00Z`);
+    const end = /* @__PURE__ */ new Date(`${dateRange.endDate}T00:00:00Z`);
+    const inclusiveDays = Math.floor((end.getTime() - start.getTime()) / 864e5) + 1;
+    if (Number.isFinite(inclusiveDays) && inclusiveDays > 10) {
+      errors.push(`Hourly Search Analytics is available for at most 10 days; this range spans ${inclusiveDays} days.`);
+    }
+  }
+  return {
+    request,
+    siteUrl: params.siteUrl,
+    warnings,
+    errors,
+    calculatedMetrics,
+    requestedMetrics
+  };
+}
+
+// src/platforms/gsc/tools.ts
+var siteUrlSchema = z2.string().optional().describe("Search Console property URL, e.g. https://example.com/ or sc-domain:example.com. Uses GSC_SITE_URL when omitted.");
+var datePresetSchema = z2.enum(["today", "yesterday", "last7days", "last28days", "last3months", "last6months", "last12months", "last16months"]);
+var searchTypeSchema = z2.enum(["web", "image", "video", "news", "discover", "googleNews"]);
+var dataStateSchema = z2.enum(["final", "all", "hourly_all"]);
+var aggregationTypeSchema = z2.enum(["auto", "byPage", "byProperty", "byNewsShowcasePanel"]);
+var limitSchema = z2.number().int().min(1).max(25e3).optional().default(1e3);
+var dateRangeSchema = z2.object({
+  startDate: z2.string().describe("Start date YYYY-MM-DD"),
+  endDate: z2.string().describe("End date YYYY-MM-DD")
+});
+var comparisonDimensionSchema = z2.enum(["query", "page"]);
+var sitemapBaselineSchema = z2.object({
+  path: z2.string().describe("Sitemap URL/path returned by GSC."),
+  submitted: z2.number().int().min(0).optional().default(0),
+  indexed: z2.number().int().min(0).optional().default(0),
+  warnings: z2.number().int().min(0).optional().default(0),
+  errors: z2.number().int().min(0).optional().default(0),
+  lastSubmitted: z2.string().optional(),
+  lastDownloaded: z2.string().optional()
+});
+var watchlistUrlSchema = z2.object({
+  url: z2.string().url(),
+  label: z2.string().optional(),
+  priority: z2.enum(["low", "medium", "high", "critical"]).optional().default("medium"),
+  tags: z2.array(z2.string()).optional().default([]),
+  expectedVerdict: z2.enum(["PASS", "PARTIAL", "FAIL", "NEUTRAL", "VERDICT_UNSPECIFIED"]).optional().default("PASS"),
+  expectedCanonical: z2.string().url().optional(),
+  expectedCoverageState: z2.string().optional()
+});
+var samplingObjectiveSchema = z2.enum(["topTraffic", "lowCtr", "declining", "sitemapRisk", "staleSitemaps"]);
+var BULK_URL_INSPECTION_LIMIT = 10;
+var URL_INSPECTION_DAILY_QUOTA = 2e3;
+var DEFAULT_FRESHNESS_LAG_WARNING_DAYS = 3;
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "about",
+  "after",
+  "and",
+  "are",
+  "as",
+  "at",
+  "avec",
+  "be",
+  "by",
+  "comment",
+  "dans",
+  "de",
+  "des",
+  "du",
+  "en",
+  "est",
+  "et",
+  "for",
+  "from",
+  "how",
+  "in",
+  "is",
+  "la",
+  "le",
+  "les",
+  "of",
+  "on",
+  "ou",
+  "pour",
+  "que",
+  "qui",
+  "the",
+  "to",
+  "un",
+  "une",
+  "what",
+  "when",
+  "where",
+  "why",
+  "with"
+]);
+var QUESTION_TOKENS = /* @__PURE__ */ new Set([
+  "comment",
+  "combien",
+  "est-ce",
+  "how",
+  "ou",
+  "pourquoi",
+  "quand",
+  "que",
+  "quel",
+  "quelle",
+  "quelles",
+  "quels",
+  "qui",
+  "quoi",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "why"
+]);
+var COMMERCIAL_TOKENS = /* @__PURE__ */ new Set([
+  "avis",
+  "best",
+  "buy",
+  "comparatif",
+  "compare",
+  "coupon",
+  "discount",
+  "meilleur",
+  "price",
+  "prix",
+  "review",
+  "tarif",
+  "vs"
+]);
+var NAVIGATIONAL_TOKENS = /* @__PURE__ */ new Set(["account", "app", "connexion", "dashboard", "login", "sign", "signin"]);
+var GSC_RESPONSE_API_VERSION = "searchconsole_v1/webmasters_v3";
+function isAgentResponseRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwnField(value, field) {
+  return Object.prototype.hasOwnProperty.call(value, field);
+}
+function getDebugRecord(payload) {
+  return isAgentResponseRecord(payload["debug"]) ? payload["debug"] : {};
+}
+function getRequestCount(payload) {
+  const debug = getDebugRecord(payload);
+  const requestCount = debug["requestCount"];
+  return typeof requestCount === "number" ? requestCount : 1;
+}
+function getWarnings(payload) {
+  if (Array.isArray(payload["warnings"])) return payload["warnings"];
+  const debug = getDebugRecord(payload);
+  return Array.isArray(debug["warnings"]) ? debug["warnings"] : [];
+}
+function withAgentResponseContract(data) {
+  if (!isAgentResponseRecord(data)) return data;
+  return {
+    ...data,
+    warnings: hasOwnField(data, "warnings") ? data["warnings"] : getWarnings(data),
+    limitations: hasOwnField(data, "limitations") ? data["limitations"] : [],
+    nextActions: hasOwnField(data, "nextActions") ? data["nextActions"] : [],
+    debug: {
+      ...getDebugRecord(data),
+      source: "google_search_console",
+      apiVersion: GSC_RESPONSE_API_VERSION,
+      requestCount: getRequestCount(data)
+    }
+  };
+}
+function ok(data) {
+  return { content: [{ type: "text", text: JSON.stringify(withAgentResponseContract(data), null, 2) }] };
+}
+var AuthenticatedGSCClient = class {
+  constructor(config) {
+    this.config = config;
+    this.accessToken = config.accessToken;
+    if (config.accessToken) {
+      this.tokenExpiresAt = Date.now() + 45 * 60 * 1e3;
+    }
+  }
+  config;
+  accessToken;
+  tokenExpiresAt = 0;
+  rateLimiter = new RateLimiter();
+  async ensureAccessToken() {
+    if (this.accessToken && Date.now() < this.tokenExpiresAt) {
+      return this.accessToken;
+    }
+    if (!this.config.refreshToken || !this.config.clientId || !this.config.clientSecret) {
+      throw new Error("No valid GSC access token and refresh credentials are incomplete.");
+    }
+    const tokens = await this.rateLimiter.execute(
+      () => refreshAccessToken(this.config.refreshToken, this.config.clientId, this.config.clientSecret)
+    );
+    this.accessToken = tokens.access_token;
+    this.tokenExpiresAt = Date.now() + ((tokens.expires_in ?? 3600) - 60) * 1e3;
+    return this.accessToken;
+  }
+  async get() {
+    return new GSCClient(await this.ensureAccessToken());
+  }
+};
+function resolveSiteUrl(inputSiteUrl, config) {
+  const siteUrl = inputSiteUrl || config.defaultSiteUrl;
+  if (!siteUrl) {
+    throw new Error("Missing siteUrl. Pass siteUrl, or set GSC_SITE_URL in Claude Desktop config.");
+  }
+  return siteUrl;
+}
+function roundMetric(value, decimals = 2) {
+  if (!Number.isFinite(value)) return 0;
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+function parseCount(value) {
+  if (value === void 0) return 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+function formatDate(date) {
+  return date.toISOString().slice(0, 10);
+}
+function todayUtc() {
+  const now = /* @__PURE__ */ new Date();
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+function addUtcDays(date, days) {
+  const copy = new Date(date);
+  copy.setUTCDate(copy.getUTCDate() + days);
+  return copy;
+}
+function parseDateStrict(value, label) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    throw new Error(`${label} must use YYYY-MM-DD format.`);
+  }
+  const parsed = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+  if (Number.isNaN(parsed.getTime()) || formatDate(parsed) !== value) {
+    throw new Error(`${label} is not a valid date.`);
+  }
+  return parsed;
+}
+function validateDateRange(dateRange) {
+  const start = parseDateStrict(dateRange.startDate, "startDate");
+  const end = parseDateStrict(dateRange.endDate, "endDate");
+  if (start > end) {
+    throw new Error("startDate must be before or equal to endDate.");
+  }
+}
+function inclusiveDayCount(dateRange) {
+  const start = parseDateStrict(dateRange.startDate, "startDate");
+  const end = parseDateStrict(dateRange.endDate, "endDate");
+  return Math.floor((end.getTime() - start.getTime()) / 864e5) + 1;
+}
+function derivePreviousDateRange(dateRange) {
+  const start = parseDateStrict(dateRange.startDate, "startDate");
+  const days = inclusiveDayCount(dateRange);
+  const previousEnd = addUtcDays(start, -1);
+  const previousStart = addUtcDays(previousEnd, -(days - 1));
+  return { startDate: formatDate(previousStart), endDate: formatDate(previousEnd) };
+}
+function daysBetween(fromDate, toDate) {
+  const from = parseDateStrict(fromDate, "date");
+  return Math.floor((toDate.getTime() - from.getTime()) / 864e5);
+}
+function safeDaysBetweenDatePrefix(fromDate, toDate) {
+  if (!fromDate) return null;
+  try {
+    return daysBetween(fromDate.slice(0, 10), toDate);
+  } catch {
+    return null;
+  }
+}
+function rowMetrics(row) {
+  if (!row) {
+    return { clicks: 0, impressions: 0, ctr: 0, position: null };
+  }
+  return {
+    clicks: roundMetric(row.clicks, 0),
+    impressions: roundMetric(row.impressions, 0),
+    ctr: roundMetric(row.ctr * 100),
+    position: roundMetric(row.position)
+  };
+}
+function summarizeRows(rows) {
+  const clicks = rows.reduce((sum, row) => sum + row.clicks, 0);
+  const impressions = rows.reduce((sum, row) => sum + row.impressions, 0);
+  const weightedPosition = rows.reduce((sum, row) => sum + row.position * row.impressions, 0);
+  return {
+    clicks: roundMetric(clicks, 0),
+    impressions: roundMetric(impressions, 0),
+    ctr: impressions > 0 ? roundMetric(clicks / impressions * 100) : 0,
+    position: impressions > 0 ? roundMetric(weightedPosition / impressions) : 0
+  };
+}
+function percentageChange(current, previous) {
+  if (previous === 0) return current === 0 ? 0 : null;
+  return roundMetric((current - previous) / previous * 100);
+}
+function keyRowsByDimension(rows) {
+  const keyed = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = row.keys?.[0];
+    if (key) keyed.set(key, row);
+  }
+  return keyed;
+}
+function normalizeText(value) {
+  return value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().trim();
+}
+function uniqueValues(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+function tokenizeQuery(query) {
+  return uniqueValues(
+    normalizeText(query).replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).map((token) => token.replace(/^-+|-+$/g, "")).filter((token) => token.length > 1 && !STOP_WORDS.has(token))
+  );
+}
+function deriveBrandTerms(siteUrl) {
+  let host = siteUrl;
+  if (siteUrl.startsWith("sc-domain:")) {
+    host = siteUrl.replace("sc-domain:", "");
+  } else {
+    try {
+      host = new URL(siteUrl).hostname;
+    } catch {
+      host = siteUrl;
+    }
+  }
+  const ignored = /* @__PURE__ */ new Set(["www", "com", "fr", "io", "ai", "net", "org", "co", "uk"]);
+  return uniqueValues(
+    normalizeText(host).split(/[.-]/).filter((part) => part.length > 2 && !ignored.has(part))
+  );
+}
+function expandBrandTerms(terms) {
+  const expanded = /* @__PURE__ */ new Set();
+  for (const term of terms.map(normalizeText).filter((value) => value.length > 1)) {
+    expanded.add(term);
+    const compacted = term.replace(/[\s-]+/g, "");
+    expanded.add(compacted);
+    const words = term.replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter(Boolean);
+    if (words.length > 1 && words[0].endsWith("s")) {
+      expanded.add([words[0].slice(0, -1), ...words.slice(1)].join(" "));
+    }
+    if (compacted === "galerieslafayette" || compacted === "galerielafayette") {
+      expanded.add("galeries lafayette");
+      expanded.add("galerie lafayette");
+      expanded.add("gallery lafayette");
+      expanded.add("gallerie lafayette");
+      expanded.add("lafayette");
+    }
+  }
+  return uniqueValues([...expanded]);
+}
+function classifyQuery(query, tokens, brandTerms) {
+  const normalized = normalizeText(query);
+  const compacted = normalized.replace(/[\s-]+/g, "");
+  const normalizedWords = normalized.replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter(Boolean);
+  const isBrand = brandTerms.some((term) => {
+    const normalizedTerm = normalizeText(term);
+    const compactedTerm = normalizedTerm.replace(/[\s-]+/g, "");
+    return normalizedTerm.length > 1 && (normalized.includes(normalizedTerm) || compacted.includes(compactedTerm));
+  });
+  const isQuestion = normalizedWords.some((token) => QUESTION_TOKENS.has(token)) || normalized.endsWith("?");
+  const hasCommercialIntent = tokens.some((token) => COMMERCIAL_TOKENS.has(token));
+  const hasNavigationalIntent = tokens.some((token) => NAVIGATIONAL_TOKENS.has(token));
+  return {
+    brand: isBrand ? "brand" : "nonBrand",
+    question: isQuestion ? "question" : "nonQuestion",
+    intent: isQuestion ? "question" : hasCommercialIntent ? "commercial" : hasNavigationalIntent ? "navigational" : "informational"
+  };
+}
+function resolveQueryCategory(query, tokens, categoryRules) {
+  const normalized = normalizeText(query);
+  for (const [category, terms] of Object.entries(categoryRules ?? {})) {
+    const normalizedTerms = terms.map(normalizeText).filter(Boolean);
+    if (normalizedTerms.some((term) => tokens.includes(term) || normalized.includes(term))) {
+      return category;
+    }
+  }
+  return tokens[0] ? `topic:${tokens[0]}` : "uncategorized";
+}
+function createMetricBucket() {
+  return { clicks: 0, impressions: 0, weightedPosition: 0, queryCount: 0, topQueries: [] };
+}
+function addQueryToBucket(bucket, query, row) {
+  bucket.clicks += row.clicks;
+  bucket.impressions += row.impressions;
+  bucket.weightedPosition += row.position * row.impressions;
+  bucket.queryCount += 1;
+  bucket.topQueries.push({
+    query,
+    clicks: roundMetric(row.clicks, 0),
+    impressions: roundMetric(row.impressions, 0),
+    ctr: roundMetric(row.ctr * 100),
+    position: roundMetric(row.position)
+  });
+}
+function getOrCreateBucket(map, key) {
+  const existing = map.get(key);
+  if (existing) return existing;
+  const created = createMetricBucket();
+  map.set(key, created);
+  return created;
+}
+function finalizeBucket(label, bucket, topQueryLimit = 10) {
+  return {
+    cluster: label,
+    queryCount: bucket.queryCount,
+    clicks: roundMetric(bucket.clicks, 0),
+    impressions: roundMetric(bucket.impressions, 0),
+    ctr: bucket.impressions > 0 ? roundMetric(bucket.clicks / bucket.impressions * 100) : 0,
+    position: bucket.impressions > 0 ? roundMetric(bucket.weightedPosition / bucket.impressions) : 0,
+    topQueries: bucket.topQueries.sort((a, b) => b.clicks - a.clicks || b.impressions - a.impressions).slice(0, topQueryLimit)
+  };
+}
+function finalizeBuckets(map, topQueryLimit = 10) {
+  return [...map.entries()].map(([label, bucket]) => finalizeBucket(label, bucket, topQueryLimit)).sort((a, b) => b.clicks - a.clicks || b.impressions - a.impressions);
+}
+function normalizeInspectionResult(url, response) {
+  const inspection = response.inspectionResult;
+  const indexStatus = inspection.indexStatusResult;
+  const mobileIssues = inspection.mobileUsabilityResult?.issues ?? [];
+  const richIssues = (inspection.richResultsResult?.detectedItems ?? []).flatMap(
+    (detectedItem) => (detectedItem.items ?? []).flatMap(
+      (item) => (item.issues ?? []).map((issue) => ({
+        richResultType: detectedItem.richResultType,
+        itemName: item.name,
+        message: issue.issueMessage,
+        severity: issue.severity
+      }))
+    )
+  );
+  const ampIssues = inspection.ampResult?.issues ?? [];
+  return {
+    url,
+    inspectionResultLink: inspection.inspectionResultLink,
+    indexStatus: {
+      verdict: indexStatus?.verdict,
+      coverageState: indexStatus?.coverageState,
+      indexingState: indexStatus?.indexingState,
+      pageFetchState: indexStatus?.pageFetchState,
+      robotsTxtState: indexStatus?.robotsTxtState,
+      lastCrawlTime: indexStatus?.lastCrawlTime,
+      crawledAs: indexStatus?.crawledAs,
+      googleCanonical: indexStatus?.googleCanonical,
+      userCanonical: indexStatus?.userCanonical
+    },
+    mobileUsability: {
+      verdict: inspection.mobileUsabilityResult?.verdict,
+      issueCount: mobileIssues.length,
+      issues: mobileIssues
+    },
+    richResults: {
+      verdict: inspection.richResultsResult?.verdict,
+      itemCount: inspection.richResultsResult?.detectedItems?.length ?? 0,
+      issueCount: richIssues.length,
+      issues: richIssues
+    },
+    amp: {
+      verdict: inspection.ampResult?.verdict,
+      ampUrl: inspection.ampResult?.ampUrl,
+      ampIndexStatusVerdict: inspection.ampResult?.ampIndexStatusVerdict,
+      issueCount: ampIssues.length,
+      issues: ampIssues
+    }
+  };
+}
+function normalizePerUrlError(error) {
+  const apiError = error;
+  return {
+    error: apiError.message ?? (error instanceof Error ? error.message : String(error)),
+    code: apiError.code,
+    status: apiError.status,
+    isRateLimit: Boolean(apiError.isRateLimitError || apiError.isQuotaError),
+    suggestion: apiError.suggestion
+  };
+}
+function summarizeSitemapForP2(sitemap) {
+  const warningCount = parseCount(sitemap.warnings);
+  const errorCount = parseCount(sitemap.errors);
+  const contents = (sitemap.contents || []).map((content) => {
+    const submitted2 = parseCount(content.submitted);
+    const indexed2 = parseCount(content.indexed);
+    return {
+      type: content.type,
+      submitted: submitted2,
+      indexed: indexed2,
+      indexRate: submitted2 > 0 ? roundMetric(indexed2 / submitted2 * 100) : null
+    };
+  });
+  const submitted = contents.reduce((sum, content) => sum + content.submitted, 0);
+  const indexed = contents.reduce((sum, content) => sum + content.indexed, 0);
+  const status = sitemap.isPending ? "pending" : errorCount > 0 ? "error" : warningCount > 0 ? "warning" : "healthy";
+  return {
+    path: sitemap.path,
+    status,
+    lastSubmitted: sitemap.lastSubmitted,
+    lastDownloaded: sitemap.lastDownloaded,
+    isPending: Boolean(sitemap.isPending),
+    isSitemapsIndex: Boolean(sitemap.isSitemapsIndex),
+    type: sitemap.type,
+    warnings: warningCount,
+    errors: errorCount,
+    contents,
+    totals: {
+      submitted,
+      indexed,
+      indexRate: submitted > 0 ? roundMetric(indexed / submitted * 100) : null
+    }
+  };
+}
+function summarizeSitemapCollection(sitemaps) {
+  const submitted = sitemaps.reduce((sum, sitemap) => sum + sitemap.totals.submitted, 0);
+  const indexed = sitemaps.reduce((sum, sitemap) => sum + sitemap.totals.indexed, 0);
+  const statusCounts = {
+    healthy: sitemaps.filter((sitemap) => sitemap.status === "healthy").length,
+    pending: sitemaps.filter((sitemap) => sitemap.status === "pending").length,
+    warning: sitemaps.filter((sitemap) => sitemap.status === "warning").length,
+    error: sitemaps.filter((sitemap) => sitemap.status === "error").length
+  };
+  return {
+    count: sitemaps.length,
+    statusCounts,
+    warnings: sitemaps.reduce((sum, sitemap) => sum + sitemap.warnings, 0),
+    errors: sitemaps.reduce((sum, sitemap) => sum + sitemap.errors, 0),
+    sitemapIndexes: sitemaps.filter((sitemap) => sitemap.isSitemapsIndex).length,
+    submitted,
+    indexed,
+    indexRate: submitted > 0 ? roundMetric(indexed / submitted * 100) : null,
+    newestLastSubmitted: latestStringDate(sitemaps.map((sitemap) => sitemap.lastSubmitted)),
+    newestLastDownloaded: latestStringDate(sitemaps.map((sitemap) => sitemap.lastDownloaded))
+  };
+}
+function latestStringDate(values) {
+  const sorted = values.filter((value) => Boolean(value)).sort((a, b) => a.localeCompare(b));
+  return sorted[sorted.length - 1] ?? null;
+}
+function sitemapSnapshot(summary) {
+  return {
+    path: summary.path,
+    submitted: summary.totals.submitted,
+    indexed: summary.totals.indexed,
+    warnings: summary.warnings,
+    errors: summary.errors,
+    lastSubmitted: summary.lastSubmitted,
+    lastDownloaded: summary.lastDownloaded
+  };
+}
+function analyzeDailyFreshness(rows, endDate, lagWarningDays) {
+  const sortedRows = rows.filter((row) => row.keys?.[0]).sort((a, b) => String(a.keys?.[0]).localeCompare(String(b.keys?.[0])));
+  const rowsWithData = sortedRows.filter((row) => row.clicks > 0 || row.impressions > 0);
+  const latestRow = rowsWithData[rowsWithData.length - 1];
+  const latestDataDate = latestRow?.keys?.[0] ?? null;
+  const dataLagDays = latestDataDate ? daysBetween(latestDataDate, endDate) : null;
+  const status = latestDataDate === null ? "noData" : dataLagDays !== null && dataLagDays <= lagWarningDays ? "fresh" : dataLagDays !== null && dataLagDays <= lagWarningDays + 2 ? "delayed" : "stale";
+  return {
+    latestDataDate,
+    dataLagDays,
+    status,
+    hasRecentData: dataLagDays !== null && dataLagDays <= lagWarningDays,
+    rowCount: sortedRows.length,
+    dailyRows: sortedRows.map((row) => ({
+      date: row.keys?.[0],
+      ...rowMetrics(row)
+    }))
+  };
+}
+function assessInspectionResult(result, watch) {
+  const issues = [];
+  const verdict = result.indexStatus.verdict;
+  const coverageState = result.indexStatus.coverageState;
+  const pageFetchState = result.indexStatus.pageFetchState;
+  const robotsTxtState = result.indexStatus.robotsTxtState;
+  const expectedVerdict = watch?.expectedVerdict ?? "PASS";
+  if (!verdict) {
+    issues.push("URL Inspection did not return an index status verdict.");
+  } else if (verdict !== expectedVerdict) {
+    issues.push(`Expected index verdict ${expectedVerdict}, got ${verdict}.`);
+  }
+  if (watch?.expectedCoverageState && coverageState !== watch.expectedCoverageState) {
+    issues.push(`Expected coverage state '${watch.expectedCoverageState}', got '${coverageState ?? "unknown"}'.`);
+  }
+  if (pageFetchState && !/successful/i.test(pageFetchState)) {
+    issues.push(`Page fetch state is '${pageFetchState}'.`);
+  }
+  if (robotsTxtState && /disallow|blocked/i.test(robotsTxtState)) {
+    issues.push(`robots.txt state is '${robotsTxtState}'.`);
+  }
+  if (watch?.expectedCanonical && result.indexStatus.googleCanonical && result.indexStatus.googleCanonical !== watch.expectedCanonical) {
+    issues.push(`Google canonical differs from expected canonical '${watch.expectedCanonical}'.`);
+  }
+  if (result.mobileUsability.verdict && !["PASS", "NEUTRAL"].includes(result.mobileUsability.verdict)) {
+    issues.push(`Mobile usability verdict is ${result.mobileUsability.verdict}.`);
+  }
+  if (result.richResults.issueCount > 0) {
+    issues.push(`${result.richResults.issueCount} rich result issue(s) detected.`);
+  }
+  const priority = watch?.priority ?? "medium";
+  const status = issues.length === 0 ? "ok" : priority === "critical" || priority === "high" ? "alert" : "review";
+  return {
+    status,
+    indexed: verdict === "PASS",
+    priority,
+    issues
+  };
+}
+function rowCompositeKey(row, dimensionCount) {
+  return JSON.stringify((row.keys ?? []).slice(0, dimensionCount));
+}
+function dedupeUrlList(urls, limit) {
+  return uniqueValues(urls).slice(0, limit);
+}
+function registerGSCTools(server, config) {
+  const clientFactory = new AuthenticatedGSCClient(config);
+  server.tool(
+    "gsc_list_sites",
+    "List all Google Search Console properties accessible with the current credentials.",
+    {},
+    async () => {
+      try {
+        const client = await clientFactory.get();
+        const sites = await client.listSites();
+        return ok({ sites, count: sites.length });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_get_site",
+    "Get one Search Console property and its exact permission level (read-only sites.get).",
+    { siteUrl: siteUrlSchema },
+    async ({ siteUrl }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const client = await clientFactory.get();
+        const site = await client.getSite(resolvedSiteUrl);
+        return ok({ site });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_health_check",
+    "Verify Google Search Console read-only authentication, visible properties, configured default site, and permission levels without exposing tokens.",
+    { siteUrl: siteUrlSchema },
+    async ({ siteUrl }) => {
+      try {
+        const warnings = [];
+        const targetSiteUrl = siteUrl || config.defaultSiteUrl;
+        const hasRefreshCredentials = Boolean(config.refreshToken && config.clientId && config.clientSecret);
+        const client = await clientFactory.get();
+        const sites = await client.listSites();
+        const visibleSites = sites.map((site) => ({
+          siteUrl: site.siteUrl,
+          permissionLevel: site.permissionLevel,
+          status: site.permissionLevel === "siteUnverifiedUser" ? "unverified" : "verified",
+          canRead: site.permissionLevel !== "siteUnverifiedUser"
+        }));
+        const targetSite = targetSiteUrl ? visibleSites.find((site) => site.siteUrl === targetSiteUrl) : void 0;
+        if (sites.length === 0) {
+          warnings.push("No Search Console properties are visible to these credentials.");
+        }
+        if (!targetSiteUrl) {
+          warnings.push("No default site is configured. Set GSC_SITE_URL or pass siteUrl to property-specific tools.");
+        }
+        if (targetSiteUrl && !targetSite) {
+          warnings.push(`Configured/requested site '${targetSiteUrl}' is not visible in listSites(). Check exact URL/property format and permissions.`);
+        }
+        if (targetSite?.permissionLevel === "siteUnverifiedUser") {
+          warnings.push(`Site '${targetSite.siteUrl}' is visible but unverified for this account.`);
+        }
+        if (targetSite?.permissionLevel === "siteRestrictedUser") {
+          warnings.push(`Site '${targetSite.siteUrl}' has restricted permissions; some GSC reports may be unavailable.`);
+        }
+        if (!hasRefreshCredentials && config.accessToken) {
+          warnings.push("Using a static access token without refresh credentials; re-authentication may be required when it expires.");
+        }
+        return ok({
+          ok: true,
+          authentication: {
+            status: "authenticated",
+            credentialMode: config.accessToken ? hasRefreshCredentials ? "access_token_with_refresh_fallback" : "access_token" : "refresh_token",
+            requiredScope: GSC_OAUTH_SCOPE
+          },
+          defaultSite: {
+            configured: Boolean(config.defaultSiteUrl),
+            requestedSiteUrl: targetSiteUrl,
+            found: Boolean(targetSite),
+            permissionLevel: targetSite?.permissionLevel,
+            status: targetSite?.status
+          },
+          sites: {
+            count: visibleSites.length,
+            entries: visibleSites
+          },
+          warnings
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_query_search_analytics",
+    `Query Google Search Console Search Analytics. Returns clicks, impressions, CTR, and average position for queries, pages, countries, devices, dates, and search appearances.
+Use gsc://metrics, gsc://dimensions, gsc://filters, and gsc://compatibility for available fields and rules.`,
+    {
+      siteUrl: siteUrlSchema,
+      metrics: z2.array(z2.string()).optional().describe("Native: clicks, impressions, ctr, position. Calculated: ctrOpportunity, clicksPerImpression, impressionShare, clickShare."),
+      dimensions: z2.array(z2.string()).max(5).optional().describe("Up to 5 dimensions selected from query, page, country, device, date, hour, searchAppearance."),
+      filters: z2.array(z2.object({
+        field: z2.string(),
+        operator: z2.enum(["contains", "equals", "notContains", "notEquals", "includingRegex", "excludingRegex"]),
+        value: z2.union([z2.string(), z2.number(), z2.boolean()])
+      })).optional(),
+      searchType: searchTypeSchema.optional().default("web"),
+      dataState: dataStateSchema.optional().default("all").describe("final=stable data, all=fresh daily data, hourly_all=fresh hourly data (use hour dimension)."),
+      aggregationType: aggregationTypeSchema.optional().default("auto").describe("Official GSC aggregation. byProperty is incompatible with page grouping/filtering and Discover/Google News. byNewsShowcasePanel requires discover/googleNews plus searchAppearance equals NEWS_SHOWCASE, and forbids page grouping/filtering or another searchAppearance filter."),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      dateRange: z2.object({
+        startDate: z2.string().describe("Start date YYYY-MM-DD"),
+        endDate: z2.string().describe("End date YYYY-MM-DD")
+      }).optional(),
+      orderBy: z2.enum(["clicks", "impressions", "ctr", "position", "ctrOpportunity", "clicksPerImpression", "impressionShare", "clickShare"]).optional().default("clicks"),
+      orderDirection: z2.enum(["ASC", "DESC"]).optional().default("DESC"),
+      limit: limitSchema,
+      startRow: z2.number().int().min(0).optional().describe("Optional 0-based row offset for explicit pagination."),
+      autoPaginate: z2.boolean().optional().default(false).describe("When true, omit rowLimit so the GSC client auto-paginates until exhaustion.")
+    },
+    async ({ siteUrl, metrics, dimensions, filters, searchType, dataState, aggregationType, datePreset, dateRange, orderBy, orderDirection, limit, startRow, autoPaginate }) => {
+      try {
+        const startTime = Date.now();
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const plan = planGSCQuery({
+          siteUrl: resolvedSiteUrl,
+          metrics,
+          dimensions,
+          filters,
+          searchType,
+          datePreset,
+          dateRange,
+          orderBy,
+          limit: autoPaginate ? void 0 : limit,
+          aggregationType,
+          dataState
+        });
+        if (typeof startRow === "number") plan.request.startRow = startRow;
+        if (plan.errors.length > 0) {
+          return ok({ error: "Query validation failed", errors: plan.errors, warnings: plan.warnings });
+        }
+        const client = await clientFactory.get();
+        const response = await client.querySearchAnalytics(plan.siteUrl, plan.request);
+        const flatData = flattenSearchAnalyticsResponse(response, plan.request.dimensions);
+        const enrichedData = plan.calculatedMetrics.length > 0 ? enrichWithCalculatedMetrics(flatData, plan.calculatedMetrics) : flatData;
+        const data = enrichedData;
+        if (orderBy && data.length > 0) {
+          data.sort((a, b) => {
+            const aVal = Number(a[orderBy]) || 0;
+            const bVal = Number(b[orderBy]) || 0;
+            const asc = orderDirection === "ASC" || orderBy === "position";
+            return asc ? aVal - bVal : bVal - aVal;
+          });
+        }
+        return ok({
+          data,
+          rowCount: data.length,
+          responseAggregationType: response.responseAggregationType,
+          metadata: response.metadata,
+          debug: {
+            executionTimeMs: Date.now() - startTime,
+            warnings: plan.warnings,
+            calculatedMetrics: plan.calculatedMetrics,
+            requestedMetrics: plan.requestedMetrics,
+            pagination: {
+              mode: autoPaginate ? "auto_startRow" : "single_page",
+              autoPaginate,
+              startRow: startRow ?? 0,
+              limit: autoPaginate ? null : limit
+            },
+            dataState,
+            aggregationType
+          }
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_inspect_url",
+    "Inspect a URL for Google indexing status, crawl info, mobile usability, AMP, and rich results. Quota: 2000 requests/day/property.",
+    {
+      siteUrl: siteUrlSchema,
+      url: z2.string().url().describe("Full URL to inspect."),
+      languageCode: z2.string().optional().describe("Optional IETF language tag, e.g. en-US or fr-FR.")
+    },
+    async ({ siteUrl, url, languageCode }) => {
+      try {
+        const client = await clientFactory.get();
+        const result = await client.inspectUrl(url, resolveSiteUrl(siteUrl, config), languageCode);
+        const inspection = result.inspectionResult;
+        return ok({
+          url,
+          inspectionResultLink: inspection.inspectionResultLink,
+          indexStatus: inspection.indexStatusResult,
+          mobileUsability: inspection.mobileUsabilityResult,
+          richResults: inspection.richResultsResult,
+          amp: inspection.ampResult
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_bulk_inspect_urls",
+    "Inspect multiple URLs with a conservative sequential limit and normalized URL Inspection results. Quota: 2000 requests/day/property.",
+    {
+      siteUrl: siteUrlSchema,
+      urls: z2.array(z2.string().url()).min(1).max(BULK_URL_INSPECTION_LIMIT).describe(`Full URLs to inspect. Maximum ${BULK_URL_INSPECTION_LIMIT} per call to protect URL Inspection quota.`),
+      languageCode: z2.string().optional().describe("Optional IETF language tag, e.g. en-US or fr-FR."),
+      continueOnError: z2.boolean().optional().default(true).describe("When true, returns per-URL errors instead of failing the entire batch.")
+    },
+    async ({ siteUrl, urls, languageCode, continueOnError }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const client = await clientFactory.get();
+        const uniqueUrls = uniqueValues(urls);
+        const warnings = [
+          `URL Inspection API quota is limited to ${URL_INSPECTION_DAILY_QUOTA} requests/day/property; this tool caps each call at ${BULK_URL_INSPECTION_LIMIT} URLs and runs sequentially.`
+        ];
+        if (uniqueUrls.length < urls.length) {
+          warnings.push(`${urls.length - uniqueUrls.length} duplicate URL(s) were skipped before inspection.`);
+        }
+        const results = [];
+        for (const url of uniqueUrls) {
+          try {
+            const response = await client.inspectUrl(url, resolvedSiteUrl, languageCode);
+            results.push({ ok: true, ...normalizeInspectionResult(url, response) });
+          } catch (error) {
+            if (!continueOnError) throw error;
+            results.push({ ok: false, url, ...normalizePerUrlError(error) });
+          }
+        }
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          inspectedCount: results.length,
+          failedCount: results.filter((result) => !result.ok).length,
+          warnings,
+          results
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_list_sitemaps",
+    "List sitemaps submitted for a Search Console property, including processing status and submitted/indexed counts.",
+    {
+      siteUrl: siteUrlSchema,
+      sitemapIndex: z2.string().url().optional().describe("Optional sitemap index URL used to return only its child sitemaps.")
+    },
+    async ({ siteUrl, sitemapIndex }) => {
+      try {
+        const client = await clientFactory.get();
+        const result = await client.listSitemaps(resolveSiteUrl(siteUrl, config), sitemapIndex);
+        const sitemaps = (result.sitemap || []).map((s) => ({
+          path: s.path,
+          lastSubmitted: s.lastSubmitted,
+          isPending: s.isPending,
+          isSitemapsIndex: s.isSitemapsIndex,
+          type: s.type,
+          lastDownloaded: s.lastDownloaded,
+          warnings: s.warnings,
+          errors: s.errors,
+          contents: s.contents
+        }));
+        return ok({ sitemaps, count: sitemaps.length });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_get_sitemap",
+    "Get one submitted sitemap by full feed path, including type, fetch state, warnings/errors, and submitted/indexed content totals.",
+    {
+      siteUrl: siteUrlSchema,
+      feedpath: z2.string().url().describe("Full sitemap URL exactly as submitted to Search Console.")
+    },
+    async ({ siteUrl, feedpath }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const client = await clientFactory.get();
+        const sitemap = await client.getSitemap(resolvedSiteUrl, feedpath);
+        return ok({ siteUrl: resolvedSiteUrl, sitemap });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_get_sitemap_health",
+    "Return an enriched read-only sitemap health summary with status totals, submitted/indexed content counts, warnings, and errors.",
+    { siteUrl: siteUrlSchema },
+    async ({ siteUrl }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const client = await clientFactory.get();
+        const result = await client.listSitemaps(resolvedSiteUrl);
+        const sitemaps = (result.sitemap || []).map((sitemap) => {
+          const warningCount = parseCount(sitemap.warnings);
+          const errorCount = parseCount(sitemap.errors);
+          const submitted = (sitemap.contents || []).reduce((sum, content) => sum + parseCount(content.submitted), 0);
+          const indexed = (sitemap.contents || []).reduce((sum, content) => sum + parseCount(content.indexed), 0);
+          const status = sitemap.isPending ? "pending" : errorCount > 0 ? "error" : warningCount > 0 ? "warning" : "healthy";
+          return {
+            path: sitemap.path,
+            status,
+            lastSubmitted: sitemap.lastSubmitted,
+            lastDownloaded: sitemap.lastDownloaded,
+            isPending: Boolean(sitemap.isPending),
+            isSitemapsIndex: Boolean(sitemap.isSitemapsIndex),
+            type: sitemap.type,
+            warnings: warningCount,
+            errors: errorCount,
+            contents: sitemap.contents || [],
+            totals: {
+              submitted,
+              indexed,
+              indexRate: submitted > 0 ? roundMetric(indexed / submitted * 100) : null
+            }
+          };
+        });
+        const totals = {
+          sitemaps: sitemaps.length,
+          healthy: sitemaps.filter((sitemap) => sitemap.status === "healthy").length,
+          pending: sitemaps.filter((sitemap) => sitemap.status === "pending").length,
+          warnings: sitemaps.reduce((sum, sitemap) => sum + sitemap.warnings, 0),
+          errors: sitemaps.reduce((sum, sitemap) => sum + sitemap.errors, 0),
+          sitemapIndexes: sitemaps.filter((sitemap) => sitemap.isSitemapsIndex).length,
+          submitted: sitemaps.reduce((sum, sitemap) => sum + sitemap.totals.submitted, 0),
+          indexed: sitemaps.reduce((sum, sitemap) => sum + sitemap.totals.indexed, 0)
+        };
+        const overallStatus = totals.errors > 0 ? "error" : totals.pending > 0 ? "pending" : totals.warnings > 0 ? "warning" : "healthy";
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          overallStatus,
+          totals: {
+            ...totals,
+            indexRate: totals.submitted > 0 ? roundMetric(totals.indexed / totals.submitted * 100) : null
+          },
+          sitemaps,
+          warnings: sitemaps.length === 0 ? ["No submitted sitemaps returned for this property."] : []
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_compare_search_types",
+    "Compare performance across Search Console search types: web, image, video, news, discover, and Google News.",
+    {
+      siteUrl: siteUrlSchema,
+      searchTypes: z2.array(searchTypeSchema).optional().default(["web", "image", "video", "discover"]),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      dateRange: z2.object({ startDate: z2.string(), endDate: z2.string() }).optional()
+    },
+    async ({ siteUrl, searchTypes, datePreset, dateRange }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const resolvedDateRange = dateRange || resolveDatePreset(datePreset);
+        const client = await clientFactory.get();
+        const data = await Promise.all(
+          searchTypes.map(async (type) => {
+            try {
+              const response = await client.querySearchAnalytics(resolvedSiteUrl, {
+                startDate: resolvedDateRange.startDate,
+                endDate: resolvedDateRange.endDate,
+                type,
+                dataState: "all"
+              });
+              const rows = response.rows || [];
+              const clicks = rows.reduce((sum, row) => sum + row.clicks, 0);
+              const impressions = rows.reduce((sum, row) => sum + row.impressions, 0);
+              const weightedPosition = rows.reduce((sum, row) => sum + row.position * row.impressions, 0);
+              return {
+                searchType: type,
+                clicks,
+                impressions,
+                ctr: impressions > 0 ? Math.round(clicks / impressions * 1e4) / 100 : 0,
+                position: impressions > 0 ? Math.round(weightedPosition / impressions * 100) / 100 : 0
+              };
+            } catch (error) {
+              return {
+                searchType: type,
+                clicks: 0,
+                impressions: 0,
+                ctr: 0,
+                position: 0,
+                error: error instanceof Error ? error.message : "No data available"
+              };
+            }
+          })
+        );
+        return ok({ data, rowCount: data.length });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_get_data_freshness",
+    "Detect the most recent date with Search Analytics data by querying recent daily rows.",
+    {
+      siteUrl: siteUrlSchema,
+      searchType: searchTypeSchema.optional().default("web"),
+      lookbackDays: z2.number().int().min(3).max(30).optional().default(14).describe("Recent days to scan for daily data. Max 30.")
+    },
+    async ({ siteUrl, searchType, lookbackDays }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const end = todayUtc();
+        const dateRange = {
+          startDate: formatDate(addUtcDays(end, -(lookbackDays - 1))),
+          endDate: formatDate(end)
+        };
+        const validation = validateGSCQuerySelection(["date"], searchType, dateRange);
+        if (validation.errors.length > 0) {
+          return ok({ error: "Query validation failed", errors: validation.errors, warnings: validation.warnings });
+        }
+        const client = await clientFactory.get();
+        const response = await client.querySearchAnalytics(resolvedSiteUrl, {
+          startDate: dateRange.startDate,
+          endDate: dateRange.endDate,
+          dimensions: ["date"],
+          type: searchType,
+          dataState: "all",
+          rowLimit: lookbackDays
+        });
+        const rows = (response.rows || []).filter((row) => row.keys?.[0]).sort((a, b) => String(a.keys?.[0]).localeCompare(String(b.keys?.[0])));
+        const rowsWithData = rows.filter((row) => row.clicks > 0 || row.impressions > 0);
+        const latestRow = rowsWithData[rowsWithData.length - 1];
+        const latestDataDate = latestRow?.keys?.[0] ?? null;
+        const dataLagDays = latestDataDate ? daysBetween(latestDataDate, end) : null;
+        const warnings = [...validation.warnings];
+        if (!latestDataDate) {
+          warnings.push(`No daily rows with clicks or impressions were found in the last ${lookbackDays} days.`);
+        } else if (dataLagDays !== null && dataLagDays > 3) {
+          warnings.push(`Latest visible data is ${dataLagDays} days old; GSC normally lags by about 2-3 days.`);
+        }
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          searchType,
+          checkedRange: dateRange,
+          latestDataDate,
+          dataLagDays,
+          hasRecentData: dataLagDays !== null && dataLagDays <= 3,
+          rowCount: rows.length,
+          dailyRows: rows.map((row) => ({
+            date: row.keys?.[0],
+            ...rowMetrics(row)
+          })),
+          warnings
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_monitor_indexation_freshness",
+    "Read-only monitoring snapshot for Search Analytics freshness, sitemap indexation totals, and an optional small URL Inspection sample.",
+    {
+      siteUrl: siteUrlSchema,
+      searchTypes: z2.array(searchTypeSchema).min(1).max(6).optional().default(["web"]),
+      lookbackDays: z2.number().int().min(3).max(30).optional().default(14).describe("Recent days to scan for Search Analytics freshness."),
+      freshnessLagWarningDays: z2.number().int().min(1).max(14).optional().default(DEFAULT_FRESHNESS_LAG_WARNING_DAYS).describe("Maximum acceptable lag in days before freshness is marked delayed/stale."),
+      inspectUrls: z2.array(z2.string().url()).max(BULK_URL_INSPECTION_LIMIT).optional().default([]).describe(`Optional URLs to inspect. Maximum ${BULK_URL_INSPECTION_LIMIT} to protect URL Inspection quota.`),
+      languageCode: z2.string().optional().describe("Optional IETF language tag for URL Inspection, e.g. en-US or fr-FR.")
+    },
+    async ({ siteUrl, searchTypes, lookbackDays, freshnessLagWarningDays, inspectUrls, languageCode }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const client = await clientFactory.get();
+        const end = todayUtc();
+        const checkedRange = {
+          startDate: formatDate(addUtcDays(end, -(lookbackDays - 1))),
+          endDate: formatDate(end)
+        };
+        const uniqueSearchTypes = uniqueValues(searchTypes);
+        const sitemapPromise = client.listSitemaps(resolvedSiteUrl);
+        const freshnessPromise = Promise.all(uniqueSearchTypes.map(async (type) => {
+          const validation = validateGSCQuerySelection(["date"], type, checkedRange);
+          if (validation.errors.length > 0) {
+            return {
+              searchType: type,
+              checkedRange,
+              status: "error",
+              errors: validation.errors,
+              warnings: validation.warnings
+            };
+          }
+          try {
+            const response = await client.querySearchAnalytics(resolvedSiteUrl, {
+              startDate: checkedRange.startDate,
+              endDate: checkedRange.endDate,
+              dimensions: ["date"],
+              type,
+              dataState: "all",
+              rowLimit: lookbackDays
+            });
+            const analysis = analyzeDailyFreshness(response.rows || [], end, freshnessLagWarningDays);
+            const warnings = [...validation.warnings];
+            if (analysis.status === "noData") {
+              warnings.push(`No ${type} daily rows with clicks or impressions were found in the last ${lookbackDays} days.`);
+            } else if (analysis.status === "stale" || analysis.status === "delayed") {
+              warnings.push(`Latest ${type} data is ${analysis.dataLagDays} days old; threshold is ${freshnessLagWarningDays} day(s).`);
+            }
+            return {
+              searchType: type,
+              checkedRange,
+              ...analysis,
+              warnings
+            };
+          } catch (error) {
+            return {
+              searchType: type,
+              checkedRange,
+              status: "error",
+              error: normalizePerUrlError(error)
+            };
+          }
+        }));
+        const [sitemapResult, freshness] = await Promise.all([sitemapPromise, freshnessPromise]);
+        const sitemapSummaries = (sitemapResult.sitemap || []).map(summarizeSitemapForP2);
+        const sitemapTotals = summarizeSitemapCollection(sitemapSummaries);
+        const urlsToInspect = dedupeUrlList(inspectUrls, BULK_URL_INSPECTION_LIMIT);
+        const inspections = [];
+        let inspectionAlertCount = 0;
+        for (const url of urlsToInspect) {
+          try {
+            const response = await client.inspectUrl(url, resolvedSiteUrl, languageCode);
+            const normalized = normalizeInspectionResult(url, response);
+            const assessment = assessInspectionResult(normalized);
+            if (assessment.status === "alert") inspectionAlertCount += 1;
+            inspections.push({ ok: true, ...normalized, assessment });
+          } catch (error) {
+            inspectionAlertCount += 1;
+            inspections.push({ ok: false, url, ...normalizePerUrlError(error) });
+          }
+        }
+        const freshnessAlertCount = freshness.filter((item) => ["noData", "stale", "error"].includes(String(item.status))).length;
+        const sitemapAlertCount = sitemapTotals.statusCounts.error + sitemapTotals.statusCounts.pending;
+        const overallStatus = freshnessAlertCount > 0 || sitemapAlertCount > 0 || inspectionAlertCount > 0 ? "attention" : sitemapTotals.statusCounts.warning > 0 ? "warning" : "ok";
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          overallStatus,
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          freshness,
+          sitemapIndexation: {
+            totals: sitemapTotals,
+            atRiskSitemaps: sitemapSummaries.filter((sitemap) => sitemap.status !== "healthy").sort((a, b) => b.errors - a.errors || b.warnings - a.warnings).slice(0, 25)
+          },
+          optionalUrlInspectionSample: {
+            requestedCount: inspectUrls.length,
+            inspectedCount: inspections.length,
+            skippedDuplicates: inspectUrls.length - urlsToInspect.length,
+            dailyQuotaNote: `${URL_INSPECTION_DAILY_QUOTA} requests/day/property; this monitor caps optional samples at ${BULK_URL_INSPECTION_LIMIT} URLs.`,
+            results: inspections
+          }
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_track_sitemap_deltas",
+    "Read-only sitemap delta tracker. Fetches the current sitemap snapshot and compares it to an agent-provided baseline; no state is written.",
+    {
+      siteUrl: siteUrlSchema,
+      baseline: z2.array(sitemapBaselineSchema).optional().default([]).describe("Previous snapshot entries from this tool's snapshot output."),
+      includeUnchanged: z2.boolean().optional().default(false),
+      minAbsIndexedDelta: z2.number().int().min(0).optional().default(1).describe("Minimum absolute indexed URL delta to include otherwise unchanged sitemaps.")
+    },
+    async ({ siteUrl, baseline, includeUnchanged, minAbsIndexedDelta }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const client = await clientFactory.get();
+        const result = await client.listSitemaps(resolvedSiteUrl);
+        const current = (result.sitemap || []).map(summarizeSitemapForP2);
+        const currentSnapshot = current.map(sitemapSnapshot);
+        const baselineMap = new Map(baseline.map((entry) => [entry.path, entry]));
+        const currentPaths = new Set(current.map((sitemap) => sitemap.path));
+        const changes = [];
+        for (const sitemap of current) {
+          const previous = baselineMap.get(sitemap.path);
+          if (!previous) {
+            changes.push({
+              path: sitemap.path,
+              changeType: "new",
+              current: sitemapSnapshot(sitemap),
+              previous: null,
+              delta: {
+                submitted: sitemap.totals.submitted,
+                indexed: sitemap.totals.indexed,
+                warnings: sitemap.warnings,
+                errors: sitemap.errors
+              }
+            });
+            continue;
+          }
+          const currentEntry = sitemapSnapshot(sitemap);
+          const delta = {
+            submitted: currentEntry.submitted - previous.submitted,
+            indexed: currentEntry.indexed - previous.indexed,
+            warnings: currentEntry.warnings - previous.warnings,
+            errors: currentEntry.errors - previous.errors
+          };
+          const dateChanged = currentEntry.lastSubmitted !== previous.lastSubmitted || currentEntry.lastDownloaded !== previous.lastDownloaded;
+          const changed = dateChanged || Math.abs(delta.indexed) >= minAbsIndexedDelta || delta.submitted !== 0 || delta.warnings !== 0 || delta.errors !== 0;
+          if (includeUnchanged || changed) {
+            changes.push({
+              path: sitemap.path,
+              changeType: changed ? "changed" : "unchanged",
+              current: currentEntry,
+              previous,
+              delta,
+              dateChanged
+            });
+          }
+        }
+        for (const previous of baseline) {
+          if (currentPaths.has(previous.path)) continue;
+          changes.push({
+            path: previous.path,
+            changeType: "missing",
+            current: null,
+            previous,
+            delta: {
+              submitted: -previous.submitted,
+              indexed: -previous.indexed,
+              warnings: -previous.warnings,
+              errors: -previous.errors
+            }
+          });
+        }
+        const totals = summarizeSitemapCollection(current);
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          baselineCount: baseline.length,
+          currentCount: current.length,
+          totals,
+          changeSummary: {
+            new: changes.filter((change) => change.changeType === "new").length,
+            changed: changes.filter((change) => change.changeType === "changed").length,
+            missing: changes.filter((change) => change.changeType === "missing").length,
+            unchangedIncluded: changes.filter((change) => change.changeType === "unchanged").length
+          },
+          changes,
+          snapshot: currentSnapshot,
+          usage: "Persist snapshot in the calling agent/workflow if you want the next read-only delta comparison."
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_analyze_search_appearance_trends",
+    "Analyze structured data and rich-result trend signals via the Search Analytics searchAppearance dimension when GSC exposes it.",
+    {
+      siteUrl: siteUrlSchema,
+      searchType: searchTypeSchema.optional().default("web"),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      currentDateRange: dateRangeSchema.optional().describe("Current period. Defaults to datePreset."),
+      previousDateRange: dateRangeSchema.optional().describe("Previous period. Defaults to the immediately preceding period with the same length."),
+      includePages: z2.boolean().optional().default(false).describe("When true, groups by searchAppearance + page for page-level rich result trends."),
+      limit: z2.number().int().min(1).max(25e3).optional().default(5e3),
+      topN: z2.number().int().min(1).max(100).optional().default(50),
+      minImpressions: z2.number().int().min(0).optional().default(0),
+      sortBy: z2.enum(["currentClicks", "currentImpressions", "clicksDelta", "impressionsDelta", "positionDelta"]).optional().default("impressionsDelta")
+    },
+    async ({ siteUrl, searchType, datePreset, currentDateRange, previousDateRange, includePages, limit, topN, minImpressions, sortBy }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const currentRange = currentDateRange || resolveDatePreset(datePreset);
+        const previousRange = previousDateRange || derivePreviousDateRange(currentRange);
+        validateDateRange(currentRange);
+        validateDateRange(previousRange);
+        const dimensions = includePages ? ["searchAppearance", "page"] : ["searchAppearance"];
+        const validation = validateGSCQuerySelection(dimensions, searchType, currentRange);
+        if (validation.errors.length > 0) {
+          return ok({ error: "Query validation failed", errors: validation.errors, warnings: validation.warnings });
+        }
+        const client = await clientFactory.get();
+        const buildRequest = (dateRange) => ({
+          startDate: dateRange.startDate,
+          endDate: dateRange.endDate,
+          dimensions,
+          type: searchType,
+          dataState: "all",
+          rowLimit: limit
+        });
+        const [currentResponse, previousResponse] = await Promise.all([
+          client.querySearchAnalytics(resolvedSiteUrl, buildRequest(currentRange)),
+          client.querySearchAnalytics(resolvedSiteUrl, buildRequest(previousRange))
+        ]);
+        const currentRows = currentResponse.rows || [];
+        const previousRows = previousResponse.rows || [];
+        const currentByKey = new Map(currentRows.map((row) => [rowCompositeKey(row, dimensions.length), row]));
+        const previousByKey = new Map(previousRows.map((row) => [rowCompositeKey(row, dimensions.length), row]));
+        const allKeys = uniqueValues([...currentByKey.keys(), ...previousByKey.keys()]);
+        const warnings = [...validation.warnings];
+        if (currentRows.length === 0 && previousRows.length === 0) {
+          warnings.push("No searchAppearance rows were returned. This property/search type/date range may not expose structured data or rich-result appearance data.");
+        }
+        if (currentRows.length === limit || previousRows.length === limit) {
+          warnings.push("At least one period reached the row limit; lower-volume search appearance rows may be omitted.");
+        }
+        const trends = allKeys.map((key) => {
+          const keys = JSON.parse(key);
+          const current = rowMetrics(currentByKey.get(key));
+          const previous = rowMetrics(previousByKey.get(key));
+          const clicksDelta = current.clicks - previous.clicks;
+          const impressionsDelta = current.impressions - previous.impressions;
+          const ctrDelta = roundMetric(current.ctr - previous.ctr);
+          const positionDelta = current.position !== null && previous.position !== null ? roundMetric(current.position - previous.position) : null;
+          return {
+            searchAppearance: keys[0] ?? "unknown",
+            page: includePages ? keys[1] ?? null : void 0,
+            current,
+            previous,
+            delta: {
+              clicks: clicksDelta,
+              impressions: impressionsDelta,
+              ctr: ctrDelta,
+              position: positionDelta,
+              positionDirection: positionDelta === null ? "unknown" : positionDelta < 0 ? "improved" : positionDelta > 0 ? "declined" : "unchanged"
+            },
+            changePercent: {
+              clicks: percentageChange(current.clicks, previous.clicks),
+              impressions: percentageChange(current.impressions, previous.impressions)
+            }
+          };
+        }).filter((row) => row.current.impressions >= minImpressions || row.previous.impressions >= minImpressions);
+        const sortTrendRows = (rows) => rows.sort((a, b) => {
+          switch (sortBy) {
+            case "currentClicks":
+              return b.current.clicks - a.current.clicks;
+            case "currentImpressions":
+              return b.current.impressions - a.current.impressions;
+            case "clicksDelta":
+              return Math.abs(b.delta.clicks) - Math.abs(a.delta.clicks);
+            case "positionDelta":
+              return Math.abs(b.delta.position ?? 0) - Math.abs(a.delta.position ?? 0);
+            case "impressionsDelta":
+            default:
+              return Math.abs(b.delta.impressions) - Math.abs(a.delta.impressions);
+          }
+        });
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          searchType,
+          dimensions,
+          currentRange,
+          previousRange,
+          fetchedRows: {
+            current: currentRows.length,
+            previous: previousRows.length
+          },
+          totals: {
+            current: summarizeRows(currentRows),
+            previous: summarizeRows(previousRows)
+          },
+          trends: sortTrendRows(trends).slice(0, topN),
+          warnings
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_plan_large_site_sampling",
+    "Build a read-only URL Inspection sampling plan for large sites from sitemap risk signals and Search Analytics page performance.",
+    {
+      siteUrl: siteUrlSchema,
+      searchType: searchTypeSchema.optional().default("web"),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      dateRange: dateRangeSchema.optional(),
+      objectives: z2.array(samplingObjectiveSchema).min(1).max(5).optional().default(["topTraffic", "lowCtr", "declining", "sitemapRisk", "staleSitemaps"]),
+      pageLimit: z2.number().int().min(1).max(25e3).optional().default(5e3),
+      maxInspectionUrls: z2.number().int().min(1).max(BULK_URL_INSPECTION_LIMIT).optional().default(BULK_URL_INSPECTION_LIMIT),
+      minImpressionsForLowCtr: z2.number().int().min(1).optional().default(100),
+      staleSitemapDays: z2.number().int().min(1).max(180).optional().default(14)
+    },
+    async ({ siteUrl, searchType, datePreset, dateRange, objectives, pageLimit, maxInspectionUrls, minImpressionsForLowCtr, staleSitemapDays }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const resolvedDateRange = dateRange || resolveDatePreset(datePreset);
+        const previousRange = derivePreviousDateRange(resolvedDateRange);
+        validateDateRange(resolvedDateRange);
+        const validation = validateGSCQuerySelection(["page"], searchType, resolvedDateRange);
+        if (validation.errors.length > 0) {
+          return ok({ error: "Query validation failed", errors: validation.errors, warnings: validation.warnings });
+        }
+        const client = await clientFactory.get();
+        const [sitemapResult, currentResponse, previousResponse] = await Promise.all([
+          client.listSitemaps(resolvedSiteUrl),
+          client.querySearchAnalytics(resolvedSiteUrl, {
+            startDate: resolvedDateRange.startDate,
+            endDate: resolvedDateRange.endDate,
+            dimensions: ["page"],
+            type: searchType,
+            dataState: "all",
+            rowLimit: pageLimit
+          }),
+          client.querySearchAnalytics(resolvedSiteUrl, {
+            startDate: previousRange.startDate,
+            endDate: previousRange.endDate,
+            dimensions: ["page"],
+            type: searchType,
+            dataState: "all",
+            rowLimit: pageLimit
+          })
+        ]);
+        const sitemapSummaries = (sitemapResult.sitemap || []).map(summarizeSitemapForP2);
+        const previousByPage = keyRowsByDimension(previousResponse.rows || []);
+        const pageRows = (currentResponse.rows || []).flatMap((row) => {
+          const page = row.keys?.[0];
+          if (!page) return [];
+          const previous = page ? rowMetrics(previousByPage.get(page)) : rowMetrics(void 0);
+          const current = rowMetrics(row);
+          return [{
+            page,
+            current,
+            previous,
+            delta: {
+              clicks: current.clicks - previous.clicks,
+              impressions: current.impressions - previous.impressions,
+              ctr: roundMetric(current.ctr - previous.ctr),
+              position: current.position !== null && previous.position !== null ? roundMetric(current.position - previous.position) : null
+            }
+          }];
+        });
+        const selectedObjectives = objectives;
+        const buckets = [];
+        const addBucket = (objective, rationale, candidateUrls, sitemapPaths = []) => {
+          if (!selectedObjectives.includes(objective)) return;
+          buckets.push({
+            objective,
+            rationale,
+            candidateUrls: dedupeUrlList(candidateUrls, maxInspectionUrls),
+            sitemapPaths
+          });
+        };
+        addBucket(
+          "topTraffic",
+          "Protect the pages carrying the most organic clicks.",
+          pageRows.slice().sort((a, b) => b.current.clicks - a.current.clicks || b.current.impressions - a.current.impressions).map((row) => row.page)
+        );
+        addBucket(
+          "lowCtr",
+          "Sample high-impression pages with weak CTR that may have snippet or rich-result problems.",
+          pageRows.filter((row) => row.current.impressions >= minImpressionsForLowCtr).sort((a, b) => a.current.ctr - b.current.ctr || b.current.impressions - a.current.impressions).map((row) => row.page)
+        );
+        addBucket(
+          "declining",
+          "Sample pages with the largest click losses versus the previous equivalent period.",
+          pageRows.filter((row) => row.delta.clicks < 0 || row.delta.impressions < 0).sort((a, b) => a.delta.clicks - b.delta.clicks || a.delta.impressions - b.delta.impressions).map((row) => row.page)
+        );
+        addBucket(
+          "sitemapRisk",
+          "Inspect representative URLs from sitemaps that currently report errors, warnings, pending status, or low index rates.",
+          [],
+          sitemapSummaries.filter((sitemap) => sitemap.status !== "healthy" || sitemap.totals.indexRate !== null && sitemap.totals.indexRate < 90).sort((a, b) => b.errors - a.errors || b.warnings - a.warnings || (a.totals.indexRate ?? 100) - (b.totals.indexRate ?? 100)).map((sitemap) => sitemap.path).slice(0, 25)
+        );
+        addBucket(
+          "staleSitemaps",
+          `Inspect representative URLs from sitemaps not downloaded in the last ${staleSitemapDays} day(s).`,
+          [],
+          sitemapSummaries.filter((sitemap) => {
+            const daysSinceDownload = safeDaysBetweenDatePrefix(sitemap.lastDownloaded, todayUtc());
+            return daysSinceDownload === null || daysSinceDownload > staleSitemapDays;
+          }).map((sitemap) => sitemap.path).slice(0, 25)
+        );
+        const recommendedInspectionUrls = dedupeUrlList(
+          buckets.flatMap((bucket) => bucket.candidateUrls),
+          maxInspectionUrls
+        );
+        const warnings = [...validation.warnings];
+        if ((currentResponse.rows || []).length === pageLimit) {
+          warnings.push("The page query reached pageLimit; sampling is based on the highest-returned Search Analytics rows.");
+        }
+        if (buckets.some((bucket) => bucket.sitemapPaths.length > 0 && bucket.candidateUrls.length === 0)) {
+          warnings.push("Sitemaps API exposes sitemap paths and counts, not child URLs. Use these sitemap paths to choose representative URLs from your own sitemap inventory before calling URL Inspection.");
+        }
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          searchType,
+          dateRange: resolvedDateRange,
+          previousRange,
+          pageRowsAnalyzed: pageRows.length,
+          sitemapTotals: summarizeSitemapCollection(sitemapSummaries),
+          inspectionBudget: {
+            dailyQuota: URL_INSPECTION_DAILY_QUOTA,
+            maxPerToolCall: BULK_URL_INSPECTION_LIMIT,
+            recommendedNow: recommendedInspectionUrls.length
+          },
+          recommendedInspectionUrls,
+          samplingBuckets: buckets,
+          warnings
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_indexation_watchlist",
+    "Read-only URL Inspection watchlist for critical URLs. Inspects up to 10 URLs and returns alert/review/ok assessments without storing state.",
+    {
+      siteUrl: siteUrlSchema,
+      urls: z2.array(watchlistUrlSchema).min(1).max(BULK_URL_INSPECTION_LIMIT).describe(`Watchlist entries. Maximum ${BULK_URL_INSPECTION_LIMIT} per call to protect URL Inspection quota.`),
+      languageCode: z2.string().optional().describe("Optional IETF language tag, e.g. en-US or fr-FR."),
+      continueOnError: z2.boolean().optional().default(true)
+    },
+    async ({ siteUrl, urls, languageCode, continueOnError }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const client = await clientFactory.get();
+        const dedupedWatchlist = [];
+        const seenUrls = /* @__PURE__ */ new Set();
+        for (const entry of urls) {
+          if (seenUrls.has(entry.url)) continue;
+          seenUrls.add(entry.url);
+          dedupedWatchlist.push(entry);
+        }
+        const results = [];
+        const summary = { ok: 0, review: 0, alert: 0, failed: 0 };
+        for (const entry of dedupedWatchlist) {
+          try {
+            const response = await client.inspectUrl(entry.url, resolvedSiteUrl, languageCode);
+            const normalized = normalizeInspectionResult(entry.url, response);
+            const assessment = assessInspectionResult(normalized, entry);
+            summary[assessment.status] += 1;
+            results.push({
+              ok: true,
+              label: entry.label,
+              tags: entry.tags,
+              expected: {
+                verdict: entry.expectedVerdict,
+                canonical: entry.expectedCanonical,
+                coverageState: entry.expectedCoverageState
+              },
+              ...normalized,
+              assessment
+            });
+          } catch (error) {
+            summary.failed += 1;
+            if (!continueOnError) throw error;
+            results.push({ ok: false, url: entry.url, label: entry.label, priority: entry.priority, tags: entry.tags, ...normalizePerUrlError(error) });
+          }
+        }
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          inspectedCount: results.length,
+          skippedDuplicates: urls.length - dedupedWatchlist.length,
+          summary,
+          quota: {
+            dailyQuota: URL_INSPECTION_DAILY_QUOTA,
+            maxPerToolCall: BULK_URL_INSPECTION_LIMIT,
+            note: "URL Inspection is read-only but quota-limited; run watchlists in small batches."
+          },
+          results
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_find_losses_gains",
+    "Compare two periods for query or page performance and return click/impression/CTR/position deltas.",
+    {
+      siteUrl: siteUrlSchema,
+      dimension: comparisonDimensionSchema.optional().default("query"),
+      searchType: searchTypeSchema.optional().default("web"),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      currentDateRange: dateRangeSchema.optional().describe("Current period. Defaults to datePreset."),
+      previousDateRange: dateRangeSchema.optional().describe("Previous period. Defaults to the immediately preceding period with the same length."),
+      limit: z2.number().int().min(1).max(25e3).optional().default(5e3).describe("Rows to fetch for each period."),
+      topN: z2.number().int().min(1).max(100).optional().default(25),
+      minAbsClickDelta: z2.number().min(0).optional().default(0).describe("Filter out rows with smaller absolute click delta."),
+      sortBy: z2.enum(["clicksDelta", "impressionsDelta", "ctrDelta", "positionDelta"]).optional().default("clicksDelta")
+    },
+    async ({ siteUrl, dimension, searchType, datePreset, currentDateRange, previousDateRange, limit, topN, minAbsClickDelta, sortBy }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const currentRange = currentDateRange || resolveDatePreset(datePreset);
+        const previousRange = previousDateRange || derivePreviousDateRange(currentRange);
+        validateDateRange(currentRange);
+        validateDateRange(previousRange);
+        const validation = validateGSCQuerySelection([dimension], searchType, currentRange);
+        if (validation.errors.length > 0) {
+          return ok({ error: "Query validation failed", errors: validation.errors, warnings: validation.warnings });
+        }
+        const client = await clientFactory.get();
+        const buildRequest = (dateRange) => ({
+          startDate: dateRange.startDate,
+          endDate: dateRange.endDate,
+          dimensions: [dimension],
+          type: searchType,
+          dataState: "all",
+          rowLimit: limit
+        });
+        const [currentResponse, previousResponse] = await Promise.all([
+          client.querySearchAnalytics(resolvedSiteUrl, buildRequest(currentRange)),
+          client.querySearchAnalytics(resolvedSiteUrl, buildRequest(previousRange))
+        ]);
+        const currentRows = currentResponse.rows || [];
+        const previousRows = previousResponse.rows || [];
+        const currentByKey = keyRowsByDimension(currentRows);
+        const previousByKey = keyRowsByDimension(previousRows);
+        const allKeys = uniqueValues([...currentByKey.keys(), ...previousByKey.keys()]);
+        const deltas = allKeys.map((key) => {
+          const current = rowMetrics(currentByKey.get(key));
+          const previous = rowMetrics(previousByKey.get(key));
+          const clicksDelta = current.clicks - previous.clicks;
+          const impressionsDelta = current.impressions - previous.impressions;
+          const ctrDelta = roundMetric(current.ctr - previous.ctr);
+          const positionDelta = current.position !== null && previous.position !== null ? roundMetric(current.position - previous.position) : null;
+          return {
+            entity: { type: dimension, value: key },
+            current,
+            previous,
+            delta: {
+              clicks: clicksDelta,
+              impressions: impressionsDelta,
+              ctr: ctrDelta,
+              position: positionDelta,
+              positionDirection: positionDelta === null ? "unknown" : positionDelta < 0 ? "improved" : positionDelta > 0 ? "declined" : "unchanged"
+            },
+            changePercent: {
+              clicks: percentageChange(current.clicks, previous.clicks),
+              impressions: percentageChange(current.impressions, previous.impressions)
+            }
+          };
+        }).filter((row) => Math.abs(row.delta.clicks) >= minAbsClickDelta);
+        const getSortValue = (row) => {
+          switch (sortBy) {
+            case "clicksDelta":
+              return row.delta.clicks;
+            case "impressionsDelta":
+              return row.delta.impressions;
+            case "ctrDelta":
+              return row.delta.ctr;
+            case "positionDelta":
+              return row.delta.position ?? 0;
+            default:
+              return row.delta.clicks;
+          }
+        };
+        const sortDeltaRows = (rows, direction) => rows.sort((a, b) => {
+          const aValue = getSortValue(a);
+          const bValue = getSortValue(b);
+          if (sortBy === "positionDelta") {
+            return direction === "gain" ? aValue - bValue : bValue - aValue;
+          }
+          return direction === "gain" ? Number(bValue) - Number(aValue) : Number(aValue) - Number(bValue);
+        });
+        const gains = sortDeltaRows(
+          deltas.filter((row) => row.delta.clicks > 0 || row.delta.impressions > 0),
+          "gain"
+        ).slice(0, topN);
+        const losses = sortDeltaRows(
+          deltas.filter((row) => row.delta.clicks < 0 || row.delta.impressions < 0),
+          "loss"
+        ).slice(0, topN);
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          dimension,
+          searchType,
+          currentRange,
+          previousRange,
+          fetchedRows: {
+            current: currentRows.length,
+            previous: previousRows.length
+          },
+          totals: {
+            current: summarizeRows(currentRows),
+            previous: summarizeRows(previousRows)
+          },
+          gains,
+          losses,
+          warnings: validation.warnings
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_cluster_queries",
+    "Cluster Search Console queries by simple tokens and intent signals: brand/non-brand, question, category, and topic tokens.",
+    {
+      siteUrl: siteUrlSchema,
+      searchType: searchTypeSchema.optional().default("web"),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      dateRange: dateRangeSchema.optional(),
+      brandTerms: z2.array(z2.string()).optional().default([]).describe("Optional brand terms. Defaults to terms derived from the property domain."),
+      categoryRules: z2.record(z2.array(z2.string())).optional().describe("Optional map of category name to matching tokens/phrases."),
+      limit: z2.number().int().min(1).max(25e3).optional().default(5e3),
+      maxClusters: z2.number().int().min(1).max(100).optional().default(25),
+      topQueriesPerCluster: z2.number().int().min(1).max(25).optional().default(10)
+    },
+    async ({ siteUrl, searchType, datePreset, dateRange, brandTerms, categoryRules, limit, maxClusters, topQueriesPerCluster }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const resolvedDateRange = dateRange || resolveDatePreset(datePreset);
+        validateDateRange(resolvedDateRange);
+        const validation = validateGSCQuerySelection(["query"], searchType, resolvedDateRange);
+        if (validation.errors.length > 0) {
+          return ok({ error: "Query validation failed", errors: validation.errors, warnings: validation.warnings });
+        }
+        const client = await clientFactory.get();
+        const response = await client.querySearchAnalytics(resolvedSiteUrl, {
+          startDate: resolvedDateRange.startDate,
+          endDate: resolvedDateRange.endDate,
+          dimensions: ["query"],
+          type: searchType,
+          dataState: "all",
+          rowLimit: limit
+        });
+        const rows = response.rows || [];
+        const resolvedBrandTerms = expandBrandTerms(brandTerms.length > 0 ? brandTerms : deriveBrandTerms(resolvedSiteUrl));
+        const brandClusters = /* @__PURE__ */ new Map();
+        const questionClusters = /* @__PURE__ */ new Map();
+        const intentClusters = /* @__PURE__ */ new Map();
+        const categoryClusters = /* @__PURE__ */ new Map();
+        const tokenClusters = /* @__PURE__ */ new Map();
+        const warnings = [...validation.warnings];
+        if (resolvedBrandTerms.length === 0) {
+          warnings.push("No brand terms were provided or derived; all queries may be classified as nonBrand.");
+        }
+        if (rows.length === limit) {
+          warnings.push("The response reached the row limit; lower-volume queries may be missing from clusters.");
+        }
+        for (const row of rows) {
+          const query = row.keys?.[0];
+          if (!query) continue;
+          const tokens = tokenizeQuery(query);
+          const classification = classifyQuery(query, tokens, resolvedBrandTerms);
+          const category = resolveQueryCategory(query, tokens, categoryRules);
+          addQueryToBucket(getOrCreateBucket(brandClusters, classification.brand), query, row);
+          addQueryToBucket(getOrCreateBucket(questionClusters, classification.question), query, row);
+          addQueryToBucket(getOrCreateBucket(intentClusters, classification.intent), query, row);
+          addQueryToBucket(getOrCreateBucket(categoryClusters, category), query, row);
+          for (const token of tokens) {
+            addQueryToBucket(getOrCreateBucket(tokenClusters, token), query, row);
+          }
+        }
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          searchType,
+          dateRange: resolvedDateRange,
+          rowCount: rows.length,
+          brandTerms: resolvedBrandTerms,
+          totals: summarizeRows(rows),
+          clusters: {
+            brand: finalizeBuckets(brandClusters, topQueriesPerCluster),
+            question: finalizeBuckets(questionClusters, topQueriesPerCluster),
+            intent: finalizeBuckets(intentClusters, topQueriesPerCluster),
+            category: finalizeBuckets(categoryClusters, topQueriesPerCluster).slice(0, maxClusters),
+            tokens: finalizeBuckets(tokenClusters, topQueriesPerCluster).slice(0, maxClusters)
+          },
+          warnings
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_detect_cannibalization",
+    "Detect queries where multiple pages compete for clicks/impressions in Search Analytics query-page rows.",
+    {
+      siteUrl: siteUrlSchema,
+      searchType: searchTypeSchema.optional().default("web"),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      dateRange: dateRangeSchema.optional(),
+      limit: z2.number().int().min(1).max(25e3).optional().default(5e3),
+      minPages: z2.number().int().min(2).max(10).optional().default(2),
+      minImpressions: z2.number().int().min(0).optional().default(100),
+      maxTopPageClickShare: z2.number().min(0.1).max(0.99).optional().default(0.8).describe("Only flag queries where the top page owns less than or equal to this click share."),
+      topN: z2.number().int().min(1).max(100).optional().default(25)
+    },
+    async ({ siteUrl, searchType, datePreset, dateRange, limit, minPages, minImpressions, maxTopPageClickShare, topN }) => {
+      try {
+        const resolvedSiteUrl = resolveSiteUrl(siteUrl, config);
+        const resolvedDateRange = dateRange || resolveDatePreset(datePreset);
+        validateDateRange(resolvedDateRange);
+        const validation = validateGSCQuerySelection(["query", "page"], searchType, resolvedDateRange);
+        if (validation.errors.length > 0) {
+          return ok({ error: "Query validation failed", errors: validation.errors, warnings: validation.warnings });
+        }
+        const client = await clientFactory.get();
+        const response = await client.querySearchAnalytics(resolvedSiteUrl, {
+          startDate: resolvedDateRange.startDate,
+          endDate: resolvedDateRange.endDate,
+          dimensions: ["query", "page"],
+          type: searchType,
+          dataState: "all",
+          rowLimit: limit
+        });
+        const rows = response.rows || [];
+        const grouped = /* @__PURE__ */ new Map();
+        const warnings = [...validation.warnings];
+        if (rows.length === limit) {
+          warnings.push("The query-page response reached the row limit; cannibalization candidates may be incomplete.");
+        }
+        for (const row of rows) {
+          const query = row.keys?.[0];
+          const page = row.keys?.[1];
+          if (!query || !page) continue;
+          const pageMap = grouped.get(query) || /* @__PURE__ */ new Map();
+          const pageStats = pageMap.get(page) || { page, clicks: 0, impressions: 0, weightedPosition: 0 };
+          pageStats.clicks += row.clicks;
+          pageStats.impressions += row.impressions;
+          pageStats.weightedPosition += row.position * row.impressions;
+          pageMap.set(page, pageStats);
+          grouped.set(query, pageMap);
+        }
+        const candidates = [];
+        for (const [query, pageMap] of grouped.entries()) {
+          const pages = [...pageMap.values()].map((pageStats) => ({
+            page: pageStats.page,
+            clicks: roundMetric(pageStats.clicks, 0),
+            impressions: roundMetric(pageStats.impressions, 0),
+            ctr: pageStats.impressions > 0 ? roundMetric(pageStats.clicks / pageStats.impressions * 100) : 0,
+            position: pageStats.impressions > 0 ? roundMetric(pageStats.weightedPosition / pageStats.impressions) : 0
+          })).sort((a, b) => b.clicks - a.clicks || b.impressions - a.impressions);
+          const totalClicks = pages.reduce((sum, page) => sum + page.clicks, 0);
+          const totalImpressions = pages.reduce((sum, page) => sum + page.impressions, 0);
+          if (pages.length < minPages || totalImpressions < minImpressions) continue;
+          const topPage = pages[0];
+          if (!topPage) continue;
+          const topClickShare = totalClicks > 0 ? topPage.clicks / totalClicks : 0;
+          const topImpressionShare = totalImpressions > 0 ? topPage.impressions / totalImpressions : 0;
+          const competitionShare = totalClicks > 0 ? topClickShare : topImpressionShare;
+          if (competitionShare > maxTopPageClickShare) continue;
+          const dispersion = 1 - competitionShare;
+          const pageFactor = Math.min(pages.length / 5, 1);
+          const volumeFactor = Math.min(totalImpressions / 1e4, 1);
+          const severityScore = roundMetric(dispersion * 70 + pageFactor * 20 + volumeFactor * 10);
+          candidates.push({
+            query,
+            pageCount: pages.length,
+            totalClicks: roundMetric(totalClicks, 0),
+            totalImpressions: roundMetric(totalImpressions, 0),
+            ctr: totalImpressions > 0 ? roundMetric(totalClicks / totalImpressions * 100) : 0,
+            topPage: topPage.page,
+            topPageClickShare: roundMetric(topClickShare * 100),
+            topPageImpressionShare: roundMetric(topImpressionShare * 100),
+            severityScore,
+            competingPages: pages.slice(0, 10)
+          });
+        }
+        return ok({
+          siteUrl: resolvedSiteUrl,
+          searchType,
+          dateRange: resolvedDateRange,
+          analyzedRows: rows.length,
+          candidateCount: candidates.length,
+          candidates: candidates.sort((a, b) => b.severityScore - a.severityScore || b.totalImpressions - a.totalImpressions).slice(0, topN),
+          thresholds: {
+            minPages,
+            minImpressions,
+            maxTopPageClickShare: roundMetric(maxTopPageClickShare * 100)
+          },
+          warnings
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "gsc_validate_query",
+    "Validate a Search Console metric/dimension/search type combination before executing it.",
+    {
+      dimensions: z2.array(z2.string()).optional().describe("Dimensions to validate."),
+      searchType: searchTypeSchema.optional().default("web"),
+      dateRange: z2.object({ startDate: z2.string(), endDate: z2.string() }).optional()
+    },
+    async ({ dimensions, searchType, dateRange }) => {
+      try {
+        const result = validateGSCQuerySelection(
+          dimensions ?? [],
+          searchType,
+          dateRange
+        );
+        return ok(result);
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+}
+
+// src/platforms/gsc/metricCatalog.ts
+var GSC_METRIC_CATALOG = [
+  // ============================================
+  // PERFORMANCE METRICS (always returned by API)
+  // ============================================
+  {
+    key: "clicks",
+    name: "Clicks",
+    description: "Number of clicks from Google Search results to your site",
+    category: "performance",
+    format: "number",
+    apiField: "clicks",
+    type: "api"
+  },
+  {
+    key: "impressions",
+    name: "Impressions",
+    description: "Number of times your site appeared in Google Search results",
+    category: "performance",
+    format: "number",
+    apiField: "impressions",
+    type: "api"
+  },
+  {
+    key: "ctr",
+    name: "CTR",
+    description: "Click-through rate: clicks / impressions (percentage)",
+    category: "performance",
+    format: "percent",
+    apiField: "ctr",
+    type: "api"
+  },
+  {
+    key: "position",
+    name: "Average Position",
+    description: "Average ranking position in Google Search results (1 = top)",
+    category: "performance",
+    format: "position",
+    apiField: "position",
+    type: "api"
+  }
+];
+
+// src/platforms/gsc/resources.ts
+var GSC_MANIFEST = {
+  platform: "google-search-console",
+  package: "@getmcpads/google-search-console-mcp-server",
+  access: "read-only",
+  oauthScope: GSC_OAUTH_SCOPE,
+  defaultPropertyEnv: "GSC_SITE_URL",
+  quotaNotes: {
+    searchAnalytics: "Read-only Search Analytics queries. Maximum 25,000 rows per request.",
+    urlInspection: "Read-only URL Inspection. Google quota is limited; bulk inspection is capped at 10 URLs per call.",
+    p2Monitoring: "P2 tools are read-only orchestration helpers. Delta tracking is caller-managed: pass prior snapshots back in; no server-side state is written."
+  },
+  tools: [
+    { name: "gsc_health_check", category: "diagnostics", description: "Verify auth, visible sites, default property, permissions, and warnings." },
+    { name: "gsc_list_sites", category: "properties", description: "List visible Search Console properties." },
+    { name: "gsc_get_site", category: "properties", description: "Get one property and its exact permission level." },
+    { name: "gsc_query_search_analytics", category: "analytics", description: "Query clicks, impressions, CTR, and position across supported dimensions." },
+    { name: "gsc_get_data_freshness", category: "analytics", description: "Find the latest recent date with Search Analytics data." },
+    { name: "gsc_monitor_indexation_freshness", category: "monitoring", description: "Monitor Search Analytics freshness, sitemap indexation totals, and optional small URL Inspection samples." },
+    { name: "gsc_track_sitemap_deltas", category: "sitemaps", description: "Compare current sitemap counts/statuses to an agent-provided baseline snapshot." },
+    { name: "gsc_analyze_search_appearance_trends", category: "analytics", description: "Trend structured data/rich result visibility via searchAppearance when available." },
+    { name: "gsc_plan_large_site_sampling", category: "planning", description: "Build a large-site URL Inspection sampling plan from sitemaps and page analytics." },
+    { name: "gsc_indexation_watchlist", category: "indexing", description: "Inspect up to 10 watchlist URLs and classify alert/review/ok indexation status." },
+    { name: "gsc_find_losses_gains", category: "analytics", description: "Compare query/page performance between two periods." },
+    { name: "gsc_cluster_queries", category: "analytics", description: "Cluster queries by brand, question intent, category, and tokens." },
+    { name: "gsc_detect_cannibalization", category: "analytics", description: "Detect queries where multiple pages compete." },
+    { name: "gsc_inspect_url", category: "indexing", description: "Inspect one URL for indexing, mobile usability, AMP, and rich result status." },
+    { name: "gsc_bulk_inspect_urls", category: "indexing", description: "Inspect up to 10 URLs sequentially with normalized results." },
+    { name: "gsc_list_sitemaps", category: "sitemaps", description: "List submitted sitemaps." },
+    { name: "gsc_get_sitemap", category: "sitemaps", description: "Get one submitted sitemap by feed path." },
+    { name: "gsc_get_sitemap_health", category: "sitemaps", description: "Summarize sitemap status, warnings, errors, submitted, and indexed counts." },
+    { name: "gsc_compare_search_types", category: "analytics", description: "Compare web, image, video, news, Discover, and Google News performance." },
+    { name: "gsc_validate_query", category: "planning", description: "Validate dimensions/search type/date compatibility." }
+  ],
+  resources: [
+    "gsc://manifest",
+    "gsc://recipes",
+    "gsc://metrics",
+    "gsc://dimensions",
+    "gsc://filters",
+    "gsc://compatibility",
+    "gsc://p2-readonly-playbooks"
+  ]
+};
+var GSC_RECIPES = [
+  {
+    name: "preflight",
+    goal: "Confirm the MCP can read the right GSC property before analysis.",
+    steps: [
+      { tool: "gsc_health_check", args: { siteUrl: "optional property URL" } },
+      { tool: "gsc_get_data_freshness", args: { searchType: "web", lookbackDays: 14 } }
+    ]
+  },
+  {
+    name: "weekly-performance-review",
+    goal: "Find query or page winners and losers between two equal periods.",
+    steps: [
+      { tool: "gsc_find_losses_gains", args: { dimension: "query", datePreset: "last28days", topN: 25 } },
+      { tool: "gsc_find_losses_gains", args: { dimension: "page", datePreset: "last28days", topN: 25 } }
+    ]
+  },
+  {
+    name: "indexing-and-sitemap-triage",
+    goal: "Check sitemap health, then inspect a small set of URLs without burning URL Inspection quota.",
+    steps: [
+      { tool: "gsc_get_sitemap_health", args: {} },
+      { tool: "gsc_bulk_inspect_urls", args: { urls: ["https://example.com/page"], continueOnError: true } }
+    ],
+    caution: "Keep URL Inspection batches small; bulk calls are capped at 10 URLs."
+  },
+  {
+    name: "p2-readonly-monitoring",
+    goal: "Run a no-write monitoring pass for freshness, sitemap indexation, and optional critical URL checks.",
+    steps: [
+      { tool: "gsc_monitor_indexation_freshness", args: { searchTypes: ["web"], lookbackDays: 14, inspectUrls: [] } },
+      { tool: "gsc_indexation_watchlist", args: { urls: [{ url: "https://example.com/important-page", priority: "high" }] } }
+    ],
+    caution: "URL Inspection quota is limited; keep watchlists capped at 10 URLs per call."
+  },
+  {
+    name: "p2-sitemap-delta-loop",
+    goal: "Compare sitemap submitted/indexed counts against a previous agent-held snapshot.",
+    steps: [
+      { tool: "gsc_track_sitemap_deltas", args: { baseline: [] } },
+      { tool: "gsc_track_sitemap_deltas", args: { baseline: [{ path: "https://example.com/sitemap.xml", submitted: 1e3, indexed: 950, warnings: 0, errors: 0 }] } }
+    ],
+    caution: "This server does not persist snapshots. Store snapshots in the calling workflow if deltas are needed later."
+  },
+  {
+    name: "p2-rich-result-trends",
+    goal: "Track structured data and rich-result visibility via Search Analytics searchAppearance rows.",
+    steps: [
+      { tool: "gsc_analyze_search_appearance_trends", args: { datePreset: "last28days", includePages: false } },
+      { tool: "gsc_analyze_search_appearance_trends", args: { datePreset: "last28days", includePages: true, topN: 25 } }
+    ],
+    caution: "searchAppearance only returns rows when the property/date/search type has appearance data available."
+  },
+  {
+    name: "p2-large-site-sampling",
+    goal: "Create an inspection sample before spending URL Inspection quota on a large site.",
+    steps: [
+      { tool: "gsc_plan_large_site_sampling", args: { datePreset: "last28days", maxInspectionUrls: 10 } },
+      { tool: "gsc_indexation_watchlist", args: { urls: [{ url: "https://example.com/page-from-recommendedInspectionUrls", priority: "medium" }] } }
+    ]
+  },
+  {
+    name: "content-opportunity-map",
+    goal: "Cluster demand and detect query-page overlap.",
+    steps: [
+      { tool: "gsc_cluster_queries", args: { datePreset: "last28days", limit: 5e3 } },
+      { tool: "gsc_detect_cannibalization", args: { datePreset: "last28days", minImpressions: 100 } }
+    ]
+  }
+];
+var GSC_P2_READONLY_PLAYBOOKS = {
+  scope: "P2 read-only agent workflows for monitoring freshness/indexation, sitemap deltas, rich-result trends, large-site sampling, and indexation watchlists.",
+  invariants: [
+    "No tool writes to Search Console or local state.",
+    "Sitemap delta tracking compares against caller-provided baselines only.",
+    "URL Inspection is read-only but quota-limited; all P2 inspection tools cap calls at 10 URLs.",
+    "Use Search Analytics searchAppearance only when rows are available for the selected property/date/search type."
+  ],
+  workflows: [
+    {
+      name: "freshness-indexation-monitor",
+      primaryTool: "gsc_monitor_indexation_freshness",
+      followUps: ["gsc_track_sitemap_deltas", "gsc_indexation_watchlist"],
+      outputUse: "Alert on stale Search Analytics data, sitemap errors/pending states, or unexpected URL Inspection verdicts."
+    },
+    {
+      name: "sitemap-delta-tracking",
+      primaryTool: "gsc_track_sitemap_deltas",
+      followUps: ["gsc_get_sitemap_health"],
+      outputUse: "Persist the returned snapshot externally, then pass it as baseline on the next run."
+    },
+    {
+      name: "structured-data-trends",
+      primaryTool: "gsc_analyze_search_appearance_trends",
+      followUps: ["gsc_query_search_analytics"],
+      outputUse: "Find searchAppearance winners/losses and optionally page-level feature changes."
+    },
+    {
+      name: "large-site-indexation-sampling",
+      primaryTool: "gsc_plan_large_site_sampling",
+      followUps: ["gsc_indexation_watchlist", "gsc_bulk_inspect_urls"],
+      outputUse: "Spend URL Inspection quota on representative top-traffic, low-CTR, declining, and sitemap-risk URLs."
+    }
+  ]
+};
+function registerGSCResources(server) {
+  server.resource("gsc-manifest", "gsc://manifest", async () => ({
+    contents: [{
+      uri: "gsc://manifest",
+      mimeType: "application/json",
+      text: JSON.stringify(GSC_MANIFEST, null, 2)
+    }]
+  }));
+  server.resource("gsc-recipes", "gsc://recipes", async () => ({
+    contents: [{
+      uri: "gsc://recipes",
+      mimeType: "application/json",
+      text: JSON.stringify(GSC_RECIPES, null, 2)
+    }]
+  }));
+  server.resource("gsc-metrics", "gsc://metrics", async () => ({
+    contents: [{
+      uri: "gsc://metrics",
+      mimeType: "application/json",
+      text: JSON.stringify([...GSC_METRIC_CATALOG, ...GSC_CALCULATED_METRIC_DEFINITIONS], null, 2)
+    }]
+  }));
+  server.resource("gsc-dimensions", "gsc://dimensions", async () => ({
+    contents: [{
+      uri: "gsc://dimensions",
+      mimeType: "application/json",
+      text: JSON.stringify(GSC_DIMENSION_CATALOG, null, 2)
+    }]
+  }));
+  server.resource("gsc-filters", "gsc://filters", async () => ({
+    contents: [{
+      uri: "gsc://filters",
+      mimeType: "application/json",
+      text: JSON.stringify(GSC_FILTER_CATALOG, null, 2)
+    }]
+  }));
+  server.resource("gsc-compatibility", "gsc://compatibility", async () => ({
+    contents: [{
+      uri: "gsc://compatibility",
+      mimeType: "application/json",
+      text: JSON.stringify({
+        description: "Google Search Console Search Analytics constraints.",
+        maxDimensions: 5,
+        dimensions: ["query", "page", "country", "device", "date", "hour", "searchAppearance"],
+        searchTypes: ["web", "image", "video", "news", "discover", "googleNews"],
+        queryDimensionUnsupportedFor: ["discover", "googleNews"],
+        dataStates: ["final", "all", "hourly_all"],
+        aggregationTypes: ["auto", "byPage", "byProperty", "byNewsShowcasePanel"],
+        aggregationRules: {
+          byProperty: "Cannot group or filter by page and is unsupported for discover/googleNews.",
+          byNewsShowcasePanel: "Requires type=discover or type=googleNews and searchAppearance equals NEWS_SHOWCASE; cannot group/filter by page or filter to another searchAppearance."
+        },
+        dataFreshness: "final is stable; all includes incomplete daily data; hourly_all requires hour, is limited to 10 days, and can return firstIncompleteHour metadata.",
+        rowLimitMax: 25e3
+      }, null, 2)
+    }]
+  }));
+  server.resource("gsc-p2-readonly-playbooks", "gsc://p2-readonly-playbooks", async () => ({
+    contents: [{
+      uri: "gsc://p2-readonly-playbooks",
+      mimeType: "application/json",
+      text: JSON.stringify(GSC_P2_READONLY_PLAYBOOKS, null, 2)
+    }]
+  }));
+}
+
+// src/platforms/gsc/index.ts
+function registerGSC(server, config) {
+  registerGSCTools(server, config);
+  registerGSCResources(server);
+  logger.info("gsc", "Registered 20 read tools and 7 resources");
+}
+
+// src/server.ts
+var PACKAGE_VERSION = "1.0.0";
+function createServer(config) {
+  const server = new McpServer(
+    { name: "google-search-console-mcp", version: PACKAGE_VERSION },
+    { capabilities: { tools: { listChanged: true }, resources: { subscribe: false, listChanged: true } } }
+  );
+  registerGSC(server, config);
+  logger.system(`google-search-console-mcp v${PACKAGE_VERSION} ready, read-only`);
+  return server;
+}
+
+// src/cli.ts
+async function main() {
+  try {
+    const config = loadConfig();
+    logger.setLevel(config.logLevel);
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.system("Stdio transport connected - waiting for MCP client");
+  } catch (error) {
+    logger.error("cli", "Fatal error", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+main();
+//# sourceMappingURL=cli.js.map