Elevate Analytics

Production-ready analytics and MCP platform integrating Google Search Console, GA4, PageSpeed Insights, and SEO intelligence.

Installation

1. Install Node.js 22+.
2. Install dependencies:

npm ci

3. Copy environment template and update values:

cp .env.example .env

4. Validate environment:

npm run check:env

Development

Run local development server:

npm run dev

Run with Docker Compose:

docker compose up --build

Google OAuth Setup

1. Create OAuth credentials in Google Cloud Console.
2. Configure authorized callback URL:
   • local: http://localhost:3000/oauth/google/callback
   • production: https://YOUR_CLOUD_RUN_DOMAIN/oauth/google/callback
3. Set these environment variables:
   • GOOGLE_CLIENT_ID
   • GOOGLE_CLIENT_SECRET
   • GOOGLE_REDIRECT_URI

Search Console Setup

1. Ensure OAuth scope includes https://www.googleapis.com/auth/webmasters.readonly.
2. Add and verify your site property in Search Console.
3. Ensure authenticated Google account has required site permissions.

GA4 Setup

1. Ensure OAuth scope includes https://www.googleapis.com/auth/analytics.readonly.
2. Retrieve your GA4 property ID.
3. Confirm API access is enabled for the Google Cloud project.

PageSpeed Setup

1. Enable PageSpeed Insights API in Google Cloud.
2. Set GOOGLE_API_KEY (optional but recommended for quota tracking and reliability).

Cloud Run Deployment

Option A: Cloud Build

gcloud builds submit --config cloudbuild.yaml .

Option B: Scripted Deploy

export GCP_PROJECT_ID=your-project
export GCP_REGION=us-central1
export GCP_SERVICE_NAME=elevate-analytics-mcp
export IMAGE_TAG=$(git rev-parse --short HEAD)
bash scripts/deploy-cloud-run.sh

Secret Manager

Set secrets in Google Secret Manager and bind on deploy:

• jwt-secret
• session-secret
• encryption-key
• google-client-secret
• mcp-api-key

Claude Custom Connector Configuration

1. Deploy the MCP server endpoint on Cloud Run.
2. Use the Cloud Run HTTPS URL with /mcp path in Claude Custom Connector.
3. Provide MCP API key using x-api-key: <MCP_API_KEY> (or Authorization: Bearer <MCP_API_KEY>).
4. Validate MCP discovery:

curl -H "x-api-key: YOUR_MCP_API_KEY" https://YOUR_CLOUD_RUN_URL/mcp

Security and Observability

Implemented production controls:

• Helmet security headers
• CORS controls
• Rate limiting
• Compression
• Trusted proxy support
• Secure cookies (in production)
• Structured JSON logging with Pino
• Health probes: /health, /ready, /live, /version
• Prometheus metrics endpoint: /metrics
• MCP endpoint protection with API key middleware (MCP_API_KEY)

Collected metrics include:

• Request duration
• Memory usage
• CPU usage
• Process uptime
• Google API latency
• Database latency
• Cache hit ratio
• MCP tool execution time
• MCP tool execution count
• Quota usage events

Caching

• Set REDIS_URL to enable Redis-backed caches.
• If Redis is unavailable, the app falls back to the in-memory cache automatically.

Tracing

• Set OTEL_ENABLED=true to emit OpenTelemetry spans.
• Optional: set OTEL_SERVICE_NAME to override the service name.
• Traced operations include OAuth flows, Google APIs, database checks, MCP tools, and incoming HTTP/MCP requests.

Health Endpoints

• GET /health
• GET /ready
• GET /live

Authenticated endpoints:

• GET /version
• GET /metrics
• GET/POST /mcp

Environment Variables

Required in all environments:

• DATABASE_URL

Required in production:

• JWT_SECRET
• SESSION_SECRET
• ENCRYPTION_KEY
• MCP_API_KEY
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GOOGLE_REDIRECT_URI
• GCP_PROJECT_ID
• GCP_REGION
• GCP_SERVICE_NAME

Optional but recommended:

• GOOGLE_API_KEY
• METRICS_AUTH_TOKEN
• ALLOWED_ORIGINS
• LOG_LEVEL

CORS Configuration

• ALLOWED_ORIGINS accepts a comma-separated list of browser origins.
• In development, localhost origins such as http://localhost:3000 and http://127.0.0.1:3000 are allowed automatically.
• In production, unknown origins are rejected.

CI/CD

GitHub Actions workflow at .github/workflows/ci-cd.yml executes:

1. Install
2. Lint
3. Build
4. Test
5. Docker build
6. Cloud Run deployment (main branch)

Cloud Build pipeline at cloudbuild.yaml performs equivalent build and deploy workflow.

Troubleshooting

1. Startup fails due to missing env vars:
   • Run npm run check:env.
2. OAuth callback errors:
   • Verify redirect URI and client credentials.
3. 429/quota errors:
   • Check Google API quotas and logs for quota events.
4. /ready returns non-200:
   • Verify database connectivity and DATABASE_URL.
5. Metrics endpoint unauthorized:
   • Provide Authorization: Bearer <METRICS_AUTH_TOKEN> when token is set.
6. MCP endpoint unauthorized:
   • Provide x-api-key: <MCP_API_KEY> or Authorization: Bearer <MCP_API_KEY>.

Testing

Run quality gates:

npm run lint
npm run build
npm test

Run production smoke checks:

bash scripts/production-check.sh http://localhost:3000

Checklists

• Deployment checklist: docs/deployment-checklist.md
• Production checklist: docs/production-checklist.md