fastmcp 2.5.1__tar.gz → 2.5.2__tar.gz

{fastmcp-2.5.1 → fastmcp-2.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.5.1
+Version: 2.5.2
 Summary: The fast, Pythonic way to build MCP servers.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp

{fastmcp-2.5.1 → fastmcp-2.5.2}/docs/clients/client.mdx

@@ -18,18 +18,6 @@ The FastMCP Client architecture separates the protocol logic (`Client`) from the
 - **`Client`**: Handles sending MCP requests (like `tools/call`, `resources/read`), receiving responses, and managing callbacks.
 - **`Transport`**: Responsible for establishing and maintaining the connection to the server (e.g., via WebSockets, SSE, Stdio, or in-memory).
 
-```python
-from fastmcp import Client, FastMCP
-from fastmcp.client import (
-    RootsHandler,
-    RootsList,
-    LogHandler,
-    MessageHandler,
-    SamplingHandler,
-    ProgressHandler  # For handling progress notifications
-)
-```
-
 ### Transports
 
 Clients must be initialized with a `transport`. You can either provide an already instantiated transport object, or provide a transport source and let FastMCP attempt to infer the correct transport to use.
@@ -282,7 +270,7 @@ These methods are especially useful for debugging or when you need to access met
 
 ### Additional Features
 
-#### Pinging the server
+#### Pinging the Server
 
 The client can be used to ping the server to verify connectivity.
 
@@ -292,6 +280,29 @@ async with client:
     print("Server is reachable")
 ```
 
+#### Session Management
+
+When using stdio transports, clients support a `keep_alive` feature (enabled by default) that maintains subprocess sessions between connection contexts. You can manually control this behavior using the client's `close()` method.
+
+When `keep_alive=False`, the client will automatically close the session when the context manager exits.
+
+```python
+from fastmcp import Client
+
+client = Client("my_mcp_server.py")  # keep_alive=True by default
+
+async def example():
+    async with client:
+        await client.ping()
+    
+    async with client:
+        await client.ping()  # Same subprocess as above
+```
+
+<Note>
+For detailed examples and configuration options, see [Session Management in Transports](/clients/transports#session-management).
+</Note>
+
 #### Timeouts
 
 <VersionBadge version="2.3.4" />

{fastmcp-2.5.1 → fastmcp-2.5.2}/docs/clients/transports.mdx

@@ -160,6 +160,63 @@ client = Client(transport)
 
 These transports manage an MCP server running as a subprocess, communicating with it via standard input (stdin) and standard output (stdout). This is the standard mechanism used by clients like Claude Desktop.
 
+### Session Management
+
+All stdio transports support a `keep_alive` parameter (default: `True`) that controls session persistence across multiple client context managers:
+
+- **`keep_alive=True` (default)**: The subprocess and session are maintained between client context exits and re-entries. This improves performance when making multiple separate connections to the same server.
+- **`keep_alive=False`**: A new subprocess is started for each client context, ensuring complete isolation between sessions.
+
+When `keep_alive=True`, you can manually close the session using `await client.close()` if needed. This will terminate the subprocess and require a new one to be started on the next connection.
+
+<CodeGroup>
+```python keep_alive=True
+from fastmcp import Client
+
+# Client with keep_alive=True (default)
+client = Client("my_mcp_server.py")
+
+async def example():
+    # First session
+    async with client:
+        await client.ping()
+
+    # Second session - uses the same subprocess
+    async with client:
+        await client.ping()
+
+    # Manually close the session
+    await client.close()
+
+    # Third session - will start a new subprocess
+    async with client:
+        await client.ping()
+
+asyncio.run(example())
+```
+```python keep_alive=False
+from fastmcp import Client
+
+# Client with keep_alive=False
+client = Client("my_mcp_server.py", keep_alive=False)
+
+async def example():
+    # First session
+    async with client:
+        await client.ping()
+    
+    # Second session - will start a new subprocess
+    async with client:
+        await client.ping()
+
+    # Third session - will start a new subprocess
+    async with client:
+        await client.ping()
+
+asyncio.run(example())
+```
+</CodeGroup>
+
 ### Python Stdio
 
 - **Class:** `fastmcp.client.transports.PythonStdioTransport`
@@ -218,7 +275,7 @@ client = Client(node_server_script)
 # Option 2: Explicit transport
 transport = NodeStdioTransport(
     script_path=node_server_script,
-    node_cmd="node" # Optional: specify path to Node executable
+    node_cmd="node", # Optional: specify path to Node executable
 )
 client = Client(transport)
 

{fastmcp-2.5.1 → fastmcp-2.5.2}/docs/deployment/cli.mdx

@@ -148,9 +148,12 @@ Install a MCP server in the Claude desktop app.
 fastmcp install server.py
 ```
 
-<Tip>
-This command installs your server in an isolated environment. All dependencies must be explicitly specified using the `--with` and/or `--with-editable` options.
-</Tip>
+
+Note that for security reasons, Claude runs every MCP server in a completely isolated environment. Therefore, all dependencies must be explicitly specified using the `--with` and/or `--with-editable` options (following `uv` conventions) or by attaching them to your server in code via the `dependencies` parameter.
+<Warning>
+- **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.
+- **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop.
+</Warning>
 
 <Warning>
 The `install` command currently only sets up servers for STDIO transport. When installed in the Claude desktop app, your server will be run using STDIO regardless of any transport configuration in your code.

{fastmcp-2.5.1 → fastmcp-2.5.2}/docs/patterns/http-requests.mdx

@@ -77,7 +77,7 @@ async def safe_header_info() -> dict:
     }
 ```
 
-By default, `get_http_headers()` excludes problematic headers like `content-length`. To include all headers, use `get_http_headers(include_all=True)`.
+By default, `get_http_headers()` excludes problematic headers like `host` and `content-length`. To include all headers, use `get_http_headers(include_all=True)`.
 
 ## Important Notes
 

{fastmcp-2.5.1 → fastmcp-2.5.2}/src/fastmcp/cli/cli.py

@@ -50,9 +50,7 @@ def _get_npx_command():
 def _parse_env_var(env_var: str) -> tuple[str, str]:
     """Parse environment variable string in format KEY=VALUE."""
     if "=" not in env_var:
-        logger.error(
-            f"Invalid environment variable format: {env_var}. Must be KEY=VALUE"
-        )
+        logger.error("Invalid environment variable format. Must be KEY=VALUE")
         sys.exit(1)
     key, value = env_var.split("=", 1)
     return key.strip(), value.strip()

{fastmcp-2.5.1 → fastmcp-2.5.2}/src/fastmcp/client/client.py

@@ -1,7 +1,7 @@
 import datetime
 from contextlib import AsyncExitStack, asynccontextmanager
 from pathlib import Path
-from typing import Any, cast
+from typing import Any, Generic, cast, overload
 
 import anyio
 import mcp.types
@@ -9,6 +9,7 @@ from exceptiongroup import catch
 from mcp import ClientSession
 from pydantic import AnyUrl
 
+import fastmcp
 from fastmcp.client.logging import (
     LogHandler,
     MessageHandler,
@@ -27,7 +28,18 @@ 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
+from .transports import (
+    ClientTransportT,
+    FastMCP1Server,
+    FastMCPTransport,
+    MCPConfigTransport,
+    NodeStdioTransport,
+    PythonStdioTransport,
+    SessionKwargs,
+    SSETransport,
+    StreamableHttpTransport,
+    infer_transport,
+)
 
 __all__ = [
     "Client",
@@ -40,13 +52,13 @@ __all__ = [
 ]
 
 
-class Client:
+class Client(Generic[ClientTransportT]):
     """
     MCP client that delegates connection management to a Transport instance.
 
     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.
+    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:
@@ -62,24 +74,60 @@ class Client:
         message_handler: Optional handler for protocol messages
         progress_handler: Optional handler for progress notifications
         timeout: Optional timeout for requests (seconds or timedelta)
+        init_timeout: Optional timeout for initial connection (seconds or timedelta).
+            Set to 0 to disable. If None, uses the value in the FastMCP global settings.
 
     Examples:
-        ```python
-        # Connect to FastMCP server
-        client = Client("http://localhost:8080")
+        ```python # Connect to FastMCP server client =
+        Client("http://localhost:8080")
 
         async with client:
-            # List available resources
-            resources = await client.list_resources()
+            # List available resources resources = await client.list_resources()
 
-            # Call a tool
-            result = await client.call_tool("my_tool", {"param": "value"})
+            # Call a tool result = await client.call_tool("my_tool", {"param":
+            "value"})
         ```
     """
 
+    @overload
+    def __new__(
+        cls,
+        transport: ClientTransportT,
+        **kwargs: Any,
+    ) -> "Client[ClientTransportT]": ...
+
+    @overload
+    def __new__(
+        cls, transport: AnyUrl, **kwargs
+    ) -> "Client[SSETransport|StreamableHttpTransport]": ...
+
+    @overload
+    def __new__(
+        cls, transport: FastMCP | FastMCP1Server, **kwargs
+    ) -> "Client[FastMCPTransport]": ...
+
+    @overload
+    def __new__(
+        cls, transport: Path, **kwargs
+    ) -> "Client[PythonStdioTransport|NodeStdioTransport]": ...
+
+    @overload
+    def __new__(
+        cls, transport: MCPConfig | dict[str, Any], **kwargs
+    ) -> "Client[MCPConfigTransport]": ...
+
+    @overload
+    def __new__(
+        cls, transport: str, **kwargs
+    ) -> "Client[PythonStdioTransport|NodeStdioTransport|SSETransport|StreamableHttpTransport]": ...
+
+    def __new__(cls, transport, **kwargs) -> "Client":
+        instance = super().__new__(cls)
+        return instance
+
     def __init__(
         self,
-        transport: ClientTransport
+        transport: ClientTransportT
         | FastMCP
         | AnyUrl
         | Path
@@ -93,8 +141,9 @@ class Client:
         message_handler: MessageHandler | None = None,
         progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
+        init_timeout: datetime.timedelta | float | int | None = None,
     ):
-        self.transport = infer_transport(transport)
+        self.transport = cast(ClientTransportT, infer_transport(transport))
         self._session: ClientSession | None = None
         self._exit_stack: AsyncExitStack | None = None
         self._nesting_counter: int = 0
@@ -111,6 +160,17 @@ class Client:
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=timeout)
 
+        # handle init handshake timeout
+        if init_timeout is None:
+            init_timeout = fastmcp.settings.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._session_kwargs: SessionKwargs = {
             "sampling_callback": None,
             "list_roots_callback": None,
@@ -134,6 +194,7 @@ class Client:
             raise RuntimeError(
                 "Client is not connected. Use the 'async with client:' context manager first."
             )
+
         return self._session
 
     @property
@@ -168,9 +229,11 @@ class Client:
                 self._session = session
                 # Initialize the session
                 try:
-                    with anyio.fail_after(1):
+                    with anyio.fail_after(self._init_timeout):
                         self._initialize_result = await self._session.initialize()
                     yield
+                except anyio.ClosedResourceError:
+                    raise RuntimeError("Server session was closed unexpectedly")
                 except TimeoutError:
                     raise RuntimeError("Failed to initialize server session")
                 finally:
@@ -203,6 +266,11 @@ class Client:
                 finally:
                     self._exit_stack = None
 
+    async def close(self):
+        await self.transport.close()
+        self._session = None
+        self._initialize_result = None
+
     # --- MCP Client Methods ---
 
     async def ping(self) -> bool: