google-analytics-mcp 2.7.2__tar.gz → 2.7.3__tar.gz

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-analytics-mcp
-Version: 2.7.2
+Version: 2.7.3
 Summary: Model Context Protocol for Google Analytics 4 (Data API) allowing autonomous agents to query dimensions and metrics. Gives agents analysis-ready GA4 access with schema discovery, server-side aggregation, and smart defaults.
 Author-email: Surendran B <reachsuren@gmail.com>
 License-Expression: Apache-2.0

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.3}/ga4_mcp/coordinator.py

@@ -126,8 +126,20 @@ def _telemetry_tool(*args, **kwargs):
         is_async = inspect.iscoroutinefunction(func)
 
         def _intercept(name):
-            return (f"Configuration Error: {SERVER_INIT_ERROR}. Please instruct the user to fix their setup."
-                    if (SERVER_INIT_ERROR and name not in _INIT_ERROR_EXEMPT) else None)
+            if not SERVER_INIT_ERROR or name in _INIT_ERROR_EXEMPT:
+                return None
+            # Agent-directed recovery playbook, not a description. The old wording
+            # ("Configuration Error: ...") read as retryable, so agents re-called
+            # the data tool in a loop. Lead with STOP + category, then the fix.
+            lead = {
+                "ADCExpired": "The user's Google credentials have EXPIRED (a returning-user auth issue, not a query problem).",
+                "IAMError": "The service account lacks access to this GA4 property (a permissions grant is missing).",
+                "InitError": "The GA4 MCP server is not configured yet (missing Property ID or credentials).",
+            }.get(SERVER_INIT_ERROR_CATEGORY,
+                  "The GA4 MCP server setup is incomplete.")
+            return (f"STOP — do not retry this tool; it will fail identically until setup is fixed. {lead} "
+                    f"NEXT ACTION: call setup_ga4_access now — it fixes this interactively and reconnects "
+                    f"without a restart. If that is unavailable, relay this to the user. Details: {SERVER_INIT_ERROR}")
 
         if is_async:
             @functools.wraps(func)
@@ -243,6 +255,7 @@ def reinitialize():
         metadata.PROPERTY_SCHEMA = schema
         reporting.PROPERTY_SCHEMA = schema
         SERVER_INIT_ERROR = None
+        telemetry.mark_ever_worked()
         return True, "ok", "initialized"
     except Exception as e:
         err = str(e)

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.3}/ga4_mcp/resources.py

@@ -52,3 +52,22 @@ def get_setup_guide() -> str:
     """Provides instructions to the agent on how to heal the human's MCP setup."""
     send_telemetry("resource_read", {"resource_uri": "docs://setup_guide"})
     return SETUP_GUIDE_MD
+
+
+# Category-addressed fix guides, same content the get_troubleshooting_guide tool
+# serves — exposed as resources for clients that surface resources to the model.
+# One source of truth (tools.troubleshooting._GUIDES); progressive enhancement
+# on top of the always-reaches error playbook.
+from .tools.troubleshooting import _GUIDES as _FIX_GUIDES
+
+
+def _make_fix_resource(topic):
+    def _read() -> str:
+        send_telemetry("resource_read", {"resource_uri": f"docs://fix/{topic}"})
+        return _FIX_GUIDES[topic]
+    _read.__name__ = f"get_fix_{topic}"
+    return mcp.resource(f"docs://fix/{topic}")(_read)
+
+
+for _t in _FIX_GUIDES:
+    _make_fix_resource(_t)

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.3}/ga4_mcp/server.py

@@ -21,7 +21,8 @@ def main():
     """
     print("Starting GA4 MCP server...", file=sys.stderr)
     import ga4_mcp.coordinator as coordinator
-    import ga4_mcp.tools.troubleshooting  # Register the OTA tool
+    from ga4_mcp import telemetry
+    import ga4_mcp.tools.troubleshooting  # Register the troubleshooting tool
     import ga4_mcp.setup_flow  # Register the interactive setup-recovery tool
     config_status = "valid"
 
@@ -97,6 +98,7 @@ def main():
         try:
             PROPERTY_SCHEMA = metadata.get_property_schema_uncached(property_id)
             print("Schema loaded successfully.", file=sys.stderr)
+            telemetry.mark_ever_worked()
         except Exception as e:
             print(f"FATAL: Could not fetch GA4 property schema: {e}", file=sys.stderr)
             err_str = str(e)

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.3}/ga4_mcp/setup_flow.py

@@ -6,14 +6,44 @@ session, avoiding a client restart. Falls back to guided text if the client
 doesn't support elicitation."""
 
 import os
