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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-analytics-mcp
-Version: 2.7.2
+Version: 2.7.4
 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.4}/ga4_mcp/coordinator.py

@@ -3,7 +3,9 @@
 """FastMCP singleton, plus the decorator that wraps each tool with telemetry
 and boot-error interception. Telemetry mechanics live in ga4_mcp.telemetry."""
 
+import os
 import sys
+import json
 import time
 import inspect
 import functools
@@ -31,6 +33,30 @@ SERVER_INIT_ERROR_CATEGORY = "InitError"
 mcp = FastMCP("Google Analytics 4")
 telemetry.announce_and_fire_boot_events()
 
+
+def inspect_credentials(path):
+    """Report the SHAPE of a credentials file so error messages can be
+    auth-model-correct and hand the model exact values — without logging any
+    secret. Returns (model, client_email, ok):
+      model: service_account | adc | unknown | missing | unreadable
+      client_email: only for service_account (safe to show — it's the grantee)
+      ok: whether the file is present and parseable."""
+    try:
+        if not path or not os.path.exists(path):
+            return ("missing", None, False)
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        t = data.get("type")
+        if t == "service_account":
+            return ("service_account", data.get("client_email"), True)
+        if t == "authorized_user":
+            return ("adc", None, True)
+        return ("unknown", None, True)
+    except json.JSONDecodeError:
+        return ("unreadable", None, False)
+    except Exception:
+        return ("unknown", None, False)
+
 _original_tool = mcp.tool
 
 
@@ -126,8 +152,12 @@ 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)
+            # SERVER_INIT_ERROR is already a self-contained decision brief (built
+            # in server.py) — what broke, why, don't-retry, exact user action,
+            # who, forwardable, optional depth. Deliver it as-is; no extra hop.
+            if not SERVER_INIT_ERROR or name in _INIT_ERROR_EXEMPT:
+                return None
+            return str(SERVER_INIT_ERROR)
 
         if is_async:
             @functools.wraps(func)
@@ -243,6 +273,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.4}/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.4/ga4_mcp/server.py

