google-analytics-mcp-server 0.1.0__py3-none-any.whl

google_analytics_mcp_server/__init__.py

@@ -0,0 +1,18 @@
+"""Google Analytics MCP server entry point."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def package_version() -> str:
+    """Return the installed distribution version."""
+    try:
+        return version('google-analytics-mcp-server')
+    except PackageNotFoundError:
+        return '0.1.0'
+
+
+def main() -> None:
+    """Start the stdio server without writing application output to stdout."""
+    from google_analytics_mcp_server.server import run_server
+
+    run_server()

google_analytics_mcp_server/auth.py

@@ -0,0 +1,71 @@
+"""Lazy, process-local Application Default Credentials."""
+
+import subprocess
+import threading
+from unittest.mock import patch
+
+import google.auth
+from google.auth.credentials import Credentials
+from google.auth.exceptions import DefaultCredentialsError
+from mcp.server.mcpserver.exceptions import ToolError
+
+from google_analytics_mcp_server import config
+
+PREFIX = 'https://www.googleapis.com/auth/'
+BASE_SCOPES = ('analytics.readonly', 'analytics.edit', 'analytics.manage.users')
+_lock = threading.Lock()
+_credentials: Credentials | None = None
+
+
+def _gcloud_output(command: list[str]) -> bytes:
+    """Keep google-auth's project lookup subprocess off MCP's stdin."""
+    return subprocess.check_output(
+        command, stdin=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30
+    )
+
+
+def scopes() -> tuple[str, ...]:
+    """Request chat scope only when the chat tool can be registered."""
+    extra = (
+        ('analytics.chatbot.read',)
+        if config.enabled('ENABLE_CHAT') and not config.read_only()
+        else ()
+    )
+    return tuple(PREFIX + scope for scope in (*BASE_SCOPES, *extra))
+
+
+def setup_hint() -> str:
+    """Explain explicit user login without performing it."""
+    return (
+        'Enable analyticsadmin.googleapis.com and analyticsdata.googleapis.com in your project. '
+        'Create a Desktop OAuth client and run:\n'
+        'gcloud auth application-default login --client-id-file=YOUR_DESKTOP_CLIENT.json '
+        f'--scopes={",".join(scopes())}\n'
+        'If this ADC file is shared with GTM or other applications, include their scopes too. '
+        'Alternatively set GOOGLE_APPLICATION_CREDENTIALS per MCP process. '
+        'Passing scopes in code does not grant additional consent to existing user credentials.'
+    )
+
+
+def credentials() -> Credentials:
+    """Resolve ADC only on the first permitted API request."""
+    global _credentials
+    with _lock:
+        if _credentials is None:
+            try:
+                # The installed google-auth helper inherits stdin by default.
+                # Patch only its project-lookup helper, not process-wide Popen.
+                with patch(
+                    'google.auth._cloud_sdk._run_subprocess_ignore_stderr',
+                    _gcloud_output,
+                ):
+                    _credentials, _ = google.auth.default(scopes=scopes())
+            except DefaultCredentialsError as error:
+                raise ToolError(
+                    f'No usable Google credentials. {setup_hint()}'
+                ) from error
+            except subprocess.TimeoutExpired as error:
+                raise ToolError(
+                    'gcloud project lookup timed out. Set GOOGLE_CLOUD_PROJECT explicitly or repair the local gcloud setup.'
+                ) from error
+        return _credentials

google_analytics_mcp_server/capabilities.py

@@ -0,0 +1,172 @@
+"""Declarative endpoint and field routes, separate from verification evidence."""
+
+import re
+from typing import Any
+
+from google_analytics_mcp_server import catalog, config, policy
+from google_analytics_mcp_server.catalog import Method
+
+TRANSPORT_OVERRIDES = frozenset(
+    {
+        'key',
+        'access_token',
+        'oauth_token',
+        'uploadType',
+        'upload_protocol',
+        'callback',
+    }
+)
+QUERY_ARGUMENTS = {
+    'pageSize': 'limit',
+    'pageToken': 'page_token',
+    'showDeleted': 'show_deleted',
+    'filter': 'filter',
+    'names': 'names',
+    'updateMask': 'update_mask',
+    'calculatedMetricId': 'resource_id',
+}
+
+
+def availability(item: Method) -> dict[str, Any]:
+    """Describe current reachability without claiming live API eligibility."""
+    feature = 'GA_MCP_ENABLE_CHAT' if item.owner == 'ga_chat' else None
+    enabled = (not config.read_only() or policy.is_read(item)) and (
+        feature is None or config.enabled('ENABLE_CHAT')
+    )
+    return {
+        'native_enabled': enabled,
+        'feature_gate': feature,
+        'read_only_eligible': policy.is_read(item),
+        'confirmation_required': item.owner in policy.DESTRUCTIVE_OWNERS,
+        'raw_enabled': enabled
+        and config.enabled('ENABLE_RAW_API')
+        and not config.read_only(),
+    }
+
+
+def parameter_route(item: Method, name: str, spec: dict[str, Any]) -> str:
+    """Map a business parameter to the corresponding native tool argument."""
+    if spec['location'] == 'query':
+        return QUERY_ARGUMENTS.get(name, 'raw.params.' + name)
+    if item.owner in {
+        'ga_start_async_job',
+        'ga_submit_user_deletion',
+        'ga_get_metadata',
+    }:
+        return 'property'
+    return name
+
+
+def request_fields(item: Method) -> list[dict[str, Any]]:
+    """Enumerate recursive field routes; mark repeated and recursive references."""
+    if not item.request_schema:
+        return []
+    argument = 'patch' if item.owner in {'ga_update', 'ga_update_settings'} else 'body'
+    generated = item.owner in {
+        'ga_acknowledge_user_data_collection',
+        'ga_delete',
+        'ga_review_dv360_link_proposal',
+    }
+    result: list[dict[str, Any]] = []
+
+    def visit(
+        spec: dict[str, Any], path: str, ancestors: frozenset[str], writable: bool
+    ) -> None:
+        writable = writable and not spec.get('readOnly', False)
+        if argument == 'patch' and re.search(
+            r'\bImmutable\.', spec.get('description', '')
+        ):
+            writable = False
+        entry: dict[str, Any] = {
+            'path': path,
+            'native': 'generated' if generated else f'{argument}.{path}',
+            'raw': f'body.{path}',
+            'writable': writable,
+        }
+        if '$ref' in spec:
+            ref = spec['$ref']
+            if ref in ancestors:
+                entry['recursive_schema'] = ref
+                result.append(entry)
+                return
+            spec = item.schema(ref)
+            ancestors = ancestors | {ref}
+        if spec.get('type') == 'array':
+            visit(spec.get('items', {}), path + '[]', ancestors, writable)
+        elif spec.get('properties'):
+            for name, child in spec['properties'].items():
+                visit(child, f'{path}.{name}' if path else name, ancestors, writable)
+        else:
+            entry.update({k: spec[k] for k in ('type', 'format', 'enum') if k in spec})
+            result.append(entry)
+
+    visit({'$ref': item.request_schema}, '', frozenset(), True)
+    return result
+
+
+def endpoint(item: Method) -> dict[str, Any]:
+    """Describe field access and intentional value restrictions for one endpoint."""
+    global_params = catalog.document(item.api, item.version).get('parameters', {})
+    restrictions = [
+        'Google enforces business rules, roles, feature eligibility and preview access.',
+        'Read output is bounded by GA_MCP_MAX_OUTPUT_BYTES; no silent row clipping.',
+    ]
+    if 'updateMask' in item.parameters:
+        restrictions.extend(
+            [
+                'An explicit nonempty updateMask is required.',
+                'Native patches require exact writable leaf masks; wildcard and parent-message masks require raw dispatch and confirmation.',
+                'Unverified null clearing is rejected by native patches; array semantics are method-specific.',
+            ]
+        )
+    if 'accessBindings' in item.resource and not policy.is_read(item):
+        restrictions.append(
+            'All binding writes require confirmation; updates require a complete intended roles array, with [] denoting deletion.'
+        )
+    return {
+        'method': item.key,
+        'native_tool': item.owner,
+        'default_version': catalog.routes()[item.logical_key]['default_version'],
+        **availability(item),
+        'parameters': {
+            name: {'native': parameter_route(item, name, spec), 'raw': f'params.{name}'}
+            for name, spec in item.parameters.items()
+        },
+        'request_fields': request_fields(item),
+        'global_query_parameters': {
+            name: f'raw.params.{name}'
+            for name in global_params
+            if name not in TRANSPORT_OVERRIDES
+        },
+        'restrictions': restrictions,
+        'transport': 'ADC authentication and JSON responses; auth/upload overrides are not exposed.',
+        'verification': 'Declared routes from pinned discovery; not evidence of offline or live test coverage.',
+    }
+
+
+def ledger() -> dict[str, Any]:
+    """Return the versioned ledger and actual configured method availability."""
+    entries = [
+        {
+            'method': item.key,
+            'tool': item.owner,
+            'default': catalog.routes()[item.logical_key]['default_version']
+            == item.version,
+            **availability(item),
+        }
+        for item in catalog.methods()
+    ]
+    enabled = [entry for entry in entries if entry['native_enabled']]
+    return {
+        'logical_methods': len(catalog.routes()),
+        'versioned_endpoints': len(entries),
+        'enabled_logical_methods': len(
+            {
+                (entry['method'].split(':')[0], entry['method'].split(':')[2])
+                for entry in enabled
+            }
+        ),
+        'enabled_versioned_endpoints': len(enabled),
+        'verification': 'Declared routes, not a test result. Describe a method to inspect its field routes and value restrictions.',
+        'methods': entries,
+    }

google_analytics_mcp_server/catalog.py

@@ -0,0 +1,219 @@
+"""Pinned, versioned discovery catalog and reviewed tool ownership."""
+
+import json
+import re
+from dataclasses import dataclass
+from functools import cache
+from importlib.resources import files
+from typing import Any, cast
+
+from mcp.server.mcpserver.exceptions import ToolError
+
+from google_analytics_mcp_server.config import ApiVersion, Version
+
+SERVICES = {'admin': 'analyticsadmin', 'data': 'analyticsdata'}
+VERSIONS: tuple[Version, ...] = ('v1beta', 'v1alpha')
+
+
+@dataclass(frozen=True)
+class Method:
+    """A concrete discovery method; identity always includes its version."""
+
+    api: str
+    version: Version
+    id: str
+    resource: str
+    name: str
+    spec: dict[str, Any]
+    owner: str
+
+    @property
+    def logical_key(self) -> str:
+        """Return the version-independent identity."""
+        return f'{self.api}:{self.id}'
+
+    @property
+    def key(self) -> str:
+        """Return the fully qualified identity."""
+        return f'{self.api}:{self.version}:{self.id}'
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        """Return method-specific path and query parameters."""
+        return dict(self.spec.get('parameters', {}))
+
+    @property
+    def path_parameters(self) -> dict[str, Any]:
+        """Return path parameters, retaining their wire names."""
+        return {k: v for k, v in self.parameters.items() if v['location'] == 'path'}
+
+    @property
+    def request_schema(self) -> str | None:
+        """Return the request schema name when a body is supported."""
+        return cast(str | None, self.spec.get('request', {}).get('$ref'))
+
+    @property
+    def response_schema(self) -> str | None:
+        """Return the response schema name."""
+        return cast(str | None, self.spec.get('response', {}).get('$ref'))
+
+    def schema(self, name: str) -> dict[str, Any]:
+        """Resolve a schema in this method's exact discovery version."""
+        return cast(dict[str, Any], document(self.api, self.version)['schemas'][name])
+
+
+@cache
+def document(api: str, version: str) -> dict[str, Any]:
+    """Load a bundled discovery snapshot without network access."""
+    if api not in SERVICES or version not in VERSIONS:
+        raise ToolError('Use api=admin|data and version=v1alpha|v1beta.')
+    path = files('google_analytics_mcp_server').joinpath(
+        'discovery', f'{SERVICES[api]}.{version}.json'
+    )
+    result: dict[str, Any] = json.loads(path.read_text('utf-8'))
+    return result
+
+
+@cache
+def routes() -> dict[str, dict[str, str]]:
+    """Load reviewed default versions and logical owners."""
+    result: dict[str, dict[str, str]] = json.loads(
+        files('google_analytics_mcp_server')
+        .joinpath('discovery', 'routes.json')
+        .read_text('utf-8')
+    )
+    return result
+
+
+@cache
+def methods() -> tuple[Method, ...]:
+    """Enumerate every versioned endpoint, including non-default variants."""
+    found: list[Method] = []
+
+    def visit(api: str, version: Version, node: dict[str, Any], resource: str) -> None:
+        for name, spec in node.get('methods', {}).items():
+            identity = spec['id'].removeprefix(f'{SERVICES[api]}.')
+            key = f'{api}:{identity}'
+            if key not in routes():
+                raise ToolError(
+                    f'{key} needs a reviewed entry in discovery/routes.json.'
+                )
+            found.append(
+                Method(
+                    api, version, identity, resource, name, spec, routes()[key]['tool']
+                )
+            )
+        for name, child in node.get('resources', {}).items():
+            visit(api, version, child, '.'.join(filter(None, (resource, name))))
+
+    for api in SERVICES:
+        for version in VERSIONS:
+            visit(api, version, document(api, version), '')
+    return tuple(found)
+
+
+def method(api: str, identity: str, version: ApiVersion = 'auto') -> Method:
+    """Resolve a method without falling back from an explicitly selected version."""
+    identity = identity.removeprefix(f'{SERVICES.get(api, api)}.')
+    route = routes().get(f'{api}:{identity}')
+    if route is None:
+        raise ToolError(f'Unknown {api} method {identity}. Use ga_describe_schema.')
+    chosen = route['default_version'] if version == 'auto' else version
+    for item in methods():
+        if (item.api, item.id, item.version) == (api, identity, chosen):
+            return item
+    raise ToolError(
+        f'{api}:{identity} is unavailable in {chosen}; choose its published version.'
+    )
+
+
+def candidates(owner: str, version: ApiVersion = 'auto') -> list[Method]:
+    """Return the routes served by one native tool in the requested version."""
+    return [
+        item
+        for item in methods()
+        if item.owner == owner
+        and (
+            item.version == version
+            if version != 'auto'
+            else item.version == routes()[item.logical_key]['default_version']
+        )
+    ]
+
+
+def items_key(item: Method) -> str:
+    """Find the collection in a list response."""
+    fields = item.schema(item.response_schema or '').get('properties', {})
+    arrays: list[str] = [k for k, v in fields.items() if v.get('type') == 'array']
+    if len(arrays) != 1:
+        raise ToolError(f'{item.key} does not have an unambiguous list response.')
+    return arrays[0]
+
+
+def short_schema(name: str) -> str:
+    """Remove the Admin version prefix from a schema name."""
+    return re.sub(r'^GoogleAnalyticsAdminV1(?:alpha|beta)', '', name)
+
+
+def describe(
+    name: str, api: str | None = None, version: ApiVersion = 'auto'
+) -> dict[str, Any]:
+    """Describe an exact method or schema with references, scopes and ownership."""
+    parts = name.split(':')
+    if len(parts) == 3:
+        api, selected, name = parts
+        if selected not in VERSIONS:
+            raise ToolError('Qualified names use admin|data:v1alpha|v1beta:name.')
+        version = selected
+    elif len(parts) == 2:
+        api, name = parts
+        if '.' in api:
+            api, selected = api.split('.', 1)
+            if selected not in VERSIONS:
+                raise ToolError(
+                    'Qualified names use admin.v1alpha:Name or data.v1beta:Name.'
+                )
+            version = selected
+    for alias, service_name in SERVICES.items():
+        if name.startswith(f'{service_name}.'):
+            api = alias
+            name = name.removeprefix(f'{service_name}.')
+            break
+    if api is not None and api not in SERVICES:
+        raise ToolError('api must be admin or data.')
+    matches = [m for m in methods() if (api is None or m.api == api) and m.id == name]
+    if matches:
+        apis = {m.api for m in matches}
+        if len(apis) != 1:
+            raise ToolError('Qualify the method with api=admin or data.')
+        chosen = method(next(iter(apis)), name, version)
+        return {
+            'method': chosen.key,
+            'tool': chosen.owner,
+            'available_versions': sorted({m.version for m in matches}),
+            **chosen.spec,
+            'request_schema': chosen.schema(chosen.request_schema)
+            if chosen.request_schema
+            else None,
+            'response_schema': chosen.schema(chosen.response_schema)
+            if chosen.response_schema
+            else None,
+        }
+    schemas: list[tuple[str, Version, str, dict[str, Any]]] = []
+    for service in SERVICES:
+        if api and service != api:
+            continue
+        for selected in VERSIONS:
+            if version != 'auto' and version != selected:
+                continue
+            for identity, schema in document(service, selected)['schemas'].items():
+                if name in {identity, short_schema(identity)}:
+                    schemas.append((service, selected, identity, schema))
+    if not schemas:
+        raise ToolError(
+            f'Unknown schema or method: {name}. Use a discovery name, e.g. Audience or properties.runReport.'
+        )
+    if len({s[0] for s in schemas}) > 1:
+        raise ToolError(f'{name} exists in both APIs. Specify api=admin or data.')
+    service, selected, identity, schema = schemas[0]
+    return {'api': service, 'api_version': selected, 'name': identity, **schema}

google_analytics_mcp_server/client.py

@@ -0,0 +1,207 @@
+"""One authorized execution path with policy, serialization and bounded retries."""
+
+import json
+import random
+import threading
+import time
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+import httplib2
+from google.auth.exceptions import RefreshError, TransportError
+from google_auth_httplib2 import AuthorizedHttp
+from googleapiclient.discovery import build_from_document, fix_method_name, key2param
+from googleapiclient.errors import HttpError
+from mcp.server.mcpserver.exceptions import ToolError
+
+from google_analytics_mcp_server import (
+    auth,
+    catalog,
+    config,
+    contracts,
+    package_version,
+    policy,
+)
+from google_analytics_mcp_server.capabilities import TRANSPORT_OVERRIDES
+from google_analytics_mcp_server.catalog import Method
+
+_lock = threading.RLock()
+_services: dict[tuple[str, str], Any] = {}
+
+
+def service(item: Method) -> Any:
+    """Build the exact vendored service while holding the transport lock."""
+    key = (item.api, item.version)
+    if key not in _services:
+        transport = httplib2.Http(timeout=config.positive_int('HTTP_TIMEOUT', 60))
+        _services[key] = build_from_document(
+            json.dumps(catalog.document(*key)),
+            http=AuthorizedHttp(auth.credentials(), http=transport),
+        )
+    return _services[key]
+
+
+def execute(
+    item: Method,
+    params: dict[str, Any] | None = None,
+    body: dict[str, Any] | None = None,
+    *,
+    confirm: bool = False,
+) -> dict[str, Any]:
+    """Send a validated request; native and raw calls both enter here."""
+    config.validate_limits()
+    wire_params = dict(params or {})
+    policy.guard(item, wire_params, body, confirm)
+    available = {
+        **catalog.document(item.api, item.version).get('parameters', {}),
+        **item.parameters,
+    }
+    unknown = set(wire_params) - set(available)
+    if unknown:
+        raise ToolError(
+            f'{item.key} has no query/path parameter: {", ".join(sorted(unknown))}.'
+        )
+    if set(wire_params) & TRANSPORT_OVERRIDES:
+        raise ToolError(
+            'Authentication and upload transport overrides are not supported; configure ADC on the server.'
+        )
+    if wire_params.get('alt', 'json') != 'json':
+        raise ToolError('MCP responses require alt=json.')
+    for key, spec in item.parameters.items():
+        if spec.get('required') and key not in wire_params:
+            raise ToolError(f'{item.key} requires parameter {key}.')
+    wire_params = {
+        k: contracts.validate(
+            v,
+            {'type': 'array', 'items': available[k]}
+            if available[k].get('repeated')
+            else available[k],
+            item,
+            k,
+        )
+        for k, v in wire_params.items()
+    }
+    if body is not None and not item.request_schema:
+        raise ToolError(f'{item.id} does not accept a body.')
+    if item.request_schema:
+        body = contracts.validate(
+            body if body is not None else {}, {'$ref': item.request_schema}, item
+        )
+        contracts.enforce_request(item, body, wire_params)
+    # Run the policy on the exact normalized payload that is about to be sent.
+    policy.guard(item, wire_params, body, confirm)
+    with _lock:
+        try:
+            resource = service(item)
+            for part in item.resource.split('.'):
+                resource = getattr(resource, fix_method_name(part))()
+            kwargs = {key2param(k): v for k, v in wire_params.items()}
+            if body is not None:
+                kwargs['body'] = body
+            request = getattr(resource, fix_method_name(item.name))(**kwargs)
+            request.headers['user-agent'] = (
+                f'google-analytics-mcp-server/{package_version()}'
+            )
+            return _send(request, item)
+        except RefreshError as error:
+            raise ToolError(
+                f'Google credentials could not refresh. {auth.setup_hint()}'
+            ) from error
+        except (TypeError, ValueError) as error:
+            raise ToolError(f'{item.key}: {error}') from error
+        except (OSError, httplib2.HttpLib2Error, TransportError) as error:
+            hint = (
+                ''
+                if policy.is_read(item)
+                else ' The outcome may be unknown; inspect the target before repeating this mutation.'
+            )
+            raise ToolError(
+                f'Network request to {catalog.SERVICES[item.api]}.googleapis.com failed: {error}.{hint}'
+            ) from error
+
+
+def _retry_delay(error: HttpError, attempt: int) -> float:
+    value = error.resp.get('retry-after')
+    if value:
+        try:
+            return max(0.0, float(value))
+        except ValueError:
+            try:
+                return max(
+                    0.0,
+                    (parsedate_to_datetime(value) - datetime.now(UTC)).total_seconds(),
+                )
+            except ValueError, TypeError:
+                pass
+    return min(16.0, 2.0**attempt + random.random())
+
+
+def _retry_limit(error: HttpError, item: Method) -> int:
+    if not policy.is_read(item):
+        return 0
+    status = int(error.resp.status)
+    text = error.content.decode('utf-8', errors='replace').lower()
+    if status in {429, 403}:
+        if any(
+            word in text
+            for word in (
+                'token',
+                'daily',
+                'per day',
+                'per hour',
+                'threshold',
+                'server error',
+            )
+        ):
+            return 0
+        if 'concurrent' in text:
+            return 3
+        if item.api == 'admin' and any(
+            word in text for word in ('ratelimitexceeded', 'rate limit', 'per minute')
+        ):
+            return 5
+        return 0
+    if 500 <= status < 600:
+        return 1 if item.api == 'data' or item.name == 'runAccessReport' else 3
+    return 0
+
+
+def _send(request: Any, item: Method) -> dict[str, Any]:
+    attempt = 0
+    while True:
+        try:
+            response = request.execute(num_retries=0)
+            return response if isinstance(response, dict) else {'response': response}
+        except HttpError as error:
+            if attempt < _retry_limit(error, item):
+                delay = _retry_delay(error, attempt)
+                if delay <= 30:
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+            message = error.content.decode('utf-8', errors='replace')
+            try:
+                data = json.loads(message).get('error', {})
+                message = data.get('message', message)
+            except json.JSONDecodeError, AttributeError:
+                pass
+            hints = ''
+            lower = error.content.decode('utf-8', errors='replace').lower()
+            if 'scope' in lower:
+                hints = f' Required scopes: {item.spec.get("scopes", [])}. {auth.setup_hint()}'
+            elif 'service_disabled' in lower or 'accessnotconfigured' in lower:
+                hints = f' Enable {catalog.SERVICES[item.api]}.googleapis.com on the project named in the error.'
+            elif error.resp.status == 403:
+                hints = ' Check the account/property role and any Analytics 360 or preview eligibility.'
+            elif error.resp.status == 400:
+                hints = ' Inspect ga_describe_schema; report dimensions/metrics can be checked with ga_get_metadata and ga_check_compatibility.'
+            elif error.resp.status == 404:
+                hints = ' Copy an existing resource name from ga_list.'
+            elif error.resp.status == 429:
+                hints = ' Do not retry exhausted or unknown quotas. Hourly quotas refresh within an hour, not necessarily at a whole-hour boundary.'
+            if error.resp.status >= 500 and not policy.is_read(item):
+                hints += ' The mutation was not retried. Its outcome may be unknown; inspect the target before repeating it.'
+            raise ToolError(
+                f'{item.key}: HTTP {error.resp.status}: {message}.{hints}'
+            ) from error