platform-mcp 0.2.0__py3-none-any.whl

platform_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Read-only GCP platform-engineer MCP server."""
+
+__version__ = "0.2.0"

platform_mcp/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

platform_mcp/clients.py

@@ -0,0 +1,116 @@
+"""Lazy, per-environment GCP client factory.
+
+Base credentials are resolved once via Application Default Credentials. If
+``GOOGLE_APPLICATION_CREDENTIALS`` points at a service-account key, google-auth
+picks it up automatically. Each configured environment may name its own
+read-only service account to impersonate, so staging and production are reached
+through separate identities from the same process.
+
+Every getter takes the resolved :class:`~platform_mcp.config.Environment` and is
+cached per environment: switching back and forth costs nothing after the first
+call, and no client is ever shared across projects.
+
+Every client returned here is read-only in practice: the server never calls a
+mutating method, and this is paired with viewer-only IAM identities.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import google.auth
+from google.auth import impersonated_credentials
+
+from .config import Environment
+
+_SCOPES = ["https://www.googleapis.com/auth/cloud-platform"]
+
+# Number of distinct environments to keep clients for. Generous relative to any
+# realistic registry, so caches never thrash between staging and production.
+_CACHE_SIZE = 16
+
+
+@lru_cache(maxsize=1)
+def _base_credentials():
+    creds, _ = google.auth.default(scopes=_SCOPES)
+    return creds
+
+
+@lru_cache(maxsize=_CACHE_SIZE)
+def get_credentials(impersonate: str = ""):
+    """Credentials for a target identity; impersonates when one is configured."""
+    creds = _base_credentials()
+    if impersonate:
+        creds = impersonated_credentials.Credentials(
+            source_credentials=creds,
+            target_principal=impersonate,
+            target_scopes=_SCOPES,
+        )
+    return creds
+
+
+def _creds_for(env: Environment):
+    return get_credentials(env.impersonate)
+
+
+@lru_cache(maxsize=_CACHE_SIZE)
+def get_logging_client(env: Environment):
+    from google.cloud import logging_v2
+
+    return logging_v2.Client(project=env.project, credentials=_creds_for(env))
+
+
+@lru_cache(maxsize=_CACHE_SIZE)
+def get_error_stats_client(env: Environment):
+    from google.cloud import errorreporting_v1beta1
+
+    return errorreporting_v1beta1.ErrorStatsServiceClient(credentials=_creds_for(env))
+
+
+@lru_cache(maxsize=_CACHE_SIZE)
+def get_metric_client(env: Environment):
+    from google.cloud import monitoring_v3
+
+    return monitoring_v3.MetricServiceClient(credentials=_creds_for(env))
+
+
+@lru_cache(maxsize=_CACHE_SIZE)
+def get_alert_policy_client(env: Environment):
+    from google.cloud import monitoring_v3
+
+    return monitoring_v3.AlertPolicyServiceClient(credentials=_creds_for(env))
+
+
+@lru_cache(maxsize=_CACHE_SIZE)
+def get_uptime_client(env: Environment):
+    from google.cloud import monitoring_v3
+
+    return monitoring_v3.UptimeCheckServiceClient(credentials=_creds_for(env))
+
+
+@lru_cache(maxsize=_CACHE_SIZE)
+def get_recommender_client(env: Environment):
+    from google.cloud import recommender_v1
+
+    return recommender_v1.RecommenderClient(credentials=_creds_for(env))
+
+
+@lru_cache(maxsize=_CACHE_SIZE)
+def get_asset_client(env: Environment):
+    from google.cloud import asset_v1
+
+    return asset_v1.AssetServiceClient(credentials=_creds_for(env))
+
+
+@lru_cache(maxsize=_CACHE_SIZE)
+def get_billing_client(env: Environment):
+    from google.cloud import billing_v1
+
+    return billing_v1.CloudBillingClient(credentials=_creds_for(env))
+
+
+@lru_cache(maxsize=_CACHE_SIZE)
+def get_bigquery_client(env: Environment):
+    from google.cloud import bigquery
+
+    return bigquery.Client(project=env.project, credentials=_creds_for(env))

platform_mcp/config.py

