fastmcp 2.14.4__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

fastmcp/client/transports/base.py

@@ -0,0 +1,82 @@
+import abc
+import contextlib
+import datetime
+from collections.abc import AsyncIterator
+from typing import Literal, TypeVar
+
+import httpx
+import mcp.types
+from mcp import ClientSession
+from mcp.client.session import (
+    ElicitationFnT,
+    ListRootsFnT,
+    LoggingFnT,
+    MessageHandlerFnT,
+    SamplingFnT,
+)
+from typing_extensions import TypedDict, Unpack
+
+# TypeVar for preserving specific ClientTransport subclass types
+ClientTransportT = TypeVar("ClientTransportT", bound="ClientTransport")
+
+
+class SessionKwargs(TypedDict, total=False):
+    """Keyword arguments for the MCP ClientSession constructor."""
+
+    read_timeout_seconds: datetime.timedelta | None
+    sampling_callback: SamplingFnT | None
+    sampling_capabilities: mcp.types.SamplingCapability | None
+    list_roots_callback: ListRootsFnT | None
+    logging_callback: LoggingFnT | None
+    elicitation_callback: ElicitationFnT | None
+    message_handler: MessageHandlerFnT | None
+    client_info: mcp.types.Implementation | None
+
+
+class ClientTransport(abc.ABC):
+    """
+    Abstract base class for different MCP client transport mechanisms.
+
+    A Transport is responsible for establishing and managing connections
+    to an MCP server, and providing a ClientSession within an async context.
+
+    """
+
+    @abc.abstractmethod
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        """
+        Establishes a connection and yields an active ClientSession.
+
+        The ClientSession is *not* expected to be initialized in this context manager.
+
+        The session is guaranteed to be valid only within the scope of the
+        async context manager. Connection setup and teardown are handled
+        within this context.
+
+        Args:
+            **session_kwargs: Keyword arguments to pass to the ClientSession
+                              constructor (e.g., callbacks, timeouts).
+
+        Yields:
+            A mcp.ClientSession instance.
+        """
+        raise NotImplementedError
+        yield
+
+    def __repr__(self) -> str:
+        # Basic representation for subclasses
+        return f"<{self.__class__.__name__}>"
+
+    async def close(self):  # noqa: B027
+        """Close the transport."""
+
+    def get_session_id(self) -> str | None:
+        """Get the session ID for this transport, if available."""
+        return None
+
+    def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
+        if auth is not None:
+            raise ValueError("This transport does not support auth")

fastmcp/client/transports/config.py

