fastmcp 2.5.1__py3-none-any.whl → 2.6.0__py3-none-any.whl

fastmcp/client/transports.py

@@ -1,13 +1,25 @@
 import abc
+import asyncio
 import contextlib
 import datetime
 import os
 import shutil
 import sys
-from collections.abc import AsyncIterator
+import warnings
+from collections.abc import AsyncIterator, Callable
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, TypedDict, cast
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    TypedDict,
+    TypeVar,
+    cast,
+    overload,
+)
 
+import anyio
+import httpx
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.session import (
     ListRootsFnT,
@@ -24,7 +36,7 @@ from mcp.shared.memory import create_connected_server_and_client_session
 from pydantic import AnyUrl
 from typing_extensions import Unpack
 
-from fastmcp.server import FastMCP as FastMCPServer
+from fastmcp.client.auth.oauth import OAuth
 from fastmcp.server.dependencies import get_http_headers
 from fastmcp.server.server import FastMCP
 from fastmcp.utilities.logging import get_logger
@@ -35,6 +47,23 @@ if TYPE_CHECKING:
 
 logger = get_logger(__name__)
 
+# TypeVar for preserving specific ClientTransport subclass types
+ClientTransportT = TypeVar("ClientTransportT", bound="ClientTransport")
+
+__all__ = [
+    "ClientTransport",
+    "SSETransport",
+    "StreamableHttpTransport",
+    "StdioTransport",
+    "PythonStdioTransport",
+    "FastMCPStdioTransport",
+    "NodeStdioTransport",
+    "UvxStdioTransport",
+    "NpxStdioTransport",
+    "FastMCPTransport",
+    "infer_transport",
+]
+
 
 class SessionKwargs(TypedDict, total=False):
     """Keyword arguments for the MCP ClientSession constructor."""
@@ -83,11 +112,25 @@ class ClientTransport(abc.ABC):
         # Basic representation for subclasses
         return f"<{self.__class__.__name__}>"
 
+    async def close(self):
+        """Close the transport."""
+        pass
+
+    def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
+        if auth is not None:
+            raise ValueError("This transport does not support auth")
+
 
 class WSTransport(ClientTransport):
     """Transport implementation that connects to an MCP server via WebSockets."""
 
     def __init__(self, url: str | AnyUrl):
+        # we never really used this transport, so it can be removed at any time
+        warnings.warn(
+            "WSTransport is a deprecated MCP transport and will be removed in a future version. Use StreamableHttpTransport instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if isinstance(url, AnyUrl):
             url = str(url)
         if not isinstance(url, str) or not url.startswith("ws"):
@@ -116,7 +159,9 @@ class SSETransport(ClientTransport):
         self,
         url: str | AnyUrl,
         headers: dict[str, str] | None = None,
+        auth: httpx.Auth | Literal["oauth"] | str | None = None,
         sse_read_timeout: datetime.timedelta | float | int | None = None,
+        httpx_client_factory: Callable[[], httpx.AsyncClient] | None = None,
     ):
         if isinstance(url, AnyUrl):
             url = str(url)
@@ -124,11 +169,21 @@ class SSETransport(ClientTransport):
             raise ValueError("Invalid HTTP/S URL provided for SSE.")
         self.url = url
         self.headers = headers or {}
+        self._set_auth(auth)
+        self.httpx_client_factory = httpx_client_factory
 
         if isinstance(sse_read_timeout, int | float):
             sse_read_timeout = datetime.timedelta(seconds=sse_read_timeout)
         self.sse_read_timeout = sse_read_timeout
 
+    def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
+        if auth == "oauth":
+            auth = OAuth(self.url)
+        elif isinstance(auth, str):
+            self.headers["Authorization"] = auth
+            auth = None
+        self.auth = auth
+
     @contextlib.asynccontextmanager
     async def connect_session(
         self, **session_kwargs: Unpack[SessionKwargs]
@@ -150,7 +205,10 @@ class SSETransport(ClientTransport):
             )
             client_kwargs["timeout"] = read_timeout_seconds.total_seconds()
 
-        async with sse_client(self.url, **client_kwargs) as transport:
+        if self.httpx_client_factory is not None:
+            client_kwargs["httpx_client_factory"] = self.httpx_client_factory
+
+        async with sse_client(self.url, auth=self.auth, **client_kwargs) as transport:
             read_stream, write_stream = transport
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
@@ -168,7 +226,9 @@ class StreamableHttpTransport(ClientTransport):
         self,
         url: str | AnyUrl,
         headers: dict[str, str] | None = None,
+        auth: httpx.Auth | Literal["oauth"] | str | None = None,
         sse_read_timeout: datetime.timedelta | float | int | None = None,
+        httpx_client_factory: Callable[[], httpx.AsyncClient] | None = None,
     ):
         if isinstance(url, AnyUrl):
             url = str(url)
