fastmcp 2.3.4__py3-none-any.whl → 2.4.0__py3-none-any.whl

fastmcp/client/client.py

@@ -1,14 +1,21 @@
 import datetime
-from contextlib import AsyncExitStack
+from contextlib import AsyncExitStack, asynccontextmanager
 from pathlib import Path
 from typing import Any, cast
 
+import anyio
 import mcp.types
 from exceptiongroup import catch
 from mcp import ClientSession
 from pydantic import AnyUrl
 
-from fastmcp.client.logging import LogHandler, MessageHandler
+from fastmcp.client.logging import (
+    LogHandler,
+    MessageHandler,
+    create_log_callback,
+    default_log_handler,
+)
+from fastmcp.client.progress import ProgressHandler, default_progress_handler
 from fastmcp.client.roots import (
     RootsHandler,
     RootsList,
@@ -18,6 +25,7 @@ from fastmcp.client.sampling import SamplingHandler, create_sampling_callback
 from fastmcp.exceptions import ToolError
 from fastmcp.server import FastMCP
 from fastmcp.utilities.exceptions import get_catch_handlers
+from fastmcp.utilities.mcp_config import MCPConfig
 
 from .transports import ClientTransport, SessionKwargs, infer_transport
 
@@ -28,6 +36,7 @@ __all__ = [
     "LogHandler",
     "MessageHandler",
     "SamplingHandler",
+    "ProgressHandler",
 ]
 
 
@@ -45,11 +54,13 @@ class Client:
             - FastMCP: In-process FastMCP server
             - AnyUrl | str: URL to connect to
             - Path: File path for local socket
+            - MCPConfig: MCP server configuration
             - dict: Transport configuration
         roots: Optional RootsList or RootsHandler for filesystem access
         sampling_handler: Optional handler for sampling requests
         log_handler: Optional handler for log messages
         message_handler: Optional handler for protocol messages
+        progress_handler: Optional handler for progress notifications
         timeout: Optional timeout for requests (seconds or timedelta)
 
     Examples:
@@ -68,18 +79,34 @@ class Client:
 
     def __init__(
         self,
-        transport: ClientTransport | FastMCP | AnyUrl | Path | dict[str, Any] | str,
+        transport: ClientTransport
+        | FastMCP
+        | AnyUrl
+        | Path
+        | MCPConfig
+        | dict[str, Any]
+        | str,
         # Common args
         roots: RootsList | RootsHandler | None = None,
         sampling_handler: SamplingHandler | None = None,
         log_handler: LogHandler | None = None,
         message_handler: MessageHandler | None = None,
+        progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
     ):
         self.transport = infer_transport(transport)
         self._session: ClientSession | None = None
         self._exit_stack: AsyncExitStack | None = None
         self._nesting_counter: int = 0
+        self._initialize_result: mcp.types.InitializeResult | None = None
+
+        if log_handler is None:
+            log_handler = default_log_handler
+
+        if progress_handler is None:
+            progress_handler = default_progress_handler
+
+        self._progress_handler = progress_handler
 
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=timeout)
@@ -87,7 +114,7 @@ class Client:
         self._session_kwargs: SessionKwargs = {
             "sampling_callback": None,
             "list_roots_callback": None,
-            "logging_callback": log_handler,
+            "logging_callback": create_log_callback(log_handler),
             "message_handler": message_handler,
             "read_timeout_seconds": timeout,
         }
@@ -96,17 +123,28 @@ class Client:
             self.set_roots(roots)
 
         if sampling_handler is not None:
-            self.set_sampling_callback(sampling_handler)
+            self._session_kwargs["sampling_callback"] = create_sampling_callback(
+                sampling_handler
+            )
 
     @property
     def session(self) -> ClientSession:
         """Get the current active session. Raises RuntimeError if not connected."""
         if self._session is None:
             raise RuntimeError(
-                "Client is not connected. Use 'async with client:' context manager first."
+                "Client is not connected. Use the 'async with client:' context manager first."
             )
         return self._session
 
