"""Remote MCP servers hosted by the Cloud provider, exposed as read-only ToolSpecs. Only tools on a server's reviewed allowlist are ever offered, and an allowlisted tool must declare `readOnlyHint: true` or loading fails. Tools keep the server's tier, so the Execution's cloud-read permission gate applies to them like any other tool. Failures become discovery gaps the agent records, never exceptions. """ from __future__ import annotations import asyncio import logging import re from collections.abc import AsyncIterator, Iterable, Mapping from contextlib import asynccontextmanager from dataclasses import dataclass from datetime import timedelta from typing import Any, Protocol import httpx from mcp import ClientSession from mcp.client.streamable_http import streamable_http_client from mcp.shared._httpx_utils import create_mcp_http_client from app.adk.runtime import ToolResult, ToolSpec from app.providers import McpServerSpec logger = logging.getLogger(__name__) GAP_INSTRUCTION = "Record this under 'Assumptions / discovery gaps' and continue." _MAX_TOOL_NAME = 64 _CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform" class McpConfigError(RuntimeError): """An MCP server or its allowlist can't be used safely.""" # --- auth ------------------------------------------------------------------------------ class McpAuth(Protocol): async def headers(self) -> dict[str, str]: ... class NoAuth: async def headers(self) -> dict[str, str]: return {} class StaticHeadersAuth: def __init__(self, headers: Mapping[str, str]) -> None: self._headers = dict(headers) async def headers(self) -> dict[str, str]: return dict(self._headers) class GoogleAdcAuth: """Bearer token from Application Default Credentials, plus the quota project.""" def __init__(self, quota_project: str | None = None) -> None: self._quota_project = quota_project self._credentials: Any = None self._project: str | None = None self._lock = asyncio.Lock() async def headers(self) -> dict[str, str]: async with self._lock: await asyncio.to_thread(self._refresh_if_needed) headers = {"Authorization": f"Bearer {self._credentials.token}"} project = self._quota_project or self._project if project: headers["X-Goog-User-Project"] = project return headers def _refresh_if_needed(self) -> None: import google.auth import google.auth.transport.requests if self._credentials is None: self._credentials, self._project = google.auth.default( scopes=[_CLOUD_PLATFORM_SCOPE] ) if not self._credentials.valid: self._credentials.refresh(google.auth.transport.requests.Request()) def auth_from_config( config: Mapping[str, Any], quota_project: str | None = None ) -> McpAuth: kind = config.get("kind", "none") if kind == "none": return NoAuth() if kind == "google_adc": return GoogleAdcAuth(quota_project) raise McpConfigError(f"Unsupported mcp_auth kind {kind!r}; use google_adc or none") # --- client ---------------------------------------------------------------------------- @dataclass(frozen=True) class McpToolInfo: name: str description: str input_schema: Mapping[str, Any] read_only: bool class McpClient: def __init__( self, server: McpServerSpec, auth: McpAuth, timeout: float = 30 ) -> None: self._server = server self._auth = auth self._timeout = timeout @asynccontextmanager async def _session(self) -> AsyncIterator[ClientSession]: headers = await self._auth.headers() async with ( create_mcp_http_client( headers=headers, timeout=httpx.Timeout(self._timeout) ) as http_client, streamable_http_client(self._server.url, http_client=http_client) as ( read, write, _, ), ClientSession( read, write, read_timeout_seconds=timedelta(seconds=self._timeout) ) as session, ): await session.initialize() yield session async def list_tools(self) -> list[McpToolInfo]: tools: list[McpToolInfo] = [] async with self._session() as session: cursor = None while True: page = await session.list_tools(cursor=cursor) for tool in page.tools: annotations = tool.annotations tools.append( McpToolInfo( name=tool.name, description=tool.description or tool.title or tool.name, input_schema=tool.inputSchema or {"type": "object"}, read_only=bool(annotations and annotations.readOnlyHint), ) ) cursor = page.nextCursor if not cursor: return tools async def call_tool( self, name: str, arguments: Mapping[str, Any] ) -> tuple[bool, str]: """Return (is_error, text).""" async with self._session() as session: result = await session.call_tool(name, dict(arguments)) text = "\n".join( getattr(item, "text", None) or str(item) for item in result.content ) if not text and result.structuredContent is not None: text = str(result.structuredContent) return bool(result.isError), text # --- catalog --------------------------------------------------------------------------- def tool_name(server_id: str, tool: str) -> str: """A tool name every model provider accepts: [A-Za-z0-9_-], at most 64 characters.""" name = re.sub(r"[^A-Za-z0-9_-]", "_", f"{server_id}__{tool}") return name[:_MAX_TOOL_NAME] class McpCatalog: def __init__(self) -> None: self._tools: dict[str, list[ToolSpec]] = {} self.gaps: dict[str, str] = {} @classmethod async def load( cls, servers: Iterable[McpServerSpec], auth: McpAuth, *, timeout: float = 30, max_result_chars: int = 20_000, ) -> McpCatalog: catalog = cls() pending = [server for server in servers if server.allow] results = await asyncio.gather( *(McpClient(server, auth, timeout).list_tools() for server in pending), return_exceptions=True, ) for server, listed in zip(pending, results, strict=True): client = McpClient(server, auth, timeout) if isinstance(listed, BaseException): reason = _describe(listed) logger.warning("MCP server %s unavailable: %s", server.id, reason) catalog.gaps[server.id] = reason catalog._tools[server.id] = [_unavailable_tool(server, reason)] continue by_name = {tool.name: tool for tool in listed} not_read_only = [ name for name in server.allow if name in by_name and not by_name[name].read_only ] if not_read_only: raise McpConfigError( f"MCP server {server.id} allowlists tools not marked readOnlyHint: " f"{', '.join(not_read_only)}. Remove them from the allowlist." ) missing = [name for name in server.allow if name not in by_name] if missing: catalog.gaps[server.id] = ( f"allowlisted tools not offered by the server: {', '.join(missing)}" ) catalog._tools[server.id] = [ _tool_spec(server, client, by_name[name], max_result_chars) for name in server.allow if name in by_name ] return catalog def tools_for(self, server_ids: Iterable[str]) -> list[ToolSpec]: return [ tool for server_id in server_ids for tool in self._tools.get(server_id, []) ] def _tool_spec( server: McpServerSpec, client: McpClient, info: McpToolInfo, max_chars: int ) -> ToolSpec: name = tool_name(server.id, info.name) async def call(**arguments: Any) -> ToolResult: try: is_error, text = await client.call_tool(info.name, arguments) except Exception as exc: # noqa: BLE001 - a remote failure is a discovery gap return ToolResult( f"Discovery gap: {name} failed ({_describe(exc)}). {GAP_INSTRUCTION}" ) if is_error: return ToolResult( f"Discovery gap: {name} failed ({text}). {GAP_INSTRUCTION}" ) if len(text) > max_chars: text = text[:max_chars] + "\n[truncated]" return ToolResult(text) return ToolSpec( name, f"[{server.id} MCP, read-only] {info.description}", dict(info.input_schema), call, tier=server.tier, ) def _unavailable_tool(server: McpServerSpec, reason: str) -> ToolSpec: async def report(**_: Any) -> ToolResult: return ToolResult( f"Discovery gap: {server.id} MCP server unavailable ({reason}). {GAP_INSTRUCTION}" ) return ToolSpec( tool_name(server.id, "unavailable"), f"The {server.id} MCP server could not be reached; call to get the reason.", {"type": "object", "properties": {}}, report, tier=server.tier, ) def _describe(exc: BaseException) -> str: grouped = getattr(exc, "exceptions", None) # ExceptionGroup from anyio task groups if grouped: return _describe(grouped[0]) return f"{type(exc).__name__}: {exc}" if str(exc) else type(exc).__name__