Files
orchestration_engine/execution_engine/tools/mcp.py

288 lines
9.7 KiB
Python

"""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 execution_engine.adk.runtime import ToolResult, ToolSpec
from execution_engine.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__