@@ -0,0 +1,170 @@
+import contextlib
+import datetime
+from collections.abc import AsyncIterator
+from typing import Any
+
+from mcp import ClientSession
+from typing_extensions import Unpack
+
+from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+from fastmcp.client.transports.memory import FastMCPTransport
+from fastmcp.mcp_config import (
+    MCPConfig,
+    MCPServerTypes,
+    RemoteMCPServer,
+    StdioMCPServer,
+    TransformingRemoteMCPServer,
+    TransformingStdioMCPServer,
+)
+from fastmcp.server.server import FastMCP, create_proxy
+
+
+class MCPConfigTransport(ClientTransport):
+    """Transport for connecting to one or more MCP servers defined in an MCPConfig.
+
+    This transport provides a unified interface to multiple MCP servers defined in an MCPConfig
+    object or dictionary matching the MCPConfig schema. It supports two key scenarios:
+
+    1. If the MCPConfig contains exactly one server, it creates a direct transport to that server.
+    2. If the MCPConfig contains multiple servers, it creates a composite client by mounting
+       all servers on a single FastMCP instance, with each server's name, by default, used as its mounting prefix.
+
+    In the multi-server case, tools are accessible with the prefix pattern `{server_name}_{tool_name}`
+    and resources with the pattern `protocol://{server_name}/path/to/resource`.
+
+    This is particularly useful for creating clients that need to interact with multiple specialized
+    MCP servers through a single interface, simplifying client code.
+
+    Examples:
+        ```python
+        from fastmcp import Client
+
+        # Create a config with multiple servers
+        config = {
+            "mcpServers": {
+                "weather": {
+                    "url": "https://weather-api.example.com/mcp",
+                    "transport": "http"
+                },
+                "calendar": {
+                    "url": "https://calendar-api.example.com/mcp",
+                    "transport": "http"
+                }
+            }
+        }
+
+        # Create a client with the config
+        client = Client(config)
+
+        async with client:
+            # Access tools with prefixes
+            weather = await client.call_tool("weather_get_forecast", {"city": "London"})
+            events = await client.call_tool("calendar_list_events", {"date": "2023-06-01"})
+
+            # Access resources with prefixed URIs
+            icons = await client.read_resource("weather://weather/icons/sunny")
+        ```
+    """
+
+    def __init__(self, config: MCPConfig | dict, name_as_prefix: bool = True):
+        if isinstance(config, dict):
+            config = MCPConfig.from_dict(config)
+        self.config = config
+        self.name_as_prefix = name_as_prefix
+        self._transports: list[ClientTransport] = []
+
+        if not self.config.mcpServers:
+            raise ValueError("No MCP servers defined in the config")
+
+        # For single server, create transport eagerly so it can be inspected
+        if len(self.config.mcpServers) == 1:
+            self.transport = next(iter(self.config.mcpServers.values())).to_transport()
+            self._transports.append(self.transport)
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        # Single server - delegate directly to pre-created transport
+        if len(self.config.mcpServers) == 1:
+            async with self.transport.connect_session(**session_kwargs) as session:
+                yield session
+            return
+
+        # Multiple servers - create composite with mounted proxies
+        # Close any previous transports from prior connections to avoid leaking
+        for t in self._transports:
+            await t.close()
+        self._transports = []
+        timeout = session_kwargs.get("read_timeout_seconds")
+        composite = FastMCP[Any](name="MCPRouter")
+
+        try:
+            for name, server_config in self.config.mcpServers.items():
+                transport, proxy = self._create_proxy(name, server_config, timeout)
+                self._transports.append(transport)
+                composite.mount(proxy, namespace=name if self.name_as_prefix else None)
+        except Exception:
+            # Clean up any transports created before the failure
+            for t in self._transports:
+                await t.close()
+            self._transports = []
+            raise
+
+        async with FastMCPTransport(mcp=composite).connect_session(
+            **session_kwargs
+        ) as session:
+            yield session
+
+    def _create_proxy(
+        self,
+        name: str,
+        config: MCPServerTypes,
+        timeout: datetime.timedelta | None,
+    ) -> tuple[ClientTransport, FastMCP[Any]]:
+        """Create underlying transport and proxy server for a single backend."""
+        # Import here to avoid circular dependency
+        from fastmcp.server.providers.proxy import ProxyClient
+
+        tool_transforms = None
+        include_tags = None
+        exclude_tags = None
+
+        # Handle transforming servers - call base class to_transport() for underlying transport
+        if isinstance(config, TransformingStdioMCPServer):
+            transport = StdioMCPServer.to_transport(config)
+            tool_transforms = config.tools
+            include_tags = config.include_tags
+            exclude_tags = config.exclude_tags
+        elif isinstance(config, TransformingRemoteMCPServer):
+            transport = RemoteMCPServer.to_transport(config)
+            tool_transforms = config.tools
+            include_tags = config.include_tags
+            exclude_tags = config.exclude_tags
+        else:
+            transport = config.to_transport()
+
+        client = ProxyClient(transport=transport, timeout=timeout)
+        # Create proxy without include_tags/exclude_tags - we'll add them after tool transforms
+        proxy = create_proxy(
+            client,
+            name=f"Proxy-{name}",
+        )
+        # Add tool transforms FIRST - they may add/modify tags
+        if tool_transforms:
+            from fastmcp.server.transforms import ToolTransform
+
+            proxy.add_transform(ToolTransform(tool_transforms))
+        # Then add enabled filters - they filter based on tags
+        if include_tags:
+            proxy.enable(tags=set(include_tags), only=True)
+        if exclude_tags:
+            proxy.disable(tags=set(exclude_tags))
+        return transport, proxy
+
+    async def close(self):
+        for transport in self._transports:
+            await transport.close()
+
+    def __repr__(self) -> str:
+        return f"<MCPConfigTransport(config='{self.config}')>"

fastmcp/client/transports/http.py