@@ -176,11 +236,21 @@ class StreamableHttpTransport(ClientTransport):
             raise ValueError("Invalid HTTP/S URL provided for Streamable HTTP.")
         self.url = url
         self.headers = headers or {}
+        self._set_auth(auth)
+        self.httpx_client_factory = httpx_client_factory
 
         if isinstance(sse_read_timeout, int | float):
             sse_read_timeout = datetime.timedelta(seconds=sse_read_timeout)
         self.sse_read_timeout = sse_read_timeout
 
+    def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
+        if auth == "oauth":
+            auth = OAuth(self.url)
+        elif isinstance(auth, str):
+            self.headers["Authorization"] = auth
+            auth = None
+        self.auth = auth
+
     @contextlib.asynccontextmanager
     async def connect_session(
         self, **session_kwargs: Unpack[SessionKwargs]
@@ -199,7 +269,14 @@ class StreamableHttpTransport(ClientTransport):
         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, **client_kwargs) as transport:
+        if self.httpx_client_factory is not None:
+            client_kwargs["httpx_client_factory"] = self.httpx_client_factory
+
+        async with streamablehttp_client(
+            self.url,
+            auth=self.auth,
+            **client_kwargs,
+        ) as transport:
             read_stream, write_stream, _ = transport
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
@@ -224,6 +301,7 @@ class StdioTransport(ClientTransport):
         args: list[str],
         env: dict[str, str] | None = None,
         cwd: str | None = None,
+        keep_alive: bool | None = None,
     ):
         """
         Initialize a Stdio transport.
@@ -233,25 +311,90 @@ class StdioTransport(ClientTransport):
             args: The arguments to pass to the command
             env: Environment variables to set for the subprocess
             cwd: Current working directory for the subprocess
+            keep_alive: Whether to keep the subprocess alive between connections.
+                       Defaults to True. When True, the subprocess remains active
+                       after the connection context exits, allowing reuse in
+                       subsequent connections.
         """
         self.command = command
         self.args = args
         self.env = env
         self.cwd = cwd
+        if keep_alive is None:
+            keep_alive = True
+        self.keep_alive = keep_alive
+
+        self._session: ClientSession | None = None
+        self._connect_task: asyncio.Task | None = None
+        self._ready_event = anyio.Event()
+        self._stop_event = anyio.Event()
 
     @contextlib.asynccontextmanager
     async def connect_session(
         self, **session_kwargs: Unpack[SessionKwargs]
     ) -> AsyncIterator[ClientSession]:
