mcp-ga4 1.0.0 → 1.1.0

package/README.md

@@ -20,29 +20,15 @@ This will:
 Click **Advanced** then **Go to mcp-ga4 (unsafe)** to continue. This is safe --
 the app only requests read-only access to your analytics data.
 
-### 2. Configure Claude Code
+### 2. Restart Claude Code
 
-Copy the JSON snippet from the setup wizard into your Claude Code MCP config.
+The setup wizard automatically registers the GA4 server with Claude Code.
+Just restart Claude Code to pick it up:
 
-The snippet looks like:
+- **CLI:** Exit and reopen `claude`
+- **Desktop app:** Quit and reopen the app
 
-```json
-{
-  "ga4": {
-    "command": "npx",
-    "args": ["-y", "mcp-ga4"],
-    "env": {
-      "GA4_PROPERTY_ID": "YOUR_PROPERTY_ID",
-      "GOOGLE_APPLICATION_CREDENTIALS": "~/.config/mcp-ga4/credentials.json"
-    }
-  }
-}
-```
-
-- **Claude Desktop (Mac):** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Claude Code CLI:** `.mcp.json` in your project directory
-
-That's it. No Python, no pip, no venv. Just `npx`.
+That's it. No config files to edit, no JSON to paste. Just `npx` and restart.
 
 ## Usage
 
@@ -72,10 +58,6 @@ Go to https://myaccount.google.com/permissions, remove "mcp-ga4", then re-run `n
 Your Google account may not have access to the GA4 property. Check your access at
 GA4 > Admin > Account Access Management.
 
-**"OAuth client credentials not found"**
-The setup needs OAuth client credentials. Set `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`
-environment variables, or on macOS store them in Keychain (the setup will guide you).
-
 **Token expired**
 Re-run `npx mcp-ga4-setup` to refresh your credentials.
 

package/dist/ga4.d.ts

@@ -19,5 +19,6 @@ export declare class GA4Manager {
     listDataStreams(propertyId: string): Promise<any>;
     listCustomDimensions(propertyId: string): Promise<any>;
     createCustomDimension(propertyId: string, parameterName: string, displayName: string, scope: string, description: string): Promise<any>;
+    healthCheck(propertyId: string): Promise<any>;
     listCustomMetrics(propertyId: string): Promise<any>;
 }

package/dist/ga4.js

@@ -118,6 +118,39 @@ export class GA4Manager {
             scope: result.scope,
         };
     }