@@ -0,0 +1,329 @@
+"""Runtime settings for the platform-mcp server.
+
+Holds a registry of named GCP environments (staging, production, ...) so a
+single server process can answer questions about any of them. Every tool takes
+an optional ``environment`` argument that is resolved here; when it is omitted
+the configured default environment is used.
+
+The registry comes from ``PLATFORM_MCP_ENVIRONMENTS``, a JSON object mapping an
+environment name to its settings::
+
+    {
+      "staging": {
+        "project": "my-app-staging",
+        "impersonate": "platform-mcp-ro@my-app-staging.iam.gserviceaccount.com"
+      },
+      "production": {
+        "project": "my-app",
+        "impersonate": "platform-mcp-ro@my-app.iam.gserviceaccount.com",
+        "billing_export_table": "my-app.billing.gcp_billing_export_v1_XXXXXX",
+        "aliases": ["live"]
+      }
+    }
+
+A value may also be a bare project-id string when no impersonation is needed.
+If ``PLATFORM_MCP_ENVIRONMENTS`` is unset the server falls back to the original
+single-project behaviour (``GCP_PROJECT`` + ``IMPERSONATE_SERVICE_ACCOUNT``),
+exposed as one environment named ``default``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tomllib
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+
+# Where the config file lives when PLATFORM_MCP_CONFIG does not name one.
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "platform-mcp" / "config.toml"
+
+_PROJECT_ENV_VARS = (
+    "GCP_PROJECT",
+    "GOOGLE_CLOUD_PROJECT",
+    "GOOGLE_CLOUD_QUOTA_PROJECT",
+    "GCLOUD_PROJECT",
+)
+
+# Spoken shorthands an agent is likely to pick up from a prompt ("check prod").
+# Listed in both directions so the environment can be named either way, and
+# only applied when they do not collide with a real environment name.
+_BUILTIN_ALIASES = {
+    "prod": "production",
+    "prd": "production",
+    "live": "production",
+    "production": "prod",
+    "stg": "staging",
+    "stage": "staging",
+    "qa": "staging",
+    "staging": "stage",
+    "dev": "development",
+    "development": "dev",
+    "test": "testing",
+    "testing": "test",
+}
+
+
+@dataclass(frozen=True)
+class Environment:
+    """One resolvable GCP target: a project plus how to authenticate to it."""
+
+    name: str
+    project: str
+    impersonate: str = ""
+    billing_export_table: str = ""
+    aliases: tuple[str, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class Settings:
+    environments: tuple[Environment, ...]
+    default_environment: str
+    default_location: str = "global"
+    default_limit: int = 50
+
+
+def _adc_project() -> str:
+    """Project associated with Application Default Credentials, if any."""
+    try:
+        import google.auth
+
+        _, project = google.auth.default()
+        return str(project) if project else ""
+    except Exception:
+        return ""
+
+
+def _resolve_single_project() -> str:
+    for var in _PROJECT_ENV_VARS:
+        value = os.environ.get(var)
+        if value:
+            return value
+    # Fall back to the ADC-associated project so the server still works with a
+    # bare `gcloud auth application-default login` and no explicit config.
+    return _adc_project()
+
+
+def _parse_registry(raw: str) -> tuple[Environment, ...]:
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(
+            f"PLATFORM_MCP_ENVIRONMENTS is not valid JSON: {exc}"
+        ) from exc
+    if not isinstance(parsed, dict) or not parsed:
+        raise RuntimeError(
+            "PLATFORM_MCP_ENVIRONMENTS must be a non-empty JSON object mapping "
+            'environment name -> settings, e.g. {"staging": {"project": "..."}}'
+        )
+
+    # Global values act as the fallback for environments that don't set them,
+    # which keeps a pre-existing single-project config working unchanged.
+    global_impersonate = os.environ.get("IMPERSONATE_SERVICE_ACCOUNT", "").strip()
+    global_billing = os.environ.get("BILLING_EXPORT_TABLE", "").strip()
+
+    environments = []
+    for name, spec in parsed.items():
+        key = str(name).strip().lower()
+        if not key:
+            continue
+        if isinstance(spec, str):
+            spec = {"project": spec}
+        if not isinstance(spec, dict):
+            raise RuntimeError(
+                f"PLATFORM_MCP_ENVIRONMENTS['{name}'] must be an object or a "
+                "project-id string."
+            )
+        project = str(spec.get("project", "")).strip()
+        if not project:
+            raise RuntimeError(
+                f"PLATFORM_MCP_ENVIRONMENTS['{name}'] is missing a 'project'."
+            )
+        aliases = spec.get("aliases") or []
+        if isinstance(aliases, str):
+            aliases = [aliases]
+        environments.append(
+            Environment(
+                name=key,
+                project=project,
+                impersonate=str(spec.get("impersonate", "") or global_impersonate).strip(),
+                billing_export_table=str(
+                    spec.get("billing_export_table", "") or global_billing
+                ).strip(),
+                aliases=tuple(str(a).strip().lower() for a in aliases if str(a).strip()),
+            )
+        )
+    if not environments:
+        raise RuntimeError("PLATFORM_MCP_ENVIRONMENTS defined no usable environments.")
+    return tuple(environments)
+
+
+def config_path() -> Path:
+    """Path of the config file, whether or not it exists."""
+    override = os.environ.get("PLATFORM_MCP_CONFIG", "").strip()
+    return Path(override).expanduser() if override else DEFAULT_CONFIG_PATH
+
+
+def _load_config_file() -> dict:
+    """Read the TOML config file, or return an empty mapping if there is none.
+
+    A config file is far kinder than a JSON blob squeezed into an environment
+    variable, and it can be committed and shared across a team. Environment
+    variables still win, so an existing setup keeps working and a one-off
+    override needs no edit.
+    """
+    path = config_path()
+    try:
+        raw = path.read_bytes()
+    except FileNotFoundError:
+        return {}
+    except OSError as exc:
+        raise RuntimeError(f"Could not read config file {path}: {exc}") from exc
+    try:
+        parsed = tomllib.loads(raw.decode("utf-8"))
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        raise RuntimeError(f"Config file {path} is not valid TOML: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise RuntimeError(f"Config file {path} must define a TOML table.")
+    return parsed
+
+
+def _environments_from_file(file_config: dict) -> tuple[Environment, ...]:
+    table = file_config.get("environments")
+    if not table:
+        return ()
+    if not isinstance(table, dict):
+        raise RuntimeError(
+            "The [environments] section of the config file must be a table of "
+            'named environments, e.g. [environments.staging].'
+        )
+    # Reuse the JSON parser so file and environment variable cannot drift apart.
+    return _parse_registry(json.dumps(table))
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    file_config = _load_config_file()
+
+    limit_raw = os.environ.get("PLATFORM_MCP_DEFAULT_LIMIT", "").strip()
+    if not limit_raw:
+        limit_raw = str(file_config.get("default_limit", 50))
+    try:
+        default_limit = max(1, int(limit_raw))
+    except ValueError:
+        default_limit = 50
+
+    raw_registry = os.environ.get("PLATFORM_MCP_ENVIRONMENTS", "").strip()
+    file_environments = _environments_from_file(file_config)
+    if raw_registry:
+        environments = _parse_registry(raw_registry)
+    elif file_environments:
+        environments = file_environments
+    else:
+        environments = (
+            Environment(
+                name="default",
+                project=_resolve_single_project(),
+                impersonate=os.environ.get("IMPERSONATE_SERVICE_ACCOUNT", "").strip(),
+                billing_export_table=os.environ.get("BILLING_EXPORT_TABLE", "").strip(),
+            ),
+        )
+
+    requested_default = os.environ.get("PLATFORM_MCP_DEFAULT_ENVIRONMENT", "").strip().lower()
+    if not requested_default:
+        requested_default = str(file_config.get("default_environment", "")).strip().lower()
+    known = {e.name for e in environments}
+    if requested_default and requested_default not in known:
+        raise RuntimeError(
+            f"PLATFORM_MCP_DEFAULT_ENVIRONMENT='{requested_default}' is not one of "
+            f"the configured environments: {sorted(known)}"
+        )
+    # With no explicit default, prefer the safest target when it exists rather
+    # than silently defaulting to whichever key happened to be listed first.
+    if requested_default:
+        default_environment = requested_default
+    elif "staging" in known:
+        default_environment = "staging"
+    else:
+        default_environment = environments[0].name
+
+    return Settings(
+        environments=environments,
+        default_environment=default_environment,
+        default_location=os.environ.get("GCP_LOCATION", "global"),
+        default_limit=default_limit,
+    )
+
+
+@lru_cache(maxsize=1)
+def _lookup_table() -> dict[str, Environment]:
+    """Map every accepted spelling of an environment to its Environment."""
+    environments = get_settings().environments
+    table: dict[str, Environment] = {}
+    for env in environments:
+        table[env.name] = env
+        for alias in env.aliases:
+            table.setdefault(alias, env)
+        # Let the agent name the project id directly ("check my-app-prod").
+        if env.project:
+            table.setdefault(env.project.lower(), env)
+    for alias, canonical in _BUILTIN_ALIASES.items():
+        if canonical in table:
+            table.setdefault(alias, table[canonical])
+    return table
+
+
+def list_environments() -> tuple[Environment, ...]:
+    return get_settings().environments
+
+
+def resolve_environment(name: str = "") -> Environment:
+    """Resolve an environment name (or alias, or project id) to an Environment.
+
+    An empty name yields the default environment. Unknown names raise a
+    ``ValueError`` naming the valid options rather than silently falling back,
+    so a typo can never send a production question to staging or vice versa.
+    """
+    settings = get_settings()
+    key = (name or "").strip().lower()
+    table = _lookup_table()
+
+    if not key:
+        env = table.get(settings.default_environment)
+        if env is None:  # pragma: no cover - guarded by get_settings()
+            raise RuntimeError("No environments are configured.")
+    else:
+        env = table.get(key)
+        if env is None:
+            valid = sorted({e.name for e in settings.environments})
+            raise ValueError(
+                f"Unknown environment '{name}'. Configured environments: "
+                f"{', '.join(valid)}."
+            )
+
+    if not env.project:
+        raise RuntimeError(
+            f"Environment '{env.name}' has no GCP project configured. Set "
+            "PLATFORM_MCP_ENVIRONMENTS (or GCP_PROJECT for single-project mode)."
+        )
+    return env
+
+
+def require_project(environment: str = "") -> str:
+    """Return the project id for an environment, raising if it is unset."""
+    return resolve_environment(environment).project
+
+
+def describe_environments() -> str:
+    """One-line-per-environment summary used in the server instructions."""
+    settings = get_settings()
+    try:
+        environments = settings.environments
+    except RuntimeError:  # pragma: no cover - defensive
+        return ""
+    lines = []
+    for env in environments:
+        marker = " (default)" if env.name == settings.default_environment else ""
+        lines.append(f"- {env.name}{marker}: project {env.project}")
+    return "\n".join(lines)

platform_mcp/diagnostics.py

@@ -0,0 +1,173 @@
+"""``platform-mcp doctor``: check that this machine can actually reach GCP.
+
+Every prerequisite here fails at a different layer -- credentials, IAM, API
+enablement, cross-project BigQuery grants -- and each one produces a different
+opaque error at the first tool call. Checking them up front, per environment,
+with the fix printed next to the failure, is the difference between onboarding
+in a minute and onboarding in a support thread.
+
+This runs as a CLI command, not over the protocol, so printing to stdout here
+is safe. The server itself must never do that.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .config import Environment, config_path, get_settings
+
+OK = "  ok  "
+FAIL = " FAIL "
+SKIP = " skip "
+
+
+def _line(status: str, message: str) -> None:
+    print(f"[{status}] {message}")
+
+
+def _fix(text: str) -> None:
+    for line in text.strip().splitlines():
+        print(f"         {line}")
+
+
+def _check_adc() -> bool:
+    try:
+        import google.auth
+
+        credentials, project = google.auth.default(
+            scopes=["https://www.googleapis.com/auth/cloud-platform"]
+        )
+    except Exception as exc:
+        _line(FAIL, "Application Default Credentials")
+        _fix(f"{exc}\nFix:  gcloud auth application-default login")
+        return False
+    kind = type(credentials).__name__
+    _line(OK, f"Application Default Credentials ({kind}, quota project: {project or 'unset'})")
+    if not project:
+        _fix(
+            "No quota project is set. Some APIs bill quota to it and will fail "
+            "without one.\nFix:  gcloud auth application-default set-quota-project PROJECT_ID"
+        )
+    return True
+
+
+def _check_impersonation(env: Environment) -> bool:
+    if not env.impersonate:
+        _line(SKIP, "impersonation not configured (using your own credentials)")
+        return True
+    from google.auth.transport.requests import Request
+
+    from .clients import get_credentials
+
+    try:
+        credentials = get_credentials(env.impersonate)
+        credentials.refresh(Request())
+    except Exception as exc:
+        _line(FAIL, f"impersonate {env.impersonate}")
+        _fix(
+            f"{str(exc)[:200]}\n"
+            "Fix:  gcloud iam service-accounts add-iam-policy-binding \\\n"
+            f"        {env.impersonate} \\\n"
+            "        --member=user:YOUR_EMAIL \\\n"
+            "        --role=roles/iam.serviceAccountTokenCreator"
+        )
+        return False
+    _line(OK, f"impersonate {env.impersonate}")
+    return True
+
+
+def _check_read_api(env: Environment) -> bool:
+    """One real read, so API enablement and viewer roles are proven, not assumed."""
+    try:
+        from google.cloud import logging_v2
+
+        from .clients import get_logging_client
+
+        client = get_logging_client(env)
+        entries = client.list_entries(
+            filter_="timestamp>=\"1970-01-01T00:00:00Z\"",
+            order_by=logging_v2.DESCENDING,
+            max_results=1,
+            page_size=1,
+        )
+        next(iter(entries), None)
+    except Exception as exc:
+        _line(FAIL, f"read Cloud Logging in {env.project}")
+        _fix(
+            f"{str(exc)[:200]}\n"
+            f"Fix:  grant roles/logging.viewer on {env.project} to "
+            f"{env.impersonate or 'your user'}, and enable the Cloud Logging API."
+        )
+        return False
+    _line(OK, f"read Cloud Logging in {env.project}")
+    return True
+
+
+def _check_billing_export(env: Environment) -> bool:
+    if not env.billing_export_table:
+        _line(SKIP, "billing export not configured (get_cost_breakdown unavailable)")
+        return True
+    try:
+        from google.cloud import bigquery
+
+        from .clients import get_bigquery_client
+
+        client = get_bigquery_client(env)
+        # A dry run costs nothing and still proves both grants: permission to
+        # start a job here, and permission to read a table that usually lives
+        # in a different project.
+        job_config = bigquery.QueryJobConfig(dry_run=True, use_query_cache=False)
+        client.query(
+            f"SELECT cost FROM `{env.billing_export_table}` LIMIT 1",
+            job_config=job_config,
+        )
+    except Exception as exc:
+        _line(FAIL, f"read billing export {env.billing_export_table}")
+        _fix(
+            f"{str(exc)[:200]}\n"
+            f"Fix:  the identity needs roles/bigquery.jobUser on {env.project} "
+            "AND roles/bigquery.dataViewer on the dataset holding the export "
+            "(often a different project)."
+        )
+        return False
+    _line(OK, f"read billing export {env.billing_export_table}")
+    return True
+
+
+def run_doctor() -> int:
+    """Print a per-environment readiness report. Returns a process exit code."""
+    path = config_path()
+    print("platform-mcp doctor")
+    print(f"config file: {path}{'' if path.exists() else '  (not found)'}")
+    print()
+
+    try:
+        settings = get_settings()
+    except Exception as exc:
+        _line(FAIL, "configuration")
+        _fix(str(exc))
+        return 1
+
+    healthy = _check_adc()
+    print()
+
+    for env in settings.environments:
+        marker = " (default)" if env.name == settings.default_environment else ""
+        print(f"environment: {env.name}{marker} -> {env.project}")
+        results = [
+            _check_impersonation(env),
+            _check_read_api(env),
+            _check_billing_export(env),
+        ]
+        healthy = healthy and all(results)
+        print()
+
+    if healthy:
+        print("All checks passed.")
+        return 0
+    print("Some checks failed. Fix the items marked FAIL above, then re-run.")
+    return 1
+
+
+def main() -> None:  # pragma: no cover - thin CLI wrapper
+    sys.exit(run_doctor())