feat: working orhcestration engine
This commit is contained in:
287
execution_engine/tools/mcp.py
Normal file
287
execution_engine/tools/mcp.py
Normal file
@@ -0,0 +1,287 @@
|
||||
"""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__
|
||||
Reference in New Issue
Block a user