@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import sys
+from .coordinator import mcp
+from .tools import metadata, reporting
+from . import resources
+
+# Property schema, cached at startup.
+PROPERTY_SCHEMA = None
+
+def main():
+    """
+    Main entry point for the MCP server.
+
+    This function performs the following steps:
+    1. Validates required environment variables.
+    2. Fetches and caches the GA4 property schema (dimensions and metrics).
+    3. Registers the tools with the MCP server.
+    4. Starts the server and listens for requests.
+    """
+    print("Starting GA4 MCP server...", file=sys.stderr)
+    import ga4_mcp.coordinator as coordinator
+    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"
+
+    # 1. Validate environment variables
+    credentials_path = os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
+    property_id = os.getenv("GA4_PROPERTY_ID")
+
+    setup_url = "https://ga4.builditwithai.xyz/setup"
+
+    def _config_hint():
+        # Name the config surface for the detected client.
+        agent = getattr(coordinator, "AGENT_NAME", "")
+        if agent == "claude_code":
+            return ("In Claude Code run: claude mcp add ga4-analytics -e GA4_PROPERTY_ID=<id> "
+                    "-e GOOGLE_APPLICATION_CREDENTIALS=<key-path> -- uvx --from google-analytics-mcp ga4-mcp-server")
+        if agent == "claude_desktop":
+            return ("In Claude Desktop: Settings > Developer > Edit Config, set these env values under "
+                    "mcpServers > ga4-analytics in claude_desktop_config.json")
+        if agent == "cursor":
+            return "In Cursor: Settings > MCP (edit .cursor/mcp.json), set these env values for ga4-analytics"
+        if agent in ("vscode", "windsurf"):
+            return "Edit this editor's MCP settings JSON and set these env values for ga4-analytics"
+        return "Set these env values in your MCP client's server config for ga4-analytics"
+
+    def _guided(what, steps, anchor, topic="setup", why=None, who=None, handoff=None):
+        """Self-contained decision brief written FOR THE MODEL: what broke, why it
+        blocks everything, that retrying is futile, exactly what the user must do
+        (with their values), and who can do it. setup_ga4_access and docs are
+        OPTIONAL depth, not the path to understanding — reduce hops."""
+        step_text = " ".join(f"({i}) {s}" for i, s in enumerate(steps, 1))
+        why = why or "No GA4 data can be returned until this is resolved."
+        who = who or "the user (whoever set up this server's Google access)"
+        parts = [
+            f"[SETUP BLOCKED] {what}",
+            f"WHY: {why}",
+            "RETRYING WON'T HELP — every call fails identically until the user changes setup outside this tool; do not re-call data tools.",
+            f"WHAT MUST HAPPEN (only the user can do this): {step_text}",
+            f"WHO CAN DO IT: {who}.",
+        ]
+        if handoff:
+            parts.append(f'FORWARDABLE — the user can send this verbatim to whoever admins their GA4/Google Cloud: "{handoff}"')
+        parts.append(
+            f"OPTIONAL (not needed to understand or relay this): call setup_ga4_access to collect a missing value "
+            f"in-session; get_troubleshooting_guide(topic='{topic}') or resource docs://fix/{topic} for detail; "
+            f"full guide {setup_url}#{anchor}.")
+        return "  ".join(parts)
+
+    if not credentials_path:
+        print("ERROR: GOOGLE_APPLICATION_CREDENTIALS environment variable not set.", file=sys.stderr)
+        coordinator.SERVER_INIT_ERROR = _guided(
+            "No Google credentials are configured — GOOGLE_APPLICATION_CREDENTIALS is unset.",
+            ["Point GOOGLE_APPLICATION_CREDENTIALS at a Google service-account JSON key "
+             "(Cloud Console > IAM > Service Accounts > Keys) — best for a persistent/shared setup; "
+             "OR if you have the gcloud CLI, run 'gcloud auth application-default login' and use that credentials file.",
+             _config_hint()],
+            "credentials",
+            why="The server cannot authenticate to the GA4 API, so no query can run.")
+        config_status = "error"
+    elif not property_id:
+        print("ERROR: GA4_PROPERTY_ID environment variable not set.", file=sys.stderr)
+        coordinator.SERVER_INIT_ERROR = _guided(
+            "No GA4 Property ID is set — GA4_PROPERTY_ID is unset.",
+            ["Set GA4_PROPERTY_ID to the numeric Property ID (NOT the 'G-' Measurement ID) — "
+             "find it at analytics.google.com > Admin > Property details (e.g. 123456789).",
+             _config_hint()],
+            "property-id",
+            why="Every query must target a specific property; without the ID nothing can be read.")
+        config_status = "error"
+    elif "ABSOLUTE/PATH/TO" in credentials_path:
+        print(f"ERROR: Dummy credentials path detected: '{credentials_path}'.", file=sys.stderr)
+        coordinator.SERVER_INIT_ERROR = _guided(
+            "The credentials path is still the copy-paste placeholder ('/ABSOLUTE/PATH/TO...'), not a real path.",
+            ["Replace the /ABSOLUTE/PATH/TO placeholder in the config with the real absolute path of the "
+             "downloaded service-account JSON key.",
+             _config_hint()],
+            "credentials",
+            why="The server has no real credentials file to authenticate with, so no query can run.")
+        config_status = "error"
+    elif not os.path.exists(credentials_path):
+        print(f"ERROR: Credentials file not found at '{credentials_path}'.", file=sys.stderr)
+        coordinator.SERVER_INIT_ERROR = _guided(
+            f"The credentials file does not exist at the configured path '{credentials_path}'.",
+            ["Verify the file exists at that exact absolute path (check the filename, folder, and any typo).",
+             "If it was moved or never downloaded, re-download the service-account JSON key from "
+             "Google Cloud Console > IAM > Service Accounts > Keys and point the config at it.",
+             _config_hint()],
+            "credentials",
+            why="The server cannot read credentials, so it cannot authenticate to GA4.")
+        config_status = "error"
+    else:
+        # 2. Fetch and cache the GA4 property schema
+        print(f"Fetching schema for property '{property_id}'...", file=sys.stderr)
+        global PROPERTY_SCHEMA
+        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)
+            if "403" in err_str or "PermissionDenied" in err_str or "permission" in err_str.lower():
+                model, email, _ = coordinator.inspect_credentials(credentials_path)
+                if model == "service_account" and email:
+                    grantee = f"the service account {email}"
+                    handoff = (f"Please add {email} as a Viewer on GA4 property {property_id} "
+                               f"(analytics.google.com > Admin > Property Access Management).")
+                elif model == "adc":
+                    grantee = "the Google account you authenticated with via gcloud"
+                    handoff = (f"Please grant my Google account Viewer access on GA4 property {property_id} "
+                               f"(Admin > Property Access Management).")
+                else:
+                    grantee = "the service account (the client_email inside the JSON key)"
+                    handoff = f"Please add my service account as a Viewer on GA4 property {property_id}."
+                coordinator.SERVER_INIT_ERROR = _guided(
+                    f"Credentials are valid, but {grantee} has no access to GA4 property {property_id}.",
+                    [f"At analytics.google.com > Admin > Property Access Management, add {grantee} with the Viewer role.",
+                     "Wait ~1 minute for the grant to propagate, then ask me to retry (no restart needed)."],
+                    "iam", topic="iam",
+                    why="Authentication succeeded but this account is not authorized to read this property (Google returns 403).",
+                    who="the user, or whoever administers this GA4 property if that is someone else",
+                    handoff=handoff)
+                coordinator.SERVER_INIT_ERROR_CATEGORY = "IAMError"
+            elif ("Reauthentication is needed" in err_str or "invalid_grant" in err_str
+                    or "expired or revoked" in err_str):
+                worked_before = telemetry.HAS_EVER_WORKED
+                lead = ("This server was working before — the Google credentials have now expired."
+                        if worked_before else "The Google credentials are expired or revoked.")
+                coordinator.SERVER_INIT_ERROR = _guided(
+                    lead,
+                    ["Re-authenticate: run 'gcloud auth application-default login' in a terminal (for ADC), "
+                     "or replace the service-account key file if that is what this server uses.",
+                     "Then ask me to retry — no config changes needed.",
+                     "Tip: service-account keys do not expire; prefer one if this recurs."],
+                    "adc",
+                    why="The stored credentials are no longer valid, so authentication to GA4 fails.",
+                    who="the user (re-auth is a local action only they can take)")
+                coordinator.SERVER_INIT_ERROR_CATEGORY = "ADCExpired"
+            else:
+                coordinator.SERVER_INIT_ERROR = _guided(
+                    f"Could not fetch GA4 property schema: {err_str}.",
+                    ["Check that GA4_PROPERTY_ID is the numeric ID of a property this service account can access.",
+                     "Check the credentials file is a valid service-account JSON key.",
+                     _config_hint()],
+                    "setup")
+            config_status = "error"
+
+    # 3. Register tools (importing the modules registers their @mcp.tool functions)
+    metadata.PROPERTY_SCHEMA = PROPERTY_SCHEMA
+    reporting.PROPERTY_SCHEMA = PROPERTY_SCHEMA
+    
+    # 4. Run the server
+    from .coordinator import send_telemetry
+    import time as _time
+    start_payload = {
+        "config_status": config_status,
+        "shell": os.path.basename(os.getenv("SHELL", "") or "unknown"),
+        "term_program": os.getenv("TERM_PROGRAM", "unknown"),
+        "system_lang": os.getenv("LANG", "unknown"),
+        "is_ci": os.getenv("CI", "false").lower() == "true" or os.getenv("GITHUB_ACTIONS", "false").lower() == "true",
+        # Env var NAMES only, never values — makes harnesses we didn't
+        # anticipate visible instead of falling to generic_agent.
+        "env_var_names": sorted(os.environ.keys()),
+    }
+    if coordinator.SERVER_INIT_ERROR:
+        start_payload["error_message"] = str(coordinator.SERVER_INIT_ERROR)
+        start_payload["error_category"] = coordinator.SERVER_INIT_ERROR_CATEGORY
+    send_telemetry("mcp_started", start_payload)
+    mcp.run(transport="stdio")
+
+if __name__ == "__main__":
+    main()

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.4}/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 "
@@ -89,6 +131,19 @@ async def setup_ga4_access(ctx: Context) -> str:
                 return "Setup paused — no credentials path provided. Re-run setup_ga4_access when ready."
             path = r.data.credentials_path.strip()
             if path.lower() != "adc":
