adloop 0.4.3__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.4.3
+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)
@@ -322,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."*
 
@@ -347,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
@@ -358,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
@@ -378,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.3 → 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)
@@ -298,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."*
 
@@ -323,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
@@ -334,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
@@ -354,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.3 → adloop-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.4.3"
+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.3 → adloop-0.5.0}/src/adloop/__init__.py

@@ -2,7 +2,7 @@
 
 import sys
 
-__version__ = "0.4.3"
+__version__ = "0.5.0"
 
 
 def main() -> None:

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.3 → 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.3 → adloop-0.5.0}/src/adloop/ads/read.py

@@ -222,6 +222,100 @@ def get_negative_keywords(
     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.3 → 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,
     *,
@@ -1670,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,
@@ -2462,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.3 → 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(
@@ -1212,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.3/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("-", "")