fastmcp 2.5.0__tar.gz → 2.5.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.5.0
+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.0 → 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.0 → 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.0 → 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.0 → fastmcp-2.5.2}/docs/patterns/http-requests.mdx

@@ -23,7 +23,7 @@ from fastmcp import FastMCP
 from fastmcp.server.dependencies import get_http_request
 from starlette.requests import Request
 
-mcp = FastMCP(name="HTTPRequestDemo")
+mcp = FastMCP(name="HTTP Request Demo")
 
 @mcp.tool()
 async def user_agent_info() -> dict:
@@ -48,32 +48,40 @@ This approach works anywhere within a request's execution flow, not just within
 2. You're calling nested functions that need HTTP request data
 3. You're working with middleware or other request processing code
 
-## Important Notes
-
-- HTTP requests are only available when FastMCP is running as part of a web application
-- Accessing the HTTP request outside of a web request context will raise a `RuntimeError`
-- The `get_http_request()` function returns a standard [Starlette Request](https://www.starlette.io/requests/) object
+## Accessing HTTP Headers Only
 
-## Common Use Cases
+If you only need request headers and want to avoid potential errors, you can use the `get_http_headers()` helper:
 
-### Accessing Request Headers
+```python {2}
+from fastmcp import FastMCP
+from fastmcp.server.dependencies import get_http_headers
 
-```python
-from fastmcp.server.dependencies import get_http_request
+mcp = FastMCP(name="Headers Demo")
 
 @mcp.tool()
-async def get_auth_info() -> dict:
-    """Get authentication information from request headers."""
-    request = get_http_request()
+async def safe_header_info() -> dict:
+    """Safely get header information without raising errors."""
+    # Get headers (returns empty dict if no request context)
+    headers = get_http_headers()
     
     # Get authorization header
-    auth_header = request.headers.get("authorization", "")
-    
-    # Check for Bearer token
+    auth_header = headers.get("authorization", "")
     is_bearer = auth_header.startswith("Bearer ")
     
     return {
+        "user_agent": headers.get("user-agent", "Unknown"),
+        "content_type": headers.get("content-type", "Unknown"),
         "has_auth": bool(auth_header),
-        "auth_type": "Bearer" if is_bearer else "Other" if auth_header else "None"
+        "auth_type": "Bearer" if is_bearer else "Other" if auth_header else "None",
+        "headers_count": len(headers)
     }
 ```
+
+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
+
+- HTTP requests are only available when FastMCP is running as part of a web application
+- Accessing the HTTP request with `get_http_request()` outside of a web request context will raise a `RuntimeError`
+- The `get_http_headers()` function **never raises errors** - it returns an empty dict when no request context is available
+- The `get_http_request()` function returns a standard [Starlette Request](https://www.starlette.io/requests/) object

{fastmcp-2.5.0 → fastmcp-2.5.2}/docs/servers/openapi.mdx

@@ -51,13 +51,7 @@ FastMCP analyzes your API specification and automatically creates MCP components
 | `GET` without path params | `GET /stats` | **Resource** |
 | `POST`, `PUT`, `PATCH`, `DELETE`, etc. | `POST /users` | **Tool** |
 
-
-
-### Custom Route Maps
-
-<VersionBadge version="2.5.0" />
-
-FastMCP uses an ordered list of `RouteMap` objects to determine how to map OpenAPI routes to various MCP component types.
+Interally, FastMCP uses an ordered list of `RouteMap` objects to determine how to map OpenAPI routes to various MCP component types.
 
 Each `RouteMap` specifies a combination of methods, patterns, and tags, as well as a corresponding MCP component type. Each OpenAPI route is checked against each `RouteMap` in order, and the first one that matches every criteria is used to determine its converted MCP type. A special type, `EXCLUDE`, can be used to exclude routes from the MCP server entirely.
 
@@ -66,7 +60,7 @@ Each `RouteMap` specifies a combination of methods, patterns, and tags, as well
 - **Tags**: A set of OpenAPI tags that must all be present. An empty set (`{}`) means no tag filtering, so the route matches regardless of its tags.
 - **MCP type**: What MCP component type to create (`TOOL`, `RESOURCE`, `RESOURCE_TEMPLATE`, or `EXCLUDE`)
 
-To illustrate this in practice, here are FastMCP's default route mappings as a list of `RouteMap` objects:
+To illustrate this in practice, here are FastMCP's default rules as a list of `RouteMap` objects:
 
 ```python
 from fastmcp.server.openapi import RouteMap, MCPType

{fastmcp-2.5.0 → 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.0 → 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: