mcp-ga4 1.0.0

package/dist/index.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * mcp-ga4 -- MCP server for querying Google Analytics 4 via natural language.
+ *
+ * Supports two config modes:
+ * 1. Single-property (env vars): GA4_PROPERTY_ID + GOOGLE_APPLICATION_CREDENTIALS
+ * 2. Multi-client (config.json): MCP_GA4_CONFIG or ~/.config/mcp-ga4/config.json
+ */
+import { readFileSync, existsSync, appendFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { tools } from "./tools.js";
+import { GA4Manager } from "./ga4.js";
+import { validateCredentials } from "./auth.js";
+import { classifyError, GA4AuthError, GA4RateLimitError, GA4ServiceError } from "./errors.js";
+import { logger } from "./resilience.js";
+function loadConfig() {
+    // Mode 1: Single-property via env vars
+    const propertyId = process.env.GA4_PROPERTY_ID;
+    const credsFile = process.env.GOOGLE_APPLICATION_CREDENTIALS || "";
+    if (propertyId) {
+        return {
+            credentials_file: credsFile,
+            clients: {
+                default: {
+                    name: process.env.GA4_PROPERTY_NAME || "My Property",
+                    folder: "",
+                    property_id: propertyId,
+                },
+            },
+        };
+    }
+    // Mode 2: Config file
+    const configPath = findConfigFile();
+    if (!configPath) {
+        throw new Error("No GA4 configuration found. Either:\n" +
+            "  1. Set GA4_PROPERTY_ID and GOOGLE_APPLICATION_CREDENTIALS env vars, or\n" +
+            "  2. Run 'npx mcp-ga4-setup' for guided setup, or\n" +
+            "  3. Create ~/.config/mcp-ga4/config.json");
+    }
+    const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+    const clients = {};
+    for (const [key, c] of Object.entries(raw.clients || {})) {
+        const client = c;
+        clients[key] = {
+            name: client.name,
+            folder: client.folder,
+            property_id: client.property_id,
+            sandbox_measurement_id: client.sandbox_measurement_id,
+            production_measurement_id: client.production_measurement_id,
+        };
+    }
+    return {
+        credentials_file: raw.credentials_file || credsFile,
+        clients,
+    };
+}
+function findConfigFile() {
+    // 1. Explicit env var
+    const envPath = process.env.MCP_GA4_CONFIG;
+    if (envPath && existsSync(envPath))
+        return envPath;
+    // 2. XDG-style user config
+    const xdg = join(homedir(), ".config", "mcp-ga4", "config.json");
+    if (existsSync(xdg))
+        return xdg;
+    // 3. Package-relative (dev mode)
+    const legacy = join(dirname(new URL(import.meta.url).pathname), "..", "config.json");
+    if (existsSync(legacy))
+        return legacy;
+    return null;
+}
+function getClientFromWorkingDir(config, cwd) {
+    // Single-property mode: always return the one client
+    const keys = Object.keys(config.clients);
+    if (keys.length === 1 && keys[0] === "default") {
+        return config.clients.default;
+    }
+    for (const [key, client] of Object.entries(config.clients)) {
+        if (cwd.startsWith(client.folder) || cwd.includes(key)) {
+            return client;
+        }
+    }
+    return null;
+}
+// ============================================
+// FEEDBACK
+// ============================================
+const FEEDBACK_DIR = join(homedir(), ".config", "mcp-ga4", "feedback");
+function writeFeedback(filename, entry) {
+    mkdirSync(FEEDBACK_DIR, { recursive: true });
+    appendFileSync(join(FEEDBACK_DIR, filename), JSON.stringify(entry) + "\n");
+}
+// ============================================
+// PARSE HELPERS
+// ============================================
+function splitCsv(s, fallback) {
+    const val = (s || fallback).trim();
+    return val.split(",").map((x) => x.trim()).filter(Boolean);
+}
+function parseFilter(raw) {
+    if (!raw || !raw.includes("=="))
+        return undefined;
+    const [field, value] = raw.split("==", 2);
+    return { field: field.trim(), value: value.trim() };
+}
+// ============================================
+// SERVER
+// ============================================
+const GA4_INSTRUCTIONS = `GA4 Analytics MCP - Query Google Analytics 4 data using natural language.
+
+## Quick Start
+1. Call ga4_get_client_context first to confirm which property you're connected to.
+2. Use ga4_run_report for historical data or ga4_realtime_report for live data.
+
+## Common Dimension & Metric API Names
+Dimensions: date, dateHour, eventName, pagePath, pageTitle, sessionSource,
+  sessionMedium, sessionCampaignName, country, city, deviceCategory,
+  browser, operatingSystem, landingPage, pageReferrer, newVsReturning,
+  firstUserSource, firstUserMedium, firstUserCampaignName
+Metrics: sessions, totalUsers, newUsers, activeUsers, screenPageViews,
+  eventCount, conversions, engagedSessions, engagementRate,
+  averageSessionDuration, bounceRate, sessionsPerUser,
+  screenPageViewsPerSession, userEngagementDuration
+
+## Date Formats
+Use YYYY-MM-DD or relative: "today", "yesterday", "7daysAgo", "30daysAgo", "90daysAgo"
+
+## Common Query Patterns
+- Top pages: dimensions="pagePath", metrics="screenPageViews", order_by="screenPageViews"
+- Traffic sources: dimensions="sessionSource,sessionMedium", metrics="sessions,totalUsers"
+- Daily trend: dimensions="date", metrics="sessions,totalUsers"
+- Campaign performance: dimensions="sessionCampaignName", metrics="sessions,conversions"
+- Device breakdown: dimensions="deviceCategory", metrics="sessions,totalUsers"
+- Geographic: dimensions="country", metrics="sessions,totalUsers"
+
+## Data Freshness
+- Standard reports: 24-48 hour delay
+- Realtime reports: last 30 minutes only
+
+## Feedback
+If a query doesn't return what the user expected, call ga4_suggest_improvement.`;
+async function main() {
+    const config = loadConfig();
+    // Validate credentials at startup
+    const credCheck = validateCredentials(config.credentials_file);
+    if (!credCheck.valid) {
+        logger.error({ error: credCheck.error }, "Credential validation failed -- MCP will start but API calls will fail");
+    }
+    else {
+        logger.info({ type: credCheck.type }, "Credentials validated");
+    }
+    const ga4 = new GA4Manager(config.credentials_file);
+    const server = new Server({ name: "mcp-ga4", version: "1.0.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            switch (name) {
+                // ---- Context ----
+                case "ga4_get_client_context": {
+                    const cwd = args?.working_directory || "";
+                    const client = getClientFromWorkingDir(config, cwd);
+                    if (!client) {
+                        return text({
+                            error: "No client found for working directory",
+                            working_directory: cwd,
+                            available_clients: Object.entries(config.clients).map(([k, v]) => ({ key: k, name: v.name, folder: v.folder })),
+                        });
+                    }
+                    return text({
+                        client_name: client.name,
+                        property_id: client.property_id,
+                        folder: client.folder,
+                        sandbox_measurement_id: client.sandbox_measurement_id,
+                        production_measurement_id: client.production_measurement_id,
+                    });
+                }
+                // ---- Reports ----
+                case "ga4_run_report": {
+                    const result = await ga4.runReport(args?.property_id, splitCsv(args?.dimensions, "eventName"), splitCsv(args?.metrics, "eventCount"), args?.start_date || "7daysAgo", args?.end_date || "today", parseFilter(args?.dimension_filter), args?.limit || 100, args?.order_by || undefined);
+                    return text(result);
+                }
+                case "ga4_realtime_report": {
+                    const result = await ga4.runRealtimeReport(args?.property_id, splitCsv(args?.dimensions, "eventName"), splitCsv(args?.metrics, "eventCount"), parseFilter(args?.dimension_filter));
+                    return text(result);
+                }
+                // ---- Admin ----
+                case "ga4_list_data_streams": {
+                    const result = await ga4.listDataStreams(args?.property_id);
+                    return text(result);
+                }
+                case "ga4_list_custom_dimensions": {
+                    const result = await ga4.listCustomDimensions(args?.property_id);
+                    return text(result);
+                }
+                case "ga4_create_custom_dimension": {
+                    const result = await ga4.createCustomDimension(args?.property_id, args?.parameter_name, args?.display_name, args?.scope || "EVENT", args?.description || "");
+                    return text(result);
+                }
+                case "ga4_list_custom_metrics": {
+                    const result = await ga4.listCustomMetrics(args?.property_id);
+                    return text(result);
+                }
+                // ---- Feedback ----
+                case "ga4_send_feedback": {
+                    const feedbackType = args?.feedback_type;
+                    if (!["bug", "feature", "question"].includes(feedbackType)) {
+                        return text({
+                            error: 'feedback_type must be: bug, feature, or question',
+                        });
+                    }
+                    writeFeedback("feedback.jsonl", {
+                        type: feedbackType,
+                        message: args?.message,
+                        query_context: args?.query_context || "",
+                        timestamp: new Date().toISOString(),
+                    });
+                    return text({
+                        status: "recorded",
+                        feedback_type: feedbackType,
+                        message: "Feedback saved. For urgent issues, file at: https://github.com/drak-marketing/mcp-ga4/issues",
+                    });
+                }
+                case "ga4_suggest_improvement": {
+                    writeFeedback("improvements.jsonl", {
+                        type: "improvement",
+                        failed_query: args?.failed_query,
+                        expected_result: args?.expected_result,
+                        actual_result: args?.actual_result || "",
+                        timestamp: new Date().toISOString(),
+                    });
+                    return text({
+                        status: "recorded",
+                        message: "Query pattern logged for improvement. This helps make GA4 queries more accurate for everyone.",
+                    });
+                }
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+        }
+        catch (rawError) {
+            const error = classifyError(rawError);
+            logger.error({ errorType: error.name, tool: name }, error.message);
+            const response = {
+                error: true,
+                error_type: error.name,
+                message: error.message,
+            };
+            if (error instanceof GA4AuthError) {
+                response.action_required =
+                    "Re-authenticate: run 'npx mcp-ga4-setup' to refresh credentials.";
+            }
+            else if (error instanceof GA4RateLimitError) {
+                response.retry_after_ms = error.retryAfterMs;
+                response.action_required = `Rate limited. Retry after ${Math.ceil(error.retryAfterMs / 1000)} seconds.`;
+            }
+            else if (error instanceof GA4ServiceError) {
+                response.action_required =
+                    "GA4 API server error. This is transient -- retry in a few minutes.";
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("mcp-ga4 server running");
+}
+function text(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+main().catch((err) => logger.error({ error: err.message, stack: err.stack }, "Fatal startup error"));

package/dist/resilience.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Logger, retry/circuit-breaker/timeout, and response size limiting.
+ */
+export declare const logger: import("pino").Logger<never>;
+export declare function safeResponse<T>(data: T, context: string): T;
+export declare function withResilience<T>(fn: () => Promise<T>, operationName: string): Promise<T>;

package/dist/resilience.js

@@ -0,0 +1,79 @@
+/**
+ * Logger, retry/circuit-breaker/timeout, and response size limiting.
+ */
+import { retry, circuitBreaker, wrap, handleAll, timeout, TimeoutStrategy, ExponentialBackoff, ConsecutiveBreaker, } from "cockatiel";
+import pino from "pino";
+// ============================================
+// LOGGER
+// ============================================
+export const logger = pino({
+    level: process.env.LOG_LEVEL || "info",
+    ...(process.env.NODE_ENV !== "test" && {
+        transport: {
+            target: "pino-pretty",
+            options: {
+                colorize: true,
+                singleLine: true,
+                translateTime: "SYS:standard",
+            },
+        },
+    }),
+});
+// ============================================
+// SAFE RESPONSE (Response Size Limiting)
+// ============================================
+const MAX_RESPONSE_SIZE = 200_000; // 200KB
+export function safeResponse(data, context) {
+    const jsonStr = JSON.stringify(data);
+    const sizeBytes = Buffer.byteLength(jsonStr, "utf-8");
+    if (sizeBytes > MAX_RESPONSE_SIZE) {
+        logger.warn({ sizeBytes, maxSize: MAX_RESPONSE_SIZE, context }, "Response exceeds size limit, truncating");
+        if (Array.isArray(data)) {
+            return data.slice(0, Math.max(1, Math.floor(data.length * 0.5)));
+        }
+        if (typeof data === "object" && data !== null) {
+            const obj = data;
+            for (const key of ["items", "results", "data", "rows"]) {
+                if (Array.isArray(obj[key])) {
+                    obj[key] = obj[key].slice(0, Math.max(1, Math.floor(obj[key].length * 0.5)));
+                    return obj;
+                }
+            }
+        }
+    }
+    return data;
+}
+// ============================================
+// RETRY + CIRCUIT BREAKER + TIMEOUT
+// ============================================
+const backoff = new ExponentialBackoff({
+    initialDelay: 100,
+    maxDelay: 5_000,
+});
+const retryPolicy = retry(handleAll, { maxAttempts: 3, backoff });
+const circuitBreakerPolicy = circuitBreaker(handleAll, {
+    halfOpenAfter: 60_000,
+    breaker: new ConsecutiveBreaker(5),
+});
+const timeoutPolicy = timeout(30_000, TimeoutStrategy.Cooperative);
+const policy = wrap(timeoutPolicy, circuitBreakerPolicy, retryPolicy);
+export async function withResilience(fn, operationName) {
+    try {
+        logger.debug({ operation: operationName }, "Starting API call");
+        const result = await policy.execute(() => fn());
+        logger.debug({ operation: operationName }, "API call succeeded");
+        return result;
+    }
+    catch (err) {
+        let error;
+        if (err instanceof Error) {
+            error = err;
+        }
+        else {
+            error = new Error(String(err));
+            error.cause = err;
+        }
+        logger.error({ operation: operationName, error: error.message }, "API call failed after retries");
+        throw error;
+    }
+}

package/dist/setup.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Interactive setup wizard for mcp-ga4.
+ *
+ * Guides users through:
+ * 1. Entering their GA4 property ID
+ * 2. Google OAuth authentication
+ * 3. Connection verification
+ * 4. Claude Code MCP configuration
+ *
+ * OAuth client credentials loaded from env vars or macOS Keychain.
+ */
+export {};

package/dist/setup.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * Interactive setup wizard for mcp-ga4.
+ *
+ * Guides users through:
+ * 1. Entering their GA4 property ID
+ * 2. Google OAuth authentication
+ * 3. Connection verification
+ * 4. Claude Code MCP configuration
+ *
+ * OAuth client credentials loaded from env vars or macOS Keychain.
+ */
+import { createInterface } from "readline";
+import { createServer } from "http";
+import { mkdirSync, writeFileSync, readFileSync, chmodSync } from "fs";
+import { join } from "path";
+import { homedir, platform } from "os";
+import { execSync } from "child_process";
+import { URL } from "url";
+const CONFIG_DIR = join(homedir(), ".config", "mcp-ga4");
+const CREDENTIALS_FILE = join(CONFIG_DIR, "credentials.json");
+const SCOPES = ["https://www.googleapis.com/auth/analytics.readonly"];
+const REDIRECT_PORT = 8087;
+const REDIRECT_URI = `http://localhost:${REDIRECT_PORT}`;
+// ============================================
+// HELPERS
+// ============================================
+function printHeader(text) {
+    console.log(`\n${"=".repeat(50)}`);
+    console.log(`  ${text}`);
+    console.log(`${"=".repeat(50)}\n`);
+}
+function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function getOAuthCredentials() {
+    // Try env vars first
+    let clientId = process.env.OAUTH_CLIENT_ID || "";
+    let clientSecret = process.env.OAUTH_CLIENT_SECRET || "";
+    if (clientId && clientSecret)
+        return { clientId, clientSecret };
+    // Try macOS Keychain
+    if (platform() === "darwin") {
+        try {
+            if (!clientId) {
+                clientId = execSync('security find-generic-password -a mcp-ga4 -s OAUTH_CLIENT_ID -w', { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+            }
+            if (!clientSecret) {
+                clientSecret = execSync('security find-generic-password -a mcp-ga4 -s OAUTH_CLIENT_SECRET -w', { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+            }
+        }
+        catch {
+            // Not found in Keychain
+        }
+    }
+    if (!clientId || !clientSecret) {
+        console.error("OAuth client credentials not found.");
+        console.error("Set OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET environment variables,");
+        console.error("or on macOS, store them in Keychain:");
+        console.error('  security add-generic-password -a mcp-ga4 -s OAUTH_CLIENT_ID -w \'<your-client-id>\'');
+        console.error('  security add-generic-password -a mcp-ga4 -s OAUTH_CLIENT_SECRET -w \'<your-secret>\'');
+        process.exit(1);
+    }
+    return { clientId, clientSecret };
+}
+// ============================================
+// STEPS
+// ============================================
+async function collectPropertyId() {
+    printHeader("Step 1: GA4 Property ID");
+    console.log("Your GA4 property ID is a 9-digit number.");
+    console.log("Find it at: GA4 > Admin (gear icon) > Property Details");
+    console.log("It's listed as 'Property ID' near the top.\n");
+    while (true) {
+        const id = await ask("Enter your GA4 property ID: ");
+        if (/^\d{6,12}$/.test(id))
+            return id;
+        console.log("  That doesn't look right. Enter just the numeric ID (e.g., 331956119).\n");
+    }
+}
+async function runOAuth(clientId, clientSecret) {
+    printHeader("Step 2: Google Authentication");
+    console.log("A browser window will open for Google sign-in.");
+    console.log("Sign in with the Google account that has access to your GA4 property.");
+    console.log('You may see a warning about an unverified app -- click "Advanced"');
+    console.log('then "Go to mcp-ga4 (unsafe)" to continue. This is safe.\n');
+    const authCode = await new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url || "", REDIRECT_URI);
+            const code = url.searchParams.get("code");
+            const error = url.searchParams.get("error");
+            if (code) {
+                res.writeHead(200, { "Content-Type": "text/html" });
+                res.end('<html><body style="font-family:sans-serif;text-align:center;padding:60px">' +
+                    "<h2>Authorization successful!</h2>" +
+                    "<p>You can close this tab and return to your terminal.</p>" +
+                    "</body></html>");
+                server.close();
+                resolve(code);
+            }
+            else {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end(`<h2>Error: ${error || "unknown"}</h2>`);
+                server.close();
+                reject(new Error(`OAuth error: ${error}`));
+            }
+        });
+        server.listen(REDIRECT_PORT, async () => {
+            const scope = encodeURIComponent(SCOPES.join(" "));
+            const authUrl = `https://accounts.google.com/o/oauth2/auth` +
+                `?client_id=${clientId}` +
+                `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
+                `&response_type=code` +
+                `&scope=${scope}` +
+                `&access_type=offline` +
+                `&prompt=consent`;
+            await ask("Press Enter to open your browser for Google sign-in...");
+            // Dynamic import for ESM 'open' package
+            const { default: openBrowser } = await import("open");
+            await openBrowser(authUrl);
+            console.log("Waiting for authorization...");
+        });
+    });
+    // Exchange code for tokens
+    const params = new URLSearchParams({
+        code: authCode,
+        client_id: clientId,
+        client_secret: clientSecret,
+        redirect_uri: REDIRECT_URI,
+        grant_type: "authorization_code",
+    });
+    const resp = await fetch("https://oauth2.googleapis.com/token", {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+    });
+    if (!resp.ok) {
+        const text = await resp.text();
+        console.error(`\nToken exchange failed: ${text}`);
+        process.exit(1);
+    }
+    const tokens = (await resp.json());
+    if (!tokens.refresh_token) {
+        console.error("\nNo refresh token received. Try revoking app access at");
+        console.error("https://myaccount.google.com/permissions and re-running setup.");
+        process.exit(1);
+    }
+    return tokens;
+}
+function saveCredentials(tokens, clientId, clientSecret) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    const creds = {
+        type: "authorized_user",
+        client_id: clientId,
+        client_secret: clientSecret,
+        refresh_token: tokens.refresh_token,
+    };
+    writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2));
+    chmodSync(CREDENTIALS_FILE, 0o600);
+    console.log(`\nCredentials saved to: ${CREDENTIALS_FILE}`);
+    return CREDENTIALS_FILE;
+}
+async function verifyConnection(propertyId, credsFile) {
+    printHeader("Step 3: Verifying Connection");
+    console.log("Testing connection to your GA4 property...");
+    try {
+        // Read creds and get an access token
+        const creds = JSON.parse(readFileSync(credsFile, "utf-8"));
+        const params = new URLSearchParams({
+            grant_type: "refresh_token",
+            client_id: creds.client_id,
+            client_secret: creds.client_secret,
+            refresh_token: creds.refresh_token,
+        });
+        const tokenResp = await fetch("https://oauth2.googleapis.com/token", {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: params.toString(),
+        });
+        if (!tokenResp.ok) {
+            throw new Error(`Token refresh failed: ${await tokenResp.text()}`);
+        }
+        const { access_token } = (await tokenResp.json());
+        // List data streams to verify access
+        const apiResp = await fetch(`https://analyticsadmin.googleapis.com/v1beta/properties/${propertyId}/dataStreams`, { headers: { Authorization: `Bearer ${access_token}` } });
+        if (!apiResp.ok) {
+            throw new Error(`API call failed: ${await apiResp.text()}`);
+        }
+        const data = (await apiResp.json());
+        const streams = data.dataStreams || [];
+        console.log("\nConnected successfully!");
+        console.log(`  Property ID: ${propertyId}`);
+        console.log(`  Data streams found: ${streams.length}`);
+        for (const s of streams) {
+            const mid = s.webStreamData?.measurementId;
+            console.log(`    - ${s.displayName}${mid ? ` (${mid})` : ""}`);
+        }
+        return true;
+    }
+    catch (err) {
+        console.error(`\nConnection failed: ${err.message}`);
+        console.error("\nPossible causes:");
+        console.error("  - Wrong property ID");
+        console.error("  - Your Google account doesn't have access to this property");
+        console.error("  - Try re-running: npx mcp-ga4-setup");
+        return false;
+    }
+}
+function generateConfig(propertyId, credsFile) {
+    printHeader("Step 4: Claude Code Configuration");
+    const mcpConfig = {
+        ga4: {
+            command: "npx",
+            args: ["-y", "mcp-ga4"],
+            env: {
+                GA4_PROPERTY_ID: propertyId,
+                GOOGLE_APPLICATION_CREDENTIALS: credsFile,
+            },
+        },
+    };
+    console.log("Add this to your Claude Code MCP configuration:\n");
+    if (platform() === "darwin") {
+        const configPath = join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+        console.log(`  File: ${configPath}`);
+        console.log("  (Or for Claude Code CLI: add to .mcp.json in your project)\n");
+    }
+    else if (platform() === "win32") {
+        const configPath = join(homedir(), "AppData", "Roaming", "Claude", "claude_desktop_config.json");
+        console.log(`  File: ${configPath}\n`);
+    }
+    else {
+        console.log("  Add to .mcp.json in your project directory:\n");
+    }
+    console.log('Add this inside the "mcpServers" key:\n');
+    console.log(JSON.stringify(mcpConfig, null, 2));
+    // Offer to write .mcp.json
+    console.log(`\n${"=".repeat(50)}`);
+}
+// ============================================
+// MAIN
+// ============================================
+async function main() {
+    printHeader("mcp-ga4 Setup");
+    console.log("This wizard will connect Claude to your Google Analytics 4 property.");
+    console.log("You'll need:");
+    console.log("  1. Your GA4 property ID (a 9-digit number)");
+    console.log("  2. A Google account with access to that GA4 property\n");
+    const { clientId, clientSecret } = getOAuthCredentials();
+    const propertyId = await collectPropertyId();
+    const tokens = await runOAuth(clientId, clientSecret);
+    const credsFile = saveCredentials(tokens, clientId, clientSecret);
+    if (await verifyConnection(propertyId, credsFile)) {
+        generateConfig(propertyId, credsFile);
+        printHeader("Setup Complete!");
+        console.log("You can now use Claude to query your GA4 data.");
+        console.log('Try asking: "What were my top 10 pages last week?"\n');
+        console.log("To update or re-authenticate: npx mcp-ga4-setup");
+        console.log("To report issues: use the ga4_send_feedback tool in Claude\n");
+    }
+    else {
+        process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(`Setup failed: ${err.message}`);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP tool definitions for GA4.
+ */
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const tools: Tool[];