adloop 0.11.0__tar.gz → 0.13.0__tar.gz

{adloop-0.11.0 → adloop-0.13.0}/PKG-INFO

@@ -1,17 +1,18 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.11.0
+Version: 0.13.0
 Summary: The AI command center for Google Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
 Author-email: Daniel Klose <info@daniel-klose.com>
 License: MIT
 Requires-Dist: fastmcp>=3.0.0
-Requires-Dist: google-ads>=29.0.0
+Requires-Dist: google-ads>=31.1.0
 Requires-Dist: google-analytics-data>=0.20.0
 Requires-Dist: google-analytics-admin>=0.27.0
 Requires-Dist: google-api-python-client>=2.100.0
 Requires-Dist: google-auth-oauthlib>=1.0.0
+Requires-Dist: google-api-python-client>=2.0.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: pytest>=8.0 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
@@ -33,7 +34,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-8A2BE2.svg)](https://modelcontextprotocol.io)
-[![Google Ads API](https://img.shields.io/badge/Google%20Ads-API%20v23-4285F4.svg?logo=google-ads&logoColor=white)](https://developers.google.com/google-ads/api/docs/start)
+[![Google Ads API](https://img.shields.io/badge/Google%20Ads-API%20v24-4285F4.svg?logo=google-ads&logoColor=white)](https://developers.google.com/google-ads/api/docs/start)
 [![GA4 Data API](https://img.shields.io/badge/GA4-Data%20API-E37400.svg?logo=google-analytics&logoColor=white)](https://developers.google.com/analytics/devguides/reporting/data/v1)
 [![GitHub stars](https://img.shields.io/github/stars/kLOsk/adloop?style=social)](https://github.com/kLOsk/adloop)
 
@@ -44,13 +45,13 @@ An MCP server that gives your AI assistant read + write access to Google Ads and
 </div>
 
 > [!TIP]
-> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the same 61 tools from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
+> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
 
 ---
 
 ## Cloud or Self-Hosted?
 
-Both versions run the same 61 tools with the same safety model. The difference is who handles the plumbing:
+Both versions run the same tools with the same safety model. The difference is who handles the plumbing:
 
 |  | ☁️ [AdLoop Cloud](https://getadloop.com) | 🛠️ Self-hosted (this repo) |
 |---|---|---|
@@ -88,7 +89,7 @@ Every tool exists because of an actual problem hit while running real Google Ads
 
 The best features come from real workflows. If you're using AdLoop and find yourself wishing it could do something it can't, **open an issue describing your situation** — not just "add feature X" but "I was trying to do Y and couldn't because Z." The context matters more than the request.
 
-## All 61 Tools
+## All Tools
 
 > **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init` — or zero setup on [AdLoop Cloud](https://getadloop.com)
 
@@ -168,12 +169,36 @@ These tools read the live GTM container and join it with the codebase + GA4 to f
 
 > **Setup for GTM tools** — Enable the **Tag Manager API v2** in your GCP project, then add your AdLoop credentials' email (the OAuth user, or the service account email if using a service account) as a **Read** user on the GTM container under Admin → User Management. Service accounts pick up access on the next call. **OAuth users upgrading from an earlier AdLoop version must re-authorize once**: the GTM scope is new, so delete `~/.adloop/token.json` and run any tool to re-consent — until then GTM tools return a permissions error.
 
+### Search Console Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `list_gsc_sites` | List Search Console properties the connected account can access |
+| `run_gsc_report` | Organic search analytics — clicks, impressions, CTR, position by query/page/country/device/date |
+
+### Web Performance Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `analyze_page_speed` | PageSpeed Insights for landing pages — Lighthouse score, Core Web Vitals, real-user CrUX data, top fixes. No OAuth needed (optional API key). |
+
+### Merchant Center Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `list_merchant_accounts` | Discover accessible Merchant Center accounts |
+| `get_merchant_feed_health` | Feed health — approved/pending/disapproved counts per reporting context, top product issues with docs, account-level issues. Disapprovals silently starve Shopping/PMax. |
+
+> **Setup for Merchant Center tools** — Enable the **Merchant API** in your GCP project (the Content API for Shopping is deprecated). The Merchant API has no read-only scope; AdLoop uses it strictly read-only. Upgrading OAuth users re-authorize once.
+
+> **Setup for GSC tools** — Enable the **Search Console API** in your GCP project. Upgrading OAuth users must re-authorize once for the new scope (delete `~/.adloop/token.json`, run any tool). The killer combo: cross-reference organic queries with `get_keyword_performance` to find paid/organic cannibalization and untapped keyword opportunities.
+
 ### Planning Tools
 
 | Tool | What It Does |
 |------|-------------|
-| `discover_keywords` | Discover new keyword ideas from seed keywords and/or a URL using Google Ads Keyword Planner. Returns avg monthly searches, competition level, and top-of-page bid range. |
-| `estimate_budget` | Forecast clicks, impressions, and cost for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |
+| `discover_keywords` | Discover new keyword ideas from seed keywords and/or a URL — with optional per-month search history + seasonality insights (`include_monthly_volumes`) using Google Ads Keyword Planner. Returns avg monthly searches, competition level, and top-of-page bid range. |
+| `estimate_budget` | Forecast clicks, cost, and conversions for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |
 
 ### Google Ads Write Tools
 
@@ -192,6 +217,7 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — blocks BROAD match on Manual CPC campaigns. |
 | `add_negative_keywords` | Propose negative keywords directly on a campaign |
 | `add_negative_locations` | Propose negative geo exclusions on a campaign — exclude cities/regions while keeping broader positive targets |
+| `draft_key_event` | Mark a GA4 event as a key event (conversion) — the fix for "fires but isn't tracked as a conversion" |
 | `draft_demographic_targeting` | Propose demographic criteria (age, gender, parental status, income) — exclusions by default |
 | `propose_negative_keyword_list` | Draft a shared negative keyword list (SharedSet) and attach it to a campaign — reusable across multiple campaigns |
 | `pause_entity` | Pause a campaign, ad group, ad, or keyword |
@@ -232,6 +258,7 @@ AdLoop manages real ad spend, so safety is not optional.
 
 - **Two-step writes.** Every mutation returns a preview first. A separate `confirm_and_apply` call is required to execute.
 - **Dry-run by default.** Even `confirm_and_apply` defaults to `dry_run=true`. Real changes require explicit `dry_run=false`.
+- **Two-phase apply (optional).** With `safety.two_phase_apply: true`, `confirm_and_apply` refuses `dry_run=false` until the plan has completed one dry-run pass — preview-then-apply becomes server-enforced instead of a convention.
 - **Budget caps.** Configurable maximum daily budget — the server rejects anything above the cap.
 - **Audit log.** Every operation (including dry runs) is logged to `~/.adloop/audit.log`.
 - **New campaigns and ads are PAUSED.** Nothing goes live without manual enablement.
@@ -250,6 +277,9 @@ AdLoop manages real ad spend, so safety is not optional.
 >
 > *(Upgrading from ≤0.9 with built-in credentials? Those sign-ins were retired in 0.10 — run `adloop init` once to switch to your own project.)*
 
+> [!IMPORTANT]
+> **Seeing `deleted_client: The OAuth client was deleted.` or `invalid_client`?** The shared Google Cloud project behind AdLoop ≤0.9's bundled credentials has been shut down, so its stored sign-ins no longer refresh. Two ways forward: **[AdLoop Cloud](https://getadloop.com)** (connect Google in two clicks, nothing to configure) or stay self-hosted with `pip install -U adloop && adloop init` to set up your own free Google Cloud project. Details in [the pinned issue (#49)](https://github.com/kLOsk/adloop/issues/49).
+
 ### Install
 
 **From PyPI:**
@@ -277,8 +307,10 @@ The wizard walks you through:
 3. **MCC Account ID** — your Manager Account ID (top bar in the MCC UI)
 4. **OAuth sign-in** — opens a browser to sign in with Google (or prints a URL for headless servers)
 5. **Auto-discovers your accounts** — finds your GA4 properties and Ads accounts automatically
-6. **Safety defaults** — budget cap and dry-run preference
-7. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
+6. **Optional services** — pin a GTM container, a Search Console property (both auto-discovered too), and a PageSpeed API key; skip any of them with Enter
+7. **Safety defaults** — budget cap and dry-run preference
+8. **Toolsets** — optionally expose only part of the tool catalog to your AI client (see [Toolsets](#toolsets--trim-the-context-footprint))
+9. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code, including your toolset selection
 
 ### Requirements
 
@@ -412,14 +444,37 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 | `ads` | `login_customer_id` | — | Your MCC account ID |
 | `safety` | `max_daily_budget` | `50.00` | Maximum allowed daily budget per campaign |
 | `safety` | `require_dry_run` | `true` | Force all writes to dry-run mode |
+| `safety` | `two_phase_apply` | `false` | Refuse real applies until the plan had a dry-run pass |
 | `safety` | `blocked_operations` | `[]` | Operations to block entirely |
 
+### Toolsets — trim the context footprint
+
+Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into the model's context at the start of every conversation**. AdLoop's full catalog costs roughly 18k tokens per session that way — paid before you type a word. If you only use part of AdLoop, expose a subset with the `ADLOOP_TOOLSETS` environment variable in your MCP client's `env` block (the `adloop init` wizard offers this and writes it into the snippets for you):
+
+```json
+"env": { "ADLOOP_TOOLSETS": "ads,ga4" }
+```
+
+| Toolset | Covers |
+|---|---|
+| `ads` | Google Ads reads, writes, and planning (Keyword Planner) |
+| `ga4` | Google Analytics reports, realtime, key events |
+| `tracking` | Cross-channel attribution + tracking code generation |
+| `gtm` | Google Tag Manager audits and reads |
+| `gsc` | Search Console reads |
+| `web` | PageSpeed / Core Web Vitals |
+| `merchant` | Merchant Center feed health |
+
+`health_check` and `confirm_and_apply` are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: `ads,ga4` drops the session cost to ~13k tokens, and a `ga4`-only client pays ~2k — nearly 90% less. Toolsets are per *client*, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
+
+On [AdLoop Cloud](https://getadloop.com), the same feature is per API key: pick toolsets when creating a key in the dashboard, and that key's tools/list is trimmed server-side for whichever AI client uses it.
+
 ## Project Structure
 
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 61 tool registrations with safety annotations
+├── server.py          # FastMCP server — 67 tool registrations with safety annotations
 ├── config.py          # Config loader (~/.adloop/config.yaml)
 ├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
 ├── cli.py             # Interactive 'adloop init' setup wizard

{adloop-0.11.0 → adloop-0.13.0}/README.md

@@ -8,7 +8,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-8A2BE2.svg)](https://modelcontextprotocol.io)
-[![Google Ads API](https://img.shields.io/badge/Google%20Ads-API%20v23-4285F4.svg?logo=google-ads&logoColor=white)](https://developers.google.com/google-ads/api/docs/start)
+[![Google Ads API](https://img.shields.io/badge/Google%20Ads-API%20v24-4285F4.svg?logo=google-ads&logoColor=white)](https://developers.google.com/google-ads/api/docs/start)
 [![GA4 Data API](https://img.shields.io/badge/GA4-Data%20API-E37400.svg?logo=google-analytics&logoColor=white)](https://developers.google.com/analytics/devguides/reporting/data/v1)
 [![GitHub stars](https://img.shields.io/github/stars/kLOsk/adloop?style=social)](https://github.com/kLOsk/adloop)
 
@@ -19,13 +19,13 @@ An MCP server that gives your AI assistant read + write access to Google Ads and
 </div>
 
 > [!TIP]
-> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the same 61 tools from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
+> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
 
 ---
 
 ## Cloud or Self-Hosted?
 
-Both versions run the same 61 tools with the same safety model. The difference is who handles the plumbing:
+Both versions run the same tools with the same safety model. The difference is who handles the plumbing:
 
 |  | ☁️ [AdLoop Cloud](https://getadloop.com) | 🛠️ Self-hosted (this repo) |
 |---|---|---|
@@ -63,7 +63,7 @@ Every tool exists because of an actual problem hit while running real Google Ads
 
 The best features come from real workflows. If you're using AdLoop and find yourself wishing it could do something it can't, **open an issue describing your situation** — not just "add feature X" but "I was trying to do Y and couldn't because Z." The context matters more than the request.
 
-## All 61 Tools
+## All Tools
 
 > **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init` — or zero setup on [AdLoop Cloud](https://getadloop.com)
 
@@ -143,12 +143,36 @@ These tools read the live GTM container and join it with the codebase + GA4 to f
 
 > **Setup for GTM tools** — Enable the **Tag Manager API v2** in your GCP project, then add your AdLoop credentials' email (the OAuth user, or the service account email if using a service account) as a **Read** user on the GTM container under Admin → User Management. Service accounts pick up access on the next call. **OAuth users upgrading from an earlier AdLoop version must re-authorize once**: the GTM scope is new, so delete `~/.adloop/token.json` and run any tool to re-consent — until then GTM tools return a permissions error.
 
+### Search Console Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `list_gsc_sites` | List Search Console properties the connected account can access |
+| `run_gsc_report` | Organic search analytics — clicks, impressions, CTR, position by query/page/country/device/date |
+
+### Web Performance Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `analyze_page_speed` | PageSpeed Insights for landing pages — Lighthouse score, Core Web Vitals, real-user CrUX data, top fixes. No OAuth needed (optional API key). |
+
+### Merchant Center Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `list_merchant_accounts` | Discover accessible Merchant Center accounts |
+| `get_merchant_feed_health` | Feed health — approved/pending/disapproved counts per reporting context, top product issues with docs, account-level issues. Disapprovals silently starve Shopping/PMax. |
+
+> **Setup for Merchant Center tools** — Enable the **Merchant API** in your GCP project (the Content API for Shopping is deprecated). The Merchant API has no read-only scope; AdLoop uses it strictly read-only. Upgrading OAuth users re-authorize once.
+
+> **Setup for GSC tools** — Enable the **Search Console API** in your GCP project. Upgrading OAuth users must re-authorize once for the new scope (delete `~/.adloop/token.json`, run any tool). The killer combo: cross-reference organic queries with `get_keyword_performance` to find paid/organic cannibalization and untapped keyword opportunities.
+
 ### Planning Tools
 
 | Tool | What It Does |
 |------|-------------|
-| `discover_keywords` | Discover new keyword ideas from seed keywords and/or a URL using Google Ads Keyword Planner. Returns avg monthly searches, competition level, and top-of-page bid range. |
-| `estimate_budget` | Forecast clicks, impressions, and cost for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |
+| `discover_keywords` | Discover new keyword ideas from seed keywords and/or a URL — with optional per-month search history + seasonality insights (`include_monthly_volumes`) using Google Ads Keyword Planner. Returns avg monthly searches, competition level, and top-of-page bid range. |
+| `estimate_budget` | Forecast clicks, cost, and conversions for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |
 
 ### Google Ads Write Tools
 
@@ -167,6 +191,7 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — blocks BROAD match on Manual CPC campaigns. |
 | `add_negative_keywords` | Propose negative keywords directly on a campaign |
 | `add_negative_locations` | Propose negative geo exclusions on a campaign — exclude cities/regions while keeping broader positive targets |
+| `draft_key_event` | Mark a GA4 event as a key event (conversion) — the fix for "fires but isn't tracked as a conversion" |
 | `draft_demographic_targeting` | Propose demographic criteria (age, gender, parental status, income) — exclusions by default |
 | `propose_negative_keyword_list` | Draft a shared negative keyword list (SharedSet) and attach it to a campaign — reusable across multiple campaigns |
 | `pause_entity` | Pause a campaign, ad group, ad, or keyword |
@@ -207,6 +232,7 @@ AdLoop manages real ad spend, so safety is not optional.
 
 - **Two-step writes.** Every mutation returns a preview first. A separate `confirm_and_apply` call is required to execute.
 - **Dry-run by default.** Even `confirm_and_apply` defaults to `dry_run=true`. Real changes require explicit `dry_run=false`.
+- **Two-phase apply (optional).** With `safety.two_phase_apply: true`, `confirm_and_apply` refuses `dry_run=false` until the plan has completed one dry-run pass — preview-then-apply becomes server-enforced instead of a convention.
 - **Budget caps.** Configurable maximum daily budget — the server rejects anything above the cap.
 - **Audit log.** Every operation (including dry runs) is logged to `~/.adloop/audit.log`.
 - **New campaigns and ads are PAUSED.** Nothing goes live without manual enablement.
@@ -225,6 +251,9 @@ AdLoop manages real ad spend, so safety is not optional.
 >
 > *(Upgrading from ≤0.9 with built-in credentials? Those sign-ins were retired in 0.10 — run `adloop init` once to switch to your own project.)*
 
+> [!IMPORTANT]
+> **Seeing `deleted_client: The OAuth client was deleted.` or `invalid_client`?** The shared Google Cloud project behind AdLoop ≤0.9's bundled credentials has been shut down, so its stored sign-ins no longer refresh. Two ways forward: **[AdLoop Cloud](https://getadloop.com)** (connect Google in two clicks, nothing to configure) or stay self-hosted with `pip install -U adloop && adloop init` to set up your own free Google Cloud project. Details in [the pinned issue (#49)](https://github.com/kLOsk/adloop/issues/49).
+
 ### Install
 
 **From PyPI:**
@@ -252,8 +281,10 @@ The wizard walks you through:
 3. **MCC Account ID** — your Manager Account ID (top bar in the MCC UI)
 4. **OAuth sign-in** — opens a browser to sign in with Google (or prints a URL for headless servers)
 5. **Auto-discovers your accounts** — finds your GA4 properties and Ads accounts automatically
-6. **Safety defaults** — budget cap and dry-run preference
-7. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
+6. **Optional services** — pin a GTM container, a Search Console property (both auto-discovered too), and a PageSpeed API key; skip any of them with Enter
+7. **Safety defaults** — budget cap and dry-run preference
+8. **Toolsets** — optionally expose only part of the tool catalog to your AI client (see [Toolsets](#toolsets--trim-the-context-footprint))
+9. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code, including your toolset selection
 
 ### Requirements
 
@@ -387,14 +418,37 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 | `ads` | `login_customer_id` | — | Your MCC account ID |
 | `safety` | `max_daily_budget` | `50.00` | Maximum allowed daily budget per campaign |
 | `safety` | `require_dry_run` | `true` | Force all writes to dry-run mode |
+| `safety` | `two_phase_apply` | `false` | Refuse real applies until the plan had a dry-run pass |
 | `safety` | `blocked_operations` | `[]` | Operations to block entirely |
 
+### Toolsets — trim the context footprint
+
+Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into the model's context at the start of every conversation**. AdLoop's full catalog costs roughly 18k tokens per session that way — paid before you type a word. If you only use part of AdLoop, expose a subset with the `ADLOOP_TOOLSETS` environment variable in your MCP client's `env` block (the `adloop init` wizard offers this and writes it into the snippets for you):
+
+```json
+"env": { "ADLOOP_TOOLSETS": "ads,ga4" }
+```
+
+| Toolset | Covers |
+|---|---|
+| `ads` | Google Ads reads, writes, and planning (Keyword Planner) |
+| `ga4` | Google Analytics reports, realtime, key events |
+| `tracking` | Cross-channel attribution + tracking code generation |
+| `gtm` | Google Tag Manager audits and reads |
+| `gsc` | Search Console reads |
+| `web` | PageSpeed / Core Web Vitals |
+| `merchant` | Merchant Center feed health |
+
+`health_check` and `confirm_and_apply` are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: `ads,ga4` drops the session cost to ~13k tokens, and a `ga4`-only client pays ~2k — nearly 90% less. Toolsets are per *client*, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
+
+On [AdLoop Cloud](https://getadloop.com), the same feature is per API key: pick toolsets when creating a key in the dashboard, and that key's tools/list is trimmed server-side for whichever AI client uses it.
+
 ## Project Structure
 
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 61 tool registrations with safety annotations
+├── server.py          # FastMCP server — 67 tool registrations with safety annotations
 ├── config.py          # Config loader (~/.adloop/config.yaml)
 ├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
 ├── cli.py             # Interactive 'adloop init' setup wizard

{adloop-0.11.0 → adloop-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.11.0"
+version = "0.13.0"
 description = "The AI command center for Google Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [
@@ -11,11 +11,12 @@ license = { text = "MIT" }
 keywords = ["mcp", "google-ads", "google-analytics", "ga4", "cursor", "marketing"]
 dependencies = [
     "fastmcp>=3.0.0",
-    "google-ads>=29.0.0",
+    "google-ads>=31.1.0",
     "google-analytics-data>=0.20.0",
     "google-analytics-admin>=0.27.0",
     "google-api-python-client>=2.100.0",
     "google-auth-oauthlib>=1.0.0",
+    "google-api-python-client>=2.0.0",
     "pyyaml>=6.0",
 ]
 

{adloop-0.11.0 → adloop-0.13.0}/src/adloop/ads/client.py

@@ -16,7 +16,7 @@ if TYPE_CHECKING:
 # Pin the API version so library upgrades don't silently break field names,
 # enum values, or mutate operation structures. Bump this deliberately when
 # migrating to a new API version — never let it float to the library default.
-GOOGLE_ADS_API_VERSION = "v23"
+GOOGLE_ADS_API_VERSION = "v24"
 
 
 def get_ads_client(config: AdLoopConfig) -> GoogleAdsClient:

{adloop-0.11.0 → adloop-0.13.0}/src/adloop/ads/forecast.py

@@ -22,13 +22,16 @@ def estimate_budget(
     forecast_days: int = 30,
     customer_id: str = "",
 ) -> dict:
-    """Forecast clicks, impressions, and cost for a set of keywords.
+    """Forecast clicks, cost, and conversions for a set of keywords.
 
     Uses KeywordPlanIdeaService.GenerateKeywordForecastMetrics to estimate
     campaign performance without creating anything. Useful for budget planning
     before launching a new campaign.
 
     keywords: list of {"text": str, "match_type": "EXACT|PHRASE|BROAD", "max_cpc": float (optional)}
+        Since Ads API v24 the forecast takes no per-keyword bids — the
+        highest max_cpc across the list becomes the campaign-level manual
+        CPC cap.
     geo_target_id: geo target constant (2276=Germany, 2840=USA, 2826=UK, 2250=France)
     language_id: language constant (1000=English, 1001=German, 1002=French, 1003=Spanish)
     forecast_days: number of days to forecast (default 30)
@@ -45,9 +48,6 @@ def estimate_budget(
     kp_service = client.get_service("KeywordPlanIdeaService")
 
     campaign = client.get_type("CampaignToForecast")
-    campaign.keyword_plan_network = (
-        client.enums.KeywordPlanNetworkEnum.GOOGLE_SEARCH
-    )
 
     max_bid = max(
         (int(kw.get("max_cpc", 0) * 1_000_000) for kw in keywords),
@@ -57,11 +57,9 @@ def estimate_budget(
         max_bid = _DEFAULT_MAX_CPC_MICROS
     campaign.bidding_strategy.manual_cpc_bidding_strategy.max_cpc_bid_micros = max_bid
 
-    geo_modifier = client.get_type("CriterionBidModifier")
-    geo_modifier.geo_target_constant = googleads_service.geo_target_constant_path(
-        geo_target_id
+    campaign.geo_target_constants.append(
+        googleads_service.geo_target_constant_path(geo_target_id)
     )
-    campaign.geo_modifiers.append(geo_modifier)
 
     campaign.language_constants.append(
         googleads_service.language_constant_path(language_id)
@@ -74,15 +72,13 @@ def estimate_budget(
         if not text:
             continue
         match_type = kw.get("match_type", "BROAD").upper()
-        cpc_micros = int(kw.get("max_cpc", 0) * 1_000_000) or _DEFAULT_MAX_CPC_MICROS
 
-        biddable = client.get_type("BiddableKeyword")
-        biddable.max_cpc_bid_micros = cpc_micros
-        biddable.keyword.text = text
-        biddable.keyword.match_type = getattr(
+        keyword = client.get_type("KeywordInfo")
+        keyword.text = text
+        keyword.match_type = getattr(
             client.enums.KeywordMatchTypeEnum, match_type, client.enums.KeywordMatchTypeEnum.BROAD
         )
-        ad_group.biddable_keywords.append(biddable)
+        ad_group.keywords.append(keyword)
 
     campaign.ad_groups.append(ad_group)
 
@@ -98,29 +94,29 @@ def estimate_budget(
     response = kp_service.generate_keyword_forecast_metrics(request=request)
     metrics = response.campaign_forecast_metrics
 
-    # KeywordForecastMetrics fields are ``optional`` in v23, so the SDK
-    # returns ``None`` for unset fields and the actual integer (including
-    # 0) otherwise. Falsy checks like ``int(v) if v else None`` would
+    # KeywordForecastMetrics fields are ``optional``, so the SDK returns
+    # ``None`` for unset fields and the actual number (including 0)
+    # otherwise. Falsy checks like ``int(v) if v else None`` would
     # silently map a real 0-click or 0-cost forecast to None and the
     # caller couldn't tell "no data" apart from "data says zero" — same
     # bug class as discover_keywords (issue Bug 2). Use ``is not None``
     # throughout and the shared ``_micros_to_currency`` helper for the
     # micros→currency conversions.
+    # v24 dropped impressions/click_through_rate from the forecast and
+    # added conversions/average_cpa_micros.
     clicks = getattr(metrics, "clicks", None)
-    impressions = getattr(metrics, "impressions", None)
     avg_cpc_micros = getattr(metrics, "average_cpc_micros", None)
     cost_micros = getattr(metrics, "cost_micros", None)
-    ctr = getattr(metrics, "click_through_rate", None)
+    conversions = getattr(metrics, "conversions", None)
+    avg_cpa_micros = getattr(metrics, "average_cpa_micros", None)
 
     total_cost = _micros_to_currency(cost_micros)
     avg_cpc = _micros_to_currency(avg_cpc_micros)
+    avg_cpa = _micros_to_currency(avg_cpa_micros)
 
     days = max(forecast_days, 1)
     daily = {
         "clicks": round(clicks / days, 1) if clicks is not None else None,
-        "impressions": (
-            round(impressions / days, 1) if impressions is not None else None
-        ),
         "cost": round(total_cost / days, 2) if total_cost is not None else None,
     }
 
@@ -147,15 +143,16 @@ def estimate_budget(
                 f"most available traffic (estimated daily cost: {daily['cost']:.2f})."
             )
 
-    if (
-        impressions is not None
-        and clicks is not None
-        and impressions > 0
-        and clicks == 0
-    ):
+    if clicks is not None and clicks == 0:
+        insights.append(
+            "Forecast shows zero clicks — keywords may be too niche, too "
+            "generic, or the max CPC too low for competitive positions."
+        )
+
+    if conversions is not None and conversions > 0 and avg_cpa is not None:
         insights.append(
-            "Forecast shows impressions but zero clicks — keywords may be too "
-            "generic or CPCs too low for competitive positions."
+            f"Estimated {conversions:.1f} conversions at ~{avg_cpa:.2f} avg "
+            f"CPA (based on historical conversion rates for these keywords)."
         )
 
     return {
@@ -164,10 +161,12 @@ def estimate_budget(
             "end": end_date.isoformat(),
         },
         "estimated_clicks": clicks,
-        "estimated_impressions": impressions,
         "estimated_cost": total_cost,
         "estimated_avg_cpc": avg_cpc,
-        "estimated_ctr": round(ctr, 4) if ctr is not None else None,
+        "estimated_conversions": (
+            round(conversions, 1) if conversions is not None else None
+        ),
+        "estimated_avg_cpa": avg_cpa,
         "daily_estimates": daily,
         "keywords_used": len([kw for kw in keywords if kw.get("text")]),
         "insights": insights,
@@ -227,7 +226,7 @@ def _build_keyword_ideas_rest_body(
 ) -> dict:
     """Build the JSON body for the REST generateKeywordIdeas endpoint.
 
-    Schema follows google-ads REST v23 (camelCase). Exactly one of
+    Schema follows google-ads REST v24 (camelCase). Exactly one of
     ``keywordSeed`` / ``urlSeed`` / ``keywordAndUrlSeed`` is set based on
     which inputs were provided.
     """
@@ -255,7 +254,7 @@ def _post_keyword_ideas_rest_page(
 
     Issue #37: ``KeywordPlanIdeaService.GenerateKeywordIdeas`` over gRPC sits
     in a tight quota bucket that exhausts after a small number of sequential
-    calls and returns ``RESOURCE_EXHAUSTED`` regardless of QPS. The REST v23
+    calls and returns ``RESOURCE_EXHAUSTED`` regardless of QPS. The REST
     endpoint for the same method lives in a separate, much larger quota
     bucket, so this swap eliminates the 429s that made ``discover_keywords``
     unusable for any multi-geo or repeat-call workflow. Filed against
@@ -295,6 +294,69 @@ def _post_keyword_ideas_rest_page(
     return response.json()
 
 
+
+_MONTH_NUMBERS = {
+    "JANUARY": 1, "FEBRUARY": 2, "MARCH": 3, "APRIL": 4, "MAY": 5,
+    "JUNE": 6, "JULY": 7, "AUGUST": 8, "SEPTEMBER": 9, "OCTOBER": 10,
+    "NOVEMBER": 11, "DECEMBER": 12,
+}
+
+_MONTH_NAMES = {v: k.capitalize() for k, v in _MONTH_NUMBERS.items()}
+
+
+def _parse_monthly_volumes(raw: list[dict]) -> list[dict]:
+    """REST monthlySearchVolumes → compact chronological history.
+
+    Keeps the last 24 months: enough to see seasonality across two cycles
+    without flooding the response (the API returns up to ~4 years).
+    """
+    volumes = []
+    for row in raw:
+        month = _MONTH_NUMBERS.get(str(row.get("month", "")).upper())
+        year = _maybe_int(row.get("year"))
+        if month is None or year is None:
+            continue
+        volumes.append({
+            "year": year,
+            "month": month,
+            "searches": _maybe_int(row.get("monthlySearches")) or 0,
+        })
+    volumes.sort(key=lambda v: (v["year"], v["month"]))
+    return volumes[-24:]
+
+
+def _seasonality_insight(idea: dict) -> str | None:
+    """Name the peak months when demand is meaningfully seasonal (>=40%
+    above the keyword's own monthly average)."""
+    volumes = idea.get("monthly_search_volumes") or []
+    if len(volumes) < 12:
+        return None
+
+    by_month: dict[int, list[int]] = {}
+    for v in volumes:
+        by_month.setdefault(v["month"], []).append(v["searches"])
+    month_avgs = {m: sum(s) / len(s) for m, s in by_month.items()}
+    overall = sum(month_avgs.values()) / len(month_avgs)
+    if overall <= 0:
+        return None
+
+    peaks = sorted(
+        (m for m, avg in month_avgs.items() if avg >= overall * 1.4),
+        key=lambda m: month_avgs[m],
+        reverse=True,
+    )
+    if not peaks:
+        return None
+
+    names = ", ".join(_MONTH_NAMES[m] for m in peaks[:3])
+    ratio = month_avgs[peaks[0]] / overall
+    return (
+        f"'{idea['keyword']}' is seasonal: demand peaks in {names} "
+        f"(up to {ratio:.1f}x its monthly average). Plan budgets and "
+        f"campaign launches around the ramp-up, not the peak itself."
+    )
+
+
 def discover_keywords(
     config: AdLoopConfig,
     *,
@@ -304,6 +366,7 @@ def discover_keywords(
     language_id: str = "1000",
     page_size: int = 50,
     customer_id: str = "",
+    include_monthly_volumes: bool = False,
 ) -> dict:
     """Discover new keyword ideas using Google Ads Keyword Planner.
 
@@ -320,9 +383,12 @@ def discover_keywords(
     geo_target_id: geo target constant (2276=Germany, 2840=USA, 2826=UK)
     language_id: language constant (1000=English, 1001=German, 1002=French)
     page_size: max number of keyword ideas to return (default 50, max 1000)
+    include_monthly_volumes: attach per-month search volume history (up to
+        ~4 years, trimmed to the last 24 months, top 20 ideas only) plus a
+        seasonality insight — the "Google Trends" view for keyword demand.
 
     Network: this tool intentionally bypasses the google-ads gRPC client for
-    KeywordPlanIdeaService and calls the v23 REST endpoint directly. The
+    KeywordPlanIdeaService and calls the versioned REST endpoint directly. The
     gRPC quota bucket for this single method exhausts almost immediately
     under sequential single-geo calls (issue #37); REST sits in a separate,
     much larger bucket and works without issue. All other Ads tools still
@@ -358,7 +424,7 @@ def discover_keywords(
             # ``_micros_to_currency`` preserve legitimate 0 values that
             # falsy checks would otherwise silently drop. See the helper
             # docstrings for the failure modes this defends against.
-            ideas.append({
+            entry = {
                 "keyword": idea.get("text", ""),
                 "avg_monthly_searches": _maybe_int(metrics.get("avgMonthlySearches")),
                 "competition": competition,
@@ -369,7 +435,12 @@ def discover_keywords(
                 "high_top_of_page_bid": _micros_to_currency(
                     _maybe_int(metrics.get("highTopOfPageBidMicros"))
                 ),
-            })
+            }
+            if include_monthly_volumes:
+                entry["monthly_search_volumes"] = _parse_monthly_volumes(
+                    metrics.get("monthlySearchVolumes") or []
+                )
+            ideas.append(entry)
 
         page_token = payload.get("nextPageToken") or ""
         if not page_token:
@@ -378,6 +449,13 @@ def discover_keywords(
     # Sort by avg monthly searches descending (None last)
     ideas.sort(key=lambda x: x["avg_monthly_searches"] or 0, reverse=True)
 
+    if include_monthly_volumes:
+        # History is context-heavy (24 rows per keyword) — keep it on the
+        # ideas that matter and drop it from the long tail.
+        for i, idea in enumerate(ideas):
+            if i >= 20:
+                idea.pop("monthly_search_volumes", None)
+
     insights = []
     if ideas:
         high_competition = [i for i in ideas if i["competition"] == "HIGH"]
@@ -399,6 +477,9 @@ def discover_keywords(
                 f"Highest-volume idea: '{top['keyword']}' with ~{top['avg_monthly_searches']:,} "
                 f"avg monthly searches."
             )
+            seasonality = _seasonality_insight(top)
+            if seasonality:
+                insights.append(seasonality)
 
     return {
         "keyword_ideas": ideas,