Skip to content

"Vibe-Trading: Your Personal Trading Agent"

54.7 KB
Raw Blame
"""MCP client adapter and remote tool wrappers."""

from __future__ import annotations

import asyncio
import hashlib
import json
import logging
import os
import re
import threading
import webbrowser
from collections.abc import AsyncGenerator, Mapping
from copy import deepcopy
from dataclasses import dataclass, is_dataclass
from typing import Any, Awaitable, Callable, Coroutine, Iterable, Protocol, TypeVar
from urllib.parse import urlparse

import httpx
from fastmcp.client import Client
from fastmcp.client.auth import OAuth
from fastmcp.client.auth.oauth import ClientNotFoundError
from fastmcp.client.client import CallToolResult
try:
    from fastmcp.client.transports.http import StreamableHttpTransport
    from fastmcp.client.transports.sse import SSETransport
    from fastmcp.client.transports.stdio import StdioTransport
except ModuleNotFoundError:
    from fastmcp.client.transports import (
        SSETransport,
        StdioTransport,
        StreamableHttpTransport,
    )
from fastmcp.exceptions import McpError, ToolError
from key_value.aio.stores.filetree import FileTreeStore, FileTreeV1KeySanitizationStrategy
from mcp import types as mcp_types
from mcp.shared.auth import OAuthMetadata
from pydantic_core import PydanticSerializationError, to_jsonable_python

from src.agent.tools import BaseTool
from src.config.schema import (
    ROBINHOOD_AGENT_CONFIG_PATH,
    MCPOAuthConfig,
    MCPServerConfig,
    live_broker_key_for_entry,
    robinhood_readonly_enabled_tools,
)

logger = logging.getLogger(__name__)

_NAME_SEGMENT_RE = re.compile(r"[^a-z0-9]+")
_SCHEMA_COMPOSITION_KEYS = ("anyOf", "oneOf", "allOf")
_LOCAL_ONLY_ARGUMENTS = {"run_dir"}
_TRANSIENT_ERROR_TOKENS = (
    "broken pipe",
    "connection closed",
    "connection reset",
    "eof",
    "temporar",
    "timed out",
    "timeout",
    "try again",
    "unavailable",
)

ResultT = TypeVar("ResultT")

_MCP_SPECS_CACHE: dict[tuple[str, ...], list["MCPRemoteToolSpec"]] = {}
_MCP_SPECS_LOCK = threading.Lock()


def _fingerprint(text: str) -> str:
    """One-way fingerprint for a cache-key component that may carry secrets."""
    return hashlib.sha256(text.encode("utf-8")).hexdigest()


def _fingerprint_auth(auth: MCPOAuthConfig | None) -> str:
    """Fingerprint an MCP server's OAuth config, never storing it raw.

    ``MCPOAuthConfig.client_secret`` is a real credential, so the whole
    config is hashed as one unit rather than spread across raw tuple
    elements.
    """
    if auth is None:
        return _fingerprint("")
    canonical = "|".join(
        [
            auth.type,
            str(sorted(auth.scopes)),
            auth.client_name,
            auth.cache_dir,
            str(auth.callback_port),
            auth.client_id or "",
            auth.client_secret or "",
            auth.client_metadata_url or "",
        ]
    )
    return _fingerprint(canonical)


class _GuardedOAuth(OAuth):
    """FastMCP OAuth that can refuse to start a browser-based authorization flow.

    Non-interactive callers (background pollers, API request handlers, scheduled
    jobs) must never have a browser window opened on the host on their behalf.
    Constructing this provider with ``allow_interactive=False`` turns the
    browser step into a loud ``RuntimeError`` so the caller can tell the user to
    run the explicit connect/reconnect step instead. With
    ``allow_interactive=True`` the provider behaves exactly like
    :class:`fastmcp.client.auth.OAuth`.
    """

    def __init__(self, *args: Any, allow_interactive: bool = True, **kwargs: Any) -> None:
        """Initialize the OAuth provider.

        Args:
            *args: Positional arguments forwarded to ``fastmcp``'s ``OAuth``.
            allow_interactive: When False, ``redirect_handler`` raises instead of
                opening a browser for user consent.
            **kwargs: Keyword arguments forwarded to ``fastmcp``'s ``OAuth``.
        """
        self._allow_interactive = allow_interactive
        super().__init__(*args, **kwargs)

    async def redirect_handler(self, authorization_url: str) -> None:
        """Hand the authorization URL to the user's browser, or refuse to.

        Args:
            authorization_url: Authorization endpoint URL built by the OAuth
                client for user consent.

        Returns:
            None.

        Raises:
            RuntimeError: If this provider was built with
                ``allow_interactive=False``.
        """
        if not self._allow_interactive:
            raise RuntimeError(
                "OAuth authorization required; run the interactive connect/reconnect step"
            )
        await super().redirect_handler(authorization_url)


class _IBKROAuth(_GuardedOAuth):
    """Add the browser headers required by IBKR's OAuth WAF."""

    async def _refresh_token(self) -> httpx.Request:
        if self.context.oauth_metadata is None:
            self.context.oauth_metadata = OAuthMetadata(
                issuer="https://api.ibkr.com",
                authorization_endpoint="https://api.ibkr.com/oauth2/authorize",
                token_endpoint="https://api.ibkr.com/oauth2/api/v1/token",
                registration_endpoint="https://api.ibkr.com/oauth2/register",
            )
        return await super()._refresh_token()

    async def _initialize(self) -> None:
        await super()._initialize()
        client_info = self.context.client_info
        registered_redirects = {
            str(uri) for uri in (getattr(client_info, "redirect_uris", None) or [])
        }
        current_redirect = str(self.context.client_metadata.redirect_uris[0])
        if (
            client_info is not None
            and self._static_client_info is None
            and registered_redirects
            and current_redirect not in registered_redirects
        ):
            await self.token_storage_adapter.clear()
            self.context.client_info = None
            self.context.current_tokens = None
            self.context.token_expiry_time = None

    async def async_auth_flow(
        self, request: httpx.Request
    ) -> AsyncGenerator[httpx.Request, httpx.Response]:
        flow = super().async_auth_flow(request)
        response = None
        try:
            while True:
                try:
                    oauth_request = await flow.asend(response)
                except StopAsyncIteration:
                    break
                if oauth_request.url.host == "api.ibkr.com":
                    oauth_request.headers["User-Agent"] = "Mozilla/5.0"
                    if not oauth_request.url.path.startswith("/v1/api/mcp"):
                        oauth_request.headers["Accept"] = "application/json"
                    if oauth_request.url.path == "/oauth2/register":
                        oauth_request.headers["Origin"] = "https://api.ibkr.com"
                response = yield oauth_request
        finally:
            await flow.aclose()

    async def redirect_handler(self, authorization_url: str) -> None:
        if not self._allow_interactive:
            await super().redirect_handler(authorization_url)
            return
        async with self.httpx_client_factory() as client:
            response = await client.get(
                authorization_url,
                headers={
                    "User-Agent": "Mozilla/5.0",
                    "Accept": "application/json",
                },
                follow_redirects=False,
            )
        if response.status_code == 400:
            raise ClientNotFoundError(
                "OAuth client not found - cached credentials may be stale"
            )
        if response.status_code not in (200, 301, 302, 303, 307, 308):
            raise RuntimeError(
                f"Unexpected authorization response: {response.status_code}"
            )
        webbrowser.open(authorization_url)


