"""Solution Architecture Google Cloud ================================== Google Cloud documentation and read-only estate tools for the Solution Architecture agent, through Google's hosted MCP servers. Generated by Agent Builder Platform - MCP Server Builder Version: 0.1.0 Template: mcp-server-template 1.1.0 Features: - JSON-RPC 2.0 over HTTP (MCP standard) - Bearer token authentication - Health check endpoint - Structured logging (JSON, one object per line) Environment Variables: - MCP_REGISTRATION_API_KEY: Authentication key for Gateway registration (required) - MCP_SERVER_PORT: Server port (default: 8115) - MCP_SERVER_NAME: Display name for the server - LOG_LEVEL: Logging level (default: INFO) - LOG_FORMAT: json (default) or console """ import os import re import sys import json import inspect import time import traceback import asyncio import logging import secrets from typing import Dict, Any, List, Optional, Union # noqa: F401 from collections import OrderedDict from contextlib import asynccontextmanager from datetime import datetime, timezone import structlog from fastapi import FastAPI, HTTPException, Depends, Request from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials from pydantic import BaseModel, Field, StrictInt, StrictStr import mcp_connection # Additional imports from tool implementations import base64 import hashlib from google.auth.transport.requests import Request as GoogleRequest from google.oauth2 import service_account import httpx TEMPLATE_VERSION = '1.1.0' # What this server needs to reach its upstream, advertised to the gateway on initialize (None: nothing) CONNECTION_SCHEMA = {'type': 'object', 'title': 'Solution Architecture Google Cloud', 'description': 'Google Cloud documentation and read-only estate tools for the ' "Solution Architecture agent, through Google's hosted MCP servers.", 'properties': {'service_account_json': {'type': 'string', 'title': 'Service account key', 'description': 'The read-only service ' "account's JSON key.", 'writeOnly': True, 'format': 'password'}, 'scope_root': {'type': 'string', 'title': 'Scope root', 'description': 'organizations/, folders/ or ' 'projects/.'}, 'quota_project': {'type': 'string', 'title': 'Quota project', 'description': 'Sent as X-Goog-User-Project. ' 'Optional.'}, 'docs_api_key': {'type': 'string', 'title': 'Documentation API key', 'description': 'Developer Knowledge API key. Without ' 'it, the service account signs in.', 'writeOnly': True, 'format': 'password'}}, 'required': ['service_account_json', 'scope_root'], 'additionalProperties': False} VERIFY_TOOL = 'verify_connection' # ============================================ # Configuration # ============================================ def _load_env_file() -> None: """Read the `.env` next to this file, so `cp .env.example .env` and `python server.py` work. Variables that are already set win, so a container's or a pipeline's settings are never overridden. The image does not contain a `.env`, so this does nothing there. """ path = globals().get("__file__") if not path: return try: from dotenv import load_dotenv except ImportError: return load_dotenv(os.path.join(os.path.dirname(os.path.abspath(path)), ".env")) _load_env_file() class Config: """Server configuration from environment variables""" # Server Identity SERVER_ID = os.getenv("MCP_SERVER_ID", 'sa-gcp-cloud') SERVER_NAME = os.getenv("MCP_SERVER_NAME", 'Solution Architecture Google Cloud') SERVER_VERSION = os.getenv("MCP_SERVER_VERSION", '0.1.0') # MCP_SERVER_PORT, or SERVER_PORT as the ConfigMaps in the tools repo name it SERVER_PORT = int(os.getenv("MCP_SERVER_PORT") or os.getenv("SERVER_PORT") or "8115") # Authentication (REQUIRED for MCP Gateway registration) # Generate secure key: openssl rand -hex 32 MCP_REGISTRATION_API_KEY = os.getenv("MCP_REGISTRATION_API_KEY", "").strip() # The placeholder from .env.example is not a key: a server started with it unchanged has no key. if MCP_REGISTRATION_API_KEY.startswith("<"): MCP_REGISTRATION_API_KEY = "" # Feature Flags REQUIRE_AUTH = os.getenv("REQUIRE_AUTH", "true").lower() == "true" # Applies when CONNECTION_SCHEMA is set: refuse a call that arrives without the tenant's connection # instead of falling back to this server's own environment. Set to false only for local runs. REQUIRE_VAULT_CONNECTION = os.getenv("REQUIRE_VAULT_CONNECTION", "true").lower() == "true" # Logging: LOG_FORMAT is "json" (one object per line, for log stores) or "console" (for reading by eye) LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper() LOG_FORMAT = os.getenv("LOG_FORMAT", "json").lower() config = Config() # ============================================ # Logging Configuration # ============================================ def sanitize_log(value: Any, max_length: int = 200) -> str: """Make a caller-supplied value safe to log: one line, no control characters, bounded.""" if not isinstance(value, str): value = str(value) # Written with .replace() because that is the pattern CodeQL recognises as a # barrier for py/log-injection (CWE-117). value = value.replace("\n", "").replace("\r", "") return re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]", "", value)[:max_length] def _add_server_identity(_logger, _method, event_dict): event_dict.setdefault("server_id", config.SERVER_ID) event_dict.setdefault("server_name", config.SERVER_NAME) event_dict.setdefault("server_version", config.SERVER_VERSION) return event_dict _LEADING_KEYS = ( "timestamp", "level", "event", "logger", "server_id", "server_name", "server_version", "request_id", "method", "tool", ) def _scrub_secrets(_logger, _method, event_dict): """The last step before a line is written: no credential reaches the log, whoever logged it.""" return mcp_connection.scrub(event_dict) def _lead_with_common_keys(_logger, _method, event_dict): """Every line starts with the same fields in the same order; the event's own follow.""" lead = {key: event_dict.pop(key) for key in _LEADING_KEYS if key in event_dict} lead.update(event_dict) return lead def configure_logging() -> None: """Send every log line, ours and the libraries', to stdout in one format.""" level = getattr(logging, config.LOG_LEVEL, logging.INFO) shared = [ structlog.contextvars.merge_contextvars, structlog.stdlib.add_logger_name, structlog.stdlib.add_log_level, structlog.processors.TimeStamper(fmt="iso", utc=True), _add_server_identity, ] renderer = ( structlog.dev.ConsoleRenderer(colors=False) if config.LOG_FORMAT == "console" else structlog.processors.JSONRenderer() ) structlog.configure( processors=shared + [ structlog.stdlib.PositionalArgumentsFormatter(), structlog.processors.StackInfoRenderer(), structlog.processors.format_exc_info, structlog.stdlib.ProcessorFormatter.wrap_for_formatter, ], logger_factory=structlog.stdlib.LoggerFactory(), wrapper_class=structlog.stdlib.BoundLogger, cache_logger_on_first_use=True, ) handler = logging.StreamHandler(sys.stdout) handler.mcp_server_handler = True handler.setFormatter(structlog.stdlib.ProcessorFormatter( foreign_pre_chain=shared, processors=[ structlog.stdlib.ProcessorFormatter.remove_processors_meta, structlog.processors.format_exc_info, _lead_with_common_keys, _scrub_secrets, renderer, ], )) root = logging.getLogger() root.handlers = [h for h in root.handlers if not getattr(h, "mcp_server_handler", False)] + [handler] root.setLevel(level) # httpx logs every request URL at INFO, and an upstream URL often carries a key: keep those lines for DEBUG for name in ("httpx", "httpcore"): logging.getLogger(name).setLevel(level if level <= logging.DEBUG else logging.WARNING) # uvicorn installs its own handlers; route them through ours so every line has the same shape for name in ("uvicorn", "uvicorn.error", "uvicorn.access"): uvicorn_logger = logging.getLogger(name) uvicorn_logger.handlers.clear() uvicorn_logger.propagate = True configure_logging() logger = structlog.get_logger(__name__) # ============================================ # Per-request connection # ============================================ CONNECTION_METHODS = ("tools/call", "resources/read", "prompts/get") def get_connection() -> Dict[str, Any]: """The connection fields the gateway sent with this request; empty when it sent none.""" return dict(mcp_connection.active() or {}) _client_cache: "OrderedDict[str, Any]" = OrderedDict() _CLIENT_CACHE_MAX = 32 def get_upstream_client(kind, build): """The upstream client of type `kind` for this request's connection. `build(connection)` runs once per distinct (kind, connection), so two tools that talk to different upstreams with the same tenant connection each get their own client. """ if not isinstance(kind, str) or not kind: raise TypeError("get_upstream_client needs a client kind, for example get_upstream_client('jira', build)") key = f"{kind}:{mcp_connection.fingerprint(mcp_connection.active())}" client = _client_cache.get(key) if client is None: client = build(get_connection()) _client_cache[key] = client while len(_client_cache) > _CLIENT_CACHE_MAX: _close_client(_client_cache.popitem(last=False)[1]) else: _client_cache.move_to_end(key) return client _closing_tasks: set = set() def _close_client(client) -> None: """Release the connections of a client that left the cache (an httpx client holds a pool of sockets). Closes with `aclose()`, `close()` or `dispose()` (an httpx client, most clients, a SQLAlchemy engine); a client with none of them is left to the garbage collector. A failure to close is logged and never reaches the request that happened to evict it. """ close = getattr(client, "aclose", None) or getattr(client, "close", None) or getattr(client, "dispose", None) if close is None: return try: result = close() if inspect.isawaitable(result): try: task = asyncio.get_running_loop().create_task(result) except RuntimeError: # no loop to run it on result.close() return _closing_tasks.add(task) # a task nobody refers to can be collected before it finishes task.add_done_callback(_closing_tasks.discard) except Exception as error: logger.warning("client_close_failed", error_type=type(error).__name__, error=sanitize_log(error)) async def _close_all_clients() -> None: """On shutdown: close every cached client and wait for the closes already under way.""" while _client_cache: _close_client(_client_cache.popitem(last=False)[1]) if _closing_tasks: await asyncio.gather(*list(_closing_tasks), return_exceptions=True) def check_connection(profile: Optional[Dict[str, Any]]) -> None: """Refuse a call with no connection (unless the environment may be used) or with an incomplete one.""" if not profile: if config.REQUIRE_VAULT_CONNECTION: raise ValueError( "No connection was sent with this request: no credential is stored for this tenant. " "Store one under Credentials, or set REQUIRE_VAULT_CONNECTION=false to use this " "server's own environment." ) return missing = mcp_connection.missing_fields(profile, CONNECTION_SCHEMA) if missing: raise ValueError("The connection sent with this request is missing: " + ", ".join(missing)) def render_prompt(template: str, values: Dict[str, Any]) -> str: """Fill {{name}} markers in a prompt template; a marker with no value is left as written.""" return re.sub( r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}", lambda m: str(values[m.group(1)]) if m.group(1) in values else m.group(0), template, ) # ============================================ # Authentication # ============================================ security = HTTPBearer(auto_error=False) async def verify_mcp_registration_key( credentials: Optional[HTTPAuthorizationCredentials] = Depends(security) ) -> bool: """ Verify MCP registration API key for /messages endpoint. This is the industry-standard Bearer token authentication pattern. """ # Skip auth if disabled (for testing only!) if not config.REQUIRE_AUTH: logger.warning("auth_disabled", detail="testing mode only") return True if not credentials: logger.warning("auth_missing_credentials") raise HTTPException( status_code=401, detail="Missing authentication credentials. Include 'Authorization: Bearer ' header.", headers={"WWW-Authenticate": "Bearer"} ) provided_key = credentials.credentials expected_key = config.MCP_REGISTRATION_API_KEY if not expected_key: logger.error("auth_key_not_configured") raise HTTPException( status_code=500, detail="Server authentication not configured" ) if not secrets.compare_digest(provided_key.encode("utf-8"), expected_key.encode("utf-8")): logger.warning("auth_invalid_key") raise HTTPException( status_code=401, detail="Invalid authentication credentials", headers={"WWW-Authenticate": "Bearer"} ) return True # ============================================ # MCP Protocol Models # ============================================ class MCPRequest(BaseModel): """JSON-RPC 2.0 request (MCP standard)""" jsonrpc: str = "2.0" id: Union[StrictStr, StrictInt] # JSON-RPC allows a string or a number; the reply echoes it unchanged method: str params: Dict[str, Any] = Field(default_factory=dict) class MCPResponse(BaseModel): """JSON-RPC 2.0 response (MCP standard)""" jsonrpc: str = "2.0" id: Union[StrictStr, StrictInt] result: Optional[Dict[str, Any]] = None error: Optional[Dict[str, Any]] = None # ============================================ # Tool Definitions # ============================================ TOOLS_REGISTRY = [ { "name": 'gcp_check_connection', "description": 'Test the stored connection: sign in and open the resource manager server.', "inputSchema": {'type': 'object', 'properties': {}, 'required': []} }, { "name": 'gcp_describe_tool', "description": "Read a hosted tool's live description and argument schema, before calling it.", "inputSchema": {'type': 'object', 'properties': {'server': {'type': 'string', 'description': 'The hosted server, such as compute.'}, 'tool': {'type': 'string', 'description': 'The hosted tool, such as list_instances.'}}, 'required': ['server', 'tool']} }, { "name": 'gcp_developer_knowledge_search_documents', "description": "Google's search_documents on its developer_knowledge MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_developer_knowledge_get_documents', "description": "Google's get_documents on its developer_knowledge MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_developer_knowledge_answer_query', "description": "Google's answer_query on its developer_knowledge MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_resource_manager_search_projects', "description": "Google's search_projects on its resource_manager MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_asset_inventory_list_assets', "description": "Google's list_assets on its asset_inventory MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_asset_inventory_analyze_iam_policy', "description": "Google's analyze_iam_policy on its asset_inventory MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_list_instances', "description": "Google's list_instances on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_get_instance_basic_info', "description": "Google's get_instance_basic_info on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_list_instance_attached_disks', "description": "Google's list_instance_attached_disks on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_list_instance_group_managers', "description": "Google's list_instance_group_managers on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_get_instance_group_manager_basic_info', "description": "Google's get_instance_group_manager_basic_info on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_list_instance_templates', "description": "Google's list_instance_templates on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_get_instance_template_properties', "description": "Google's get_instance_template_properties on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_list_disks', "description": "Google's list_disks on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_get_disk_basic_info', "description": "Google's get_disk_basic_info on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_list_reservations', "description": "Google's list_reservations on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_compute_list_commitments', "description": "Google's list_commitments on its compute MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_gke_list_clusters', "description": "Google's list_clusters on its gke MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_gke_get_cluster', "description": "Google's get_cluster on its gke MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_gke_list_node_pools', "description": "Google's list_node_pools on its gke MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_gke_get_node_pool', "description": "Google's get_node_pool on its gke MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_gke_get_k8s_version', "description": "Google's get_k8s_version on its gke MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_cloud_run_list_services', "description": "Google's list_services on its cloud_run MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_cloud_run_get_service', "description": "Google's get_service on its cloud_run MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_cloud_sql_list_instances', "description": "Google's list_instances on its cloud_sql MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_cloud_sql_get_instance', "description": "Google's get_instance on its cloud_sql MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_storage_list_buckets', "description": "Google's list_buckets on its storage MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_pubsub_list_topics', "description": "Google's list_topics on its pubsub MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_pubsub_get_topic', "description": "Google's get_topic on its pubsub MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_pubsub_list_subscriptions', "description": "Google's list_subscriptions on its pubsub MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_pubsub_get_subscription', "description": "Google's get_subscription on its pubsub MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_iam_list_roles', "description": "Google's list_roles on its iam MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_iam_get_role', "description": "Google's get_role on its iam MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_iam_list_deny_policies', "description": "Google's list_deny_policies on its iam MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_iam_get_deny_policy', "description": "Google's get_deny_policy on its iam MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_monitoring_list_alert_policies', "description": "Google's list_alert_policies on its monitoring MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_monitoring_get_alert_policy', "description": "Google's get_alert_policy on its monitoring MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_monitoring_list_dashboards', "description": "Google's list_dashboards on its monitoring MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_monitoring_list_metric_descriptors', "description": "Google's list_metric_descriptors on its monitoring MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_monitoring_list_timeseries', "description": "Google's list_timeseries on its monitoring MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_network_intelligence_list_connectivity_tests', "description": "Google's list_connectivity_tests on its network_intelligence MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'gcp_network_intelligence_get_connectivity_test', "description": "Google's get_connectivity_test on its network_intelligence MCP server, read-only. Call gcp_describe_tool for its arguments.", "inputSchema": {'type': 'object', 'properties': {'tool_arguments': {'type': 'object', 'description': "The hosted tool's arguments."}}, 'required': []} }, { "name": 'verify_connection', "description": ( "Check that the connection sent with this request works against the upstream, and say who it " "authenticated as. Makes no change." ), "inputSchema": {'type': 'object', 'properties': {}, 'required': []} } ] # ============================================ # Resource Definitions # ============================================ RESOURCES_REGISTRY = [] # ============================================ # Prompt Definitions # ============================================ PROMPT_TEMPLATES = {} PROMPTS_REGISTRY = [ { "name": name, "description": prompt["description"], "arguments": [ {"name": a["name"], "description": a["description"], "required": a["required"]} for a in prompt["arguments"] ], } for name, prompt in PROMPT_TEMPLATES.items() ] # ============================================ # Tool Implementations # ============================================ DEFAULT_PAGE_SIZE = 50 MAX_PAGE_SIZE = 200 MAX_RESPONSE_BYTES = 200000 RETRY_ATTEMPTS = 5 RETRY_MAX_WAIT_SECONDS = 20 RETRY_BUDGET_SECONDS = 60 SECRET_KEYS = ( "userdata", "customdata", "customscript", "protectedsettings", "connectionstring", "connectionstrings", "appsettings", "env", "envvars", "environmentvariables", "variables", "password", "adminpassword", "secret", "secretvalue", "sastoken", "accesskey", "primarykey", "secondarykey", "privatekey", "kubeconfig", "credentials", ) PERSON_KEYS = ( "createdby", "lastmodifiedby", "updatedby", "creator", "owner", "owneremail", "contact", "contactemail", "email", "objectid", "principalid", "principalname", "userprincipalname", ) PRINCIPAL_KINDS = {"user": "[user]", "group": "[group]", "domain": "[domain]", "principal": "[user]", "principalSet": "[group]", "deleted": "[user]"} NON_PERSON_EMAIL_DOMAINS = ("gserviceaccount.com",) def _clean_text(text: str) -> str: """Anonymise people inside a string: emails, AWS IAM users, and session names, which are often emails.""" def email(match): return match.group(0) if match.group(0).lower().endswith(NON_PERSON_EMAIL_DOMAINS) else "[email]" text = re.sub(r"arn:aws[a-z-]*:iam::\d{12}:user/[^\s\"',]+", "[user]", text) text = re.sub(r"(arn:aws[a-z-]*:sts::\d{12}:assumed-role/[^/\s\"',]+)/[^\s\"',]+", r"\1/[session]", text) # Bounded, and skipped without an @: an unbounded pattern takes minutes on one long string. if "@" not in text: return text return re.sub(r"[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,255}\.[A-Za-z]{2,24}", email, text) def _anonymise_member(value: str) -> str: """One IAM member, such as user:a@b.example. Service accounts stay: Discovery shows what can reach what.""" kind = value.split(":", 1)[0] if ":" in value and kind == "serviceAccount": return value if ":" in value and kind in PRINCIPAL_KINDS: return PRINCIPAL_KINDS[kind] return _clean_text(value) def _scrub(value, key: str = ""): """Drop secrets and anonymise people, however deep. Every tool's reply passes through here.""" lowered = key.lower().replace("_", "").replace("-", "") if lowered in SECRET_KEYS: return "[redacted]" if lowered in PERSON_KEYS: return "[user]" if isinstance(value, dict): tag = str(value.get("Key", value.get("key", ""))).lower().replace("_", "").replace("-", "") cleaned = {k: _scrub(v, str(k)) for k, v in value.items()} for name in ("Value", "value"): if name in cleaned and tag in PERSON_KEYS: cleaned[name] = "[user]" elif name in cleaned and tag in SECRET_KEYS: cleaned[name] = "[redacted]" return cleaned if isinstance(value, (list, tuple)): return [_scrub(v, "members" if lowered == "members" else "") for v in value] if isinstance(value, str): return _anonymise_member(value) if lowered == "members" else _clean_text(value) if value is None or isinstance(value, (bool, int, float)): return value return str(value) def _retry_delay(response, attempt: int) -> float: """How long the provider asked us to wait: Retry-After, or Resource Graph's hh:mm:ss quota reset.""" reset = response.headers.get("x-ms-user-quota-resets-after", "") if reset.count(":") == 2: hours, minutes, seconds = reset.split(":") return int(hours) * 3600 + int(minutes) * 60 + float(seconds) try: return float(response.headers.get("retry-after", "")) except ValueError: return float(2 ** attempt) async def _with_backoff(send): """Send, waiting when the provider throttles. The waits stay well inside the 120-second limit on an MCP call.""" waited = 0.0 response = await send() for attempt in range(RETRY_ATTEMPTS): if response.status_code not in (429, 503): return response delay = min(_retry_delay(response, attempt), RETRY_MAX_WAIT_SECONDS) if waited + delay > RETRY_BUDGET_SECONDS: return response logger.info("upstream_throttled", status=response.status_code, wait_seconds=delay) await asyncio.sleep(delay) waited += delay response = await send() return response def _page_size(arguments: Dict[str, Any]) -> int: try: size = int(arguments.get("page_size") or DEFAULT_PAGE_SIZE) except (TypeError, ValueError): return DEFAULT_PAGE_SIZE return max(1, min(size, MAX_PAGE_SIZE)) def _read_page(arguments: Dict[str, Any]): """(upstream token, items of that upstream page already returned).""" token = arguments.get("page_token") if not token: return None, 0 state = json.loads(base64.urlsafe_b64decode(str(token).encode()).decode()) return state["u"], int(state["s"]) def _write_page(upstream, skip: int) -> str: return base64.urlsafe_b64encode(json.dumps({"u": upstream, "s": skip}).encode()).decode() def _evidence_ref(tool: str, arguments: Dict[str, Any], payload) -> str: asked = {k: v for k, v in arguments.items() if k != "page_token"} blob = json.dumps([tool, asked, payload], sort_keys=True, default=str) return "sha256:" + hashlib.sha256(blob.encode()).hexdigest() def _collected_at() -> str: return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()) def _refuse(code: str, message: str) -> Dict[str, Any]: return {"success": False, "error": {"code": code, "message": message}} def _upstream_failed(provider: str, error: Exception) -> Dict[str, Any]: """Name the failure and never its text: an upstream error can quote a request or an identity.""" status = getattr(getattr(error, "response", None), "status_code", None) code = getattr(error, "response", None) if isinstance(code, dict): status = code.get("Error", {}).get("Code") logger.warning("upstream_call_failed", provider=provider, error_type=type(error).__name__, status=status) detail = f" ({status})" if status else "" return _refuse("upstream_failed", f"{provider} refused or failed the call: {type(error).__name__}{detail}") def _page_result(provider: str, tool: str, arguments: Dict[str, Any], items: List[Any], used, upstream_next, skip: int = 0, extra: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: """One page of scrubbed items, cut at MAX_RESPONSE_BYTES; the token resumes exactly where the cut fell.""" remaining = [_scrub(item) for item in items[skip:]] kept, size = [], 0 for item in remaining: size += len(json.dumps(item, default=str)) if kept and size > MAX_RESPONSE_BYTES: break kept.append(item) if len(kept) < len(remaining): next_token = _write_page(used, skip + len(kept)) else: next_token = _write_page(upstream_next, 0) if upstream_next else None data = {"provider": provider, "items": kept, "count": len(kept), "next_page_token": next_token, "collected_at": _collected_at(), "evidence_ref": _evidence_ref(tool, arguments, kept)} data.update(extra or {}) return {"success": True, "data": data} def _one_result(provider: str, tool: str, arguments: Dict[str, Any], metadata: Any) -> Dict[str, Any]: clean = _scrub(metadata) return {"success": True, "data": {"provider": provider, "metadata": clean, "collected_at": _collected_at(), "evidence_ref": _evidence_ref(tool, arguments, clean)}} GCP_ASSET_API = "https://cloudasset.googleapis.com/v1" GCP_ORG_POLICY_API = "https://orgpolicy.googleapis.com/v2" GCP_RECOMMENDER_API = "https://recommender.googleapis.com/v1" GCP_READ_ONLY = "https://www.googleapis.com/auth/cloud-platform.read-only" GCP_TOKENS = {} GCP_SERVERS = { "instances": ["compute.googleapis.com/Instance"], "instance_groups": ["compute.googleapis.com/InstanceGroupManager"], "disks": ["compute.googleapis.com/Disk"], } GCP_WORKLOADS = { "cloud_run": ["run.googleapis.com/Service"], "cloud_functions": ["cloudfunctions.googleapis.com/Function"], "app_engine": ["appengine.googleapis.com/Service"], } GCP_KUBERNETES = {"clusters": ["container.googleapis.com/Cluster"], "node_pools": ["container.googleapis.com/NodePool"]} GCP_NETWORK = { "networks": ["compute.googleapis.com/Network"], "subnetworks": ["compute.googleapis.com/Subnetwork"], "routes": ["compute.googleapis.com/Route"], "firewall_rules": ["compute.googleapis.com/Firewall", "compute.googleapis.com/FirewallPolicy"], "load_balancers": ["compute.googleapis.com/ForwardingRule", "compute.googleapis.com/BackendService"], "gateways": ["compute.googleapis.com/Router", "compute.googleapis.com/VpnGateway", "compute.googleapis.com/InterconnectAttachment"], } GCP_DATA = { "cloud_sql": ["sqladmin.googleapis.com/Instance"], "firestore": ["firestore.googleapis.com/Database"], "cloud_storage": ["storage.googleapis.com/Bucket"], } GCP_ACCOUNTS = { "projects": ["cloudresourcemanager.googleapis.com/Project"], "folders": ["cloudresourcemanager.googleapis.com/Folder"], } GCP_PERIMETERS = {"vpc_service_controls": ["accesscontextmanager.googleapis.com/ServicePerimeter"]} GCP_RECOMMENDERS = ("google.compute.instance.MachineTypeRecommender", "google.compute.instance.IdleResourceRecommender", "google.compute.disk.IdleResourceRecommender", "google.iam.policy.Recommender") GCP_PILLARS = {"cost": "cost", "security": "security", "performance": "performance", "reliability": "reliability", "manageability": "operations", "sustainability": "sustainability"} def _gcp_scope() -> str: scope = str(get_connection().get("scope_root", "")).strip("/") kind, _, identifier = scope.partition("/") if kind not in ("organizations", "folders", "projects") or not identifier or "/" in identifier: raise ValueError("scope_root must be organizations/, folders/ or projects/") return scope def _gcp_client(): return get_upstream_client("gcp", lambda c: httpx.AsyncClient(timeout=100)) async def _gcp_token() -> str: connection = get_connection() key = hashlib.sha256(json.dumps(connection, sort_keys=True).encode()).hexdigest() cached = GCP_TOKENS.get(key) now = time.time() if cached and cached[1] > now + 60: return cached[0] def refresh(): info = json.loads(connection["service_account_json"]) credentials = service_account.Credentials.from_service_account_info(info, scopes=[GCP_READ_ONLY]) credentials.refresh(GoogleRequest()) return credentials.token token = await asyncio.to_thread(refresh) GCP_TOKENS[key] = (token, now + 3000) return token async def _gcp_get(url: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: token = await _gcp_token() response = await _with_backoff( lambda: _gcp_client().get(url, params=params, headers={"Authorization": f"Bearer {token}"})) response.raise_for_status() return response.json() async def _gcp_page(tool: str, arguments: Dict[str, Any], url: str, params: Dict[str, Any], result_key: str, finish=None) -> Dict[str, Any]: try: upstream, skip = _read_page(arguments) except (ValueError, KeyError, TypeError): return _refuse("invalid_page_token", "page_token isn't one this server issued") request = {**params, "pageSize": _page_size(arguments)} if upstream: request["pageToken"] = upstream try: body = await _gcp_get(url, request) except Exception as error: return _upstream_failed("gcp", error) items = [finish(i) for i in body.get(result_key, [])] if finish else body.get(result_key, []) return _page_result("gcp", tool, arguments, items, upstream, body.get("nextPageToken"), skip) async def _gcp_search(tool: str, arguments: Dict[str, Any], asset_types: List[str], query: str = "") -> Dict[str, Any]: try: url = f"{GCP_ASSET_API}/{_gcp_scope()}:searchAllResources" except ValueError as error: return _refuse("invalid_connection", str(error)) params = {"assetTypes": asset_types, "readMask": "*"} if query: params["query"] = query return await _gcp_page(tool, arguments, url, params, "results") async def _gcp_kind(tool: str, arguments: Dict[str, Any], kinds: Dict[str, List[str]], default: str) -> Dict[str, Any]: kind = arguments.get("kind") or default if kind not in kinds: return _refuse("unknown_kind", "kind must be one of: " + ", ".join(kinds)) return await _gcp_search(tool, arguments, kinds[kind]) async def _gcp_project_in_scope(project_id: str) -> bool: """Whether Cloud Asset, queried under the scope, can see this project. The API sets the boundary.""" scope = _gcp_scope() if scope == f"projects/{project_id}": return True body = await _gcp_get(f"{GCP_ASSET_API}/{scope}:searchAllResources", {"assetTypes": GCP_ACCOUNTS["projects"], "query": f"name:{project_id}", "pageSize": 5}) return any(str(r.get("name", "")).endswith(f"/projects/{project_id}") for r in body.get("results", [])) def _gcp_recommendation(item: Dict[str, Any]) -> Dict[str, Any]: category = str(item.get("primaryImpact", {}).get("category", "")) return {**item, "pillar": GCP_PILLARS.get(category.lower(), "other"), "provider_category": category} def _docs_query_logged(provider: str, tool: str, query: Any) -> None: logger.info("docs_query", provider=provider, tool=tool, query=str(query)) GCP_MCP_SERVERS = { "developer_knowledge": {"url": "https://developerknowledge.googleapis.com/mcp", "allow": ("search_documents", "get_documents", "answer_query")}, "resource_manager": {"url": "https://cloudresourcemanager.googleapis.com/mcp", "allow": ("search_projects",)}, "asset_inventory": {"url": "https://cloudasset.googleapis.com/mcp", "allow": ("list_assets", "analyze_iam_policy")}, "compute": {"url": "https://compute.googleapis.com/mcp", "allow": ("list_instances", "get_instance_basic_info", "list_instance_attached_disks", "list_instance_group_managers", "get_instance_group_manager_basic_info", "list_instance_templates", "get_instance_template_properties", "list_disks", "get_disk_basic_info", "list_reservations", "list_commitments")}, "gke": {"url": "https://container.googleapis.com/mcp", "allow": ("list_clusters", "get_cluster", "list_node_pools", "get_node_pool", "get_k8s_version")}, "cloud_run": {"url": "https://run.googleapis.com/mcp", "allow": ("list_services", "get_service")}, "cloud_sql": {"url": "https://sqladmin.googleapis.com/mcp", "allow": ("list_instances", "get_instance")}, "storage": {"url": "https://storage.googleapis.com/storage/mcp", "allow": ("list_buckets",)}, "pubsub": {"url": "https://pubsub.googleapis.com/mcp", "allow": ("list_topics", "get_topic", "list_subscriptions", "get_subscription")}, "iam": {"url": "https://iam.googleapis.com/mcp", "allow": ("list_roles", "get_role", "list_deny_policies", "get_deny_policy")}, "monitoring": {"url": "https://monitoring.googleapis.com/mcp", "allow": ("list_alert_policies", "get_alert_policy", "list_dashboards", "list_metric_descriptors", "list_timeseries")}, "network_intelligence": {"url": "https://networkmanagement.googleapis.com/mcp", "allow": ("list_connectivity_tests", "get_connectivity_test")}, } GCP_DOCS_SERVER = "developer_knowledge" async def _gcp_mcp_headers(server_name: str) -> Dict[str, str]: headers = {"Accept": "application/json, text/event-stream", "Content-Type": "application/json"} connection = get_connection() if server_name == GCP_DOCS_SERVER and connection.get("docs_api_key"): headers["X-Goog-Api-Key"] = str(connection["docs_api_key"]) else: headers["Authorization"] = f"Bearer {await _gcp_token()}" if connection.get("quota_project"): headers["X-Goog-User-Project"] = str(connection["quota_project"]) return headers async def _gcp_mcp_post(server_name: str, body: Dict[str, Any], session: Optional[str] = None): headers = await _gcp_mcp_headers(server_name) if session: headers["Mcp-Session-Id"] = session url = GCP_MCP_SERVERS[server_name]["url"] response = await _with_backoff(lambda: _gcp_client().post(url, content=json.dumps(body), headers=headers)) response.raise_for_status() return response def _gcp_mcp_message(response) -> Dict[str, Any]: """The JSON-RPC reply, whether it came back as JSON or as a server-sent event.""" if "text/event-stream" in response.headers.get("content-type", ""): lines = [line[5:].strip() for line in response.text.splitlines() if line.startswith("data:")] return json.loads(lines[-1]) if lines else {} return response.json() async def _gcp_mcp_session(server_name: str) -> Optional[str]: response = await _gcp_mcp_post(server_name, { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "sa-gcp-cloud", "version": "0.1.0"}}}) session = response.headers.get("mcp-session-id") await _gcp_mcp_post(server_name, {"jsonrpc": "2.0", "method": "notifications/initialized"}, session) return session async def _gcp_mcp_tools(server_name: str, session: Optional[str]) -> Dict[str, Dict[str, Any]]: response = await _gcp_mcp_post(server_name, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session) return {t.get("name"): t for t in _gcp_mcp_message(response).get("result", {}).get("tools", [])} def _gcp_mcp_payload(result: Dict[str, Any]) -> Any: if result.get("structuredContent") is not None: return result["structuredContent"] parts = [] for part in result.get("content", []): if part.get("type") != "text": continue try: parts.append(json.loads(part["text"])) except ValueError: parts.append(part["text"]) return parts[0] if len(parts) == 1 else parts async def _gcp_forward(tool: str, server_name: str, name: str, arguments: Dict[str, Any]) -> Dict[str, Any]: """One allow-listed tool on one hosted server. As in the source, a tool must declare itself read-only.""" entry = GCP_MCP_SERVERS.get(server_name) if not entry or name not in entry["allow"]: return _refuse("not_allowed", "this tool isn't on the allow list") passed = arguments.get("tool_arguments") or {} if not isinstance(passed, dict): return _refuse("invalid_argument", "tool_arguments must be an object") if server_name == GCP_DOCS_SERVER: _docs_query_logged("gcp", tool, json.dumps(passed, sort_keys=True)) try: session = await _gcp_mcp_session(server_name) tools = await _gcp_mcp_tools(server_name, session) if name not in tools: return _refuse("not_offered", "Google no longer offers this tool") if not tools[name].get("annotations", {}).get("readOnlyHint"): return _refuse("not_read_only", "the tool doesn't declare itself read-only") response = await _gcp_mcp_post(server_name, { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": name, "arguments": passed}}, session) message = _gcp_mcp_message(response) except Exception as error: return _upstream_failed("gcp", error) result = message.get("result") or {} if message.get("error") or result.get("isError"): return _refuse("upstream_refused", f"{name} refused the request") return _one_result("gcp", tool, arguments, _gcp_mcp_payload(result)) async def _gcp_describe(arguments: Dict[str, Any]) -> Dict[str, Any]: server_name, name = str(arguments.get("server") or ""), str(arguments.get("tool") or "") entry = GCP_MCP_SERVERS.get(server_name) if not entry or name not in entry["allow"]: return _refuse("not_allowed", "this tool isn't on the allow list") try: tools = await _gcp_mcp_tools(server_name, await _gcp_mcp_session(server_name)) except Exception as error: return _upstream_failed("gcp", error) if name not in tools: return _refuse("not_offered", "Google no longer offers this tool") return _one_result("gcp", "gcp_describe_tool", arguments, { "description": tools[name].get("description"), "input_schema": tools[name].get("inputSchema")}) async def gcp_check_connection(arguments: Dict[str, Any]) -> Dict[str, Any]: try: await _gcp_mcp_session("resource_manager") except Exception as error: return {"ok": False, "message": _upstream_failed("gcp", error)["error"]["message"]} return {"ok": True, "message": "Signed in and reached Google's hosted servers."} async def gcp_describe_tool(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_describe(arguments) async def gcp_developer_knowledge_search_documents(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_developer_knowledge_search_documents", "developer_knowledge", "search_documents", arguments) async def gcp_developer_knowledge_get_documents(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_developer_knowledge_get_documents", "developer_knowledge", "get_documents", arguments) async def gcp_developer_knowledge_answer_query(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_developer_knowledge_answer_query", "developer_knowledge", "answer_query", arguments) async def gcp_resource_manager_search_projects(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_resource_manager_search_projects", "resource_manager", "search_projects", arguments) async def gcp_asset_inventory_list_assets(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_asset_inventory_list_assets", "asset_inventory", "list_assets", arguments) async def gcp_asset_inventory_analyze_iam_policy(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_asset_inventory_analyze_iam_policy", "asset_inventory", "analyze_iam_policy", arguments) async def gcp_compute_list_instances(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_list_instances", "compute", "list_instances", arguments) async def gcp_compute_get_instance_basic_info(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_get_instance_basic_info", "compute", "get_instance_basic_info", arguments) async def gcp_compute_list_instance_attached_disks(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_list_instance_attached_disks", "compute", "list_instance_attached_disks", arguments) async def gcp_compute_list_instance_group_managers(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_list_instance_group_managers", "compute", "list_instance_group_managers", arguments) async def gcp_compute_get_instance_group_manager_basic_info(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_get_instance_group_manager_basic_info", "compute", "get_instance_group_manager_basic_info", arguments) async def gcp_compute_list_instance_templates(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_list_instance_templates", "compute", "list_instance_templates", arguments) async def gcp_compute_get_instance_template_properties(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_get_instance_template_properties", "compute", "get_instance_template_properties", arguments) async def gcp_compute_list_disks(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_list_disks", "compute", "list_disks", arguments) async def gcp_compute_get_disk_basic_info(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_get_disk_basic_info", "compute", "get_disk_basic_info", arguments) async def gcp_compute_list_reservations(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_list_reservations", "compute", "list_reservations", arguments) async def gcp_compute_list_commitments(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_compute_list_commitments", "compute", "list_commitments", arguments) async def gcp_gke_list_clusters(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_gke_list_clusters", "gke", "list_clusters", arguments) async def gcp_gke_get_cluster(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_gke_get_cluster", "gke", "get_cluster", arguments) async def gcp_gke_list_node_pools(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_gke_list_node_pools", "gke", "list_node_pools", arguments) async def gcp_gke_get_node_pool(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_gke_get_node_pool", "gke", "get_node_pool", arguments) async def gcp_gke_get_k8s_version(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_gke_get_k8s_version", "gke", "get_k8s_version", arguments) async def gcp_cloud_run_list_services(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_cloud_run_list_services", "cloud_run", "list_services", arguments) async def gcp_cloud_run_get_service(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_cloud_run_get_service", "cloud_run", "get_service", arguments) async def gcp_cloud_sql_list_instances(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_cloud_sql_list_instances", "cloud_sql", "list_instances", arguments) async def gcp_cloud_sql_get_instance(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_cloud_sql_get_instance", "cloud_sql", "get_instance", arguments) async def gcp_storage_list_buckets(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_storage_list_buckets", "storage", "list_buckets", arguments) async def gcp_pubsub_list_topics(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_pubsub_list_topics", "pubsub", "list_topics", arguments) async def gcp_pubsub_get_topic(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_pubsub_get_topic", "pubsub", "get_topic", arguments) async def gcp_pubsub_list_subscriptions(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_pubsub_list_subscriptions", "pubsub", "list_subscriptions", arguments) async def gcp_pubsub_get_subscription(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_pubsub_get_subscription", "pubsub", "get_subscription", arguments) async def gcp_iam_list_roles(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_iam_list_roles", "iam", "list_roles", arguments) async def gcp_iam_get_role(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_iam_get_role", "iam", "get_role", arguments) async def gcp_iam_list_deny_policies(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_iam_list_deny_policies", "iam", "list_deny_policies", arguments) async def gcp_iam_get_deny_policy(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_iam_get_deny_policy", "iam", "get_deny_policy", arguments) async def gcp_monitoring_list_alert_policies(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_monitoring_list_alert_policies", "monitoring", "list_alert_policies", arguments) async def gcp_monitoring_get_alert_policy(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_monitoring_get_alert_policy", "monitoring", "get_alert_policy", arguments) async def gcp_monitoring_list_dashboards(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_monitoring_list_dashboards", "monitoring", "list_dashboards", arguments) async def gcp_monitoring_list_metric_descriptors(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_monitoring_list_metric_descriptors", "monitoring", "list_metric_descriptors", arguments) async def gcp_monitoring_list_timeseries(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_monitoring_list_timeseries", "monitoring", "list_timeseries", arguments) async def gcp_network_intelligence_list_connectivity_tests(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_network_intelligence_list_connectivity_tests", "network_intelligence", "list_connectivity_tests", arguments) async def gcp_network_intelligence_get_connectivity_test(arguments: Dict[str, Any]) -> Dict[str, Any]: return await _gcp_forward("gcp_network_intelligence_get_connectivity_test", "network_intelligence", "get_connectivity_test", arguments) async def verify_connection(arguments: Dict[str, Any]) -> Dict[str, Any]: """Check that the connection sent with this request works against the upstream. Makes no change.""" connection = get_connection() if not connection: return {"ok": False, "message": "No connection was sent with this request."} missing = mcp_connection.missing_fields(connection, CONNECTION_SCHEMA) if missing: return {"ok": False, "message": "The connection is missing: " + ", ".join(missing)} return await gcp_check_connection(arguments) # Tool function registry TOOL_FUNCTIONS = { 'gcp_check_connection': gcp_check_connection, 'gcp_describe_tool': gcp_describe_tool, 'gcp_developer_knowledge_search_documents': gcp_developer_knowledge_search_documents, 'gcp_developer_knowledge_get_documents': gcp_developer_knowledge_get_documents, 'gcp_developer_knowledge_answer_query': gcp_developer_knowledge_answer_query, 'gcp_resource_manager_search_projects': gcp_resource_manager_search_projects, 'gcp_asset_inventory_list_assets': gcp_asset_inventory_list_assets, 'gcp_asset_inventory_analyze_iam_policy': gcp_asset_inventory_analyze_iam_policy, 'gcp_compute_list_instances': gcp_compute_list_instances, 'gcp_compute_get_instance_basic_info': gcp_compute_get_instance_basic_info, 'gcp_compute_list_instance_attached_disks': gcp_compute_list_instance_attached_disks, 'gcp_compute_list_instance_group_managers': gcp_compute_list_instance_group_managers, 'gcp_compute_get_instance_group_manager_basic_info': gcp_compute_get_instance_group_manager_basic_info, 'gcp_compute_list_instance_templates': gcp_compute_list_instance_templates, 'gcp_compute_get_instance_template_properties': gcp_compute_get_instance_template_properties, 'gcp_compute_list_disks': gcp_compute_list_disks, 'gcp_compute_get_disk_basic_info': gcp_compute_get_disk_basic_info, 'gcp_compute_list_reservations': gcp_compute_list_reservations, 'gcp_compute_list_commitments': gcp_compute_list_commitments, 'gcp_gke_list_clusters': gcp_gke_list_clusters, 'gcp_gke_get_cluster': gcp_gke_get_cluster, 'gcp_gke_list_node_pools': gcp_gke_list_node_pools, 'gcp_gke_get_node_pool': gcp_gke_get_node_pool, 'gcp_gke_get_k8s_version': gcp_gke_get_k8s_version, 'gcp_cloud_run_list_services': gcp_cloud_run_list_services, 'gcp_cloud_run_get_service': gcp_cloud_run_get_service, 'gcp_cloud_sql_list_instances': gcp_cloud_sql_list_instances, 'gcp_cloud_sql_get_instance': gcp_cloud_sql_get_instance, 'gcp_storage_list_buckets': gcp_storage_list_buckets, 'gcp_pubsub_list_topics': gcp_pubsub_list_topics, 'gcp_pubsub_get_topic': gcp_pubsub_get_topic, 'gcp_pubsub_list_subscriptions': gcp_pubsub_list_subscriptions, 'gcp_pubsub_get_subscription': gcp_pubsub_get_subscription, 'gcp_iam_list_roles': gcp_iam_list_roles, 'gcp_iam_get_role': gcp_iam_get_role, 'gcp_iam_list_deny_policies': gcp_iam_list_deny_policies, 'gcp_iam_get_deny_policy': gcp_iam_get_deny_policy, 'gcp_monitoring_list_alert_policies': gcp_monitoring_list_alert_policies, 'gcp_monitoring_get_alert_policy': gcp_monitoring_get_alert_policy, 'gcp_monitoring_list_dashboards': gcp_monitoring_list_dashboards, 'gcp_monitoring_list_metric_descriptors': gcp_monitoring_list_metric_descriptors, 'gcp_monitoring_list_timeseries': gcp_monitoring_list_timeseries, 'gcp_network_intelligence_list_connectivity_tests': gcp_network_intelligence_list_connectivity_tests, 'gcp_network_intelligence_get_connectivity_test': gcp_network_intelligence_get_connectivity_test, 'verify_connection': verify_connection, } # ============================================ # Resource Implementations # ============================================ # Resource read handlers by uri RESOURCE_HANDLERS = { } # ============================================ # FastAPI Application # ============================================ @asynccontextmanager async def lifespan(app: FastAPI): """Application lifespan manager""" logger.info( "server_starting", port=config.SERVER_PORT, auth_required=config.REQUIRE_AUTH, tools=len(TOOLS_REGISTRY), resources=len(RESOURCES_REGISTRY), prompts=len(PROMPTS_REGISTRY), template_version=TEMPLATE_VERSION, ) # Validate configuration if config.REQUIRE_AUTH and not config.MCP_REGISTRATION_API_KEY: logger.error( "registration_key_not_set", hint="Set MCP_REGISTRATION_API_KEY before starting the server", ) yield await _close_all_clients() logger.info("server_stopping") app = FastAPI( title=config.SERVER_NAME, version=config.SERVER_VERSION, description="Google Cloud documentation and read-only estate tools for the Solution Architecture agent, through Google's hosted MCP servers.", lifespan=lifespan ) # FastAPI's default answer to an invalid request repeats it, and the request can carry the tenant's connection mcp_connection.install_invalid_request_handler( app, lambda fields: logger.warning("invalid_request", fields=sanitize_log(fields)) ) # ============================================ # Health Check Endpoint # ============================================ @app.get("/health") async def health_check(): """ Health check endpoint (no authentication required). Used by: - MCP Gateway health monitoring - Kubernetes liveness/readiness probes - Load balancers """ # Answers without a key, so it says only what a probe needs: not how authentication is set up return { "status": "healthy" if config.MCP_REGISTRATION_API_KEY else "degraded", "server_id": config.SERVER_ID, "server_name": config.SERVER_NAME, "version": config.SERVER_VERSION, "timestamp": datetime.now(timezone.utc).isoformat(), } # ============================================ # MCP Authentication Info Endpoint # ============================================ @app.get("/.well-known/mcp-auth") async def mcp_auth_info(): """ MCP Authentication Information Endpoint (PUBLIC - no auth required). Exposes authentication requirements for Gateway registration. """ return { "auth_required": config.REQUIRE_AUTH, "auth_type": "bearer", "description": "Include 'Authorization: Bearer ' header", "env_var": "MCP_REGISTRATION_API_KEY" } # ============================================ # MCP Protocol /messages Endpoint # ============================================ class _MethodNotFound(Exception): """The JSON-RPC method is not one this server answers.""" async def dispatch_mcp_request(request: MCPRequest) -> MCPResponse: """Run one JSON-RPC request; every outcome, errors included, is an MCPResponse.""" # The tenant's connection, bound for this request only so tools reach the right account connection_token = mcp_connection.bind(mcp_connection.from_params(request.params)) try: if CONNECTION_SCHEMA is not None and request.method in CONNECTION_METHODS: check_connection(mcp_connection.active()) if request.method == "initialize": result = { "protocolVersion": "1.0.0", "serverInfo": { "name": config.SERVER_NAME, "version": config.SERVER_VERSION, "server_id": config.SERVER_ID }, "capabilities": { "tools": True, "resources": False, "prompts": False }, "authentication": { "type": "bearer", "description": "Requires MCP_REGISTRATION_API_KEY in Authorization header" } } if CONNECTION_SCHEMA is not None: result["_meta"] = mcp_connection.schema_meta(CONNECTION_SCHEMA, verify_tool=VERIFY_TOOL) return MCPResponse(id=request.id, result=result) elif request.method == "tools/list": return MCPResponse(id=request.id, result={"tools": TOOLS_REGISTRY}) elif request.method == "tools/call": tool_name = request.params.get("name") arguments = request.params.get("arguments") if arguments is None: arguments = {} if not tool_name: raise ValueError("Missing 'name' in params") if not isinstance(tool_name, str): raise ValueError("'name' must be a string") if not isinstance(arguments, dict): raise ValueError("'arguments' must be an object") structlog.contextvars.bind_contextvars(tool=sanitize_log(tool_name)) tool_func = TOOL_FUNCTIONS.get(tool_name) if not tool_func: raise ValueError(f"Unknown tool: {tool_name}") result = await tool_func(arguments) if isinstance(result, dict) and result.get("success") is False and isinstance(result.get("error"), str): # A failed call's message often quotes the upstream URL, which may carry a key result = {**result, "error": mcp_connection.scrub(result["error"])} reply = { "content": [ { "type": "text", "text": json.dumps(result) if isinstance(result, dict) else str(result) } ] } if isinstance(result, dict) and result.get("success") is False: # A tool that reports failure is an error to the caller too (MCP: isError), not a normal result reply["isError"] = True return MCPResponse(id=request.id, result=reply) elif request.method == "resources/list": return MCPResponse(id=request.id, result={"resources": RESOURCES_REGISTRY}) elif request.method == "resources/read": uri = request.params.get("uri") if not uri: raise ValueError("Missing 'uri' in params") structlog.contextvars.bind_contextvars(resource=sanitize_log(uri)) handler = RESOURCE_HANDLERS.get(uri) if not handler: raise ValueError(f"Unknown resource: {uri}") content = await handler(uri) mime_type = next((r["mimeType"] for r in RESOURCES_REGISTRY if r["uri"] == uri), "text/plain") text = content if isinstance(content, str) else json.dumps(content) return MCPResponse(id=request.id, result={ "contents": [{"uri": uri, "mimeType": mime_type, "text": text}] }) elif request.method == "prompts/list": return MCPResponse(id=request.id, result={"prompts": PROMPTS_REGISTRY}) elif request.method == "prompts/get": prompt_name = request.params.get("name") prompt = PROMPT_TEMPLATES.get(prompt_name) if isinstance(prompt_name, str) else None if prompt is None: raise ValueError(f"Unknown prompt: {prompt_name}") structlog.contextvars.bind_contextvars(prompt=sanitize_log(prompt_name)) supplied = request.params.get("arguments") or {} values = {a["name"]: a["default"] for a in prompt["arguments"] if a["default"] is not None} values.update(supplied) missing = [a["name"] for a in prompt["arguments"] if a["required"] and a["name"] not in values] if missing: raise ValueError("Missing prompt argument(s): " + ", ".join(missing)) return MCPResponse(id=request.id, result={ "description": prompt["description"], "messages": [{ "role": "user", "content": {"type": "text", "text": render_prompt(prompt["template"], values)}, }], }) else: raise _MethodNotFound(f"Unknown method: {request.method}") except _MethodNotFound as e: logger.warning("mcp_method_not_found", error=sanitize_log(mcp_connection.redact(e))) return MCPResponse(id=request.id, error={"code": -32601, "message": mcp_connection.redact(e)}) except NotImplementedError as e: message = mcp_connection.redact(e) logger.warning("tool_not_implemented", error=sanitize_log(message)) return MCPResponse(id=request.id, error={"code": -32601, "message": message}) except ValueError as e: message = mcp_connection.redact(e) logger.warning("mcp_client_error", error=sanitize_log(message)) return MCPResponse(id=request.id, error={"code": -32602, "message": message}) except Exception as e: # The message of an unexpected error is not shown to the caller and is redacted before it is logged; # a tool may have put the connection's credential in it. logger.error( "mcp_unexpected_error", error_type=type(e).__name__, error=sanitize_log(mcp_connection.redact(e)), traceback=sanitize_log(mcp_connection.redact(traceback.format_exc())), ) return MCPResponse(id=request.id, error={"code": -32603, "message": "Internal server error"}) finally: mcp_connection.unbind(connection_token) @app.post("/messages") async def handle_mcp_message( request: MCPRequest, http_request: Request, authenticated: bool = Depends(verify_mcp_registration_key) ) -> MCPResponse: """ MCP protocol message handler (JSON-RPC 2.0 over HTTP). This is the STANDARD MCP endpoint for Gateway integration. Requires Bearer token authentication (MCP_REGISTRATION_API_KEY). Supported Methods: - initialize: Protocol handshake and capability exchange - tools/list: Discover available tools - tools/call: Execute a specific tool - resources/list: List available resources - prompts/list: List available prompts """ started = time.monotonic() structlog.contextvars.clear_contextvars() structlog.contextvars.bind_contextvars( request_id=sanitize_log(http_request.headers.get("x-request-id") or str(request.id)), method=sanitize_log(request.method), ) try: response = await dispatch_mcp_request(request) completed = {} if CONNECTION_SCHEMA is not None and request.method in CONNECTION_METHODS: # Which connection served the call: a short id, never the credential completed["connection"] = mcp_connection.fingerprint(mcp_connection.from_params(request.params)) logger.info( "mcp_request_completed", outcome="error" if response.error else ("tool_error" if (response.result or {}).get("isError") else "ok"), error_code=(response.error or {}).get("code"), duration_ms=round((time.monotonic() - started) * 1000, 1), **completed, ) return response finally: structlog.contextvars.clear_contextvars() # ============================================ # Entry Point # ============================================ if __name__ == "__main__": import uvicorn uvicorn.run( "server:app", host="0.0.0.0", port=config.SERVER_PORT, log_level=logging.getLevelName(getattr(logging, config.LOG_LEVEL, logging.INFO)).lower(), log_config=None, # configure_logging() owns the format access_log=True, reload=False # Set to True for development )