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 and a fetch-based client to remove GA SDKs, simplify auth, and expose tools for reports (including funnels), realtime, accounts, property metadata, Ads links, and annotations. Also migrated Google MCP connection URLs from decocache.com to deco.site for stable endpoints and OAuth redirects.

• New Features

  • New google-analytics MCP server with Google OAuth2 (read-only) and runtime setup.
  • Tools: run-report, run-funnel-report, run-realtime-report, get-account-summaries, get-property-details, get-custom-dimensions-and-metrics, list-google-ads-links, list-property-annotations.
  • Reports support filters, ordering, pagination, currency, and quota; env helper for Bearer token; README/app.json (+ example) and deploy.json entry.

• Bug Fixes

  • Replaced GA SDKs with a fetch client to resolve google-auth-library type conflicts.
  • Pagination for Admin list endpoints with a MAX_PAGES cap; custom dimensions/metrics fetched in parallel; property annotations use the v1alpha endpoint.
  • Hardened auth/validation: strict normalizeProperty (accepts numeric IDs), sanitized GA errors, Authorization header precedence, 204 response guard, improved token parsing, required metrics in report schemas, and integer limits.
  • Migrated all Google MCP connection URLs to deco.site for correct OAuth redirects and stable connections.

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

[cubic-dev-ai]

4 issues found across 20 files

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