def _make_cache_key(server_name: str, server_config: "MCPServerConfig") -> tuple[str, ...]:
    """Build a content-based cache key for MCP tool discovery results.

    Every field that can change the tool specs a server returns must
    participate in cache identity (mirrors the enabled_tools fix this cache
    key already went through once). ``url``, ``headers``, and ``auth`` are
    fingerprinted rather than stored raw: a URL can carry a credential in
    its query string, a header can carry a static bearer token, and
    ``auth`` can carry an OAuth client secret. None of those should sit as
    plaintext in a process-wide in-memory cache key.
    """
    return (
        server_name,
        str(server_config.type),
        server_config.command,
        str(server_config.args or []),
        str(sorted((server_config.env or {}).items())),
        str(sorted(server_config.enabled_tools or [])),
        _fingerprint(server_config.url or ""),
        _fingerprint(str(sorted((server_config.headers or {}).items()))),
        _fingerprint_auth(server_config.auth),
    )


def invalidate_mcp_specs_cache() -> None:
    """Clear the MCP tool discovery cache.

    Called by SwarmRuntime at the start of each run to ensure fresh
    discovery when operator config may have changed between runs.
    """
    with _MCP_SPECS_LOCK:
        _MCP_SPECS_CACHE.clear()


class AsyncMCPClient(Protocol):
    """Protocol for async MCP clients used by the adapter."""

    async def __aenter__(self) -> "AsyncMCPClient":
        """Enter the async client context."""
        ...

    async def __aexit__(
        self,
        exc_type: type[BaseException] | None,
        exc_val: BaseException | None,
        exc_tb: Any,
        /,
    ) -> None:
        """Exit the async client context."""
        ...

    async def list_tools(self) -> list[mcp_types.Tool]:
        """List tools exposed by the remote MCP server."""
        ...

    async def call_tool(
        self,
        name: str,
        arguments: dict[str, Any] | None = None,
        *,
        timeout: float | int | None = None,
        raise_on_error: bool = False,
    ) -> CallToolResult:
        """Call a remote MCP tool."""
        ...


ClientFactory = Callable[[], AsyncMCPClient]


@dataclass(frozen=True)
class MCPRemoteToolSpec:
    """Resolved metadata for one remote MCP tool.

    Attributes:
        annotations: Server-asserted MCP tool annotations (``readOnlyHint`` /
            ``destructiveHint`` / etc.), or ``None`` when the server omits them.
            These are advisory hints from a possibly-untrusted server and must
            never be the sole basis for relaxing safety — the live classification
            layer (P1) treats them as one tier behind the curated map.
    """

    server_name: str
    remote_name: str
    local_name: str
    description: str
    parameters: dict[str, Any]
    annotations: mcp_types.ToolAnnotations | None = None


def build_mcp_tool_wrappers(
    server_name: str,
    server_config: MCPServerConfig,
    *,
    local_server_name: str | None = None,
    client_factory: ClientFactory | None = None,
    max_list_tools_attempts: int = 2,
) -> list["MCPRemoteTool"]:
    """Build local tool wrappers for a configured MCP server.

    Args:
        server_name: Logical server name from config.
        server_config: Validated stdio MCP server config.
        local_server_name: Optional local naming override for the server
            portion of generated tool names. This lets registry assembly keep
            tool names stable when multiple raw server names sanitize to the
            same local prefix.
        client_factory: Optional async client factory for tests.
        max_list_tools_attempts: Number of ``list_tools`` attempts during tool
            discovery. Defaults to 2 (one transient retry). Set to 1 for the
            interactive ``connector authorize`` bootstrap, where a retry would
            start a second OAuth callback server and orphan the user's
            in-progress sign-in.

    Returns:
        Local BaseTool wrappers for all enabled remote tools.

    Raises:
        Exception: Propagates discovery failures so callers can decide whether
            to warn, skip, or abort.
    """
    # --- Cache lookup (thread-safe) ---
    # Skip cache when a custom client_factory is provided (test injection).
    cache_key: tuple[str, ...] | None = None
    if client_factory is None:
        cache_key = _make_cache_key(server_name, server_config)
        with _MCP_SPECS_LOCK:
            cached_specs = _MCP_SPECS_CACHE.get(cache_key)
        if cached_specs is not None:
            adapter = MCPServerAdapter(
                server_name,
                server_config,
                local_server_name=local_server_name,
                client_factory=client_factory,
                max_list_tools_attempts=max_list_tools_attempts,
            )
            return [MCPRemoteTool(adapter=adapter, spec=spec) for spec in cached_specs]

    # --- Original logic (cache miss) ---
    adapter = MCPServerAdapter(
        server_name,
        server_config,
        local_server_name=local_server_name,
        client_factory=client_factory,
        max_list_tools_attempts=max_list_tools_attempts,
    )
    specs = adapter.discover_tools()

    # Store in cache (only for production path, not test injection)
    if cache_key is not None:
        with _MCP_SPECS_LOCK:
            _MCP_SPECS_CACHE[cache_key] = specs

    return [MCPRemoteTool(adapter=adapter, spec=spec) for spec in specs]


def make_mcp_tool_name(server_name: str, tool_name: str) -> str:
    """Create the stable local tool name for a remote MCP tool.

    Args:
        server_name: Logical MCP server name.
        tool_name: Remote tool name reported by the MCP server.

    Returns:
        Stable local tool name in ``mcp_<server>_<tool>`` format.
    """
    return f"mcp_{_sanitize_name_segment(server_name)}_{_sanitize_name_segment(tool_name)}"


def format_mcp_server_name_collision_warning(server_name: str, local_server_name: str) -> str:
    """Build operator-facing warning text for sanitized server-name collisions.

    Args:
        server_name: Raw MCP server name from config.
        local_server_name: Unique local server-name segment assigned after
            collision disambiguation.

    Returns:
        Warning copy suitable for CLI, SessionService, and logs.
    """
    return (
        f"Configured MCP server '{server_name}' collides with another server after local name normalization. "
        f"Using local tool prefix 'mcp_{local_server_name}_<tool>' to keep generated tool names unique. "
        "Rename the server in agent config if you want a different prefix."
    )


def resolve_mcp_server_tool_name_segments(
    server_names: Iterable[str],
    warn_callback: Callable[[str], None] | None = None,
) -> dict[str, str]:
    """Resolve unique local server-name segments for MCP tool names.

    The first release keeps MCP tool names ASCII-safe by sanitizing server
    names. Different raw server names can therefore collapse to the same local
    segment, such as ``foo-bar`` and ``foo_bar`` both becoming ``foo_bar``.
    When that happens, all members of the colliding group receive a stable hash
    suffix at the server-segment level so local tool names remain unique
    without depending on config order.

    Args:
        server_names: Ordered raw MCP server names from config.
        warn_callback: Optional callable invoked with the operator-facing
            warning message when a server-name collision is detected and
            disambiguated. Receives the same text as ``logger.warning`` so
            callers (CLI, SessionService) can surface it to operators.

    Returns:
        Mapping of raw server names to unique local server-name segments.
    """
    ordered_names = list(server_names)
    base_counts: dict[str, int] = {}
    for server_name in ordered_names:
        base_segment = _sanitize_name_segment(server_name)
        base_counts[base_segment] = base_counts.get(base_segment, 0) + 1

    resolved_segments: dict[str, str] = {}
    used_segments: set[str] = set()
    for server_name in ordered_names:
        base_segment = _sanitize_name_segment(server_name)
        if base_counts[base_segment] == 1 and base_segment not in used_segments:
            resolved_segments[server_name] = base_segment
            used_segments.add(base_segment)
            continue

        unique_segment = _dedupe_server_name_segment(base_segment, server_name, used_segments)
        warning_text = format_mcp_server_name_collision_warning(server_name, unique_segment)
        logger.warning(warning_text)
        if warn_callback is not None:
            warn_callback(warning_text)
        resolved_segments[server_name] = unique_segment
        used_segments.add(unique_segment)

    return resolved_segments


def normalize_mcp_tool_schema(schema: dict[str, Any] | None) -> dict[str, Any]:
    """Normalize remote MCP input schemas into OpenAI-compatible objects.

    Args:
        schema: Raw MCP input schema.

    Returns:
        A JSON Schema object with top-level object semantics and nullable forms
        reduced to non-null branches where possible.
    """
    normalized = _normalize_schema_node(deepcopy(schema) if isinstance(schema, dict) else {})
    normalized = _collapse_nullable_union(normalized)

    if not isinstance(normalized, dict):
        return {"type": "object", "properties": {}, "required": []}

    if _schema_looks_object_like(normalized):
        normalized["type"] = "object"
    else:
        return {"type": "object", "properties": {}, "required": []}

    properties = normalized.get("properties")
    if properties is not None and not isinstance(properties, dict):
        normalized.pop("properties", None)
        properties = None
    if not isinstance(properties, dict) and not _schema_uses_composed_top_level_rules(normalized):
        normalized["properties"] = {}

    required = normalized.get("required")
    if required is None and not _schema_uses_composed_top_level_rules(normalized):
        normalized["required"] = []
    elif isinstance(required, list):
        normalized["required"] = [item for item in required if isinstance(item, str)]
    elif required is not None:
        normalized.pop("required", None)

    return normalized


def _format_zero_enabled_tools_warning(server_name: str, server_config: MCPServerConfig) -> str:
    """Build a warning when discovery yields no locally enabled tools."""
    enabled_tools = list(getattr(server_config, "enabled_tools", []) or [])
    if "*" in enabled_tools and live_broker_key_for_entry(server_name, server_config) == "robinhood":
        tools = ", ".join(robinhood_readonly_enabled_tools())
        return (
            f"Server '{server_name}' produced 0 enabled tools with wildcard enabledTools ['*']. "
            "Robinhood live MCP must use the safe read-only allowlist "
            f"({tools}); copy the safe seed into {ROBINHOOD_AGENT_CONFIG_PATH}."
        )
    return f"Server '{server_name}' produced 0 enabled tools — check the enabledTools allowlist in agent config."


def _build_token_store(cache_dir: str) -> FileTreeStore:
    """Build a persistent OAuth token store rooted at ``cache_dir``.

    The directory is created (with parents) and locked down to ``0700`` so only
    the owning user can read the cached refresh tokens. ``FileTreeStore`` is a
    pure-stdlib ``AsyncKeyValue`` backend (no ``diskcache`` dependency) and uses
    atomic same-directory temp-file renames for write safety. FastMCP's OAuth
    storage uses raw MCP URLs as logical keys, so key sanitization is enabled to
    keep those URL-shaped keys as filesystem-safe cache-local filenames. The
    collection names stay unchanged because token-presence checks scan FastMCP's
    literal ``mcp-oauth-token`` collection directory.

    Args:
        cache_dir: Token cache directory. A leading ``~`` is expanded.

    Returns:
        A ``FileTreeStore`` rooted at the resolved cache directory.
    """
    from pathlib import Path

    path = Path(cache_dir).expanduser()
    path.mkdir(parents=True, exist_ok=True)
    # 0700: owner-only. Tokens are secrets; no group/other access.
    os.chmod(path, 0o700)
    return FileTreeStore(
        data_directory=path,
        key_sanitization_strategy=FileTreeV1KeySanitizationStrategy(path),
    )


