fastmcp 2.12.1__py3-none-any.whl → 2.13.2__py3-none-any.whl

fastmcp/client/client.py

@@ -61,15 +61,15 @@ from .transports import (
 
 __all__ = [
     "Client",
-    "SessionKwargs",
-    "RootsHandler",
-    "RootsList",
-    "LogHandler",
-    "MessageHandler",
     "ClientSamplingHandler",
-    "SamplingHandler",
     "ElicitationHandler",
+    "LogHandler",
+    "MessageHandler",
     "ProgressHandler",
+    "RootsHandler",
+    "RootsList",
+    "SamplingHandler",
+    "SessionKwargs",
 ]
 
 logger = get_logger(__name__)
@@ -77,6 +77,16 @@ logger = get_logger(__name__)
 T = TypeVar("T", bound="ClientTransport")
 
 
+def _timeout_to_seconds(
+    timeout: datetime.timedelta | float | int | None,
+) -> float | None:
+    if timeout is None:
+        return None
+    if isinstance(timeout, datetime.timedelta):
+        return timeout.total_seconds()
+    return float(timeout)
+
+
 @dataclass
 class ClientSessionState:
     """Holds all session-related state for a Client instance.
@@ -155,38 +165,38 @@ class Client(Generic[ClientTransportT]):
     """
 
     @overload
-    def __init__(self: Client[T], transport: T, *args, **kwargs) -> None: ...
+    def __init__(self: Client[T], transport: T, *args: Any, **kwargs: Any) -> None: ...
 
     @overload
     def __init__(
         self: Client[SSETransport | StreamableHttpTransport],
         transport: AnyUrl,
-        *args,
-        **kwargs,
+        *args: Any,
+        **kwargs: Any,
     ) -> None: ...
 
     @overload
     def __init__(
         self: Client[FastMCPTransport],
         transport: FastMCP | FastMCP1Server,
-        *args,
-        **kwargs,
+        *args: Any,
+        **kwargs: Any,
     ) -> None: ...
 
     @overload
     def __init__(
         self: Client[PythonStdioTransport | NodeStdioTransport],
         transport: Path,
-        *args,
-        **kwargs,
+        *args: Any,
+        **kwargs: Any,
     ) -> None: ...
 
     @overload
     def __init__(
         self: Client[MCPConfigTransport],
         transport: MCPConfig | dict[str, Any],
-        *args,
-        **kwargs,
+        *args: Any,
+        **kwargs: Any,
     ) -> None: ...
 
     @overload
@@ -198,8 +208,8 @@ class Client(Generic[ClientTransportT]):
             | StreamableHttpTransport
         ],
         transport: str,
-        *args,
-        **kwargs,
+        *args: Any,
+        **kwargs: Any,
     ) -> None: ...
 
     def __init__(
@@ -222,6 +232,7 @@ class Client(Generic[ClientTransportT]):
         message_handler: MessageHandlerT | MessageHandler | None = None,
         progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
+        auto_initialize: bool = True,
         init_timeout: datetime.timedelta | float | int | None = None,
         client_info: mcp.types.Implementation | None = None,
         auth: httpx.Auth | Literal["oauth"] | str | None = None,
@@ -240,26 +251,23 @@ class Client(Generic[ClientTransportT]):
 
         self._progress_handler = progress_handler
 
+        # Convert timeout to timedelta if needed
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=float(timeout))
 
         # handle init handshake timeout
         if init_timeout is None:
             init_timeout = fastmcp.settings.client_init_timeout
-        if isinstance(init_timeout, datetime.timedelta):
-            init_timeout = init_timeout.total_seconds()
-        elif not init_timeout:
-            init_timeout = None
-        else:
-            init_timeout = float(init_timeout)
-        self._init_timeout = init_timeout
+        self._init_timeout = _timeout_to_seconds(init_timeout)
+
+        self.auto_initialize = auto_initialize
 
         self._session_kwargs: SessionKwargs = {
             "sampling_callback": None,
             "list_roots_callback": None,
             "logging_callback": create_log_callback(log_handler),
             "message_handler": message_handler,
-            "read_timeout_seconds": timeout,
+            "read_timeout_seconds": timeout,  # ty: ignore[invalid-argument-type]
             "client_info": client_info,
         }
 
