our-claude-skills/ga-agent-skills/docs/PROJECT-PLAN.md

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

# 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

# Navigate to project
cd /Users/ourdigital/Projects/claude-skills-factory/ga-agent-project

# Start with MCP setup
cat 01-mcp-setup/setup-guide.md