class MCPServerAdapter:
    """Synchronous wrapper around the async FastMCP client."""

    def __init__(
        self,
        server_name: str,
        server_config: MCPServerConfig,
        *,
        local_server_name: str | None = None,
        client_factory: ClientFactory | None = None,
        max_list_tools_attempts: int = 2,
        interactive_oauth: bool = True,
    ) -> None:
        """Initialize the MCP server adapter.

        Args:
            server_name: Logical server name from config.
            server_config: Validated MCP server config.
            local_server_name: Optional local naming override used only for the
                server portion of generated tool names.
            client_factory: Optional async client factory, mainly for tests.
            max_list_tools_attempts: Number of ``list_tools`` attempts (>= 1).
                Defaults to 2 (one transient retry). The authorize bootstrap
                sets this to 1 so a retry cannot start a second OAuth callback
                server and orphan an in-progress sign-in.
            interactive_oauth: When False, an OAuth flow that needs fresh user
                consent raises instead of opening a browser on the host. Callers
                that run without a user in front of them pass False.
        """
        self.server_name = server_name
        self.local_server_name = local_server_name or server_name
        self.server_config = server_config
        self._client_factory = client_factory or self._build_client
        self._list_tools_attempts = max(1, max_list_tools_attempts)
        self._interactive_oauth = interactive_oauth

    def discover_tools(self) -> list[MCPRemoteToolSpec]:
        """Discover enabled tools from the remote MCP server.

        Returns:
            Resolved tool specs for enabled remote tools.

        Raises:
            Exception: Propagates discovery failures after retry exhaustion.
        """
        try:
            tools = _run_sync(self._list_tools)
        except httpx.HTTPStatusError as exc:
            # Same reason as _http_error_body: discovery propagates raw, so the
            # traceback the user sees would otherwise carry no server detail.
            if body := _http_error_body(exc):
                raise httpx.HTTPStatusError(
                    f"{exc} - server said: {body}",
                    request=exc.request,
                    response=exc.response,
                ) from exc
            raise
        seen_names: dict[str, str] = {}
        specs: list[MCPRemoteToolSpec] = []

        for tool in tools:
            if not _tool_is_enabled(tool.name, self.server_config.enabled_tools):
                continue

            local_name = _dedupe_local_tool_name(
                make_mcp_tool_name(self.local_server_name, tool.name),
                tool.name,
                seen_names,
            )
            specs.append(
                MCPRemoteToolSpec(
                    server_name=self.server_name,
                    remote_name=tool.name,
                    local_name=local_name,
                    description=(tool.description or f"Remote MCP tool {tool.name} from {self.server_name}."),
                    parameters=normalize_mcp_tool_schema(getattr(tool, "inputSchema", None)),
                    annotations=getattr(tool, "annotations", None),
                )
            )

        if not specs:
            logger.warning(_format_zero_enabled_tools_warning(self.server_name, self.server_config))

        return specs

    def call_tool(
        self,
        remote_name: str,
        arguments: dict[str, Any],
        *,
        local_name: str | None = None,
    ) -> dict[str, Any]:
        """Call one remote MCP tool and normalize its result.

        Args:
            remote_name: Remote tool identifier.
            arguments: Tool arguments to forward.
            local_name: Optional local wrapper name for logging/payloads.

        Returns:
            Normalized result payload ready for JSON serialization.
        """
        try:
            result = _run_sync(lambda: self._call_tool(remote_name, arguments))
            payload = _normalize_call_tool_result(result)
            payload.update({
                "server": self.server_name,
                "remote_tool": remote_name,
                "tool": local_name or remote_name,
            })
            return payload
        except Exception as exc:
            return {
                "status": "error",
                "server": self.server_name,
                "remote_tool": remote_name,
                "tool": local_name or remote_name,
                "error": _format_exception_message(exc),
                "error_type": type(exc).__name__,
            }

    def _build_client(self) -> AsyncMCPClient:
        """Create the default FastMCP client from MCP transport config.

        Returns:
            Configured async FastMCP client.
        """
        transport_type = self.server_config.resolved_transport()

        if transport_type == "stdio":
            env = os.environ.copy()
            env.update(self.server_config.env)
            transport = StdioTransport(
                command=self.server_config.command,
                args=list(self.server_config.args),
                env=env,
                keep_alive=False,
            )
        elif transport_type == "sse":
            transport = SSETransport(
                url=self.server_config.url,
                headers=dict(self.server_config.headers) or None,
            )
        else:
            auth = None
            if self.server_config.auth is not None:
                oauth_config = self.server_config.auth
                # fastmcp's OAuth pre-flights the authorization URL with a
                # client built by `httpx_client_factory`; httpx defaults that to
                # a 5 s deadline, which is short for a consent endpoint. Reuse
                # the server's configured init_timeout instead.
                oauth_http_timeout = (
                    self.server_config.init_timeout
                    if self.server_config.init_timeout is not None
                    else max(self.server_config.tool_timeout, 30.0)
                )
                # `mcp_url` is intentionally omitted — StreamableHttpTransport
                # calls `auth._bind(self.url)` so the URL fills in from the
                # transport. Token cache is persistent (FileTreeStore), so the
                # channel stays authorized across CLI invocations and refresh is
                # handled inside the MCP lib's OAuthClientProvider.
                is_ibkr = urlparse(self.server_config.url).hostname == "api.ibkr.com"
                oauth_type = _IBKROAuth if is_ibkr else _GuardedOAuth
                auth = oauth_type(
                    scopes=list(oauth_config.scopes) or None,
                    client_name=oauth_config.client_name,
                    token_storage=_build_token_store(oauth_config.cache_dir),
                    additional_client_metadata=(
                        {"token_endpoint_auth_method": "none"} if is_ibkr else None
                    ),
                    callback_port=(
                        oauth_config.callback_port
                        or (8765 if is_ibkr else None)
                    ),
                    client_id=oauth_config.client_id,
                    client_secret=oauth_config.client_secret,
                    client_metadata_url=oauth_config.client_metadata_url,
                    httpx_client_factory=lambda: httpx.AsyncClient(
                        timeout=oauth_http_timeout,
                        trust_env=True,
                    ),
                    allow_interactive=self._interactive_oauth,
                )
            transport = StreamableHttpTransport(
                url=self.server_config.url,
                headers=dict(self.server_config.headers) or None,
                auth=auth,
            )

        # Use a minimum of 30 s for init_timeout so cold-start servers (pip
        # install, docker pull, slow imports) do not trip the same short
        # deadline as a per-call tool_timeout. OAuth-heavy servers may set an
        # explicit init_timeout without widening ordinary tool-call timeout.
        init_timeout = (
            self.server_config.init_timeout
            if self.server_config.init_timeout is not None
            else max(self.server_config.tool_timeout, 30.0)
        )
        return Client(
            transport,
            name=self.server_name,
            timeout=self.server_config.tool_timeout,
            init_timeout=init_timeout,
        )

    async def _list_tools(self) -> list[mcp_types.Tool]:
        """List remote tools, retrying once on transient failures by default.

        The number of attempts is governed by ``self._list_tools_attempts``
        (1 disables the retry, used by the authorize bootstrap).

        Returns:
            Remote MCP tool definitions.

        Raises:
            Exception: Propagates non-transient or exhausted failures.
        """
        return await self._run_with_retry(
            "list_tools",
            self._list_tools_once,
            attempts=self._list_tools_attempts,
        )

    async def _list_tools_once(self) -> list[mcp_types.Tool]:
        """List remote tools without retry handling.

        Returns:
            Remote MCP tool definitions.
        """
        async with self._client_factory() as client:
            return await client.list_tools()

    async def _call_tool(self, remote_name: str, arguments: dict[str, Any]) -> CallToolResult:
        """Call a remote tool with timeout and no automatic retry.

        Args:
            remote_name: Remote tool name.
            arguments: Arguments to forward.

        Returns:
            Parsed FastMCP call result.

        Raises:
            Exception: Propagates non-transient or exhausted failures.
        """
        async def _invoke() -> CallToolResult:
            async with self._client_factory() as client:
                return await client.call_tool(
                    remote_name,
                    arguments=arguments,
                    timeout=self.server_config.tool_timeout,
                    raise_on_error=False,
                )

        # Remote MCP tools are arbitrary and may mutate external state. If a
        # timeout / connection drop happens after the server has already
        # committed the action, retrying here would duplicate the side effect.
        return await _invoke()

    async def _run_with_retry(
        self,
        operation_name: str,
        operation: Callable[[], Awaitable[ResultT]],
        *,
        attempts: int = 2,
    ) -> ResultT:
        """Run an async MCP operation with bounded transient retries.

        Args:
            operation_name: Human-readable operation label.
            operation: Async operation to execute.
            attempts: Maximum attempts (>= 1). Defaults to 2 (one transient
                retry). Pass 1 to disable retry — used by the authorize
                bootstrap, where a retry restarts the OAuth flow.

        Returns:
            Operation result.

        Raises:
            Exception: Re-raises the last failure when retry is not allowed or
                all attempts fail.
        """
        attempts = max(1, attempts)
        for attempt in range(1, attempts + 1):
            try:
                return await operation()
            except Exception as exc:
                if attempt >= attempts or not _is_retryable_error(exc):
                    raise
                logger.warning(
                    "Retrying MCP operation %s for server %s after transient failure: %s",
                    operation_name,
                    self.server_name,
                    exc,
                )


class MCPRemoteTool(BaseTool):
    """BaseTool wrapper for a discovered remote MCP tool."""

    name = ""
    description = ""
    parameters: dict[str, Any]
    repeatable = True
    is_readonly = False

    def __init__(self, adapter: MCPServerAdapter, spec: MCPRemoteToolSpec) -> None:
        """Initialize a remote MCP tool wrapper.

        Args:
            adapter: Adapter used to invoke the remote server.
            spec: Resolved local metadata for the remote tool.
        """
        self._adapter = adapter
        self._spec = spec
        self.name = spec.local_name
        self.description = spec.description
        self.parameters = spec.parameters

    def execute(self, **kwargs: Any) -> str:
        """Execute the remote MCP tool and return normalized JSON.

        Args:
            **kwargs: Tool arguments from the agent loop.

        Returns:
            JSON string with normalized success or error payload.
        """
        payload = self._adapter.call_tool(
            self._spec.remote_name,
            self._filter_arguments(kwargs),
            local_name=self.name,
        )
        payload = compact_result_for_agent(payload)
        return json.dumps(payload, ensure_ascii=False, default=_json_default)

    def _filter_arguments(self, arguments: dict[str, Any]) -> dict[str, Any]:
        """Drop local-only arguments before forwarding to the remote tool.

        Args:
            arguments: Raw arguments from the local agent loop.

        Returns:
            Filtered arguments compatible with the remote tool schema.
        """
        allowed_keys = _collect_top_level_property_names(self.parameters)
        allow_additional = _schema_allows_additional_top_level_keys(self.parameters)

        if allowed_keys:
            return {
                key: value
                for key, value in arguments.items()
                if key in allowed_keys or (allow_additional and key not in _LOCAL_ONLY_ARGUMENTS)
            }

        if allow_additional:
            return {
                key: value
                for key, value in arguments.items()
                if key not in _LOCAL_ONLY_ARGUMENTS
            }

        return {}


def _run_sync(operation: Callable[[], Coroutine[Any, Any, ResultT]]) -> ResultT:
    """Run an async operation from sync code.

    Args:
        operation: Async callable to execute.

    Returns:
        Result returned by the async callable.

    Raises:
        BaseException: Re-raises exceptions from the async operation.
    """
    try:
        asyncio.get_running_loop()
    except RuntimeError:
        return asyncio.run(operation())

    result: dict[str, ResultT] = {}
    failure: dict[str, BaseException] = {}

    def _runner() -> None:
        try:
            result["value"] = asyncio.run(operation())
        except BaseException as exc:
            failure["error"] = exc

    thread = threading.Thread(target=_runner, daemon=True)
    thread.start()
    thread.join()

    if "error" in failure:
        raise failure["error"]
    return result["value"]


def _sanitize_name_segment(value: str) -> str:
    """Normalize a server or tool name segment for stable local naming.

    Args:
        value: Raw server or tool name.

    Returns:
        Lowercase ASCII-safe identifier segment.
    """
    normalized = _NAME_SEGMENT_RE.sub("_", value.strip().lower()).strip("_")
    return normalized or "tool"


def _dedupe_server_name_segment(base_segment: str, server_name: str, used_segments: set[str]) -> str:
    """Disambiguate colliding sanitized server-name segments.

    Args:
        base_segment: Preferred sanitized server-name segment.
        server_name: Raw server name from config.
        used_segments: Already-assigned local server-name segments.

    Returns:
        Unique local server-name segment.
    """
    suffix_source = server_name.encode("utf-8")
    unique_segment = f"{base_segment}_{hashlib.sha1(suffix_source).hexdigest()[:8]}"
    salt = 1
    while unique_segment in used_segments:
        unique_segment = (
            f"{base_segment}_{hashlib.sha1(suffix_source + f':{salt}'.encode('utf-8')).hexdigest()[:8]}"
        )
        salt += 1
    return unique_segment


def _dedupe_local_tool_name(candidate: str, remote_name: str, seen_names: dict[str, str]) -> str:
    """Disambiguate colliding local MCP tool names deterministically.

    Args:
        candidate: Preferred local tool name.
        remote_name: Original remote tool name.
        seen_names: Mapping of assigned local names to remote names.

    Returns:
        Unique local tool name for one server.
    """
    existing_remote = seen_names.get(candidate)
    if existing_remote is None:
        seen_names[candidate] = remote_name
        return candidate
    if existing_remote == remote_name:
        return candidate

    suffix_source = remote_name.encode("utf-8")
    unique_name = f"{candidate}_{hashlib.sha1(suffix_source).hexdigest()[:8]}"
    salt = 1
    while unique_name in seen_names and seen_names[unique_name] != remote_name:
        unique_name = f"{candidate}_{hashlib.sha1(suffix_source + f':{salt}'.encode('utf-8')).hexdigest()[:8]}"
        salt += 1

    logger.warning("Disambiguated MCP tool name collision: %s -> %s", remote_name, unique_name)
    seen_names[unique_name] = remote_name
    return unique_name


def _tool_is_enabled(tool_name: str, enabled_tools: list[str]) -> bool:
    """Check whether a remote tool passes the config allowlist.

    Args:
        tool_name: Remote tool name.
        enabled_tools: Configured allowlist.

    Returns:
        ``True`` when the tool should be exposed locally.
    """
    if not enabled_tools:
        return False
    return "*" in enabled_tools or tool_name in enabled_tools


def _normalize_schema_node(value: Any) -> Any:
    """Recursively normalize nullable JSON Schema fragments.

    Args:
        value: Schema fragment.

    Returns:
        Normalized schema fragment.
    """
    if isinstance(value, dict):
        normalized = {key: _normalize_schema_node(item) for key, item in value.items()}
        normalized_type = normalized.get("type")
        if isinstance(normalized_type, list):
            non_null_types = [item for item in normalized_type if item != "null"]
            if not non_null_types:
                normalized.pop("type", None)
            elif len(non_null_types) == 1:
                normalized["type"] = non_null_types[0]
            else:
                normalized["type"] = non_null_types
        elif normalized_type == "null":
            normalized.pop("type", None)

        for key in ("anyOf", "oneOf"):
            norm_branches = normalized.get(key)
            orig_branches = value.get(key)
            if isinstance(norm_branches, list) and isinstance(orig_branches, list):
                # Check nullness against the *original* branch before recursive
                # normalization strips the "type" key from {"type": "null"} → {}.
                # This preserves Copilot's requirement: {} means "accept anything"
                # in JSON Schema and must NOT be treated as null-only.
                normalized[key] = [
                    nb for nb, ob in zip(norm_branches, orig_branches)
                    if not _is_null_schema(ob)
                ]

        return normalized

    if isinstance(value, list):
        return [_normalize_schema_node(item) for item in value]

    return value


def _collapse_nullable_union(schema: dict[str, Any]) -> dict[str, Any]:
    """Collapse top-level nullable unions when a single non-null branch exists.

    Args:
        schema: Normalized schema.

    Returns:
        Collapsed schema when possible; otherwise the original schema.
    """
    for key in ("anyOf", "oneOf"):
        branches = schema.get(key)
        if isinstance(branches, list) and len(branches) == 1 and isinstance(branches[0], dict):
            merged = dict(schema)
            merged.pop(key, None)
            merged.update(branches[0])
            return merged
    return schema


def _schema_looks_object_like(schema: dict[str, Any]) -> bool:
    """Return whether a schema appears to describe a top-level object."""
    if schema.get("type") == "object":
        return True
    if isinstance(schema.get("properties"), dict):
        return True
    if "additionalProperties" in schema or "patternProperties" in schema or "$ref" in schema:
        return True

    for key in _SCHEMA_COMPOSITION_KEYS:
        branches = schema.get(key)
        if isinstance(branches, list) and any(isinstance(branch, dict) and _schema_looks_object_like(branch) for branch in branches):
            return True

    return False


def _schema_uses_composed_top_level_rules(schema: dict[str, Any]) -> bool:
    """Return whether a schema relies on top-level composition or refs."""
    if "$ref" in schema or "patternProperties" in schema:
        return True
    return any(isinstance(schema.get(key), list) and schema[key] for key in _SCHEMA_COMPOSITION_KEYS)


def _collect_top_level_property_names(schema: dict[str, Any] | None) -> set[str]:
    """Collect top-level property names across composed object schemas."""
    if not isinstance(schema, dict):
        return set()

    names: set[str] = set()
    properties = schema.get("properties")
    if isinstance(properties, dict):
        names.update(key for key in properties if isinstance(key, str))

    for key in _SCHEMA_COMPOSITION_KEYS:
        branches = schema.get(key)
        if isinstance(branches, list):
            for branch in branches:
                names.update(_collect_top_level_property_names(branch))

    return names


def _schema_allows_additional_top_level_keys(schema: dict[str, Any] | None) -> bool:
    """Return whether a schema may accept top-level keys beyond known properties."""
    if not isinstance(schema, dict):
        return False
    if "$ref" in schema:
        return True
    if _schema_keyword_allows_values(schema.get("additionalProperties")):
        return True

    pattern_properties = schema.get("patternProperties")
    if isinstance(pattern_properties, dict) and pattern_properties:
        return True

    for key in _SCHEMA_COMPOSITION_KEYS:
        branches = schema.get(key)
        if isinstance(branches, list) and any(_schema_allows_additional_top_level_keys(branch) for branch in branches):
            return True

    return False


def _schema_keyword_allows_values(value: Any) -> bool:
    """Return whether a schema keyword encodes an open-ended allowance."""
    return value is not None and value is not False


def _is_null_schema(schema: Any) -> bool:
    """Return whether a schema branch represents only ``null``.

    Args:
        schema: Candidate schema branch.

    Returns:
        ``True`` when the branch encodes a null-only schema.
    """
    if not isinstance(schema, dict):
        return False
    branch_type = schema.get("type")
    return branch_type == "null" or branch_type == ["null"]


def _normalize_call_tool_result(result: CallToolResult) -> dict[str, Any]:
    """Convert a FastMCP call result into the local JSON payload shape.

    Args:
        result: Parsed FastMCP tool result.

    Returns:
        Normalized payload with ``status`` plus structured/text content.
    """
    if result.is_error:
        return {
            "status": "error",
            "error": _extract_result_error(result),
        }

    payload: dict[str, Any] = {"status": "ok"}
    if result.structured_content is not None:
        # ``structured_content`` is the canonical JSON value received over
        # MCP. FastMCP's ``data`` is a convenience view hydrated from that
        # value into dataclasses, datetime objects, UUIDs, and other Python
        # types. Prefer the wire value whenever hydration made ``data`` cease
        # to be natively JSON-serializable; serializing the hydrated copy is
        # both redundant and the source of #922's false circular-reference
        # failure.
        structured = result.structured_content
        payload["data"] = _select_result_data(result, structured)
        payload["structured_content"] = structured
    elif result.data is not None:
        # Compatibility fallback for injected/legacy clients that provide a
        # parsed value without standard MCP structured content.
        payload["data"] = _make_jsonable(result.data)
    if result.content:
        payload["content"] = [_make_jsonable(block) for block in result.content]
        text = _extract_text_content(result.content)
        if text:
            payload["text"] = text
    return payload


def _select_result_data(result: CallToolResult, structured: dict[str, Any]) -> Any:
    """Choose a JSON-safe local ``data`` view for a structured MCP result.

    FastMCP unwraps primitive return values from ``{"result": value}`` and
    exposes the unwrapped value through ``CallToolResult.data``. Mirror only
    that wire-format convention; otherwise use the canonical structured JSON
    instead of re-serializing FastMCP's hydrated Python copy.

    Args:
        result: Parsed FastMCP result.
        structured: Canonical structured JSON received over MCP.

    Returns:
        JSON-compatible value for the local ``data`` field.
    """
    if _is_wrapped_fastmcp_result(result, structured):
        return structured["result"]

    return structured


def _is_wrapped_fastmcp_result(
    result: CallToolResult,
    structured: dict[str, Any],
) -> bool:
    """Detect FastMCP's wrapper for non-object tool return values.

    Modern FastMCP marks the wrapper in result metadata. FastMCP 2.14, the
    project's minimum supported version, only exposed the marker through the
    output schema. The narrow fallback below handles its hydrated non-object
    values without mistaking an ordinary object-schema dataclass for a wrapper.
    """
    if set(structured) != {"result"}:
        return False

    fastmcp_meta = (result.meta or {}).get("fastmcp")
    if isinstance(fastmcp_meta, dict) and fastmcp_meta.get("wrap_result") is True:
        return True

    data = result.data
    return (
        data is not None
        and not isinstance(data, Mapping)
        and not (is_dataclass(data) and not isinstance(data, type))
        and not callable(getattr(data, "model_dump", None))
    )


def compact_result_for_agent(payload: dict[str, Any]) -> dict[str, Any]:
    """Drop redundant copies of one MCP result before it reaches the agent.

    ``_normalize_call_tool_result`` keeps every surface programmatic callers of
    ``MCPServerAdapter.call_tool`` may read, so a structured result is carried
    up to four times: ``data``, ``structured_content``, a text block mirroring
    it in ``content`` and the joined ``text``. Serialized into the agent
    context that multiplies one payload several times over.

    Only exact mirrors of ``data`` are removed, and only when ``data`` exists:
    a ``structured_content`` equal to it, bare text blocks whose JSON equals
    it, and the ``text`` join once a mirror block it embeds is gone. Text-only
    results, distinct or metadata-bearing blocks, unrelated ``structured_content``
    and error payloads are returned unchanged. ``payload`` is never mutated.

    Args:
        payload: Normalized result from ``MCPServerAdapter.call_tool``.

    Returns:
        Payload without the redundant copies.
    """
    if payload.get("status") != "ok" or "data" not in payload:
        return payload

    compact = dict(payload)
    data = compact["data"]
    structured = compact.get("structured_content")
    if structured is not None and (
        _same_json(structured, data) or _same_json(structured, {"result": data})
    ):
        del compact["structured_content"]

    blocks = compact.get("content")
    if isinstance(blocks, list):
        kept = [block for block in blocks if not _is_mirror_text_block(block, data)]
        if len(kept) != len(blocks):
            if kept:
                compact["content"] = kept
            else:
                del compact["content"]
            # ``text`` is the join of the original text blocks, so it embeds the
            # removed mirror; drop it only when it is exactly that derived join.
            if compact.get("text") == _extract_text_content(blocks):
                del compact["text"]
    return compact


def _same_json(left: Any, right: Any) -> bool:
    """Compare JSON values strictly (``1`` is not ``True``, key order ignored)."""
    try:
        return json.dumps(left, sort_keys=True) == json.dumps(right, sort_keys=True)
    except (TypeError, ValueError):
        return False


def _is_mirror_text_block(block: Any, data: Any) -> bool:
    """Return whether ``block`` is a bare text block that only restates ``data``."""
    if not isinstance(block, dict) or block.get("type") != "text":
        return False
    text = block.get("text")
    if not isinstance(text, str):
        return False
    if any(value is not None for key, value in block.items() if key not in ("type", "text")):
        return False
    if isinstance(data, str) and text == data:
        return True
    try:
        parsed = json.loads(text)
    except ValueError:
        return False
    return _same_json(parsed, data) or _same_json(parsed, {"result": data})


def _extract_result_error(result: CallToolResult) -> str:
    """Extract a readable error message from a failed MCP result.

    Args:
        result: Failed FastMCP result.

    Returns:
        Human-readable error text.
    """
    text = _extract_text_content(result.content)
    if text:
        return text
    if result.structured_content is not None:
        return _to_display_text(result.structured_content)
    if result.data is not None:
        return _to_display_text(result.data)
    return "Remote MCP tool returned an error"


def _extract_text_content(content: list[Any]) -> str:
    """Join text content blocks from a FastMCP response.

    Args:
        content: Content block list.

    Returns:
        Joined text block content.
    """
    texts: list[str] = []
    for block in content:
        raw = _make_jsonable(block)
        if isinstance(raw, dict) and raw.get("type") == "text" and isinstance(raw.get("text"), str):
            texts.append(raw["text"])
    return "\n".join(texts).strip()


def _is_retryable_error(exc: Exception) -> bool:
    """Determine whether a failure should receive a single retry.

    Args:
        exc: Exception raised by an MCP operation.

    Returns:
        ``True`` for transient timeout/connection failures.
    """
    if isinstance(exc, (asyncio.TimeoutError, TimeoutError, BrokenPipeError, ConnectionError, EOFError, OSError)):
        return True

    if isinstance(exc, McpError) and getattr(exc, "error", None) is not None:
        error_code = getattr(exc.error, "code", None)
        if error_code == mcp_types.CONNECTION_CLOSED:
            return True
        message = getattr(exc.error, "message", "")
        return _message_looks_transient(message)

    # ToolError signals a remote business / validation error, not a
    # connection-level transient failure.  Do not retry these.
    if isinstance(exc, ToolError):
        return False

    return _message_looks_transient(str(exc))


def _message_looks_transient(message: str) -> bool:
    """Check whether an exception message looks transient.

    Args:
        message: Exception message.

    Returns:
        ``True`` when the message matches common transient failure markers.
    """
    lowered = message.lower()
    return any(token in lowered for token in _TRANSIENT_ERROR_TOKENS)


#: Cap on the remote error body echoed back to the user. Enough for a JSON
#: error envelope, short enough that a stray HTML page does not fill the log.
_HTTP_ERROR_BODY_LIMIT = 300


def _http_error_body(exc: BaseException) -> str:
    """Return the response body of an HTTP status error, if there is one.

    ``httpx.HTTPStatusError`` stringifies to the status and URL only, so the
    server's own explanation is dropped — which turns an auth rejection into an
    unreadable "Client error 400". IBKR, for one, answers a token it will not
    accept with ``{"error":"Status failed 500","statusCode":400}`` and a 400,
    while an unauthenticated request gets a 401 (issue #1126); without the body
    those two are indistinguishable to the user.

    Args:
        exc: Exception that may carry an HTTP response.

    Returns:
        The trimmed body, or ``""`` when there is none to report.
    """
    response = getattr(exc, "response", None)
    if response is None:
        return ""
    try:
        body = (response.text or "").strip()
    except Exception:  # noqa: BLE001 - a body we cannot read is not reportable
        return ""
    if not body:
        return ""
    if len(body) > _HTTP_ERROR_BODY_LIMIT:
        body = body[:_HTTP_ERROR_BODY_LIMIT] + "..."
    return " ".join(body.split())


def _format_exception_message(exc: Exception) -> str:
    """Render an exception into a user-facing error string.

    Args:
        exc: Exception to format.

    Returns:
        Human-readable error message.
    """
    if isinstance(exc, McpError) and getattr(exc, "error", None) is not None:
        return getattr(exc.error, "message", str(exc))
    message = str(exc) or type(exc).__name__
    if isinstance(exc, httpx.HTTPStatusError) and (body := _http_error_body(exc)):
        return f"{message} - server said: {body}"
    return message


def _make_jsonable(value: Any) -> Any:
    """Convert a fallback MCP value with Pydantic's JSON serializer.

    FastMCP uses the same public ``pydantic_core`` primitive when producing
    structured tool results. Normal structured responses bypass this helper;
    it exists for content blocks and legacy/data-only client results.

    Args:
        value: Arbitrary response value.

    Returns:
        JSON-serializable equivalent.

    Raises:
        TypeError: If the value is cyclic or unsupported. The error reports
            only type names, never the value or the underlying exception text.
    """
    try:
        return to_jsonable_python(value, by_alias=True, exclude_none=True)
    except (PydanticSerializationError, TypeError, ValueError, UnicodeDecodeError) as exc:
        raise TypeError(
            f"Unable to serialize MCP result type {_qualified_type_name(value)}: "
            f"{type(exc).__name__}"
        ) from None


def _qualified_type_name(value: Any) -> str:
    """Return a stable type name without calling the value's representation."""
    value_type = type(value)
    return f"{value_type.__module__}.{value_type.__qualname__}"


def _json_default(value: Any) -> Any:
    """Fallback serializer used by ``json.dumps``.

    Args:
        value: Value rejected by the standard encoder.

    Returns:
        JSON-serializable representation.

    Raises:
        TypeError: If the value has no safe serialization contract.
    """
    return _make_jsonable(value)


def _to_display_text(value: Any) -> str:
    """Render structured values into compact human-readable text.

    Args:
        value: Structured response value.

    Returns:
        Human-readable string.
    """
    jsonable = _make_jsonable(value)
    if isinstance(jsonable, str):
        return jsonable
    return json.dumps(jsonable, ensure_ascii=False, sort_keys=True)


__all__ = [
    "MCPRemoteTool",
    "MCPRemoteToolSpec",
    "MCPServerAdapter",
    "build_mcp_tool_wrappers",
    "format_mcp_server_name_collision_warning",
    "invalidate_mcp_specs_cache",
    "make_mcp_tool_name",
    "normalize_mcp_tool_schema",
    "resolve_mcp_server_tool_name_segments",
]