@@ -290,12 +298,8 @@ class Client(Generic[ClientTransportT]):
         return self._session_state.session
 
     @property
-    def initialize_result(self) -> mcp.types.InitializeResult:
+    def initialize_result(self) -> mcp.types.InitializeResult | None:
         """Get the result of the initialization request."""
-        if self._session_state.initialize_result is None:
-            raise RuntimeError(
-                "Client is not connected. Use the 'async with client:' context manager first."
-            )
         return self._session_state.initialize_result
 
     def set_roots(self, roots: RootsList | RootsHandler) -> None:
@@ -357,15 +361,11 @@ class Client(Generic[ClientTransportT]):
                 self._session_state.session = session
                 # Initialize the session
                 try:
-                    with anyio.fail_after(self._init_timeout):
-                        self._session_state.initialize_result = (
-                            await self._session_state.session.initialize()
-                        )
+                    if self.auto_initialize:
+                        await self.initialize()
                     yield
-                except anyio.ClosedResourceError:
-                    raise RuntimeError("Server session was closed unexpectedly")
-                except TimeoutError:
-                    raise RuntimeError("Failed to initialize server session")
+                except anyio.ClosedResourceError as e:
+                    raise RuntimeError("Server session was closed unexpectedly") from e
                 finally:
                     self._session_state.session = None
                     self._session_state.initialize_result = None
@@ -454,7 +454,7 @@ class Client(Generic[ClientTransportT]):
             if self._session_state.nesting_counter > 0:
                 return
 
-            # stop the active seesion
+            # stop the active session
             if self._session_state.session_task is None:
                 return
             self._session_state.stop_event.set()
@@ -493,6 +493,55 @@ class Client(Generic[ClientTransportT]):
 
     # --- MCP Client Methods ---
 
+    async def initialize(
+        self,
+        timeout: datetime.timedelta | float | int | None = None,
+    ) -> mcp.types.InitializeResult:
+        """Send an initialize request to the server.
+
+        This method performs the MCP initialization handshake with the server,
+        exchanging capabilities and server information. It is idempotent - calling
+        it multiple times returns the cached result from the first call.
+
+        The initialization happens automatically when entering the client context
+        manager unless `auto_initialize=False` was set during client construction.
+        Manual calls to this method are only needed when auto-initialization is disabled.
+
+        Args:
+            timeout: Optional timeout for the initialization request (seconds or timedelta).
+                If None, uses the client's init_timeout setting.
+
+        Returns:
+            InitializeResult: The server's initialization response containing server info,
+                capabilities, protocol version, and optional instructions.
+
+        Raises:
+            RuntimeError: If the client is not connected or initialization times out.
+
+        Example:
+            ```python
+            # With auto-initialization disabled
+            client = Client(server, auto_initialize=False)
+            async with client:
+                result = await client.initialize()
+                print(f"Server: {result.serverInfo.name}")
+                print(f"Instructions: {result.instructions}")
+            ```
+        """
+
+        if self.initialize_result is not None:
+            return self.initialize_result
+
+        if timeout is None:
+            timeout = self._init_timeout
+        try:
+            with anyio.fail_after(_timeout_to_seconds(timeout)):
+                initialize_result = await self.session.initialize()
+                self._session_state.initialize_result = initialize_result
+                return initialize_result
+        except TimeoutError as e:
+            raise RuntimeError("Failed to initialize server session") from e
+
     async def ping(self) -> bool:
         """Send a ping request."""
         result = await self.session.send_ping()