+    @property
+    def initialize_result(self) -> mcp.types.InitializeResult:
+        """Get the result of the initialization request."""
+        if self._initialize_result is None:
+            raise RuntimeError(
+                "Client is not connected. Use the 'async with client:' context manager first."
+            )
+        return self._initialize_result
+
     def set_roots(self, roots: RootsList | RootsHandler) -> None:
         """Set the roots for the client. This does not automatically call `send_roots_list_changed`."""
         self._session_kwargs["list_roots_callback"] = create_roots_callback(roots)
@@ -121,27 +159,37 @@ class Client:
         """Check if the client is currently connected."""
         return self._session is not None
 
+    @asynccontextmanager
+    async def _context_manager(self):
+        with catch(get_catch_handlers()):
+            async with self.transport.connect_session(
+                **self._session_kwargs
+            ) as session:
+                self._session = session
+                # Initialize the session
+                try:
+                    with anyio.fail_after(1):
+                        self._initialize_result = await self._session.initialize()
+                    yield
+                except TimeoutError:
+                    raise RuntimeError("Failed to initialize server session")
+                finally:
+                    self._exit_stack = None
+                    self._session = None
+                    self._initialize_result = None
+
     async def __aenter__(self):
         if self._nesting_counter == 0:
             # Create exit stack to manage both context managers
             stack = AsyncExitStack()
             await stack.__aenter__()
 
-            # Add the exception handling context
-            stack.enter_context(catch(get_catch_handlers()))
+            await stack.enter_async_context(self._context_manager())
 
-            # the above catch will only apply once this __aenter__ finishes so
-            # we need to wrap the session creation in a new context in case it
-            # raises errors itself
-            with catch(get_catch_handlers()):
-                # Create and enter the transport session using the exit stack
-                session_cm = self.transport.connect_session(**self._session_kwargs)
-                self._session = await stack.enter_async_context(session_cm)
-
-            # Store the stack for cleanup in __aexit__
             self._exit_stack = stack
 
         self._nesting_counter += 1
+
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
@@ -154,7 +202,6 @@ class Client:
                     await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
                 finally:
                     self._exit_stack = None
-                    self._session = None
 
     # --- MCP Client Methods ---
 
@@ -168,9 +215,12 @@ class Client:
         progress_token: str | int,
         progress: float,
         total: float | None = None,
+        message: str | None = None,
     ) -> None:
         """Send a progress notification."""
-        await self.session.send_progress_notification(progress_token, progress, total)
+        await self.session.send_progress_notification(
+            progress_token, progress, total, message
+        )
 
     async def set_logging_level(self, level: mcp.types.LoggingLevel) -> None:
         """Send a logging/setLevel request."""
@@ -430,6 +480,7 @@ class Client:
         self,
         name: str,
         arguments: dict[str, Any],
