Files

Andrew Yim 214247ace2 feat(ga-agent): Add GA Agent project with decomposed architecture

Create workspace for building Google Analytics Claude Skill with:
- 5 independent components (MCP setup, skill, dimension explorer, Slack reporter, realtime watcher)
- Comprehensive project plan and documentation
- Step-by-step setup guides for each component

Components:
1. MCP Setup - GA4 + BigQuery MCP server installation
2. GA Agent Skill - Core Claude Skill for interactive analysis
3. Dimension Explorer - Validate dims/metrics with explanations
4. Slack Reporter - Automated reports to Slack (P2)
5. Realtime Watcher - Real-time monitoring (deferred)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2025-12-21 10:32:13 +09:00

README.md

feat(ga-agent): Add GA Agent project with decomposed architecture

2025-12-21 10:32:13 +09:00

README.md

Component 3: Dimension Explorer

Type: Utility (MCP Server / CLI / Reference) Priority: P1 Status: Not Started

Goal

Validate GA4 dimensions and metrics with detailed explanations.

Features

List all available dimensions/metrics
Validate if a dimension/metric exists
Get description, data type, category
Fuzzy search for typos
Compatibility checking

Implementation Options

Option	Approach	Effort
A	Reference JSON in skill	Low
B	CLI tool	Low
C	MCP Server	Medium

Recommendation: Start with A, upgrade to C later.

Structure

03-dimension-explorer/
├── README.md
├── fetch_metadata.py       # Fetch from GA4 Admin API
├── data/
│   ├── dimensions.json     # All dimensions
│   └── metrics.json        # All metrics
├── explorer.py             # CLI tool (optional)
└── requirements.txt

Data Format

dimensions.json

{
  "dimensions": [
    {
      "apiName": "sessionSource",
      "uiName": "Session source",
      "description": "The source that initiated a session",
      "category": "Traffic source",
      "deprecatedApiNames": []
    }
  ]
}

metrics.json

{
  "metrics": [
    {
      "apiName": "activeUsers",
      "uiName": "Active users",
      "description": "Number of distinct users who visited",
      "category": "User",
      "type": "TYPE_INTEGER",
      "expression": ""
    }
  ]
}

fetch_metadata.py

from google.analytics.admin import AnalyticsAdminServiceClient

def fetch_metadata(property_id: str):
    """Fetch all dimensions and metrics for a property."""
    client = AnalyticsAdminServiceClient()

    # Get metadata
    metadata = client.get_metadata(
        name=f"properties/{property_id}/metadata"
    )

    dimensions = [
        {
            "apiName": d.api_name,
            "uiName": d.ui_name,
            "description": d.description,
            "category": d.category,
        }
        for d in metadata.dimensions
    ]

    metrics = [
        {
            "apiName": m.api_name,
            "uiName": m.ui_name,
            "description": m.description,
            "category": m.category,
            "type": m.type_.name,
        }
        for m in metadata.metrics
    ]

    return {"dimensions": dimensions, "metrics": metrics}

Usage

As Reference (Option A)

Include data/dimensions.json and data/metrics.json in the GA Agent skill's references/ folder.

As CLI (Option B)

# Validate a dimension
python explorer.py validate --dimension sessionSource

# Search for metrics
python explorer.py search --query "user"

# List by category
python explorer.py list --category "Traffic source"

As MCP Server (Option C)

# Run server
python server.py

# Claude can use tools like:
# - validate_dimension
# - validate_metric
# - search_metadata
# - list_by_category

Checklist

fetch_metadata.py created
Metadata fetched and saved
dimensions.json generated
metrics.json generated
explorer.py (optional)
Integrated with GA Agent skill