Chore/merge upstream

.claude/commands/analyze-performance.md

@@ -8,21 +8,32 @@ Analyze Google Ads and GA4 performance: $ARGUMENTS
 ## 1. Pull data (AdLoop MCP)
 
 - `get_campaign_performance` — relevant date range (default: last 30 days)
+- `get_impression_share` — visibility and lost opportunity analysis
+- `get_bid_strategy_status` — check learning status and strategy health
 - `analyze_campaign_conversions` — cross-referenced Ads + GA4 data with GDPR gap detection
 - If specific campaigns mentioned, filter by name
 - If keywords are relevant, also pull `get_keyword_performance` and `get_search_terms`
+- If budget concerns, pull `get_budget_pacing` for month-to-date pacing
 
 **Context tip:** for the account-wide pass, call the performance tools with `compact=true` — you get totals, top-10 rows, and pre-computed offender lists instead of every row. Only switch to full mode when drilling into a specific campaign/keyword. In harnesses that support subagents, this whole data-pull step can be delegated to a subagent that returns just the summary.
 
 ## 2. Analyze
 
 - Spend, Clicks, Conversions, CPA, CTR per campaign
+- Impression share: search IS, budget-lost IS, rank-lost IS — identify visibility gaps
+- Bid strategy status: any campaigns in learning phase? Appropriate strategy type?
 - Paid vs organic comparison (from non_paid_channels)
 - GDPR gap (clicks vs sessions ratio — 2:1 to 5:1 is normal in EU)
-- Flag: zero conversions with significant spend, CPA > 3x target, QS < 5, wasteful search terms
+- Flag: zero conversions with significant spend, CPA > 3x target, QS < 5, wasteful search terms, high budget-lost IS
 
 If conversion issues found: run `attribution_check`
 If landing page problems suspected: run `landing_page_analysis`
+If quality scores are low: run `get_quality_score_details` for component breakdowns
+If device performance varies: run `get_device_performance` to compare mobile vs desktop
+If performance changed unexpectedly: run `get_change_history` to correlate with account changes
+If geographic waste suspected: run `get_location_performance` to identify underperforming areas
+If timing patterns matter: run `get_ad_schedule_performance` for hour/day analysis
+If competitive context needed: run `get_auction_insights` (requires allowlisted account)
 
 ## 3. Present results
 

CLAUDE.md

@@ -19,12 +19,12 @@ src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' vs MCP server
 ├── server.py          # FastMCP server — all tool registrations + toolset tags
 ├── config.py          # Config loader (~/.adloop/config.yaml)
-├── auth.py            # OAuth 2.0 (user-supplied credentials, headless fallback) + service accounts
+├── auth.py            # OAuth 2.0 (user-supplied credentials, headless fallback) + service accounts + token refresh
 ├── cli.py             # Interactive setup wizard (own Google Cloud project + auto-discovery)
-├── crossref.py        # Cross-reference tools (GA4 + Ads combined)
+├── crossref.py        # Cross-reference tools (GA4 + Ads, incl. analyze_pmax_performance)
 ├── tracking.py        # Tracking validation + code generation
 ├── ga4/               # GA4 Data + Admin API (reports, realtime, events)