+        progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
     ) -> mcp.types.CallToolResult:
         """Send a tools/call request and return the complete MCP protocol result.
@@ -441,6 +492,8 @@ class Client:
             name (str): The name of the tool to call.
             arguments (dict[str, Any]): Arguments to pass to the tool.
             timeout (datetime.timedelta | float | int | None, optional): The timeout for the tool call. Defaults to None.
+            progress_handler (ProgressHandler | None, optional): The progress handler to use for the tool call. Defaults to None.
+
         Returns:
             mcp.types.CallToolResult: The complete response object from the protocol,
                 containing the tool result and any additional metadata.
@@ -452,7 +505,10 @@ class Client:
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=timeout)
         result = await self.session.call_tool(
-            name=name, arguments=arguments, read_timeout_seconds=timeout
+            name=name,
+            arguments=arguments,
+            read_timeout_seconds=timeout,
+            progress_callback=progress_handler or self._progress_handler,
         )
         return result
 
@@ -461,6 +517,7 @@ class Client:
         name: str,
         arguments: dict[str, Any] | None = None,
         timeout: datetime.timedelta | float | int | None = None,
+        progress_handler: ProgressHandler | None = None,
     ) -> list[
         mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource
     ]:
@@ -471,6 +528,8 @@ class Client:
         Args:
             name (str): The name of the tool to call.
             arguments (dict[str, Any] | None, optional): Arguments to pass to the tool. Defaults to None.
+            timeout (datetime.timedelta | float | int | None, optional): The timeout for the tool call. Defaults to None.
+            progress_handler (ProgressHandler | None, optional): The progress handler to use for the tool call. Defaults to None.
 
         Returns:
             list[mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource]:
@@ -484,6 +543,7 @@ class Client:
             name=name,
             arguments=arguments or {},
             timeout=timeout,
+            progress_handler=progress_handler,
         )
         if result.isError:
             msg = cast(mcp.types.TextContent, result.content[0]).text

fastmcp/client/logging.py

@@ -1,13 +1,27 @@
+from collections.abc import Awaitable, Callable
 from typing import TypeAlias
 
-from mcp.client.session import (
-    LoggingFnT,
-    MessageHandlerFnT,
-)
+from mcp.client.session import LoggingFnT, MessageHandlerFnT
 from mcp.types import LoggingMessageNotificationParams
 
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
 LogMessage: TypeAlias = LoggingMessageNotificationParams
-LogHandler: TypeAlias = LoggingFnT
+LogHandler: TypeAlias = Callable[[LogMessage], Awaitable[None]]
 MessageHandler: TypeAlias = MessageHandlerFnT
 
-__all__ = ["LogMessage", "LogHandler", "MessageHandler"]
+
+async def default_log_handler(message: LogMessage) -> None:
+    logger.debug(f"Log received: {message}")
+
+
+def create_log_callback(handler: LogHandler | None = None) -> LoggingFnT:
+    if handler is None:
+        handler = default_log_handler
+
+    async def log_callback(params: LoggingMessageNotificationParams) -> None:
+        await handler(params)
+
+    return log_callback

fastmcp/client/progress.py

@@ -0,0 +1,38 @@
+from typing import TypeAlias
+
+from mcp.shared.session import ProgressFnT
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+ProgressHandler: TypeAlias = ProgressFnT
+
+
+async def default_progress_handler(
+    progress: float, total: float | None, message: str | None
+) -> None:
+    """Default handler for progress notifications.
+
+    Logs progress updates at debug level, properly handling missing total or message values.
+
+    Args:
+        progress: Current progress value
+        total: Optional total expected value
+        message: Optional status message
+    """
+    if total is not None:
+        # We have both progress and total
+        percent = (progress / total) * 100
+        progress_str = f"{progress}/{total} ({percent:.1f}%)"
+    else:
+        # We only have progress
+        progress_str = f"{progress}"
+
+    # Include message if available
+    if message:
+        log_msg = f"Progress: {progress_str} - {message}"
+    else:
+        log_msg = f"Progress: {progress_str}"
+
+    logger.debug(log_msg)

fastmcp/client/transports.py

@@ -1,14 +1,12 @@
 import abc
 import contextlib
 import datetime
-import inspect
 import os
 import shutil
 import sys
-import warnings
 from collections.abc import AsyncIterator
 from pathlib import Path
-from typing import Any, TypedDict, cast
+from typing import TYPE_CHECKING, Any, TypedDict, cast
 
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.session import (
@@ -26,6 +24,14 @@ from pydantic import AnyUrl
 from typing_extensions import Unpack
 
 from fastmcp.server import FastMCP as FastMCPServer
+from fastmcp.server.server import FastMCP
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_config import MCPConfig, infer_transport_type_from_url
+
+if TYPE_CHECKING:
+    from fastmcp.utilities.mcp_config import MCPConfig
+
+logger = get_logger(__name__)
 
 
 class SessionKwargs(TypedDict, total=False):
@@ -44,6 +50,7 @@ class ClientTransport(abc.ABC):
 
     A Transport is responsible for establishing and managing connections
     to an MCP server, and providing a ClientSession within an async context.
+
     """
 
     @abc.abstractmethod
