adloop 0.6.0__tar.gz → 0.6.2__tar.gz

{adloop-0.6.0 → adloop-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.6.0
+Version: 0.6.2
 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.6.0 → adloop-0.6.2}/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.6.0 → adloop-0.6.2}/pyproject.toml

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

{adloop-0.6.0 → adloop-0.6.2}/src/adloop/__init__.py

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

{adloop-0.6.0 → adloop-0.6.2}/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(

adloop-0.6.2/src/adloop/diagnostics.py

@@ -0,0 +1,213 @@
+"""Optional diagnostic instrumentation for debugging MCP host disconnects.
+
+Activated only when the environment variable ``ADLOOP_DEBUG`` is set to a
+truthy value (``1``, ``true``, ``yes``). Otherwise all hooks are no-ops and
+impose no runtime cost.
+
+When enabled, this module emits structured ``[adloop-debug]`` lines to
+**stderr** (never stdout — stdout is the MCP channel). The output is designed
+to answer a specific question: when the MCP server process disappears without
+a Python exception, did it exit via signal, EOF on stdin, or SIGKILL?
+
+Emitted events:
+
+- ``started`` — once, at server startup, including pid and python version.
+- ``heartbeat`` — every ``ADLOOP_HEARTBEAT_SECONDS`` (default 30s) with uptime,
+  time since last tool call, and peak RSS.
+- ``tool_start`` / ``tool_end`` — bracketing every MCP tool invocation, with
+  the tool name and duration.
+- ``signal`` — on SIGTERM/SIGHUP/SIGINT/SIGPIPE, immediately before the signal
+  propagates to Python's default handler (which then terminates the process).
+- ``atexit`` — if the interpreter shuts down normally.
+
+If stderr goes silent between two heartbeats and no ``signal`` or ``atexit``
+line appears, the process was SIGKILL'd or the stdio pipe was torn down
+without giving Python a chance to run handlers. That's the diagnostic signal
+we care about.
+"""
+
+from __future__ import annotations
+
+import atexit
+import functools
+import os
+import signal
+import sys
+import threading
+import time
+from typing import Callable
+
+_ENABLED = os.getenv("ADLOOP_DEBUG", "").lower() in ("1", "true", "yes", "on")
+_HEARTBEAT_SECONDS = int(os.getenv("ADLOOP_HEARTBEAT_SECONDS", "30") or "30")
+
+_start_time: float = time.monotonic()
+_last_activity_time: float = time.monotonic()
+_last_activity_label: str = "startup"
+_activity_lock = threading.Lock()
+
+
+def enabled() -> bool:
+    """Return True if debug diagnostics are active."""
+    return _ENABLED
+
+
+def _uptime() -> float:
+    return time.monotonic() - _start_time
+
+
+def _time_since_activity() -> float:
+    return time.monotonic() - _last_activity_time
+
+
+def _rss_mb() -> float | None:
+    """Return peak resident set size in MB, or None if unavailable."""
+    try:
+        import resource
+
+        rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    except Exception:
+        return None
+    # macOS reports bytes, Linux reports kilobytes.
+    if sys.platform == "darwin":
+        return rss / (1024.0 * 1024.0)
+    return rss / 1024.0
+
+
+def _emit(event: str, **fields: object) -> None:
+    """Write a single diagnostic line to stderr (never stdout)."""
+    parts = [f"[adloop-debug] event={event}", f"uptime={_uptime():.2f}s"]
+    for k, v in fields.items():
+        if isinstance(v, float):
+            parts.append(f"{k}={v:.2f}")
+        else:
+            parts.append(f"{k}={v}")
+    try:
+        sys.stderr.write(" ".join(parts) + "\n")
+        sys.stderr.flush()
+    except Exception:
+        # Stderr might be closed during shutdown — never raise from the logger.
+        pass
+
+
+def mark_activity(label: str) -> None:
+    """Record that the server produced or started handling traffic."""
+    if not _ENABLED:
+        return
+    global _last_activity_time, _last_activity_label
+    with _activity_lock:
+        _last_activity_time = time.monotonic()
+        _last_activity_label = label
+
+
+def wrap_tool(fn: Callable) -> Callable:
+    """Wrap an MCP tool callable so its start/end events are logged.
+
+    No-op when diagnostics are disabled, so there's zero overhead in production.
+    """
+    if not _ENABLED:
+        return fn
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        name = getattr(fn, "__name__", "tool")
+        t0 = time.monotonic()
+        mark_activity(f"tool_start:{name}")
+        _emit("tool_start", tool=name)
+        try:
+            result = fn(*args, **kwargs)
+            return result
+        finally:
+            dt = time.monotonic() - t0
+            mark_activity(f"tool_end:{name}")
+            _emit("tool_end", tool=name, duration_s=dt)
+
+    return wrapper
+
+
+def _heartbeat_loop() -> None:
+    """Daemon thread that emits a periodic liveness line."""
+    while True:
+        time.sleep(_HEARTBEAT_SECONDS)
+        try:
+            _emit(
+                "heartbeat",
+                idle_s=_time_since_activity(),
+                last_activity=_last_activity_label,
+                rss_mb=_rss_mb() if _rss_mb() is not None else "unknown",
+            )
+        except Exception:
+            return
+
+
+def _install_signal_handlers() -> None:
+    """Log signal receipt, then let Python's default handler take over.
+
+    We can't meaningfully prevent termination; the goal is only to prove that
+    a signal was received (vs. silent SIGKILL or EOF).
+    """
+    def make_handler(signum: int):
+        def handler(_signum, _frame):
+            try:
+                name = signal.Signals(signum).name
+            except Exception:
+                name = str(signum)
+            _emit(
+                "signal",
+                name=name,
+                idle_s=_time_since_activity(),
+                last_activity=_last_activity_label,
+                rss_mb=_rss_mb() if _rss_mb() is not None else "unknown",
+            )
+            # Restore default behavior and re-raise the signal against ourselves
+            # so termination semantics (exit code, core dump, etc.) are preserved.
+            signal.signal(signum, signal.SIG_DFL)
+            os.kill(os.getpid(), signum)
+
+        return handler
+
+    for sig in (signal.SIGTERM, signal.SIGHUP, signal.SIGINT, signal.SIGPIPE):
+        try:
+            signal.signal(sig, make_handler(sig))
+        except (ValueError, OSError):
+            # Some signals can't be installed from non-main threads or on
+            # certain platforms — skip silently.
+            pass
+
+
+def _install_atexit() -> None:
+    def _on_exit():
+        _emit(
+            "atexit",
+            idle_s=_time_since_activity(),
+            last_activity=_last_activity_label,
+            rss_mb=_rss_mb() if _rss_mb() is not None else "unknown",
+        )
+
+    atexit.register(_on_exit)
+
+
+def install() -> None:
+    """Enable all diagnostic hooks. Safe to call multiple times (idempotent)."""
+    if not _ENABLED:
+        return
+
+    if getattr(install, "_installed", False):
+        return
+    install._installed = True  # type: ignore[attr-defined]
+
+    _emit(
+        "started",
+        pid=os.getpid(),
+        python=sys.version.split()[0],
+        heartbeat_s=_HEARTBEAT_SECONDS,
+        platform=sys.platform,
+    )
+    _install_signal_handlers()
+    _install_atexit()
+
+    thread = threading.Thread(
+        target=_heartbeat_loop,
+        name="adloop-debug-heartbeat",
+        daemon=True,
+    )
+    thread.start()

{adloop-0.6.0 → adloop-0.6.2}/src/adloop/server.py

@@ -8,8 +8,11 @@ from typing import Callable
 from fastmcp import FastMCP
 from mcp.types import ToolAnnotations
 
+from adloop import diagnostics
 from adloop.config import load_config
 
+diagnostics.install()
+
 _READONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False)
 _WRITE = ToolAnnotations(readOnlyHint=False, destructiveHint=False)
 _DESTRUCTIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=True)