+import uuid
 
 from pydantic import BaseModel, Field
 from mcp.server.fastmcp import Context
 
 from .coordinator import mcp
-from .telemetry import send_telemetry
+from .telemetry import send_telemetry, client_supports_url_elicitation
 from . import coordinator
 
+# Pages we own or that land the user exactly where the fix happens. URL-mode
+# elicitation opens these at the client; no OAuth, no secrets — guided navigation.
+_GA4_ADMIN_URL = "https://analytics.google.com/analytics/web/#/admin"
+_SETUP_PAGE_URL = "https://ga4.builditwithai.xyz/setup"
+
+
+async def _offer_page(ctx, message, url, branch):
+    """URL-mode elicitation: ask the client to open a helpful page before we
+    collect the value. No-op on clients without URL elicitation (falls through
+    to the existing form/text). Records whether the offer was accepted."""
+    if not client_supports_url_elicitation():
+        return None
+    try:
+        r = await ctx.request_context.session.elicit_url(
+            message=message,
+            url=url,
+            elicitation_id=f"setup_{uuid.uuid4().hex[:12]}",
+            related_request_id=ctx.request_id,
+        )
+        action = str(getattr(r, "action", None))
+        send_telemetry("setup_flow", {
+            "flow_branch": branch, "flow_outcome": "url_offered",
+            "url_elicit_action": action,
+            "error_category_at_entry": coordinator.SERVER_INIT_ERROR_CATEGORY,
+        })
+        return action
+    except Exception:
+        return None
+
 
 class _PropertyId(BaseModel):
     property_id: str = Field(description="Your numeric GA4 Property ID, e.g. 123456789")
@@ -62,9 +92,15 @@ async def setup_ga4_access(ctx: Context) -> str:
     branch = "other"
 
     try:
-        # Missing Property ID — collect it.
+        # Missing Property ID — offer to open GA4 Admin, then collect it.
         if not prop:
             branch = "property_id"
+            await _offer_page(
+                ctx,
+                "I'll open Google Analytics Admin so you can copy your Property ID "
+                "(Admin > Property details, a numeric id like 123456789).",
+                _GA4_ADMIN_URL, "property_id_open_admin",
+            )
             r = await ctx.elicit(
                 "What is your GA4 Property ID? Find it at analytics.google.com > Admin > "
                 "Property details (a numeric id like 123456789).",
@@ -75,9 +111,15 @@ async def setup_ga4_access(ctx: Context) -> str:
                 return "Setup paused — no Property ID provided. Re-run setup_ga4_access when ready."
             os.environ["GA4_PROPERTY_ID"] = r.data.property_id.strip()
 
-        # Missing/invalid credentials path — collect it.
+        # Missing/invalid credentials path — offer the setup page, then collect.
         elif not creds or (creds and not os.path.exists(creds)):
             branch = "credentials"
+            await _offer_page(
+                ctx,
+                "I'll open the setup guide — it walks through creating a service-account "
+                "key or using gcloud, with the exact steps.",
+                _SETUP_PAGE_URL, "credentials_open_setup",
+            )
             r = await ctx.elicit(
                 "Where is your Google service-account JSON key on this machine? "
                 "Paste its absolute path. (Or, to use gcloud instead, run "

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.3}/ga4_mcp/telemetry.py

@@ -72,6 +72,30 @@ def _init_anonymous_identity():
 INSTALLATION_ID, IS_FIRST_INSTALL = _init_anonymous_identity()
 SESSION_ID = f"sess_{uuid.uuid4()}"  # one per process
 
+
+def _has_ever_worked() -> bool:
+    """True if this install successfully initialized in a PRIOR session. Lets a
+    query tell a first-time setup failure (never worked) from a returning-user
+    credential decay (worked before, broke since). Bool only, non-PII."""
+    try:
+        return (Path.home() / ".ga4_mcp" / "ever_worked").exists()
+    except Exception:
+        return False
+
+
+HAS_EVER_WORKED = _has_ever_worked()
+
+
+def mark_ever_worked():
+    """Write the 'has successfully worked' marker once, on first successful init.
+    Additive to the frozen identity contract — a separate flag file, not the id."""
+    try:
+        f = Path.home() / ".ga4_mcp" / "ever_worked"
+        if not f.exists():
+            f.write_text("1", encoding="utf-8")
+    except Exception:
+        pass
+
 IN_VIRTUAL_ENV = sys.prefix != sys.base_prefix
 CPU_ARCH = platform.machine()
 TIMEZONE_OFFSET = -time.timezone if (time.localtime().tm_isdst == 0) else -time.altzone
@@ -333,6 +357,17 @@ def capture_client_info(mcp_server):
         pass
 
 
+def client_supports_url_elicitation() -> bool:
+    """True if the handshake advertised URL-mode elicitation (elicitation.url).
+    Read from the raw capabilities we capture; used to offer guided-navigation
+    recovery only to clients that can open a URL."""
+    caps = _RUNTIME_CLIENT.get("caps_raw")
+    if not isinstance(caps, dict):
+        return False
+    elicit = caps.get("elicitation")
+    return isinstance(elicit, dict) and "url" in elicit
+
+
 # In-flight sender threads, drained briefly at exit — short-lived sessions
 # (a large share of real boots) otherwise lose their events to process death.
 _PENDING_SENDS = []
@@ -374,6 +409,7 @@ def send_telemetry(event: str, properties: dict = None):
                 "run_context": RUN_CONTEXT,
                 "discovery_channel": DISCOVERY_CHANNEL,
                 "launch_channel": DISCOVERY_CHANNEL,
+                "has_ever_worked": HAS_EVER_WORKED,
                 "raw_env": ENV_SIGNALS,  # the raw clues behind run_context/agent_name
                 "session_id": SESSION_ID,
                 **(properties or {}),

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.3}/ga4_mcp/tools/reporting.py

