our-claude-skills/ga-agent-skills/03-dimension-explorer/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