-        server_params = StdioServerParameters(
-            command=self.command, args=self.args, env=self.env, cwd=self.cwd
-        )
-        async with stdio_client(server_params) as transport:
-            read_stream, write_stream = transport
-            async with ClientSession(
-                read_stream, write_stream, **session_kwargs
-            ) as session:
-                yield session
+        try:
+            await self.connect(**session_kwargs)
+            assert self._session is not None
+            yield self._session
+        finally:
+            if not self.keep_alive:
+                await self.disconnect()
+            else:
+                logger.debug("Stdio transport has keep_alive=True, not disconnecting")
+
+    async def connect(
+        self, **session_kwargs: Unpack[SessionKwargs]
+    ) -> ClientSession | None:
+        if self._connect_task is not None:
+            return
+
+        async def _connect_task():
+            async with contextlib.AsyncExitStack() as stack:
+                try:
+                    server_params = StdioServerParameters(
+                        command=self.command, args=self.args, env=self.env, cwd=self.cwd
+                    )
+                    transport = await stack.enter_async_context(
+                        stdio_client(server_params)
+                    )
+                    read_stream, write_stream = transport
+                    self._session = await stack.enter_async_context(
+                        ClientSession(read_stream, write_stream, **session_kwargs)
+                    )
+
+                    logger.debug("Stdio transport connected")
+                    self._ready_event.set()
+
+                    # Wait until disconnect is requested (stop_event is set)
+                    await self._stop_event.wait()
+                finally:
+                    # Clean up client on exit
+                    self._session = None
+                    logger.debug("Stdio transport disconnected")
+
+        # start the connection task
+        self._connect_task = asyncio.create_task(_connect_task())
+        # wait for the client to be ready before returning
+        await self._ready_event.wait()
+
+    async def disconnect(self):
+        if self._connect_task is None:
+            return
+
+        # signal the connection task to stop
+        self._stop_event.set()
+
+        # wait for the connection task to finish cleanly
+        await self._connect_task
+
+        # reset variables and events for potential future reconnects
+        self._connect_task = None
+        self._stop_event = anyio.Event()
+        self._ready_event = anyio.Event()
+
+    async def close(self):
+        await self.disconnect()
 
     def __repr__(self) -> str:
         return (
@@ -269,6 +412,7 @@ class PythonStdioTransport(StdioTransport):
         env: dict[str, str] | None = None,
         cwd: str | None = None,
         python_cmd: str = sys.executable,
+        keep_alive: bool | None = None,
     ):
         """
         Initialize a Python transport.
@@ -279,6 +423,10 @@ class PythonStdioTransport(StdioTransport):
             env: Environment variables to set for the subprocess
             cwd: Current working directory for the subprocess
             python_cmd: Python command to use (default: "python")
+            keep_alive: Whether to keep the subprocess alive between connections.
+                       Defaults to True. When True, the subprocess remains active
+                       after the connection context exits, allowing reuse in
+                       subsequent connections.
         """
         script_path = Path(script_path).resolve()
         if not script_path.is_file():
@@ -290,7 +438,13 @@ class PythonStdioTransport(StdioTransport):
         if args:
             full_args.extend(args)
 
-        super().__init__(command=python_cmd, args=full_args, env=env, cwd=cwd)
+        super().__init__(
+            command=python_cmd,
+            args=full_args,
+            env=env,
+            cwd=cwd,
+            keep_alive=keep_alive,
+        )
         self.script_path = script_path
 
 
@@ -303,6 +457,7 @@ class FastMCPStdioTransport(StdioTransport):
         args: list[str] | None = None,
         env: dict[str, str] | None = None,
         cwd: str | None = None,
+        keep_alive: bool | None = None,
     ):
         script_path = Path(script_path).resolve()
         if not script_path.is_file():
@@ -311,7 +466,11 @@ class FastMCPStdioTransport(StdioTransport):
             raise ValueError(f"Not a Python script: {script_path}")
 
         super().__init__(
-            command="fastmcp", args=["run", str(script_path)], env=env, cwd=cwd
+            command="fastmcp",
+            args=["run", str(script_path)],
+            env=env,
+            cwd=cwd,
+            keep_alive=keep_alive,
         )
         self.script_path = script_path
 
@@ -326,6 +485,7 @@ class NodeStdioTransport(StdioTransport):
         env: dict[str, str] | None = None,
         cwd: str | None = None,
         node_cmd: str = "node",
