adloop 0.9.0__tar.gz → 0.11.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.9.0
+Version: 0.11.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
@@ -10,6 +10,7 @@ Requires-Dist: fastmcp>=3.0.0
 Requires-Dist: google-ads>=29.0.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: pyyaml>=6.0
 Requires-Dist: pytest>=8.0 ; extra == 'dev'
@@ -38,12 +39,31 @@ Description-Content-Type: text/markdown
 
 An MCP server that gives your AI assistant read + write access to Google Ads and GA4 — with safety guardrails that prevent accidental spend.
 
-`pip install adloop`
+**[☁️ Skip the setup — use AdLoop Cloud (free beta)](https://getadloop.com)**  ·  or self-host: `pip install adloop`
 
 </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.
+
 ---
 
+## Cloud or Self-Hosted?
+
+Both versions run the same 61 tools with the same safety model. The difference is who handles the plumbing:
+
+|  | ☁️ [AdLoop Cloud](https://getadloop.com) | 🛠️ Self-hosted (this repo) |
+|---|---|---|
+| **Setup** | Connect Google in two clicks | ~5 min: own Google Cloud project + `adloop init` |
+| **Google Cloud project** | Not needed | Required (free) |
+| **Ads developer token** | Not needed | Required (from your MCC) |
+| **Works with** | claude.ai, ChatGPT, Claude Code, Cursor, Gemini | Claude Code, Cursor, Claude Desktop, any local MCP client |
+| **Where your data flows** | EU servers (Germany), GDPR-first, DPA included | 100% your machine — nothing leaves it |
+| **Updates** | Automatic | `pip install -U adloop` |
+| **Price** | Free during beta | Free forever (MIT) |
+
+**Not sure? [Start with Cloud](https://getadloop.com)** — it's the fastest way to see what AdLoop can do, and it's the only way to use AdLoop from claude.ai or ChatGPT. Self-host when you want everything on your own machine or need to modify the code. And if you're here to hack on AdLoop itself: welcome, keep scrolling.
+
 ## What It Solves
 
 AdLoop exists because managing Google Ads alongside your code is a mess. These are the specific problems it handles:
@@ -58,6 +78,8 @@ AdLoop exists because managing Google Ads alongside your code is a mess. These a
 
 - **"My landing page gets paid traffic but nobody converts."** AdLoop joins your ad final URLs with GA4 page-level data. See which pages get clicks but no conversions, which have high bounce rates, and which ones are orphaned from any ad campaign.
 
+- **"Are conversions even being tagged on every page?"** AdLoop reads your live Google Tag Manager container, joins it against the events in your codebase and the events firing in GA4, and tells you exactly which conversions are being captured, which tags are paused, which page-scope filters are too narrow, and which codebase events have no tag at all — the kind of three-way audit GTM Preview can't give you in a single view.
+
 - **"I don't know if my EU consent setup is causing data gaps."** In Europe, 30-70% of users reject analytics cookies. AdLoop accounts for this automatically — it won't diagnose a normal GDPR consent gap as broken tracking.
 
 ## Built From Real Usage
@@ -66,9 +88,9 @@ 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 43 Tools
+## All 61 Tools
 
-> **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init`
+> **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)
 
 ### Diagnostics
 
@@ -103,8 +125,11 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_asset_performance` | Per-asset details for PMax — field type, serving status, content |
 | `get_detailed_asset_performance` | Top-performing asset combinations — which headline+description+image combos Google selects most |
 | `get_audience_performance` | Audience segment performance — remarketing, in-market, affinity, demographics |
+| `get_demographic_targeting` | List demographic criteria (age/gender/parental status/income) on an ad group or campaign |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
+> **Compact mode** — `get_campaign_performance`, `get_keyword_performance`, `get_search_terms`, and `get_ad_performance` accept `compact=true`: account totals, breakdowns, top-10 rows, and pre-computed offender lists (zero-conversion spenders, low-QS keywords, negative-keyword candidates, thin RSAs) instead of every row. ~90% smaller responses — built for account audits so raw tables don't flood your AI's context.
+
 ### Cross-Reference Tools (GA4 + Ads Combined)
 
 These tools call both APIs internally and return unified results with auto-generated insights. They're the core of what makes AdLoop different from having separate GA4 and Ads tools.
@@ -122,6 +147,27 @@ These tools call both APIs internally and return unified results with auto-gener
 | `validate_tracking` | Compare event names found in your codebase against what GA4 actually records. Returns matched, missing, and unexpected events with diagnostics. |
 | `generate_tracking_code` | Generate ready-to-paste GA4 gtag JavaScript for any event, with recommended parameters for well-known events (sign_up, purchase, etc.) and optional trigger wrappers. |
 
+### Google Tag Manager Tools
+
+These tools read the live GTM container and join it with the codebase + GA4 to find tracking gaps that pure GA4 inspection can't catch — page-scoped triggers, paused tags, dynamic event names, brittle CSS selectors, and codebase events with no tag wired up at all.
+
+| Tool | What It Does |
+|------|-------------|
+| `audit_event_coverage` | **The flagship.** Three-way join: codebase events ↔ GTM tags ↔ GA4 actual fires. For each event name in `expected_events`, returns one of 10 statuses (`ok`, `no_tag_no_fire`, `tag_paused`, `tag_active_but_not_firing`, `gtm_only_firing`, `ga4_only`, etc.) plus auto-generated insights for the gaps. |
+| `list_gtm_accounts` | Discover accessible GTM accounts |
+| `list_gtm_containers` | List containers under an account — returns numeric `container_id` (needed by other tools), public `GTM-XXXXXXX` ID, and usage context (web/iOS/Android/server) |
+| `list_gtm_tags` | Every tag in the live container with parsed event names and resolved firing/blocking trigger names |
+| `get_gtm_tag` | Full raw config for a single tag — every parameter, firing/blocking triggers with filter conditions, priority, pause status, sampling |
+| `list_gtm_triggers` | Every trigger with filter conditions parsed to readable text (e.g. `{{Page Path}} contains service-promotions`, `{{Form ID}} NOT contains wf-form-...`). Renders the `negate` flag explicitly. |
+| `get_gtm_trigger` | Full trigger config + reverse lookup of every tag that uses it. Includes parsed `element_visibility` block (selector, on-screen ratio, firing frequency) for elementVisibility triggers and `group_member_trigger_ids` for triggerGroup types |
+| `list_gtm_variables` | Custom variables (data layer, constants, JS) plus enabled built-in variables |
+| `list_gtm_workspaces` | List drafts (workspaces) under a container — workspace IDs are needed by `get_gtm_workspace_diff` |
+| `get_gtm_workspace_diff` | Drafted-but-not-published changes — common cause of "I edited a tag but nothing happened". Returns `is_clean: true` when nothing is pending. |
+| `list_gtm_versions` | Publish history with version IDs and entity counts. Use to correlate a metric drop with a recent publish. |
+| `get_gtm_version` | Full metadata + tag/trigger names for a single historical container version |
+
+> **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.
+
 ### Planning Tools
 
 | Tool | What It Does |
@@ -145,6 +191,8 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_image_assets` | Create campaign image assets from local PNG, JPEG, or GIF files. |
 | `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_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 |
 | `enable_entity` | Re-enable a paused entity |
@@ -196,12 +244,11 @@ AdLoop manages real ad spend, so safety is not optional.
 
 ## Setup
 
-> **⚠️ Built-in OAuth credentials are temporarily unavailable while Google verification is pending.**
-> Google limits unverified OAuth apps to 100 users, and AdLoop has reached that cap. New users will see a **"This app is blocked"** error if they pick the built-in option in the wizard.
+> **AdLoop uses your own (free) Google Cloud project for OAuth.** The `adloop init` wizard walks you through it — a one-time setup of about 5 minutes, with no shared user caps and no waiting on anyone's verification review. AdLoop does not ship built-in OAuth credentials.
 >
-> **What this means for you:** until Google completes verification, **bring your own Google Cloud project** — it takes ~5 minutes, has no user cap, and the `adloop init` wizard guides you through it. Status updates: [Discussion #13](https://github.com/kLOsk/adloop/discussions/13).
+> **Prefer zero setup?** [**AdLoop Cloud**](https://getadloop.com) is the hosted version: connect Google in two clicks — no Cloud project, no developer token, EU-hosted.
 >
-> *(Existing users whose tokens were already issued before the cap continue to work — only first-time sign-ins are blocked.)*
+> *(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.)*
 
 ### Install
 
@@ -223,7 +270,7 @@ uv run adloop init
 
 ### What `adloop init` does
 
-The wizard defaults to the "bring your own Google Cloud project" path while verification is pending. It walks you through:
+The wizard walks you through:
 
 1. **Google Cloud setup** — creates a project, enables the three APIs, generates an OAuth client (see [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) below for the exact steps the wizard refers you to)
 2. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
@@ -233,8 +280,6 @@ The wizard defaults to the "bring your own Google Cloud project" path while veri
 6. **Safety defaults** — budget cap and dry-run preference
 7. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
 
-The wizard does still offer AdLoop's built-in credentials as a non-default option for existing users whose tokens predate the cap. Picking that option for a brand-new Google account will fail at the consent screen — the wizard warns you about this before you choose.
-
 ### Requirements
 
 - Python 3.11+
@@ -243,7 +288,7 @@ The wizard does still offer AdLoop's built-in credentials as a non-default optio
 
 ### Google Ads Developer Token
 
-A developer token is **always required** — even when using AdLoop's built-in OAuth credentials. The built-in credentials handle Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.
+A developer token is **always required**. Your OAuth client handles Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.
 
 1. **Create an MCC** (free) at [ads.google.com/home/tools/manager-accounts](https://ads.google.com/home/tools/manager-accounts/) if you don't have one. Link your regular Google Ads account to it.
 2. In the MCC, go to **Tools & Settings → API Center**
@@ -265,7 +310,7 @@ Running on a server without a browser (VMs, Docker, SSH)? The wizard automatical
 
 ### Custom Google Cloud Project Setup
 
-This is the default path while built-in credentials are blocked by Google's 100-user cap. The wizard refers to these steps — do them in your browser before running `adloop init` (or while it waits at the OAuth prompt).
+The wizard refers to these steps — do them in your browser before running `adloop init` (or while it waits at the OAuth prompt).
 
 #### Step 1 — Google Cloud Project
 
@@ -347,6 +392,7 @@ Ask your AI assistant things like:
 - *"Draft a new responsive search ad for my main campaign."*
 - *"Which landing pages get paid traffic but don't convert?"*
 - *"Is my tracking set up correctly? Compare my codebase events against GA4."*
+- *"Audit my Google Tag Manager container — which conversions are being captured and where are the gaps?"*
 - *"What keywords should I target for [product]? Find ideas and estimate the budget."*
 - *"How much budget would I need for these keywords in Germany?"*
 - *"Create a new search campaign for [product feature] with a €20/day budget."*
@@ -358,7 +404,7 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 | Section | Key | Default | Description |
 |---------|-----|---------|-------------|
 | `google` | `project_id` | *(empty)* | Google Cloud project ID (only needed with custom credentials) |
-| `google` | `credentials_path` | *(empty — uses built-in)* | Path to OAuth client JSON or service account key. Leave empty to use AdLoop's built-in credentials. |
+| `google` | `credentials_path` | *(empty)* | Path to OAuth client JSON or service account key. Empty = `~/.adloop/credentials.json`, else Application Default Credentials. |
 | `google` | `token_path` | `~/.adloop/token.json` | Where to store the OAuth token (auto-created) |
 | `ga4` | `property_id` | — | Your GA4 property ID (auto-discovered by `adloop init`) |
 | `ads` | `developer_token` | — | Your Google Ads API developer token |
@@ -373,11 +419,11 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 43 tool registrations with safety annotations
+├── server.py          # FastMCP server — 61 tool registrations with safety annotations
 ├── config.py          # Config loader (~/.adloop/config.yaml)
-├── auth.py            # OAuth 2.0 flow (bundled + custom credentials, headless fallback) + service accounts
+├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
 ├── cli.py             # Interactive 'adloop init' setup wizard
-├── crossref.py        # Cross-reference tools (GA4 + Ads combined analysis)
+├── crossref.py        # Cross-reference tools (GA4 + Ads + GTM combined analysis)
 ├── tracking.py        # Tracking validation + code generation tools
 ├── ga4/
 │   ├── client.py      # GA4 Data + Admin API clients
@@ -390,6 +436,9 @@ src/adloop/
 │   ├── pmax.py        # Performance Max tools — campaign/asset group performance, asset labels, top combinations
 │   ├── write.py       # Draft campaign, RSA, keywords; pause, enable, remove, confirm
 │   └── forecast.py    # Budget estimation + keyword discovery via Keyword Planner API
+├── gtm/
+│   ├── client.py      # Google Tag Manager API v2 client
+│   └── read.py        # Live container fetching, tag/trigger/variable parsing, workspace diff, version history
 └── safety/
     ├── guards.py      # Budget caps, bid limits, blocked operations, Broad Match safety
     ├── preview.py     # Change plans and previews
@@ -411,9 +460,10 @@ What's been shipped and what's next:
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - **Claude Desktop one-click install** — `adloop install claude-desktop` (and/or a `.dxt` extension bundle) that writes the AdLoop MCP entry into `claude_desktop_config.json` automatically, so Claude Desktop + Cowork users don't have to hand-edit JSON
 - ~~PyPI package~~ ✓ — `pip install adloop`
-- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required (**currently blocked at 100-user cap** pending Google verification; `adloop init` defaults to the [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) path until verification completes)
+- ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version, live in beta: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
+- ~~Google Tag Manager integration~~ ✓ — read tools for tags, triggers, variables, workspaces, and version history, plus the `audit_event_coverage` three-way join across codebase events, GTM tags, and GA4 actual fires
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter
 - **Video walkthrough**
 
@@ -427,14 +477,14 @@ MIT — see [LICENSE](LICENSE).
 
 ## Privacy
 
-AdLoop runs entirely on your machine. No data is collected, stored, or transmitted to any server. See [PRIVACY.md](PRIVACY.md) for the full privacy policy.
+The open-source version runs entirely on your machine. No data is collected, stored, or transmitted to any server. See [PRIVACY.md](PRIVACY.md) for the full privacy policy. AdLoop Cloud has its own [privacy policy](https://getadloop.com/datenschutz) and [DPA](https://getadloop.com/avv).
 
 ---
 
 <div align="center">
 
-**If AdLoop helps you run Google Ads, GA4, and tracking code from one place — [give it a star](https://github.com/kLOsk/adloop).**
+**If AdLoop helps you run Google Ads, GA4, and tracking code from one place — [give it a star](https://github.com/kLOsk/adloop) or [try the hosted version](https://getadloop.com).**
 
-Made by [@kLOsk](https://github.com/kLOsk) | [Privacy Policy](PRIVACY.md)
+Made by [@kLOsk](https://github.com/kLOsk) | [AdLoop Cloud](https://getadloop.com) | [Privacy Policy](PRIVACY.md)
 
 </div>

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

@@ -14,12 +14,31 @@
 
 An MCP server that gives your AI assistant read + write access to Google Ads and GA4 — with safety guardrails that prevent accidental spend.
 
-`pip install adloop`
+**[☁️ Skip the setup — use AdLoop Cloud (free beta)](https://getadloop.com)**  ·  or self-host: `pip install adloop`
 
 </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.
+
 ---
 
+## Cloud or Self-Hosted?
+
+Both versions run the same 61 tools with the same safety model. The difference is who handles the plumbing:
+
+|  | ☁️ [AdLoop Cloud](https://getadloop.com) | 🛠️ Self-hosted (this repo) |
+|---|---|---|
+| **Setup** | Connect Google in two clicks | ~5 min: own Google Cloud project + `adloop init` |
+| **Google Cloud project** | Not needed | Required (free) |
+| **Ads developer token** | Not needed | Required (from your MCC) |
+| **Works with** | claude.ai, ChatGPT, Claude Code, Cursor, Gemini | Claude Code, Cursor, Claude Desktop, any local MCP client |
+| **Where your data flows** | EU servers (Germany), GDPR-first, DPA included | 100% your machine — nothing leaves it |
+| **Updates** | Automatic | `pip install -U adloop` |
+| **Price** | Free during beta | Free forever (MIT) |
+
+**Not sure? [Start with Cloud](https://getadloop.com)** — it's the fastest way to see what AdLoop can do, and it's the only way to use AdLoop from claude.ai or ChatGPT. Self-host when you want everything on your own machine or need to modify the code. And if you're here to hack on AdLoop itself: welcome, keep scrolling.
+
 ## What It Solves
 
 AdLoop exists because managing Google Ads alongside your code is a mess. These are the specific problems it handles:
@@ -34,6 +53,8 @@ AdLoop exists because managing Google Ads alongside your code is a mess. These a
 
 - **"My landing page gets paid traffic but nobody converts."** AdLoop joins your ad final URLs with GA4 page-level data. See which pages get clicks but no conversions, which have high bounce rates, and which ones are orphaned from any ad campaign.
 
+- **"Are conversions even being tagged on every page?"** AdLoop reads your live Google Tag Manager container, joins it against the events in your codebase and the events firing in GA4, and tells you exactly which conversions are being captured, which tags are paused, which page-scope filters are too narrow, and which codebase events have no tag at all — the kind of three-way audit GTM Preview can't give you in a single view.
+
 - **"I don't know if my EU consent setup is causing data gaps."** In Europe, 30-70% of users reject analytics cookies. AdLoop accounts for this automatically — it won't diagnose a normal GDPR consent gap as broken tracking.
 
 ## Built From Real Usage
@@ -42,9 +63,9 @@ 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 43 Tools
+## All 61 Tools
 
-> **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init`
+> **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)
 
 ### Diagnostics
 
@@ -79,8 +100,11 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_asset_performance` | Per-asset details for PMax — field type, serving status, content |
 | `get_detailed_asset_performance` | Top-performing asset combinations — which headline+description+image combos Google selects most |
 | `get_audience_performance` | Audience segment performance — remarketing, in-market, affinity, demographics |
+| `get_demographic_targeting` | List demographic criteria (age/gender/parental status/income) on an ad group or campaign |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
+> **Compact mode** — `get_campaign_performance`, `get_keyword_performance`, `get_search_terms`, and `get_ad_performance` accept `compact=true`: account totals, breakdowns, top-10 rows, and pre-computed offender lists (zero-conversion spenders, low-QS keywords, negative-keyword candidates, thin RSAs) instead of every row. ~90% smaller responses — built for account audits so raw tables don't flood your AI's context.
+
 ### Cross-Reference Tools (GA4 + Ads Combined)
 
 These tools call both APIs internally and return unified results with auto-generated insights. They're the core of what makes AdLoop different from having separate GA4 and Ads tools.
@@ -98,6 +122,27 @@ These tools call both APIs internally and return unified results with auto-gener
 | `validate_tracking` | Compare event names found in your codebase against what GA4 actually records. Returns matched, missing, and unexpected events with diagnostics. |
 | `generate_tracking_code` | Generate ready-to-paste GA4 gtag JavaScript for any event, with recommended parameters for well-known events (sign_up, purchase, etc.) and optional trigger wrappers. |
 
+### Google Tag Manager Tools
+
+These tools read the live GTM container and join it with the codebase + GA4 to find tracking gaps that pure GA4 inspection can't catch — page-scoped triggers, paused tags, dynamic event names, brittle CSS selectors, and codebase events with no tag wired up at all.
+
+| Tool | What It Does |
+|------|-------------|
+| `audit_event_coverage` | **The flagship.** Three-way join: codebase events ↔ GTM tags ↔ GA4 actual fires. For each event name in `expected_events`, returns one of 10 statuses (`ok`, `no_tag_no_fire`, `tag_paused`, `tag_active_but_not_firing`, `gtm_only_firing`, `ga4_only`, etc.) plus auto-generated insights for the gaps. |
+| `list_gtm_accounts` | Discover accessible GTM accounts |
+| `list_gtm_containers` | List containers under an account — returns numeric `container_id` (needed by other tools), public `GTM-XXXXXXX` ID, and usage context (web/iOS/Android/server) |
+| `list_gtm_tags` | Every tag in the live container with parsed event names and resolved firing/blocking trigger names |
+| `get_gtm_tag` | Full raw config for a single tag — every parameter, firing/blocking triggers with filter conditions, priority, pause status, sampling |
+| `list_gtm_triggers` | Every trigger with filter conditions parsed to readable text (e.g. `{{Page Path}} contains service-promotions`, `{{Form ID}} NOT contains wf-form-...`). Renders the `negate` flag explicitly. |
+| `get_gtm_trigger` | Full trigger config + reverse lookup of every tag that uses it. Includes parsed `element_visibility` block (selector, on-screen ratio, firing frequency) for elementVisibility triggers and `group_member_trigger_ids` for triggerGroup types |
+| `list_gtm_variables` | Custom variables (data layer, constants, JS) plus enabled built-in variables |
+| `list_gtm_workspaces` | List drafts (workspaces) under a container — workspace IDs are needed by `get_gtm_workspace_diff` |
+| `get_gtm_workspace_diff` | Drafted-but-not-published changes — common cause of "I edited a tag but nothing happened". Returns `is_clean: true` when nothing is pending. |
+| `list_gtm_versions` | Publish history with version IDs and entity counts. Use to correlate a metric drop with a recent publish. |
+| `get_gtm_version` | Full metadata + tag/trigger names for a single historical container version |
+
+> **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.
+
 ### Planning Tools
 
 | Tool | What It Does |
@@ -121,6 +166,8 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_image_assets` | Create campaign image assets from local PNG, JPEG, or GIF files. |
 | `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_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 |
 | `enable_entity` | Re-enable a paused entity |
@@ -172,12 +219,11 @@ AdLoop manages real ad spend, so safety is not optional.
 
 ## Setup
 
-> **⚠️ Built-in OAuth credentials are temporarily unavailable while Google verification is pending.**
-> Google limits unverified OAuth apps to 100 users, and AdLoop has reached that cap. New users will see a **"This app is blocked"** error if they pick the built-in option in the wizard.
+> **AdLoop uses your own (free) Google Cloud project for OAuth.** The `adloop init` wizard walks you through it — a one-time setup of about 5 minutes, with no shared user caps and no waiting on anyone's verification review. AdLoop does not ship built-in OAuth credentials.
 >
-> **What this means for you:** until Google completes verification, **bring your own Google Cloud project** — it takes ~5 minutes, has no user cap, and the `adloop init` wizard guides you through it. Status updates: [Discussion #13](https://github.com/kLOsk/adloop/discussions/13).
+> **Prefer zero setup?** [**AdLoop Cloud**](https://getadloop.com) is the hosted version: connect Google in two clicks — no Cloud project, no developer token, EU-hosted.
 >
-> *(Existing users whose tokens were already issued before the cap continue to work — only first-time sign-ins are blocked.)*
+> *(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.)*
 
 ### Install
 
@@ -199,7 +245,7 @@ uv run adloop init
 
 ### What `adloop init` does
 
-The wizard defaults to the "bring your own Google Cloud project" path while verification is pending. It walks you through:
+The wizard walks you through:
 
 1. **Google Cloud setup** — creates a project, enables the three APIs, generates an OAuth client (see [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) below for the exact steps the wizard refers you to)
 2. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
@@ -209,8 +255,6 @@ The wizard defaults to the "bring your own Google Cloud project" path while veri
 6. **Safety defaults** — budget cap and dry-run preference
 7. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
 
-The wizard does still offer AdLoop's built-in credentials as a non-default option for existing users whose tokens predate the cap. Picking that option for a brand-new Google account will fail at the consent screen — the wizard warns you about this before you choose.
-
 ### Requirements
 
 - Python 3.11+
@@ -219,7 +263,7 @@ The wizard does still offer AdLoop's built-in credentials as a non-default optio
 
 ### Google Ads Developer Token
 
-A developer token is **always required** — even when using AdLoop's built-in OAuth credentials. The built-in credentials handle Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.
+A developer token is **always required**. Your OAuth client handles Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.
 
 1. **Create an MCC** (free) at [ads.google.com/home/tools/manager-accounts](https://ads.google.com/home/tools/manager-accounts/) if you don't have one. Link your regular Google Ads account to it.
 2. In the MCC, go to **Tools & Settings → API Center**
@@ -241,7 +285,7 @@ Running on a server without a browser (VMs, Docker, SSH)? The wizard automatical
 
 ### Custom Google Cloud Project Setup
 
-This is the default path while built-in credentials are blocked by Google's 100-user cap. The wizard refers to these steps — do them in your browser before running `adloop init` (or while it waits at the OAuth prompt).
+The wizard refers to these steps — do them in your browser before running `adloop init` (or while it waits at the OAuth prompt).
 
 #### Step 1 — Google Cloud Project
 
@@ -323,6 +367,7 @@ Ask your AI assistant things like:
 - *"Draft a new responsive search ad for my main campaign."*
 - *"Which landing pages get paid traffic but don't convert?"*
 - *"Is my tracking set up correctly? Compare my codebase events against GA4."*
+- *"Audit my Google Tag Manager container — which conversions are being captured and where are the gaps?"*
 - *"What keywords should I target for [product]? Find ideas and estimate the budget."*
 - *"How much budget would I need for these keywords in Germany?"*
 - *"Create a new search campaign for [product feature] with a €20/day budget."*
@@ -334,7 +379,7 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 | Section | Key | Default | Description |
 |---------|-----|---------|-------------|
 | `google` | `project_id` | *(empty)* | Google Cloud project ID (only needed with custom credentials) |
-| `google` | `credentials_path` | *(empty — uses built-in)* | Path to OAuth client JSON or service account key. Leave empty to use AdLoop's built-in credentials. |
+| `google` | `credentials_path` | *(empty)* | Path to OAuth client JSON or service account key. Empty = `~/.adloop/credentials.json`, else Application Default Credentials. |
 | `google` | `token_path` | `~/.adloop/token.json` | Where to store the OAuth token (auto-created) |
 | `ga4` | `property_id` | — | Your GA4 property ID (auto-discovered by `adloop init`) |
 | `ads` | `developer_token` | — | Your Google Ads API developer token |
@@ -349,11 +394,11 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 43 tool registrations with safety annotations
+├── server.py          # FastMCP server — 61 tool registrations with safety annotations
 ├── config.py          # Config loader (~/.adloop/config.yaml)
-├── auth.py            # OAuth 2.0 flow (bundled + custom credentials, headless fallback) + service accounts
+├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
 ├── cli.py             # Interactive 'adloop init' setup wizard
-├── crossref.py        # Cross-reference tools (GA4 + Ads combined analysis)
+├── crossref.py        # Cross-reference tools (GA4 + Ads + GTM combined analysis)
 ├── tracking.py        # Tracking validation + code generation tools
 ├── ga4/
 │   ├── client.py      # GA4 Data + Admin API clients
@@ -366,6 +411,9 @@ src/adloop/
 │   ├── pmax.py        # Performance Max tools — campaign/asset group performance, asset labels, top combinations
 │   ├── write.py       # Draft campaign, RSA, keywords; pause, enable, remove, confirm
 │   └── forecast.py    # Budget estimation + keyword discovery via Keyword Planner API
+├── gtm/
+│   ├── client.py      # Google Tag Manager API v2 client
+│   └── read.py        # Live container fetching, tag/trigger/variable parsing, workspace diff, version history
 └── safety/
     ├── guards.py      # Budget caps, bid limits, blocked operations, Broad Match safety
     ├── preview.py     # Change plans and previews
@@ -387,9 +435,10 @@ What's been shipped and what's next:
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - **Claude Desktop one-click install** — `adloop install claude-desktop` (and/or a `.dxt` extension bundle) that writes the AdLoop MCP entry into `claude_desktop_config.json` automatically, so Claude Desktop + Cowork users don't have to hand-edit JSON
 - ~~PyPI package~~ ✓ — `pip install adloop`
-- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required (**currently blocked at 100-user cap** pending Google verification; `adloop init` defaults to the [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) path until verification completes)
+- ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version, live in beta: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
+- ~~Google Tag Manager integration~~ ✓ — read tools for tags, triggers, variables, workspaces, and version history, plus the `audit_event_coverage` three-way join across codebase events, GTM tags, and GA4 actual fires
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter
 - **Video walkthrough**
 
@@ -403,14 +452,14 @@ MIT — see [LICENSE](LICENSE).
 
 ## Privacy
 
-AdLoop runs entirely on your machine. No data is collected, stored, or transmitted to any server. See [PRIVACY.md](PRIVACY.md) for the full privacy policy.
+The open-source version runs entirely on your machine. No data is collected, stored, or transmitted to any server. See [PRIVACY.md](PRIVACY.md) for the full privacy policy. AdLoop Cloud has its own [privacy policy](https://getadloop.com/datenschutz) and [DPA](https://getadloop.com/avv).
 
 ---
 
 <div align="center">
 
-**If AdLoop helps you run Google Ads, GA4, and tracking code from one place — [give it a star](https://github.com/kLOsk/adloop).**
+**If AdLoop helps you run Google Ads, GA4, and tracking code from one place — [give it a star](https://github.com/kLOsk/adloop) or [try the hosted version](https://getadloop.com).**
 
-Made by [@kLOsk](https://github.com/kLOsk) | [Privacy Policy](PRIVACY.md)
+Made by [@kLOsk](https://github.com/kLOsk) | [AdLoop Cloud](https://getadloop.com) | [Privacy Policy](PRIVACY.md)
 
 </div>

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

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.9.0"
+version = "0.11.0"
 description = "The AI command center for Google Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [
@@ -14,6 +14,7 @@ dependencies = [
     "google-ads>=29.0.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",
     "pyyaml>=6.0",
 ]

{adloop-0.9.0 → adloop-0.11.0}/src/adloop/__init__.py

@@ -1,8 +1,12 @@
 """AdLoop — MCP server connecting Google Ads + GA4 + codebase."""
 
 import sys
+from importlib.metadata import PackageNotFoundError, version
 
-__version__ = "0.9.0"
+try:
+    __version__ = version("adloop")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0.dev0"
 
 
 def main() -> None:
@@ -42,6 +46,15 @@ def main() -> None:
             sys.exit(130)
         return
 
+    # Process-global side effects (signal handlers, heartbeat thread, and
+    # the stdio cancellation-race monkeypatch) are deliberately installed
+    # here — in the stdio entry point — rather than at adloop.server import
+    # time, so embedding the server in an ASGI app stays side-effect-free.
+    from adloop import _mcp_patches, diagnostics
+
+    diagnostics.install()
+    _mcp_patches.install()
+
     from adloop.server import mcp
 
     mcp.run()

{adloop-0.9.0 → adloop-0.11.0}/src/adloop/ads/gaql.py

@@ -89,7 +89,29 @@ _GAQL_ERROR_HINTS = {
 
 
 def _parse_gaql_error(exc: Exception) -> str:
-    """Extract a human-readable message from Google Ads gRPC errors."""
+    """Extract a human-readable message from Google Ads gRPC errors.
+
+    Prefers the structured ``failure.errors[]`` a GoogleAdsException
+    carries — Google's own message names the exact field/clause at
+    fault (e.g. PROHIBITED_FIELD_IN_SELECT_CLAUSE with the field name),
+    which is far more actionable than a generic hint. Known error codes
+    still get the hint appended as a suffix.
+    """
+    failure = getattr(exc, "failure", None)
+    errors = getattr(failure, "errors", None) if failure is not None else None
+    if errors:
+        parts = []
+        for err in errors:
+            code = str(getattr(err, "error_code", "") or "").strip()
+            message = str(getattr(err, "message", "") or "").strip()
+            parts.append(" — ".join(p for p in (code, message) if p))
+        detail = " | ".join(p for p in parts if p)
+        if detail:
+            for known, hint in _GAQL_ERROR_HINTS.items():
+                if known in detail:
+                    return f"{detail} (hint: {hint})"
+            return detail
+
     raw = str(exc)
     for code, hint in _GAQL_ERROR_HINTS.items():
         if code in raw:
@@ -137,6 +159,21 @@ def _to_python(obj: object) -> object:
     # AdTextAsset and similar message types
     if hasattr(obj, "text") and isinstance(getattr(obj, "text", None), str):
         return obj.text
+    # Nested proto-plus messages (targeting settings, criteria, ...) —
+    # serialize to a dict instead of collapsing to their str() repr.
+    try:
+        import proto
+
+        if isinstance(obj, proto.Message):
+            return type(obj).to_dict(
+                obj, preserving_proto_field_name=True, use_integers_for_enums=False
+            )
+    except ImportError:
+        pass
+    if hasattr(obj, "DESCRIPTOR"):
+        from google.protobuf.json_format import MessageToDict
+
+        return MessageToDict(obj, preserving_proto_field_name=True)
     return str(obj)