+                # Validate at collection: existence alone isn't enough — a
+                # present-but-malformed/wrong-type file passes os.path.exists but
+                # fails later. Tell the model precisely which so it can re-ask.
+                model, _email, ok = coordinator.inspect_credentials(path)
+                if model == "missing":
+                    _emit_flow(branch, r.action, "invalid_path")
+                    return (f"No file exists at '{path}'. Ask the user for the correct absolute path to their "
+                            "Google service-account JSON key, then re-run setup_ga4_access.")
+                if not ok or model in ("unreadable", "unknown"):
+                    _emit_flow(branch, r.action, "invalid_creds")
+                    return (f"The file at '{path}' is not a valid Google credentials JSON (expected a "
+                            "service-account key or an authorized_user/ADC file). Ask the user to re-download "
+                            "the service-account key from Google Cloud Console > IAM > Service Accounts > Keys.")
                 os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = path
 
         # Expired credentials (ADC) — confirm the terminal fix.

{google_analytics_mcp-2.7.2 → google_analytics_mcp-2.7.4}/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.4}/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.4/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.4}/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.4
 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.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "google-analytics-mcp"
-version = "2.7.2"
+version = "2.7.4"
 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/server.py

@@ -1,153 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-
-import os
-import sys
-from .coordinator import mcp
-from .tools import metadata, reporting
-from . import resources
-
-# Property schema, cached at startup.
-PROPERTY_SCHEMA = None
-
-def main():
-    """
-    Main entry point for the MCP server.
-
-    This function performs the following steps:
-    1. Validates required environment variables.
-    2. Fetches and caches the GA4 property schema (dimensions and metrics).
-    3. Registers the tools with the MCP server.
-    4. Starts the server and listens for requests.
-    """
-    print("Starting GA4 MCP server...", file=sys.stderr)
-    import ga4_mcp.coordinator as coordinator
-    import ga4_mcp.tools.troubleshooting  # Register the OTA tool
-    import ga4_mcp.setup_flow  # Register the interactive setup-recovery tool
-    config_status = "valid"
-
-    # 1. Validate environment variables
-    credentials_path = os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
-    property_id = os.getenv("GA4_PROPERTY_ID")
-
-    setup_url = "https://ga4.builditwithai.xyz/setup"
-
-    def _config_hint():
-        # Name the config surface for the detected client.
-        agent = getattr(coordinator, "AGENT_NAME", "")
-        if agent == "claude_code":
-            return ("In Claude Code run: claude mcp add ga4-analytics -e GA4_PROPERTY_ID=<id> "
-                    "-e GOOGLE_APPLICATION_CREDENTIALS=<key-path> -- uvx --from google-analytics-mcp ga4-mcp-server")
-        if agent == "claude_desktop":
-            return ("In Claude Desktop: Settings > Developer > Edit Config, set these env values under "
-                    "mcpServers > ga4-analytics in claude_desktop_config.json")
-        if agent == "cursor":
-            return "In Cursor: Settings > MCP (edit .cursor/mcp.json), set these env values for ga4-analytics"
-        if agent in ("vscode", "windsurf"):
-            return "Edit this editor's MCP settings JSON and set these env values for ga4-analytics"
-        return "Set these env values in your MCP client's server config for ga4-analytics"
-
-    def _guided(message, steps, anchor, topic="setup"):
-        step_text = " ".join(f"({i}) {s}" for i, s in enumerate(steps, 1))
-        return (f"{message} FASTEST FIX — call the setup_ga4_access tool now: it walks the user through "
-                f"fixing this interactively and reconnects without a restart. "
-                f"Or relay these steps manually: {step_text} "
-                f"Full guide: {setup_url}#{anchor}. "
-                f"For deeper reference call get_troubleshooting_guide(topic='{topic}').")
-
-    if not credentials_path:
-        print("ERROR: GOOGLE_APPLICATION_CREDENTIALS environment variable not set.", file=sys.stderr)
-        coordinator.SERVER_INIT_ERROR = _guided(
-            "GOOGLE_APPLICATION_CREDENTIALS environment variable not set.",
-            ["Create a Google Cloud service account JSON key (Cloud Console > IAM > Service Accounts > Keys), "
-             "or run 'gcloud auth application-default login' and use that credentials file.",
-             _config_hint()],
-            "credentials")
-        config_status = "error"
-    elif not property_id:
-        print("ERROR: GA4_PROPERTY_ID environment variable not set.", file=sys.stderr)
-        coordinator.SERVER_INIT_ERROR = _guided(
-            "GA4_PROPERTY_ID environment variable not set.",
-            ["Open analytics.google.com > Admin > Property details and copy the numeric Property ID (e.g. 123456789).",
-             _config_hint()],
-            "property-id")
-        config_status = "error"
-    elif "ABSOLUTE/PATH/TO" in credentials_path:
-        print(f"ERROR: Dummy credentials path detected: '{credentials_path}'.", file=sys.stderr)
-        coordinator.SERVER_INIT_ERROR = _guided(
-            "Setup failed because the dummy path is still in the config.",
-            ["Replace the /ABSOLUTE/PATH/TO placeholder with the real absolute path of the downloaded "
-             "service-account JSON key.",
-             _config_hint()],
-            "credentials")
-        config_status = "error"
-    elif not os.path.exists(credentials_path):
-        print(f"ERROR: Credentials file not found at '{credentials_path}'.", file=sys.stderr)
-        coordinator.SERVER_INIT_ERROR = _guided(
-            f"Credentials file not found at '{credentials_path}'.",
-            ["Verify the file exists at that exact absolute path (check the filename and folder).",
-             "If it is missing, re-download the service account JSON key from Google Cloud Console > IAM > "
-             "Service Accounts > Keys.",
-             _config_hint()],
-            "credentials")
-        config_status = "error"
-    else:
-        # 2. Fetch and cache the GA4 property schema
-        print(f"Fetching schema for property '{property_id}'...", file=sys.stderr)
-        global PROPERTY_SCHEMA
-        try:
-            PROPERTY_SCHEMA = metadata.get_property_schema_uncached(property_id)
-            print("Schema loaded successfully.", file=sys.stderr)
-        except Exception as e:
-            print(f"FATAL: Could not fetch GA4 property schema: {e}", file=sys.stderr)
-            err_str = str(e)
-            if "403" in err_str or "PermissionDenied" in err_str or "permission" in err_str.lower():
-                coordinator.SERVER_INIT_ERROR = _guided(
-                    "IAM Error: The service account does not have Viewer access to the GA4 property.",
-                    ["Open analytics.google.com > Admin > Property Access Management.",
-                     "Add the service account email (the client_email field inside the JSON key) with the "
-                     "Viewer role.",
-                     "Wait a minute for permissions to propagate, then restart the MCP client."],
-                    "iam", topic="iam")
-                coordinator.SERVER_INIT_ERROR_CATEGORY = "IAMError"
-            elif ("Reauthentication is needed" in err_str or "invalid_grant" in err_str
-                    or "expired or revoked" in err_str):
-                coordinator.SERVER_INIT_ERROR = _guided(
-                    f"Google credentials have expired: {err_str}.",
-                    ["Ask the user to run in a terminal: gcloud auth application-default login",
-                     "Then restart the MCP client — no config changes needed."],
-                    "adc")
-                coordinator.SERVER_INIT_ERROR_CATEGORY = "ADCExpired"
-            else:
-                coordinator.SERVER_INIT_ERROR = _guided(
-                    f"Could not fetch GA4 property schema: {err_str}.",
-                    ["Check that GA4_PROPERTY_ID is the numeric ID of a property this service account can access.",
-                     "Check the credentials file is a valid service-account JSON key.",
-                     _config_hint()],
-                    "setup")
-            config_status = "error"
-
-    # 3. Register tools (importing the modules registers their @mcp.tool functions)
-    metadata.PROPERTY_SCHEMA = PROPERTY_SCHEMA
-    reporting.PROPERTY_SCHEMA = PROPERTY_SCHEMA
-    
-    # 4. Run the server
-    from .coordinator import send_telemetry
-    import time as _time
-    start_payload = {
-        "config_status": config_status,
-        "shell": os.path.basename(os.getenv("SHELL", "") or "unknown"),
-        "term_program": os.getenv("TERM_PROGRAM", "unknown"),
-        "system_lang": os.getenv("LANG", "unknown"),
-        "is_ci": os.getenv("CI", "false").lower() == "true" or os.getenv("GITHUB_ACTIONS", "false").lower() == "true",
-        # Env var NAMES only, never values — makes harnesses we didn't
-        # anticipate visible instead of falling to generic_agent.
-        "env_var_names": sorted(os.environ.keys()),
-    }
-    if coordinator.SERVER_INIT_ERROR:
-        start_payload["error_message"] = str(coordinator.SERVER_INIT_ERROR)
-        start_payload["error_category"] = coordinator.SERVER_INIT_ERROR_CATEGORY
-    send_telemetry("mcp_started", start_payload)
-    mcp.run(transport="stdio")
-
-if __name__ == "__main__":
-    main()

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."