directory changes and restructuring

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-22 02:01:41 +09:00
parent eea49f9f8c
commit 236be6c580
598 changed files with 0 additions and 0 deletions
--- a/ga-agent-skills/docs/01-mcp-servers-overview.md
+++ b/ga-agent-skills/docs/01-mcp-servers-overview.md
@@ -0,0 +1,94 @@
+# MCP Servers Overview for GA Agent
+
+## Available MCP Servers
+
+### Google Analytics MCP Servers
+
+| Server | Language | Source | Status |
+|--------|----------|--------|--------|
+| **google-analytics-mcp** (Official) | Python | [googleanalytics/google-analytics-mcp](https://github.com/googleanalytics/google-analytics-mcp) | Recommended |
+| mcp-server-google-analytics | TypeScript | [ruchernchong/mcp-server-google-analytics](https://github.com/ruchernchong/mcp-server-google-analytics) | Community |
+
+**Official Google GA MCP Features:**
+- Real-time reporting
+- Custom/standard dimensions/metrics
+- Natural language queries (e.g., "top products by revenue")
+- `order_by` support
+- OAuth + Service Account auth
+
+### BigQuery MCP Servers
+
+| Server | Language | npm | Status |
+|--------|----------|-----|--------|
+| **@ergut/mcp-bigquery-server** | Node.js | `npx -y @ergut/mcp-bigquery-server` | Recommended |
+| mcp-server-bigquery | Python | - | Alternative |
+| Google MCP Toolbox | Python | - | Official (multi-DB) |
+
+**ergut/mcp-bigquery-server Features:**
+- Read-only secure access
+- Schema discovery
+- Natural language to SQL
+- 1GB query limit
+
+## Recommended Stack
+
+For our GA Agent, we recommend:
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Claude Code                        │
+│                        │                             │
+│           ┌───────────┴───────────┐                 │
+│           ▼                       ▼                 │
+│  ┌─────────────────┐    ┌─────────────────┐        │
+│  │ Google Analytics│    │    BigQuery     │        │
+│  │   MCP Server    │    │   MCP Server    │        │
+│  └────────┬────────┘    └────────┬────────┘        │
+│           │                      │                  │
+│           ▼                      ▼                  │
+│  ┌─────────────────┐    ┌─────────────────┐        │
+│  │  GA4 Data API   │    │  BigQuery API   │        │
+│  │  GA4 Admin API  │    │  (GA4 Export)   │        │
+│  └─────────────────┘    └─────────────────┘        │
+└─────────────────────────────────────────────────────┘
+```
+
+## Why Both?
+
+1. **GA4 MCP** - Direct API access for:
+   - Real-time data
+   - Quick metrics queries
+   - Account/property management
+
+2. **BigQuery MCP** - For advanced analysis:
+   - Historical data (GA4 → BigQuery export)
+   - Complex SQL queries
+   - Cross-dataset joins
+   - Large-scale analysis
+
+## Prerequisites
+
+### Google Cloud Setup
+
+1. Create a Google Cloud Project (or use existing)
+2. Enable these APIs:
+   - Google Analytics Data API
+   - Google Analytics Admin API
+   - BigQuery API
+
+3. Create Service Account:
+   - Go to IAM & Admin → Service Accounts
+   - Create new service account
+   - Grant roles:
+     - `Analytics Viewer` (or Admin for write ops)
+     - `BigQuery Data Viewer`
+     - `BigQuery Job User`
+   - Download JSON key file
+
+4. Grant GA4 Access:
+   - In GA4 Admin → Property Access Management
+   - Add service account email with Viewer role
+
+## Next Steps
+
+See `02-setup-guide.md` for installation instructions.
--- a/ga-agent-skills/docs/02-setup-guide.md
+++ b/ga-agent-skills/docs/02-setup-guide.md
@@ -0,0 +1,203 @@
+# MCP Server Setup Guide
+
+## Step 1: Google Cloud Prerequisites
+
+### 1.1 Create/Select Project
+
+```bash
+# List existing projects
+gcloud projects list
+
+# Create new project (optional)
+gcloud projects create ga-agent-project --name="GA Agent Project"
+
+# Set active project
+gcloud config set project YOUR_PROJECT_ID
+```
+
+### 1.2 Enable Required APIs
+
+```bash
+# Enable all required APIs
+gcloud services enable \
+  analyticsdata.googleapis.com \
+  analyticsadmin.googleapis.com \
+  bigquery.googleapis.com
+```
+
+### 1.3 Create Service Account
+
+```bash
+# Create service account
+gcloud iam service-accounts create ga-agent-sa \
+  --display-name="GA Agent Service Account"
+
+# Get the email
+SA_EMAIL="ga-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com"
+
+# Grant BigQuery roles
+gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/bigquery.dataViewer"
+
+gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/bigquery.jobUser"
+
+# Create and download key
+gcloud iam service-accounts keys create \
+  ~/ga-agent-credentials.json \
+  --iam-account=$SA_EMAIL
+
+# Move to secure location
+mv ~/ga-agent-credentials.json /path/to/secure/location/
+```
+
+### 1.4 Grant GA4 Property Access
+
+1. Go to [Google Analytics Admin](https://analytics.google.com/analytics/web/)
+2. Select your property
+3. Admin → Property Access Management
+4. Click "+" → Add users
+5. Enter service account email: `ga-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com`
+6. Select role: **Viewer** (or Analyst for more access)
+
+---
+
+## Step 2: Install Google Analytics MCP Server
+
+### Option A: Official Google GA MCP (Python)
+
+```bash
+# Clone the repository
+git clone https://github.com/googleanalytics/google-analytics-mcp.git
+cd google-analytics-mcp
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -e .
+
+# Set credentials
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/ga-agent-credentials.json"
+
+# Test the server
+python -m google_analytics_mcp
+```
+
+### Option B: TypeScript Community Server
+
+```bash
+# Install globally
+npm install -g @anthropic/mcp-server-google-analytics
+
+# Or run with npx
+npx @anthropic/mcp-server-google-analytics
+```
+
+---
+
+## Step 3: Install BigQuery MCP Server
+
+```bash
+# Using npx (recommended - no install needed)
+npx -y @ergut/mcp-bigquery-server \
+  --project-id YOUR_PROJECT_ID \
+  --location us-central1 \
+  --key-file /path/to/ga-agent-credentials.json
+
+# Or install globally
+npm install -g @ergut/mcp-bigquery-server
+```
+
+---
+
+## Step 4: Configure Claude Code
+
+Add to your Claude Code MCP configuration (`~/.claude/mcp_servers.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "google-analytics": {
+      "command": "python",
+      "args": ["-m", "google_analytics_mcp"],
+      "env": {
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/ga-agent-credentials.json"
+      }
+    },
+    "bigquery": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@ergut/mcp-bigquery-server",
+        "--project-id", "YOUR_PROJECT_ID",
+        "--location", "us-central1",
+        "--key-file", "/path/to/ga-agent-credentials.json"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Step 5: Verify Installation
+
+After restarting Claude Code:
+
+```bash
+# Check servers are connected
+mcp-cli servers
+
+# List available tools
+mcp-cli tools google-analytics
+mcp-cli tools bigquery
+```
+
+Expected output should show tools like:
+- `google-analytics/run_report`
+- `google-analytics/run_realtime_report`
+- `bigquery/execute-query`
+- `bigquery/list-tables`
+
+---
+
+## Troubleshooting
+
+### Authentication Errors
+
+```bash
+# Verify credentials
+gcloud auth application-default print-access-token
+
+# Check service account permissions
+gcloud projects get-iam-policy YOUR_PROJECT_ID \
+  --filter="bindings.members:ga-agent-sa"
+```
+
+### GA4 Access Issues
+
+- Ensure service account email is added to GA4 property
+- Wait 5-10 minutes after adding access
+- Check property ID is correct (numeric, not "UA-" format)
+
+### BigQuery Connection Issues
+
+```bash
+# Test BigQuery access directly
+bq ls YOUR_PROJECT_ID:analytics_*
+
+# Check dataset exists
+bq show YOUR_PROJECT_ID:analytics_PROPERTY_ID
+```
+
+---
+
+## Next Steps
+
+1. Set up GA4 → BigQuery export (if not already)
+2. Create visualization tools (see `03-visualization-setup.md`)
+3. Build the Claude Skill
--- a/ga-agent-skills/docs/03-visualization-setup.md
+++ b/ga-agent-skills/docs/03-visualization-setup.md
@@ -0,0 +1,286 @@
+# Visualization Tools Setup
+
+## Overview
+
+For lightweight dashboards displaying GA4/BigQuery insights, we recommend:
+
+| Tool | Best For | Complexity |
+|------|----------|------------|
+| **Streamlit** | Quick Python dashboards | Low |
+| **Plotly Dash** | Interactive charts | Medium |
+| **HTML + Chart.js** | Portable, no server | Low |
+
+## Option 1: Streamlit Dashboard (Recommended)
+
+### Install Dependencies
+
+```bash
+cd /path/to/ga-agent-project/visualization
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate
+
+# Install packages
+pip install streamlit pandas plotly google-cloud-bigquery google-analytics-data
+```
+
+### Basic Dashboard Template
+
+Create `visualization/streamlit_dashboard.py`:
+
+```python
+import streamlit as st
+import pandas as pd
+import plotly.express as px
+from google.cloud import bigquery
+from google.analytics.data_v1beta import BetaAnalyticsDataClient
+from google.analytics.data_v1beta.types import RunReportRequest
+
+# Page config
+st.set_page_config(
+    page_title="GA4 Analytics Dashboard",
+    page_icon="📊",
+    layout="wide"
+)
+
+st.title("📊 GA4 Analytics Dashboard")
+
+# Sidebar for configuration
+with st.sidebar:
+    st.header("Settings")
+    property_id = st.text_input("GA4 Property ID", "YOUR_PROPERTY_ID")
+    date_range = st.selectbox(
+        "Date Range",
+        ["Last 7 days", "Last 30 days", "Last 90 days"]
+    )
+
+# Date mapping
+date_map = {
+    "Last 7 days": "7daysAgo",
+    "Last 30 days": "30daysAgo",
+    "Last 90 days": "90daysAgo"
+}
+
+@st.cache_data(ttl=3600)
+def fetch_ga4_data(property_id: str, start_date: str):
+    """Fetch data from GA4 API"""
+    client = BetaAnalyticsDataClient()
+
+    request = RunReportRequest(
+        property=f"properties/{property_id}",
+        dimensions=[{"name": "date"}],
+        metrics=[
+            {"name": "activeUsers"},
+            {"name": "sessions"},
+            {"name": "screenPageViews"}
+        ],
+        date_ranges=[{"start_date": start_date, "end_date": "today"}]
+    )
+
+    response = client.run_report(request)
+
+    data = []
+    for row in response.rows:
+        data.append({
+            "date": row.dimension_values[0].value,
+            "users": int(row.metric_values[0].value),
+            "sessions": int(row.metric_values[1].value),
+            "pageviews": int(row.metric_values[2].value)
+        })
+
+    return pd.DataFrame(data)
+
+# Fetch and display data
+try:
+    df = fetch_ga4_data(property_id, date_map[date_range])
+
+    # Metrics row
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        st.metric("Total Users", f"{df['users'].sum():,}")
+    with col2:
+        st.metric("Total Sessions", f"{df['sessions'].sum():,}")
+    with col3:
+        st.metric("Total Pageviews", f"{df['pageviews'].sum():,}")
+
+    # Charts
+    st.subheader("Traffic Over Time")
+    fig = px.line(df, x="date", y=["users", "sessions"],
+                  title="Users & Sessions")
+    st.plotly_chart(fig, use_container_width=True)
+
+    # Raw data
+    with st.expander("View Raw Data"):
+        st.dataframe(df)
+
+except Exception as e:
+    st.error(f"Error fetching data: {e}")
+    st.info("Ensure GOOGLE_APPLICATION_CREDENTIALS is set")
+```
+
+### Run Dashboard
+
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
+streamlit run visualization/streamlit_dashboard.py
+```
+
+---
+
+## Option 2: Static HTML Dashboard
+
+For portable reports without a server:
+
+Create `visualization/templates/report.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>GA4 Report</title>
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    <style>
+        body { font-family: -apple-system, sans-serif; margin: 40px; }
+        .metrics { display: flex; gap: 20px; margin-bottom: 40px; }
+        .metric-card {
+            background: #f5f5f5;
+            padding: 20px;
+            border-radius: 8px;
+            flex: 1;
+        }
+        .metric-value { font-size: 32px; font-weight: bold; }
+        .metric-label { color: #666; }
+        .chart-container { max-width: 800px; margin: 40px 0; }
+    </style>
+</head>
+<body>
+    <h1>📊 GA4 Analytics Report</h1>
+    <p>Generated: <span id="date"></span></p>
+
+    <div class="metrics">
+        <div class="metric-card">
+            <div class="metric-value" id="users">--</div>
+            <div class="metric-label">Active Users</div>
+        </div>
+        <div class="metric-card">
+            <div class="metric-value" id="sessions">--</div>
+            <div class="metric-label">Sessions</div>
+        </div>
+        <div class="metric-card">
+            <div class="metric-value" id="pageviews">--</div>
+            <div class="metric-label">Page Views</div>
+        </div>
+    </div>
+
+    <div class="chart-container">
+        <canvas id="trafficChart"></canvas>
+    </div>
+
+    <script>
+        // Data will be injected by Python script
+        const reportData = {{ DATA_JSON }};
+
+        document.getElementById('date').textContent = new Date().toLocaleDateString();
+        document.getElementById('users').textContent = reportData.totals.users.toLocaleString();
+        document.getElementById('sessions').textContent = reportData.totals.sessions.toLocaleString();
+        document.getElementById('pageviews').textContent = reportData.totals.pageviews.toLocaleString();
+
+        new Chart(document.getElementById('trafficChart'), {
+            type: 'line',
+            data: {
+                labels: reportData.dates,
+                datasets: [{
+                    label: 'Users',
+                    data: reportData.users,
+                    borderColor: '#4285f4',
+                    tension: 0.1
+                }, {
+                    label: 'Sessions',
+                    data: reportData.sessions,
+                    borderColor: '#34a853',
+                    tension: 0.1
+                }]
+            },
+            options: {
+                responsive: true,
+                plugins: {
+                    title: { display: true, text: 'Traffic Over Time' }
+                }
+            }
+        });
+    </script>
+</body>
+</html>
+```
+
+---
+
+## Option 3: Python Chart Generation
+
+For generating standalone chart images:
+
+```python
+# visualization/scripts/generate_charts.py
+import pandas as pd
+import plotly.express as px
+import plotly.io as pio
+
+def generate_traffic_chart(df: pd.DataFrame, output_path: str):
+    """Generate traffic chart as HTML or PNG"""
+    fig = px.line(
+        df,
+        x="date",
+        y=["users", "sessions"],
+        title="Traffic Overview",
+        template="plotly_white"
+    )
+
+    fig.update_layout(
+        xaxis_title="Date",
+        yaxis_title="Count",
+        legend_title="Metric"
+    )
+
+    # Save as interactive HTML
+    fig.write_html(f"{output_path}/traffic_chart.html")
+
+    # Save as static image (requires kaleido)
+    # pip install kaleido
+    fig.write_image(f"{output_path}/traffic_chart.png", scale=2)
+
+    return fig
+```
+
+---
+
+## Integration with Claude Skill
+
+The Claude Skill will use these visualization tools via Python scripts:
+
+```
+15-ourdigital-ga-agent/
+├── SKILL.md
+├── scripts/
+│   ├── fetch_ga4_data.py      # Get data from GA4/BigQuery
+│   ├── generate_report.py     # Create visualizations
+│   └── streamlit_app.py       # Launch dashboard
+├── templates/
+│   └── report.html            # Static report template
+└── assets/
+    └── styles.css             # Dashboard styling
+```
+
+## Requirements File
+
+Create `visualization/requirements.txt`:
+
+```
+streamlit>=1.28.0
+pandas>=2.0.0
+plotly>=5.18.0
+google-cloud-bigquery>=3.12.0
+google-analytics-data>=0.18.0
+kaleido>=0.2.1
+```
--- a/ga-agent-skills/docs/PROJECT-PLAN.md
+++ b/ga-agent-skills/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
+```