@@ -82,7 +85,12 @@ def _structured_error(fn_name: str, exc: Exception) -> dict:
 
 
 def _safe(fn: Callable) -> Callable:
-    """Wrap a tool function so exceptions return structured error dicts."""
+    """Wrap a tool function so exceptions return structured error dicts.
+
+    When ``ADLOOP_DEBUG`` is set, the resulting callable is additionally
+    instrumented via :mod:`adloop.diagnostics` to emit tool_start/tool_end
+    events and update the last-activity timestamp.
+    """
 
     @functools.wraps(fn)
     def wrapper(*args, **kwargs):
@@ -93,7 +101,7 @@ def _safe(fn: Callable) -> Callable:
         except Exception as e:
             return _structured_error(fn.__name__, e)
 
-    return wrapper
+    return diagnostics.wrap_tool(wrapper)
 
 # ---------------------------------------------------------------------------
 # Health Check
@@ -147,11 +155,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 +291,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)
@@ -1367,3 +1387,19 @@ def discover_keywords(
         page_size=page_size,
         customer_id=customer_id or _config.ads.customer_id,
     )
+
+
+# ---------------------------------------------------------------------------
+# Optional local-only debug tools (not shipped in git).
+# ---------------------------------------------------------------------------
+# Activated by ``ADLOOP_DEBUG_TOOLS=1``. The module file is .gitignored and
+# only present on developer machines doing MCP-host stress testing.
+
+import os as _os  # noqa: E402
+
+if _os.getenv("ADLOOP_DEBUG_TOOLS", "").lower() in ("1", "true", "yes", "on"):
+    try:
+        from adloop import _debug_tools  # noqa: F401
+    except ImportError:
+        # _debug_tools.py is intentionally absent in released builds.
+        pass