# 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

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

### metrics.json

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

## fetch_metadata.py

```python
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)

```bash
# 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)

```bash
# 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