@@ -505,7 +554,7 @@ class Client(Generic[ClientTransportT]):
     ) -> None:
         """Send a cancellation notification for an in-progress request."""
         notification = mcp.types.ClientNotification(
-            mcp.types.CancelledNotification(
+            root=mcp.types.CancelledNotification(
                 method="notifications/cancelled",
                 params=mcp.types.CancelledNotificationParams(
                     requestId=request_id,
@@ -743,14 +792,17 @@ class Client(Generic[ClientTransportT]):
 
     async def complete_mcp(
         self,
-        ref: mcp.types.ResourceReference | mcp.types.PromptReference,
+        ref: mcp.types.ResourceTemplateReference | mcp.types.PromptReference,
         argument: dict[str, str],
+        context_arguments: dict[str, Any] | None = None,
     ) -> mcp.types.CompleteResult:
         """Send a completion request and return the complete MCP protocol result.
 
         Args:
-            ref (mcp.types.ResourceReference | mcp.types.PromptReference): The reference to complete.
+            ref (mcp.types.ResourceTemplateReference | mcp.types.PromptReference): The reference to complete.
             argument (dict[str, str]): Arguments to pass to the completion request.
+            context_arguments (dict[str, Any] | None, optional): Optional context arguments to
+                include with the completion request. Defaults to None.
 
         Returns:
             mcp.types.CompleteResult: The complete response object from the protocol,
@@ -761,19 +813,24 @@ class Client(Generic[ClientTransportT]):
         """
         logger.debug(f"[{self.name}] called complete: {ref}")
 
-        result = await self.session.complete(ref=ref, argument=argument)
+        result = await self.session.complete(
+            ref=ref, argument=argument, context_arguments=context_arguments
+        )
         return result
 
     async def complete(
         self,
-        ref: mcp.types.ResourceReference | mcp.types.PromptReference,
+        ref: mcp.types.ResourceTemplateReference | mcp.types.PromptReference,
         argument: dict[str, str],
+        context_arguments: dict[str, Any] | None = None,
     ) -> mcp.types.Completion:
         """Send a completion request to the server.
 
         Args:
-            ref (mcp.types.ResourceReference | mcp.types.PromptReference): The reference to complete.
+            ref (mcp.types.ResourceTemplateReference | mcp.types.PromptReference): The reference to complete.
             argument (dict[str, str]): Arguments to pass to the completion request.
+            context_arguments (dict[str, Any] | None, optional): Optional context arguments to
+                include with the completion request. Defaults to None.
 
         Returns:
             mcp.types.Completion: The completion object.
@@ -781,7 +838,9 @@ class Client(Generic[ClientTransportT]):
         Raises:
             RuntimeError: If called while the client is not connected.
         """
-        result = await self.complete_mcp(ref=ref, argument=argument)
+        result = await self.complete_mcp(
+            ref=ref, argument=argument, context_arguments=context_arguments
+        )
         return result.completion
 
     # --- Tools ---
@@ -821,6 +880,7 @@ class Client(Generic[ClientTransportT]):
         arguments: dict[str, Any],
         progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> mcp.types.CallToolResult:
         """Send a tools/call request and return the complete MCP protocol result.
 
@@ -832,6 +892,10 @@ class Client(Generic[ClientTransportT]):
             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.
+            meta (dict[str, Any] | None, optional): Additional metadata to include with the request.
+                This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
+                that shouldn't be tool arguments but may influence server-side processing. The server
+                can access this via `context.request_context.meta`. Defaults to None.
 
         Returns:
             mcp.types.CallToolResult: The complete response object from the protocol,
@@ -842,13 +906,16 @@ class Client(Generic[ClientTransportT]):
         """
         logger.debug(f"[{self.name}] called call_tool: {name}")
 
+        # Convert timeout to timedelta if needed
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=float(timeout))
+
         result = await self.session.call_tool(
             name=name,
             arguments=arguments,
-            read_timeout_seconds=timeout,
+            read_timeout_seconds=timeout,  # ty: ignore[invalid-argument-type]
             progress_callback=progress_handler or self._progress_handler,
+            meta=meta,
         )
         return result
 
@@ -859,6 +926,7 @@ class Client(Generic[ClientTransportT]):
         timeout: datetime.timedelta | float | int | None = None,
         progress_handler: ProgressHandler | None = None,
         raise_on_error: bool = True,
+        meta: dict[str, Any] | None = None,
     ) -> CallToolResult:
         """Call a tool on the server.
 
@@ -869,6 +937,11 @@ class Client(Generic[ClientTransportT]):
             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.
+            raise_on_error (bool, optional): Whether to raise a ToolError if the tool call results in an error. Defaults to True.
+            meta (dict[str, Any] | None, optional): Additional metadata to include with the request.
+                This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
+                that shouldn't be tool arguments but may influence server-side processing. The server
+                can access this via `context.request_context.meta`. Defaults to None.
 
         Returns:
             CallToolResult:
@@ -888,6 +961,7 @@ class Client(Generic[ClientTransportT]):
             arguments=arguments or {},
             timeout=timeout,
             progress_handler=progress_handler,
+            meta=meta,
         )
         data = None
         if result.isError and raise_on_error:
@@ -918,6 +992,7 @@ class Client(Generic[ClientTransportT]):
         return CallToolResult(
             content=result.content,
             structured_content=result.structuredContent,
+            meta=result.meta,
             data=data,
             is_error=result.isError,
         )
@@ -935,5 +1010,6 @@ class Client(Generic[ClientTransportT]):
 class CallToolResult:
     content: list[mcp.types.ContentBlock]
     structured_content: dict[str, Any] | None
+    meta: dict[str, Any] | None
     data: Any = None
     is_error: bool = False

fastmcp/client/elicitation.py

@@ -59,7 +59,12 @@ def create_elicitation_callback(
                     "Elicitation responses must be serializable as a JSON object (dict). Received: "
                     f"{result.content!r}"
                 )
-            return MCPElicitResult(**result.model_dump() | {"content": content})
+            return MCPElicitResult(
+                _meta=result.meta,
+                action=result.action,
+                content=content,
+            )
+
         except Exception as e:
             return mcp.types.ErrorData(
                 code=mcp.types.INTERNAL_ERROR,

fastmcp/client/logging.py

@@ -1,4 +1,5 @@
 from collections.abc import Awaitable, Callable
+from logging import Logger
 from typing import TypeAlias
 
 from mcp.client.session import LoggingFnT
@@ -6,7 +7,8 @@ from mcp.types import LoggingMessageNotificationParams
 
 from fastmcp.utilities.logging import get_logger
 
-logger = get_logger(__name__)
+logger: Logger = get_logger(name=__name__)
+from_server_logger: Logger = get_logger(name="fastmcp.client.from_server")
 
 LogMessage: TypeAlias = LoggingMessageNotificationParams
 LogHandler: TypeAlias = Callable[[LogMessage], Awaitable[None]]
@@ -14,30 +16,32 @@ LogHandler: TypeAlias = Callable[[LogMessage], Awaitable[None]]
 
 async def default_log_handler(message: LogMessage) -> None:
     """Default handler that properly routes server log messages to appropriate log levels."""
-    msg = message.data.get("msg", str(message))
-    extra = message.data.get("extra", {})
+    # data can be any JSON-serializable type, not just a dict
+    data = message.data
 
     # Map MCP log levels to Python logging levels
     level_map = {
-        "debug": logger.debug,
-        "info": logger.info,
-        "notice": logger.info,  # Python doesn't have 'notice', map to info
-        "warning": logger.warning,
-        "error": logger.error,
-        "critical": logger.critical,
-        "alert": logger.critical,  # Map alert to critical
-        "emergency": logger.critical,  # Map emergency to critical
+        "debug": from_server_logger.debug,
+        "info": from_server_logger.info,
+        "notice": from_server_logger.info,  # Python doesn't have 'notice', map to info
+        "warning": from_server_logger.warning,
+        "error": from_server_logger.error,
+        "critical": from_server_logger.critical,
+        "alert": from_server_logger.critical,  # Map alert to critical
+        "emergency": from_server_logger.critical,  # Map emergency to critical
     }
 
     # Get the appropriate logging function based on the message level
     log_fn = level_map.get(message.level.lower(), logger.info)
 
     # Include logger name if available
+    msg_prefix: str = f"Received {message.level.upper()} from server"
+
     if message.logger:
-        msg = f"[{message.logger}] {msg}"
+        msg_prefix += f" ({message.logger})"
 
-    # Log with appropriate level and extra data
-    log_fn(f"Server log: {msg}", extra=extra)
+    # Log with appropriate level and data
+    log_fn(msg=f"{msg_prefix}: {data}")
 
 
 def create_log_callback(handler: LogHandler | None = None) -> LoggingFnT: