"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""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",
]