feat(analytics): initialize Google Analytics MCP server

[yuriassuncx]

This pull request introduces a new official Google Analytics (GA4) MCP integration under the google-analytics directory. It provides a complete implementation including configuration, authentication, server setup, and a suite of tools for interacting with Google Analytics 4 data and properties. The integration is ready for deployment and includes documentation and template files to help with customization and extension.

The most important changes are grouped as follows:

1. New MCP Integration: Core Implementation

• Added a new google-analytics MCP package with its own package.json, .gitignore, and README.md, establishing the project structure and dependencies. [1] [2] [3]
• Implemented the main server entrypoint in server/main.ts to configure the runtime, set up OAuth for Google Analytics, and register all tools for the MCP.

2. Google Analytics Tools and Functionality

• Added tools for querying Google Analytics data: run-report, run-realtime-report, get-account-summaries, get-property-details, get-custom-dimensions-and-metrics, and list-google-ads-links, each implemented in their respective files under server/tools/. These tools leverage the Google Analytics Data and Admin APIs and are registered in tools/index.ts. [1] [2] [3] [4] [5]
• Provided a set of example tool implementations in example-tool.ts.example to illustrate how to extend the MCP with custom logic, API calls, database queries, and event publishing.

3. Authentication and Environment Handling

• Implemented Google OAuth2 authentication flow for secure access to Analytics data, including helper functions for extracting the access token from the environment (server/lib/env.ts) and a client wrapper for the Google Analytics APIs (server/lib/ga-client.ts). [1] [2]

4. Configuration and Deployment

• Added app.json and app.json.example for MCP metadata, configuration, and deployment customization. [1] [2]
• Updated deploy.json to include the new google-analytics MCP for deployment on the target platform.

5. Documentation and Usage Instructions

• Provided clear setup and usage instructions in README.md, guiding users on configuration, tool implementation, deployment, and testing.
• Added a detailed prompt in server/instructions.ts to guide LLM interactions with the MCP, ensuring correct usage patterns and best practices for querying Analytics data.

---

Summary by cubic

Initialize the GA4 MCP server under google-analytics with OAuth, core tools, and deployment wiring. Enables querying GA4 reports, realtime data, account summaries, and property metadata from the MCP.

• New Features

  • New google-analytics MCP server with OAuth2 (Analytics read-only) and runtime setup.
  • Tools: run-report, run-realtime-report, get-account-summaries, get-property-details, get-custom-dimensions-and-metrics, list-google-ads-links.
  • GA client wrapper and env helpers for token-based auth; guided prompt in server/instructions.ts.
  • Docs and config: README.md, app.json (+ example), and deploy.json entry for deployment.

• Migration

  • Rename google-analytics/app.json.example to app.json and set the connection URL.
  • Build and deploy using the new deploy.json target (entrypoint: ./dist/server/main.js).
  • Authorize via Google OAuth, then start with get-account-summaries to pick a GA4 property.

^{Written for commit feeff43. Summary will update on new commits.}

[cubic-dev-ai]

4 issues found across 20 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="google-analytics/server/tools/properties.ts">

<violation number="1" location="google-analytics/server/tools/properties.ts:23">
P2: Catch blocks unsafely assume thrown values have `.message`, which can mask original errors or throw again for non-Error values.</violation>
</file>

<file name="google-analytics/server/tools/reports.ts">

<violation number="1" location="google-analytics/server/tools/reports.ts:27">
P2: `metrics` is incorrectly optional in GA report tool schemas, allowing requests that should be rejected during input validation.</violation>

<violation number="2" location="google-analytics/server/tools/reports.ts:44">
P2: Catch block can throw a secondary exception by accessing `.message` on non-Error thrown values.</violation>

<violation number="3" location="google-analytics/server/tools/reports.ts:72">
P2: Realtime report catch path also unsafely assumes caught values have `.message`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Catch blocks unsafely assume thrown values have .message, which can mask original errors or throw again for non-Error values.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At google-analytics/server/tools/properties.ts, line 23:

<comment>Catch blocks unsafely assume thrown values have `.message`, which can mask original errors or throw again for non-Error values.</comment>

<file context>
@@ -0,0 +1,55 @@
+        
+        return { response };
+      } catch (error: any) {
+        throw new Error(`Failed to retrieve property details: ${error.message}`);
+      }
+    },
</file context>

[cubic-dev-ai]

P2: metrics is incorrectly optional in GA report tool schemas, allowing requests that should be rejected during input validation.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At google-analytics/server/tools/reports.ts, line 27:

<comment>`metrics` is incorrectly optional in GA report tool schemas, allowing requests that should be rejected during input validation.</comment>

<file context>
@@ -0,0 +1,75 @@
+      property: z.string().describe("The Google Analytics Property identifier e.g. 'properties/1234567'"),
+      dateRanges: z.array(DateRangeSchema).min(1).describe("Date ranges to query."),
+      dimensions: z.array(DimensionSchema).optional().describe("Dimensions requested and displayed."),
+      metrics: z.array(MetricSchema).optional().describe("Metrics requested and displayed."),
+      limit: z.number().optional().describe("Maximum number of rows to return."),
+    }),
</file context>

[cubic-dev-ai]

P2: Realtime report catch path also unsafely assumes caught values have .message.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At google-analytics/server/tools/reports.ts, line 72:

<comment>Realtime report catch path also unsafely assumes caught values have `.message`.</comment>

<file context>
@@ -0,0 +1,75 @@
+        
+        return { response };
+      } catch (error: any) {
+        throw new Error(`Failed to run realtime report: ${error.message}`);
+      }
+    },
</file context>

[cubic-dev-ai]

P2: Catch block can throw a secondary exception by accessing .message on non-Error thrown values.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At google-analytics/server/tools/reports.ts, line 44:

<comment>Catch block can throw a secondary exception by accessing `.message` on non-Error thrown values.</comment>

<file context>
@@ -0,0 +1,75 @@
+        
+        return { response };
+      } catch (error: any) {
+        throw new Error(`Failed to run report: ${error.message}`);
+      }
+    },
</file context>