@@ -52,7 +59,9 @@ class ClientTransport(abc.ABC):
         self, **session_kwargs: Unpack[SessionKwargs]
     ) -> AsyncIterator[ClientSession]:
         """
-        Establishes a connection and yields an active, initialized 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
@@ -63,10 +72,10 @@ class ClientTransport(abc.ABC):
                               constructor (e.g., callbacks, timeouts).
 
         Yields:
-            An initialized mcp.ClientSession instance.
+            A mcp.ClientSession instance.
         """
         raise NotImplementedError
-        yield None  # type: ignore
+        yield  # type: ignore
 
     def __repr__(self) -> str:
         # Basic representation for subclasses
@@ -92,7 +101,6 @@ class WSTransport(ClientTransport):
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
             ) as session:
-                await session.initialize()  # Initialize after session creation
                 yield session
 
     def __repr__(self) -> str:
@@ -141,7 +149,6 @@ class SSETransport(ClientTransport):
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
             ) as session:
-                await session.initialize()
                 yield session
 
     def __repr__(self) -> str:
@@ -187,7 +194,6 @@ class StreamableHttpTransport(ClientTransport):
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
             ) as session:
-                await session.initialize()
                 yield session
 
     def __repr__(self) -> str:
@@ -235,7 +241,6 @@ class StdioTransport(ClientTransport):
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
             ) as session:
-                await session.initialize()
                 yield session
 
     def __repr__(self) -> str:
@@ -451,7 +456,7 @@ class FastMCPTransport(ClientTransport):
     """
 
     def __init__(self, mcp: FastMCPServer):
-        self._fastmcp = mcp  # Can be FastMCP or MCPServer
+        self.server = mcp  # Can be FastMCP or MCPServer
 
     @contextlib.asynccontextmanager
     async def connect_session(
@@ -459,17 +464,105 @@ class FastMCPTransport(ClientTransport):
     ) -> AsyncIterator[ClientSession]:
         # create_connected_server_and_client_session manages the session lifecycle itself
         async with create_connected_server_and_client_session(
-            server=self._fastmcp._mcp_server,
+            server=self.server._mcp_server,
             **session_kwargs,
         ) as session:
             yield session
 
     def __repr__(self) -> str:
-        return f"<FastMCP(server='{self._fastmcp.name}')>"
+        return f"<FastMCP(server='{self.server.name}')>"
+
+
+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 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
+        from fastmcp.utilities.mcp_config import MCPConfig
+
+        # Create a config with multiple servers
+        config = {
+            "mcpServers": {
+                "weather": {
+                    "url": "https://weather-api.example.com/mcp",
+                    "transport": "streamable-http"
+                },
+                "calendar": {
+                    "url": "https://calendar-api.example.com/mcp",
+                    "transport": "streamable-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):
+        from fastmcp.client.client import Client
+
+        if isinstance(config, dict):
+            config = MCPConfig.from_dict(config)
+        self.config = config
+
+        # if there's exactly one server, create a client for that server
+        if len(self.config.mcpServers) == 1:
+            self.transport = list(self.config.mcpServers.values())[0].to_transport()
+
+        # otherwise create a composite client
+        else:
+            composite_server = FastMCP()
+
+            for name, server in self.config.mcpServers.items():
+                server_client = Client(transport=server.to_transport())
+                composite_server.mount(
+                    prefix=name, server=FastMCP.as_proxy(server_client)
+                )
+
+            self.transport = FastMCPTransport(mcp=composite_server)
+
+    @contextlib.asynccontextmanager
+    async def connect_session(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> AsyncIterator[ClientSession]:
+        async with self.transport.connect_session(**session_kwargs) as session:
+            yield session
+
+    def __repr__(self) -> str:
+        return f"<MCPConfig(config='{self.config}')>"
 
 
 def infer_transport(
-    transport: ClientTransport | FastMCPServer | AnyUrl | Path | dict[str, Any] | str,
+    transport: ClientTransport
+    | FastMCPServer
+    | AnyUrl
+    | Path
+    | MCPConfig
+    | dict[str, Any]
+    | str,
 ) -> ClientTransport:
     """
     Infer the appropriate transport type from the given transport argument.
@@ -478,80 +571,73 @@ def infer_transport(
     argument, handling various input types and converting them to the appropriate
     ClientTransport subclass.
 
+    The function supports these input types:
+    - ClientTransport: Used directly without modification
+    - FastMCPServer: 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)
+        ```
     """
+    from fastmcp.utilities.mcp_config import MCPConfig
+
     # the transport is already a ClientTransport
     if isinstance(transport, ClientTransport):
         return transport
 
     # the transport is a FastMCP server
     elif isinstance(transport, FastMCPServer):
-        return FastMCPTransport(mcp=transport)
+        inferred_transport = FastMCPTransport(mcp=transport)
 
     # the transport is a path to a script
     elif isinstance(transport, Path | str) and Path(transport).exists():
         if str(transport).endswith(".py"):
-            return PythonStdioTransport(script_path=transport)
+            inferred_transport = PythonStdioTransport(script_path=transport)
         elif str(transport).endswith(".js"):
-            return NodeStdioTransport(script_path=transport)
+            inferred_transport = NodeStdioTransport(script_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"):
-        if str(transport).rstrip("/").endswith("/sse"):
-            warnings.warn(
-                inspect.cleandoc(
-                    """
-                    As of FastMCP 2.3.0, HTTP URLs are inferred to use Streamable HTTP.
-                    The provided URL ends in `/sse`, so you may encounter unexpected behavior.
-                    If you intended to use SSE, please use the `SSETransport` class directly.
-                    """
-                ),
-                category=UserWarning,
-                stacklevel=2,
-            )
-        return StreamableHttpTransport(url=transport)
-
-    # the transport is a websocket URL
-    elif isinstance(transport, AnyUrl | str) and str(transport).startswith("ws"):
-        return WSTransport(url=transport)
-
-    ## if the transport is a config dict
-    elif isinstance(transport, dict):
-        if "mcpServers" not in transport:
-            raise ValueError("Invalid transport dictionary: missing 'mcpServers' key")
+        inferred_transport_type = infer_transport_type_from_url(transport)
+        if inferred_transport_type == "sse":
+            inferred_transport = SSETransport(url=transport)
         else:
-            server = transport["mcpServers"]
-            if len(list(server.keys())) > 1:
-                raise ValueError(
-                    "Invalid transport dictionary: multiple servers found - only one expected"
-                )
-            server_name = list(server.keys())[0]
-            # Stdio transport
-            if "command" in server[server_name] and "args" in server[server_name]:
-                return StdioTransport(
-                    command=server[server_name]["command"],
-                    args=server[server_name]["args"],
-                    env=server[server_name].get("env", None),
-                    cwd=server[server_name].get("cwd", None),
-                )
-
-            # HTTP transport
-            elif "url" in server:
-                return SSETransport(
-                    url=server["url"],
-                    headers=server.get("headers", None),
-                )
-
-            # WebSocket transport
-            elif "ws_url" in server:
-                return WSTransport(
-                    url=server["ws_url"],
-                )
+            inferred_transport = StreamableHttpTransport(url=transport)
 
-            raise ValueError("Cannot determine transport type from dictionary")
+    # if the transport is a config dict or MCPConfig
+    elif isinstance(transport, dict | MCPConfig):
+        inferred_transport = MCPConfigTransport(config=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/server/context.py

@@ -56,7 +56,7 @@ class Context:
         ctx.error("Error message")
 
         # Report progress
-        ctx.report_progress(50, 100)
+        ctx.report_progress(50, 100, "Processing")
 
         # Access resources
         data = ctx.read_resource("resource://data")
@@ -96,7 +96,7 @@ class Context:
         return self.fastmcp._mcp_server.request_context
 
     async def report_progress(
-        self, progress: float, total: float | None = None
+        self, progress: float, total: float | None = None, message: str | None = None
     ) -> None:
         """Report progress for the current operation.
 
@@ -115,7 +115,10 @@ class Context:
             return
 
         await self.request_context.session.send_progress_notification(
-            progress_token=progress_token, progress=progress, total=total
+            progress_token=progress_token,
+            progress=progress,
+            total=total,
+            message=message,
         )
 
     async def read_resource(self, uri: str | AnyUrl) -> list[ReadResourceContents]: