fastmcp 2.3.3__py3-none-any.whl → 2.3.5__py3-none-any.whl

fastmcp/client/client.py

@@ -1,21 +1,24 @@
 import datetime
-from contextlib import AbstractAsyncContextManager
+from contextlib import AsyncExitStack, asynccontextmanager
 from pathlib import Path
 from typing import Any, cast
 
 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, default_log_handler
+from fastmcp.client.progress import ProgressHandler, default_progress_handler
 from fastmcp.client.roots import (
     RootsHandler,
     RootsList,
     create_roots_callback,
 )
 from fastmcp.client.sampling import SamplingHandler, create_sampling_callback
-from fastmcp.exceptions import ClientError
+from fastmcp.exceptions import ToolError
 from fastmcp.server import FastMCP
+from fastmcp.utilities.exceptions import get_catch_handlers
 
 from .transports import ClientTransport, SessionKwargs, infer_transport
 
@@ -26,6 +29,7 @@ __all__ = [
     "LogHandler",
     "MessageHandler",
     "SamplingHandler",
+    "ProgressHandler",
 ]
 
 
@@ -33,8 +37,36 @@ class Client:
     """
     MCP client that delegates connection management to a Transport instance.
 
-    The Client class is primarily concerned with MCP protocol logic,
-    while the Transport handles connection establishment and management.
+    The Client class is responsible for MCP protocol logic, while the Transport
+    handles connection establishment and management. Client provides methods
+    for working with resources, prompts, tools and other MCP capabilities.
+
+    Args:
+        transport: Connection source specification, which can be:
+            - ClientTransport: Direct transport instance
+            - FastMCP: In-process FastMCP server
+            - AnyUrl | str: URL to connect to
+            - Path: File path for local socket
+            - 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:
+        ```python
+        # Connect to FastMCP server
+        client = Client("http://localhost:8080")
+
+        async with client:
+            # List available resources
+            resources = await client.list_resources()
+
+            # Call a tool
+            result = await client.call_tool("my_tool", {"param": "value"})
+        ```
     """
 
     def __init__(
@@ -45,36 +77,60 @@ class Client:
         sampling_handler: SamplingHandler | None = None,
         log_handler: LogHandler | None = None,
         message_handler: MessageHandler | None = None,
-        read_timeout_seconds: datetime.timedelta | 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._session_cm: AbstractAsyncContextManager[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)
 
         self._session_kwargs: SessionKwargs = {
             "sampling_callback": None,
             "list_roots_callback": None,
             "logging_callback": log_handler,
             "message_handler": message_handler,
-            "read_timeout_seconds": read_timeout_seconds,
+            "read_timeout_seconds": timeout,
         }
 
         if roots is not None:
             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)
@@ -89,22 +145,47 @@ 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
+                self._initialize_result = await self._session.initialize()
+
+                try:
+                    yield
+                finally:
+                    self._exit_stack = None
+                    self._session = None
+                    self._initialize_result = None
+
     async def __aenter__(self):
         if self._nesting_counter == 0:
-            # create new session
-            self._session_cm = self.transport.connect_session(**self._session_kwargs)
-            self._session = await self._session_cm.__aenter__()
+            # Create exit stack to manage both context managers
+            stack = AsyncExitStack()
+            await stack.__aenter__()
+
+            await stack.enter_async_context(self._context_manager())
+
+            self._exit_stack = stack
 
         self._nesting_counter += 1
+
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
         self._nesting_counter -= 1
 
-        if self._nesting_counter == 0 and self._session_cm is not None:
-            await self._session_cm.__aexit__(exc_type, exc_val, exc_tb)
-            self._session_cm = None
-            self._session = None
+        if self._nesting_counter == 0:
+            # Exit the stack which will handle cleaning up the session
+            if self._exit_stack is not None:
+                try:
+                    await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
+                finally:
+                    self._exit_stack = None
 
     # --- MCP Client Methods ---
 
@@ -118,9 +199,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."""
@@ -377,7 +461,11 @@ class Client:
     # --- Call Tool ---
 
     async def call_tool_mcp(
-        self, name: str, arguments: dict[str, Any]
+        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.
 
@@ -387,6 +475,8 @@ class Client:
         Args:
             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,
@@ -395,34 +485,51 @@ class Client:
         Raises:
             RuntimeError: If called while the client is not connected.
         """
-        result = await self.session.call_tool(name=name, arguments=arguments)
+
+        if isinstance(timeout, int | float):
+            timeout = datetime.timedelta(seconds=timeout)
+        result = await self.session.call_tool(
+            name=name,
+            arguments=arguments,
+            read_timeout_seconds=timeout,
+            progress_callback=progress_handler or self._progress_handler,
+        )
         return result
 
     async def call_tool(
         self,
         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
     ]:
         """Call a tool on the server.
 
-        Unlike call_tool_mcp, this method raises a ClientError if the tool call results in an error.
+        Unlike call_tool_mcp, this method raises a ToolError if the tool call results in an error.
 
         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]:
                 The content returned by the tool.
 
         Raises:
-            ClientError: If the tool call results in an error.
+            ToolError: If the tool call results in an error.
             RuntimeError: If called while the client is not connected.
         """
-        result = await self.call_tool_mcp(name=name, arguments=arguments or {})
+        result = await self.call_tool_mcp(
+            name=name,
+            arguments=arguments or {},
+            timeout=timeout,
+            progress_handler=progress_handler,
+        )
         if result.isError:
             msg = cast(mcp.types.TextContent, result.content[0]).text
-            raise ClientError(msg)
+            raise ToolError(msg)
         return result.content

fastmcp/client/logging.py

@@ -6,8 +6,16 @@ from mcp.client.session import (
 )
 from mcp.types import LoggingMessageNotificationParams
 
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
 LogMessage: TypeAlias = LoggingMessageNotificationParams
 LogHandler: TypeAlias = LoggingFnT
 MessageHandler: TypeAlias = MessageHandlerFnT
 
 __all__ = ["LogMessage", "LogHandler", "MessageHandler"]
+
+
+async def default_log_handler(params: LogMessage) -> None:
+    logger.debug(f"Log received: {params}")

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,17 +1,15 @@
 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
+from typing import Any, TypedDict, cast
+from urllib.parse import urlparse
 
-from exceptiongroup import BaseExceptionGroup, catch
-from mcp import ClientSession, McpError, StdioServerParameters
+from mcp import ClientSession, StdioServerParameters
 from mcp.client.session import (
     ListRootsFnT,
     LoggingFnT,
@@ -26,8 +24,10 @@ from mcp.shared.memory import create_connected_server_and_client_session
 from pydantic import AnyUrl
 from typing_extensions import Unpack
 
-from fastmcp.exceptions import ClientError
 from fastmcp.server import FastMCP as FastMCPServer
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
 
 
 class SessionKwargs(TypedDict, total=False):
@@ -46,6 +46,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
@@ -54,7 +55,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
@@ -65,7 +68,7 @@ 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
@@ -94,7 +97,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:
@@ -104,7 +106,12 @@ class WSTransport(ClientTransport):
 class SSETransport(ClientTransport):
     """Transport implementation that connects to an MCP server via Server-Sent Events."""
 
-    def __init__(self, url: str | AnyUrl, headers: dict[str, str] | None = None):
+    def __init__(
+        self,
+        url: str | AnyUrl,
+        headers: dict[str, str] | None = None,
+        sse_read_timeout: datetime.timedelta | float | int | None = None,
+    ):
         if isinstance(url, AnyUrl):
             url = str(url)
         if not isinstance(url, str) or not url.startswith("http"):
@@ -112,16 +119,32 @@ class SSETransport(ClientTransport):
         self.url = url
         self.headers = headers or {}
 
+        if isinstance(sse_read_timeout, int | float):
+            sse_read_timeout = datetime.timedelta(seconds=sse_read_timeout)
+        self.sse_read_timeout = sse_read_timeout
+
     @contextlib.asynccontextmanager
     async def connect_session(
         self, **session_kwargs: Unpack[SessionKwargs]
     ) -> AsyncIterator[ClientSession]:
-        async with sse_client(self.url, headers=self.headers) as transport:
+        client_kwargs = {}
+        # sse_read_timeout has a default value set, so we can't pass None without overriding it
+        # instead we simply leave the kwarg out if it's not provided
+        if self.sse_read_timeout is not None:
+            client_kwargs["sse_read_timeout"] = self.sse_read_timeout.total_seconds()
+        if session_kwargs.get("read_timeout_seconds", None) is not None:
+            read_timeout_seconds = cast(
+                datetime.timedelta, session_kwargs.get("read_timeout_seconds")
+            )
+            client_kwargs["timeout"] = read_timeout_seconds.total_seconds()
+
+        async with sse_client(
+            self.url, headers=self.headers, **client_kwargs
+        ) as transport:
             read_stream, write_stream = transport
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
             ) as session:
-                await session.initialize()
                 yield session
 
     def __repr__(self) -> str:
@@ -131,7 +154,12 @@ class SSETransport(ClientTransport):
 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):
+    def __init__(
+        self,
+        url: str | AnyUrl,
+        headers: dict[str, str] | None = None,
+        sse_read_timeout: datetime.timedelta | float | int | None = None,
+    ):
         if isinstance(url, AnyUrl):
             url = str(url)
         if not isinstance(url, str) or not url.startswith("http"):
@@ -139,16 +167,29 @@ class StreamableHttpTransport(ClientTransport):
         self.url = url
         self.headers = headers or {}
 
+        if isinstance(sse_read_timeout, int | float):
+            sse_read_timeout = datetime.timedelta(seconds=sse_read_timeout)
+        self.sse_read_timeout = sse_read_timeout
+
     @contextlib.asynccontextmanager
     async def connect_session(
         self, **session_kwargs: Unpack[SessionKwargs]
     ) -> AsyncIterator[ClientSession]:
-        async with streamablehttp_client(self.url, headers=self.headers) as transport:
+        client_kwargs = {}
+        # sse_read_timeout has a default value set, so we can't pass None without overriding it
+        # instead we simply leave the kwarg out if it's not provided
+        if self.sse_read_timeout is not None:
+            client_kwargs["sse_read_timeout"] = self.sse_read_timeout
+        if session_kwargs.get("read_timeout_seconds", None) is not None:
+            client_kwargs["timeout"] = session_kwargs.get("read_timeout_seconds")
+
+        async with streamablehttp_client(
+            self.url, headers=self.headers, **client_kwargs
+        ) as transport:
             read_stream, write_stream, _ = transport
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
             ) as session:
-                await session.initialize()
                 yield session
 
     def __repr__(self) -> str:
@@ -196,7 +237,6 @@ class StdioTransport(ClientTransport):
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
             ) as session:
-                await session.initialize()
                 yield session
 
     def __repr__(self) -> str:
@@ -418,26 +458,12 @@ class FastMCPTransport(ClientTransport):
     async def connect_session(
         self, **session_kwargs: Unpack[SessionKwargs]
     ) -> AsyncIterator[ClientSession]:
-        def exception_handler(excgroup: BaseExceptionGroup):
-            for exc in excgroup.exceptions:
-                if isinstance(exc, BaseExceptionGroup):
-                    exception_handler(exc)
-                raise exc
-
-        def mcperror_handler(excgroup: BaseExceptionGroup):
-            for exc in excgroup.exceptions:
-                if isinstance(exc, BaseExceptionGroup):
-                    mcperror_handler(exc)
-                raise ClientError(exc)
-
-        # backport of 3.11's except* syntax
-        with catch({McpError: mcperror_handler, Exception: exception_handler}):
-            # create_connected_server_and_client_session manages the session lifecycle itself
-            async with create_connected_server_and_client_session(
-                server=self._fastmcp._mcp_server,
-                **session_kwargs,
-            ) as session:
-                yield session
+        # create_connected_server_and_client_session manages the session lifecycle itself
+        async with create_connected_server_and_client_session(
+            server=self._fastmcp._mcp_server,
+            **session_kwargs,
+        ) as session:
+            yield session
 
     def __repr__(self) -> str:
         return f"<FastMCP(server='{self._fastmcp.name}')>"