+        keep_alive: bool | None = None,
     ):
         """
         Initialize a Node transport.
@@ -336,6 +496,10 @@ class NodeStdioTransport(StdioTransport):
             env: Environment variables to set for the subprocess
             cwd: Current working directory for the subprocess
             node_cmd: Node.js command to use (default: "node")
+            keep_alive: Whether to keep the subprocess alive between connections.
+                       Defaults to True. When True, the subprocess remains active
+                       after the connection context exits, allowing reuse in
+                       subsequent connections.
         """
         script_path = Path(script_path).resolve()
         if not script_path.is_file():
@@ -347,7 +511,9 @@ class NodeStdioTransport(StdioTransport):
         if args:
             full_args.extend(args)
 
-        super().__init__(command=node_cmd, args=full_args, env=env, cwd=cwd)
+        super().__init__(
+            command=node_cmd, args=full_args, env=env, cwd=cwd, keep_alive=keep_alive
+        )
         self.script_path = script_path
 
 
@@ -363,6 +529,7 @@ class UvxStdioTransport(StdioTransport):
         with_packages: list[str] | None = None,
         from_package: str | None = None,
         env_vars: dict[str, str] | None = None,
+        keep_alive: bool | None = None,
     ):
         """
         Initialize a Uvx transport.
@@ -375,6 +542,10 @@ class UvxStdioTransport(StdioTransport):
             with_packages: Additional packages to include
             from_package: Package to install the tool from
             env_vars: Additional environment variables
+            keep_alive: Whether to keep the subprocess alive between connections.
+                       Defaults to True. When True, the subprocess remains active
+                       after the connection context exits, allowing reuse in
+                       subsequent connections.
         """
         # Basic validation
         if project_directory and not Path(project_directory).exists():
@@ -402,7 +573,13 @@ class UvxStdioTransport(StdioTransport):
             env = os.environ.copy()
             env.update(env_vars)
 
-        super().__init__(command="uvx", args=uvx_args, env=env, cwd=project_directory)
+        super().__init__(
+            command="uvx",
+            args=uvx_args,
+            env=env,
+            cwd=project_directory,
+            keep_alive=keep_alive,
+        )
         self.tool_name = tool_name
 
 
@@ -416,6 +593,7 @@ class NpxStdioTransport(StdioTransport):
         project_directory: str | None = None,
         env_vars: dict[str, str] | None = None,
         use_package_lock: bool = True,
+        keep_alive: bool | None = None,
     ):
         """
         Initialize an Npx transport.
@@ -426,6 +604,10 @@ class NpxStdioTransport(StdioTransport):
             project_directory: Project directory with package.json
             env_vars: Additional environment variables
             use_package_lock: Whether to use package-lock.json (--prefer-offline)
+            keep_alive: Whether to keep the subprocess alive between connections.
+                       Defaults to True. When True, the subprocess remains active
+                       after the connection context exits, allowing reuse in
+                       subsequent connections.
         """
         # verify npx is installed
         if shutil.which("npx") is None:
@@ -453,7 +635,13 @@ class NpxStdioTransport(StdioTransport):
             env = os.environ.copy()
             env.update(env_vars)
 
-        super().__init__(command="npx", args=npx_args, env=env, cwd=project_directory)
+        super().__init__(
+            command="npx",
+            args=npx_args,
+            env=env,
+            cwd=project_directory,
+            keep_alive=keep_alive,
+        )
         self.package = package
 
 
@@ -466,7 +654,7 @@ class FastMCPTransport(ClientTransport):
     tests or scenarios where client and server run in the same runtime.
     """
 
-    def __init__(self, mcp: FastMCPServer | FastMCP1Server):
+    def __init__(self, mcp: FastMCP | FastMCP1Server):
         """Initialize a FastMCPTransport from a FastMCP server instance."""
 
         # Accept both FastMCP 2.x and FastMCP 1.0 servers. Both expose a
@@ -575,9 +763,47 @@ class MCPConfigTransport(ClientTransport):
         return f"<MCPConfig(config='{self.config}')>"
 
 
+@overload
+def infer_transport(transport: ClientTransportT) -> ClientTransportT: ...
+
+
+@overload
+def infer_transport(transport: FastMCP) -> FastMCPTransport: ...
+
+
+@overload
+def infer_transport(transport: FastMCP1Server) -> FastMCPTransport: ...
+
+
+@overload
+def infer_transport(transport: MCPConfig) -> MCPConfigTransport: ...
+
+
+@overload
+def infer_transport(transport: dict[str, Any]) -> MCPConfigTransport: ...
+
+
+@overload
+def infer_transport(
+    transport: AnyUrl,
+) -> SSETransport | StreamableHttpTransport: ...
+
+
+@overload
+def infer_transport(
+    transport: str,
+) -> (
+    PythonStdioTransport | NodeStdioTransport | SSETransport | StreamableHttpTransport
+): ...
+
+
+@overload
+def infer_transport(transport: Path) -> PythonStdioTransport | NodeStdioTransport: ...
+
+
 def infer_transport(
     transport: ClientTransport
-    | FastMCPServer
+    | FastMCP
     | FastMCP1Server
     | AnyUrl
     | Path
@@ -594,7 +820,7 @@ def infer_transport(
 
     The function supports these input types:
     - ClientTransport: Used directly without modification
-    - FastMCPServer or FastMCP1Server: Creates an in-memory FastMCPTransport
+    - FastMCP or FastMCP1Server: 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
@@ -632,7 +858,7 @@ def infer_transport(
         return transport
 
     # the transport is a FastMCP server (2.x or 1.0)
-    elif isinstance(transport, FastMCPServer | FastMCP1Server):
+    elif isinstance(transport, FastMCP | FastMCP1Server):
         inferred_transport = FastMCPTransport(mcp=transport)
 
     # the transport is a path to a script

fastmcp/resources/template.py

@@ -148,7 +148,7 @@ class ResourceTemplate(BaseModel):
                     f"URI parameters {uri_params} must be a subset of the function arguments: {func_params}"
                 )
 
-        description = description or fn.__doc__ or ""
+        description = description or fn.__doc__
 
         if not inspect.isroutine(fn):
             fn = fn.__call__

fastmcp/server/auth/__init__.py

@@ -0,0 +1,4 @@
+from .providers.bearer import BearerAuthProvider
+
+
+__all__ = ["BearerAuthProvider"]

fastmcp/server/auth/auth.py

@@ -0,0 +1,45 @@
+from mcp.server.auth.provider import (
+    AccessToken,
+    AuthorizationCode,
+    OAuthAuthorizationServerProvider,
+    RefreshToken,
+)
+from mcp.server.auth.settings import (
+    ClientRegistrationOptions,
+    RevocationOptions,
+)
+from pydantic import AnyHttpUrl
+
+
+class OAuthProvider(
+    OAuthAuthorizationServerProvider[AuthorizationCode, RefreshToken, AccessToken]
+):
+    def __init__(
+        self,
+        issuer_url: AnyHttpUrl | str,
+        service_documentation_url: AnyHttpUrl | str | None = None,
+        client_registration_options: ClientRegistrationOptions | None = None,
+        revocation_options: RevocationOptions | None = None,
+        required_scopes: list[str] | None = None,
+    ):
+        """
+        Initialize the OAuth provider.
+
+        Args:
+            issuer_url: The URL of the OAuth issuer.
+            service_documentation_url: The URL of the service documentation.
+            client_registration_options: The client registration options.
+            revocation_options: The revocation options.
+            required_scopes: Scopes that are required for all requests.
+        """
+        super().__init__()
+        if isinstance(issuer_url, str):
+            issuer_url = AnyHttpUrl(issuer_url)
+        if isinstance(service_documentation_url, str):
+            service_documentation_url = AnyHttpUrl(service_documentation_url)
+
+        self.issuer_url = issuer_url
+        self.service_documentation_url = service_documentation_url
+        self.client_registration_options = client_registration_options
+        self.revocation_options = revocation_options
+        self.required_scopes = required_scopes