adloop 0.5.2__tar.gz → 0.6.1__tar.gz

{adloop-0.5.2 → adloop-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.5.2
+Version: 0.6.1
 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
@@ -216,6 +216,11 @@ uv run adloop init
 
 The `adloop init` wizard walks you through everything. AdLoop ships with built-in Google OAuth credentials, so you don't need to create a Google Cloud project.
 
+> **⚠️ Built-in credentials temporarily unavailable — Google verification pending.**
+> Google limits unverified OAuth apps to 100 users. AdLoop has reached that cap while awaiting Google's app verification. Until verification is complete, the built-in credentials will show a **"This app is blocked"** error for new users.
+>
+> **Workaround:** set up your own Google Cloud project using the [Advanced Setup](#advanced-setup-custom-google-cloud-project) instructions below (takes ~5 minutes). Your own project has no user cap and is the recommended setup path in the meantime.
+
 The wizard:
 
 1. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
@@ -390,7 +395,7 @@ What's been shipped and what's next:
 - ~~Setup wizard (`adloop init`)~~ ✓
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - ~~PyPI package~~ ✓ — `pip install adloop`
-- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required, auto-discovery of GA4/Ads accounts
+- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required, auto-discovery of GA4/Ads accounts (currently capped at 100 users pending Google verification — use [Advanced Setup](#advanced-setup-custom-google-cloud-project) in the meantime)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter

{adloop-0.5.2 → adloop-0.6.1}/README.md

@@ -192,6 +192,11 @@ uv run adloop init
 
 The `adloop init` wizard walks you through everything. AdLoop ships with built-in Google OAuth credentials, so you don't need to create a Google Cloud project.
 
+> **⚠️ Built-in credentials temporarily unavailable — Google verification pending.**
+> Google limits unverified OAuth apps to 100 users. AdLoop has reached that cap while awaiting Google's app verification. Until verification is complete, the built-in credentials will show a **"This app is blocked"** error for new users.
+>
+> **Workaround:** set up your own Google Cloud project using the [Advanced Setup](#advanced-setup-custom-google-cloud-project) instructions below (takes ~5 minutes). Your own project has no user cap and is the recommended setup path in the meantime.
+
 The wizard:
 
 1. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
@@ -366,7 +371,7 @@ What's been shipped and what's next:
 - ~~Setup wizard (`adloop init`)~~ ✓
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - ~~PyPI package~~ ✓ — `pip install adloop`
-- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required, auto-discovery of GA4/Ads accounts
+- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required, auto-discovery of GA4/Ads accounts (currently capped at 100 users pending Google verification — use [Advanced Setup](#advanced-setup-custom-google-cloud-project) in the meantime)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter

{adloop-0.5.2 → adloop-0.6.1}/pyproject.toml

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

{adloop-0.5.2 → adloop-0.6.1}/src/adloop/__init__.py

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

{adloop-0.5.2 → adloop-0.6.1}/src/adloop/ads/read.py

@@ -10,16 +10,25 @@ if TYPE_CHECKING:
     from adloop.config import AdLoopConfig
 
 
-def list_accounts(config: AdLoopConfig) -> dict:
-    """List all accessible Google Ads accounts."""
+def list_accounts(config: AdLoopConfig, *, limit: int = 50) -> dict:
+    """List accessible Google Ads accounts, up to *limit* entries.
+
+    The default of 50 is intentionally conservative: on large agency MCCs
+    (100+ accounts) returning the full list as a single MCP tool response
+    can trip per-response timeouts or size caps on some MCP hosts. Raise
+    *limit* when you explicitly want more, or use the customer_id parameter
+    on individual tools (get_campaign_performance, run_gaql, etc.) to query
+    a specific account directly without enumerating all of them.
+    """
     from adloop.ads.gaql import execute_query
 
     mcc_id = config.ads.login_customer_id
     if mcc_id:
-        query = """
+        query = f"""
             SELECT customer_client.id, customer_client.descriptive_name,
                    customer_client.status, customer_client.manager
             FROM customer_client
+            LIMIT {int(limit) + 1}
         """
         rows = execute_query(config, mcc_id, query)
     else:
@@ -31,7 +40,19 @@ def list_accounts(config: AdLoopConfig) -> dict:
         """
         rows = execute_query(config, config.ads.customer_id, query)
 
-    return {"accounts": rows, "total_accounts": len(rows)}
+    truncated = len(rows) > limit
+    if truncated:
+        rows = rows[:limit]
+
+    result: dict = {"accounts": rows, "total_accounts": len(rows)}
+    if truncated:
+        result["truncated"] = True
+        result["note"] = (
+            f"Returned the first {limit} accounts. Call list_accounts with a higher "
+            f"limit to see more, or pass customer_id directly to other tools to "
+            f"query a specific account without enumerating all of them."
+        )
+    return result
 
 
 def get_campaign_performance(
@@ -267,7 +288,8 @@ def get_negative_keyword_list_keywords(
         return {"error": "shared_set_id must be a numeric ID"}
 
     query = f"""
-        SELECT shared_criterion.keyword.text,
+        SELECT shared_criterion.criterion_id,
+               shared_criterion.keyword.text,
                shared_criterion.keyword.match_type,
                shared_criterion.type,
                shared_set.id, shared_set.name
@@ -277,6 +299,11 @@ def get_negative_keyword_list_keywords(
     """
 
     rows = execute_query(config, customer_id, query)
+    for row in rows:
+        ssid = row.get("shared_set.id")
+        crit_id = row.get("shared_criterion.criterion_id")
+        if ssid and crit_id:
+            row["resource_id"] = f"{ssid}~{crit_id}"
     return {
         "keywords": rows,
         "total_keywords": len(rows),

{adloop-0.5.2 → adloop-0.6.1}/src/adloop/ads/write.py

@@ -396,6 +396,77 @@ def propose_negative_keyword_list(
     return plan.to_preview()
 
 
+def add_to_negative_keyword_list(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    shared_set_id: str = "",
+    keywords: list[str] | None = None,
+    match_type: str = "EXACT",
+) -> dict:
+    """Draft adding keywords to an existing shared negative keyword list — returns PREVIEW.
+
+    Unlike ``propose_negative_keyword_list`` (which creates a NEW list), this
+    appends keywords to an existing SharedSet identified by ``shared_set_id``.
+    Use ``get_negative_keyword_lists`` to find the list's ID. 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("add_to_negative_keyword_list", config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    keywords = keywords or []
+    match_type = match_type.upper()
+
+    errors = []
+    if not shared_set_id:
+        errors.append("shared_set_id is required")
+    elif not str(shared_set_id).isdigit():
+        errors.append("shared_set_id must be a numeric ID (from get_negative_keyword_lists)")
+    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}
+
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for kw in keywords:
+        text = kw.strip()
+        if not text:
+            continue
+        key = text.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(text)
+
+    if not deduped:
+        return {
+            "error": "Validation failed",
+            "details": ["At least one non-empty keyword is required"],
+        }
+
+    plan = ChangePlan(
+        operation="add_to_negative_keyword_list",
+        entity_type="negative_keyword_list",
+        entity_id=str(shared_set_id),
+        customer_id=customer_id,
+        changes={
+            "shared_set_id": str(shared_set_id),
+            "keywords": deduped,
+            "match_type": match_type,
+        },
+    )
+    store_plan(plan)
+    return plan.to_preview()
+
+
 def update_ad_group(
     config: AdLoopConfig,
     *,
@@ -484,11 +555,26 @@ def remove_entity(
     entity_type: str = "",
     entity_id: str = "",
 ) -> dict:
-    """Draft removing an entity (keyword, negative_keyword, ad, ad_group, campaign).
+    """Draft removing an entity — returns preview.
+
+    Supported ``entity_type`` values: ``campaign``, ``ad_group``, ``ad``,
+    ``keyword``, ``negative_keyword``, ``shared_criterion``, ``campaign_asset``,
+    ``asset``, ``customer_asset``.
+
+    Composite ``entity_id`` formats:
+
+    - ``keyword``: ``adGroupId~criterionId``
+    - ``negative_keyword``: ``campaignId~criterionId`` (use the ``resource_id``
+      field from ``get_negative_keywords``)
+    - ``shared_criterion``: ``sharedSetId~criterionId`` (use the ``resource_id``
+      field from ``get_negative_keyword_list_keywords``)
+    - ``campaign_asset``: ``campaignId~assetId~fieldType``
+    - ``customer_asset``: ``assetId~fieldType``
+    - ``asset``: bare asset ID
 
     This is a DESTRUCTIVE operation — removed entities cannot be re-enabled.
-    For keywords and negative keywords, this fully deletes the criterion.
-    Returns a preview; call confirm_and_apply to execute.
+    Prefer ``pause_entity`` unless the user explicitly wants permanent removal.
+    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
@@ -1167,6 +1253,7 @@ _VALID_MATCH_TYPES = {"EXACT", "PHRASE", "BROAD"}
 _VALID_ENTITY_TYPES = {"campaign", "ad_group", "ad", "keyword"}
 _REMOVABLE_ENTITY_TYPES = _VALID_ENTITY_TYPES | {
     "negative_keyword", "campaign_asset", "asset", "customer_asset",
+    "shared_criterion",
 }
 
 _SMART_BIDDING_STRATEGIES = {
@@ -1726,6 +1813,7 @@ def _execute_plan(config: AdLoopConfig, plan: object) -> dict:
         "add_keywords": _apply_add_keywords,
         "add_negative_keywords": _apply_add_negative_keywords,
         "create_negative_keyword_list": _apply_create_negative_keyword_list,
+        "add_to_negative_keyword_list": _apply_add_to_negative_keyword_list,
         "pause_entity": _apply_status_change,
         "enable_entity": _apply_status_change,
         "remove_entity": _apply_remove,
@@ -2282,6 +2370,19 @@ def _apply_remove(
             customer_id=cid, operations=[operation]
         )
 
+    elif entity_type == "shared_criterion":
+        if "~" not in entity_id:
+            raise ValueError(
+                f"shared_criterion entity_id must be "
+                f"'sharedSetId~criterionId', got '{entity_id}'"
+            )
+        service = client.get_service("SharedCriterionService")
+        operation = client.get_type("SharedCriterionOperation")
+        operation.remove = f"customers/{cid}/sharedCriteria/{entity_id}"
+        response = service.mutate_shared_criteria(
+            customer_id=cid, operations=[operation]
+        )
+
     elif entity_type == "campaign_asset":
         parts = entity_id.split("~")
         if len(parts) != 3:
@@ -2599,3 +2700,34 @@ def _apply_create_negative_keyword_list(
         "campaign_shared_set_resource": css_response.results[0].resource_name,
         "keyword_count": len(changes["keywords"]),
     }
+
+
+def _apply_add_to_negative_keyword_list(
+    client: object, cid: str, changes: dict
+) -> dict:
+    """Append keywords to an existing shared negative keyword list."""
+    shared_set_service = client.get_service("SharedSetService")
+    shared_set_resource = shared_set_service.shared_set_path(
+        cid, changes["shared_set_id"]
+    )
+
+    sc_service = client.get_service("SharedCriterionService")
+    operations = []
+    for kw_text in changes["keywords"]:
+        op = client.get_type("SharedCriterionOperation")
+        criterion = op.create
+        criterion.shared_set = shared_set_resource
+        criterion.keyword.text = kw_text
+        criterion.keyword.match_type = getattr(
+            client.enums.KeywordMatchTypeEnum, changes["match_type"]
+        )
+        operations.append(op)
+
+    response = sc_service.mutate_shared_criteria(
+        customer_id=cid, operations=operations
+    )
+    return {
+        "shared_set_resource": shared_set_resource,
+        "resource_names": [r.resource_name for r in response.results],
+        "keyword_count": len(response.results),
+    }

{adloop-0.5.2 → adloop-0.6.1}/src/adloop/server.py

@@ -147,11 +147,21 @@ def health_check() -> dict:
             status["ga4_error_details"] = parsed["details"]
 
     try:
-        from adloop.ads.read import list_accounts as _ads_test
-
-        result = _ads_test(_config)
+        from adloop.ads.gaql import execute_query
+
+        # Minimal probe — one row is enough to confirm OAuth, developer token,
+        # and API reachability. We deliberately avoid enumerating customer_client
+        # here: on large MCCs (100+ accounts) that call can take multiple seconds
+        # and its size/latency is the likely culprit when the MCP host kills the
+        # connection shortly after health_check. Call list_accounts explicitly
+        # if a count or listing is actually needed.
+        mcc_id = _config.ads.login_customer_id or _config.ads.customer_id
+        execute_query(
+            _config,
+            mcc_id,
+            "SELECT customer.id, customer.descriptive_name FROM customer LIMIT 1",
+        )
         status["ads"] = "ok"
-        status["ads_accounts"] = result.get("total_accounts", 0)
     except Exception as e:
         parsed = _structured_error("health_check", e)
         status["ads"] = "error"
@@ -273,15 +283,17 @@ def get_tracking_events(
 
 @mcp.tool(annotations=_READONLY)
 @_safe
-def list_accounts() -> dict:
-    """List all accessible Google Ads accounts.
+def list_accounts(limit: int = 50) -> dict:
+    """List accessible Google Ads accounts.
 
-    Returns account names, IDs, and status. Use this to discover
-    which accounts are available before running performance queries.
+    Returns account names, IDs, and status. The default cap of 50 keeps the
+    response small on large agency MCCs — raise *limit* if you actually need
+    more. For most workflows you don't need to list accounts at all: pass
+    customer_id directly to get_campaign_performance, run_gaql, etc.
     """
     from adloop.ads.read import list_accounts as _impl
 
-    return _impl(_config)
+    return _impl(_config, limit=limit)
 
 
 @mcp.tool(annotations=_READONLY)
@@ -979,6 +991,39 @@ def propose_negative_keyword_list(
     )
 
 
+@mcp.tool(annotations=_WRITE)
+@_safe
+def add_to_negative_keyword_list(
+    shared_set_id: str,
+    keywords: list[str],
+    customer_id: str = "",
+    match_type: str = "EXACT",
+) -> dict:
+    """Append keywords to an EXISTING shared negative keyword list — returns a PREVIEW.
+
+    Use this when a suitable list already exists and only needs more keywords
+    (instead of propose_negative_keyword_list, which creates a new list).
+    Always call get_negative_keyword_lists first to find the right shared_set_id
+    and get_negative_keyword_list_keywords to avoid duplicating existing terms.
+
+    shared_set_id: numeric ID from get_negative_keyword_lists (shared_set.id).
+    keywords: list of keyword strings to append (duplicates in the input list
+        are collapsed).
+    match_type: "EXACT", "PHRASE", or "BROAD"
+
+    Call confirm_and_apply with the returned plan_id to execute.
+    """
+    from adloop.ads.write import add_to_negative_keyword_list as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        shared_set_id=shared_set_id,
+        keywords=keywords,
+        match_type=match_type,
+    )
+
+
 @mcp.tool(annotations=_WRITE)
 @_safe
 def update_ad_group(
@@ -1119,11 +1164,13 @@ def remove_entity(
     """Draft REMOVING an entity — returns a PREVIEW. This is IRREVERSIBLE.
 
     entity_type: "campaign", "ad_group", "ad", "keyword", "negative_keyword",
-                 "campaign_asset", "asset", or "customer_asset"
+                 "shared_criterion", "campaign_asset", "asset", or "customer_asset"
     entity_id: The resource ID.
                For keywords: "adGroupId~criterionId"
                For negative_keywords: "campaignId~criterionId"
                    (use the resource_id field from get_negative_keywords)
+               For shared_criterion: "sharedSetId~criterionId"
+                   (use the resource_id field from get_negative_keyword_list_keywords)
                For campaign_asset: "campaignId~assetId~fieldType"
                For asset: simple asset ID
                For customer_asset: "assetId~fieldType"