@getmcpads/google-analytics-mcp-server 1.0.0

package/dist/cli.js

@@ -0,0 +1,4488 @@
+#!/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().min(1, "GA4_CLIENT_ID is required"),
+  clientSecret: z.string().min(1, "GA4_CLIENT_SECRET is required"),
+  refreshToken: z.string().min(1, "GA4_REFRESH_TOKEN is required"),
+  defaultPropertyId: z.string().optional(),
+  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info")
+});
+function loadConfig() {
+  const raw = {
+    clientId: process.env["GA4_CLIENT_ID"] ?? "",
+    clientSecret: process.env["GA4_CLIENT_SECRET"] ?? "",
+    refreshToken: process.env["GA4_REFRESH_TOKEN"] ?? "",
+    defaultPropertyId: process.env["GA4_PROPERTY_ID"] || process.env["GA4_DEFAULT_PROPERTY_ID"] || void 0,
+    logLevel: process.env["LOG_LEVEL"] ?? "info"
+  };
+  const result = configSchema.safeParse(raw);
+  if (!result.success) {
+    const missing = result.error.issues.map((i) => i.message).join(", ");
+    logger.error("config", `Missing credentials: ${missing}`);
+    throw new Error(`Missing GA4 credentials: ${missing}`);
+  }
+  logger.system("GA4 MCP Server configured");
+  return result.data;
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/platforms/ga4/tools.ts
+import { z as z3 } from "zod";
+
+// src/platforms/ga4/types.ts
+var GA4ApiException = class extends Error {
+  code;
+  status;
+  constructor(message, code, status) {
+    super(message);
+    this.name = "GA4ApiException";
+    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 Analytics";
+    if (this.isRateLimitError) return "Rate limit exceeded, wait and retry";
+    if (this.isQuotaError) return "Quota exceeded, reduce query frequency";
+    return "Check the error details for more information";
+  }
+};
+var GA4_DATA_API_BASE = "https://analyticsdata.googleapis.com/v1beta";
+var GA4_DATA_API_ALPHA_BASE = "https://analyticsdata.googleapis.com/v1alpha";
+var GA4_ADMIN_API_BASE = "https://analyticsadmin.googleapis.com/v1beta";
+var GA4_ADMIN_API_ALPHA_BASE = "https://analyticsadmin.googleapis.com/v1alpha";
+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: "yesterday", endDate: "yesterday" };
+    case "last7days":
+      return { startDate: "7daysAgo", endDate: "today" };
+    case "last28days":
+      return { startDate: "28daysAgo", endDate: "today" };
+    case "last30days":
+      return { startDate: "30daysAgo", endDate: "today" };
+    case "last90days":
+      return { startDate: "90daysAgo", endDate: "today" };
+    case "last12months":
+      return { startDate: daysAgo(365), endDate: today };
+    case "thisMonth": {
+      const firstOfMonth = new Date(now.getFullYear(), now.getMonth(), 1).toISOString().split("T")[0];
+      return { startDate: firstOfMonth, endDate: today };
+    }
+    case "lastMonth": {
+      const first = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+      const last = new Date(now.getFullYear(), now.getMonth(), 0);
+      return { startDate: first.toISOString().split("T")[0], endDate: last.toISOString().split("T")[0] };
+    }
+    case "thisYear": {
+      const firstOfYear = new Date(now.getFullYear(), 0, 1).toISOString().split("T")[0];
+      return { startDate: firstOfYear, endDate: today };
+    }
+    default:
+      return { startDate: "28daysAgo", endDate: "today" };
+  }
+}
+
+// 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,
+      suggestion: this.suggestion,
+      ...this.retryAfter !== void 0 && { retryAfter: this.retryAfter }
+    };
+  }
+};
+var RateLimitError = class extends PlatformApiError {
+  constructor(retryAfter) {
+    super("ga4", 429, "Rate limit exceeded", true, false, false, "Wait and retry with backoff", retryAfter);
+  }
+};
+function formatMcpToolError(error) {
+  if (error instanceof PlatformApiError) return { content: [{ type: "text", text: JSON.stringify(error.toMcpError(), 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 lastSec = this.timestamps.filter((t) => now - t < 1e3);
+    if (lastSec.length >= 10) {
+      const w = 1e3 - (now - lastSec[0]) + 50;
+      logger.debug("ga4", `Rate limit: ${w}ms`);
+      await new Promise((r) => setTimeout(r, w));
+    }
+    if (this.timestamps.length >= 600) {
+      const w = 6e4 - (now - this.timestamps[0]) + 100;
+      await new Promise((r) => setTimeout(r, w));
+    }
+    this.timestamps.push(Date.now());
+  }
+  async execute(fn) {
+    for (let i = 0; i <= 3; i++) {
+      await this.acquire();
+      try {
+        return await fn();
+      } catch (e) {
+        const isRL = e instanceof RateLimitError || e instanceof Error && e.message.toLowerCase().includes("rate limit");
+        if (isRL && i < 3) {
+          await new Promise((r) => setTimeout(r, Math.min(1e3 * Math.pow(2, i) + Math.floor(Math.random() * 500), 3e4)));
+          continue;
+        }
+        throw e;
+      }
+    }
+    throw new RateLimitError();
+  }
+};
+
+// src/platforms/ga4/client.ts
+var GOOGLE_OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+var GA4_ADMIN_COLLECTIONS = {
+  accessBindings: { version: "v1alpha", collectionKey: "accessBindings" },
+  adSenseLinks: { version: "v1alpha", collectionKey: "adSenseLinks" },
+  audiences: { version: "v1alpha", collectionKey: "audiences" },
+  bigQueryLinks: { version: "v1alpha", collectionKey: "bigQueryLinks" },
+  calculatedMetrics: { version: "v1alpha", collectionKey: "calculatedMetrics" },
+  channelGroups: { version: "v1alpha", collectionKey: "channelGroups" },
+  customDimensions: { version: "v1beta", collectionKey: "customDimensions" },
+  customMetrics: { version: "v1beta", collectionKey: "customMetrics" },
+  dataStreams: { version: "v1beta", collectionKey: "dataStreams" },
+  displayVideo360AdvertiserLinkProposals: { version: "v1alpha", collectionKey: "displayVideo360AdvertiserLinkProposals" },
+  displayVideo360AdvertiserLinks: { version: "v1alpha", collectionKey: "displayVideo360AdvertiserLinks" },
+  expandedDataSets: { version: "v1alpha", collectionKey: "expandedDataSets" },
+  firebaseLinks: { version: "v1beta", collectionKey: "firebaseLinks" },
+  googleAdsLinks: { version: "v1beta", collectionKey: "googleAdsLinks" },
+  keyEvents: { version: "v1beta", collectionKey: "keyEvents" },
+  reportingDataAnnotations: { version: "v1alpha", collectionKey: "reportingDataAnnotations" },
+  rollupPropertySourceLinks: { version: "v1alpha", collectionKey: "rollupPropertySourceLinks" },
+  searchAds360Links: { version: "v1alpha", collectionKey: "searchAds360Links" },
+  subpropertyEventFilters: { version: "v1alpha", collectionKey: "subpropertyEventFilters" },
+  subpropertySyncConfigs: { version: "v1alpha", collectionKey: "subpropertySyncConfigs" }
+};
+var GA4Client = class {
+  accessToken = "";
+  tokenExpiresAt = 0;
+  clientId;
+  clientSecret;
+  refreshToken;
+  rateLimiter;
+  constructor(config) {
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+    this.refreshToken = config.refreshToken;
+    this.rateLimiter = new RateLimiter();
+  }
+  // ============================================
+  // PRIVATE METHODS
+  // ============================================
+  /**
+   * Refresh access token using refresh token.
+   * Google refresh tokens never expire.
+   */
+  async refreshAccessToken() {
+    logger.debug("ga4", "Refreshing access token");
+    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: this.refreshToken,
+        client_id: this.clientId,
+        client_secret: this.clientSecret
+      })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      logger.error("ga4", "Token refresh failed", { status: response.status, error });
+      throw new GA4ApiException(
+        error.error_description || error.error || "Failed to refresh token",
+        response.status,
+        error.error
+      );
+    }
+    const data = await response.json();
+    this.accessToken = data.access_token;
+    this.tokenExpiresAt = Date.now() + (data.expires_in - 60) * 1e3;
+    logger.debug("ga4", "Access token refreshed successfully");
+  }
+  /**
+   * Ensure we have a valid access token before making API calls.
+   */
+  async ensureValidToken() {
+    if (!this.accessToken || Date.now() >= this.tokenExpiresAt) {
+      await this.refreshAccessToken();
+    }
+  }
+  async request(url, options = {}) {
+    await this.ensureValidToken();
+    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;
+        logger.error("ga4", "API Error", { status: response.status, error: errorBody });
+        const detailedMessage = errorDetails?.message || `Request failed: ${response.statusText}`;
+        throw new GA4ApiException(
+          detailedMessage,
+          response.status,
+          errorDetails?.status
+        );
+      }
+      return response.json();
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new GA4ApiException(
+          "GA4 API request timed out after 90 seconds",
+          408,
+          "TIMEOUT"
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  cleanPropertyId(propertyId) {
+    return propertyId.replace("properties/", "");
+  }
+  cleanResourceName(resourceName) {
+    return resourceName.replace(/^\/+/, "");
+  }
+  async listPagedRecords(baseUrl, collectionKey, pageSize, maxPages = 50) {
+    const records = [];
+    let pageToken;
+    let pagesRead = 0;
+    do {
+      const params = new URLSearchParams({ pageSize: String(pageSize) });
+      if (pageToken) {
+        params.set("pageToken", pageToken);
+      }
+      const separator = baseUrl.includes("?") ? "&" : "?";
+      const response = await this.rateLimiter.execute(
+        () => this.request(`${baseUrl}${separator}${params.toString()}`)
+      );
+      const collection = response[collectionKey];
+      if (Array.isArray(collection)) {
+        records.push(...collection.filter((item) => typeof item === "object" && item !== null && !Array.isArray(item)));
+      }
+      pageToken = typeof response.nextPageToken === "string" ? response.nextPageToken : void 0;
+      pagesRead += 1;
+    } while (pageToken && pagesRead < maxPages);
+    return records;
+  }
+  redactSecretRecord(record) {
+    const safeRecord = { ...record };
+    if ("secretValue" in safeRecord) {
+      safeRecord.secretValue = "[REDACTED]";
+      safeRecord.secretValueRedacted = true;
+    }
+    return safeRecord;
+  }
+  // ============================================
+  // PROPERTY MANAGEMENT
+  // ============================================
+  /**
+   * List all GA4 properties accessible to the authenticated user
+   * Calls GET /v1beta/accountSummaries with pagination
+   * Returns flattened array of GA4Property
+   */
+  async listProperties() {
+    const properties = [];
+    let pageToken;
+    do {
+      const params = new URLSearchParams({ pageSize: "200" });
+      if (pageToken) {
+        params.set("pageToken", pageToken);
+      }
+      const url = `${GA4_ADMIN_API_BASE}/accountSummaries?${params.toString()}`;
+      const response = await this.rateLimiter.execute(
+        () => this.request(url)
+      );
+      if (response.accountSummaries) {
+        for (const account of response.accountSummaries) {
+          if (account.propertySummaries) {
+            for (const prop of account.propertySummaries) {
+              const propertyId = prop.property.replace("properties/", "");
+              properties.push({
+                propertyId,
+                displayName: prop.displayName,
+                timeZone: "",
+                currencyCode: "",
+                propertyType: prop.propertyType,
+                parent: account.account
+              });
+            }
+          }
+        }
+      }
+      pageToken = response.nextPageToken;
+    } while (pageToken);
+    await Promise.all(
+      properties.map(async (prop) => {
+        try {
+          const detail = await this.rateLimiter.execute(
+            () => this.request(`${GA4_ADMIN_API_BASE}/properties/${prop.propertyId}`)
+          );
+          prop.currencyCode = detail.currencyCode || "";
+          prop.timeZone = detail.timeZone || "";
+          if (detail.industryCategory) {
+            prop.industryCategory = detail.industryCategory;
+          }
+        } catch {
+          logger.warn("ga4", `Failed to enrich property ${prop.propertyId}`);
+        }
+      })
+    );
+    return properties;
+  }
+  // ============================================
+  // REPORTING
+  // ============================================
+  /**
+   * Run a GA4 report with automatic pagination
+   * POST /v1beta/properties/{propertyId}:runReport
+   * Handles pagination via offset, capped at 250,000 rows per request
+   */
+  async runReport(propertyId, request) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const url = `${GA4_DATA_API_BASE}/properties/${cleanPropertyId}:runReport`;
+    const MAX_ROWS_PER_REQUEST = 25e4;
+    const firstResponse = await this.rateLimiter.execute(
+      () => this.request(url, {
+        method: "POST",
+        body: JSON.stringify({
+          ...request,
+          limit: request.limit ?? MAX_ROWS_PER_REQUEST,
+          offset: request.offset ?? 0
+        })
+      })
+    );
+    const totalRows = firstResponse.rowCount ?? 0;
+    const returnedRows = firstResponse.rows?.length ?? 0;
+    const startOffset = request.offset ?? 0;
+    if (request.limit) {
+      return firstResponse;
+    }
+    if (startOffset + returnedRows >= totalRows) {
+      return firstResponse;
+    }
+    const allRows = [...firstResponse.rows ?? []];
+    let currentOffset = startOffset + returnedRows;
+    while (currentOffset < totalRows) {
+      const pageResponse = await this.rateLimiter.execute(
+        () => this.request(url, {
+          method: "POST",
+          body: JSON.stringify({
+            ...request,
+            limit: MAX_ROWS_PER_REQUEST,
+            offset: currentOffset
+          })
+        })
+      );
+      if (pageResponse.rows) {
+        allRows.push(...pageResponse.rows);
+      }
+      const pageRowCount = pageResponse.rows?.length ?? 0;
+      if (pageRowCount === 0) break;
+      currentOffset += pageRowCount;
+    }
+    return {
+      ...firstResponse,
+      rows: allRows
+    };
+  }
+  /**
+   * Run a GA4 realtime report.
+   * POST /v1beta/properties/{propertyId}:runRealtimeReport
+   */
+  async runRealtimeReport(propertyId, request) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const url = `${GA4_DATA_API_BASE}/properties/${cleanPropertyId}:runRealtimeReport`;
+    return this.rateLimiter.execute(
+      () => this.request(url, {
+        method: "POST",
+        body: JSON.stringify(request)
+      })
+    );
+  }
+  /** POST /v1beta/properties/{propertyId}:batchRunReports (maximum five reports). */
+  async batchRunReports(propertyId, requests) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const url = `${GA4_DATA_API_BASE}/properties/${cleanPropertyId}:batchRunReports`;
+    return this.rateLimiter.execute(
+      () => this.request(url, {
+        method: "POST",
+        body: JSON.stringify({ requests })
+      })
+    );
+  }
+  /** POST /v1beta/properties/{propertyId}:runPivotReport. */
+  async runPivotReport(propertyId, request) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const url = `${GA4_DATA_API_BASE}/properties/${cleanPropertyId}:runPivotReport`;
+    return this.rateLimiter.execute(
+      () => this.request(url, {
+        method: "POST",
+        body: JSON.stringify(request)
+      })
+    );
+  }
+  /** POST /v1beta/properties/{propertyId}:batchRunPivotReports (maximum five reports). */
+  async batchRunPivotReports(propertyId, requests) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const url = `${GA4_DATA_API_BASE}/properties/${cleanPropertyId}:batchRunPivotReports`;
+    return this.rateLimiter.execute(
+      () => this.request(url, {
+        method: "POST",
+        body: JSON.stringify({ requests })
+      })
+    );
+  }
+  /** POST /v1beta/properties/{propertyId}:checkCompatibility for Core reports. */
+  async checkCompatibility(propertyId, request) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const url = `${GA4_DATA_API_BASE}/properties/${cleanPropertyId}:checkCompatibility`;
+    return this.rateLimiter.execute(
+      () => this.request(url, {
+        method: "POST",
+        body: JSON.stringify(request)
+      })
+    );
+  }
+  /** GET /v1alpha/properties/{propertyId}/propertyQuotasSnapshot. */
+  async getPropertyQuotasSnapshot(propertyId) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    return this.rateLimiter.execute(
+      () => this.request(
+        `${GA4_DATA_API_ALPHA_BASE}/properties/${cleanPropertyId}/propertyQuotasSnapshot`
+      )
+    );
+  }
+  /**
+   * Run a GA4 funnel report.
+   * POST /v1alpha/properties/{propertyId}:runFunnelReport
+   */
+  async runFunnelReport(propertyId, request) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const url = `${GA4_DATA_API_ALPHA_BASE}/properties/${cleanPropertyId}:runFunnelReport`;
+    return this.rateLimiter.execute(
+      () => this.request(url, {
+        method: "POST",
+        body: JSON.stringify(request)
+      })
+    );
+  }
+  // ============================================
+  // METADATA
+  // ============================================
+  /**
+   * Get metadata for a GA4 property (available dimensions & metrics)
+   * GET /v1beta/properties/{propertyId}/metadata
+   */
+  async getMetadata(propertyId) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const url = `${GA4_DATA_API_BASE}/properties/${cleanPropertyId}/metadata`;
+    return this.rateLimiter.execute(
+      () => this.request(url)
+    );
+  }
+  /**
+   * Get Admin API property details.
+   * GET /v1beta/properties/{propertyId}
+   */
+  async getProperty(propertyId) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const url = `${GA4_ADMIN_API_BASE}/properties/${cleanPropertyId}`;
+    return this.rateLimiter.execute(
+      () => this.request(url)
+    );
+  }
+  /** List raw Analytics Admin accounts accessible to the caller. */
+  async listAccounts(pageSize = 200) {
+    return this.listPagedRecords(
+      `${GA4_ADMIN_API_BASE}/accounts`,
+      "accounts",
+      pageSize
+    );
+  }
+  /**
+   * List an allowlisted Analytics Admin collection for a property.
+   * Every route in the allowlist is a GET-only list method.
+   */
+  async listAdminPropertyResources(propertyId, collection, pageSize = 200) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const definition = GA4_ADMIN_COLLECTIONS[collection];
+    const base = definition.version === "v1beta" ? GA4_ADMIN_API_BASE : GA4_ADMIN_API_ALPHA_BASE;
+    return this.listPagedRecords(
+      `${base}/properties/${cleanPropertyId}/${collection}`,
+      definition.collectionKey,
+      pageSize
+    );
+  }
+  /** Get an allowlisted property singleton setting through a GET-only Admin API method. */
+  async getPropertySetting(propertyId, setting) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const endpoints = {
+      attributionSettings: `${GA4_ADMIN_API_ALPHA_BASE}/properties/${cleanPropertyId}/attributionSettings`,
+      dataRetentionSettings: `${GA4_ADMIN_API_BASE}/properties/${cleanPropertyId}/dataRetentionSettings`,
+      googleSignalsSettings: `${GA4_ADMIN_API_ALPHA_BASE}/properties/${cleanPropertyId}/googleSignalsSettings`,
+      reportingIdentitySettings: `${GA4_ADMIN_API_ALPHA_BASE}/properties/${cleanPropertyId}/reportingIdentitySettings`,
+      userProvidedDataSettings: `${GA4_ADMIN_API_ALPHA_BASE}/properties/${cleanPropertyId}/userProvidedDataSettings`
+    };
+    return this.rateLimiter.execute(() => this.request(endpoints[setting]));
+  }
+  // ============================================
+  // AUDIENCES & AUDIENCE EXPORTS
+  // ============================================
+  /**
+   * List Audience Export snapshots for a property.
+   * GET /v1beta/properties/{propertyId}/audienceExports
+   */
+  async listAudienceExports(propertyId, pageSize = 100) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    return this.listPagedRecords(
+      `${GA4_DATA_API_BASE}/properties/${cleanPropertyId}/audienceExports`,
+      "audienceExports",
+      pageSize
+    );
+  }
+  /**
+   * Get Audience Export metadata.
+   * GET /v1beta/properties/{propertyId}/audienceExports/{audienceExport}
+   */
+  async getAudienceExport(audienceExportName) {
+    const resourceName = this.cleanResourceName(audienceExportName);
+    return this.rateLimiter.execute(
+      () => this.request(`${GA4_DATA_API_BASE}/${resourceName}`)
+    );
+  }
+  /**
+   * Query rows from an existing Audience Export. This is read-only but can contain user identifiers.
+   * POST /v1beta/properties/{propertyId}/audienceExports/{audienceExport}:query
+   */
+  async queryAudienceExport(audienceExportName, request) {
+    const resourceName = this.cleanResourceName(audienceExportName);
+    return this.rateLimiter.execute(
+      () => this.request(`${GA4_DATA_API_BASE}/${resourceName}:query`, {
+        method: "POST",
+        body: JSON.stringify(request)
+      })
+    );
+  }
+  /**
+   * List configured Admin API Audiences for a property.
+   * GET /v1alpha/properties/{propertyId}/audiences
+   */
+  async listAudiences(propertyId, pageSize = 200) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    return this.listPagedRecords(
+      `${GA4_ADMIN_API_ALPHA_BASE}/properties/${cleanPropertyId}/audiences`,
+      "audiences",
+      pageSize
+    );
+  }
+  /**
+   * List Recurring Audience Lists for a property.
+   * GET /v1alpha/properties/{propertyId}/recurringAudienceLists
+   */
+  async listRecurringAudienceLists(propertyId, pageSize = 100) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    return this.listPagedRecords(
+      `${GA4_DATA_API_ALPHA_BASE}/properties/${cleanPropertyId}/recurringAudienceLists`,
+      "recurringAudienceLists",
+      pageSize
+    );
+  }
+  /**
+   * Get Recurring Audience List metadata.
+   * GET /v1alpha/properties/{propertyId}/recurringAudienceLists/{recurringAudienceList}
+   */
+  async getRecurringAudienceList(recurringAudienceListName) {
+    const resourceName = this.cleanResourceName(recurringAudienceListName);
+    return this.rateLimiter.execute(
+      () => this.request(`${GA4_DATA_API_ALPHA_BASE}/${resourceName}`)
+    );
+  }
+  // ============================================
+  // EXPORTS & TAGGING DIAGNOSTICS
+  // ============================================
+  /**
+   * List BigQuery links configured for a property.
+   * GET /v1alpha/properties/{propertyId}/bigQueryLinks
+   */
+  async listBigQueryLinks(propertyId, pageSize = 200) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    return this.listPagedRecords(
+      `${GA4_ADMIN_API_ALPHA_BASE}/properties/${cleanPropertyId}/bigQueryLinks`,
+      "bigQueryLinks",
+      pageSize
+    );
+  }
+  /**
+   * List data streams configured for a property.
+   * GET /v1alpha/properties/{propertyId}/dataStreams
+   */
+  async listDataStreams(propertyId, pageSize = 200) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    return this.listPagedRecords(
+      `${GA4_ADMIN_API_ALPHA_BASE}/properties/${cleanPropertyId}/dataStreams`,
+      "dataStreams",
+      pageSize
+    );
+  }
+  /**
+   * List Measurement Protocol secrets for a stream with secret values redacted.
+   * GET /v1alpha/properties/{propertyId}/dataStreams/{dataStream}/measurementProtocolSecrets
+   */
+  async listMeasurementProtocolSecrets(dataStreamName, pageSize = 10) {
+    const resourceName = this.cleanResourceName(dataStreamName);
+    const secrets = await this.listPagedRecords(
+      `${GA4_ADMIN_API_ALPHA_BASE}/${resourceName}/measurementProtocolSecrets`,
+      "measurementProtocolSecrets",
+      pageSize
+    );
+    return secrets.map((secret) => this.redactSecretRecord(secret));
+  }
+  /**
+   * Get enhanced measurement settings for a web stream.
+   * GET /v1alpha/properties/{propertyId}/dataStreams/{dataStream}/enhancedMeasurementSettings
+   */
+  async getEnhancedMeasurementSettings(dataStreamName) {
+    const resourceName = this.cleanResourceName(dataStreamName);
+    return this.rateLimiter.execute(
+      () => this.request(`${GA4_ADMIN_API_ALPHA_BASE}/${resourceName}/enhancedMeasurementSettings`)
+    );
+  }
+  /**
+   * Get data redaction settings for a web stream.
+   * GET /v1alpha/properties/{propertyId}/dataStreams/{dataStream}/dataRedactionSettings
+   */
+  async getDataRedactionSettings(dataStreamName) {
+    const resourceName = this.cleanResourceName(dataStreamName);
+    return this.rateLimiter.execute(
+      () => this.request(`${GA4_ADMIN_API_ALPHA_BASE}/${resourceName}/dataRedactionSettings`)
+    );
+  }
+  /**
+   * List event create rules for a web stream.
+   * GET /v1alpha/properties/{propertyId}/dataStreams/{dataStream}/eventCreateRules
+   */
+  async listEventCreateRules(dataStreamName, pageSize = 200) {
+    const resourceName = this.cleanResourceName(dataStreamName);
+    return this.listPagedRecords(
+      `${GA4_ADMIN_API_ALPHA_BASE}/${resourceName}/eventCreateRules`,
+      "eventCreateRules",
+      pageSize
+    );
+  }
+  /**
+   * List event edit rules for a web stream.
+   * GET /v1alpha/properties/{propertyId}/dataStreams/{dataStream}/eventEditRules
+   */
+  async listEventEditRules(dataStreamName, pageSize = 200) {
+    const resourceName = this.cleanResourceName(dataStreamName);
+    return this.listPagedRecords(
+      `${GA4_ADMIN_API_ALPHA_BASE}/${resourceName}/eventEditRules`,
+      "eventEditRules",
+      pageSize
+    );
+  }
+  // ============================================
+  // CHANNEL GROUPS
+  // ============================================
+  /**
+   * List custom channel groups for a GA4 property
+   * GET /v1alpha/properties/{propertyId}/channelGroups
+   * NOTE: channelGroups endpoint is only available in v1alpha, not v1beta
+   */
+  async listChannelGroups(propertyId) {
+    const cleanPropertyId = this.cleanPropertyId(propertyId);
+    const url = `https://analyticsadmin.googleapis.com/v1alpha/properties/${cleanPropertyId}/channelGroups`;
+    const response = await this.rateLimiter.execute(
+      () => this.request(url)
+    );
+    return response.channelGroups ?? [];
+  }
+  // ============================================
+  // RESPONSE FLATTENING
+  // ============================================
+  /**
+   * Convert a GA4RunReportResponse into flat GA4InsightRow[]
+   * Maps dimension and metric headers to row values
+   * Parses numeric strings to numbers for metric values
+   *
+   * Input:
+   *   dimensionHeaders: [{ name: "date" }, { name: "sessionSource" }]
+   *   metricHeaders: [{ name: "sessions", type: "TYPE_INTEGER" }, { name: "totalRevenue", type: "TYPE_CURRENCY" }]
+   *   rows: [{ dimensionValues: [{ value: "20260301" }, { value: "google" }], metricValues: [{ value: "150" }, { value: "1234.56" }] }]
+   *
+   * Output:
+   *   [{ date: "20260301", sessionSource: "google", sessions: 150, totalRevenue: 1234.56 }]
+   */
+  flattenResponse(response) {
+    if (!response.rows || response.rows.length === 0) {
+      return [];
+    }
+    const dimensionHeaders = response.dimensionHeaders ?? [];
+    const metricHeaders = response.metricHeaders ?? [];
+    return response.rows.map((row) => {
+      const flat = {};
+      if (row.dimensionValues) {
+        for (let i = 0; i < dimensionHeaders.length; i++) {
+          const header = dimensionHeaders[i];
+          const value = row.dimensionValues[i]?.value ?? null;
+          flat[header.name] = value;
+        }
+      }
+      if (row.metricValues) {
+        for (let i = 0; i < metricHeaders.length; i++) {
+          const header = metricHeaders[i];
+          const rawValue = row.metricValues[i]?.value ?? null;
+          if (rawValue === null) {
+            flat[header.name] = null;
+          } else if (/^-?\d+(\.\d+)?$/.test(rawValue)) {
+            flat[header.name] = parseFloat(rawValue);
+          } else {
+            flat[header.name] = rawValue;
+          }
+        }
+      }
+      return flat;
+    });
+  }
+};
+
+// src/platforms/ga4/metric-catalog.ts
+var TRAFFIC_METRICS = [
+  {
+    key: "sessions",
+    name: "Sessions",
+    description: "The number of sessions that began on your site or app.",
+    category: "traffic",
+    format: "number",
+    apiField: "sessions",
+    type: "api"
+  },
+  {
+    key: "activeUsers",
+    name: "Active Users",
+    description: "The number of distinct users who visited your site or app.",
+    category: "traffic",
+    format: "number",
+    apiField: "activeUsers",
+    type: "api"
+  },
+  {
+    key: "newUsers",
+    name: "New Users",
+    description: "The number of users who interacted with your site or app for the first time.",
+    category: "traffic",
+    format: "number",
+    apiField: "newUsers",
+    type: "api"
+  },
+  {
+    key: "totalUsers",
+    name: "Total Users",
+    description: "The total number of unique users who logged an event.",
+    category: "traffic",
+    format: "number",
+    apiField: "totalUsers",
+    type: "api"
+  },
+  {
+    key: "screenPageViews",
+    name: "Page Views",
+    description: "The number of app screens or web pages your users viewed. Includes repeated views of a single page or screen.",
+    category: "traffic",
+    format: "number",
+    apiField: "screenPageViews",
+    type: "api"
+  },
+  {
+    key: "bounceRate",
+    name: "Bounce Rate",
+    description: "The percentage of sessions that were not engaged (lasted less than 10 seconds, had no conversion events, and had fewer than 2 page/screen views).",
+    category: "traffic",
+    format: "percent",
+    apiField: "bounceRate",
+    type: "api"
+  },
+  {
+    key: "sessionsPerUser",
+    name: "Sessions per User",
+    description: "The average number of sessions per user.",
+    category: "traffic",
+    format: "ratio",
+    apiField: "sessionsPerUser",
+    type: "api"
+  },
+  {
+    key: "engagedSessions",
+    name: "Engaged Sessions",
+    description: "The number of sessions that lasted 10 seconds or longer, had a conversion event, or had 2 or more page/screen views.",
+    category: "traffic",
+    format: "number",
+    apiField: "engagedSessions",
+    type: "api"
+  },
+  {
+    key: "crashAffectedUsers",
+    name: "Crash Affected Users",
+    description: "The number of users who experienced a crash in your app.",
+    category: "traffic",
+    format: "number",
+    apiField: "crashAffectedUsers",
+    type: "api"
+  }
+];
+var ENGAGEMENT_METRICS = [
+  {
+    key: "averageSessionDuration",
+    name: "Avg. Session Duration",
+    description: "The average duration (in seconds) of users' sessions.",
+    category: "engagement",
+    format: "duration",
+    apiField: "averageSessionDuration",
+    type: "api"
+  },
+  {
+    key: "engagementRate",
+    name: "Engagement Rate",
+    description: "The percentage of engaged sessions (sessions that lasted 10 seconds or longer, had a conversion event, or had 2 or more page/screen views).",
+    category: "engagement",
+    format: "percent",
+    apiField: "engagementRate",
+    type: "api"
+  },
+  {
+    key: "screenPageViewsPerSession",
+    name: "Pages per Session",
+    description: "The average number of pages viewed per session.",
+    category: "engagement",
+    format: "ratio",
+    apiField: "screenPageViewsPerSession",
+    type: "api"
+  },
+  {
+    key: "eventCount",
+    name: "Event Count",
+    description: "The total number of events triggered by users.",
+    category: "engagement",
+    format: "number",
+    apiField: "eventCount",
+    type: "api"
+  },
+  {
+    key: "eventsPerSession",
+    name: "Events per Session",
+    description: "The average number of events triggered per session.",
+    category: "engagement",
+    format: "ratio",
+    apiField: "eventsPerSession",
+    type: "api"
+  },
+  {
+    key: "userEngagementDuration",
+    name: "User Engagement Duration",
+    description: "The total amount of time (in seconds) your app was in the foreground or your website had focus in the browser.",
+    category: "engagement",
+    format: "duration",
+    apiField: "userEngagementDuration",
+    type: "api"
+  },
+  {
+    key: "scrolledUsers",
+    name: "Scrolled Users",
+    description: "The number of unique users who scrolled down at least 90% of the page.",
+    category: "engagement",
+    format: "number",
+    apiField: "scrolledUsers",
+    type: "api"
+  }
+];
+var REVENUE_METRICS = [
+  {
+    key: "totalRevenue",
+    name: "Total Revenue",
+    description: "The sum of revenue from purchases, subscriptions, and advertising (purchase revenue plus subscription revenue plus ad revenue).",
+    category: "revenue",
+    format: "currency",
+    apiField: "totalRevenue",
+    type: "api"
+  },
+  {
+    key: "purchaseRevenue",
+    name: "Purchase Revenue",
+    description: "The sum of revenue from purchases made on your site or app.",
+    category: "revenue",
+    format: "currency",
+    apiField: "purchaseRevenue",
+    type: "api"
+  },
+  {
+    key: "ecommercePurchases",
+    name: "Purchases",
+    description: "The number of times users completed a purchase.",
+    category: "revenue",
+    format: "number",
+    apiField: "ecommercePurchases",
+    type: "api"
+  },
+  {
+    key: "transactions",
+    name: "Transactions",
+    description: "The count of transaction events with purchase revenue.",
+    category: "revenue",
+    format: "number",
+    apiField: "transactions",
+    type: "api"
+  },
+  {
+    key: "averagePurchaseRevenue",
+    name: "Avg. Purchase Revenue",
+    description: "The average revenue per purchase (total purchase revenue divided by the number of purchases).",
+    category: "revenue",
+    format: "currency",
+    apiField: "averagePurchaseRevenue",
+    type: "api"
+  },
+  {
+    key: "averageRevenuePerUser",
+    name: "ARPU",
+    description: "Average revenue per user (total revenue divided by total users).",
+    category: "revenue",
+    format: "currency",
+    apiField: "averageRevenuePerUser",
+    type: "api"
+  },
+  {
+    key: "itemRevenue",
+    name: "Item Revenue",
+    description: "The total revenue from items only (product sales revenue).",
+    category: "revenue",
+    format: "currency",
+    apiField: "itemRevenue",
+    type: "api"
+  },
+  {
+    key: "itemsPurchased",
+    name: "Items Purchased",
+    description: "The number of units purchased across all items.",
+    category: "revenue",
+    format: "number",
+    apiField: "itemsPurchased",
+    type: "api"
+  },
+  {
+    key: "refundAmount",
+    name: "Refund Amount",
+    description: "The total amount of refunds issued.",
+    category: "revenue",
+    format: "currency",
+    apiField: "refundAmount",
+    type: "api"
+  },
+  {
+    key: "shippingAmount",
+    name: "Shipping Amount",
+    description: "The total shipping amount associated with transactions.",
+    category: "revenue",
+    format: "currency",
+    apiField: "shippingAmount",
+    type: "api"
+  },
+  {
+    key: "taxAmount",
+    name: "Tax Amount",
+    description: "The total tax amount associated with transactions.",
+    category: "revenue",
+    format: "currency",
+    apiField: "taxAmount",
+    type: "api"
+  }
+];
+var ECOMMERCE_METRICS = [
+  {
+    key: "addToCarts",
+    name: "Add to Carts",
+    description: "The number of times users added items to their shopping carts.",
+    category: "ecommerce",
+    format: "number",
+    apiField: "addToCarts",
+    type: "api"
+  },
+  {
+    key: "checkouts",
+    name: "Checkouts",
+    description: "The number of times users started the checkout process.",
+    category: "ecommerce",
+    format: "number",
+    apiField: "checkouts",
+    type: "api"
+  },
+  {
+    key: "itemsViewed",
+    name: "Items Viewed",
+    description: "The number of items viewed by users.",
+    category: "ecommerce",
+    format: "number",
+    apiField: "itemsViewed",
+    type: "api"
+  },
+  {
+    key: "itemsAddedToCart",
+    name: "Items Added to Cart",
+    description: "The number of units added to cart across all items.",
+    category: "ecommerce",
+    format: "number",
+    apiField: "itemsAddedToCart",
+    type: "api"
+  },
+  {
+    key: "itemsCheckedOut",
+    name: "Items Checked Out",
+    description: "The number of units included in checkout across all items.",
+    category: "ecommerce",
+    format: "number",
+    apiField: "itemsCheckedOut",
+    type: "api"
+  },
+  {
+    key: "cartToViewRate",
+    name: "Cart-to-View Rate",
+    description: "The percentage of users who added items to their cart after viewing them.",
+    category: "ecommerce",
+    format: "percent",
+    apiField: "cartToViewRate",
+    type: "api"
+  },
+  {
+    key: "purchaseToViewRate",
+    name: "Purchase-to-View Rate",
+    description: "The percentage of users who purchased items after viewing them.",
+    category: "ecommerce",
+    format: "percent",
+    apiField: "purchaseToViewRate",
+    type: "api"
+  },
+  {
+    key: "itemViewEvents",
+    name: "Item View Events",
+    description: "The number of times item details were viewed (view_item events).",
+    category: "ecommerce",
+    format: "number",
+    apiField: "itemViewEvents",
+    type: "api"
+  },
+  {
+    key: "itemListClickEvents",
+    name: "Item List Click Events",
+    description: "The number of times users clicked an item in an item list (select_item events).",
+    category: "ecommerce",
+    format: "number",
+    apiField: "itemListClickEvents",
+    type: "api"
+  },
+  {
+    key: "itemListViewEvents",
+    name: "Item List View Events",
+    description: "The number of times an item list was viewed (view_item_list events).",
+    category: "ecommerce",
+    format: "number",
+    apiField: "itemListViewEvents",
+    type: "api"
+  },
+  {
+    key: "itemListClickThroughRate",
+    name: "Item List CTR",
+    description: "The percentage of users who clicked through after viewing an item list.",
+    category: "ecommerce",
+    format: "percent",
+    apiField: "itemListClickThroughRate",
+    type: "api"
+  },
+  {
+    key: "itemPromotionClickThroughRate",
+    name: "Promotion CTR",
+    description: "The percentage of users who clicked through after viewing an item promotion.",
+    category: "ecommerce",
+    format: "percent",
+    apiField: "itemPromotionClickThroughRate",
+    type: "api"
+  }
+];
+var CONVERSION_METRICS = [
+  {
+    key: "conversions",
+    name: "Conversions",
+    description: "The total count of conversion events.",
+    category: "conversions",
+    format: "number",
+    apiField: "conversions",
+    type: "api"
+  },
+  {
+    key: "keyEvents",
+    name: "Key Events",
+    description: "The count of key events (formerly conversions) triggered by users.",
+    category: "conversions",
+    format: "number",
+    apiField: "keyEvents",
+    type: "api"
+  },
+  {
+    key: "firstTimePurchasers",
+    name: "First-time Purchasers",
+    description: "The number of users who completed their first purchase.",
+    category: "conversions",
+    format: "number",
+    apiField: "firstTimePurchasers",
+    type: "api"
+  },
+  {
+    key: "firstTimePurchaserRate",
+    name: "First-time Purchaser Rate",
+    description: "The percentage of active users who made their first purchase.",
+    category: "conversions",
+    format: "percent",
+    apiField: "firstTimePurchaserConversionRate",
+    type: "api"
+  }
+];
+var ADS_METRICS = [
+  {
+    key: "publisherAdClicks",
+    name: "Publisher Ad Clicks",
+    description: "The number of times users clicked on an ad served by a publisher on your site or app.",
+    category: "ads",
+    format: "number",
+    apiField: "publisherAdClicks",
+    type: "api"
+  },
+  {
+    key: "publisherAdImpressions",
+    name: "Publisher Ad Impressions",
+    description: "The number of ad impressions served by a publisher on your site or app.",
+    category: "ads",
+    format: "number",
+    apiField: "publisherAdImpressions",
+    type: "api"
+  },
+  {
+    key: "totalAdRevenue",
+    name: "Total Ad Revenue",
+    description: "The total revenue earned from ads served on your site or app.",
+    category: "ads",
+    format: "currency",
+    apiField: "totalAdRevenue",
+    type: "api"
+  },
+  {
+    key: "returnOnAdSpend",
+    name: "Return on Ad Spend",
+    description: "The return on ad spend (total revenue divided by advertiser ad cost).",
+    category: "ads",
+    format: "ratio",
+    apiField: "returnOnAdSpend",
+    type: "api"
+  }
+];
+var USER_METRICS = [
+  {
+    key: "dauPerMau",
+    name: "DAU/MAU",
+    description: "The rolling ratio of daily active users to monthly active users. A measure of user stickiness.",
+    category: "user",
+    format: "ratio",
+    apiField: "dauPerMau",
+    type: "api"
+  },
+  {
+    key: "dauPerWau",
+    name: "DAU/WAU",
+    description: "The rolling ratio of daily active users to weekly active users.",
+    category: "user",
+    format: "ratio",
+    apiField: "dauPerWau",
+    type: "api"
+  },
+  {
+    key: "wauPerMau",
+    name: "WAU/MAU",
+    description: "The rolling ratio of weekly active users to monthly active users.",
+    category: "user",
+    format: "ratio",
+    apiField: "wauPerMau",
+    type: "api"
+  },
+  {
+    key: "crashFreeUsersRate",
+    name: "Crash-free Users Rate",
+    description: "The percentage of users who did not experience a crash during the selected time period.",
+    category: "user",
+    format: "percent",
+    apiField: "crashFreeUsersRate",
+    type: "api"
+  }
+];
+var GA4_METRIC_CATALOG = [
+  ...TRAFFIC_METRICS,
+  ...ENGAGEMENT_METRICS,
+  ...REVENUE_METRICS,
+  ...ECOMMERCE_METRICS,
+  ...CONVERSION_METRICS,
+  ...ADS_METRICS,
+  ...USER_METRICS
+];
+function getMetricByKey(key) {
+  return GA4_METRIC_CATALOG.find((m) => m.key === key || m.apiField === key);
+}
+
+// src/platforms/ga4/dimension-catalog.ts
+var TIME_DIMENSIONS = [
+  {
+    key: "date",
+    name: "Date",
+    description: "The date of the event (YYYYMMDD format)",
+    category: "time",
+    apiField: "date"
+  },
+  {
+    key: "dateHour",
+    name: "Date + Hour",
+    description: "The combined date and hour of the event (YYYYMMDDHH format)",
+    category: "time",
+    apiField: "dateHour"
+  },
+  {
+    key: "dayOfWeek",
+    name: "Day of Week",
+    description: "The day of the week as a number (0 = Sunday through 6 = Saturday)",
+    category: "time",
+    apiField: "dayOfWeek"
+  },
+  {
+    key: "dayOfWeekName",
+    name: "Day Name",
+    description: "The name of the day of the week (e.g., Sunday, Monday)",
+    category: "time",
+    apiField: "dayOfWeekName"
+  },
+  {
+    key: "month",
+    name: "Month",
+    description: "The month of the event (two-digit number, 01-12)",
+    category: "time",
+    apiField: "month"
+  },
+  {
+    key: "year",
+    name: "Year",
+    description: "The four-digit year of the event (e.g., 2026)",
+    category: "time",
+    apiField: "year"
+  },
+  {
+    key: "nthDay",
+    name: "Nth Day",
+    description: "The number of days since the start of the date range",
+    category: "time",
+    apiField: "nthDay"
+  },
+  {
+    key: "hour",
+    name: "Hour",
+    description: "The hour of the event (two-digit number, 00-23)",
+    category: "time",
+    apiField: "hour"
+  },
+  {
+    key: "isoWeek",
+    name: "ISO Week",
+    description: "The ISO week number of the year (01-53)",
+    category: "time",
+    apiField: "isoWeek"
+  },
+  {
+    key: "isoYearIsoWeek",
+    name: "Year + ISO Week",
+    description: "The combined ISO year and ISO week number (e.g., 202610)",
+    category: "time",
+    apiField: "isoYearIsoWeek"
+  },
+  {
+    key: "yearMonth",
+    name: "Year + Month",
+    description: "The combined year and month of the event (YYYYMM format)",
+    category: "time",
+    apiField: "yearMonth"
+  }
+];
+var TRAFFIC_SOURCE_DIMENSIONS = [
+  {
+    key: "sessionSource",
+    name: "Session Source",
+    description: "The source that initiated the session (e.g., google, facebook, direct)",
+    category: "traffic_source",
+    apiField: "sessionSource"
+  },
+  {
+    key: "sessionMedium",
+    name: "Session Medium",
+    description: "The medium of the session (e.g., organic, cpc, referral, email)",
+    category: "traffic_source",
+    apiField: "sessionMedium"
+  },
+  {
+    key: "sessionCampaignName",
+    name: "Session Campaign",
+    description: "The campaign name associated with the session",
+    category: "traffic_source",
+    apiField: "sessionCampaignName"
+  },
+  {
+    key: "sessionDefaultChannelGroup",
+    name: "Session Default Channel Group",
+    description: "The default channel grouping for the session (e.g., Organic Search, Paid Search, Direct)",
+    category: "traffic_source",
+    apiField: "sessionDefaultChannelGroup"
+  },
+  {
+    key: "sessionPrimaryChannelGroup",
+    name: "Session Primary Channel Group (Custom)",
+    description: "The custom/primary channel group for the session. Uses custom channel group rules configured in GA4 Admin. Use this dimension (not sessionDefaultChannelGroup) when the user asks for custom or personalized channel groups.",
+    category: "traffic_source",
+    apiField: "sessionPrimaryChannelGroup"
+  },
+  {
+    key: "sessionSourceMedium",
+    name: "Session Source / Medium",
+    description: "The combined source and medium of the session (e.g., google / organic)",
+    category: "traffic_source",
+    apiField: "sessionSourceMedium"
+  },
+  {
+    key: "firstUserSource",
+    name: "First User Source",
+    description: "The source that first acquired the user",
+    category: "traffic_source",
+    apiField: "firstUserSource"
+  },
+  {
+    key: "firstUserMedium",
+    name: "First User Medium",
+    description: "The medium that first acquired the user",
+    category: "traffic_source",
+    apiField: "firstUserMedium"
+  },
+  {
+    key: "firstUserCampaignName",
+    name: "First User Campaign",
+    description: "The campaign that first acquired the user",
+    category: "traffic_source",
+    apiField: "firstUserCampaignName"
+  },
+  {
+    key: "firstUserDefaultChannelGroup",
+    name: "First User Default Channel Group",
+    description: "The default channel grouping that first acquired the user",
+    category: "traffic_source",
+    apiField: "firstUserDefaultChannelGroup"
+  },
+  {
+    key: "firstUserPrimaryChannelGroup",
+    name: "First User Primary Channel Group (Custom)",
+    description: "The custom/primary channel group that first acquired the user. Uses custom channel group rules configured in GA4 Admin.",
+    category: "traffic_source",
+    apiField: "firstUserPrimaryChannelGroup"
+  },
+  {
+    key: "firstUserSourceMedium",
+    name: "First User Source / Medium",
+    description: "The combined source and medium that first acquired the user",
+    category: "traffic_source",
+    apiField: "firstUserSourceMedium"
+  }
+];
+var GEOGRAPHY_DIMENSIONS = [
+  {
+    key: "country",
+    name: "Country",
+    description: "The country from which the user activity originated",
+    category: "geography",
+    apiField: "country"
+  },
+  {
+    key: "city",
+    name: "City",
+    description: "The city from which the user activity originated",
+    category: "geography",
+    apiField: "city"
+  },
+  {
+    key: "region",
+    name: "Region",
+    description: "The geographic region (state/province) from which the user activity originated",
+    category: "geography",
+    apiField: "region"
+  },
+  {
+    key: "continent",
+    name: "Continent",
+    description: "The continent from which the user activity originated",
+    category: "geography",
+    apiField: "continent"
+  },
+  {
+    key: "countryId",
+    name: "Country ID",
+    description: "The ISO 3166 country code (e.g., US, GB, FR)",
+    category: "geography",
+    apiField: "countryId"
+  },
+  {
+    key: "subContinent",
+    name: "Sub Continent",
+    description: "The sub-continent from which the user activity originated (e.g., Northern America, Western Europe)",
+    category: "geography",
+    apiField: "subContinent"
+  }
+];
+var DEVICE_DIMENSIONS = [
+  {
+    key: "deviceCategory",
+    name: "Device Category",
+    description: "The type of device (desktop, mobile, or tablet)",
+    category: "device",
+    apiField: "deviceCategory"
+  },
+  {
+    key: "operatingSystem",
+    name: "Operating System",
+    description: "The operating system used by the visitor (e.g., Android, iOS, Windows, Macintosh)",
+    category: "device",
+    apiField: "operatingSystem"
+  },
+  {
+    key: "browser",
+    name: "Browser",
+    description: "The browser used by the visitor (e.g., Chrome, Safari, Firefox, Edge)",
+    category: "device",
+    apiField: "browser"
+  },
+  {
+    key: "screenResolution",
+    name: "Screen Resolution",
+    description: "The screen resolution of the user's device (e.g., 1920x1080)",
+    category: "device",
+    apiField: "screenResolution"
+  },
+  {
+    key: "mobileDeviceModel",
+    name: "Mobile Device Model",
+    description: "The model name of the mobile device (e.g., iPhone 15, Pixel 8)",
+    category: "device",
+    apiField: "mobileDeviceModel"
+  },
+  {
+    key: "mobileDeviceBranding",
+    name: "Mobile Device Brand",
+    description: "The brand or manufacturer of the mobile device (e.g., Apple, Samsung, Google)",
+    category: "device",
+    apiField: "mobileDeviceBranding"
+  },
+  {
+    key: "platform",
+    name: "Platform",
+    description: "The platform on which the app or website was accessed (web, iOS, Android)",
+    category: "device",
+    apiField: "platform"
+  },
+  {
+    key: "language",
+    name: "Language",
+    description: "The language setting of the user's browser or device (e.g., en-us, fr, de)",
+    category: "device",
+    apiField: "language"
+  }
+];
+var PAGE_DIMENSIONS = [
+  {
+    key: "pagePath",
+    name: "Page Path",
+    description: "The URL path of the page (without query string or hostname)",
+    category: "page",
+    apiField: "pagePath"
+  },
+  {
+    key: "pageTitle",
+    name: "Page Title",
+    description: "The title of the page as set in the HTML <title> tag",
+    category: "page",
+    apiField: "pageTitle"
+  },
+  {
+    key: "landingPage",
+    name: "Landing Page",
+    description: "The page path of the first page viewed in a session",
+    category: "page",
+    apiField: "landingPage"
+  },
+  {
+    key: "hostname",
+    name: "Hostname",
+    description: "The hostname of the URL (e.g., www.example.com)",
+    category: "page",
+    apiField: "hostname"
+  },
+  {
+    key: "pageReferrer",
+    name: "Page Referrer",
+    description: "The full referring URL including hostname and path",
+    category: "page",
+    apiField: "pageReferrer"
+  },
+  {
+    key: "landingPagePlusQueryString",
+    name: "Landing Page + Query",
+    description: "The landing page path including the query string parameters",
+    category: "page",
+    apiField: "landingPagePlusQueryString"
+  },
+  {
+    key: "pagePathPlusQueryString",
+    name: "Page Path + Query",
+    description: "The page path including the query string parameters",
+    category: "page",
+    apiField: "pagePathPlusQueryString"
+  }
+];
+var EVENT_DIMENSIONS = [
+  {
+    key: "eventName",
+    name: "Event Name",
+    description: "The name of the event (e.g., page_view, purchase, click, scroll)",
+    category: "event",
+    apiField: "eventName"
+  },
+  {
+    key: "isConversionEvent",
+    name: "Is Conversion Event",
+    description: "Whether the event is marked as a conversion (true or false)",
+    category: "event",
+    apiField: "isConversionEvent"
+  }
+];
+var ECOMMERCE_DIMENSIONS = [
+  {
+    key: "itemId",
+    name: "Item ID",
+    description: "The ID of the ecommerce item",
+    category: "ecommerce",
+    apiField: "itemId"
+  },
+  {
+    key: "itemName",
+    name: "Item Name",
+    description: "The name of the ecommerce item",
+    category: "ecommerce",
+    apiField: "itemName"
+  },
+  {
+    key: "itemBrand",
+    name: "Item Brand",
+    description: "The brand of the ecommerce item",
+    category: "ecommerce",
+    apiField: "itemBrand"
+  },
+  {
+    key: "itemCategory",
+    name: "Item Category",
+    description: "The primary category of the ecommerce item",
+    category: "ecommerce",
+    apiField: "itemCategory"
+  },
+  {
+    key: "itemCategory2",
+    name: "Item Category 2",
+    description: "The second-level category of the ecommerce item",
+    category: "ecommerce",
+    apiField: "itemCategory2"
+  },
+  {
+    key: "itemCategory3",
+    name: "Item Category 3",
+    description: "The third-level category of the ecommerce item",
+    category: "ecommerce",
+    apiField: "itemCategory3"
+  },
+  {
+    key: "itemVariant",
+    name: "Item Variant",
+    description: "The variant of the ecommerce item (e.g., size, color)",
+    category: "ecommerce",
+    apiField: "itemVariant"
+  },
+  {
+    key: "itemListName",
+    name: "Item List Name",
+    description: "The name of the list in which the item was presented to the user",
+    category: "ecommerce",
+    apiField: "itemListName"
+  },
+  {
+    key: "itemPromotionName",
+    name: "Item Promotion Name",
+    description: "The name of the promotion applied to the ecommerce item",
+    category: "ecommerce",
+    apiField: "itemPromotionName"
+  },
+  {
+    key: "transactionId",
+    name: "Transaction ID",
+    description: "The unique identifier of the ecommerce transaction",
+    category: "ecommerce",
+    apiField: "transactionId"
+  },
+  {
+    key: "orderCoupon",
+    name: "Order Coupon",
+    description: "The coupon code applied to the order",
+    category: "ecommerce",
+    apiField: "orderCoupon"
+  },
+  {
+    key: "shippingTier",
+    name: "Shipping Tier",
+    description: "The shipping tier selected for the order (e.g., Ground, Express, Next Day)",
+    category: "ecommerce",
+    apiField: "shippingTier"
+  }
+];
+var USER_DIMENSIONS = [
+  {
+    key: "newVsReturning",
+    name: "New vs Returning",
+    description: "Whether the user is new or returning to the property",
+    category: "user",
+    apiField: "newVsReturning"
+  },
+  {
+    key: "userAgeBracket",
+    name: "User Age Bracket",
+    description: "The age bracket of the user (e.g., 18-24, 25-34, 35-44)",
+    category: "user",
+    apiField: "userAgeBracket"
+  },
+  {
+    key: "userGender",
+    name: "User Gender",
+    description: "The gender of the user (male, female)",
+    category: "user",
+    apiField: "userGender"
+  },
+  {
+    key: "audienceName",
+    name: "Audience Name",
+    description: "The name of the audience the user belongs to",
+    category: "user",
+    apiField: "audienceName"
+  }
+];
+var GA4_DIMENSION_CATALOG = [
+  ...TIME_DIMENSIONS,
+  ...TRAFFIC_SOURCE_DIMENSIONS,
+  ...GEOGRAPHY_DIMENSIONS,
+  ...DEVICE_DIMENSIONS,
+  ...PAGE_DIMENSIONS,
+  ...EVENT_DIMENSIONS,
+  ...ECOMMERCE_DIMENSIONS,
+  ...USER_DIMENSIONS
+];
+function getDimensionByKey(key) {
+  return GA4_DIMENSION_CATALOG.find((d) => d.key === key || d.apiField === key);
+}
+
+// src/platforms/ga4/compatibility-rules.ts
+var ECOMMERCE_ONLY_DIMENSIONS = /* @__PURE__ */ new Set([
+  "itemId",
+  "itemName",
+  "itemBrand",
+  "itemCategory",
+  "itemCategory2",
+  "itemCategory3",
+  "itemVariant",
+  "itemListName",
+  "itemListId",
+  "itemPromotionName",
+  "itemPromotionId",
+  "orderCoupon",
+  "shippingTier",
+  "itemAffiliation",
+  "transactionId"
+]);
+var ECOMMERCE_METRICS2 = /* @__PURE__ */ new Set([
+  "addToCarts",
+  "checkouts",
+  "ecommercePurchases",
+  "itemRevenue",
+  "itemsPurchased",
+  "itemsViewed",
+  "itemsAddedToCart",
+  "itemsCheckedOut",
+  "cartToViewRate",
+  "purchaseToViewRate",
+  "itemViewEvents",
+  "itemListClickEvents",
+  "itemListViewEvents",
+  "itemListClickThroughRate",
+  "itemPromotionClickThroughRate",
+  "totalRevenue",
+  "purchaseRevenue",
+  "averagePurchaseRevenue",
+  "transactions",
+  "refundAmount",
+  "shippingAmount",
+  "taxAmount"
+]);
+var INCOMPATIBLE_DIMENSION_PAIRS = [
+  // Session-scoped vs user-scoped source dimensions
+  ["sessionSource", "firstUserSource"],
+  ["sessionMedium", "firstUserMedium"],
+  ["sessionCampaignName", "firstUserCampaignName"],
+  ["sessionDefaultChannelGroup", "firstUserDefaultChannelGroup"]
+];
+function validateGA4QuerySelection(metricKeys, dimensionKeys) {
+  const errors = [];
+  const warnings = [];
+  const hasEcommerceDimensions = dimensionKeys.some((d) => ECOMMERCE_ONLY_DIMENSIONS.has(d));
+  const hasEcommerceMetrics = metricKeys.some((m) => ECOMMERCE_METRICS2.has(m));
+  if (hasEcommerceDimensions && !hasEcommerceMetrics) {
+    warnings.push(
+      "Ecommerce dimensions (itemName, itemBrand, etc.) require ecommerce metrics to return data. Add metrics like itemRevenue, addToCarts, or ecommercePurchases."
+    );
+  }
+  for (const [dim1, dim2] of INCOMPATIBLE_DIMENSION_PAIRS) {
+    if (dimensionKeys.includes(dim1) && dimensionKeys.includes(dim2)) {
+      warnings.push(
+        `Dimensions "${dim1}" and "${dim2}" are session-scoped vs user-scoped. Using both may produce unexpected results.`
+      );
+    }
+  }
+  const highCardinalityDims = ["pagePath", "pageTitle", "pagePathPlusQueryString", "landingPagePlusQueryString"];
+  const hasHighCardinality = dimensionKeys.some((d) => highCardinalityDims.includes(d));
+  if (hasHighCardinality && dimensionKeys.length > 2) {
+    warnings.push(
+      "High-cardinality dimensions (pagePath, pageTitle) combined with other dimensions may produce very large result sets."
+    );
+  }
+  if (metricKeys.length === 0) {
+    errors.push("At least one metric is required.");
+  }
+  if (dimensionKeys.length > 9) {
+    errors.push(
+      `GA4 supports a maximum of 9 dimensions per request. You selected ${dimensionKeys.length}.`
+    );
+  }
+  if (metricKeys.length > 10) {
+    errors.push(
+      `GA4 supports a maximum of 10 metrics per request. You selected ${metricKeys.length}.`
+    );
+  }
+  const timeDimensions = ["date", "dateHour", "dayOfWeek", "month", "year", "hour", "nthDay", "isoWeek", "yearMonth"];
+  if (!dimensionKeys.some((d) => timeDimensions.includes(d))) {
+    warnings.push(
+      "No time dimension selected. Results will be aggregated over the entire date range."
+    );
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+// src/platforms/ga4/calculated-metrics.ts
+var GA4_CALCULATED_METRIC_DEFINITIONS = [
+  {
+    key: "revenuePerSession",
+    name: "Revenue per Session",
+    description: "Total revenue divided by total sessions",
+    category: "calculated",
+    format: "currency",
+    apiField: "",
+    type: "calculated",
+    formula: "totalRevenue / sessions",
+    dependencies: ["totalRevenue", "sessions"]
+  },
+  {
+    key: "conversionRate",
+    name: "Conversion Rate",
+    description: "Conversions divided by sessions (percentage)",
+    category: "calculated",
+    format: "percent",
+    apiField: "",
+    type: "calculated",
+    formula: "(conversions / sessions) * 100",
+    dependencies: ["conversions", "sessions"]
+  },
+  {
+    key: "pagesPerSession",
+    name: "Pages per Session",
+    description: "Page views divided by sessions",
+    category: "calculated",
+    format: "ratio",
+    apiField: "",
+    type: "calculated",
+    formula: "screenPageViews / sessions",
+    dependencies: ["screenPageViews", "sessions"]
+  },
+  {
+    key: "aov",
+    name: "Average Order Value",
+    description: "Purchase revenue divided by number of purchases",
+    category: "calculated",
+    format: "currency",
+    apiField: "",
+    type: "calculated",
+    formula: "purchaseRevenue / ecommercePurchases",
+    dependencies: ["purchaseRevenue", "ecommercePurchases"]
+  },
+  {
+    key: "revenuePerUser",
+    name: "Revenue per User",
+    description: "Total revenue divided by total users",
+    category: "calculated",
+    format: "currency",
+    apiField: "",
+    type: "calculated",
+    formula: "totalRevenue / totalUsers",
+    dependencies: ["totalRevenue", "totalUsers"]
+  },
+  {
+    key: "addToCartRate",
+    name: "Add to Cart Rate",
+    description: "Add to carts divided by sessions (percentage)",
+    category: "calculated",
+    format: "percent",
+    apiField: "",
+    type: "calculated",
+    formula: "(addToCarts / sessions) * 100",
+    dependencies: ["addToCarts", "sessions"]
+  },
+  {
+    key: "checkoutRate",
+    name: "Checkout Rate",
+    description: "Checkouts divided by sessions (percentage)",
+    category: "calculated",
+    format: "percent",
+    apiField: "",
+    type: "calculated",
+    formula: "(checkouts / sessions) * 100",
+    dependencies: ["checkouts", "sessions"]
+  },
+  {
+    key: "purchaseRate",
+    name: "Purchase Rate",
+    description: "Purchases divided by sessions (percentage)",
+    category: "calculated",
+    format: "percent",
+    apiField: "",
+    type: "calculated",
+    formula: "(ecommercePurchases / sessions) * 100",
+    dependencies: ["ecommercePurchases", "sessions"]
+  },
+  {
+    key: "cartAbandonmentRate",
+    name: "Cart Abandonment Rate",
+    description: "Percentage of checkouts not completed as purchases",
+    category: "calculated",
+    format: "percent",
+    apiField: "",
+    type: "calculated",
+    formula: "(1 - ecommercePurchases / checkouts) * 100",
+    dependencies: ["ecommercePurchases", "checkouts"]
+  }
+];
+function calcRevenuePerSession(row) {
+  const revenue = row["totalRevenue"];
+  const sessions = row["sessions"];
+  if (typeof revenue !== "number" || typeof sessions !== "number") return null;
+  if (sessions <= 0) return null;
+  return revenue / sessions;
+}
+function calcConversionRate(row) {
+  const conversions = row["conversions"] ?? row["keyEvents"];
+  const sessions = row["sessions"];
+  if (typeof conversions !== "number" || typeof sessions !== "number") return null;
+  if (sessions <= 0) return null;
+  return conversions / sessions * 100;
+}
+function calcPagesPerSession(row) {
+  const pageViews = row["screenPageViews"];
+  const sessions = row["sessions"];
+  if (typeof pageViews !== "number" || typeof sessions !== "number") return null;
+  if (sessions <= 0) return null;
+  return pageViews / sessions;
+}
+function calcAov(row) {
+  const revenue = row["purchaseRevenue"] ?? row["totalRevenue"];
+  const purchases = row["ecommercePurchases"] ?? row["transactions"];
+  if (typeof revenue !== "number" || typeof purchases !== "number") return null;
+  if (purchases <= 0) return null;
+  return revenue / purchases;
+}
+function calcRevenuePerUser(row) {
+  const revenue = row["totalRevenue"];
+  const users = row["totalUsers"];
+  if (typeof revenue !== "number" || typeof users !== "number") return null;
+  if (users <= 0) return null;
+  return revenue / users;
+}
+function calcAddToCartRate(row) {
+  const addToCarts = row["addToCarts"];
+  const sessions = row["sessions"];
+  if (typeof addToCarts !== "number" || typeof sessions !== "number") return null;
+  if (sessions <= 0) return null;
+  return addToCarts / sessions * 100;
+}
+function calcCheckoutRate(row) {
+  const checkouts = row["checkouts"];
+  const sessions = row["sessions"];
+  if (typeof checkouts !== "number" || typeof sessions !== "number") return null;
+  if (sessions <= 0) return null;
+  return checkouts / sessions * 100;
+}
+function calcPurchaseRate(row) {
+  const purchases = row["ecommercePurchases"];
+  const sessions = row["sessions"];
+  if (typeof purchases !== "number" || typeof sessions !== "number") return null;
+  if (sessions <= 0) return null;
+  return purchases / sessions * 100;
+}
+function calcCartAbandonmentRate(row) {
+  const purchases = row["ecommercePurchases"];
+  const checkouts = row["checkouts"];
+  if (typeof purchases !== "number" || typeof checkouts !== "number") return null;
+  if (checkouts <= 0) return null;
+  return (1 - purchases / checkouts) * 100;
+}
+function calculateMetrics(row) {
+  return {
+    revenuePerSession: calcRevenuePerSession(row),
+    conversionRate: calcConversionRate(row),
+    pagesPerSession: calcPagesPerSession(row),
+    aov: calcAov(row),
+    revenuePerUser: calcRevenuePerUser(row),
+    addToCartRate: calcAddToCartRate(row),
+    checkoutRate: calcCheckoutRate(row),
+    purchaseRate: calcPurchaseRate(row),
+    cartAbandonmentRate: calcCartAbandonmentRate(row)
+  };
+}
+function enrichWithCalculatedMetrics(rows, requestedCalculated) {
+  const requested = requestedCalculated ? new Set(requestedCalculated) : null;
+  return rows.map((row) => {
+    const all = calculateMetrics(row);
+    const picked = {};
+    for (const [key, value] of Object.entries(all)) {
+      if (value === null) continue;
+      if (requested && !requested.has(key)) continue;
+      picked[key] = Math.round(value * 100) / 100;
+    }
+    return { ...row, ...picked };
+  });
+}
+function getCalculatedMetricDependencies(metricKeys) {
+  const deps = /* @__PURE__ */ new Set();
+  for (const key of metricKeys) {
+    const def = GA4_CALCULATED_METRIC_DEFINITIONS.find((m) => m.key === key);
+    if (def?.dependencies) {
+      for (const dep of def.dependencies) {
+        deps.add(dep);
+      }
+    }
+  }
+  return Array.from(deps);
+}
+function isCalculatedMetric(key) {
+  return GA4_CALCULATED_METRIC_DEFINITIONS.some((m) => m.key === key);
+}
+
+// src/platforms/ga4/filter-catalog.ts
+function buildStringFilter(fieldName, matchType, value, caseSensitive = false) {
+  return {
+    filter: {
+      fieldName,
+      stringFilter: {
+        matchType,
+        value,
+        caseSensitive
+      }
+    }
+  };
+}
+function buildInListFilter(fieldName, values, caseSensitive = false) {
+  return {
+    filter: {
+      fieldName,
+      inListFilter: {
+        values,
+        caseSensitive
+      }
+    }
+  };
+}
+function buildNumericFilter(fieldName, operation, value) {
+  return {
+    filter: {
+      fieldName,
+      numericFilter: {
+        operation,
+        value: { doubleValue: value }
+      }
+    }
+  };
+}
+function buildAndFilter(expressions) {
+  if (expressions.length === 1) return expressions[0];
+  return { andGroup: { expressions } };
+}
+function buildFilterFromParams(filters) {
+  if (filters.length === 0) return void 0;
+  const expressions = filters.map((f) => {
+    const op = f.operator.toUpperCase();
+    if (op === "IN" && Array.isArray(f.value)) {
+      return buildInListFilter(f.field, f.value.map(String));
+    }
+    if (["GREATER_THAN", "LESS_THAN", "EQUAL", "GREATER_THAN_OR_EQUAL", "LESS_THAN_OR_EQUAL"].includes(op)) {
+      return buildNumericFilter(f.field, op, Number(f.value));
+    }
+    const matchType = op === "CONTAINS" ? "CONTAINS" : op === "BEGINS_WITH" ? "BEGINS_WITH" : op === "ENDS_WITH" ? "ENDS_WITH" : op === "REGEXP" || op === "FULL_REGEXP" ? "FULL_REGEXP" : op === "PARTIAL_REGEXP" ? "PARTIAL_REGEXP" : "EXACT";
+    return buildStringFilter(f.field, matchType, String(f.value));
+  });
+  return buildAndFilter(expressions);
+}
+
+// src/platforms/ga4/query-planner.ts
+function planGA4Query(params) {
+  const warnings = [];
+  const errors = [];
+  const calculatedMetrics = [];
+  const apiMetricKeys = [];
+  for (const key of params.metrics) {
+    if (isCalculatedMetric(key)) {
+      calculatedMetrics.push(key);
+    } else {
+      apiMetricKeys.push(key);
+    }
+  }
+  if (calculatedMetrics.length > 0) {
+    const deps = getCalculatedMetricDependencies(calculatedMetrics);
+    for (const dep of deps) {
+      if (!apiMetricKeys.includes(dep)) {
+        apiMetricKeys.push(dep);
+      }
+    }
+  }
+  const apiMetrics = [];
+  for (const key of apiMetricKeys) {
+    const def = getMetricByKey(key);
+    if (def) {
+      apiMetrics.push({ name: def.apiField });
+    } else {
+      apiMetrics.push({ name: key });
+    }
+  }
+  const dimensionKeys = params.dimensions || [];
+  const apiDimensions = [];
+  for (const key of dimensionKeys) {
+    const def = getDimensionByKey(key);
+    if (def) {
+      apiDimensions.push({ name: def.apiField });
+    } else {
+      apiDimensions.push({ name: key });
+    }
+  }
+  const validation = validateGA4QuerySelection(
+    apiMetricKeys,
+    dimensionKeys
+  );
+  errors.push(...validation.errors);
+  warnings.push(...validation.warnings);
+  let dateRanges;
+  if (params.dateRange) {
+    dateRanges = [{
+      startDate: params.dateRange.startDate,
+      endDate: params.dateRange.endDate
+    }];
+  } else if (params.datePreset) {
+    dateRanges = [resolveDatePreset(params.datePreset)];
+  } else {
+    dateRanges = [{ startDate: "28daysAgo", endDate: "today" }];
+  }
+  const orderBys = [];
+  if (params.orderBy) {
+    const metricDef = getMetricByKey(params.orderBy);
+    const dimDef = getDimensionByKey(params.orderBy);
+    if (metricDef) {
+      orderBys.push({
+        metric: { metricName: metricDef.apiField },
+        desc: params.orderDirection !== "ASC"
+      });
+    } else if (dimDef) {
+      orderBys.push({
+        dimension: { dimensionName: dimDef.apiField },
+        desc: params.orderDirection !== "ASC"
+      });
+    } else {
+      orderBys.push({
+        metric: { metricName: params.orderBy },
+        desc: params.orderDirection !== "ASC"
+      });
+    }
+  }
+  let dimensionFilter;
+  if (params.filters && params.filters.length > 0) {
+    dimensionFilter = buildFilterFromParams(params.filters);
+  }
+  const request = {
+    dateRanges,
+    metrics: apiMetrics,
+    ...apiDimensions.length > 0 && { dimensions: apiDimensions },
+    ...dimensionFilter && { dimensionFilter },
+    ...orderBys.length > 0 && { orderBys },
+    ...params.limit && { limit: params.limit },
+    keepEmptyRows: false
+  };
+  return {
+    request,
+    propertyId: params.propertyId,
+    warnings,
+    errors,
+    calculatedMetrics,
+    apiMetrics: apiMetricKeys
+  };
+}
+
+// src/platforms/ga4/surface-tools.ts
+import { z as z2 } from "zod";
+
+// src/platforms/ga4/privacy.ts
+var REDACTED = "[REDACTED]";
+var PERSONAL_IDENTIFIER_KEYS = /* @__PURE__ */ new Set([
+  "user",
+  "userid",
+  "user_id",
+  "email",
+  "emailaddress",
+  "email_address",
+  "username",
+  "deviceid",
+  "device_id",
+  "mobiledeviceid",
+  "mobile_device_id",
+  "googlesignalspseudonymousid",
+  "google_signals_pseudonymous_id"
+]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizedKey(value) {
+  return value.replace(/[-\s]/g, "").toLowerCase();
+}
+function isSensitiveAudienceDimension(name) {
+  const normalized = normalizedKey(name);
+  return PERSONAL_IDENTIFIER_KEYS.has(normalized) || /(?:user|device|pseudonymous|email|username).*id$/.test(normalized) || /^(?:user|device).*identifier$/.test(normalized);
+}
+function redactGA4PersonalIdentifiers(value) {
+  if (Array.isArray(value)) return value.map(redactGA4PersonalIdentifiers);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(Object.entries(value).map(([key, nested]) => [
+    key,
+    PERSONAL_IDENTIFIER_KEYS.has(normalizedKey(key)) ? REDACTED : redactGA4PersonalIdentifiers(nested)
+  ]));
+}
+function redactGA4AudienceExportResponse(response) {
+  const redacted = redactGA4PersonalIdentifiers(response);
+  const audienceExport = isRecord(response.audienceExport) ? response.audienceExport : void 0;
+  const dimensions = Array.isArray(audienceExport?.dimensions) ? audienceExport.dimensions : [];
+  const names = dimensions.map(
+    (dimension) => isRecord(dimension) && typeof dimension.dimensionName === "string" ? dimension.dimensionName : ""
+  );
+  const sensitiveIndexes = /* @__PURE__ */ new Set();
+  if (names.length === 0) {
+    sensitiveIndexes.add(-1);
+  } else {
+    names.forEach((name, index) => {
+      if (!name || isSensitiveAudienceDimension(name)) sensitiveIndexes.add(index);
+    });
+  }
+  if (!Array.isArray(redacted.audienceRows)) return redacted;
+  return {
+    ...redacted,
+    audienceRows: redacted.audienceRows.map((row) => {
+      if (!isRecord(row) || !Array.isArray(row.dimensionValues)) return row;
+      return {
+        ...row,
+        dimensionValues: row.dimensionValues.map((dimensionValue, index) => {
+          if (!sensitiveIndexes.has(-1) && !sensitiveIndexes.has(index)) return dimensionValue;
+          return isRecord(dimensionValue) ? { ...dimensionValue, value: REDACTED } : REDACTED;
+        })
+      };
+    })
+  };
+}
+
+// src/platforms/ga4/surface-tools.ts
+var propertyIdSchema = z2.string().min(1).describe("Numeric GA4 property ID or properties/{id}.");
+var dateRangeSchema = z2.object({
+  startDate: z2.string().min(1).describe("YYYY-MM-DD or a GA4 relative date such as 28daysAgo."),
+  endDate: z2.string().min(1).describe("YYYY-MM-DD or a GA4 relative date such as today.")
+});
+var rawFilterSchema = z2.record(z2.unknown()).describe("Native GA4 FilterExpression JSON.");
+var rawOrderBySchema = z2.record(z2.unknown()).describe("Native GA4 OrderBy JSON.");
+var aggregationSchema = z2.enum(["TOTAL", "MINIMUM", "MAXIMUM", "COUNT"]);
+var reportSchema = z2.object({
+  dateRanges: z2.array(dateRangeSchema).min(1).max(4).optional(),
+  dimensions: z2.array(z2.string().min(1)).max(9).optional().default([]),
+  metrics: z2.array(z2.string().min(1)).min(1).max(10),
+  dimensionFilter: rawFilterSchema.optional(),
+  metricFilter: rawFilterSchema.optional(),
+  orderBys: z2.array(rawOrderBySchema).max(10).optional(),
+  limit: z2.number().int().min(1).max(25e4).optional(),
+  offset: z2.number().int().min(0).optional(),
+  keepEmptyRows: z2.boolean().optional(),
+  metricAggregations: z2.array(aggregationSchema).max(4).optional(),
+  currencyCode: z2.string().length(3).optional(),
+  returnPropertyQuota: z2.boolean().optional().default(true),
+  cohortSpec: z2.record(z2.unknown()).optional().describe("Native GA4 CohortSpec JSON. Omit dateRanges for cohort requests."),
+  comparisons: z2.array(z2.record(z2.unknown())).max(4).optional().describe("Native GA4 Comparison objects.")
+}).refine((report) => Boolean(report.dateRanges?.length || report.cohortSpec), {
+  message: "Provide dateRanges or cohortSpec."
+});
+var pivotSchema = z2.object({
+  fieldNames: z2.array(z2.string().min(1)).min(1).max(9),
+  orderBys: z2.array(rawOrderBySchema).max(10).optional(),
+  offset: z2.number().int().min(0).optional(),
+  limit: z2.number().int().min(1).max(25e4),
+  metricAggregations: z2.array(aggregationSchema).max(4).optional()
+});
+var pivotReportSchema = z2.object({
+  dateRanges: z2.array(dateRangeSchema).min(1).max(4).optional(),
+  dimensions: z2.array(z2.string().min(1)).min(1).max(9),
+  metrics: z2.array(z2.string().min(1)).min(1).max(10),
+  pivots: z2.array(pivotSchema).min(1).max(9),
+  dimensionFilter: rawFilterSchema.optional(),
+  metricFilter: rawFilterSchema.optional(),
+  currencyCode: z2.string().length(3).optional(),
+  keepEmptyRows: z2.boolean().optional(),
+  returnPropertyQuota: z2.boolean().optional().default(true),
+  cohortSpec: z2.record(z2.unknown()).optional().describe("Native GA4 CohortSpec JSON. Omit dateRanges for cohort requests."),
+  comparisons: z2.array(z2.record(z2.unknown())).max(4).optional().describe("Native GA4 Comparison objects.")
+}).refine((report) => Boolean(report.dateRanges?.length || report.cohortSpec), {
+  message: "Provide dateRanges or cohortSpec."
+});
+function ok(data) {
+  const body = typeof data === "object" && data !== null && !Array.isArray(data) ? {
+    ...data,
+    warnings: "warnings" in data ? data.warnings : [],
+    limitations: "limitations" in data ? data.limitations : [],
+    nextActions: "nextActions" in data ? data.nextActions : [],
+    debug: {
+      source: "ga4",
+      apiVersion: "data_api_v1beta/admin_api_v1beta_v1alpha",
+      requestCount: 1,
+      ...data.debug
+    }
+  } : data;
+  return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+}
+function reportRequest(input) {
+  return {
+    dateRanges: input.dateRanges,
+    dimensions: input.dimensions.map((name) => ({ name })),
+    metrics: input.metrics.map((name) => ({ name })),
+    dimensionFilter: input.dimensionFilter,
+    metricFilter: input.metricFilter,
+    orderBys: input.orderBys,
+    limit: input.limit,
+    offset: input.offset,
+    keepEmptyRows: input.keepEmptyRows,
+    metricAggregations: input.metricAggregations,
+    currencyCode: input.currencyCode,
+    returnPropertyQuota: input.returnPropertyQuota,
+    cohortSpec: input.cohortSpec,
+    comparisons: input.comparisons
+  };
+}
+function pivotReportRequest(input) {
+  return {
+    dateRanges: input.dateRanges,
+    dimensions: input.dimensions.map((name) => ({ name })),
+    metrics: input.metrics.map((name) => ({ name })),
+    pivots: input.pivots.map((pivot) => ({
+      ...pivot,
+      orderBys: pivot.orderBys
+    })),
+    dimensionFilter: input.dimensionFilter,
+    metricFilter: input.metricFilter,
+    currencyCode: input.currencyCode,
+    keepEmptyRows: input.keepEmptyRows,
+    returnPropertyQuota: input.returnPropertyQuota,
+    cohortSpec: input.cohortSpec,
+    comparisons: input.comparisons
+  };
+}
+function validatePivotRequest(request) {
+  const errors = [];
+  const declared = new Set(request.dimensions.map(({ name }) => name));
+  const seen = /* @__PURE__ */ new Set();
+  let cellBudget = 1;
+  for (const pivot of request.pivots) {
+    cellBudget *= pivot.limit;
+    for (const field of pivot.fieldNames) {
+      if (!declared.has(field) && field !== "dateRange" && field !== "comparisons") {
+        errors.push(`Pivot field '${field}' is not declared in dimensions.`);
+      }
+      if (seen.has(field)) errors.push(`Pivot field '${field}' appears in more than one pivot.`);
+      seen.add(field);
+    }
+  }
+  if (cellBudget > 25e4) {
+    errors.push(`The product of pivot limits is ${cellBudget}; GA4 allows at most 250,000.`);
+  }
+  return errors;
+}
+function stripProperty(request) {
+  const { property: _property, ...body } = request;
+  return body;
+}
+function registerGA4SurfaceTools(server, client) {
+  server.tool(
+    "ga4_run_pivot_report",
+    "Run a read-only GA4 Data API pivot report with native filters, ordering, quota state, multiple date ranges, and up to 250,000 pivot cells. Every pivot requires an explicit limit.",
+    { propertyId: propertyIdSchema, report: pivotReportSchema },
+    async ({ propertyId, report }) => {
+      try {
+        const request = pivotReportRequest(report);
+        const errors = validatePivotRequest(request);
+        if (errors.length) return ok({ error: "Pivot validation failed", errors });
+        const response = await client.runPivotReport(propertyId, stripProperty(request));
+        return ok({
+          report: response,
+          data: client.flattenResponse(response),
+          rowCount: response.rows?.length ?? 0,
+          propertyQuota: response.propertyQuota
+        });
+      } catch (error) {
+        return formatMcpToolError(error);
+      }
+    }
+  );
+  server.tool(
+    "ga4_batch_run_reports",
+    "Run 1-5 independent read-only GA4 Core reports for the same property in one official Data API batch request.",
+    { propertyId: propertyIdSchema, reports: z2.array(reportSchema).min(1).max(5) },
+    async ({ propertyId, reports }) => {
+      try {
+        const requests = reports.map((report) => stripProperty(reportRequest(report)));
+        const response = await client.batchRunReports(propertyId, requests);
+        const entries = (response.reports ?? []).map((report, index) => ({
+          index,
+          rowCount: report.rowCount ?? report.rows?.length ?? 0,
+          data: client.flattenResponse(report),
+          metadata: report.metadata,
+          totals: report.totals,
+          minimums: report.minimums,
+          maximums: report.maximums,
+          propertyQuota: report.propertyQuota
+        }));
+        return ok({ reports: entries, reportCount: entries.length, kind: response.kind });
+      } catch (error) {
+        return formatMcpToolError(error);
+      }
+    }
+  );
+  server.tool(
+    "ga4_batch_run_pivot_reports",
+    "Run 1-5 independent read-only GA4 pivot reports for the same property in one official Data API batch request.",
+    { propertyId: propertyIdSchema, reports: z2.array(pivotReportSchema).min(1).max(5) },
+    async ({ propertyId, reports }) => {
+      try {
+        const requests = reports.map(pivotReportRequest);
+        const errors = requests.flatMap((request, index) => validatePivotRequest(request).map((error) => `Report ${index}: ${error}`));
+        if (errors.length) return ok({ error: "Pivot validation failed", errors });
+        const response = await client.batchRunPivotReports(
+          propertyId,
+          requests.map((request) => stripProperty(request))
+        );
+        const entries = (response.pivotReports ?? []).map((report, index) => ({
+          index,
+          rowCount: report.rows?.length ?? 0,
+          data: client.flattenResponse(report),
+          report
+        }));
+        return ok({ reports: entries, reportCount: entries.length, kind: response.kind });
+      } catch (error) {
+        return formatMcpToolError(error);
+      }
+    }
+  );
+  server.tool(
+    "ga4_check_compatibility",
+    "Ask the official GA4 Data API which dimensions and metrics are compatible with a proposed Core report selection.",
+    {
+      propertyId: propertyIdSchema,
+      dimensions: z2.array(z2.string().min(1)).max(9).optional().default([]),
+      metrics: z2.array(z2.string().min(1)).max(10).optional().default([]),
+      dimensionFilter: rawFilterSchema.optional(),
+      metricFilter: rawFilterSchema.optional(),
+      compatibilityFilter: z2.enum(["COMPATIBILITY_UNSPECIFIED", "COMPATIBLE", "INCOMPATIBLE"]).optional()
+    },
+    async ({ propertyId, dimensions, metrics, dimensionFilter, metricFilter, compatibilityFilter }) => {
+      try {
+        const response = await client.checkCompatibility(propertyId, {
+          dimensions: dimensions.map((name) => ({ name })),
+          metrics: metrics.map((name) => ({ name })),
+          ...dimensionFilter && { dimensionFilter },
+          ...metricFilter && { metricFilter },
+          ...compatibilityFilter && { compatibilityFilter }
+        });
+        return ok(response);
+      } catch (error) {
+        return formatMcpToolError(error);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_property_quotas_snapshot",
+    "Read the current GA4 Data API property quota snapshot from the official v1alpha endpoint. This does not run a report, but Google still charges one property-quota token to the category with the most remaining quota.",
+    { propertyId: propertyIdSchema },
+    async ({ propertyId }) => {
+      try {
+        const snapshot = await client.getPropertyQuotasSnapshot(propertyId);
+        return ok({ propertyId, snapshot });
+      } catch (error) {
+        return formatMcpToolError(error);
+      }
+    }
+  );
+  server.tool(
+    "ga4_list_accounts",
+    "List raw GA4 Analytics Admin accounts accessible to the authenticated user (read-only, auto-paginated).",
+    { pageSize: z2.number().int().min(1).max(200).optional().default(200) },
+    async ({ pageSize }) => {
+      try {
+        const accounts = await client.listAccounts(pageSize);
+        return ok({ accounts, count: accounts.length });
+      } catch (error) {
+        return formatMcpToolError(error);
+      }
+    }
+  );
+  const adminCollectionNames = Object.keys(GA4_ADMIN_COLLECTIONS);
+  server.tool(
+    "ga4_list_admin_resources",
+    "List an allowlisted GA4 Admin collection in read-only mode: streams, custom definitions, key events, audiences, product links, annotations, channel groups, expanded datasets, subproperty/rollup configuration, and access bindings.",
+    {
+      propertyId: propertyIdSchema,
+      collection: z2.enum(adminCollectionNames),
+      pageSize: z2.number().int().min(1).max(200).optional().default(200),
+      includePersonalIdentifiers: z2.boolean().optional().default(false).describe("Access bindings only. Explicitly include user/email identifiers; false redacts them by default.")
+    },
+    async ({ propertyId, collection, pageSize, includePersonalIdentifiers }) => {
+      try {
+        const resources = await client.listAdminPropertyResources(propertyId, collection, pageSize);
+        const exposesPersonalIdentifiers = collection === "accessBindings";
+        const safeResources = exposesPersonalIdentifiers && !includePersonalIdentifiers ? redactGA4PersonalIdentifiers(resources) : resources;
+        return ok({
+          propertyId,
+          collection,
+          resources: safeResources,
+          count: resources.length,
+          warnings: exposesPersonalIdentifiers && includePersonalIdentifiers ? ["SENSITIVE PERSONAL IDENTIFIERS INCLUDED BY EXPLICIT OPT-IN: access-binding user/email values are present. Restrict storage, sharing, and model output."] : exposesPersonalIdentifiers ? ["Access-binding user/email identifiers were redacted by default. Set includePersonalIdentifiers=true only with explicit authorization."] : []
+        });
+      } catch (error) {
+        return formatMcpToolError(error);
+      }
+    }
+  );
+  const settingNames = [
+    "attributionSettings",
+    "dataRetentionSettings",
+    "googleSignalsSettings",
+    "reportingIdentitySettings",
+    "userProvidedDataSettings"
+  ];
+  server.tool(
+    "ga4_get_property_configuration",
+    "Read GA4 property details plus selected singleton Admin settings (attribution, retention, Google Signals, reporting identity, or user-provided-data settings).",
+    {
+      propertyId: propertyIdSchema,
+      settings: z2.array(z2.enum(settingNames)).max(settingNames.length).optional().default([])
+    },
+    async ({ propertyId, settings }) => {
+      try {
+        const property = await client.getProperty(propertyId);
+        const configuration = {};
+        const warnings = [];
+        for (const setting of [...new Set(settings)]) {
+          try {
+            configuration[setting] = await client.getPropertySetting(propertyId, setting);
+          } catch (error) {
+            warnings.push(`${setting}: ${error instanceof Error ? error.message : String(error)}`);
+          }
+        }
+        return ok({ property, configuration, warnings, debug: { requestCount: 1 + new Set(settings).size } });
+      } catch (error) {
+        return formatMcpToolError(error);
+      }
+    }
+  );
+  server.tool(
+    "ga4_list_audience_exports",
+    "List existing GA4 Audience Export snapshots and Recurring Audience Lists without creating new exports.",
+    {
+      propertyId: propertyIdSchema,
+      includeRecurring: z2.boolean().optional().default(true),
+      pageSize: z2.number().int().min(1).max(200).optional().default(100)
+    },
+    async ({ propertyId, includeRecurring, pageSize }) => {
+      try {
+        const audienceExports = await client.listAudienceExports(propertyId, pageSize);
+        const recurringAudienceLists = includeRecurring ? await client.listRecurringAudienceLists(propertyId, Math.min(pageSize, 100)) : [];
+        return ok({
+          audienceExports,
+          recurringAudienceLists,
+          counts: { audienceExports: audienceExports.length, recurringAudienceLists: recurringAudienceLists.length },
+          debug: { requestCount: includeRecurring ? 2 : 1 }
+        });
+      } catch (error) {
+        return formatMcpToolError(error);
+      }
+    }
+  );
+  server.tool(
+    "ga4_query_audience_export",
+    "Query rows from an existing GA4 Audience Export. User/device identifiers are redacted by default; include them only through explicit opt-in.",
+    {
+      audienceExportName: z2.string().regex(/^properties\/[^/]+\/audienceExports\/[^/]+$/),
+      offset: z2.number().int().min(0).optional().default(0),
+      limit: z2.number().int().min(1).max(1e4).optional().default(100),
+      includePersonalIdentifiers: z2.boolean().optional().default(false).describe("Explicitly return user/device identifiers. False redacts identifier columns by default.")
+    },
+    async ({ audienceExportName, offset, limit, includePersonalIdentifiers }) => {
+      try {
+        const response = await client.queryAudienceExport(audienceExportName, {
+          offset: String(offset),
+          limit: String(limit)
+        });
+        return ok({
+          audienceExportName,
+          response: includePersonalIdentifiers ? response : redactGA4AudienceExportResponse(response),
+          warnings: includePersonalIdentifiers ? ["SENSITIVE PERSONAL IDENTIFIERS INCLUDED BY EXPLICIT OPT-IN: Audience Export user/device identifiers are present. Restrict storage, sharing, and model output."] : ["Audience Export user/device identifiers were redacted by default. Set includePersonalIdentifiers=true only with explicit authorization."]
+        });
+      } catch (error) {
+        return formatMcpToolError(error);
+      }
+    }
+  );
+}
+
+// src/platforms/ga4/tools.ts
+var propertyIdSchema2 = z3.string().describe("GA4 property ID (numeric, e.g., 123456789)");
+var datePresetValues = ["today", "yesterday", "last7days", "last28days", "last30days", "last90days", "last12months", "thisMonth", "lastMonth", "thisYear"];
+var datePresetSchema = z3.enum(datePresetValues);
+var matchTypeSchema = z3.enum(["EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP"]);
+var funnelStepSchema = z3.object({
+  name: z3.string().optional().describe("Optional display name for this funnel step"),
+  eventName: z3.string().optional().describe("GA4 eventName to count for this step"),
+  pagePath: z3.string().optional().describe("GA4 pagePath to count for this step"),
+  matchType: matchTypeSchema.optional().default("EXACT").describe("String match type for pagePath. eventName always uses EXACT.")
+}).refine((step) => Boolean(step.eventName || step.pagePath), {
+  message: "Each funnel step must include eventName or pagePath"
+});
+var advancedFunnelStepSchema = z3.object({
+  name: z3.string().optional().describe("Optional display name for this funnel step"),
+  eventName: z3.string().optional().describe("GA4 event name matched by a FunnelEventFilter"),
+  pagePath: z3.string().optional().describe("Shortcut for fieldName=pagePath string filter"),
+  fieldName: z3.string().optional().describe("Optional GA4 field name for a FunnelFieldFilter, e.g. pagePath, pageTitle, deviceCategory"),
+  fieldValue: z3.string().optional().describe("String value to match for fieldName"),
+  matchType: matchTypeSchema.optional().default("EXACT").describe("String match type for pagePath or fieldName"),
+  isDirectlyFollowedBy: z3.boolean().optional().describe("Require this step to directly follow the previous step"),
+  withinSecondsFromPriorStep: z3.number().int().min(1).max(60 * 60 * 24 * 30).optional().describe("Maximum seconds from the prior step")
+}).refine((step) => Boolean(step.eventName || step.pagePath || step.fieldName && step.fieldValue), {
+  message: "Each advanced funnel step must include eventName, pagePath, or fieldName plus fieldValue"
+});
+var funnelVisualizationTypeSchema = z3.enum(["STANDARD_FUNNEL", "TRENDED_FUNNEL"]);
+var GA4_RESPONSE_API_VERSION = "data_api_v1beta/admin_api_v1beta_v1alpha";
+function isRecord2(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 isRecord2(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 (!isRecord2(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: "ga4",
+      apiVersion: GA4_RESPONSE_API_VERSION,
+      requestCount: getRequestCount(data)
+    }
+  };
+}
+function ok2(data) {
+  return { content: [{ type: "text", text: JSON.stringify(withAgentResponseContract(data), null, 2) }] };
+}
+function stringOrUndefined(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function stringArrayOrUndefined(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : void 0;
+}
+function normalizeMetadataField(value) {
+  if (!isRecord2(value) || typeof value["apiName"] !== "string") {
+    return null;
+  }
+  return {
+    apiName: value["apiName"],
+    uiName: stringOrUndefined(value["uiName"]),
+    description: stringOrUndefined(value["description"]),
+    category: stringOrUndefined(value["category"]),
+    customDefinition: value["customDefinition"] === true,
+    type: stringOrUndefined(value["type"]),
+    deprecatedApiNames: stringArrayOrUndefined(value["deprecatedApiNames"])
+  };
+}
+function extractMetadataFields(metadata, kind) {
+  const raw = Array.isArray(metadata[kind]) ? metadata[kind] : [];
+  return raw.map(normalizeMetadataField).filter((field) => field !== null);
+}
+function summarizeMetadata(metadata) {
+  return {
+    dimensions: extractMetadataFields(metadata, "dimensions"),
+    metrics: extractMetadataFields(metadata, "metrics")
+  };
+}
+function inferCustomScope(apiName) {
+  if (apiName.startsWith("customEvent:")) return "event";
+  if (apiName.startsWith("customUser:")) return "user";
+  if (apiName.startsWith("customItem:")) return "item";
+  return "custom";
+}
+function serializeMetadataField(field) {
+  return {
+    apiName: field.apiName,
+    uiName: field.uiName,
+    description: field.description,
+    category: field.category,
+    type: field.type,
+    customDefinition: field.customDefinition === true,
+    scope: inferCustomScope(field.apiName),
+    ...field.deprecatedApiNames && field.deprecatedApiNames.length > 0 && { deprecatedApiNames: field.deprecatedApiNames }
+  };
+}
+function getCustomDefinitions(summary) {
+  const isCustom = (field) => field.customDefinition === true || field.apiName.startsWith("customEvent:") || field.apiName.startsWith("customUser:") || field.apiName.startsWith("customItem:");
+  return {
+    customDimensions: summary.dimensions.filter(isCustom).map(serializeMetadataField),
+    customMetrics: summary.metrics.filter(isCustom).map(serializeMetadataField)
+  };
+}
+function fieldMatchesCandidate(field, candidate) {
+  return field.apiName === candidate || Boolean(field.deprecatedApiNames?.includes(candidate));
+}
+function pickAvailableField(summary, kind, candidates) {
+  if (!summary || summary[kind].length === 0) {
+    return candidates[0];
+  }
+  for (const candidate of candidates) {
+    const match = summary[kind].find((field) => fieldMatchesCandidate(field, candidate));
+    if (match) return match.apiName;
+  }
+  return void 0;
+}
+function filterAvailableFields(summary, kind, candidates) {
+  if (!summary || summary[kind].length === 0) {
+    return candidates;
+  }
+  return candidates.flatMap((candidate) => {
+    const match = summary[kind].find((field) => fieldMatchesCandidate(field, candidate));
+    return match ? [match.apiName] : [];
+  });
+}
+function toMetrics(metrics) {
+  return metrics.map((metric) => ({ name: getMetricByKey(metric)?.apiField ?? metric }));
+}
+function toDimensions(dimensions) {
+  return dimensions.map((dimension) => ({ name: getDimensionByKey(dimension)?.apiField ?? dimension }));
+}
+function resolveInputDateRange(startDate, endDate, datePreset) {
+  if (startDate || endDate) {
+    return {
+      startDate: startDate ?? "28daysAgo",
+      endDate: endDate ?? "today"
+    };
+  }
+  return resolveDatePreset(datePreset ?? "last28days");
+}
+function buildStringFilter2(fieldName, value, matchType = "EXACT") {
+  return {
+    filter: {
+      fieldName,
+      stringFilter: {
+        matchType,
+        value,
+        caseSensitive: false
+      }
+    }
+  };
+}
+function buildInListFilter2(fieldName, values) {
+  return {
+    filter: {
+      fieldName,
+      inListFilter: {
+        values,
+        caseSensitive: false
+      }
+    }
+  };
+}
+function buildMetricGreaterThanFilter(fieldName, value) {
+  return {
+    filter: {
+      fieldName,
+      numericFilter: {
+        operation: "GREATER_THAN",
+        value: { doubleValue: value }
+      }
+    }
+  };
+}
+function combineFilters(expressions) {
+  if (expressions.length === 0) return void 0;
+  if (expressions.length === 1) return expressions[0];
+  return { andGroup: { expressions } };
+}
+function numericValue(row, fieldNames) {
+  if (!row) return 0;
+  for (const fieldName of fieldNames) {
+    const value = row[fieldName];
+    if (typeof value === "number") return value;
+    if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) {
+      return Number(value);
+    }
+  }
+  return 0;
+}
+function numericValueOrNull(row, fieldNames) {
+  if (!row) return null;
+  for (const fieldName of fieldNames) {
+    if (!Object.prototype.hasOwnProperty.call(row, fieldName)) continue;
+    const value = row[fieldName];
+    if (typeof value === "number") return value;
+    if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) {
+      return Number(value);
+    }
+  }
+  return null;
+}
+function stringValue(row, fieldName) {
+  const value = row[fieldName];
+  return value === null || value === void 0 ? "" : String(value);
+}
+function isTruthyGA4Flag(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value > 0;
+  if (typeof value !== "string") return false;
+  return ["true", "yes", "1", "key event", "conversion"].includes(value.trim().toLowerCase());
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function runReportRows(client, propertyId, request) {
+  const response = await client.runReport(propertyId, request);
+  return {
+    response,
+    rows: client.flattenResponse(response)
+  };
+}
+function recordString(value, key) {
+  return typeof value[key] === "string" ? value[key] : void 0;
+}
+function recordNumber(value, key) {
+  return typeof value[key] === "number" ? value[key] : void 0;
+}
+function countByStringField(records, fieldName) {
+  return records.reduce((acc, record) => {
+    const value = recordString(record, fieldName) ?? "UNKNOWN";
+    acc[value] = (acc[value] ?? 0) + 1;
+    return acc;
+  }, {});
+}
+function summarizeAudienceExport(exportRecord) {
+  const dimensions = Array.isArray(exportRecord["dimensions"]) ? exportRecord["dimensions"] : [];
+  return {
+    name: recordString(exportRecord, "name"),
+    audience: recordString(exportRecord, "audience"),
+    audienceDisplayName: recordString(exportRecord, "audienceDisplayName"),
+    state: recordString(exportRecord, "state"),
+    rowCount: recordNumber(exportRecord, "rowCount"),
+    percentageCompleted: recordNumber(exportRecord, "percentageCompleted"),
+    beginCreatingTime: recordString(exportRecord, "beginCreatingTime"),
+    errorMessage: recordString(exportRecord, "errorMessage"),
+    dimensions,
+    dimensionCount: dimensions.length,
+    creationQuotaTokensCharged: recordNumber(exportRecord, "creationQuotaTokensCharged")
+  };
+}
+function summarizeAudience(audience, includeDefinition) {
+  const filterClauses = Array.isArray(audience["filterClauses"]) ? audience["filterClauses"] : [];
+  const eventTrigger = isRecord2(audience["eventTrigger"]) ? audience["eventTrigger"] : void 0;
+  const summary = {
+    name: recordString(audience, "name"),
+    displayName: recordString(audience, "displayName"),
+    description: recordString(audience, "description"),
+    membershipDurationDays: recordNumber(audience, "membershipDurationDays"),
+    adsPersonalizationEnabled: audience["adsPersonalizationEnabled"],
+    filterClauseCount: filterClauses.length,
+    hasEventTrigger: Boolean(eventTrigger),
+    eventTrigger: eventTrigger ? {
+      eventName: recordString(eventTrigger, "eventName"),
+      logCondition: recordString(eventTrigger, "logCondition")
+    } : void 0
+  };
+  return includeDefinition ? { ...summary, definition: audience } : summary;
+}
+function summarizeRecurringAudienceList(list) {
+  const dimensions = Array.isArray(list["dimensions"]) ? list["dimensions"] : [];
+  return {
+    name: recordString(list, "name"),
+    audience: recordString(list, "audience"),
+    audienceDisplayName: recordString(list, "audienceDisplayName"),
+    dimensions,
+    dimensionCount: dimensions.length,
+    audienceLists: stringArrayOrUndefined(list["audienceLists"]) ?? [],
+    activeDaysRemaining: recordNumber(list, "activeDaysRemaining"),
+    hasWebhookNotification: isRecord2(list["webhookNotification"])
+  };
+}
+function summarizeBigQueryLink(link) {
+  return {
+    name: recordString(link, "name"),
+    project: recordString(link, "project"),
+    datasetLocation: recordString(link, "datasetLocation"),
+    createTime: recordString(link, "createTime"),
+    dailyExportEnabled: link["dailyExportEnabled"] === true,
+    streamingExportEnabled: link["streamingExportEnabled"] === true,
+    freshDailyExportEnabled: link["freshDailyExportEnabled"] === true,
+    includeAdvertisingId: link["includeAdvertisingId"] === true,
+    exportStreams: stringArrayOrUndefined(link["exportStreams"]) ?? [],
+    excludedEvents: stringArrayOrUndefined(link["excludedEvents"]) ?? []
+  };
+}
+function summarizeDataStream(stream) {
+  const webStreamData = isRecord2(stream["webStreamData"]) ? stream["webStreamData"] : void 0;
+  const androidAppStreamData = isRecord2(stream["androidAppStreamData"]) ? stream["androidAppStreamData"] : void 0;
+  const iosAppStreamData = isRecord2(stream["iosAppStreamData"]) ? stream["iosAppStreamData"] : void 0;
+  return {
+    name: recordString(stream, "name"),
+    type: recordString(stream, "type"),
+    displayName: recordString(stream, "displayName"),
+    createTime: recordString(stream, "createTime"),
+    updateTime: recordString(stream, "updateTime"),
+    webStreamData: webStreamData ? {
+      measurementId: recordString(webStreamData, "measurementId"),
+      defaultUri: recordString(webStreamData, "defaultUri")
+    } : void 0,
+    androidAppStreamData: androidAppStreamData ? {
+      packageName: recordString(androidAppStreamData, "packageName"),
+      firebaseAppId: recordString(androidAppStreamData, "firebaseAppId")
+    } : void 0,
+    iosAppStreamData: iosAppStreamData ? {
+      bundleId: recordString(iosAppStreamData, "bundleId"),
+      firebaseAppId: recordString(iosAppStreamData, "firebaseAppId")
+    } : void 0
+  };
+}
+function buildFunnelFieldFilter(fieldName, value, matchType) {
+  return {
+    funnelFieldFilter: {
+      fieldName,
+      stringFilter: {
+        matchType,
+        value,
+        caseSensitive: false
+      }
+    }
+  };
+}
+function buildAdvancedFunnelFilterExpression(step) {
+  const expressions = [];
+  if (step.eventName) {
+    expressions.push({ funnelEventFilter: { eventName: step.eventName } });
+  }
+  if (step.pagePath) {
+    expressions.push(buildFunnelFieldFilter("pagePath", step.pagePath, step.matchType ?? "EXACT"));
+  }
+  if (step.fieldName && step.fieldValue) {
+    expressions.push(buildFunnelFieldFilter(step.fieldName, step.fieldValue, step.matchType ?? "EXACT"));
+  }
+  return expressions.length === 1 ? expressions[0] : { andGroup: { expressions } };
+}
+function buildAdvancedFunnelReportFilter(step) {
+  const expressions = [];
+  if (step.eventName) {
+    expressions.push(buildStringFilter2("eventName", step.eventName, "EXACT"));
+  }
+  if (step.pagePath) {
+    expressions.push(buildStringFilter2("pagePath", step.pagePath, step.matchType ?? "EXACT"));
+  }
+  if (step.fieldName && step.fieldValue) {
+    expressions.push(buildStringFilter2(step.fieldName, step.fieldValue, step.matchType ?? "EXACT"));
+  }
+  return combineFilters(expressions);
+}
+function flattenFunnelSubReport(client, subReport) {
+  return subReport ? client.flattenResponse(subReport) : [];
+}
+async function runAdvancedFunnelStepCountFallback(client, propertyId, dateRange, steps) {
+  const rows = [];
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index];
+    const report = await runReportRows(client, propertyId, {
+      dateRanges: [dateRange],
+      metrics: toMetrics(["activeUsers"]),
+      dimensionFilter: buildAdvancedFunnelReportFilter(step),
+      keepEmptyRows: true,
+      limit: 1
+    });
+    const value = numericValue(report.rows[0], ["activeUsers"]);
+    const previousValue = rows[index - 1]?.value ?? null;
+    const firstValue = rows[0]?.value ?? value;
+    rows.push({
+      index: index + 1,
+      name: step.name ?? step.eventName ?? step.pagePath ?? step.fieldName ?? `Step ${index + 1}`,
+      value,
+      conversionRateFromPrevious: previousValue && previousValue > 0 ? value / previousValue : null,
+      conversionRateFromFirst: firstValue > 0 ? value / firstValue : null
+    });
+  }
+  return rows;
+}
+function registerGA4Tools(server, config) {
+  const client = new GA4Client({ clientId: config.clientId, clientSecret: config.clientSecret, refreshToken: config.refreshToken });
+  server.tool(
+    "ga4_health_check",
+    "Read-only GA4 health check. Verifies configured credentials, accessible properties, and metadata/property access without exposing OAuth tokens.",
+    { propertyId: propertyIdSchema2.optional().describe("Optional property ID to check metadata and property details for") },
+    async ({ propertyId }) => {
+      const warnings = [];
+      const actions = [];
+      const checks = [];
+      try {
+        checks.push({
+          name: "credentials_configured",
+          status: config.clientId && config.clientSecret && config.refreshToken ? "ok" : "error",
+          detail: "Presence checked only; credential values are never returned."
+        });
+        let properties = [];
+        try {
+          properties = await client.listProperties();
+          checks.push({ name: "list_properties", status: "ok", detail: `${properties.length} properties accessible` });
+          if (properties.length === 0) {
+            warnings.push("No GA4 properties were returned for these credentials.");
+            actions.push("Grant the authenticated Google user Viewer access to at least one GA4 property.");
+          }
+        } catch (error) {
+          checks.push({ name: "list_properties", status: "error", detail: errorMessage(error) });
+          actions.push("Verify GA4_CLIENT_ID, GA4_CLIENT_SECRET, GA4_REFRESH_TOKEN, and Analytics Admin API access.");
+          return ok2({
+            status: "error",
+            checks,
+            warnings,
+            actions,
+            credentials: {
+              clientIdConfigured: Boolean(config.clientId),
+              clientSecretConfigured: Boolean(config.clientSecret),
+              refreshTokenConfigured: Boolean(config.refreshToken)
+            },
+            debug: { requestCount: 1 },
+            tokenExposure: "No access token or refresh token is returned by this tool."
+          });
+        }
+        const configuredDefaultPropertyId = config.defaultPropertyId;
+        const selectedPropertyId = propertyId ?? configuredDefaultPropertyId ?? properties[0]?.propertyId;
+        if (configuredDefaultPropertyId && !propertyId) {
+          const foundConfiguredDefault = properties.some((property) => property.propertyId === configuredDefaultPropertyId);
+          if (foundConfiguredDefault) {
+            checks.push({ name: "default_property_configured", status: "ok", detail: `Using GA4_PROPERTY_ID=${configuredDefaultPropertyId}` });
+          } else {
+            warnings.push(`GA4_PROPERTY_ID ${configuredDefaultPropertyId} was not present in accountSummaries; direct property/metadata checks will still be attempted.`);
+            checks.push({ name: "default_property_configured", status: "warning", detail: `GA4_PROPERTY_ID=${configuredDefaultPropertyId} not found in account summaries` });
+          }
+        }
+        if (propertyId && properties.length > 0 && !properties.some((property) => property.propertyId === propertyId)) {
+          warnings.push(`Property ${propertyId} was not present in accountSummaries; direct property/metadata checks will still be attempted.`);
+        }
+        let propertyDetail = null;
+        let metadataSummary = null;
+        if (selectedPropertyId) {
+          try {
+            propertyDetail = await client.getProperty(selectedPropertyId);
+            checks.push({ name: "get_property", status: "ok", detail: `Property ${selectedPropertyId} is readable` });
+          } catch (error) {
+            checks.push({ name: "get_property", status: "warning", detail: errorMessage(error) });
+            warnings.push(`Could not read Admin API property details for ${selectedPropertyId}.`);
+            actions.push("Confirm the authenticated user can access the GA4 property in Google Analytics Admin.");
+          }
+          try {
+            metadataSummary = summarizeMetadata(await client.getMetadata(selectedPropertyId));
+            checks.push({
+              name: "get_metadata",
+              status: "ok",
+              detail: `${metadataSummary.dimensions.length} dimensions, ${metadataSummary.metrics.length} metrics`
+            });
+          } catch (error) {
+            checks.push({ name: "get_metadata", status: "warning", detail: errorMessage(error) });
+            warnings.push(`Could not read Data API metadata for ${selectedPropertyId}.`);
+            actions.push("Enable the Google Analytics Data API and verify property-level Viewer access.");
+          }
+        } else {
+          checks.push({ name: "get_property", status: "warning", detail: "Skipped because no property was available." });
+          checks.push({ name: "get_metadata", status: "warning", detail: "Skipped because no property was available." });
+        }
+        const customDefinitions = metadataSummary ? getCustomDefinitions(metadataSummary) : null;
+        const status = checks.some((check) => check.status === "error") ? "error" : warnings.length > 0 ? "warning" : "ok";
+        return ok2({
+          status,
+          checks,
+          warnings,
+          actions,
+          credentials: {
+            clientIdConfigured: Boolean(config.clientId),
+            clientSecretConfigured: Boolean(config.clientSecret),
+            refreshTokenConfigured: Boolean(config.refreshToken),
+            defaultPropertyIdConfigured: Boolean(config.defaultPropertyId)
+          },
+          properties: {
+            count: properties.length,
+            sample: properties.slice(0, 10).map((property) => ({
+              propertyId: property.propertyId,
+              displayName: property.displayName,
+              timeZone: property.timeZone,
+              currencyCode: property.currencyCode,
+              propertyType: property.propertyType,
+              parent: property.parent
+            }))
+          },
+          selectedPropertyId,
+          defaultPropertyId: configuredDefaultPropertyId ?? null,
+          property: propertyDetail,
+          metadata: metadataSummary ? {
+            dimensions: metadataSummary.dimensions.length,
+            metrics: metadataSummary.metrics.length,
+            customDimensions: customDefinitions?.customDimensions.length ?? 0,
+            customMetrics: customDefinitions?.customMetrics.length ?? 0
+          } : null,
+          debug: { requestCount: 1 + (propertyDetail ? 1 : 0) + (metadataSummary ? 1 : 0) },
+          tokenExposure: "No access token or refresh token is returned by this tool."
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_list_properties",
+    "List all GA4 properties accessible with the current credentials. Returns property ID, display name, timezone, and currency.",
+    {},
+    async () => {
+      try {
+        const properties = await client.listProperties();
+        return ok2({ properties, count: properties.length });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_run_report",
+    `Run a GA4 analytics report with intelligent query planning. Supports 52 metrics, 63 dimensions, auto-pagination.
+Use ga4://metrics and ga4://dimensions resources for available fields. Max 9 dimensions + 10 metrics per request.`,
+    {
+      propertyId: propertyIdSchema2,
+      metrics: z3.array(z3.string()).min(1).describe("Metric keys (e.g., sessions, activeUsers, totalRevenue)"),
+      dimensions: z3.array(z3.string()).optional().describe("Dimension keys (e.g., date, sessionSource, country)"),
+      startDate: z3.string().optional().describe("Start date YYYY-MM-DD or relative (7daysAgo, yesterday)"),
+      endDate: z3.string().optional().describe("End date YYYY-MM-DD or relative (today, yesterday)"),
+      datePreset: z3.enum(["today", "yesterday", "last7days", "last28days", "last30days", "last90days", "last12months", "thisMonth", "lastMonth", "thisYear"]).optional(),
+      orderBy: z3.string().optional().describe("Metric or dimension key to sort by"),
+      orderDirection: z3.enum(["ASC", "DESC"]).optional().default("DESC"),
+      limit: z3.number().int().min(1).max(25e4).optional().default(1e3),
+      offset: z3.number().int().min(0).optional().describe("Optional 0-based row offset for explicit pagination."),
+      autoPaginate: z3.boolean().optional().default(false).describe("When true, omit the limit so the GA4 client paginates through all rows using offset.")
+    },
+    async ({ propertyId, metrics, dimensions, startDate, endDate, datePreset, orderBy, orderDirection, limit, offset, autoPaginate }) => {
+      try {
+        const startTime = Date.now();
+        const plan = planGA4Query({
+          propertyId,
+          metrics,
+          dimensions,
+          dateRange: startDate && endDate ? { startDate, endDate } : void 0,
+          datePreset,
+          orderBy,
+          orderDirection,
+          limit: autoPaginate ? void 0 : limit
+        });
+        if (typeof offset === "number") plan.request.offset = offset;
+        if (plan.errors.length > 0) {
+          return ok2({ error: "Query validation failed", errors: plan.errors, warnings: plan.warnings });
+        }
+        const response = await client.runReport(propertyId, plan.request);
+        let data = client.flattenResponse(response);
+        if (plan.calculatedMetrics.length > 0) {
+          data = enrichWithCalculatedMetrics(data, plan.calculatedMetrics);
+        }
+        return ok2({
+          data,
+          rowCount: data.length,
+          totalRowCount: response.rowCount,
+          debug: {
+            requestCount: 1,
+            executionTimeMs: Date.now() - startTime,
+            warnings: plan.warnings,
+            calculatedMetrics: plan.calculatedMetrics,
+            apiMetrics: plan.apiMetrics,
+            pagination: {
+              mode: autoPaginate ? "auto_offset" : "single_page",
+              autoPaginate,
+              offset: offset ?? 0,
+              limit: autoPaginate ? null : limit,
+              totalRowCount: response.rowCount
+            }
+          }
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_run_realtime_report",
+    "Run a read-only GA4 Data API realtime report. Realtime supports only a limited subset of dimensions and metrics.",
+    {
+      propertyId: propertyIdSchema2,
+      metrics: z3.array(z3.string()).min(1).max(10).optional().default(["activeUsers"]).describe("Realtime metric API names, e.g. activeUsers, eventCount"),
+      dimensions: z3.array(z3.string()).max(9).optional().describe("Realtime dimension API names, e.g. eventName, city, deviceCategory"),
+      dimensionFilter: z3.record(z3.unknown()).optional().describe("Native realtime-compatible GA4 FilterExpression JSON."),
+      metricFilter: z3.record(z3.unknown()).optional().describe("Native realtime-compatible GA4 FilterExpression JSON."),
+      minuteRanges: z3.array(z3.object({
+        name: z3.string().optional(),
+        startMinutesAgo: z3.number().int().min(0).max(59).optional(),
+        endMinutesAgo: z3.number().int().min(0).max(59).optional()
+      })).max(2).optional().describe("Optional named realtime minute ranges; zero is the current minute."),
+      orderBys: z3.array(z3.record(z3.unknown())).max(10).optional().describe("Native GA4 OrderBy JSON."),
+      limit: z3.number().int().min(1).max(1e4).optional().default(100),
+      keepEmptyRows: z3.boolean().optional().default(false)
+    },
+    async ({ propertyId, metrics, dimensions, dimensionFilter, metricFilter, minuteRanges, orderBys, limit, keepEmptyRows }) => {
+      try {
+        const response = await client.runRealtimeReport(propertyId, {
+          metrics: toMetrics(metrics),
+          ...dimensions && dimensions.length > 0 && { dimensions: toDimensions(dimensions) },
+          ...dimensionFilter && { dimensionFilter },
+          ...metricFilter && { metricFilter },
+          ...minuteRanges && { minuteRanges },
+          ...orderBys && { orderBys },
+          limit,
+          keepEmptyRows,
+          returnPropertyQuota: true
+        });
+        const data = client.flattenResponse(response);
+        return ok2({
+          data,
+          rowCount: data.length,
+          totalRowCount: response.rowCount,
+          warnings: [
+            "GA4 realtime reports support a limited subset of dimensions and metrics. If a field fails, check ga4_get_metadata or retry with core realtime fields such as activeUsers, eventCount, eventName, city, and deviceCategory."
+          ],
+          propertyQuota: response.propertyQuota
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_metadata",
+    "Get the complete list of dimensions and metrics available for a specific GA4 property. Useful for discovering custom dimensions/metrics.",
+    { propertyId: propertyIdSchema2 },
+    async ({ propertyId }) => {
+      try {
+        const metadata = await client.getMetadata(propertyId);
+        return ok2(metadata);
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_custom_definitions",
+    "List custom dimensions and custom metrics exposed by GA4 Data API metadata. Read-only fallback for custom definition inventory.",
+    { propertyId: propertyIdSchema2 },
+    async ({ propertyId }) => {
+      try {
+        const metadata = await client.getMetadata(propertyId);
+        const summary = summarizeMetadata(metadata);
+        const customDefinitions = getCustomDefinitions(summary);
+        return ok2({
+          propertyId,
+          source: "data_api_metadata",
+          customDimensions: customDefinitions.customDimensions,
+          customMetrics: customDefinitions.customMetrics,
+          counts: {
+            customDimensions: customDefinitions.customDimensions.length,
+            customMetrics: customDefinitions.customMetrics.length,
+            metadataDimensions: summary.dimensions.length,
+            metadataMetrics: summary.metrics.length
+          },
+          limitations: [
+            "This server does not call Admin API mutate endpoints.",
+            "Data API metadata exposes reportable custom definitions but may omit Admin-only details such as archived state or exact creation metadata."
+          ]
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_key_events",
+    "Inventory GA4 key events/conversions using metadata-aware Data API reports. Returns best-effort event names and counts.",
+    {
+      propertyId: propertyIdSchema2,
+      startDate: z3.string().optional().describe("Start date YYYY-MM-DD or relative (7daysAgo, yesterday)"),
+      endDate: z3.string().optional().describe("End date YYYY-MM-DD or relative (today, yesterday)"),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      limit: z3.number().int().min(1).max(1e3).optional().default(100)
+    },
+    async ({ propertyId, startDate, endDate, datePreset, limit }) => {
+      try {
+        const warnings = [];
+        const attempts = [];
+        const dateRange = resolveInputDateRange(startDate, endDate, datePreset);
+        let metadataSummary;
+        try {
+          metadataSummary = summarizeMetadata(await client.getMetadata(propertyId));
+        } catch (error) {
+          warnings.push(`Metadata lookup failed; continuing with standard key event fields. ${errorMessage(error)}`);
+        }
+        const eventNameField = pickAvailableField(metadataSummary, "dimensions", ["eventName"]) ?? "eventName";
+        const flagField = pickAvailableField(metadataSummary, "dimensions", ["isKeyEvent", "isConversionEvent"]);
+        const metricField = pickAvailableField(metadataSummary, "metrics", ["keyEvents", "conversions"]);
+        let rows = [];
+        let source = "none";
+        if (flagField && metricField) {
+          attempts.push(`eventName + ${flagField} + ${metricField}`);
+          try {
+            const report = await runReportRows(client, propertyId, {
+              dateRanges: [dateRange],
+              dimensions: toDimensions([eventNameField, flagField]),
+              metrics: toMetrics([metricField]),
+              orderBys: [{ metric: { metricName: metricField }, desc: true }],
+              limit
+            });
+            rows = report.rows.filter((row) => isTruthyGA4Flag(row[flagField]) || numericValue(row, [metricField]) > 0);
+            source = `report:${eventNameField}+${flagField}+${metricField}`;
+          } catch (error) {
+            warnings.push(`Could not report with key event flag (${flagField}). ${errorMessage(error)}`);
+          }
+        }
+        if (rows.length === 0 && metricField) {
+          attempts.push(`eventName + ${metricField} > 0`);
+          try {
+            const report = await runReportRows(client, propertyId, {
+              dateRanges: [dateRange],
+              dimensions: toDimensions([eventNameField]),
+              metrics: toMetrics([metricField]),
+              metricFilter: buildMetricGreaterThanFilter(metricField, 0),
+              orderBys: [{ metric: { metricName: metricField }, desc: true }],
+              limit
+            });
+            rows = report.rows.filter((row) => numericValue(row, [metricField]) > 0);
+            source = `report:${eventNameField}+${metricField}`;
+          } catch (error) {
+            warnings.push(`Could not report key event metric (${metricField}). ${errorMessage(error)}`);
+          }
+        }
+        if (!metricField) {
+          warnings.push("No keyEvents or conversions metric was found in metadata. Key event inventory cannot be determined from Data API reports.");
+        }
+        const keyEvents = rows.map((row) => {
+          const count = metricField ? numericValue(row, [metricField]) : 0;
+          return {
+            eventName: stringValue(row, eventNameField),
+            ...flagField && { flagField, flagValue: row[flagField], isKeyEvent: isTruthyGA4Flag(row[flagField]) },
+            ...metricField && { metric: metricField, value: count }
+          };
+        }).filter((event) => event.eventName);
+        return ok2({
+          propertyId,
+          dateRange,
+          source,
+          attempts,
+          keyEvents,
+          count: keyEvents.length,
+          warnings,
+          limitations: [
+            "This is a read-only Data API inventory. Admin-only key event configuration details may require Admin API support.",
+            "If the property uses the newer key events naming, keyEvents is preferred; conversions is used as a fallback."
+          ]
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_ecommerce_diagnostics",
+    "Read-only ecommerce coverage diagnostics for core ecommerce events, revenue metrics, and item-level reporting over a date range.",
+    {
+      propertyId: propertyIdSchema2,
+      startDate: z3.string().optional().describe("Start date YYYY-MM-DD or relative (7daysAgo, yesterday)"),
+      endDate: z3.string().optional().describe("End date YYYY-MM-DD or relative (today, yesterday)"),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      limit: z3.number().int().min(1).max(1e3).optional().default(100)
+    },
+    async ({ propertyId, startDate, endDate, datePreset, limit }) => {
+      try {
+        const warnings = [];
+        const dateRange = resolveInputDateRange(startDate, endDate, datePreset);
+        const coreEvents = ["view_item", "add_to_cart", "begin_checkout", "purchase"];
+        const diagnosticEvents = [...coreEvents, "view_item_list", "select_item", "add_shipping_info", "add_payment_info"];
+        let metadataSummary;
+        try {
+          metadataSummary = summarizeMetadata(await client.getMetadata(propertyId));
+        } catch (error) {
+          warnings.push(`Metadata lookup failed; continuing with standard ecommerce fields. ${errorMessage(error)}`);
+        }
+        const eventNameField = pickAvailableField(metadataSummary, "dimensions", ["eventName"]) ?? "eventName";
+        const eventCountMetric = pickAvailableField(metadataSummary, "metrics", ["eventCount"]) ?? "eventCount";
+        let eventRows = [];
+        try {
+          const report = await runReportRows(client, propertyId, {
+            dateRanges: [dateRange],
+            dimensions: toDimensions([eventNameField]),
+            metrics: toMetrics([eventCountMetric]),
+            dimensionFilter: buildInListFilter2(eventNameField, diagnosticEvents),
+            orderBys: [{ metric: { metricName: eventCountMetric }, desc: true }],
+            limit
+          });
+          eventRows = report.rows;
+        } catch (error) {
+          warnings.push(`Could not read ecommerce event coverage. ${errorMessage(error)}`);
+        }
+        const totalMetrics = filterAvailableFields(metadataSummary, "metrics", [
+          "totalRevenue",
+          "purchaseRevenue",
+          "itemRevenue",
+          "transactions",
+          "ecommercePurchases",
+          "addToCarts",
+          "checkouts",
+          "itemsPurchased",
+          "itemsViewed",
+          "itemsAddedToCart",
+          "itemsCheckedOut"
+        ]);
+        let totalsRow;
+        if (totalMetrics.length > 0) {
+          totalsRow = {};
+          for (const metric of totalMetrics) {
+            try {
+              const report = await runReportRows(client, propertyId, {
+                dateRanges: [dateRange],
+                metrics: toMetrics([metric]),
+                limit: 1
+              });
+              totalsRow = { ...totalsRow, ...report.rows[0] ?? {} };
+            } catch (error) {
+              warnings.push(`Could not read ecommerce aggregate metric ${metric}. ${errorMessage(error)}`);
+            }
+          }
+        }
+        const itemDimensions = filterAvailableFields(metadataSummary, "dimensions", ["itemId", "itemName"]);
+        const itemMetrics = filterAvailableFields(metadataSummary, "metrics", [
+          "itemsViewed",
+          "itemsAddedToCart",
+          "itemsCheckedOut",
+          "itemsPurchased",
+          "itemRevenue"
+        ]);
+        let itemRows = [];
+        if (itemDimensions.length > 0 && itemMetrics.length > 0) {
+          try {
+            const report = await runReportRows(client, propertyId, {
+              dateRanges: [dateRange],
+              dimensions: toDimensions(itemDimensions.slice(0, 2)),
+              metrics: toMetrics(itemMetrics),
+              orderBys: [{ metric: { metricName: itemMetrics[0] }, desc: true }],
+              limit
+            });
+            itemRows = report.rows;
+          } catch (error) {
+            warnings.push(`Could not read item-level ecommerce report. ${errorMessage(error)}`);
+          }
+        } else {
+          warnings.push("Item-level dimensions or metrics were not available in metadata.");
+        }
+        const eventCoverage = diagnosticEvents.map((eventName) => {
+          const row = eventRows.find((candidate) => stringValue(candidate, eventNameField) === eventName);
+          const eventCount = numericValue(row, [eventCountMetric]);
+          return {
+            eventName,
+            present: eventCount > 0,
+            eventCount
+          };
+        });
+        const missingCoreEvents = eventCoverage.filter((event) => coreEvents.includes(event.eventName) && !event.present).map((event) => event.eventName);
+        const totalRevenue = numericValueOrNull(totalsRow, ["totalRevenue"]);
+        const purchaseRevenue = numericValueOrNull(totalsRow, ["purchaseRevenue"]);
+        const purchases = numericValueOrNull(totalsRow, ["ecommercePurchases", "transactions"]);
+        const purchaseEventCount = eventCoverage.find((event) => event.eventName === "purchase")?.eventCount ?? 0;
+        if (missingCoreEvents.length > 0) {
+          warnings.push(`Missing core ecommerce event coverage: ${missingCoreEvents.join(", ")}.`);
+        }
+        if (purchaseEventCount > 0 && purchases === null) {
+          warnings.push("Purchase events are present but aggregate purchase metrics were unavailable; summary.purchases is null rather than inferred as 0.");
+        }
+        if (purchases !== null && purchases > 0 && totalRevenue === 0 && purchaseRevenue === 0) {
+          warnings.push("Purchase events are present but revenue metrics are zero; verify value/currency ecommerce parameters.");
+        }
+        if (itemRows.length === 0) {
+          warnings.push("No item-level rows returned; verify items array parameters such as item_id and item_name.");
+        }
+        return ok2({
+          propertyId,
+          dateRange,
+          summary: {
+            coreEventsPresent: coreEvents.filter((eventName) => eventCoverage.some((event) => event.eventName === eventName && event.present)),
+            missingCoreEvents,
+            totalRevenue,
+            purchaseRevenue,
+            purchases,
+            itemRows: itemRows.length
+          },
+          eventCoverage,
+          aggregateMetrics: totalsRow ?? {},
+          itemBreakdown: itemRows,
+          warnings,
+          limitations: [
+            "Diagnostics are based on reportable Data API fields and do not inspect raw event payloads.",
+            "Use BigQuery export or DebugView to validate unregistered ecommerce parameters at event ingestion time."
+          ]
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_event_parameters",
+    "Best-effort event parameter inventory from GA4 metadata plus event reports. Documents Data API limitations for raw parameters.",
+    {
+      propertyId: propertyIdSchema2,
+      eventNames: z3.array(z3.string()).optional().describe("Optional event names to sample, e.g. purchase, add_to_cart"),
+      startDate: z3.string().optional().describe("Start date YYYY-MM-DD or relative (7daysAgo, yesterday)"),
+      endDate: z3.string().optional().describe("End date YYYY-MM-DD or relative (today, yesterday)"),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      limit: z3.number().int().min(1).max(1e3).optional().default(50)
+    },
+    async ({ propertyId, eventNames, startDate, endDate, datePreset, limit }) => {
+      try {
+        const warnings = [];
+        const dateRange = resolveInputDateRange(startDate, endDate, datePreset);
+        const metadata = await client.getMetadata(propertyId);
+        const summary = summarizeMetadata(metadata);
+        const customDefinitions = getCustomDefinitions(summary);
+        const eventNameField = pickAvailableField(summary, "dimensions", ["eventName"]) ?? "eventName";
+        const eventCountMetric = pickAvailableField(summary, "metrics", ["eventCount"]) ?? "eventCount";
+        let eventRows = [];
+        try {
+          const report = await runReportRows(client, propertyId, {
+            dateRanges: [dateRange],
+            dimensions: toDimensions([eventNameField]),
+            metrics: toMetrics([eventCountMetric]),
+            ...eventNames && eventNames.length > 0 && { dimensionFilter: buildInListFilter2(eventNameField, eventNames) },
+            orderBys: [{ metric: { metricName: eventCountMetric }, desc: true }],
+            limit
+          });
+          eventRows = report.rows;
+        } catch (error) {
+          warnings.push(`Could not sample events for parameter context. ${errorMessage(error)}`);
+        }
+        const registeredEventParameters = [
+          ...customDefinitions.customDimensions,
+          ...customDefinitions.customMetrics
+        ].filter((definition) => definition.scope === "event").map((definition) => ({
+          ...definition,
+          parameterName: definition.apiName.includes(":") ? definition.apiName.split(":").slice(1).join(":") : definition.apiName
+        }));
+        if (registeredEventParameters.length === 0) {
+          warnings.push("No registered event-scoped custom dimensions or metrics were exposed by metadata.");
+        }
+        return ok2({
+          propertyId,
+          dateRange,
+          registeredEventParameters,
+          eventSamples: eventRows,
+          warnings,
+          limitations: [
+            "GA4 Data API metadata only exposes parameters registered as reportable custom dimensions or metrics.",
+            "Unregistered raw event parameters and parameter values are not enumerable through this read-only Data API path.",
+            "For exhaustive raw parameter discovery, use GA4 BigQuery export or instrumentation logs."
+          ]
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_run_funnel_recipe",
+    "Run a read-only configurable funnel recipe using one GA4 report per eventName/pagePath step and return simple step counts.",
+    {
+      propertyId: propertyIdSchema2,
+      steps: z3.array(funnelStepSchema).min(2).max(10).describe("Ordered funnel steps. Each step needs eventName or pagePath."),
+      metric: z3.enum(["activeUsers", "totalUsers", "sessions", "eventCount", "screenPageViews"]).optional().default("activeUsers"),
+      startDate: z3.string().optional().describe("Start date YYYY-MM-DD or relative (7daysAgo, yesterday)"),
+      endDate: z3.string().optional().describe("End date YYYY-MM-DD or relative (today, yesterday)"),
+      datePreset: datePresetSchema.optional().default("last28days")
+    },
+    async ({ propertyId, steps, metric, startDate, endDate, datePreset }) => {
+      try {
+        const dateRange = resolveInputDateRange(startDate, endDate, datePreset);
+        const metricField = getMetricByKey(metric)?.apiField ?? metric;
+        const results = [];
+        for (let index = 0; index < steps.length; index++) {
+          const step = steps[index];
+          const filters = [];
+          if (step.eventName) {
+            filters.push(buildStringFilter2("eventName", step.eventName, "EXACT"));
+          }
+          if (step.pagePath) {
+            filters.push(buildStringFilter2("pagePath", step.pagePath, step.matchType ?? "EXACT"));
+          }
+          const report = await runReportRows(client, propertyId, {
+            dateRanges: [dateRange],
+            metrics: toMetrics([metricField]),
+            dimensionFilter: combineFilters(filters),
+            keepEmptyRows: true,
+            limit: 1
+          });
+          const value = numericValue(report.rows[0], [metricField]);
+          const previousValue = results[index - 1]?.value ?? null;
+          const firstValue = results[0]?.value ?? value;
+          results.push({
+            index: index + 1,
+            name: step.name ?? step.eventName ?? step.pagePath ?? `Step ${index + 1}`,
+            filter: {
+              ...step.eventName && { eventName: step.eventName },
+              ...step.pagePath && { pagePath: step.pagePath, matchType: step.matchType ?? "EXACT" }
+            },
+            value,
+            conversionRateFromPrevious: previousValue && previousValue > 0 ? value / previousValue : null,
+            conversionRateFromFirst: firstValue > 0 ? value / firstValue : null,
+            dropoffFromPrevious: previousValue === null ? null : Math.max(previousValue - value, 0)
+          });
+        }
+        return ok2({
+          propertyId,
+          dateRange,
+          metric: metricField,
+          steps: results,
+          recipe: {
+            type: "simple_step_counts",
+            readOnly: true,
+            reportsRun: results.length
+          },
+          limitations: [
+            "This is a simple read-only funnel recipe, not GA4 Explore funnel semantics.",
+            "Each step is counted independently with one runReport call; counts are not user-sequenced or deduplicated across steps."
+          ]
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_audience_export_diagnostics",
+    "Read-only Audience Export diagnostics. Lists existing audience exports, state counts, and optionally samples rows from an existing export.",
+    {
+      propertyId: propertyIdSchema2,
+      audienceExportName: z3.string().optional().describe("Optional resource name, e.g. properties/123456789/audienceExports/abc123"),
+      pageSize: z3.number().int().min(1).max(200).optional().default(100),
+      includeRowSample: z3.boolean().optional().default(false).describe("If true, query a small row sample from audienceExportName. Can include user-level export dimensions."),
+      sampleLimit: z3.number().int().min(1).max(10).optional().default(5),
+      includePersonalIdentifiers: z3.boolean().optional().default(false).describe("Explicitly include user/device identifiers in the optional sample. False redacts them by default.")
+    },
+    async ({ propertyId, audienceExportName, pageSize, includeRowSample, sampleLimit, includePersonalIdentifiers }) => {
+      try {
+        const warnings = [];
+        const exports = await client.listAudienceExports(propertyId, pageSize);
+        const summarizedExports = exports.map(summarizeAudienceExport);
+        const failedExports = summarizedExports.filter((exportRecord) => exportRecord.state === "FAILED");
+        let selectedExport = null;
+        let rowSample = null;
+        if (audienceExportName) {
+          try {
+            selectedExport = summarizeAudienceExport(await client.getAudienceExport(audienceExportName));
+          } catch (error) {
+            warnings.push(`Could not get audience export ${audienceExportName}. ${errorMessage(error)}`);
+          }
+          if (includeRowSample) {
+            try {
+              const response = await client.queryAudienceExport(audienceExportName, { limit: String(sampleLimit), offset: "0" });
+              rowSample = includePersonalIdentifiers ? response : redactGA4AudienceExportResponse(response);
+              warnings.push(includePersonalIdentifiers ? "SENSITIVE PERSONAL IDENTIFIERS INCLUDED BY EXPLICIT OPT-IN: Audience Export sample user/device identifiers are present. Restrict storage, sharing, and model output." : "Audience Export sample user/device identifiers were redacted by default. Set includePersonalIdentifiers=true only with explicit authorization.");
+            } catch (error) {
+              warnings.push(`Could not query row sample for ${audienceExportName}. ${errorMessage(error)}`);
+            }
+          }
+        } else if (includeRowSample) {
+          warnings.push("includeRowSample was ignored because audienceExportName was not provided.");
+        }
+        if (exports.length === 0) {
+          warnings.push("No existing Audience Exports were found. This server intentionally does not create new exports.");
+        }
+        if (failedExports.length > 0) {
+          warnings.push(`${failedExports.length} Audience Export(s) are FAILED. Inspect errorMessage for root cause.`);
+        }
+        return ok2({
+          propertyId,
+          source: "data_api_v1beta_audienceExports_list",
+          count: exports.length,
+          stateCounts: countByStringField(exports, "state"),
+          audienceExports: summarizedExports,
+          selectedExport,
+          rowSample,
+          warnings,
+          limitations: [
+            "This tool only lists/gets/queries existing Audience Exports; it never calls audienceExports.create.",
+            "Row sampling is disabled by default, and identifier values are redacted unless includePersonalIdentifiers=true is explicitly supplied."
+          ]
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_audience_diagnostics",
+    "Read-only audience diagnostics from Admin API audiences, Data API recurring audience lists, and observed audienceName report fallback.",
+    {
+      propertyId: propertyIdSchema2,
+      recurringAudienceListName: z3.string().optional().describe("Optional resource name, e.g. properties/123456789/recurringAudienceLists/abc123"),
+      includeDefinitions: z3.boolean().optional().default(false).describe("Include full Admin API audience definitions when available"),
+      startDate: z3.string().optional().describe("Start date YYYY-MM-DD or relative (7daysAgo, yesterday)"),
+      endDate: z3.string().optional().describe("End date YYYY-MM-DD or relative (today, yesterday)"),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      limit: z3.number().int().min(1).max(1e3).optional().default(100)
+    },
+    async ({ propertyId, recurringAudienceListName, includeDefinitions, startDate, endDate, datePreset, limit }) => {
+      try {
+        const warnings = [];
+        const dateRange = resolveInputDateRange(startDate, endDate, datePreset);
+        let audiences = [];
+        let recurringAudienceLists = [];
+        let selectedRecurringAudienceList = null;
+        let observedAudienceRows = [];
+        try {
+          audiences = await client.listAudiences(propertyId);
+        } catch (error) {
+          warnings.push(`Admin API audiences.list was unavailable. ${errorMessage(error)}`);
+        }
+        try {
+          recurringAudienceLists = await client.listRecurringAudienceLists(propertyId);
+        } catch (error) {
+          warnings.push(`Data API recurringAudienceLists.list was unavailable. ${errorMessage(error)}`);
+        }
+        if (recurringAudienceListName) {
+          try {
+            selectedRecurringAudienceList = summarizeRecurringAudienceList(await client.getRecurringAudienceList(recurringAudienceListName));
+          } catch (error) {
+            warnings.push(`Could not get recurring audience list ${recurringAudienceListName}. ${errorMessage(error)}`);
+          }
+        }
+        try {
+          const summary = summarizeMetadata(await client.getMetadata(propertyId));
+          const audienceNameField = pickAvailableField(summary, "dimensions", ["audienceName"]);
+          const activeUsersMetric = pickAvailableField(summary, "metrics", ["activeUsers"]) ?? "activeUsers";
+          if (audienceNameField) {
+            const report = await runReportRows(client, propertyId, {
+              dateRanges: [dateRange],
+              dimensions: toDimensions([audienceNameField]),
+              metrics: toMetrics([activeUsersMetric]),
+              orderBys: [{ metric: { metricName: activeUsersMetric }, desc: true }],
+              limit
+            });
+            observedAudienceRows = report.rows;
+          } else {
+            warnings.push("audienceName was not available in Data API metadata, so observed audience membership fallback was skipped.");
+          }
+        } catch (error) {
+          warnings.push(`Observed audienceName report fallback failed. ${errorMessage(error)}`);
+        }
+        return ok2({
+          propertyId,
+          dateRange,
+          adminAudiences: audiences.map((audience) => summarizeAudience(audience, includeDefinitions)),
+          recurringAudienceLists: recurringAudienceLists.map(summarizeRecurringAudienceList),
+          selectedRecurringAudienceList,
+          observedAudienceRows,
+          counts: {
+            adminAudiences: audiences.length,
+            recurringAudienceLists: recurringAudienceLists.length,
+            observedAudienceRows: observedAudienceRows.length
+          },
+          warnings,
+          limitations: [
+            "Admin API audiences.list is alpha and may omit pre-2020 or default audience filter definitions.",
+            "Recurring Audience Lists are listed read-only; this server never calls recurringAudienceLists.create.",
+            "The observed audienceName report is a traffic fallback, not an Admin configuration inventory."
+          ]
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_bigquery_export_diagnostics",
+    "Detect GA4 BigQuery export links and diagnose export modes, stream coverage, excluded events, and dataset location.",
+    {
+      propertyId: propertyIdSchema2,
+      includeDataStreams: z3.boolean().optional().default(true).describe("Include data stream summaries to compare against BigQuery exportStreams")
+    },
+    async ({ propertyId, includeDataStreams }) => {
+      try {
+        const warnings = [];
+        let links = [];
+        let streams = [];
+        try {
+          links = await client.listBigQueryLinks(propertyId);
+        } catch (error) {
+          warnings.push(`Admin API bigQueryLinks.list was unavailable. ${errorMessage(error)}`);
+        }
+        if (includeDataStreams) {
+          try {
+            streams = await client.listDataStreams(propertyId);
+          } catch (error) {
+            warnings.push(`Admin API dataStreams.list was unavailable. ${errorMessage(error)}`);
+          }
+        }
+        const bigQueryLinks = links.map(summarizeBigQueryLink);
+        const exportedStreamNames = new Set(bigQueryLinks.flatMap((link) => link.exportStreams));
+        const dataStreams = streams.map(summarizeDataStream);
+        const streamsNotExplicitlyExported = exportedStreamNames.size > 0 ? dataStreams.filter((stream) => stream.name && !exportedStreamNames.has(stream.name)) : [];
+        if (bigQueryLinks.length === 0) {
+          warnings.push("No BigQuery links were detected for this property.");
+        }
+        if (bigQueryLinks.some((link) => !link.dailyExportEnabled && !link.streamingExportEnabled && !link.freshDailyExportEnabled)) {
+          warnings.push("At least one BigQuery link has no daily, streaming, or fresh daily export mode enabled.");
+        }
+        if (streamsNotExplicitlyExported.length > 0) {
+          warnings.push(`${streamsNotExplicitlyExported.length} stream(s) were not present in explicit BigQuery exportStreams.`);
+        }
+        return ok2({
+          propertyId,
+          detected: bigQueryLinks.length > 0,
+          bigQueryLinks,
+          dataStreams,
+          summary: {
+            linkCount: bigQueryLinks.length,
+            dailyExportLinks: bigQueryLinks.filter((link) => link.dailyExportEnabled).length,
+            streamingExportLinks: bigQueryLinks.filter((link) => link.streamingExportEnabled).length,
+            freshDailyExportLinks: bigQueryLinks.filter((link) => link.freshDailyExportEnabled).length,
+            datasetLocations: Array.from(new Set(bigQueryLinks.map((link) => link.datasetLocation).filter(Boolean))),
+            excludedEventCount: bigQueryLinks.reduce((total, link) => total + link.excludedEvents.length, 0),
+            explicitExportStreamCount: exportedStreamNames.size,
+            streamsNotExplicitlyExported: streamsNotExplicitlyExported.length
+          },
+          warnings,
+          limitations: [
+            "This detects GA4 Admin API BigQueryLink configuration only; it does not query BigQuery datasets or table freshness.",
+            "When exportStreams is empty, Google may apply property-level defaults; stream coverage should be confirmed in GA4 Admin UI or BigQuery."
+          ]
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_server_side_tagging_diagnostics",
+    "Best-effort read-only server-side tagging diagnostics from data streams, Measurement Protocol secrets, event rules, and stream settings.",
+    {
+      propertyId: propertyIdSchema2,
+      includeSettings: z3.boolean().optional().default(true).describe("Fetch enhanced measurement and data redaction settings for web streams"),
+      includeRules: z3.boolean().optional().default(true).describe("Fetch event create/edit rules for web streams")
+    },
+    async ({ propertyId, includeSettings, includeRules }) => {
+      try {
+        const warnings = [];
+        const streams = await client.listDataStreams(propertyId);
+        const streamDiagnostics = [];
+        for (const stream of streams) {
+          const streamName = recordString(stream, "name");
+          const streamSummary = summarizeDataStream(stream);
+          const streamWarnings = [];
+          let measurementProtocolSecrets = [];
+          let enhancedMeasurementSettings = null;
+          let dataRedactionSettings = null;
+          let eventCreateRules = [];
+          let eventEditRules = [];
+          if (streamName) {
+            try {
+              measurementProtocolSecrets = await client.listMeasurementProtocolSecrets(streamName);
+            } catch (error) {
+              streamWarnings.push(`measurementProtocolSecrets.list unavailable. ${errorMessage(error)}`);
+            }
+            if (includeSettings && streamSummary.type === "WEB_DATA_STREAM") {
+              try {
+                enhancedMeasurementSettings = await client.getEnhancedMeasurementSettings(streamName);
+              } catch (error) {
+                streamWarnings.push(`enhancedMeasurementSettings unavailable. ${errorMessage(error)}`);
+              }
+              try {
+                dataRedactionSettings = await client.getDataRedactionSettings(streamName);
+              } catch (error) {
+                streamWarnings.push(`dataRedactionSettings unavailable. ${errorMessage(error)}`);
+              }
+            }
+            if (includeRules && streamSummary.type === "WEB_DATA_STREAM") {
+              try {
+                eventCreateRules = await client.listEventCreateRules(streamName);
+              } catch (error) {
+                streamWarnings.push(`eventCreateRules.list unavailable. ${errorMessage(error)}`);
+              }
+              try {
+                eventEditRules = await client.listEventEditRules(streamName);
+              } catch (error) {
+                streamWarnings.push(`eventEditRules.list unavailable. ${errorMessage(error)}`);
+              }
+            }
+          }
+          streamDiagnostics.push({
+            ...streamSummary,
+            measurementProtocolSecrets,
+            measurementProtocolSecretCount: measurementProtocolSecrets.length,
+            enhancedMeasurementSettings,
+            dataRedactionSettings,
+            eventCreateRuleCount: eventCreateRules.length,
+            eventEditRuleCount: eventEditRules.length,
+            eventCreateRules,
+            eventEditRules,
+            warnings: streamWarnings
+          });
+        }
+        const measurementProtocolSecretCount = streamDiagnostics.reduce((total, stream) => {
+          return total + (typeof stream.measurementProtocolSecretCount === "number" ? stream.measurementProtocolSecretCount : 0);
+        }, 0);
+        const eventRuleCount = streamDiagnostics.reduce((total, stream) => {
+          const createRules = typeof stream.eventCreateRuleCount === "number" ? stream.eventCreateRuleCount : 0;
+          const editRules = typeof stream.eventEditRuleCount === "number" ? stream.eventEditRuleCount : 0;
+          return total + createRules + editRules;
+        }, 0);
+        if (measurementProtocolSecretCount === 0) {
+          warnings.push("No Measurement Protocol secrets were detected. This does not prove server-side tagging is absent.");
+        }
+        warnings.push("GA4 Admin API does not expose GTM server container routing or tagging server URLs; server-side tagging is inferred, not confirmed.");
+        return ok2({
+          propertyId,
+          streamDiagnostics,
+          summary: {
+            streamCount: streams.length,
+            webStreamCount: streamDiagnostics.filter((stream) => stream.type === "WEB_DATA_STREAM").length,
+            measurementProtocolSecretCount,
+            eventRuleCount,
+            possibleServerSideOrServerToServerSignals: measurementProtocolSecretCount > 0 || eventRuleCount > 0
+          },
+          warnings,
+          safety: {
+            measurementProtocolSecretValues: "Redacted before returning tool output."
+          },
+          limitations: [
+            "Measurement Protocol secrets can support server-to-server collection, but are not proof of GTM server-side tagging.",
+            "Direct GTM server container configuration is outside the GA4 Admin/Data APIs used by this read-only server."
+          ]
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_run_advanced_funnel_report",
+    "Run the GA4 Data API v1alpha runFunnelReport endpoint with optional breakdown/next-action, falling back to read-only step counts if unavailable.",
+    {
+      propertyId: propertyIdSchema2,
+      steps: z3.array(advancedFunnelStepSchema).min(2).max(10).describe("Ordered funnel steps using eventName, pagePath, or fieldName+fieldValue"),
+      isOpenFunnel: z3.boolean().optional().default(false),
+      visualizationType: funnelVisualizationTypeSchema.optional().default("STANDARD_FUNNEL"),
+      breakdownDimension: z3.string().optional().describe("Optional breakdown dimension, e.g. deviceCategory or sessionDefaultChannelGroup"),
+      breakdownLimit: z3.number().int().min(1).max(50).optional().default(10),
+      nextActionDimension: z3.string().optional().describe("Optional next action dimension, commonly eventName"),
+      nextActionLimit: z3.number().int().min(1).max(50).optional().default(10),
+      startDate: z3.string().optional().describe("Start date YYYY-MM-DD or relative (7daysAgo, yesterday)"),
+      endDate: z3.string().optional().describe("End date YYYY-MM-DD or relative (today, yesterday)"),
+      datePreset: datePresetSchema.optional().default("last28days"),
+      limit: z3.number().int().min(1).max(25e4).optional().default(1e4),
+      fallbackToStepCounts: z3.boolean().optional().default(true)
+    },
+    async ({
+      propertyId,
+      steps,
+      isOpenFunnel,
+      visualizationType,
+      breakdownDimension,
+      breakdownLimit,
+      nextActionDimension,
+      nextActionLimit,
+      startDate,
+      endDate,
+      datePreset,
+      limit,
+      fallbackToStepCounts
+    }) => {
+      try {
+        const dateRange = resolveInputDateRange(startDate, endDate, datePreset);
+        const warnings = [];
+        const request = {
+          dateRanges: [dateRange],
+          funnel: {
+            isOpenFunnel,
+            steps: steps.map((step, index) => ({
+              name: step.name ?? step.eventName ?? step.pagePath ?? step.fieldName ?? `Step ${index + 1}`,
+              ...step.isDirectlyFollowedBy !== void 0 && { isDirectlyFollowedBy: step.isDirectlyFollowedBy },
+              ...step.withinSecondsFromPriorStep !== void 0 && index > 0 && { withinDurationFromPriorStep: `${step.withinSecondsFromPriorStep}s` },
+              filterExpression: buildAdvancedFunnelFilterExpression(step)
+            }))
+          },
+          funnelVisualizationType: visualizationType,
+          limit: String(limit),
+          returnPropertyQuota: true,
+          ...breakdownDimension && {
+            funnelBreakdown: {
+              breakdownDimension: { name: getDimensionByKey(breakdownDimension)?.apiField ?? breakdownDimension },
+              limit: String(breakdownLimit)
+            }
+          },
+          ...nextActionDimension && {
+            funnelNextAction: {
+              nextActionDimension: { name: getDimensionByKey(nextActionDimension)?.apiField ?? nextActionDimension },
+              limit: String(nextActionLimit)
+            }
+          }
+        };
+        try {
+          const response = await client.runFunnelReport(propertyId, request);
+          return ok2({
+            propertyId,
+            dateRange,
+            source: "data_api_v1alpha_runFunnelReport",
+            funnelTable: flattenFunnelSubReport(client, response.funnelTable),
+            funnelVisualization: flattenFunnelSubReport(client, response.funnelVisualization),
+            rawResponse: response,
+            request,
+            warnings,
+            limitations: [
+              "runFunnelReport is a Data API v1alpha read-only report endpoint and may have alpha limitations.",
+              "Returned rows are report aggregates; this tool does not mutate GA4 Explore reports or property configuration."
+            ]
+          });
+        } catch (error) {
+          if (!fallbackToStepCounts) {
+            throw error;
+          }
+          warnings.push(`runFunnelReport failed; used independent step-count fallback. ${errorMessage(error)}`);
+          const fallbackSteps = await runAdvancedFunnelStepCountFallback(client, propertyId, dateRange, steps);
+          return ok2({
+            propertyId,
+            dateRange,
+            source: "data_api_runReport_step_count_fallback",
+            steps: fallbackSteps,
+            request,
+            warnings,
+            limitations: [
+              "Fallback counts each step independently with activeUsers and does not reproduce GA4 Explore/runFunnelReport sequence semantics.",
+              "Disable fallbackToStepCounts to surface runFunnelReport errors directly."
+            ]
+          });
+        }
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_get_channel_groups",
+    "List custom channel groups defined for a GA4 property.",
+    { propertyId: propertyIdSchema2 },
+    async ({ propertyId }) => {
+      try {
+        const groups = await client.listChannelGroups(propertyId);
+        return ok2({ channelGroups: groups });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  server.tool(
+    "ga4_validate_query",
+    "Validate a metric/dimension combination BEFORE executing. Checks max limits (9 dims, 10 metrics), ecommerce rules, and dimension compatibility.",
+    {
+      metrics: z3.array(z3.string()).min(1).describe("Metric keys to validate"),
+      dimensions: z3.array(z3.string()).optional().describe("Dimension keys to validate")
+    },
+    async ({ metrics, dimensions }) => {
+      try {
+        const result = validateGA4QuerySelection(metrics, dimensions ?? []);
+        return ok2({
+          ...result,
+          debug: {
+            requestCount: 0
+          }
+        });
+      } catch (e) {
+        return formatMcpToolError(e);
+      }
+    }
+  );
+  registerGA4SurfaceTools(server, client);
+}
+
+// src/platforms/ga4/resources.ts
+function registerGA4Resources(server) {
+  server.resource("ga4-metrics", "ga4://metrics", async () => ({
+    contents: [{
+      uri: "ga4://metrics",
+      mimeType: "application/json",
+      text: JSON.stringify(GA4_METRIC_CATALOG.map((m) => ({
+        key: m.key,
+        name: m.name,
+        description: m.description,
+        category: m.category,
+        type: m.type,
+        format: m.format,
+        apiField: m.apiField
+      })), null, 2)
+    }]
+  }));
+  server.resource("ga4-dimensions", "ga4://dimensions", async () => ({
+    contents: [{
+      uri: "ga4://dimensions",
+      mimeType: "application/json",
+      text: JSON.stringify(GA4_DIMENSION_CATALOG.map((d) => ({
+        key: d.key,
+        name: d.name,
+        description: d.description,
+        category: d.category,
+        apiField: d.apiField
+      })), null, 2)
+    }]
+  }));
+  server.resource("ga4-compatibility", "ga4://compatibility", async () => ({
+    contents: [{
+      uri: "ga4://compatibility",
+      mimeType: "application/json",
+      text: JSON.stringify({
+        description: "GA4 constraints: max 9 dimensions + 10 metrics per request. Ecommerce dimensions require ecommerce metrics.",
+        maxDimensions: 9,
+        maxMetrics: 10,
+        maxRowsPerCoreRequest: 25e4,
+        maxReportsPerBatch: 5,
+        maxPivotCells: 25e4,
+        dateFormats: ["YYYY-MM-DD", "7daysAgo", "yesterday", "today"]
+      }, null, 2)
+    }]
+  }));
+  server.resource("ga4-manifest", "ga4://manifest", async () => ({
+    contents: [{
+      uri: "ga4://manifest",
+      mimeType: "application/json",
+      text: JSON.stringify({
+        name: "GA4 MCP",
+        platform: "google_analytics_4",
+        readOnly: true,
+        authentication: {
+          type: "google_oauth_refresh_token",
+          tokensExposedByTools: false
+        },
+        tools: [
+          { name: "ga4_health_check", purpose: "Verify credentials, list properties, and test property/metadata access" },
+          { name: "ga4_list_properties", purpose: "List accessible GA4 properties" },
+          { name: "ga4_run_report", purpose: "Run standard GA4 Data API reports" },
+          { name: "ga4_run_pivot_report", purpose: "Run native GA4 Data API pivot reports" },
+          { name: "ga4_batch_run_reports", purpose: "Run up to five Core reports in one official batch request" },
+          { name: "ga4_batch_run_pivot_reports", purpose: "Run up to five pivot reports in one official batch request" },
+          { name: "ga4_check_compatibility", purpose: "Check official Core dimension/metric compatibility" },
+          { name: "ga4_get_property_quotas_snapshot", purpose: "Read the current Data API property quota snapshot" },
+          { name: "ga4_run_realtime_report", purpose: "Run GA4 Data API realtime reports with limited realtime-compatible fields" },
+          { name: "ga4_get_metadata", purpose: "Return property metadata dimensions and metrics" },
+          { name: "ga4_get_custom_definitions", purpose: "Inventory reportable custom dimensions and metrics from metadata" },
+          { name: "ga4_get_key_events", purpose: "Best-effort key event/conversion inventory from reports" },
+          { name: "ga4_get_ecommerce_diagnostics", purpose: "Diagnose ecommerce event, revenue, and item coverage" },
+          { name: "ga4_get_event_parameters", purpose: "Approximate event parameter inventory from registered custom definitions" },
+          { name: "ga4_run_funnel_recipe", purpose: "Run simple read-only event/pagePath funnel step counts" },
+          { name: "ga4_get_audience_export_diagnostics", purpose: "List existing Audience Exports and inspect state/readiness without creating exports" },
+          { name: "ga4_get_audience_diagnostics", purpose: "List Admin audiences, recurring audience lists, and observed audienceName report fallback" },
+          { name: "ga4_get_bigquery_export_diagnostics", purpose: "Detect BigQuery export links, export modes, stream coverage, and excluded events" },
+          { name: "ga4_get_server_side_tagging_diagnostics", purpose: "Infer server-side/server-to-server tagging signals from data streams and Measurement Protocol secrets" },
+          { name: "ga4_run_advanced_funnel_report", purpose: "Run Data API v1alpha funnel reports with breakdown/next-action and read-only fallback" },
+          { name: "ga4_get_channel_groups", purpose: "List custom channel groups" },
+          { name: "ga4_list_accounts", purpose: "List raw accessible Analytics Admin accounts" },
+          { name: "ga4_list_admin_resources", purpose: "List allowlisted property Admin collections" },
+          { name: "ga4_get_property_configuration", purpose: "Read property details and singleton Admin settings" },
+          { name: "ga4_list_audience_exports", purpose: "List existing audience exports and recurring audience lists" },
+          { name: "ga4_query_audience_export", purpose: "Query rows from an existing audience export" },
+          { name: "ga4_validate_query", purpose: "Validate report metric/dimension combinations" }
+        ],
+        resources: ["ga4://metrics", "ga4://dimensions", "ga4://compatibility", "ga4://manifest", "ga4://recipes", "ga4://p2-diagnostics"],
+        safety: [
+          "No write or mutate endpoints are registered.",
+          "OAuth access and refresh tokens are never returned in tool responses.",
+          "Measurement Protocol secret values are redacted before tool output.",
+          "Audience Export and access-binding personal identifiers are redacted unless explicitly opted in.",
+          "Diagnostics are best-effort read-only views over Data API/Admin read endpoints."
+        ]
+      }, null, 2)
+    }]
+  }));
+  server.resource("ga4-recipes", "ga4://recipes", async () => ({
+    contents: [{
+      uri: "ga4://recipes",
+      mimeType: "application/json",
+      text: JSON.stringify({
+        recipes: [
+          {
+            name: "Account readiness check",
+            tool: "ga4_health_check",
+            input: { propertyId: "123456789" },
+            useWhen: "Before querying a new credential set or property."
+          },
+          {
+            name: "Realtime traffic snapshot",
+            tool: "ga4_run_realtime_report",
+            input: { propertyId: "123456789", metrics: ["activeUsers"], dimensions: ["eventName"], limit: 25 },
+            useWhen: "To inspect live activity with realtime-compatible fields."
+          },
+          {
+            name: "Key event inventory",
+            tool: "ga4_get_key_events",
+            input: { propertyId: "123456789", datePreset: "last28days", limit: 100 },
+            useWhen: "To identify key events/conversions currently receiving traffic."
+          },
+          {
+            name: "Ecommerce implementation diagnostics",
+            tool: "ga4_get_ecommerce_diagnostics",
+            input: { propertyId: "123456789", datePreset: "last28days", limit: 100 },
+            useWhen: "To check view_item, add_to_cart, begin_checkout, purchase, revenue, and item coverage."
+          },
+          {
+            name: "Registered event parameters",
+            tool: "ga4_get_event_parameters",
+            input: { propertyId: "123456789", eventNames: ["purchase", "add_to_cart"], datePreset: "last28days" },
+            useWhen: "To discover reportable custom event parameters and sample event volume."
+          },
+          {
+            name: "Simple ecommerce funnel",
+            tool: "ga4_run_funnel_recipe",
+            input: {
+              propertyId: "123456789",
+              metric: "activeUsers",
+              datePreset: "last28days",
+              steps: [
+                { name: "Product views", eventName: "view_item" },
+                { name: "Cart adds", eventName: "add_to_cart" },
+                { name: "Checkout starts", eventName: "begin_checkout" },
+                { name: "Purchases", eventName: "purchase" }
+              ]
+            },
+            useWhen: "To get quick step counts without GA4 Explore funnel semantics."
+          },
+          {
+            name: "Advanced funnel with device breakdown",
+            tool: "ga4_run_advanced_funnel_report",
+            input: {
+              propertyId: "123456789",
+              datePreset: "last28days",
+              breakdownDimension: "deviceCategory",
+              steps: [
+                { name: "Landing", pagePath: "/", matchType: "EXACT" },
+                { name: "Signup start", eventName: "sign_up_start" },
+                { name: "Signup complete", eventName: "sign_up" }
+              ]
+            },
+            useWhen: "To use GA4 Data API funnel semantics with optional fallback to independent step counts."
+          },
+          {
+            name: "Pivoted country/device performance",
+            tool: "ga4_run_pivot_report",
+            input: {
+              propertyId: "123456789",
+              report: {
+                dateRanges: [{ startDate: "28daysAgo", endDate: "today" }],
+                dimensions: ["country", "deviceCategory"],
+                metrics: ["sessions", "totalRevenue"],
+                pivots: [{ fieldNames: ["country"], limit: 20 }, { fieldNames: ["deviceCategory"], limit: 3 }]
+              }
+            },
+            useWhen: "To return a native multidimensional pivot and property quota state."
+          },
+          {
+            name: "Audience readiness",
+            tool: "ga4_get_audience_diagnostics",
+            input: { propertyId: "123456789", datePreset: "last28days", limit: 100 },
+            useWhen: "To inspect Admin audiences, recurring audience lists, and observed audienceName traffic."
+          },
+          {
+            name: "Audience export readiness",
+            tool: "ga4_get_audience_export_diagnostics",
+            input: { propertyId: "123456789", pageSize: 100 },
+            useWhen: "To find existing Audience Exports and their ACTIVE/FAILED/CREATING states without creating new exports."
+          },
+          {
+            name: "BigQuery export detection",
+            tool: "ga4_get_bigquery_export_diagnostics",
+            input: { propertyId: "123456789", includeDataStreams: true },
+            useWhen: "To confirm whether GA4 BigQuery export is configured and which export modes are enabled."
+          },
+          {
+            name: "Server-side tagging inference",
+            tool: "ga4_get_server_side_tagging_diagnostics",
+            input: { propertyId: "123456789", includeSettings: true, includeRules: true },
+            useWhen: "To infer server-side/server-to-server collection signals while keeping Measurement Protocol secret values redacted."
+          }
+        ],
+        notes: [
+          "Use ga4://metrics and ga4://dimensions for standard report fields.",
+          "Use ga4_get_metadata or ga4_get_custom_definitions for property-specific custom fields.",
+          "Funnel recipes are independent step counts, not sequence-aware user path analysis.",
+          "Advanced funnel reports use the GA4 Data API v1alpha runFunnelReport endpoint and can fall back to independent step counts.",
+          "Audience Export and Recurring Audience List diagnostics are read-only and never create new lists.",
+          "ga4_list_admin_resources is an allowlisted GET-only explorer over Admin API v1beta/v1alpha collections.",
+          "Batch Data API methods accept at most five reports for one property, matching the official API contract.",
+          "Core report and pivot-cell limits are 250,000; every pivot must include a limit."
+        ]
+      }, null, 2)
+    }]
+  }));
+  server.resource("ga4-p2-diagnostics", "ga4://p2-diagnostics", async () => ({
+    contents: [{
+      uri: "ga4://p2-diagnostics",
+      mimeType: "application/json",
+      text: JSON.stringify({
+        readOnlyP2Tools: [
+          {
+            name: "ga4_get_audience_export_diagnostics",
+            endpoints: [
+              "GET analyticsdata.googleapis.com/v1beta/properties/{property}/audienceExports",
+              "GET analyticsdata.googleapis.com/v1beta/properties/{property}/audienceExports/{audienceExport}",
+              "POST analyticsdata.googleapis.com/v1beta/properties/{property}/audienceExports/{audienceExport}:query (optional read-only sample)"
+            ],
+            noCreateEndpointCalled: true
+          },
+          {
+            name: "ga4_get_audience_diagnostics",
+            endpoints: [
+              "GET analyticsadmin.googleapis.com/v1alpha/properties/{property}/audiences",
+              "GET analyticsdata.googleapis.com/v1alpha/properties/{property}/recurringAudienceLists",
+              "POST analyticsdata.googleapis.com/v1beta/properties/{property}:runReport for audienceName fallback"
+            ],
+            noCreateEndpointCalled: true
+          },
+          {
+            name: "ga4_get_bigquery_export_diagnostics",
+            endpoints: [
+              "GET analyticsadmin.googleapis.com/v1alpha/properties/{property}/bigQueryLinks",
+              "GET analyticsadmin.googleapis.com/v1alpha/properties/{property}/dataStreams"
+            ]
+          },
+          {
+            name: "ga4_get_server_side_tagging_diagnostics",
+            endpoints: [
+              "GET analyticsadmin.googleapis.com/v1alpha/properties/{property}/dataStreams",
+              "GET analyticsadmin.googleapis.com/v1alpha/properties/{property}/dataStreams/{stream}/measurementProtocolSecrets",
+              "GET analyticsadmin.googleapis.com/v1alpha/properties/{property}/dataStreams/{stream}/enhancedMeasurementSettings",
+              "GET analyticsadmin.googleapis.com/v1alpha/properties/{property}/dataStreams/{stream}/dataRedactionSettings",
+              "GET analyticsadmin.googleapis.com/v1alpha/properties/{property}/dataStreams/{stream}/eventCreateRules",
+              "GET analyticsadmin.googleapis.com/v1alpha/properties/{property}/dataStreams/{stream}/eventEditRules"
+            ],
+            secretHandling: "measurementProtocolSecrets.secretValue is redacted"
+          },
+          {
+            name: "ga4_run_advanced_funnel_report",
+            endpoints: [
+              "POST analyticsdata.googleapis.com/v1alpha/properties/{property}:runFunnelReport",
+              "POST analyticsdata.googleapis.com/v1beta/properties/{property}:runReport fallback when enabled"
+            ]
+          }
+        ],
+        agentNotes: [
+          "Prefer diagnostics tools before asking to create GA4 assets; this server has no mutate tools.",
+          "Treat alpha Admin/Data API fields as best-effort and inspect warnings in every response.",
+          "Use includeRowSample on Audience Exports only when user-level export rows are explicitly needed."
+        ]
+      }, null, 2)
+    }]
+  }));
+}
+
+// src/platforms/ga4/index.ts
+function registerGA4(server, config) {
+  registerGA4Tools(server, config);
+  registerGA4Resources(server);
+  logger.info("ga4", "Registered 27 read tools and 6 resources");
+}
+
+// src/server.ts
+var PACKAGE_VERSION = "1.0.0";
+function createServer(config) {
+  const server = new McpServer(
+    { name: "google-analytics-mcp", version: PACKAGE_VERSION },
+    { capabilities: { tools: { listChanged: true }, resources: { subscribe: false, listChanged: true } } }
+  );
+  registerGA4(server, config);
+  logger.system(`google-analytics-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);
+    await server.connect(new StdioServerTransport());
+    logger.system("Stdio transport connected");
+  } catch (error) {
+    logger.error("cli", "Fatal error", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+main();
+//# sourceMappingURL=cli.js.map