@@ -172,9 +172,11 @@ def get_ga4_data(
                                     warning and execute the query anyway.
         enable_aggregation: (Optional) If True, uses server-side aggregation when
                             beneficial. Defaults to True.
-        intent: (Optional) The category of question this query answers. Pick ONE from:
-                traffic_overview | acquisition | content_performance | ecommerce_revenue |
-                user_behavior | geography_devices | campaign_analysis | seo | debugging | other
+        intent: (Optional) A short, plain-language description of what the user is
+                trying to learn from this query — in your own words, not a fixed
+                category. Examples: "weekly retention trend for release planning",
+                "check for bot traffic from non-Japan countries",
+                "which signup flow converts best".
 
     COMMON MISTAKES (checked against real usage — read before guessing names):
     - Metric is 'keyEvents', not 'conversions'. 'totalUsers', not 'users'.

google_analytics_mcp-2.7.3/ga4_mcp/tools/troubleshooting.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""In-server troubleshooting guides. Content lives with the code (bundled at
+release), NOT fetched from the web — instant, offline-safe, and versioned with
+the package. Written for the AI agent to act on and relay to the user."""
+
+from ga4_mcp.coordinator import mcp
+
+_SETUP_GUIDE = """--- SETUP GUIDE ---
+
+The GA4 MCP server needs two things to work: a Property ID and Google credentials.
+
+1. GA4_PROPERTY_ID — the numeric Property ID (e.g. 123456789), NOT the
+   Measurement ID that starts with 'G-'. Find it at analytics.google.com >
+   Admin > Property details.
+2. GOOGLE_APPLICATION_CREDENTIALS — the absolute path to a Google Cloud
+   service-account JSON key, OR run 'gcloud auth application-default login'
+   and use that credentials file.
+
+Set both in the env block of this server in the MCP client config, e.g.:
+   "env": {
+     "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/key.json",
+     "GA4_PROPERTY_ID": "123456789"
+   }
+
+FASTEST PATH: call setup_ga4_access — it collects the missing value
+interactively and reconnects without a restart."""
+
+_IAM_GUIDE = """--- IAM / 403 PERMISSION GUIDE ---
+
+A 403 / PermissionDenied means the credentials are valid but the service
+account has no access to the GA4 property. Grant it:
+
+1. Open analytics.google.com > Admin > Property Access Management.
+2. Click '+' > Add users.
+3. Enter the service account email — it is the 'client_email' field inside
+   the JSON key file.
+4. Assign the 'Viewer' role and save.
+5. Wait a minute for permissions to propagate, then retry.
+
+If credentials instead need re-authentication (a 'Reauthentication is needed'
+or invalid_grant / expired error), the user's Application Default Credentials
+have expired — have them run: gcloud auth application-default login"""
+
+_SCHEMA_GUIDE = """--- SCHEMA GUIDE ---
+
+Do not guess dimension/metric names — use search_schema first. Common fixes
+(verified against real usage):
+- Metric is 'keyEvents', not 'conversions'. 'totalUsers', not 'users'.
+  'itemsViewed', not 'itemViews'. 'ecommercePurchases', not 'purchases'.
+- Dimension is 'sessionDefaultChannelGroup', not 'sessionDefaultChannelGrouping'.
+- A simple dimension_filter MUST nest inside a "filter" key:
+  {"filter": {"fieldName": ..., "stringFilter": {...}}} — not fieldName at top level.
+- Logical groups are "andGroup"/"orGroup"/"notExpression" — not and_filter/or_filter."""
+
+_GUIDES = {"setup": _SETUP_GUIDE, "iam": _IAM_GUIDE, "schema": _SCHEMA_GUIDE}
+
+
+@mcp.tool()
+def get_troubleshooting_guide(topic: str) -> str:
+    """
+    Returns the troubleshooting/setup guide for a topic, served from inside the
+    server (no network needed). Use whenever you hit a schema error,
+    dimension_filter parse error, IAM / 403 authorization error, or a
+    boot-time setup error.
+
+    Args:
+        topic: One of "setup", "iam", or "schema".
+    """
+    guide = _GUIDES.get((topic or "").strip().lower())
+    if guide is None:
+        return "Invalid topic. Choose 'setup', 'iam', or 'schema'."
+    return guide

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.3}/google_analytics_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-analytics-mcp
-Version: 2.7.2
+Version: 2.7.3
 Summary: Model Context Protocol for Google Analytics 4 (Data API) allowing autonomous agents to query dimensions and metrics. Gives agents analysis-ready GA4 access with schema discovery, server-side aggregation, and smart defaults.
 Author-email: Surendran B <reachsuren@gmail.com>
 License-Expression: Apache-2.0

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "google-analytics-mcp"
-version = "2.7.2"
+version = "2.7.3"
 description = "Model Context Protocol for Google Analytics 4 (Data API) allowing autonomous agents to query dimensions and metrics. Gives agents analysis-ready GA4 access with schema discovery, server-side aggregation, and smart defaults."
 readme = "README.md"
 license = "Apache-2.0"

google_analytics_mcp-2.7.2/ga4_mcp/tools/troubleshooting.py

@@ -1,28 +0,0 @@
-import urllib.request
-import urllib.error
-from ga4_mcp.coordinator import mcp
-
-# Fetches troubleshooting guides directly from the documentation site.
-OTA_BASE_URL = "https://ga4mcp.com"
-
-@mcp.tool()
-def get_troubleshooting_guide(topic: str) -> str:
-    """
-    Fetches the latest troubleshooting and setup guides Over-The-Air (OTA) from ga4mcp.com.
-    Use this tool whenever you encounter a schema error, dimension_filter parse error,
-    IAM / 403 authorization error, or boot-time setup error.
-    
-    Args:
-        topic: The topic of the guide to fetch. Valid options are "setup", "iam", or "schema".
-    """
-    if topic not in ["setup", "iam", "schema"]:
-        return "Invalid topic. Please choose 'setup', 'iam', or 'schema'."
-
-    url = f"{OTA_BASE_URL}/{topic}.md"
-    try:
-        with urllib.request.urlopen(url, timeout=10) as response:
-            content = response.read().decode('utf-8')
-            return f"--- {topic.upper()} GUIDE ---\n\n{content}"
-    except urllib.error.URLError as e:
-        # Fallback if network is completely unreachable (rare, since GA4 needs network anyway)
-        return f"Warning: Could not fetch OTA guide for '{topic}' due to network error: {e}. Please use your best judgment based on generic GA4 API documentation."