- Scripts to run workflows from a YAML context or run inputs (kab_run_workflow.py, with --input name=@file), store per-project discovery connections, bootstrap agent MCP keys, refresh the KAB token, publish reports and build estate snapshots. - Hyperscaler discovery servers extended in place; cloud-knowledge folded into them. - deploy/crucible-kab-dev.yaml: the Discovery package agent and the Assessment agents. - Platform issue write-ups and current-wiring notes under docs/platform-issues/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1475 lines
67 KiB
Python
1475 lines
67 KiB
Python
"""Google Cloud Discovery
|
|
======================
|
|
|
|
Read-only discovery of a customer's Google Cloud estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Recommender findings - through Cloud Asset Inventory.
|
|
|
|
Generated by Agent Builder Platform - MCP Server Builder
|
|
Version: 0.1.4
|
|
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: 8113)
|
|
- 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': 'Google Cloud Discovery',
|
|
'description': "Read-only discovery of a customer's Google Cloud estate - servers, "
|
|
'workloads, Kubernetes clusters, networks, data stores, policies and '
|
|
'Recommender findings - through Cloud Asset Inventory.',
|
|
'properties': {'scope_root': {'type': 'string',
|
|
'title': 'Scope root',
|
|
'description': 'What may be read: organizations/<id>, '
|
|
'folders/<id> or projects/<id>.'},
|
|
'quota_project': {'type': 'string',
|
|
'title': 'Quota project',
|
|
'description': 'Optional. The project Google bills '
|
|
'Recommender and guidance calls to, '
|
|
'for a user token; defaults to a '
|
|
'projects/<id> scope root. The caller '
|
|
'needs serviceusage.services.use on '
|
|
'it.'},
|
|
'service_account_json': {'type': 'string',
|
|
'title': 'Service account key',
|
|
'description': 'The read-only service '
|
|
"account's JSON key.",
|
|
'writeOnly': True,
|
|
'format': 'password'},
|
|
'access_token': {'type': 'string',
|
|
'title': 'Access token',
|
|
'description': 'For a short trial only, instead of '
|
|
'the key. A token from gcloud auth '
|
|
'print-access-token. It expires within '
|
|
'about an hour and carries that '
|
|
"person's rights.",
|
|
'writeOnly': True,
|
|
'format': 'password'}},
|
|
'required': ['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", 'gcp-discovery')
|
|
SERVER_NAME = os.getenv("MCP_SERVER_NAME", 'Google Cloud Discovery')
|
|
SERVER_VERSION = os.getenv("MCP_SERVER_VERSION", '0.1.4')
|
|
# 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 "8113")
|
|
|
|
# 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 <token>' 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 search the scope root. Returns no customer data.',
|
|
"inputSchema": {'type': 'object', 'properties': {}, 'required': []}
|
|
},
|
|
{
|
|
"name": 'gcp_list_accounts',
|
|
"description": 'List the estate structure: projects or folders under the scope root.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string', 'description': 'One of: projects, folders.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'gcp_list_resources',
|
|
"description": 'List every resource under the scope root, or one asset type.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'asset_type': {'type': 'string',
|
|
'description': 'Optional asset type, such as '
|
|
'compute.googleapis.com/Instance.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'gcp_query_resources',
|
|
"description": "Search resources under the scope root with Cloud Asset's query syntax.",
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'query': {'type': 'string',
|
|
'description': 'A Cloud Asset search query, such as '
|
|
'location:europe-west2.'},
|
|
'asset_type': {'type': 'string', 'description': 'Optional asset type.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': ['query']}
|
|
},
|
|
{
|
|
"name": 'gcp_get_resource_metadata',
|
|
"description": 'Read-only provider metadata for one resource under the scope root.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'resource_name': {'type': 'string',
|
|
'description': 'The full resource name, starting '
|
|
'//.'},
|
|
'scope_entry_id': {'type': 'string',
|
|
'description': 'The scope entry this answers, '
|
|
'echoed in the reply.'}},
|
|
'required': ['resource_name']}
|
|
},
|
|
{
|
|
"name": 'gcp_list_servers',
|
|
"description": 'List Compute Engine instances, instance groups or disks.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: instances, instance_groups, disks.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'gcp_list_workloads',
|
|
"description": 'List Cloud Run services, Cloud Functions or App Engine services. Environment variables are removed.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: cloud_run, cloud_functions, '
|
|
'app_engine.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'gcp_list_kubernetes_clusters',
|
|
"description": 'List GKE clusters or node pools with version and networking. Stops at the cloud control plane.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: clusters, node_pools.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'gcp_get_network_topology',
|
|
"description": 'List VPC networks, subnetworks, routes, firewall rules, load balancers or gateways.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: networks, subnetworks, routes, '
|
|
'firewall_rules, load_balancers, gateways.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'gcp_list_data_stores',
|
|
"description": 'List Cloud SQL instances, Firestore databases or Cloud Storage buckets. Metadata only.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: cloud_sql, firestore, cloud_storage.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'gcp_list_organization_policies',
|
|
"description": 'List Organization Policy constraints set at the scope root, or VPC Service Controls perimeters.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: organization_policies, '
|
|
'vpc_service_controls.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'gcp_list_resource_policies',
|
|
"description": 'List IAM policies set on resources under the scope root. People and groups are anonymised; service accounts stay.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'query': {'type': 'string',
|
|
'description': 'Optional Cloud Asset IAM search query.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'gcp_list_recommendations',
|
|
"description": 'List Recommender findings for one project, each with a common Well-Architected pillar.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'project_id': {'type': 'string',
|
|
'description': 'A project under the scope root.'},
|
|
'recommender': {'type': 'string',
|
|
'description': 'One of the supported recommender ids. '
|
|
'Default: machine type.'},
|
|
'location': {'type': 'string',
|
|
'description': 'A zone or region. Default global.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': ['project_id']}
|
|
},
|
|
{
|
|
"name": 'gcp_search_well_architected',
|
|
"description": "Search the Google Cloud Well-Architected Framework's guidance by pillar and topic. Both come from fixed lists, so no customer detail leaves the platform. Uses this connection's own credential.",
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'pillar': {'type': 'string',
|
|
'description': 'reliability, security, cost, operations, '
|
|
'performance or sustainability.'},
|
|
'topic': {'type': 'string',
|
|
'description': 'One of the fixed topics; an invalid value '
|
|
'lists them.'}},
|
|
'required': ['pillar', 'topic']}
|
|
},
|
|
{
|
|
"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",
|
|
)
|
|
|
|
SCALAR_SAFE_KEYS = ("env",)
|
|
|
|
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 _scalar(value) -> bool:
|
|
return value is None or isinstance(value, (str, bool, int, float))
|
|
|
|
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 and not (lowered in SCALAR_SAFE_KEYS and _scalar(value)):
|
|
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 and not (tag in SCALAR_SAFE_KEYS and _scalar(cleaned[name])):
|
|
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/<id>, folders/<id> or projects/<id>")
|
|
return scope
|
|
|
|
def _gcp_client():
|
|
return get_upstream_client("gcp", lambda c: httpx.AsyncClient(timeout=100))
|
|
|
|
async def _gcp_token() -> str:
|
|
connection = get_connection()
|
|
if connection.get("access_token"):
|
|
return str(connection["access_token"])
|
|
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
|
|
|
|
def _gcp_quota_project() -> str:
|
|
"""The project Google bills a user credential's calls to: the connection's quota_project, else a projects/<id>
|
|
scope root. Recommender and Developer Knowledge refuse a user token without one; Cloud Asset doesn't need it."""
|
|
connection = get_connection()
|
|
if connection.get("quota_project"):
|
|
return str(connection["quota_project"])
|
|
kind, _, identifier = str(connection.get("scope_root", "")).strip("/").partition("/")
|
|
return identifier if kind == "projects" else ""
|
|
|
|
GCP_QUOTA_APIS = ("https://recommender.googleapis.com/",) # a literal: the builder refuses computed module-level values
|
|
|
|
async def _gcp_auth(quota: bool) -> Dict[str, str]:
|
|
headers = {"Authorization": f"Bearer {await _gcp_token()}"}
|
|
project = _gcp_quota_project() if quota else ""
|
|
if project:
|
|
headers["x-goog-user-project"] = project
|
|
return headers
|
|
|
|
async def _gcp_get(url: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
headers = await _gcp_auth(url.startswith(GCP_QUOTA_APIS))
|
|
response = await _with_backoff(lambda: _gcp_client().get(url, params=params, headers=headers))
|
|
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}
|
|
|
|
KNOWLEDGE_SERVERS = {
|
|
"azure": {"url": "https://learn.microsoft.com/api/mcp", "tool": "microsoft_docs_search",
|
|
"framework": "Azure Well-Architected Framework"},
|
|
"aws": {"url": "https://aws-mcp.eu-west-1.api.aws/mcp", "tool": "aws___search_documentation",
|
|
"framework": "AWS Well-Architected Framework"},
|
|
"gcp": {"url": "https://developerknowledge.googleapis.com/mcp", "tool": "search_documents",
|
|
"framework": "Google Cloud Well-Architected Framework"},
|
|
}
|
|
|
|
KNOWLEDGE_PILLARS = ("reliability", "security", "cost", "operations", "performance", "sustainability")
|
|
|
|
KNOWLEDGE_TOPICS = (
|
|
"landing zone", "resource organization", "identity and access", "network segmentation", "hybrid connectivity",
|
|
"encryption", "logging and monitoring", "backup and recovery", "disaster recovery", "high availability",
|
|
"scaling", "kubernetes", "containers", "virtual machines", "databases", "storage", "serverless", "governance",
|
|
"policy enforcement", "tagging", "cost allocation", "migration", "incident response", "patching",
|
|
)
|
|
|
|
KNOWLEDGE_MAX_TEXT = 4000
|
|
|
|
def _knowledge_client():
|
|
return get_upstream_client("knowledge", lambda c: httpx.AsyncClient(timeout=60, follow_redirects=False))
|
|
|
|
def _knowledge_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 _knowledge_post(provider: str, connection: Dict[str, Any], body: Dict[str, Any],
|
|
session: Optional[str] = None, auth: Optional[Dict[str, str]] = None):
|
|
"""auth: headers a discovery server supplies from its own connection (gcp-discovery's OAuth token), used in
|
|
place of the stored API key."""
|
|
url = KNOWLEDGE_SERVERS[provider]["url"]
|
|
headers = {"Accept": "application/json, text/event-stream", "Content-Type": "application/json"}
|
|
if session:
|
|
headers["Mcp-Session-Id"] = session
|
|
if auth:
|
|
headers.update(auth)
|
|
elif provider == "gcp":
|
|
headers["X-Goog-Api-Key"] = connection.get("google_api_key", "")
|
|
content = json.dumps(body)
|
|
if provider == "aws":
|
|
import boto3
|
|
from botocore.auth import SigV4Auth
|
|
from botocore.awsrequest import AWSRequest
|
|
|
|
def sign():
|
|
credentials = boto3.Session(aws_access_key_id=connection.get("aws_access_key_id"),
|
|
aws_secret_access_key=connection.get("aws_secret_access_key")).get_credentials()
|
|
request = AWSRequest(method="POST", url=url, data=content, headers=headers)
|
|
SigV4Auth(credentials, "aws-mcp", "eu-west-1").add_auth(request)
|
|
return dict(request.headers)
|
|
|
|
headers = await asyncio.to_thread(sign)
|
|
response = await _with_backoff(lambda: _knowledge_client().post(url, content=content, headers=headers))
|
|
response.raise_for_status()
|
|
return response
|
|
|
|
async def _knowledge_session(provider: str, connection: Dict[str, Any], auth: Optional[Dict[str, str]] = None) -> Optional[str]:
|
|
response = await _knowledge_post(provider, connection, {
|
|
"jsonrpc": "2.0", "id": 1, "method": "initialize",
|
|
"params": {"protocolVersion": "2025-06-18", "capabilities": {},
|
|
"clientInfo": {"name": "kab-cp1-discovery", "version": "0.1.0"}}}, auth=auth)
|
|
return response.headers.get("mcp-session-id")
|
|
|
|
async def _knowledge_tools(provider: str, connection: Dict[str, Any], session: Optional[str] = None,
|
|
auth: Optional[Dict[str, str]] = None) -> List[Dict[str, Any]]:
|
|
session = session or await _knowledge_session(provider, connection, auth)
|
|
response = await _knowledge_post(provider, connection, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session, auth)
|
|
return _knowledge_message(response).get("result", {}).get("tools", [])
|
|
|
|
def _knowledge_argument(tool: Dict[str, Any]) -> str:
|
|
"""The search tool's query argument. Vendors name it differently and may change it, so it's read from the tool."""
|
|
schema = tool.get("inputSchema", {})
|
|
properties = schema.get("properties", {})
|
|
for name in list(schema.get("required", [])) + list(properties):
|
|
if properties.get(name, {}).get("type") == "string":
|
|
return name
|
|
return "query"
|
|
|
|
async def _knowledge_search(provider: str, connection: Dict[str, Any], query: str,
|
|
auth: Optional[Dict[str, str]] = None) -> List[Dict[str, Any]]:
|
|
session = await _knowledge_session(provider, connection, auth)
|
|
name = KNOWLEDGE_SERVERS[provider]["tool"]
|
|
tools = {t.get("name"): t for t in await _knowledge_tools(provider, connection, session, auth)}
|
|
if name not in tools:
|
|
raise LookupError(f"{provider} no longer offers {name}")
|
|
response = await _knowledge_post(provider, connection, {
|
|
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
|
|
"params": {"name": name, "arguments": {_knowledge_argument(tools[name]): query}}}, session, auth)
|
|
message = _knowledge_message(response)
|
|
results = []
|
|
for part in message.get("result", {}).get("content", []):
|
|
if part.get("type") != "text":
|
|
continue
|
|
try:
|
|
parsed = json.loads(part["text"])
|
|
except ValueError:
|
|
parsed = {"content": part["text"]}
|
|
found = parsed.get("results", parsed) if isinstance(parsed, dict) else parsed
|
|
for item in found if isinstance(found, list) else [found]:
|
|
if isinstance(item, dict):
|
|
results.append({"title": item.get("title"), "url": item.get("contentUrl") or item.get("url"),
|
|
"text": str(item.get("content") or item.get("text") or "")[:KNOWLEDGE_MAX_TEXT]})
|
|
return results
|
|
|
|
async def _knowledge_tool(provider: str, tool: str, arguments: Dict[str, Any], connection: Dict[str, Any],
|
|
auth: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
|
|
"""One provider's `<provider>_search_well_architected` tool: fixed pillar and topic in, guidance excerpts out."""
|
|
pillar, topic = arguments.get("pillar"), arguments.get("topic")
|
|
if pillar not in KNOWLEDGE_PILLARS:
|
|
return _refuse("invalid_argument", "pillar must be one of: " + ", ".join(KNOWLEDGE_PILLARS))
|
|
if topic not in KNOWLEDGE_TOPICS:
|
|
return _refuse("invalid_argument", "topic must be one of: " + ", ".join(KNOWLEDGE_TOPICS))
|
|
query = f"{KNOWLEDGE_SERVERS[provider]['framework']} {pillar} {topic}"
|
|
try:
|
|
results = await _knowledge_search(provider, connection, query, auth)
|
|
except Exception as error:
|
|
return _upstream_failed(provider, error)
|
|
return {"success": True, "data": {"provider": provider, "pillar": pillar, "topic": topic, "results": results,
|
|
"collected_at": _collected_at(), "evidence_ref": _evidence_ref(tool, arguments, results)}}
|
|
|
|
async def gcp_check_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
try:
|
|
await _gcp_get(f"{GCP_ASSET_API}/{_gcp_scope()}:searchAllResources", {"pageSize": 1})
|
|
except Exception as error:
|
|
return {"ok": False, "message": _upstream_failed("gcp", error)["error"]["message"]}
|
|
return {"ok": True, "message": "Signed in and searched the scope root."}
|
|
|
|
async def gcp_list_accounts(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _gcp_kind("gcp_list_accounts", arguments, GCP_ACCOUNTS, "projects")
|
|
|
|
async def gcp_list_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
asset_type = arguments.get("asset_type")
|
|
if asset_type and not re.fullmatch(r"[a-z0-9.]+\.googleapis\.com/[A-Za-z0-9]+", str(asset_type)):
|
|
return _refuse("invalid_argument", "asset_type must look like compute.googleapis.com/Instance")
|
|
return await _gcp_search("gcp_list_resources", arguments, [asset_type] if asset_type else [])
|
|
|
|
async def gcp_query_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
query = str(arguments.get("query") or "").strip()
|
|
if not query or len(query) > 2000:
|
|
return _refuse("invalid_argument", "query is required, up to 2000 characters")
|
|
asset_type = arguments.get("asset_type")
|
|
return await _gcp_search("gcp_query_resources", arguments, [asset_type] if asset_type else [], query)
|
|
|
|
async def gcp_get_resource_metadata(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
name = str(arguments.get("resource_name") or "")
|
|
if not re.fullmatch(r"//[a-z0-9.]+\.googleapis\.com/[A-Za-z0-9._/\-]+", name):
|
|
return _refuse("invalid_argument", "resource_name must be a full resource name")
|
|
try:
|
|
body = await _gcp_get(f"{GCP_ASSET_API}/{_gcp_scope()}:searchAllResources", {"query": f'name="{name}"', "readMask": "*", "pageSize": 5})
|
|
except Exception as error:
|
|
return _upstream_failed("gcp", error)
|
|
found = [r for r in body.get("results", []) if r.get("name") == name]
|
|
if not found:
|
|
return _refuse("outside_scope", "no such resource under this connection's scope")
|
|
return _one_result("gcp", "gcp_get_resource_metadata", arguments, found[0])
|
|
|
|
async def gcp_list_servers(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _gcp_kind("gcp_list_servers", arguments, GCP_SERVERS, "instances")
|
|
|
|
async def gcp_list_workloads(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _gcp_kind("gcp_list_workloads", arguments, GCP_WORKLOADS, "cloud_run")
|
|
|
|
async def gcp_list_kubernetes_clusters(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _gcp_kind("gcp_list_kubernetes_clusters", arguments, GCP_KUBERNETES, "clusters")
|
|
|
|
async def gcp_get_network_topology(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _gcp_kind("gcp_get_network_topology", arguments, GCP_NETWORK, "networks")
|
|
|
|
async def gcp_list_data_stores(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _gcp_kind("gcp_list_data_stores", arguments, GCP_DATA, "cloud_sql")
|
|
|
|
async def gcp_list_organization_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
kind = arguments.get("kind") or "organization_policies"
|
|
if kind == "vpc_service_controls":
|
|
return await _gcp_kind("gcp_list_organization_policies", arguments, GCP_PERIMETERS, kind)
|
|
if kind != "organization_policies":
|
|
return _refuse("unknown_kind", "kind must be organization_policies or vpc_service_controls")
|
|
return await _gcp_page("gcp_list_organization_policies", arguments, f"{GCP_ORG_POLICY_API}/{_gcp_scope()}/policies", {}, "policies")
|
|
|
|
async def gcp_list_resource_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
params = {"query": arguments["query"]} if arguments.get("query") else {}
|
|
return await _gcp_page("gcp_list_resource_policies", arguments, f"{GCP_ASSET_API}/{_gcp_scope()}:searchAllIamPolicies", params, "results")
|
|
|
|
async def gcp_list_recommendations(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
project_id = str(arguments.get("project_id") or "")
|
|
location = str(arguments.get("location") or "global")
|
|
recommender = arguments.get("recommender") or GCP_RECOMMENDERS[0]
|
|
if recommender not in GCP_RECOMMENDERS:
|
|
return _refuse("unknown_kind", "recommender must be one of: " + ", ".join(GCP_RECOMMENDERS))
|
|
if not re.fullmatch(r"[a-z0-9\-]+", project_id) or not re.fullmatch(r"[a-z0-9\-]+", location):
|
|
return _refuse("invalid_argument", "project_id and location must be plain identifiers")
|
|
try:
|
|
allowed = await _gcp_project_in_scope(project_id)
|
|
except Exception as error:
|
|
return _upstream_failed("gcp", error)
|
|
if not allowed:
|
|
return _refuse("outside_scope", "project_id isn't under this connection's scope")
|
|
url = f"{GCP_RECOMMENDER_API}/projects/{project_id}/locations/{location}/recommenders/{recommender}/recommendations"
|
|
return await _gcp_page("gcp_list_recommendations", arguments, url, {}, "recommendations", _gcp_recommendation)
|
|
|
|
async def gcp_search_well_architected(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _knowledge_tool("gcp", "gcp_search_well_architected", arguments, get_connection(), await _gcp_auth(True))
|
|
|
|
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_list_accounts': gcp_list_accounts,
|
|
'gcp_list_resources': gcp_list_resources,
|
|
'gcp_query_resources': gcp_query_resources,
|
|
'gcp_get_resource_metadata': gcp_get_resource_metadata,
|
|
'gcp_list_servers': gcp_list_servers,
|
|
'gcp_list_workloads': gcp_list_workloads,
|
|
'gcp_list_kubernetes_clusters': gcp_list_kubernetes_clusters,
|
|
'gcp_get_network_topology': gcp_get_network_topology,
|
|
'gcp_list_data_stores': gcp_list_data_stores,
|
|
'gcp_list_organization_policies': gcp_list_organization_policies,
|
|
'gcp_list_resource_policies': gcp_list_resource_policies,
|
|
'gcp_list_recommendations': gcp_list_recommendations,
|
|
'gcp_search_well_architected': gcp_search_well_architected,
|
|
'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="Read-only discovery of a customer's Google Cloud estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Recommender findings - through Cloud Asset Inventory.",
|
|
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 <MCP_REGISTRATION_API_KEY>' 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
|
|
)
|