-├── ads/               # Google Ads API (read, write, GAQL, forecasting, PMax, recommendations)
+├── ads/               # Google Ads API (read, write, GAQL, forecasting, pmax_read, pmax_write, labels, recommendations)
 └── safety/            # Guards, previews, audit logging
 ```
 
@@ -34,13 +34,13 @@ All tool usage rules, safety protocols, orchestration patterns, GAQL reference,
 
 **Read and follow `.claude/rules/adloop.md` for all AdLoop MCP tool orchestration.**
 
-That file is the complete guide for combining AdLoop's tools. It covers:
+That file is the complete guide for combining AdLoop's tools (Search + Performance Max read & write + Image upload + Labels + Recommendations). It covers:
 - Tool inventory with parameters and when to use each
 - 9 safety rules (budget caps, dry-run defaults, Broad Match prevention, pre-write validation)
-- 16 orchestration patterns (performance review, PMax analysis, recommendations, ad creation, tracking diagnosis, etc.)
-- GAQL quick reference with syntax, common queries, and gotchas
+- 16 orchestration patterns (performance review, PMax analysis & diagnostics, recommendations, ad creation, tracking diagnosis, etc.)
+- GAQL quick reference with syntax, common queries, and gotchas (incl. asset_group, asset_group_asset)
 - GDPR consent awareness for EU markets
-- Ad copy character limits and marketing best practices
+- Ad copy character limits and marketing best practices (incl. PMax-specific notes)
 
 ## Documentation Site
 

scripts/install.sh

@@ -0,0 +1,329 @@
+#!/bin/bash
+# ==============================================================================
+# GAds-MCP Installer
+# Rossman Media - Google Ads MCP Setup
+#
+# This script installs GAds-MCP (AdLoop) and connects it to Claude.
+# Run the pre-flight check first to make sure your machine is ready.
+#
+# Usage: curl -sSL https://raw.githubusercontent.com/alexrich700/GAds-MCP/main/scripts/install.sh | bash
+# ==============================================================================
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+REPO_URL="https://github.com/alexrich700/GAds-MCP.git"
+INSTALL_DIR="$HOME/.gads-mcp"
+CONFIG_DIR="$HOME/.adloop"
+CLAUDE_CONFIG_DIR="$HOME/Library/Application Support/Claude"
+CLAUDE_CONFIG_FILE="$CLAUDE_CONFIG_DIR/claude_desktop_config.json"
+
+echo ""
+echo "==========================================="
+echo "  GAds-MCP Installer"
+echo "  Rossman Media"
+echo "==========================================="
+echo ""
+
+# -------------------------------------------
+# 1. Check prerequisites
+# -------------------------------------------
+echo -e "${BOLD}Step 1/6: Checking prerequisites...${NC}"
+
+# Find Python 3.11+ (check versioned commands, Homebrew paths, then generic python3)
+PYTHON_CMD=""
+for cmd in python3.13 python3.12 python3.11; do
+    if command -v "$cmd" &> /dev/null; then
+        ver=$("$cmd" --version 2>&1 | awk '{print $2}')
+        minor=$(echo "$ver" | cut -d. -f2)
+        if [[ "$minor" -ge 11 ]]; then
+            PYTHON_CMD="$cmd"
+            break
+        fi
+    fi
+done
+if [[ -z "$PYTHON_CMD" ]]; then
+    for brew_cmd in /opt/homebrew/bin/python3.13 /opt/homebrew/bin/python3.12 /opt/homebrew/bin/python3.11 /usr/local/bin/python3.13 /usr/local/bin/python3.12 /usr/local/bin/python3.11; do
+        if [[ -x "$brew_cmd" ]]; then
+            ver=$("$brew_cmd" --version 2>&1 | awk '{print $2}')
+            minor=$(echo "$ver" | cut -d. -f2)
+            if [[ "$minor" -ge 11 ]]; then
+                PYTHON_CMD="$brew_cmd"
+                break
+            fi
+        fi
+    done
+fi
+if [[ -z "$PYTHON_CMD" ]]; then
+    if command -v python3 &> /dev/null; then
+        ver=$(python3 --version 2>&1 | awk '{print $2}')
+        minor=$(echo "$ver" | cut -d. -f2)
+        if [[ "$minor" -ge 11 ]]; then
+            PYTHON_CMD="python3"
+        fi
+    fi
+fi
+if [[ -z "$PYTHON_CMD" ]]; then
+    echo -e "${RED}Error: Python 3.11+ not found. Run the pre-flight check first.${NC}"
+    echo -e "  Tried: python3.12, python3.11, /opt/homebrew/bin/python3.12, python3"
+    exit 1
+fi
+
+PY_VERSION=$("$PYTHON_CMD" --version 2>&1 | awk '{print $2}')
+echo -e "  ${GREEN}Python $PY_VERSION (using: $PYTHON_CMD)${NC}"
+
+# Git
+if ! command -v git &> /dev/null; then
+    echo -e "${RED}Error: Git not found. Run the pre-flight check first.${NC}"
+    exit 1
+fi
+echo -e "  ${GREEN}Git OK${NC}"
+echo ""
+
+# -------------------------------------------
+# 2. Install uv if needed
+# -------------------------------------------
+echo -e "${BOLD}Step 2/6: Setting up package manager...${NC}"
+
+if ! command -v uv &> /dev/null; then
+    echo "  Installing uv..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh 2>/dev/null
+
+    # Source the env so uv is available in this session
+    if [[ -f "$HOME/.local/bin/env" ]]; then
+        source "$HOME/.local/bin/env"
+    fi
+    # Also add to path directly in case the source above doesn't work
+    export PATH="$HOME/.local/bin:$PATH"
+
+    if command -v uv &> /dev/null; then
+        echo -e "  ${GREEN}uv installed successfully${NC}"
+    else
+        echo -e "${RED}Error: uv installation failed. Try manually: curl -LsSf https://astral.sh/uv/install.sh | sh${NC}"
+        exit 1
+    fi
+else
+    echo -e "  ${GREEN}uv already installed${NC}"
+fi
+echo ""
+
+# -------------------------------------------
+# 3. Clone or update the repo
+# -------------------------------------------
+echo -e "${BOLD}Step 3/6: Getting GAds-MCP...${NC}"
+
+if [[ -d "$INSTALL_DIR" ]]; then
+    echo "  Found existing installation, updating..."
+    cd "$INSTALL_DIR"
+    git pull --quiet origin main
+    echo -e "  ${GREEN}Updated to latest version${NC}"
+else
+    echo "  Cloning from GitHub..."
+    git clone --quiet "$REPO_URL" "$INSTALL_DIR"
+    echo -e "  ${GREEN}Downloaded${NC}"
+fi
+
+cd "$INSTALL_DIR"
+echo ""
+
+# -------------------------------------------
+# 4. Install Python dependencies
+# -------------------------------------------
+echo -e "${BOLD}Step 4/6: Installing dependencies...${NC}"
+
+uv sync --python "$PYTHON_CMD" --quiet 2>/dev/null || uv sync --python "$PYTHON_CMD"
+echo -e "  ${GREEN}Dependencies installed${NC}"
+echo ""
+
+# -------------------------------------------
+# 5. Run adloop init (OAuth + config)
+# -------------------------------------------
+echo -e "${BOLD}Step 5/6: Setting up Google Ads connection...${NC}"
+echo ""
+echo -e "  ${YELLOW}This will open your browser for Google sign-in.${NC}"
+echo -e "  ${YELLOW}Sign in with your Google account that has access to the MCC.${NC}"
+echo ""
+echo -e "  ${BLUE}You'll need the following info (Alex can provide these):${NC}"
+echo "    - Google Cloud Project ID"
+echo "    - Google Ads Developer Token"
+echo "    - OAuth Client ID and Client Secret"
+echo ""
+read -p "  Ready? Press Enter to continue (or Ctrl+C to exit)... "
+echo ""
+
+# Run the init wizard
+uv run adloop init
+
+echo ""
+echo -e "  ${GREEN}Google Ads connection configured${NC}"
+echo ""
+
+# -------------------------------------------
+# 6. Configure Claude MCP
+# -------------------------------------------
+echo -e "${BOLD}Step 6/6: Connecting to Claude...${NC}"
+
+# Get the full path to the Python in the venv
+PYTHON_PATH="$INSTALL_DIR/.venv/bin/python"
+
+if [[ ! -f "$PYTHON_PATH" ]]; then
+    # Fallback: find the python in the venv
+    PYTHON_PATH=$(find "$INSTALL_DIR/.venv" -name "python3" -type f 2>/dev/null | head -1)
+fi
+
+if [[ -z "$PYTHON_PATH" || ! -f "$PYTHON_PATH" ]]; then
+    echo -e "${RED}Error: Could not find Python in the virtual environment.${NC}"
+    echo "  Please contact Alex for help."
+    exit 1
+fi
+
+# The MCP server entry we need to add
+MCP_ENTRY=$(cat <<EOF
+{
+  "mcpServers": {
+    "gads-mcp": {
+      "command": "$PYTHON_PATH",
+      "args": ["-m", "adloop"]
+    }
+  }
+}
+EOF
+)
+
+# --- Claude Desktop / Cowork config ---
+CLAUDE_CONFIGURED=false
+
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    if [[ -d "$CLAUDE_CONFIG_DIR" ]] || [[ -d "/Applications/Claude.app" ]]; then
+        echo "  Configuring Claude Desktop / Cowork..."
+
+        # Create config dir if it doesn't exist
+        mkdir -p "$CLAUDE_CONFIG_DIR"
+
+        if [[ -f "$CLAUDE_CONFIG_FILE" ]]; then
+            # Config file exists, check if gads-mcp is already there
+            if grep -q "gads-mcp" "$CLAUDE_CONFIG_FILE" 2>/dev/null; then
+                echo -e "  ${GREEN}Claude Desktop already configured${NC}"
+                CLAUDE_CONFIGURED=true
+            else
+                # Need to merge. Use python for safe JSON manipulation.
+                python3 << PYEOF
+import json
+import sys
+import shutil
+
+config_file = "$CLAUDE_CONFIG_FILE"
+python_path = "$PYTHON_PATH"
+
+try:
+    with open(config_file, 'r') as f:
+        config = json.load(f)
+except (json.JSONDecodeError, FileNotFoundError):
+    config = {}
+
+# Create backup
+shutil.copy2(config_file, config_file + ".backup")
+
+# Add or update mcpServers
+if 'mcpServers' not in config:
+    config['mcpServers'] = {}
+
+config['mcpServers']['gads-mcp'] = {
+    "command": python_path,
+    "args": ["-m", "adloop"]
+}
+
+with open(config_file, 'w') as f:
+    json.dump(config, f, indent=2)
+
+print("  Config updated (backup saved as claude_desktop_config.json.backup)")
+PYEOF
+                echo -e "  ${GREEN}Claude Desktop configured${NC}"
+                CLAUDE_CONFIGURED=true
+            fi
+        else
+            # No config file yet, create one
+            echo "$MCP_ENTRY" > "$CLAUDE_CONFIG_FILE"
+            echo -e "  ${GREEN}Claude Desktop config created${NC}"
+            CLAUDE_CONFIGURED=true
+        fi
+    fi
+fi
+
+# --- Claude Code config (project-level .mcp.json) ---
+echo ""
+echo "  For Claude Code, the MCP is configured per-project."
+echo "  When you open a project in Claude Code, create a .mcp.json file"
+echo "  in the project root with this content:"
+echo ""
+echo -e "  ${BLUE}$(cat <<EOF
+{
+  "mcpServers": {
+    "gads-mcp": {
+      "command": "$PYTHON_PATH",
+      "args": ["-m", "adloop"]
+    }
+  }
+}
+EOF
+)${NC}"
+echo ""
+
+# Also save this to a file they can easily copy
+MCP_JSON_FILE="$INSTALL_DIR/mcp-config-snippet.json"
+cat > "$MCP_JSON_FILE" <<EOF
+{
+  "mcpServers": {
+    "gads-mcp": {
+      "command": "$PYTHON_PATH",
+      "args": ["-m", "adloop"]
+    }
+  }
+}
+EOF
+
+echo "  This snippet is also saved to: $MCP_JSON_FILE"
+echo "  You can copy it anytime with: cat $MCP_JSON_FILE"
+echo ""
+
+# -------------------------------------------
+# Done!
+# -------------------------------------------
+echo "==========================================="
+echo ""
+echo -e "  ${GREEN}${BOLD}Setup complete!${NC}"
+echo ""
+
+if [[ "$CLAUDE_CONFIGURED" == true ]]; then
+    echo -e "  ${GREEN}Claude Desktop / Cowork:${NC} Configured"
+    echo "    Restart Claude Desktop for changes to take effect."
+    echo ""
+fi
+
+echo -e "  ${BOLD}To verify it's working:${NC}"
+echo "    1. Open Claude Desktop (or restart it if it was open)"
+echo "    2. Start a new conversation"
+echo '    3. Ask: "List my Google Ads accounts"'
+echo "    4. Claude should call the gads-mcp tool and show your accounts"
+echo ""
+echo -e "  ${BOLD}To update later:${NC}"
+echo "    cd $INSTALL_DIR && git pull && uv sync"
+echo ""
+echo -e "  ${BOLD}If something breaks:${NC}"
+echo "    Screenshot the error and send it to Alex."
+echo ""
+echo -e "  ${BOLD}Config locations:${NC}"
+echo "    GAds-MCP install: $INSTALL_DIR"
+echo "    AdLoop config:    $CONFIG_DIR/config.yaml"
+echo "    Claude config:    $CLAUDE_CONFIG_FILE"
+echo "    MCP snippet:      $MCP_JSON_FILE"
+echo ""
+echo "==========================================="
+echo ""