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
parent 173d526cf3
commit 214247ace2
11 changed files with 1690 additions and 0 deletions
--- a/ga-agent-project/docs/PROJECT-PLAN.md
+++ b/ga-agent-project/docs/PROJECT-PLAN.md
@@ -0,0 +1,319 @@
+# 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
+```