Andrew Yim
214247ace2
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>
320 lines
9.7 KiB
Markdown
320 lines
9.7 KiB
Markdown
# GA Agent Project Plan (Revised)
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Infrastructure │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
|
│ │ GA4 MCP │ │ BigQuery MCP │ │ Dimension Explorer│ │
|
|
│ │ (install) │ │ (install) │ │ (build - small) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Claude Skill │
|
|
│ ┌──────────────────────────────────────────────────────┐ │
|
|
│ │ 15-ourdigital-ga-agent │ │
|
|
│ │ • Interactive analysis │ │
|
|
│ │ • Report generation │ │
|
|
│ │ • Period comparisons │ │
|
|
│ └──────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Standalone Services (Later) │
|
|
│ ┌────────────────────┐ ┌────────────────────────────┐ │
|
|
│ │ ga4-slack-reporter │ │ ga4-realtime-watcher │ │
|
|
│ │ (Python service) │ │ (defer or API-based) │ │
|
|
│ └────────────────────┘ └────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Components
|
|
|
|
| # | Component | Type | Priority | Effort |
|
|
|---|-----------|------|----------|--------|
|
|
| 1 | MCP Setup | Infrastructure | P0 | Low |
|
|
| 2 | ga-agent-skill | Claude Skill | P0 | Medium |
|
|
| 3 | dimension-explorer | MCP Server / CLI | P1 | Low |
|
|
| 4 | slack-reporter | Standalone Service | P2 | Medium |
|
|
| 5 | realtime-watcher | Standalone Service | P3 | High (defer) |
|
|
|
|
---
|
|
|
|
## Component 1: MCP Setup
|
|
|
|
**Location:** `01-mcp-setup/`
|
|
|
|
**Goal:** Install and configure existing MCP servers
|
|
|
|
### Tasks
|
|
|
|
- [ ] Google Cloud project setup
|
|
- [ ] Enable Analytics Data API
|
|
- [ ] Enable Analytics Admin API
|
|
- [ ] Enable BigQuery API
|
|
- [ ] Service account creation
|
|
- [ ] Create service account
|
|
- [ ] Grant Analytics Viewer role
|
|
- [ ] Grant BigQuery Data Viewer role
|
|
- [ ] Download JSON key
|
|
- [ ] GA4 property access
|
|
- [ ] Add service account to GA4 property
|
|
- [ ] Install GA4 MCP server
|
|
- [ ] Clone `googleanalytics/google-analytics-mcp`
|
|
- [ ] Configure credentials
|
|
- [ ] Test connection
|
|
- [ ] Install BigQuery MCP server
|
|
- [ ] Configure `@ergut/mcp-bigquery-server`
|
|
- [ ] Verify GA4 export dataset access
|
|
- [ ] Add to Claude Code config
|
|
- [ ] Update `~/.claude/mcp_servers.json`
|
|
- [ ] Verify with `mcp-cli servers`
|
|
|
|
### Deliverables
|
|
|
|
- `01-mcp-setup/setup-guide.md` - Step-by-step instructions
|
|
- `01-mcp-setup/mcp-config.example.json` - Example MCP configuration
|
|
- Working MCP connections verified
|
|
|
|
---
|
|
|
|
## Component 2: GA Agent Skill (Core)
|
|
|
|
**Location:** `02-ga-agent-skill/` → Final: `ourdigital-custom-skills/15-ourdigital-ga-agent/`
|
|
|
|
**Goal:** Interactive GA4 analysis and reporting skill
|
|
|
|
### Features
|
|
|
|
| Feature | Description |
|
|
|---------|-------------|
|
|
| Traffic Analysis | Users, sessions, pageviews with trends |
|
|
| Period Comparison | WoW, MoM, YoY comparisons |
|
|
| Top Content | Pages, sources, campaigns |
|
|
| Report Generation | HTML/PDF reports |
|
|
| BigQuery Queries | Complex analysis on exported data |
|
|
|
|
### Triggers (EN/KR)
|
|
|
|
- "Analyze GA4 traffic" / "GA4 트래픽 분석"
|
|
- "Compare last week vs this week" / "지난주 대비 비교"
|
|
- "Generate traffic report" / "트래픽 리포트 생성"
|
|
- "Top landing pages" / "인기 랜딩 페이지"
|
|
- "Query BigQuery for GA data" / "BigQuery GA 데이터 조회"
|
|
|
|
### Structure
|
|
|
|
```
|
|
15-ourdigital-ga-agent/
|
|
├── SKILL.md
|
|
├── scripts/
|
|
│ ├── analyze_traffic.py
|
|
│ ├── compare_periods.py
|
|
│ ├── top_content.py
|
|
│ └── generate_report.py
|
|
├── templates/
|
|
│ └── report.html
|
|
├── references/
|
|
│ └── ga4-api-reference.md
|
|
└── examples/
|
|
└── sample-queries.md
|
|
```
|
|
|
|
### Tasks
|
|
|
|
- [ ] Create SKILL.md with triggers
|
|
- [ ] Build analysis scripts
|
|
- [ ] analyze_traffic.py
|
|
- [ ] compare_periods.py
|
|
- [ ] top_content.py
|
|
- [ ] Create report template
|
|
- [ ] Add examples
|
|
- [ ] Test with Claude Code
|
|
- [ ] Move to `ourdigital-custom-skills/15-ourdigital-ga-agent/`
|
|
|
|
---
|
|
|
|
## Component 3: Dimension Explorer
|
|
|
|
**Location:** `03-dimension-explorer/`
|
|
|
|
**Goal:** Validate GA4 dimensions/metrics with explanations
|
|
|
|
### Options
|
|
|
|
| Option | Pros | Cons |
|
|
|--------|------|------|
|
|
| **A. MCP Server** | Claude can use directly | More setup |
|
|
| **B. CLI Tool** | Simple, standalone | Manual invocation |
|
|
| **C. Reference JSON** | No code needed | Static, needs refresh |
|
|
|
|
**Recommendation:** Start with C (Reference JSON), upgrade to A (MCP Server) later
|
|
|
|
### Features
|
|
|
|
- List all available dimensions/metrics
|
|
- Validate if a dimension/metric exists
|
|
- Get description, data type, category
|
|
- Fuzzy search for typos
|
|
- Compatibility checking
|
|
|
|
### Structure
|
|
|
|
```
|
|
03-dimension-explorer/
|
|
├── README.md
|
|
├── fetch_metadata.py # Script to refresh metadata
|
|
├── data/
|
|
│ ├── dimensions.json # All dimensions with descriptions
|
|
│ └── metrics.json # All metrics with descriptions
|
|
└── explorer.py # CLI tool (optional)
|
|
```
|
|
|
|
### Tasks
|
|
|
|
- [ ] Fetch metadata from GA4 Admin API
|
|
- [ ] Structure as searchable JSON
|
|
- [ ] Create CLI explorer (optional)
|
|
- [ ] Document usage
|
|
|
|
---
|
|
|
|
## Component 4: Slack Reporter
|
|
|
|
**Location:** `04-slack-reporter/`
|
|
|
|
**Goal:** Automated GA4 reports to Slack
|
|
|
|
### Features
|
|
|
|
| Report | Schedule | Content |
|
|
|--------|----------|---------|
|
|
| Daily Summary | 9:00 AM | Users, sessions, top pages |
|
|
| Weekly Digest | Monday 9 AM | WoW comparison, trends |
|
|
| Anomaly Alert | Real-time | Traffic ±30% from baseline |
|
|
|
|
### Structure
|
|
|
|
```
|
|
04-slack-reporter/
|
|
├── README.md
|
|
├── config.yaml # Schedules, channels, properties
|
|
├── reporter.py # Main service
|
|
├── queries/
|
|
│ ├── daily_summary.py
|
|
│ ├── weekly_digest.py
|
|
│ └── anomaly_check.py
|
|
├── templates/
|
|
│ └── slack_blocks.py # Slack Block Kit templates
|
|
├── requirements.txt
|
|
└── Dockerfile # For deployment
|
|
```
|
|
|
|
### Tasks
|
|
|
|
- [ ] Create Slack App
|
|
- [ ] Build query functions
|
|
- [ ] Create Slack message templates
|
|
- [ ] Implement scheduler
|
|
- [ ] Add Docker deployment
|
|
- [ ] Document setup
|
|
|
|
---
|
|
|
|
## Component 5: Realtime Watcher (Deferred)
|
|
|
|
**Location:** `05-realtime-watcher/`
|
|
|
|
**Goal:** Real-time monitoring snapshots to Slack
|
|
|
|
**Status:** Deferred — revisit after components 1-4 complete
|
|
|
|
### Simplified Approach (API-based)
|
|
|
|
Instead of screenshots:
|
|
1. Fetch real-time data via GA4 Real-time API
|
|
2. Generate chart image with Plotly/Matplotlib
|
|
3. Send to Slack
|
|
|
|
### Structure (Future)
|
|
|
|
```
|
|
05-realtime-watcher/
|
|
├── README.md
|
|
├── realtime_api.py # Fetch real-time data
|
|
├── chart_generator.py # Generate chart images
|
|
├── watcher.py # Main service
|
|
└── config.yaml
|
|
```
|
|
|
|
---
|
|
|
|
## Build Order
|
|
|
|
```
|
|
Phase 1: Foundation
|
|
├── [1] MCP Setup ←── START HERE
|
|
└── [2] GA Agent Skill (core)
|
|
|
|
Phase 2: Enhancements
|
|
├── [3] Dimension Explorer
|
|
└── [4] Slack Reporter
|
|
|
|
Phase 3: Advanced (Deferred)
|
|
└── [5] Realtime Watcher
|
|
```
|
|
|
|
---
|
|
|
|
## Environment Setup
|
|
|
|
### Required Credentials
|
|
|
|
```bash
|
|
# Google Cloud
|
|
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
|
|
GA4_PROPERTY_ID=123456789
|
|
BIGQUERY_PROJECT_ID=your-project
|
|
|
|
# Slack (for Component 4)
|
|
SLACK_BOT_TOKEN=xoxb-...
|
|
SLACK_CHANNEL_ID=C0123456789
|
|
```
|
|
|
|
### Python Dependencies
|
|
|
|
```
|
|
# Core (Components 1-3)
|
|
google-analytics-data>=0.18.0
|
|
google-cloud-bigquery>=3.12.0
|
|
google-auth>=2.23.0
|
|
pandas>=2.0.0
|
|
|
|
# Visualization
|
|
plotly>=5.18.0
|
|
jinja2>=3.1.0
|
|
|
|
# Slack Reporter (Component 4)
|
|
slack-sdk>=3.23.0
|
|
apscheduler>=3.10.0
|
|
pyyaml>=6.0
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Navigate to project
|
|
cd /Users/ourdigital/Projects/claude-skills-factory/ga-agent-project
|
|
|
|
# Start with MCP setup
|
|
cat 01-mcp-setup/setup-guide.md
|
|
```
|