+    async healthCheck(propertyId) {
+        const checks = {};
+        // Check 1: Credentials file
+        try {
+            const { readFileSync } = await import("fs");
+            readFileSync(this.credentialsFile, "utf-8");
+            checks.credentials_file = "ok";
+        }
+        catch (err) {
+            checks.credentials_file = `FAIL: ${err.message}`;
+            return { status: "unhealthy", checks };
+        }
+        // Check 2: Token refresh
+        try {
+            const token = await getAccessToken(this.credentialsFile);
+            checks.token_refresh = token ? "ok" : "FAIL: no token returned";
+        }
+        catch (err) {
+            checks.token_refresh = `FAIL: ${err.message}`;
+            return { status: "unhealthy", checks };
+        }
+        // Check 3: GA4 API access
+        try {
+            const data = await this.request(`${ADMIN_API}/properties/${propertyId}/dataStreams`);
+            const count = (data.dataStreams || []).length;
+            checks.ga4_api = `ok (${count} data stream${count !== 1 ? "s" : ""})`;
+        }
+        catch (err) {
+            checks.ga4_api = `FAIL: ${err.message}`;
+            return { status: "unhealthy", checks };
+        }
+        return { status: "healthy", property_id: propertyId, checks };
+    }
     async listCustomMetrics(propertyId) {
         const data = await withResilience(() => this.request(`${ADMIN_API}/properties/${propertyId}/customMetrics`), "listCustomMetrics");
         const metrics = (data.customMetrics || []).map((m) => ({

package/dist/index.js

@@ -205,6 +205,11 @@ async function main() {
                     const result = await ga4.listCustomMetrics(args?.property_id);
                     return text(result);
                 }
+                // ---- Health Check ----
+                case "ga4_health_check": {
+                    const result = await ga4.healthCheck(args?.property_id);
+                    return text(result);
+                }
                 // ---- Feedback ----
                 case "ga4_send_feedback": {
                     const feedbackType = args?.feedback_type;

package/dist/setup.js

@@ -14,7 +14,7 @@ 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 { homedir } from "os";
 import { execSync } from "child_process";
 import { URL } from "url";
 const CONFIG_DIR = join(homedir(), ".config", "mcp-ga4");
@@ -22,6 +22,11 @@ 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}`;
+// OAuth app credentials (not user secrets -- identifies the app, not the user).
+// Google docs: client_secret for Desktop/CLI OAuth apps is not confidential.
+// Each user gets their own refresh_token via the consent flow below.
+const DEFAULT_CLIENT_ID = "557294086068-o7rb5neg65g28uf65j85q0h60cop40j9.apps.googleusercontent.com";
+const DEFAULT_CLIENT_SECRET = "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";
 // ============================================
 // HELPERS
 // ============================================
@@ -40,33 +45,9 @@ function ask(question) {
     });
 }
 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);
-    }
+    // Allow override via env vars (for users with their own GCP project)
+    const clientId = process.env.OAUTH_CLIENT_ID || DEFAULT_CLIENT_ID;
+    const clientSecret = process.env.OAUTH_CLIENT_SECRET || DEFAULT_CLIENT_SECRET;
     return { clientId, clientSecret };
 }
 // ============================================
@@ -212,35 +193,60 @@ async function verifyConnection(propertyId, credsFile) {
         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,
+function registerWithClaude(propertyId, credsFile) {
+    printHeader("Step 4: Registering with Claude Code");
+    // Try claude mcp add (works if Claude Code CLI is installed)
+    try {
+        execSync("claude --version", { stdio: "pipe" });
+    }
+    catch {
+        // claude CLI not found -- fall back to manual instructions
+        console.log("Claude Code CLI not detected. Add this to your .mcp.json manually:\n");
+        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");
+        };
+        console.log(JSON.stringify({ mcpServers: mcpConfig }, null, 2));
+        return false;
     }
-    else if (platform() === "win32") {
-        const configPath = join(homedir(), "AppData", "Roaming", "Claude", "claude_desktop_config.json");
-        console.log(`  File: ${configPath}\n`);
+    // Remove existing ga4 server if present (ignore errors)
+    try {
+        execSync("claude mcp remove ga4 -s user", { stdio: "pipe" });
     }
-    else {
-        console.log("  Add to .mcp.json in your project directory:\n");
+    catch {
+        // not present, that's fine
+    }
+    const cmd = `claude mcp add -s user` +
+        ` -e GA4_PROPERTY_ID=${propertyId}` +
+        ` -e GOOGLE_APPLICATION_CREDENTIALS=${credsFile}` +
+        ` ga4 -- npx -y mcp-ga4`;
+    try {
+        execSync(cmd, { stdio: "inherit" });
+        console.log("\nGA4 server registered with Claude Code.");
+        return true;
+    }
+    catch (err) {
+        console.error(`\nFailed to register automatically: ${err.message}`);
+        console.log("Add this to your .mcp.json manually:\n");
+        const mcpConfig = {
+            ga4: {
+                command: "npx",
+                args: ["-y", "mcp-ga4"],
+                env: {
+                    GA4_PROPERTY_ID: propertyId,
+                    GOOGLE_APPLICATION_CREDENTIALS: credsFile,
+                },
+            },
+        };
+        console.log(JSON.stringify({ mcpServers: mcpConfig }, null, 2));
+        return false;
     }
-    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
@@ -256,10 +262,19 @@ async function main() {
     const tokens = await runOAuth(clientId, clientSecret);
     const credsFile = saveCredentials(tokens, clientId, clientSecret);
     if (await verifyConnection(propertyId, credsFile)) {
-        generateConfig(propertyId, credsFile);
+        const autoRegistered = registerWithClaude(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');
+        if (autoRegistered) {
+            console.log("GA4 is now connected to Claude Code.\n");
+            console.log("IMPORTANT: Restart Claude Code to load the new server.");
+            console.log("  - CLI: exit and reopen claude");
+            console.log("  - Desktop app: quit and reopen the app\n");
+            console.log('Then try asking: "What were my top 10 pages last week?"\n');
+        }
+        else {
+            console.log("After adding the config, restart Claude Code to load the server.\n");
+            console.log('Then 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");
     }

package/dist/tools.js

@@ -168,6 +168,20 @@ export const tools = [
             required: ["property_id"],
         },
     },
+    {
+        name: "ga4_health_check",
+        description: "Verify that GA4 credentials are valid and the API is accessible. Run this to diagnose connection issues.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                property_id: {
+                    type: "string",
+                    description: "GA4 property ID (numeric)",
+                },
+            },
+            required: ["property_id"],
+        },
+    },
     {
         name: "ga4_send_feedback",
         description: "Send feedback about the GA4 tools. Use when a query didn't work as expected, to request a feature, or ask a question.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ga4",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for querying Google Analytics 4 with natural language via Claude",
   "main": "dist/index.js",
   "type": "module",
@@ -27,6 +27,14 @@
   },
   "keywords": ["mcp", "ga4", "google-analytics", "claude", "analytics"],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mharnett/mcp-ga4.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mharnett/mcp-ga4/issues"
+  },
+  "homepage": "https://github.com/mharnett/mcp-ga4#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^0.5.0",
     "cockatiel": "^3.2.1",