@@ -461,36 +487,29 @@ def infer_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)
+        transport_str = str(transport)
+        # Parse out just the path portion to check for /sse
+        parsed_url = urlparse(transport_str)
+        path = parsed_url.path
+
+        # Check if path contains /sse/ or ends with /sse
+        if "/sse/" in path or path.rstrip("/").endswith("/sse"):
+            inferred_transport = SSETransport(url=transport)
+        else:
+            inferred_transport = StreamableHttpTransport(url=transport)
 
     ## if the transport is a config dict
     elif isinstance(transport, dict):
@@ -505,7 +524,7 @@ def infer_transport(
             server_name = list(server.keys())[0]
             # Stdio transport
             if "command" in server[server_name] and "args" in server[server_name]:
-                return StdioTransport(
+                inferred_transport = StdioTransport(
                     command=server[server_name]["command"],
                     args=server[server_name]["args"],
                     env=server[server_name].get("env", None),
@@ -514,19 +533,16 @@ def infer_transport(
 
             # HTTP transport
             elif "url" in server:
-                return SSETransport(
+                inferred_transport = SSETransport(
                     url=server["url"],
                     headers=server.get("headers", None),
                 )
 
-            # WebSocket transport
-            elif "ws_url" in server:
-                return WSTransport(
-                    url=server["ws_url"],
-                )
-
             raise ValueError("Cannot determine transport type from dictionary")
 
     # 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/exceptions.py

@@ -1,5 +1,7 @@
 """Custom exceptions for FastMCP."""
 
+from mcp import McpError  # noqa: F401
+
 
 class FastMCPError(Exception):
     """Base error for FastMCP."""

fastmcp/prompts/prompt.py

@@ -13,7 +13,8 @@ from mcp.types import PromptArgument as MCPPromptArgument
 from pydantic import BaseModel, BeforeValidator, Field, TypeAdapter, validate_call
 
 from fastmcp.server.dependencies import get_context
-from fastmcp.utilities.json_schema import prune_params
+from fastmcp.utilities.json_schema import compress_schema
+from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import (
     _convert_set_defaults,
     find_kwarg_by_type,
@@ -25,6 +26,8 @@ if TYPE_CHECKING:
 
 CONTENT_TYPES = TextContent | ImageContent | EmbeddedResource
 
+logger = get_logger(__name__)
+
 
 def Message(
     content: str | CONTENT_TYPES, role: Role | None = None, **kwargs: Any
@@ -112,7 +115,11 @@ class Prompt(BaseModel):
 
         context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
         if context_kwarg:
-            parameters = prune_params(parameters, params=[context_kwarg])
+            prune_params = [context_kwarg]
+        else:
+            prune_params = None
+
+        parameters = compress_schema(parameters, prune_params=prune_params)
 
         # Convert parameters to PromptArguments
         arguments: list[PromptArgument] = []
@@ -192,13 +199,12 @@ class Prompt(BaseModel):
                             )
                         )
                 except Exception:
-                    raise ValueError(
-                        f"Could not convert prompt result to message: {msg}"
-                    )
+                    raise ValueError("Could not convert prompt result to message.")
 
             return messages
         except Exception as e:
-            raise ValueError(f"Error rendering prompt {self.name}: {e}")
+            logger.exception(f"Error rendering prompt {self.name}: {e}")
+            raise ValueError(f"Error rendering prompt {self.name}.")
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, Prompt):