Andrew Yim
236be6c580
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
155 lines
3.1 KiB
Markdown
155 lines
3.1 KiB
Markdown
# 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
|