adloop 0.4.2__tar.gz → 0.5.0__tar.gz

{adloop-0.4.2 → adloop-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.4.2
+Version: 0.5.0
 Summary: Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped.
 Keywords: mcp,google-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
@@ -66,7 +66,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 38 Tools
+## All 43 Tools
 
 > **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init`
 
@@ -94,7 +94,10 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_ad_performance` | Ad copy analysis — headlines, descriptions, CTR |
 | `get_keyword_performance` | Keywords — quality scores, competitive metrics |
 | `get_search_terms` | What users actually searched before clicking |
-| `get_negative_keywords` | List existing negative keywords for a campaign or all campaigns |
+| `get_negative_keywords` | List direct campaign-level negative keywords |
+| `get_negative_keyword_lists` | List all shared negative keyword lists (SharedSets) — names, IDs, status, keyword count |
+| `get_negative_keyword_list_keywords` | List the keywords inside a specific shared negative keyword list |
+| `get_negative_keyword_list_campaigns` | List which campaigns a shared negative keyword list is attached to |
 | `get_recommendations` | Google's auto-generated recommendations with type, estimated impact, and campaign context |
 | `get_pmax_performance` | Performance Max campaign metrics with network breakdown + asset group ad strength |
 | `get_asset_performance` | Per-asset details for PMax — field type, serving status, content |
@@ -123,6 +126,7 @@ These tools call both APIs internally and return unified results with auto-gener
 
 | 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. |
 
 ### Google Ads Write Tools
@@ -140,7 +144,8 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_structured_snippets` | Create campaign structured snippet assets using official header values and 3-10 snippet values. |
 | `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 to reduce wasted spend |
+| `add_negative_keywords` | Propose negative keywords directly on a campaign |
+| `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 |
 | `remove_entity` | Permanently remove an entity (irreversible — prefers pause). Supports keywords, negative keywords, ads, ad groups, campaigns. |
@@ -154,7 +159,7 @@ AdLoop ships with orchestration rules that teach the AI *how* to combine these t
 - **Claude Code**: `.claude/rules/adloop.md` (synced from Cursor rules via `scripts/sync-rules.py`)
 
 The rules include:
-- **Orchestration patterns** for common workflows (performance review, conversion diagnosis, campaign creation, negative keyword hygiene, tracking validation, budget planning, landing page analysis)
+- **Orchestration patterns** for common workflows (performance review, conversion diagnosis, campaign creation, negative keyword hygiene, keyword discovery, tracking validation, budget planning, landing page analysis)
 - **GAQL quick reference** with syntax, common queries, and gotchas
 - **Safety rules** including Broad Match + Manual CPC prevention and pre-write validation
 - **Ad copy character limit guidance** (30-char headlines are shorter than you think)
@@ -224,6 +229,25 @@ The wizard:
 
 - Python 3.11+
 - A Google Ads account with an MCC (Manager Account)
+- A Google Ads Developer Token (see below)
+
+### 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.
+
+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**
+3. Your **developer token** is shown there. Copy it — the wizard will ask for it.
+
+**Access levels** — your token's access level determines what it can do:
+
+| Level | How to Get | What It Allows |
+|-------|-----------|----------------|
+| **Test Account** | Default for new tokens | Can only access test accounts — **not production accounts**. If you see `DEVELOPER_TOKEN_NOT_APPROVED`, this is why. |
+| **Explorer** | Automatic after first API call with a production account | 2,880 operations/day on production accounts. Enough to get started. |
+| **Basic** | [Apply through API Center](https://ads.google.com/aw/apicenter) | 15,000 operations/day. Apply if you need more. |
+
+> **Getting `DEVELOPER_TOKEN_NOT_APPROVED`?** Your token is at "Test Account" level. Go to [API Center](https://ads.google.com/aw/apicenter) in your MCC and check your access level. If it shows "Test Account", you need to apply for Basic access or wait for Explorer access to be granted after your first production API call.
 
 ### Headless Servers
 
@@ -253,17 +277,7 @@ When you run `adloop init`, choose "No" when asked about built-in credentials. T
 
 > Service accounts are also supported — just place the service account key JSON at the same `credentials_path`. AdLoop detects the file type automatically.
 
-#### Step 3 — Google Ads Developer Token
-
-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**
-3. Your **developer token** is shown there. Copy it.
-
-Access levels:
-- **Explorer** (automatic) — 2,880 operations/day on production accounts. Enough to get started.
-- **Basic** (requires application) — 15,000 operations/day. Apply through the same API Center page if you need more.
-
-#### Step 4 — Connect to Your Editor
+#### Step 3 — Connect to Your Editor
 
 **Cursor** — Add to your project's `.cursor/mcp.json`:
 
@@ -313,6 +327,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."*
+- *"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."*
 
@@ -338,7 +353,7 @@ 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 — 38 tool registrations with safety annotations
+├── server.py          # FastMCP server — 43 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
 ├── cli.py             # Interactive 'adloop init' setup wizard
@@ -349,12 +364,12 @@ src/adloop/
 │   ├── reports.py     # Account summaries, reports, realtime
 │   └── tracking.py    # Event discovery
 ├── ads/
-│   ├── client.py      # Google Ads API client (version-pinned)
+│   ├── client.py      # Google Ads API client (version-pinned) + retry/backoff for rate limits
 │   ├── gaql.py        # GAQL query execution with human-readable error parsing
-│   ├── read.py        # Campaign, ad, keyword, search term, negative keyword, recommendations, audience reads
+│   ├── read.py        # Campaign, ad, keyword, search term, negative keyword, shared sets, recommendations, audience reads
 │   ├── 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 via Keyword Planner API
+│   └── forecast.py    # Budget estimation + keyword discovery via Keyword Planner API
 └── safety/
     ├── guards.py      # Budget caps, bid limits, blocked operations, Broad Match safety
     ├── preview.py     # Change plans and previews
@@ -369,7 +384,9 @@ What's been shipped and what's next:
 - ~~Google Ads read + write tools with safety layer~~ ✓
 - ~~Cross-reference intelligence (campaign→conversion mapping, landing page analysis, attribution comparison)~~ ✓
 - ~~Tracking utilities (validate events against GA4, generate gtag code)~~ ✓
-- ~~Budget estimation via Keyword Planner~~ ✓
+- ~~Budget estimation + keyword discovery via Keyword Planner~~ ✓
+- ~~Shared negative keyword lists (SharedSet API)~~ ✓
+- ~~Retry/backoff for API rate limits~~ ✓
 - ~~Setup wizard (`adloop init`)~~ ✓
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - ~~PyPI package~~ ✓ — `pip install adloop`

{adloop-0.4.2 → adloop-0.5.0}/README.md

@@ -42,7 +42,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 38 Tools
+## All 43 Tools
 
 > **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init`
 
@@ -70,7 +70,10 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_ad_performance` | Ad copy analysis — headlines, descriptions, CTR |
 | `get_keyword_performance` | Keywords — quality scores, competitive metrics |
 | `get_search_terms` | What users actually searched before clicking |
-| `get_negative_keywords` | List existing negative keywords for a campaign or all campaigns |
+| `get_negative_keywords` | List direct campaign-level negative keywords |
+| `get_negative_keyword_lists` | List all shared negative keyword lists (SharedSets) — names, IDs, status, keyword count |
+| `get_negative_keyword_list_keywords` | List the keywords inside a specific shared negative keyword list |
+| `get_negative_keyword_list_campaigns` | List which campaigns a shared negative keyword list is attached to |
 | `get_recommendations` | Google's auto-generated recommendations with type, estimated impact, and campaign context |
 | `get_pmax_performance` | Performance Max campaign metrics with network breakdown + asset group ad strength |
 | `get_asset_performance` | Per-asset details for PMax — field type, serving status, content |
@@ -99,6 +102,7 @@ These tools call both APIs internally and return unified results with auto-gener
 
 | 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. |
 
 ### Google Ads Write Tools
@@ -116,7 +120,8 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_structured_snippets` | Create campaign structured snippet assets using official header values and 3-10 snippet values. |
 | `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 to reduce wasted spend |
+| `add_negative_keywords` | Propose negative keywords directly on a campaign |
+| `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 |
 | `remove_entity` | Permanently remove an entity (irreversible — prefers pause). Supports keywords, negative keywords, ads, ad groups, campaigns. |
@@ -130,7 +135,7 @@ AdLoop ships with orchestration rules that teach the AI *how* to combine these t
 - **Claude Code**: `.claude/rules/adloop.md` (synced from Cursor rules via `scripts/sync-rules.py`)
 
 The rules include:
-- **Orchestration patterns** for common workflows (performance review, conversion diagnosis, campaign creation, negative keyword hygiene, tracking validation, budget planning, landing page analysis)
+- **Orchestration patterns** for common workflows (performance review, conversion diagnosis, campaign creation, negative keyword hygiene, keyword discovery, tracking validation, budget planning, landing page analysis)
 - **GAQL quick reference** with syntax, common queries, and gotchas
 - **Safety rules** including Broad Match + Manual CPC prevention and pre-write validation
 - **Ad copy character limit guidance** (30-char headlines are shorter than you think)
@@ -200,6 +205,25 @@ The wizard:
 
 - Python 3.11+
 - A Google Ads account with an MCC (Manager Account)
+- A Google Ads Developer Token (see below)
+
+### 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.
+
+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**
+3. Your **developer token** is shown there. Copy it — the wizard will ask for it.
+
+**Access levels** — your token's access level determines what it can do:
+
+| Level | How to Get | What It Allows |
+|-------|-----------|----------------|
+| **Test Account** | Default for new tokens | Can only access test accounts — **not production accounts**. If you see `DEVELOPER_TOKEN_NOT_APPROVED`, this is why. |
+| **Explorer** | Automatic after first API call with a production account | 2,880 operations/day on production accounts. Enough to get started. |
+| **Basic** | [Apply through API Center](https://ads.google.com/aw/apicenter) | 15,000 operations/day. Apply if you need more. |
+
+> **Getting `DEVELOPER_TOKEN_NOT_APPROVED`?** Your token is at "Test Account" level. Go to [API Center](https://ads.google.com/aw/apicenter) in your MCC and check your access level. If it shows "Test Account", you need to apply for Basic access or wait for Explorer access to be granted after your first production API call.
 
 ### Headless Servers
 
@@ -229,17 +253,7 @@ When you run `adloop init`, choose "No" when asked about built-in credentials. T
 
 > Service accounts are also supported — just place the service account key JSON at the same `credentials_path`. AdLoop detects the file type automatically.
 
-#### Step 3 — Google Ads Developer Token
-
-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**
-3. Your **developer token** is shown there. Copy it.
-
-Access levels:
-- **Explorer** (automatic) — 2,880 operations/day on production accounts. Enough to get started.
-- **Basic** (requires application) — 15,000 operations/day. Apply through the same API Center page if you need more.
-
-#### Step 4 — Connect to Your Editor
+#### Step 3 — Connect to Your Editor
 
 **Cursor** — Add to your project's `.cursor/mcp.json`:
 
@@ -289,6 +303,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."*
+- *"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."*
 
@@ -314,7 +329,7 @@ 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 — 38 tool registrations with safety annotations
+├── server.py          # FastMCP server — 43 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
 ├── cli.py             # Interactive 'adloop init' setup wizard
@@ -325,12 +340,12 @@ src/adloop/
 │   ├── reports.py     # Account summaries, reports, realtime
 │   └── tracking.py    # Event discovery
 ├── ads/
-│   ├── client.py      # Google Ads API client (version-pinned)
+│   ├── client.py      # Google Ads API client (version-pinned) + retry/backoff for rate limits
 │   ├── gaql.py        # GAQL query execution with human-readable error parsing
-│   ├── read.py        # Campaign, ad, keyword, search term, negative keyword, recommendations, audience reads
+│   ├── read.py        # Campaign, ad, keyword, search term, negative keyword, shared sets, recommendations, audience reads
 │   ├── 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 via Keyword Planner API
+│   └── forecast.py    # Budget estimation + keyword discovery via Keyword Planner API
 └── safety/
     ├── guards.py      # Budget caps, bid limits, blocked operations, Broad Match safety
     ├── preview.py     # Change plans and previews
@@ -345,7 +360,9 @@ What's been shipped and what's next:
 - ~~Google Ads read + write tools with safety layer~~ ✓
 - ~~Cross-reference intelligence (campaign→conversion mapping, landing page analysis, attribution comparison)~~ ✓
 - ~~Tracking utilities (validate events against GA4, generate gtag code)~~ ✓
-- ~~Budget estimation via Keyword Planner~~ ✓
+- ~~Budget estimation + keyword discovery via Keyword Planner~~ ✓
+- ~~Shared negative keyword lists (SharedSet API)~~ ✓
+- ~~Retry/backoff for API rate limits~~ ✓
 - ~~Setup wizard (`adloop init`)~~ ✓
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - ~~PyPI package~~ ✓ — `pip install adloop`

{adloop-0.4.2 → adloop-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.4.2"
+version = "0.5.0"
 description = "Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped."
 readme = "README.md"
 authors = [

{adloop-0.4.2 → adloop-0.5.0}/src/adloop/__init__.py

@@ -2,7 +2,7 @@
 
 import sys
 
-__version__ = "0.4.2"
+__version__ = "0.5.0"
 
 
 def main() -> None:
@@ -11,6 +11,10 @@ def main() -> None:
     Routes to the setup wizard when called as ``adloop init``,
     otherwise starts the MCP server.
     """
+    if len(sys.argv) > 1 and sys.argv[1] in ("--version", "-V"):
+        print(f"adloop {__version__}")
+        return
+
     if len(sys.argv) > 1 and sys.argv[1] == "init":
         from adloop.cli import run_init_wizard
 

adloop-0.5.0/src/adloop/ads/client.py

@@ -0,0 +1,98 @@
+"""Google Ads API client wrapper — thin layer over the google-ads library."""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import TYPE_CHECKING, Any, Callable, TypeVar
+
+_T = TypeVar("_T")
+
+if TYPE_CHECKING:
+    from google.ads.googleads.client import GoogleAdsClient
+
+    from adloop.config import AdLoopConfig
+
+# 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"
+
+
+def get_ads_client(config: AdLoopConfig) -> GoogleAdsClient:
+    """Return an authenticated Google Ads API client pinned to a specific API version."""
+    from google.ads.googleads.client import GoogleAdsClient
+
+    from adloop.auth import get_ads_credentials
+
+    credentials = get_ads_credentials(config)
+
+    client_config = {
+        "developer_token": config.ads.developer_token,
+        "use_proto_plus": True,
+        "version": GOOGLE_ADS_API_VERSION,
+    }
+
+    if config.ads.login_customer_id:
+        client_config["login_customer_id"] = config.ads.login_customer_id.replace("-", "")
+
+    client = GoogleAdsClient(credentials=credentials, **client_config)
+    return client
+
+
+def normalize_customer_id(customer_id: str) -> str:
+    """Strip dashes from customer ID for API calls (123-456-7890 -> 1234567890)."""
+    return customer_id.replace("-", "")
+
+
+def _is_rate_limit_error(exc: Exception) -> bool:
+    """Return True if the exception is a 429 / RESOURCE_EXHAUSTED rate-limit error.
+
+    Checks the gRPC status code on GoogleAdsException first (reliable),
+    then falls back to string matching for non-gRPC exceptions.
+    """
+    try:
+        from google.ads.googleads.errors import GoogleAdsException
+
+        if isinstance(exc, GoogleAdsException):
+            from grpc import StatusCode
+
+            return exc.error.code() == StatusCode.RESOURCE_EXHAUSTED
+    except ImportError:
+        pass
+
+    msg = str(exc).upper()
+    return (
+        "RESOURCE_EXHAUSTED" in msg
+        or "RATE_LIMIT" in msg
+        or "QUOTA_EXCEEDED" in msg
+    )
+
+
+def call_with_retry(
+    fn: Callable[..., _T],
+    /,
+    *args: Any,
+    max_attempts: int = 4,
+    base_delay: float = 1.0,
+    **kwargs: Any,
+) -> _T:
+    """Call fn(*args, **kwargs) with exponential backoff on 429 / RESOURCE_EXHAUSTED.
+
+    Retries up to max_attempts times (default 4 — i.e. 3 retries after the
+    initial attempt). Each wait is base_delay * 2^attempt seconds plus up to
+    1 second of random jitter to avoid thundering-herd.
+
+    All other exceptions are re-raised immediately without retrying.
+
+    Note: uses time.sleep (blocking). This is safe because FastMCP runs sync
+    tool functions in a thread executor — only the worker thread blocks.
+    """
+    for attempt in range(max_attempts):
+        try:
+            return fn(*args, **kwargs)
+        except Exception as exc:
+            if not _is_rate_limit_error(exc) or attempt == max_attempts - 1:
+                raise
+            delay = base_delay * (2**attempt) + random.uniform(0, 1)
+            time.sleep(delay)

{adloop-0.4.2 → adloop-0.5.0}/src/adloop/ads/forecast.py

@@ -1,4 +1,4 @@
-"""Budget estimation via Google Ads Keyword Planner forecast metrics."""
+"""Budget estimation and keyword discovery via Google Ads Keyword Planner."""
 
 from __future__ import annotations
 
@@ -154,3 +154,117 @@ def estimate_budget(
         "keywords_used": len([kw for kw in keywords if kw.get("text")]),
         "insights": insights,
     }
+
+
+_COMPETITION_LABELS = {0: "UNSPECIFIED", 1: "LOW", 2: "MEDIUM", 3: "HIGH"}
+
+
+def discover_keywords(
+    config: AdLoopConfig,
+    *,
+    seed_keywords: list[str] = [],  # noqa: B006 — mutable default required for MCP JSON schema (array, not anyOf)
+    url: str = "",
+    geo_target_id: str = "2276",
+    language_id: str = "1000",
+    page_size: int = 50,
+    customer_id: str = "",
+) -> dict:
+    """Discover new keyword ideas using Google Ads Keyword Planner.
+
+    Mirrors the "Discover new keywords" workflow in the Keyword Planner UI:
+    - Start with keywords: provide seed_keywords (one or more terms)
+    - Start with a website: provide url (a landing page or full site URL)
+    - Both together: keywords + url for more targeted ideas
+
+    Returns keyword ideas with avg monthly searches, competition level,
+    and top-of-page bid range.
+
+    seed_keywords: list of seed terms, e.g. ["running shoes", "trail running"]
+    url: a page or site URL to extract keyword ideas from
+    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)
+    """
+    from adloop.ads.client import call_with_retry, get_ads_client, normalize_customer_id
+
+    seed_keywords = list(seed_keywords)
+    if not seed_keywords and not url:
+        return {"error": "Provide at least one of: seed_keywords or url"}
+
+    client = get_ads_client(config)
+    cid = normalize_customer_id(customer_id or config.ads.customer_id)
+    googleads_service = client.get_service("GoogleAdsService")
+    kp_service = client.get_service("KeywordPlanIdeaService")
+
+    request = client.get_type("GenerateKeywordIdeasRequest")
+    request.customer_id = cid
+    request.language = googleads_service.language_constant_path(language_id)
+    request.geo_target_constants.append(
+        googleads_service.geo_target_constant_path(geo_target_id)
+    )
+    request.keyword_plan_network = (
+        client.enums.KeywordPlanNetworkEnum.GOOGLE_SEARCH
+    )
+    request.page_size = min(max(1, page_size), 1000)
+
+    if seed_keywords and url:
+        request.keyword_and_url_seed.url = url
+        request.keyword_and_url_seed.keywords.extend(seed_keywords)
+    elif seed_keywords:
+        request.keyword_seed.keywords.extend(seed_keywords)
+    else:
+        request.url_seed.url = url
+
+    response = call_with_retry(kp_service.generate_keyword_ideas, request=request)
+
+    ideas = []
+    for idea in response:
+        metrics = idea.keyword_idea_metrics
+        avg_monthly = getattr(metrics, "avg_monthly_searches", None)
+        competition_value = getattr(metrics, "competition", 0)
+        competition_label = _COMPETITION_LABELS.get(int(competition_value), "UNSPECIFIED")
+        competition_index = getattr(metrics, "competition_index", None)
+        low_bid_micros = getattr(metrics, "low_top_of_page_bid_micros", None)
+        high_bid_micros = getattr(metrics, "high_top_of_page_bid_micros", None)
+
+        ideas.append({
+            "keyword": idea.text,
+            "avg_monthly_searches": int(avg_monthly) if avg_monthly else None,
+            "competition": competition_label,
+            "competition_index": int(competition_index) if competition_index else None,
+            "low_top_of_page_bid": round(low_bid_micros / 1_000_000, 2) if low_bid_micros else None,
+            "high_top_of_page_bid": round(high_bid_micros / 1_000_000, 2) if high_bid_micros else None,
+        })
+
+    # Sort by avg monthly searches descending (None last)
+    ideas.sort(key=lambda x: x["avg_monthly_searches"] or 0, reverse=True)
+
+    insights = []
+    if ideas:
+        high_competition = [i for i in ideas if i["competition"] == "HIGH"]
+        low_competition = [i for i in ideas if i["competition"] == "LOW"]
+        if high_competition:
+            insights.append(
+                f"{len(high_competition)} high-competition keyword(s) — expect "
+                f"higher CPCs and harder positioning."
+            )
+        if low_competition:
+            insights.append(
+                f"{len(low_competition)} low-competition keyword(s) — good "
+                f"opportunities for early traction at lower cost."
+            )
+        with_volume = [i for i in ideas if i["avg_monthly_searches"]]
+        if with_volume:
+            top = with_volume[0]
+            insights.append(
+                f"Highest-volume idea: '{top['keyword']}' with ~{top['avg_monthly_searches']:,} "
+                f"avg monthly searches."
+            )
+
+    return {
+        "keyword_ideas": ideas,
+        "total_ideas": len(ideas),
+        "seed_keywords": seed_keywords,
+        "seed_url": url,
+        "insights": insights,
+    }

{adloop-0.4.2 → adloop-0.5.0}/src/adloop/ads/read.py

@@ -214,9 +214,108 @@ def get_negative_keywords(
     """
 
     rows = execute_query(config, customer_id, query)
+    for row in rows:
+        cid = row.get("campaign.id")
+        crit_id = row.get("campaign_criterion.criterion_id")
+        if cid and crit_id:
+            row["resource_id"] = f"{cid}~{crit_id}"
     return {"negative_keywords": rows, "total_negative_keywords": len(rows)}
 
 
+def get_negative_keyword_lists(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+) -> dict:
+    """List all shared negative keyword lists (SharedSets) in the account.
+
+    Returns each list's ID, name, status, and keyword count. Use this before
+    calling propose_negative_keyword_list to check whether a suitable list
+    already exists and only needs attaching to a new campaign.
+    """
+    from adloop.ads.gaql import execute_query
+
+    query = """
+        SELECT shared_set.id, shared_set.name, shared_set.status,
+               shared_set.member_count, shared_set.resource_name
+        FROM shared_set
+        WHERE shared_set.type = 'NEGATIVE_KEYWORDS'
+          AND shared_set.status != 'REMOVED'
+        ORDER BY shared_set.name
+    """
+
+    rows = execute_query(config, customer_id, query)
+    return {"negative_keyword_lists": rows, "total_lists": len(rows)}
+
+
+def get_negative_keyword_list_keywords(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    shared_set_id: str = "",
+) -> dict:
+    """List the keywords inside a shared negative keyword list.
+
+    shared_set_id: the numeric ID from get_negative_keyword_lists
+    (shared_set.id field).
+    """
+    from adloop.ads.gaql import execute_query
+
+    if not shared_set_id:
+        return {"error": "shared_set_id is required"}
+    if not shared_set_id.isdigit():
+        return {"error": "shared_set_id must be a numeric ID"}
+
+    query = f"""
+        SELECT shared_criterion.keyword.text,
+               shared_criterion.keyword.match_type,
+               shared_criterion.type,
+               shared_set.id, shared_set.name
+        FROM shared_criterion
+        WHERE shared_set.id = {shared_set_id}
+        ORDER BY shared_criterion.keyword.text
+    """
+
+    rows = execute_query(config, customer_id, query)
+    return {
+        "keywords": rows,
+        "total_keywords": len(rows),
+        "shared_set_id": shared_set_id,
+    }
+
+
+def get_negative_keyword_list_campaigns(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    shared_set_id: str = "",
+) -> dict:
+    """List which campaigns a shared negative keyword list is attached to.
+
+    shared_set_id: the numeric ID from get_negative_keyword_lists
+    (shared_set.id field). Omit to return all list-to-campaign attachments.
+    """
+    from adloop.ads.gaql import execute_query
+
+    shared_set_filter = ""
+    if shared_set_id:
+        if not shared_set_id.isdigit():
+            return {"error": "shared_set_id must be a numeric ID"}
+        shared_set_filter = f"AND shared_set.id = {shared_set_id}"
+
+    query = f"""
+        SELECT campaign.id, campaign.name, campaign.status,
+               shared_set.id, shared_set.name
+        FROM campaign_shared_set
+        WHERE campaign_shared_set.status != 'REMOVED'
+          {shared_set_filter}
+        ORDER BY shared_set.name, campaign.name
+    """
+
+    rows = execute_query(config, customer_id, query)
+    return {"attachments": rows, "total_attachments": len(rows)}
+
+
 def get_recommendations(
     config: AdLoopConfig,
     *,

{adloop-0.4.2 → adloop-0.5.0}/src/adloop/ads/write.py

@@ -341,6 +341,61 @@ def add_negative_keywords(
     return plan.to_preview()
 
 
+def propose_negative_keyword_list(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_id: str = "",
+    list_name: str = "",
+    keywords: list[str] | None = None,
+    match_type: str = "EXACT",
+) -> dict:
+    """Draft a shared negative keyword list and attach it to a campaign — returns PREVIEW.
+
+    Creates a reusable negative keyword list (SharedSet) with the given keywords
+    and links it to the campaign. Unlike add_negative_keywords, the list can later
+    be reused across multiple campaigns.
+    Call confirm_and_apply with the returned plan_id to execute.
+    """
+    from adloop.safety.guards import SafetyViolation, check_blocked_operation
+    from adloop.safety.preview import ChangePlan, store_plan
+
+    try:
+        check_blocked_operation("create_negative_keyword_list", config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    keywords = keywords or []
+    match_type = match_type.upper()
+
+    errors = []
+    if not campaign_id:
+        errors.append("campaign_id is required")
+    if not list_name:
+        errors.append("list_name is required")
+    if not keywords:
+        errors.append("At least one keyword is required")
+    if match_type not in _VALID_MATCH_TYPES:
+        errors.append(f"Invalid match_type '{match_type}' — use EXACT, PHRASE, or BROAD")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    plan = ChangePlan(
+        operation="create_negative_keyword_list",
+        entity_type="negative_keyword_list",
+        entity_id=campaign_id,
+        customer_id=customer_id,
+        changes={
+            "campaign_id": campaign_id,
+            "list_name": list_name,
+            "keywords": keywords,
+            "match_type": match_type,
+        },
+    )
+    store_plan(plan)
+    return plan.to_preview()
+
+
 def update_ad_group(
     config: AdLoopConfig,
     *,
@@ -1626,6 +1681,35 @@ def _draft_status_change(
 # ---------------------------------------------------------------------------
 
 
+_MUTATE_RESPONSE_RESULT_FIELDS = [
+    "campaign_budget_result",
+    "campaign_result",
+    "ad_group_result",
+    "ad_group_ad_result",
+    "ad_group_criterion_result",
+    "campaign_criterion_result",
+    "asset_result",
+    "campaign_asset_result",
+    "customer_asset_result",
+]
+
+
+def _extract_resource_name(resp: object) -> str:
+    """Extract the resource_name from a MutateOperationResponse.
+
+    Uses direct field access instead of WhichOneof, which doesn't work on
+    proto-plus wrapped messages returned by the google-ads library.
+    """
+    for field in _MUTATE_RESPONSE_RESULT_FIELDS:
+        try:
+            result = getattr(resp, field, None)
+            if result and result.resource_name:
+                return result.resource_name
+        except Exception:
+            continue
+    return ""
+
+
 def _execute_plan(config: AdLoopConfig, plan: object) -> dict:
     """Dispatch to the right Google Ads mutate call based on plan.operation."""
     from adloop.ads.client import get_ads_client, normalize_customer_id
@@ -1641,6 +1725,7 @@ def _execute_plan(config: AdLoopConfig, plan: object) -> dict:
         "create_responsive_search_ad": _apply_create_rsa,
         "add_keywords": _apply_add_keywords,
         "add_negative_keywords": _apply_add_negative_keywords,
+        "create_negative_keyword_list": _apply_create_negative_keyword_list,
         "pause_entity": _apply_status_change,
         "enable_entity": _apply_status_change,
         "remove_entity": _apply_remove,
@@ -1818,22 +1903,20 @@ def _apply_create_campaign(client: object, cid: str, changes: dict) -> dict:
     num_geo = len(changes.get("geo_target_ids") or [])
     num_lang = len(changes.get("language_ids") or [])
     for i, resp in enumerate(response.mutate_operation_responses):
-        resp_type = resp.WhichOneof("response")
-        if resp_type:
-            inner = getattr(resp, resp_type)
-            resource = getattr(inner, "resource_name", str(inner))
+        rn = _extract_resource_name(resp)
+        if rn:
             if i == 0:
-                results["campaign_budget"] = resource
+                results["campaign_budget"] = rn
             elif i == 1:
-                results["campaign"] = resource
+                results["campaign"] = rn
             elif i == 2:
-                results["ad_group"] = resource
+                results["ad_group"] = rn
             elif i < 3 + num_keywords:
-                results.setdefault("keywords", []).append(resource)
+                results.setdefault("keywords", []).append(rn)
             elif i < 3 + num_keywords + num_geo:
-                results.setdefault("geo_targets", []).append(resource)
+                results.setdefault("geo_targets", []).append(rn)
             else:
-                results.setdefault("language_targets", []).append(resource)
+                results.setdefault("language_targets", []).append(rn)
 
     return results
 
@@ -1874,14 +1957,12 @@ def _apply_create_ad_group(client: object, cid: str, changes: dict) -> dict:
 
     results: dict = {}
     for i, resp in enumerate(response.mutate_operation_responses):
-        resp_type = resp.WhichOneof("response")
-        if resp_type:
-            inner = getattr(resp, resp_type)
-            resource = getattr(inner, "resource_name", str(inner))
+        rn = _extract_resource_name(resp)
+        if rn:
             if i == 0:
-                results["ad_group"] = resource
+                results["ad_group"] = rn
             else:
-                results.setdefault("keywords", []).append(resource)
+                results.setdefault("keywords", []).append(rn)
 
     return results
 
@@ -2039,11 +2120,7 @@ def _apply_update_campaign(client: object, cid: str, changes: dict) -> dict:
 
     results = {"updated": []}
     for resp in response.mutate_operation_responses:
-        rn = (
-            resp.campaign_result.resource_name
-            or resp.campaign_budget_result.resource_name
-            or resp.campaign_criterion_result.resource_name
-        )
+        rn = _extract_resource_name(resp)
         if rn:
             results["updated"].append(rn)
     return results
@@ -2441,3 +2518,77 @@ def _apply_create_sitelinks(client: object, cid: str, changes: dict) -> dict:
         client.enums.AssetFieldTypeEnum.SITELINK,
         populate,
     )
+
+
+def _apply_create_negative_keyword_list(
+    client: object, cid: str, changes: dict
+) -> dict:
+    """Create a shared negative keyword list and attach it to a campaign.
+
+    Executes three sequential API calls. If step 2 or 3 fails, the result
+    includes partial_failure info with the SharedSet resource name so the
+    caller can clean up or retry the remaining steps.
+    """
+    shared_set_resource = None
+
+    # 1. Create the SharedSet
+    shared_set_service = client.get_service("SharedSetService")
+    ss_op = client.get_type("SharedSetOperation")
+    shared_set = ss_op.create
+    shared_set.name = changes["list_name"]
+    shared_set.type_ = client.enums.SharedSetTypeEnum.NEGATIVE_KEYWORDS
+    ss_response = shared_set_service.mutate_shared_sets(
+        customer_id=cid, operations=[ss_op]
+    )
+    shared_set_resource = ss_response.results[0].resource_name
+
+    # 2. Add keywords to the list
+    try:
+        sc_service = client.get_service("SharedCriterionService")
+        sc_ops = []
+        for kw_text in changes["keywords"]:
+            sc_op = client.get_type("SharedCriterionOperation")
+            criterion = sc_op.create
+            criterion.shared_set = shared_set_resource
+            criterion.keyword.text = kw_text
+            criterion.keyword.match_type = getattr(
+                client.enums.KeywordMatchTypeEnum, changes["match_type"]
+            )
+            sc_ops.append(sc_op)
+        sc_service.mutate_shared_criteria(customer_id=cid, operations=sc_ops)
+    except Exception as exc:
+        return {
+            "partial_failure": True,
+            "shared_set_resource": shared_set_resource,
+            "completed_steps": ["create_shared_set"],
+            "failed_step": "add_keywords",
+            "error": _extract_error_message(exc),
+        }
+
+    # 3. Attach the list to the campaign
+    try:
+        css_service = client.get_service("CampaignSharedSetService")
+        css_op = client.get_type("CampaignSharedSetOperation")
+        campaign_shared_set = css_op.create
+        campaign_shared_set.campaign = client.get_service(
+            "CampaignService"
+        ).campaign_path(cid, changes["campaign_id"])
+        campaign_shared_set.shared_set = shared_set_resource
+        css_response = css_service.mutate_campaign_shared_sets(
+            customer_id=cid, operations=[css_op]
+        )
+    except Exception as exc:
+        return {
+            "partial_failure": True,
+            "shared_set_resource": shared_set_resource,
+            "keyword_count": len(changes["keywords"]),
+            "completed_steps": ["create_shared_set", "add_keywords"],
+            "failed_step": "attach_to_campaign",
+            "error": _extract_error_message(exc),
+        }
+
+    return {
+        "shared_set_resource": shared_set_resource,
+        "campaign_shared_set_resource": css_response.results[0].resource_name,
+        "keyword_count": len(changes["keywords"]),
+    }

{adloop-0.4.2 → adloop-0.5.0}/src/adloop/cli.py

@@ -294,16 +294,17 @@ def run_init_wizard() -> None:
     _print()
 
     existing_config = None
+    _original_config_backup: str | None = None
     if _CONFIG_PATH.exists():
         _print(f"  Found existing config at {_CONFIG_PATH}")
         if not _prompt_bool("Overwrite existing configuration?", default=False):
             _print("  Keeping existing config. Exiting.")
             return
+        _original_config_backup = _CONFIG_PATH.read_text()
         try:
             import yaml
 
-            with open(_CONFIG_PATH) as f:
-                existing_config = yaml.safe_load(f) or {}
+            existing_config = yaml.safe_load(_original_config_backup) or {}
         except Exception:
             existing_config = {}
 
@@ -364,7 +365,8 @@ def run_init_wizard() -> None:
     step_num += 1
     _step_header(step_num, "Authorization & Account Discovery")
 
-    # Write a minimal temporary config for OAuth + discovery
+    # Write a temporary config for OAuth + discovery.  If the wizard is
+    # interrupted after this point, _cleanup_on_cancel restores the original.
     _ADLOOP_DIR.mkdir(parents=True, exist_ok=True)
     temp_config_yaml = _generate_config_yaml(
         project_id=project_id,
@@ -378,6 +380,40 @@ def run_init_wizard() -> None:
     )
     _CONFIG_PATH.write_text(temp_config_yaml)
 
+    # Everything below uses the temp config for OAuth and discovery.
+    # If the wizard is interrupted, restore the original config (or remove
+    # the temp) so we never leave a half-baked config on disk.
+    try:
+        _run_wizard_post_config(
+            use_bundled=use_bundled,
+            credentials_path=credentials_path,
+            project_id=project_id,
+            developer_token=developer_token,
+            login_customer_id=login_customer_id,
+            step_num=step_num,
+            _existing=_existing,
+        )
+    except KeyboardInterrupt:
+        if _original_config_backup is not None:
+            _CONFIG_PATH.write_text(_original_config_backup)
+        elif _CONFIG_PATH.exists():
+            _CONFIG_PATH.unlink()
+        raise
+
+
+def _run_wizard_post_config(
+    *,
+    use_bundled: bool,
+    credentials_path: str,
+    project_id: str,
+    developer_token: str,
+    login_customer_id: str,
+    step_num: int,
+    _existing: object,
+) -> None:
+    """Run the wizard steps after the temp config has been written."""
+    from adloop.config import load_config
+
     # Optional: copy custom credentials to ~/.adloop/
     if not use_bundled and credentials_path:
         creds_expanded = Path(credentials_path).expanduser()
@@ -395,13 +431,14 @@ def run_init_wizard() -> None:
     _print()
     oauth_ok = False
     try:
-        from adloop.config import load_config
         from adloop.auth import _oauth_flow
 
         cfg = load_config(str(_CONFIG_PATH))
         _oauth_flow(cfg)
         _print("  ✓ OAuth token saved")
         oauth_ok = True
+    except KeyboardInterrupt:
+        raise
     except Exception as exc:
         _print(f"  ✗ OAuth failed: {exc}")
         _print("    You can retry later — any AdLoop tool call will trigger auth.")
@@ -427,10 +464,12 @@ def run_init_wizard() -> None:
             else:
                 _print("  No GA4 properties found. Enter manually:")
                 property_id = _prompt_property_id()
+        except KeyboardInterrupt:
+            raise
         except Exception as exc:
             _print(f"  Could not auto-discover GA4 properties: {exc}")
             property_id = _prompt_property_id(
-                default=_existing("ga4", "property_id"),
+                default=_existing("ga4", "property_id"),  # type: ignore[operator]
             )
     else:
         step_num += 1
@@ -439,7 +478,7 @@ def run_init_wizard() -> None:
         _print("  → https://analytics.google.com → Admin → Property Settings")
         _print()
         property_id = _prompt_property_id(
-            default=_existing("ga4", "property_id"),
+            default=_existing("ga4", "property_id"),  # type: ignore[operator]
         )
 
     # Auto-discover Ads accounts
@@ -463,18 +502,20 @@ def run_init_wizard() -> None:
             else:
                 _print("  No Ads accounts found. Enter manually:")
                 customer_id = _prompt_customer_id("Ads Customer ID (XXX-XXX-XXXX)")
+        except KeyboardInterrupt:
+            raise
         except Exception as exc:
             _print(f"  Could not auto-discover Ads accounts: {exc}")
             customer_id = _prompt_customer_id(
                 "Ads Customer ID (XXX-XXX-XXXX)",
-                default=_existing("ads", "customer_id"),
+                default=_existing("ads", "customer_id"),  # type: ignore[operator]
             )
     else:
         step_num += 1
         _step_header(step_num, "Google Ads Account")
         customer_id = _prompt_customer_id(
             "Ads Customer ID (XXX-XXX-XXXX)",
-            default=_existing("ads", "customer_id"),
+            default=_existing("ads", "customer_id"),  # type: ignore[operator]
         )
 
     # Safety defaults
@@ -482,7 +523,7 @@ def run_init_wizard() -> None:
     _step_header(step_num, "Safety Defaults")
     budget_str = _prompt(
         "Max daily budget cap (safety limit)",
-        default=str(_existing("safety", "max_daily_budget", "50")),
+        default=str(_existing("safety", "max_daily_budget", "50")),  # type: ignore[operator]
         required=False,
     )
     try:

{adloop-0.4.2 → adloop-0.5.0}/src/adloop/server.py

@@ -393,6 +393,61 @@ def get_negative_keywords(
     )
 
 
+@mcp.tool(annotations=_READONLY)
+@_safe
+def get_negative_keyword_lists(
+    customer_id: str = "",
+) -> dict:
+    """List all shared negative keyword lists (SharedSets) in the account.
+
+    Returns each list's ID, name, status, and keyword count. Always call
+    this before propose_negative_keyword_list to avoid creating duplicates —
+    a suitable list may already exist and just need attaching to a campaign.
+    """
+    from adloop.ads.read import get_negative_keyword_lists as _impl
+
+    return _impl(_config, customer_id=customer_id or _config.ads.customer_id)
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def get_negative_keyword_list_keywords(
+    shared_set_id: str,
+    customer_id: str = "",
+) -> dict:
+    """List the keywords inside a shared negative keyword list.
+
+    shared_set_id: numeric ID from get_negative_keyword_lists (shared_set.id).
+    """
+    from adloop.ads.read import get_negative_keyword_list_keywords as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        shared_set_id=shared_set_id,
+    )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def get_negative_keyword_list_campaigns(
+    shared_set_id: str = "",
+    customer_id: str = "",
+) -> dict:
+    """List which campaigns a shared negative keyword list is attached to.
+
+    shared_set_id: numeric ID from get_negative_keyword_lists. Omit to see
+    all list-to-campaign attachments across the account.
+    """
+    from adloop.ads.read import get_negative_keyword_list_campaigns as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        shared_set_id=shared_set_id,
+    )
+
+
 # ---------------------------------------------------------------------------
 # Google Ads — Recommendations, Performance Max & Audience Tools
 # ---------------------------------------------------------------------------
@@ -896,6 +951,34 @@ def add_negative_keywords(
     )
 
 
+@mcp.tool(annotations=_WRITE)
+@_safe
+def propose_negative_keyword_list(
+    campaign_id: str,
+    list_name: str,
+    keywords: list[str],
+    customer_id: str = "",
+    match_type: str = "EXACT",
+) -> dict:
+    """Draft a shared negative keyword list and attach it to a campaign — returns a PREVIEW.
+
+    Creates a reusable negative keyword list that can later be applied to multiple
+    campaigns, unlike add_negative_keywords which adds directly to one campaign.
+    match_type: "EXACT", "PHRASE", or "BROAD"
+    Call confirm_and_apply with the returned plan_id to execute.
+    """
+    from adloop.ads.write import propose_negative_keyword_list as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        campaign_id=campaign_id,
+        list_name=list_name,
+        keywords=keywords,
+        match_type=match_type,
+    )
+
+
 @mcp.tool(annotations=_WRITE)
 @_safe
 def update_ad_group(
@@ -1039,7 +1122,8 @@ def remove_entity(
                  "campaign_asset", "asset", or "customer_asset"
     entity_id: The resource ID.
                For keywords: "adGroupId~criterionId"
-               For negative_keywords: the campaign criterion ID
+               For negative_keywords: "campaignId~criterionId"
+                   (use the resource_id field from get_negative_keywords)
                For campaign_asset: "campaignId~assetId~fieldType"
                For asset: simple asset ID
                For customer_asset: "assetId~fieldType"
@@ -1211,3 +1295,40 @@ def estimate_budget(
         forecast_days=forecast_days,
         customer_id=customer_id or _config.ads.customer_id,
     )
+
+
+@mcp.tool(annotations=_READONLY)
+@_safe
+def discover_keywords(
+    seed_keywords: list[str] = [],  # noqa: B006 — mutable default required for MCP JSON schema
+    url: str = "",
+    geo_target_id: str = "2276",
+    language_id: str = "1000",
+    page_size: int = 50,
+    customer_id: str = "",
+) -> dict:
+    """Discover new keyword ideas using Google Ads Keyword Planner.
+
+    Mirrors the "Discover new keywords" UI in Keyword Planner:
+    - Start with keywords: pass seed_keywords (e.g. ["running shoes"])
+    - Start with a website: pass url (e.g. "https://example.com/products")
+    - Both together: keywords + url for more targeted ideas
+
+    Returns keyword ideas sorted by avg monthly search volume, with
+    competition level (LOW/MEDIUM/HIGH) and top-of-page bid range.
+
+    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 keyword ideas to return (default 50, max 1000)
+    """
+    from adloop.ads.forecast import discover_keywords as _impl
+
+    return _impl(
+        _config,
+        seed_keywords=seed_keywords,
+        url=url,
+        geo_target_id=geo_target_id,
+        language_id=language_id,
+        page_size=page_size,
+        customer_id=customer_id or _config.ads.customer_id,
+    )

adloop-0.4.2/src/adloop/ads/client.py

@@ -1,41 +0,0 @@
-"""Google Ads API client wrapper — thin layer over the google-ads library."""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from google.ads.googleads.client import GoogleAdsClient
-
-    from adloop.config import AdLoopConfig
-
-# 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"
-
-
-def get_ads_client(config: AdLoopConfig) -> GoogleAdsClient:
-    """Return an authenticated Google Ads API client pinned to a specific API version."""
-    from google.ads.googleads.client import GoogleAdsClient
-
-    from adloop.auth import get_ads_credentials
-
-    credentials = get_ads_credentials(config)
-
-    client_config = {
-        "developer_token": config.ads.developer_token,
-        "use_proto_plus": True,
-        "version": GOOGLE_ADS_API_VERSION,
-    }
-
-    if config.ads.login_customer_id:
-        client_config["login_customer_id"] = config.ads.login_customer_id.replace("-", "")
-
-    client = GoogleAdsClient(credentials=credentials, **client_config)
-    return client
-
-
-def normalize_customer_id(customer_id: str) -> str:
-    """Strip dashes from customer ID for API calls (123-456-7890 -> 1234567890)."""
-    return customer_id.replace("-", "")