@@ -0,0 +1,145 @@
+"""Streamable HTTP transport for FastMCP Client."""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+from collections.abc import AsyncIterator, Callable
+from typing import Literal, cast
+
+import httpx
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+from mcp.shared._httpx_utils import McpHttpClientFactory, create_mcp_http_client
+from pydantic import AnyUrl
+from typing_extensions import Unpack
+
+import fastmcp
+from fastmcp.client.auth.bearer import BearerAuth
+from fastmcp.client.auth.oauth import OAuth
+from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+from fastmcp.server.dependencies import get_http_headers
+from fastmcp.utilities.timeout import normalize_timeout_to_timedelta
+
+
+class StreamableHttpTransport(ClientTransport):
+    """Transport implementation that connects to an MCP server via Streamable HTTP Requests."""
+
+    def __init__(
+        self,
+        url: str | AnyUrl,
+        headers: dict[str, str] | None = None,
+        auth: httpx.Auth | Literal["oauth"] | str | None = None,
+        sse_read_timeout: datetime.timedelta | float | int | None = None,
+        httpx_client_factory: McpHttpClientFactory | None = None,
+    ):
+        """Initialize a Streamable HTTP transport.
+
+        Args:
+            url: The MCP server endpoint URL.
+            headers: Optional headers to include in requests.
+            auth: Authentication method - httpx.Auth, "oauth" for OAuth flow,
+                or a bearer token string.
+            sse_read_timeout: Deprecated. Use read_timeout_seconds in session_kwargs.
+            httpx_client_factory: Optional factory for creating httpx.AsyncClient.
+                If provided, must accept keyword arguments: headers, auth,
+                follow_redirects, and optionally timeout. Using **kwargs is
+                recommended to ensure forward compatibility.
+        """
+        if isinstance(url, AnyUrl):
+            url = str(url)
+        if not isinstance(url, str) or not url.startswith("http"):
+            raise ValueError("Invalid HTTP/S URL provided for Streamable HTTP.")
+
+        # Don't modify the URL path - respect the exact URL provided by the user
+        # Some servers are strict about trailing slashes (e.g., PayPal MCP)
+
+        self.url: str = url
+        self.headers = headers or {}
+        self.httpx_client_factory = httpx_client_factory
+        self._set_auth(auth)
+
+        if sse_read_timeout is not None:
+            if fastmcp.settings.deprecation_warnings:
+                import warnings
+
+                warnings.warn(
+                    "The `sse_read_timeout` parameter is deprecated and no longer used. "
+                    "The new streamable_http_client API does not support this parameter. "
+                    "Use `read_timeout_seconds` in session_kwargs or configure timeout on "
+                    "the httpx client via `httpx_client_factory` instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+        self.sse_read_timeout = normalize_timeout_to_timedelta(sse_read_timeout)
+
+        self._get_session_id_cb: Callable[[], str | None] | None = None
+
+    def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
+        if auth == "oauth":
+            auth = OAuth(self.url, httpx_client_factory=self.httpx_client_factory)
+        elif isinstance(auth, str):
+            auth = BearerAuth(auth)
+        self.auth = auth
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        # Load headers from an active HTTP request, if available. This will only be true
+        # if the client is used in a FastMCP Proxy, in which case the MCP client headers
+        # need to be forwarded to the remote server.
+        headers = get_http_headers() | self.headers
+
+        # Configure timeout if provided, preserving MCP's 30s connect default
+        timeout: httpx.Timeout | None = None
+        if session_kwargs.get("read_timeout_seconds") is not None:
+            read_timeout_seconds = cast(
+                datetime.timedelta, session_kwargs.get("read_timeout_seconds")
+            )
+            timeout = httpx.Timeout(30.0, read=read_timeout_seconds.total_seconds())
+
+        # Create httpx client from factory or use default with MCP-appropriate timeouts
+        # create_mcp_http_client uses 30s connect/5min read timeout by default,
+        # and always enables follow_redirects
+        if self.httpx_client_factory is not None:
+            # Factory clients get the full kwargs for backwards compatibility
+            http_client = self.httpx_client_factory(
+                headers=headers,
+                auth=self.auth,
+                follow_redirects=True,  # type: ignore[call-arg]
+                **({"timeout": timeout} if timeout else {}),
+            )
+        else:
+            http_client = create_mcp_http_client(
+                headers=headers,
+                timeout=timeout,
+                auth=self.auth,
+            )
+
+        # Ensure httpx client is closed after use
+        async with (
+            http_client,
+            streamable_http_client(self.url, http_client=http_client) as transport,
+        ):
+            read_stream, write_stream, get_session_id = transport
+            self._get_session_id_cb = get_session_id
+            async with ClientSession(
+                read_stream, write_stream, **session_kwargs
+            ) as session:
+                yield session
+
+    def get_session_id(self) -> str | None:
+        if self._get_session_id_cb:
+            try:
+                return self._get_session_id_cb()
+            except Exception:
+                return None
+        return None
+
+    async def close(self):
+        # Reset the session id callback
+        self._get_session_id_cb = None
+
+    def __repr__(self) -> str:
+        return f"<StreamableHttpTransport(url='{self.url}')>"

fastmcp/client/transports/inference.py

@@ -0,0 +1,154 @@
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast, overload
+
+from mcp.server.fastmcp import FastMCP as FastMCP1Server
+from pydantic import AnyUrl
+
+from fastmcp.client.transports.base import ClientTransport, ClientTransportT
+from fastmcp.client.transports.config import MCPConfigTransport
+from fastmcp.client.transports.http import StreamableHttpTransport
+from fastmcp.client.transports.memory import FastMCPTransport
+from fastmcp.client.transports.sse import SSETransport
+from fastmcp.client.transports.stdio import NodeStdioTransport, PythonStdioTransport
+from fastmcp.mcp_config import MCPConfig, infer_transport_type_from_url
+from fastmcp.server.server import FastMCP
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    pass
+
+logger = get_logger(__name__)
+
+
+@overload
+def infer_transport(transport: ClientTransportT) -> ClientTransportT: ...
+
+
+@overload
+def infer_transport(transport: FastMCP) -> FastMCPTransport: ...
+
+
+@overload
+def infer_transport(transport: FastMCP1Server) -> FastMCPTransport: ...
+
+
+@overload
+def infer_transport(transport: MCPConfig) -> MCPConfigTransport: ...
+
+
+@overload
+def infer_transport(transport: dict[str, Any]) -> MCPConfigTransport: ...
+
+
+@overload
+def infer_transport(
+    transport: AnyUrl,
+) -> SSETransport | StreamableHttpTransport: ...
+
+
+@overload
+def infer_transport(
+    transport: str,
+) -> (
+    PythonStdioTransport | NodeStdioTransport | SSETransport | StreamableHttpTransport
+): ...
+
+
+@overload
+def infer_transport(transport: Path) -> PythonStdioTransport | NodeStdioTransport: ...
+
+
+def infer_transport(
+    transport: ClientTransport
+    | FastMCP
+    | FastMCP1Server
+    | AnyUrl
+    | Path
+    | MCPConfig
+    | dict[str, Any]
+    | str,
+) -> ClientTransport:
+    """
+    Infer the appropriate transport type from the given transport argument.
+
+    This function attempts to infer the correct transport type from the provided
+    argument, handling various input types and converting them to the appropriate
+    ClientTransport subclass.
+
+    The function supports these input types:
+    - ClientTransport: Used directly without modification
+    - FastMCP or FastMCP1Server: Creates an in-memory FastMCPTransport
+    - Path or str (file path): Creates PythonStdioTransport (.py) or NodeStdioTransport (.js)
+    - AnyUrl or str (URL): Creates StreamableHttpTransport (default) or SSETransport (for /sse endpoints)
+    - MCPConfig or dict: Creates MCPConfigTransport, potentially connecting to multiple servers
+
+    For HTTP URLs, they are assumed to be Streamable HTTP URLs unless they end in `/sse`.
+
+    For MCPConfig with multiple servers, a composite client is created where each server
+    is mounted with its name as prefix. This allows accessing tools and resources from multiple
+    servers through a single unified client interface, using naming patterns like
+    `servername_toolname` for tools and `protocol://servername/path` for resources.
+    If the MCPConfig contains only one server, a direct connection is established without prefixing.
+
+    Examples:
+        ```python
+        # Connect to a local Python script
+        transport = infer_transport("my_script.py")
+
+        # Connect to a remote server via HTTP
+        transport = infer_transport("http://example.com/mcp")
+
+        # Connect to multiple servers using MCPConfig
+        config = {
+            "mcpServers": {
+                "weather": {"url": "http://weather.example.com/mcp"},
+                "calendar": {"url": "http://calendar.example.com/mcp"}
+            }
+        }
+        transport = infer_transport(config)
+        ```
+    """
+
+    # the transport is already a ClientTransport
+    if isinstance(transport, ClientTransport):
+        return transport
+
+    # the transport is a FastMCP server (2.x or 1.0)
+    elif isinstance(transport, FastMCP | FastMCP1Server):
+        inferred_transport = FastMCPTransport(
+            mcp=cast(FastMCP[Any] | FastMCP1Server, transport)
+        )
+
+    # the transport is a path to a script
+    elif isinstance(transport, Path | str) and Path(transport).exists():
+        if str(transport).endswith(".py"):
+            inferred_transport = PythonStdioTransport(script_path=cast(Path, transport))
+        elif str(transport).endswith(".js"):
+            inferred_transport = NodeStdioTransport(script_path=cast(Path, transport))
+        else:
+            raise ValueError(f"Unsupported script type: {transport}")
+
+    # the transport is an http(s) URL
+    elif isinstance(transport, AnyUrl | str) and str(transport).startswith("http"):
+        inferred_transport_type = infer_transport_type_from_url(
+            cast(AnyUrl | str, transport)
+        )
+        if inferred_transport_type == "sse":
+            inferred_transport = SSETransport(url=cast(AnyUrl | str, transport))
+        else:
+            inferred_transport = StreamableHttpTransport(
+                url=cast(AnyUrl | str, transport)
+            )
+
+    # if the transport is a config dict or MCPConfig
+    elif isinstance(transport, dict | MCPConfig):
+        inferred_transport = MCPConfigTransport(
+            config=cast(dict | MCPConfig, transport)
+        )
+
+    # the transport is an unknown type
+    else:
+        raise ValueError(f"Could not infer a valid transport from: {transport}")
+
+    logger.debug(f"Inferred transport: {inferred_transport}")
+    return inferred_transport

fastmcp/client/transports/memory.py

@@ -0,0 +1,90 @@
+import contextlib
+from collections.abc import AsyncIterator
+
+import anyio
+from mcp import ClientSession
+from mcp.server.fastmcp import FastMCP as FastMCP1Server
+from mcp.shared.memory import create_client_server_memory_streams
+from typing_extensions import Unpack
+
+from fastmcp.client.transports.base import ClientTransport, SessionKwargs
+from fastmcp.server.server import FastMCP
+
+
+class FastMCPTransport(ClientTransport):
+    """In-memory transport for FastMCP servers.
+
+    This transport connects directly to a FastMCP server instance in the same
+    Python process. It works with both FastMCP 2.x servers and FastMCP 1.0
+    servers from the low-level MCP SDK. This is particularly useful for unit
+    tests or scenarios where client and server run in the same runtime.
+    """
+
+    def __init__(self, mcp: FastMCP | FastMCP1Server, raise_exceptions: bool = False):
+        """Initialize a FastMCPTransport from a FastMCP server instance."""
+
+        # Accept both FastMCP 2.x and FastMCP 1.0 servers. Both expose a
+        # ``_mcp_server`` attribute pointing to the underlying MCP server
+        # implementation, so we can treat them identically.
+        self.server = mcp
+        self.raise_exceptions = raise_exceptions
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        async with create_client_server_memory_streams() as (
+            client_streams,
+            server_streams,
+        ):
+            client_read, client_write = client_streams
+            server_read, server_write = server_streams
+
+            # Capture exceptions to re-raise after task group cleanup.
+            # anyio task groups can suppress exceptions when cancel_scope.cancel()
+            # is called during cleanup, so we capture and re-raise manually.
+            exception_to_raise: BaseException | None = None
+
+            async with (
+                anyio.create_task_group() as tg,
+                _enter_server_lifespan(server=self.server),
+            ):
+                tg.start_soon(
+                    lambda: self.server._mcp_server.run(
+                        server_read,
+                        server_write,
+                        self.server._mcp_server.create_initialization_options(),
+                        raise_exceptions=self.raise_exceptions,
+                    )
+                )
+
+                try:
+                    async with ClientSession(
+                        read_stream=client_read,
+                        write_stream=client_write,
+                        **session_kwargs,
+                    ) as client_session:
+                        yield client_session
+                except BaseException as e:
+                    exception_to_raise = e
+                finally:
+                    tg.cancel_scope.cancel()
+
+            # Re-raise after task group has exited cleanly
+            if exception_to_raise is not None:
+                raise exception_to_raise
+
+    def __repr__(self) -> str:
+        return f"<FastMCPTransport(server='{self.server.name}')>"
+
+
+@contextlib.asynccontextmanager
+async def _enter_server_lifespan(
+    server: FastMCP | FastMCP1Server,
+) -> AsyncIterator[None]:
+    """Enters the server's lifespan context for FastMCP servers and does nothing for FastMCP 1 servers."""
+    if isinstance(server, FastMCP):
+        async with server._lifespan_manager():
+            yield
+    else:
+        yield