adloop 0.22.0__tar.gz → 0.22.2__tar.gz

{adloop-0.22.0 → adloop-0.22.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.22.0
+Version: 0.22.2
 Summary: The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,reddit-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose

{adloop-0.22.0 → adloop-0.22.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.22.0"
+version = "0.22.2"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 requires-python = ">=3.11"

{adloop-0.22.0 → adloop-0.22.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.22.0"
+version = "0.22.2"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [

{adloop-0.22.0 → adloop-0.22.2}/src/adloop/gsc/reports.py

@@ -101,9 +101,13 @@ def run_gsc_report(
         site_url = config.gsc.site_url
 
     if not site_url:
+        from adloop.runtime import default_setting_hint
+
         return {
-            "error": "site_url is required. Pass it as an argument or set "
-                     "gsc.site_url in ~/.adloop/config.yaml."
+            "error": "site_url is required. Pass it as an argument (see "
+                     "list_gsc_sites) or "
+                     + default_setting_hint("gsc.site_url", "Settings → Google & accounts")
+                     + "."
         }
 
     dimensions = [_normalize_dimension(d) for d in (dimensions or ["query"])]

{adloop-0.22.0 → adloop-0.22.2}/src/adloop/merchant/read.py

@@ -126,6 +126,8 @@ def get_merchant_feed_health(
 
     account_id = str(account_id or "").strip() or config.merchant.account_id.strip()
     if not account_id:
+        from adloop.runtime import default_setting_hint
+
         return {
             "error": (
                 "account_id is required: no Merchant Center account was "
@@ -133,8 +135,9 @@ def get_merchant_feed_health(
             ),
             "hint": (
                 "Call list_merchant_accounts to find the numeric Merchant "
-                "Center ID and pass it as account_id, or set "
-                "merchant.account_id in the config to make it the default."
+                "Center ID and pass it as account_id, or "
+                + default_setting_hint("merchant.account_id", "Settings → Google & accounts")
+                + "."
             ),
         }
     if not account_id.isdigit():

{adloop-0.22.0 → adloop-0.22.2}/src/adloop/reddit/read.py

@@ -103,9 +103,13 @@ def resolve_account(config: AdLoopConfig, ad_account_id: str = "") -> str:
     """Explicit id wins, then ``reddit.ad_account_id`` from the config."""
     account = (ad_account_id or config.reddit.ad_account_id or "").strip()
     if not account:
+        from adloop.runtime import default_setting_hint
+
         raise ValueError(
-            "ad_account_id is required — pass it explicitly (see "
-            "list_reddit_accounts) or set reddit.ad_account_id in the config."
+            "ad_account_id is required: pass it explicitly (see "
+            "list_reddit_accounts) or "
+            + default_setting_hint("reddit.ad_account_id", "Settings → Reddit Ads")
+            + "."
         )
     return account
 

{adloop-0.22.0 → adloop-0.22.2}/src/adloop/rules/adloop.md

@@ -14,6 +14,8 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog
 |------|-------------|----------------|
 | `health_check` | First thing to run when tools are failing — tests OAuth token, GA4, Ads, and (when configured) Reddit Ads connectivity | (none) |
 
+**A tool you expect is missing?** Apps such as claude.ai, ChatGPT and Perplexity cache AdLoop's tool list from when the connection was made. `health_check` returns `adloop_version` and `tools_offered`, the tools this server offers to you. If the user asks for something a tool in `tools_offered` does and that tool isn't in your own tool list, don't improvise with other tools: tell the user their app shows an older list and to refresh the AdLoop connection (claude.ai: Settings → Connectors → AdLoop; ChatGPT: the AdLoop plugin's settings; Perplexity: remove and add the connector again; coding agents: reconnect the MCP server or start a new session).
+
 **GA4 has two surfaces in health_check:** `ga4_admin` (listing properties) and `ga4_data` (every report). `ga4_data: error` with `SERVICE_DISABLED` means the Google Analytics Data API is not enabled in the Google Cloud project — tell the user to enable it; it is not a permissions or consent problem.
 
 **If health_check reports Google auth errors:** Tell the user to delete `~/.adloop/token.json` and re-run any tool to trigger re-authorization. If tokens keep expiring weekly, the GCP consent screen needs to be published from "Testing" to "In production". **Reddit auth errors** (`REDDIT_INVALID_GRANT`, `REDDIT_NOT_CONNECTED`) are fixed by re-running the Reddit step of `adloop init` (self-hosted) or reconnecting under Settings → Reddit Ads (AdLoop Cloud); the Google token is unrelated.

{adloop-0.22.0 → adloop-0.22.2}/src/adloop/runtime.py

@@ -26,7 +26,7 @@ from __future__ import annotations
 import threading
 from contextlib import contextmanager
 from contextvars import ContextVar
-from typing import TYPE_CHECKING, Iterator, Literal
+from typing import TYPE_CHECKING, Callable, Iterable, Iterator, Literal
 
 if TYPE_CHECKING:
     from adloop.config import AdLoopConfig
@@ -46,6 +46,38 @@ _default_config_lock = threading.Lock()
 _deployment_mode: DeploymentMode = "local"
 
 
+# Which registered tools the current caller is actually offered, given each
+# tool's tags. Self-hosted, every enabled tool is; a hosted runtime narrows it
+# per request (a key's toolsets, tools it cannot serve) so health_check can
+# report the same list the caller's tools/list shows.
+ToolVisibility = Callable[[dict[str, frozenset[str]]], Iterable[str]]
+_tool_visibility: ToolVisibility | None = None
+
+
+def set_tool_visibility(fn: ToolVisibility | None) -> None:
+    """Install the per-request tool filter. Called once at startup."""
+    global _tool_visibility
+    _tool_visibility = fn
+
+
+def tool_visibility() -> ToolVisibility | None:
+    return _tool_visibility
+
+
+def default_setting_hint(config_key: str, dashboard_page: str) -> str:
+    """How to set a missing default, phrased for where AdLoop runs.
+
+    Self-hosted it is a key in the config file; a hosted runtime has no
+    config file the user can edit, so it names the dashboard page instead.
+    """
+    if _deployment_mode == "server":
+        return (
+            f"choose a default under {dashboard_page} in the AdLoop Cloud "
+            "dashboard (agencies: per client under Settings → Clients)"
+        )
+    return f"set {config_key} in the config (~/.adloop/config.yaml)"
+
+
 def deployment_mode() -> DeploymentMode:
     """Return the process-wide deployment mode ("local" or "server")."""
     return _deployment_mode

{adloop-0.22.0 → adloop-0.22.2}/src/adloop/server.py

@@ -9,7 +9,7 @@ from typing import Annotated, Callable
 
 from fastmcp import FastMCP
 from fastmcp.utilities.docstring_parsing import parse_docstring
-from mcp.types import ToolAnnotations
+from mcp.types import Icon, ToolAnnotations
 from pydantic import BeforeValidator
 
 from adloop import diagnostics
@@ -155,10 +155,13 @@ def _gtm_defaults(account_id: str, container_id: str) -> tuple[str, str]:
     account_id = account_id or cfg.account_id
     container_id = container_id or cfg.container_id
     if not account_id or not container_id:
+        from adloop.runtime import default_setting_hint
+
         raise ValueError(
-            "gtm_account_id and gtm_container_id are required — pass them "
-            "explicitly (see list_gtm_accounts / list_gtm_containers) or set "
-            "gtm.account_id / gtm.container_id in the config."
+            "gtm_account_id and gtm_container_id are required: pass them "
+            "explicitly (see list_gtm_accounts / list_gtm_containers) or "
+            + default_setting_hint("gtm.account_id / gtm.container_id", "Settings → Google & accounts")
+            + "."
         )
     return account_id, container_id
 
@@ -166,8 +169,22 @@ def _gtm_defaults(account_id: str, container_id: str) -> tuple[str, str]:
 mcp = FastMCP(
     "AdLoop",
     instructions=_build_orchestration_instructions(),
+    website_url="https://getadloop.com",
+    # Clients that support MCP server icons show these instead of guessing
+    # from the domain's favicon. Square and full-bleed, so a client's own
+    # rounded mask leaves no stray corners.
+    icons=[
+        Icon(src="https://getadloop.com/icon-512.png", mimeType="image/png", sizes=["512x512"]),
+        Icon(src="https://getadloop.com/favicon.svg", mimeType="image/svg+xml", sizes=["any"]),
+    ],
 )
 
+# name -> tags of every registered tool, so health_check can say which tools
+# this server offers without reaching into FastMCP internals.
+_TOOL_TAGS: dict[str, frozenset[str]] = {}
+# Tags enabled by ADLOOP_TOOLSETS (None: the full catalog).
+_ENABLED_TAGS: set[str] | None = None
+
 
 # The API each toolset calls, linked at the end of every tool description:
 # directory reviews ask descriptions to reference the API they target.
@@ -217,6 +234,7 @@ def _tool(*, title: str, annotations: ToolAnnotations, tags: set[str], **kwargs)
         description = parse_docstring(fn).description or inspect.cleandoc(fn.__doc__ or "")
         if docs and "https://" not in description:
             description = f"{description}\n\n{docs}"
+        _TOOL_TAGS[kwargs.get("name") or fn.__name__] = frozenset(tags)
         return mcp.tool(
             title=title,
             annotations=annotations,
@@ -585,9 +603,44 @@ def health_check() -> dict:
     elif status.get("reddit") == "error" and status.get("reddit_hint"):
         status["hint"] = status["reddit_hint"]
 
+    status["adloop_version"] = _adloop_version()
+    status["tools_offered"] = _offered_tool_names()
+    status["tools_note"] = (
+        "These are the tools this AdLoop server offers to you. If one of "
+        "them is missing from your own tool list, your app is showing a "
+        "cached list from an earlier version: ask the user to refresh the "
+        "AdLoop connection (claude.ai: Settings → Connectors → AdLoop; "
+        "ChatGPT: the AdLoop plugin's settings; Perplexity: remove and add "
+        "the connector again; coding agents: reconnect the MCP server or "
+        "start a new session)."
+    )
     return status
 
 
+def _adloop_version() -> str:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("adloop")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def _offered_tool_names() -> list[str]:
+    """The tools the current caller sees in tools/list: enabled by
+    ADLOOP_TOOLSETS, then narrowed by the runtime's visibility hook."""
+    from adloop.runtime import tool_visibility
+
+    tools = {
+        name: tags
+        for name, tags in _TOOL_TAGS.items()
+        if _ENABLED_TAGS is None or tags & _ENABLED_TAGS
+    }
+    hook = tool_visibility()
+    names = hook(tools) if hook is not None else tools
+    return sorted(names)
+
+
 # ---------------------------------------------------------------------------
 # GA4 Read Tools
 # ---------------------------------------------------------------------------
@@ -1740,9 +1793,12 @@ def list_gtm_containers(gtm_account_id: str = "") -> dict:
 
     gtm_account_id = gtm_account_id or current_config().gtm.account_id
     if not gtm_account_id:
+        from adloop.runtime import default_setting_hint
+
         raise ValueError(
-            "gtm_account_id is required — call list_gtm_accounts first or "
-            "set gtm.account_id in the config."
+            "gtm_account_id is required: call list_gtm_accounts first or "
+            + default_setting_hint("gtm.account_id", "Settings → Google & accounts")
+            + "."
         )
     return _impl(current_config(), account_id=gtm_account_id)
 
@@ -5728,7 +5784,9 @@ def _apply_toolsets_env() -> None:
             f"ADLOOP_TOOLSETS names unknown toolset(s): {', '.join(unknown)}. "
             f"Valid toolsets: {', '.join(TOOLSETS)}. Example: ADLOOP_TOOLSETS=ads,ga4"
         )
-    mcp.enable(tags=requested | {"core"}, only=True)
+    global _ENABLED_TAGS
+    _ENABLED_TAGS = requested | {"core"}
+    mcp.enable(tags=_ENABLED_TAGS, only=True)
 
 
 _apply_toolsets_env()