fastmcp 2.11.3__py3-none-any.whl → 2.12.0__py3-none-any.whl

fastmcp/client/transports.py

@@ -21,6 +21,9 @@ from mcp.client.session import (
     MessageHandlerFnT,
     SamplingFnT,
 )
+from mcp.client.sse import sse_client
+from mcp.client.stdio import stdio_client
+from mcp.client.streamable_http import streamablehttp_client
 from mcp.server.fastmcp import FastMCP as FastMCP1Server
 from mcp.shared._httpx_utils import McpHttpClientFactory
 from mcp.shared.memory import create_client_server_memory_streams
@@ -34,6 +37,7 @@ from fastmcp.mcp_config import MCPConfig, infer_transport_type_from_url
 from fastmcp.server.dependencies import get_http_headers
 from fastmcp.server.server import FastMCP
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
 
 logger = get_logger(__name__)
 
@@ -178,7 +182,7 @@ class SSETransport(ClientTransport):
         self.httpx_client_factory = httpx_client_factory
 
         if isinstance(sse_read_timeout, int | float):
-            sse_read_timeout = datetime.timedelta(seconds=sse_read_timeout)
+            sse_read_timeout = datetime.timedelta(seconds=float(sse_read_timeout))
         self.sse_read_timeout = sse_read_timeout
 
     def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
@@ -192,8 +196,6 @@ class SSETransport(ClientTransport):
     async def connect_session(
         self, **session_kwargs: Unpack[SessionKwargs]
     ) -> AsyncIterator[ClientSession]:
-        from mcp.client.sse import sse_client
-
         client_kwargs: dict[str, Any] = {}
 
         # load headers from an active HTTP request, if available. This will only be true
@@ -250,7 +252,7 @@ class StreamableHttpTransport(ClientTransport):
         self.httpx_client_factory = httpx_client_factory
 
         if isinstance(sse_read_timeout, int | float):
-            sse_read_timeout = datetime.timedelta(seconds=sse_read_timeout)
+            sse_read_timeout = datetime.timedelta(seconds=float(sse_read_timeout))
         self.sse_read_timeout = sse_read_timeout
 
     def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
@@ -264,8 +266,6 @@ class StreamableHttpTransport(ClientTransport):
     async def connect_session(
         self, **session_kwargs: Unpack[SessionKwargs]
     ) -> AsyncIterator[ClientSession]:
-        from mcp.client.streamable_http import streamablehttp_client
-
         client_kwargs: dict[str, Any] = {}
 
         # load headers from an active HTTP request, if available. This will only be true
@@ -346,8 +346,7 @@ class StdioTransport(ClientTransport):
     ) -> AsyncIterator[ClientSession]:
         try:
             await self.connect(**session_kwargs)
-            assert self._session is not None
-            yield self._session
+            yield cast(ClientSession, self._session)
         finally:
             if not self.keep_alive:
                 await self.disconnect()
@@ -360,42 +359,22 @@ class StdioTransport(ClientTransport):
         if self._connect_task is not None:
             return
 
-        async def _connect_task():
-            from mcp.client.stdio import stdio_client
-
-            try:
-                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")
-            except Exception:
-                # Ensure ready event is set even if connection fails
-                self._ready_event.set()
-                raise
+        session_future: asyncio.Future[ClientSession] = asyncio.Future()
 
         # start the connection task
-        self._connect_task = asyncio.create_task(_connect_task())
+        self._connect_task = asyncio.create_task(
+            _stdio_transport_connect_task(
+                command=self.command,
+                args=self.args,
+                env=self.env,
+                cwd=self.cwd,
+                session_kwargs=session_kwargs,
+                ready_event=self._ready_event,
+                stop_event=self._stop_event,
+                session_future=session_future,
+            )
+        )
+
         # wait for the client to be ready before returning
         await self._ready_event.wait()
 
@@ -405,6 +384,9 @@ class StdioTransport(ClientTransport):
             if exception is not None:
                 raise exception
 
+        self._session = await session_future
+        return self._session
+
     async def disconnect(self):
         if self._connect_task is None:
             return
@@ -423,12 +405,61 @@ class StdioTransport(ClientTransport):
     async def close(self):
         await self.disconnect()
 
+    def __del__(self):
+        """Ensure that we send a disconnection signal to the transport task if we are being garbage collected."""
+        if not self._stop_event.is_set():
+            self._stop_event.set()
+
     def __repr__(self) -> str:
         return (
             f"<{self.__class__.__name__}(command='{self.command}', args={self.args})>"
         )
 
 
+async def _stdio_transport_connect_task(
+    command: str,
+    args: list[str],
+    env: dict[str, str] | None,
+    cwd: str | None,
+    session_kwargs: SessionKwargs,
+    ready_event: anyio.Event,
+    stop_event: anyio.Event,
+    session_future: asyncio.Future[ClientSession],
+):
+    """A standalone connection task for a stdio transport. It is not a part of the StdioTransport class
+    to ensure that the connection task does not hold a reference to the Transport object."""
+
+    try:
+        async with contextlib.AsyncExitStack() as stack:
+            try:
+                server_params = StdioServerParameters(
+                    command=command,
+                    args=args,
+                    env=env,
+                    cwd=cwd,
+                )
+                transport = await stack.enter_async_context(stdio_client(server_params))
+                read_stream, write_stream = transport
+                session_future.set_result(
+                    await stack.enter_async_context(
+                        ClientSession(read_stream, write_stream, **session_kwargs)
+                    )
+                )
+
+                logger.debug("Stdio transport connected")
+                ready_event.set()
+
+                # Wait until disconnect is requested (stop_event is set)
+                await stop_event.wait()
+            finally:
+                # Clean up client on exit
+                logger.debug("Stdio transport disconnected")
+    except Exception:
+        # Ensure ready event is set even if connection fails
+        ready_event.set()
+        raise
+
+
 class PythonStdioTransport(StdioTransport):
     """Transport for running Python scripts."""
 
@@ -565,16 +596,38 @@ class UvStdioTransport(StdioTransport):
                 f"Project directory not found: {project_directory}"
             )
 
-        # Build uv arguments
-        uv_args: list[str] = ["run"]
-        if project_directory:
-            uv_args.extend(["--directory", str(project_directory)])
-        if python_version:
-            uv_args.extend(["--python", python_version])
-        for pkg in with_packages or []:
-            uv_args.extend(["--with", pkg])
-        if with_requirements:
-            uv_args.extend(["--with-requirements", str(with_requirements)])
+        # Create Environment from provided parameters (internal use)
+        env_config = UVEnvironment(
+            python=python_version,
+            dependencies=with_packages,
+            requirements=with_requirements,
+            project=project_directory,
+            editable=None,  # Not exposed in this transport
+        )
+
+        # Build uv arguments using the config
+        uv_args: list[str] = []
+
+        # Check if we need any environment setup
+        if env_config.needs_uv():
+            # Use the config to build args, but we need to handle the command differently
+            # since transport has specific needs
+            uv_args = ["run"]
+
+            if python_version:
+                uv_args.extend(["--python", python_version])
+            if project_directory:
+                uv_args.extend(["--directory", str(project_directory)])
+
+            # Note: Don't add fastmcp as dependency here, transport is for general use
+            for pkg in with_packages or []:
+                uv_args.extend(["--with", pkg])
+            if with_requirements:
+                uv_args.extend(["--with-requirements", str(with_requirements)])
+        else:
+            # No environment setup needed
+            uv_args = ["run"]
+
         if module:
             uv_args.append("--module")
 
@@ -830,12 +883,14 @@ class MCPConfigTransport(ClientTransport):
     """
 
     def __init__(self, config: MCPConfig | dict, name_as_prefix: bool = True):
-        from fastmcp.utilities.mcp_config import composite_server_from_mcp_config
+        from fastmcp.utilities.mcp_config import mcp_config_to_servers_and_transports
 
         if isinstance(config, dict):
             config = MCPConfig.from_dict(config)
         self.config = config
 
+        self._underlying_transports: list[ClientTransport] = []
+
         # if there are no servers, raise an error
         if len(self.config.mcpServers) == 0:
             raise ValueError("No MCP servers defined in the config")
@@ -843,14 +898,22 @@ class MCPConfigTransport(ClientTransport):
         # if there's exactly one server, create a client for that server
         elif len(self.config.mcpServers) == 1:
             self.transport = list(self.config.mcpServers.values())[0].to_transport()
+            self._underlying_transports.append(self.transport)
 
         # otherwise create a composite client
         else:
-            self.transport = FastMCPTransport(
-                mcp=composite_server_from_mcp_config(
-                    self.config, name_as_prefix=name_as_prefix
+            name = FastMCP.generate_name("MCPRouter")
+            self._composite_server = FastMCP[Any](name=name)
+
+            for name, server, transport in mcp_config_to_servers_and_transports(
+                self.config
+            ):
+                self._underlying_transports.append(transport)
+                self._composite_server.mount(
+                    server, prefix=name if name_as_prefix else None
                 )
-            )
+
+            self.transport = FastMCPTransport(mcp=self._composite_server)
 
     @contextlib.asynccontextmanager
     async def connect_session(
@@ -859,6 +922,10 @@ class MCPConfigTransport(ClientTransport):
         async with self.transport.connect_session(**session_kwargs) as session:
             yield session
 
+    async def close(self):
+        for transport in self._underlying_transports:
+            await transport.close()
+
     def __repr__(self) -> str:
         return f"<MCPConfigTransport(config='{self.config}')>"
 
@@ -958,28 +1025,36 @@ def infer_transport(
 
     # the transport is a FastMCP server (2.x or 1.0)
     elif isinstance(transport, FastMCP | FastMCP1Server):
-        inferred_transport = FastMCPTransport(mcp=transport)
+        inferred_transport = FastMCPTransport(
+            mcp=cast(FastMCP[Any] | FastMCP1Server, transport)
+        )
 
     # the transport is a path to a script
     elif isinstance(transport, Path | str) and Path(transport).exists():
         if str(transport).endswith(".py"):
-            inferred_transport = PythonStdioTransport(script_path=transport)
+            inferred_transport = PythonStdioTransport(script_path=cast(Path, transport))
         elif str(transport).endswith(".js"):
-            inferred_transport = NodeStdioTransport(script_path=transport)
+            inferred_transport = NodeStdioTransport(script_path=cast(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"):
-        inferred_transport_type = infer_transport_type_from_url(transport)
+        inferred_transport_type = infer_transport_type_from_url(
+            cast(AnyUrl | str, transport)
+        )
         if inferred_transport_type == "sse":
-            inferred_transport = SSETransport(url=transport)
+            inferred_transport = SSETransport(url=cast(AnyUrl | str, transport))
         else:
-            inferred_transport = StreamableHttpTransport(url=transport)
+            inferred_transport = StreamableHttpTransport(
+                url=cast(AnyUrl | str, transport)
+            )
 
     # if the transport is a config dict or MCPConfig
     elif isinstance(transport, dict | MCPConfig):
-        inferred_transport = MCPConfigTransport(config=transport)
+        inferred_transport = MCPConfigTransport(
+            config=cast(dict | MCPConfig, transport)
+        )
 
     # the transport is an unknown type
     else:

fastmcp/experimental/sampling/handlers/__init__.py

@@ -0,0 +1,3 @@
+from .openai import OpenAISamplingHandler
+
+__all__ = ["OpenAISamplingHandler"]

fastmcp/experimental/sampling/handlers/base.py

@@ -0,0 +1,21 @@
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable
+
+from mcp import ClientSession, CreateMessageResult
+from mcp.server.session import ServerSession
+from mcp.shared.context import LifespanContextT, RequestContext
+from mcp.types import CreateMessageRequestParams as SamplingParams
+from mcp.types import (
+    SamplingMessage,
+)
+
+
+class BaseLLMSamplingHandler(ABC):
+    @abstractmethod
+    def __call__(
+        self,
+        messages: list[SamplingMessage],
+        params: SamplingParams,
+        context: RequestContext[ServerSession, LifespanContextT]
+        | RequestContext[ClientSession, LifespanContextT],
+    ) -> str | CreateMessageResult | Awaitable[str | CreateMessageResult]: ...

fastmcp/experimental/sampling/handlers/openai.py

@@ -0,0 +1,163 @@
+from collections.abc import Iterator, Sequence
+from typing import get_args
+
+from mcp import ClientSession, ServerSession
+from mcp.shared.context import LifespanContextT, RequestContext
+from mcp.types import CreateMessageRequestParams as SamplingParams
+from mcp.types import (
+    CreateMessageResult,
+    ModelPreferences,
+    SamplingMessage,
+    TextContent,
+)
+from openai import NOT_GIVEN, OpenAI
+from openai.types.chat import (
+    ChatCompletion,
+    ChatCompletionAssistantMessageParam,
+    ChatCompletionMessageParam,
+    ChatCompletionSystemMessageParam,
+    ChatCompletionUserMessageParam,
+)
+from openai.types.shared.chat_model import ChatModel
+from typing_extensions import override
+
+from fastmcp.experimental.sampling.handlers.base import BaseLLMSamplingHandler
+
+
+class OpenAISamplingHandler(BaseLLMSamplingHandler):
+    def __init__(self, default_model: ChatModel, client: OpenAI | None = None):
+        self.client: OpenAI = client or OpenAI()
+        self.default_model: ChatModel = default_model
+
+    @override
+    async def __call__(
+        self,
+        messages: list[SamplingMessage],
+        params: SamplingParams,
+        context: RequestContext[ServerSession, LifespanContextT]
+        | RequestContext[ClientSession, LifespanContextT],
+    ) -> CreateMessageResult:
+        openai_messages: list[ChatCompletionMessageParam] = (
+            self._convert_to_openai_messages(
+                system_prompt=params.systemPrompt,
+                messages=messages,
+            )
+        )
+
+        model: ChatModel = self._select_model_from_preferences(params.modelPreferences)
+
+        response = self.client.chat.completions.create(
+            model=model,
+            messages=openai_messages,
+            temperature=params.temperature or NOT_GIVEN,
+            max_tokens=params.maxTokens,
+            stop=params.stopSequences or NOT_GIVEN,
+        )
+
+        return self._chat_completion_to_create_message_result(response)
+
+    @staticmethod
+    def _iter_models_from_preferences(
+        model_preferences: ModelPreferences | str | list[str] | None,
+    ) -> Iterator[str]:
+        if model_preferences is None:
+            return
+
+        if isinstance(model_preferences, str) and model_preferences in get_args(
+            ChatModel
+        ):
+            yield model_preferences
+
+        if isinstance(model_preferences, list):
+            yield from model_preferences
+
+        if isinstance(model_preferences, ModelPreferences):
+            if not (hints := model_preferences.hints):
+                return
+
+            for hint in hints:
+                if not (name := hint.name):
+                    continue
+
+                yield name
+
+    @staticmethod
+    def _convert_to_openai_messages(
+        system_prompt: str | None, messages: Sequence[SamplingMessage]
+    ) -> list[ChatCompletionMessageParam]:
+        openai_messages: list[ChatCompletionMessageParam] = []
+
+        if system_prompt:
+            openai_messages.append(
+                ChatCompletionSystemMessageParam(
+                    role="system",
+                    content=system_prompt,
+                )
+            )
+
+        if isinstance(messages, str):
+            openai_messages.append(
+                ChatCompletionUserMessageParam(
+                    role="user",
+                    content=messages,
+                )
+            )
+
+        if isinstance(messages, list):
+            for message in messages:
+                if isinstance(message, str):
+                    openai_messages.append(
+                        ChatCompletionUserMessageParam(
+                            role="user",
+                            content=message,
+                        )
+                    )
+                    continue
+
+                if not isinstance(message.content, TextContent):
+                    raise ValueError("Only text content is supported")
+
+                if message.role == "user":
+                    openai_messages.append(
+                        ChatCompletionUserMessageParam(
+                            role="user",
+                            content=message.content.text,
+                        )
+                    )
+                else:
+                    openai_messages.append(
+                        ChatCompletionAssistantMessageParam(
+                            role="assistant",
+                            content=message.content.text,
+                        )
+                    )
+
+        return openai_messages
+
+    @staticmethod
+    def _chat_completion_to_create_message_result(
+        chat_completion: ChatCompletion,
+    ) -> CreateMessageResult:
+        if len(chat_completion.choices) == 0:
+            raise ValueError("No response for completion")
+
+        first_choice = chat_completion.choices[0]
+
+        if content := first_choice.message.content:
+            return CreateMessageResult(
+                content=TextContent(type="text", text=content),
+                role="assistant",
+                model=chat_completion.model,
+            )
+
+        raise ValueError("No content in response from completion")
+
+    def _select_model_from_preferences(
+        self, model_preferences: ModelPreferences | str | list[str] | None
+    ) -> ChatModel:
+        for model_option in self._iter_models_from_preferences(model_preferences):
+            if model_option in get_args(ChatModel):
+                chosen_model: ChatModel = model_option  # pyright: ignore[reportAssignmentType]
+                return chosen_model
+
+        return self.default_model

fastmcp/experimental/server/openapi/routing.py

@@ -110,8 +110,6 @@ def _determine_route_type(
                         # Tags don't match, continue to next mapping
                         continue
 
-                # We know mcp_type is not None here due to post_init validation
-                assert route_map.mcp_type is not None
                 logger.debug(
                     f"Route {route.method} {route.path} mapped to {route_map.mcp_type.name}"
                 )

fastmcp/experimental/server/openapi/server.py

@@ -163,8 +163,6 @@ class FastMCPOpenAPI(FastMCP):
             # Determine route type based on mappings or default rules
             route_map = _determine_route_type(route, route_maps)
 
-            # TODO: remove this once RouteType is removed and mcp_type is typed as MCPType without | None
-            assert route_map.mcp_type is not None
             route_type = route_map.mcp_type
 
             # Call route_map_fn if provided

fastmcp/experimental/utilities/openapi/parser.py

@@ -549,7 +549,11 @@ class OpenAPIParser(
                         return
 
                     # Add this schema and recursively find its dependencies
-                    if schema_name not in collected and schema_name in all_schemas:
+                    if (
+                        collected is not None
+                        and schema_name not in collected
+                        and schema_name in all_schemas
+                    ):
                         collected.add(schema_name)
                         # Recursively find dependencies of this schema
                         find_refs(all_schemas[schema_name])

fastmcp/mcp_config.py

@@ -27,7 +27,7 @@ from __future__ import annotations
 import datetime
 import re
 from pathlib import Path
-from typing import TYPE_CHECKING, Annotated, Any, Literal
+from typing import TYPE_CHECKING, Annotated, Any, Literal, cast
 from urllib.parse import urlparse
 
 import httpx
@@ -36,7 +36,6 @@ from pydantic import (
     BaseModel,
     ConfigDict,
     Field,
-    ValidationInfo,
     model_validator,
 )
 from typing_extensions import Self, override
@@ -47,11 +46,11 @@ from fastmcp.utilities.types import FastMCPBaseModel
 if TYPE_CHECKING:
     from fastmcp.client.transports import (
         ClientTransport,
-        FastMCPTransport,
         SSETransport,
         StdioTransport,
         StreamableHttpTransport,
     )
+    from fastmcp.server.server import FastMCP
 
 
 def infer_transport_type_from_url(
@@ -90,21 +89,38 @@ class _TransformingMCPServerMixin(FastMCPBaseModel):
         description="The tags to exclude in the proxy.",
     )
 
-    def to_transport(self) -> FastMCPTransport:
-        """Get the transport for the server."""
-        from fastmcp.client.transports import FastMCPTransport
-        from fastmcp.server.server import FastMCP
+    def _to_server_and_underlying_transport(
+        self,
+        server_name: str | None = None,
+        client_name: str | None = None,
+    ) -> tuple[FastMCP[Any], ClientTransport]:
+        """Turn the Transforming MCPServer into a FastMCP Server and also return the underlying transport."""
+        from fastmcp import FastMCP
+        from fastmcp.client import Client
+        from fastmcp.client.transports import (
+            ClientTransport,  # pyright: ignore[reportUnusedImport]
+        )
 
         transport: ClientTransport = super().to_transport()  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue, reportUnknownVariableType]
+        transport = cast(ClientTransport, transport)
+
+        client: Client[ClientTransport] = Client(transport=transport, name=client_name)
 
         wrapped_mcp_server = FastMCP.as_proxy(
-            transport,
+            name=server_name,
+            backend=client,
             tool_transformations=self.tools,
             include_tags=self.include_tags,
             exclude_tags=self.exclude_tags,
         )
 
-        return FastMCPTransport(wrapped_mcp_server)
+        return wrapped_mcp_server, transport
+
+    def to_transport(self) -> ClientTransport:
+        """Get the transport for the transforming MCP server."""
+        from fastmcp.client.transports import FastMCPTransport
+
+        return FastMCPTransport(mcp=self._to_server_and_underlying_transport()[0])
 
 
 class StdioMCPServer(BaseModel):
@@ -232,20 +248,24 @@ class MCPConfig(BaseModel):
     For an MCPConfig that is strictly canonical, see the `CanonicalMCPConfig` class.
     """
 
-    mcpServers: dict[str, MCPServerTypes]
+    mcpServers: dict[str, MCPServerTypes] = Field(default_factory=dict)
 
     model_config = ConfigDict(extra="allow")  # Preserve unknown top-level fields
 
     @model_validator(mode="before")
-    def validate_mcp_servers(self, info: ValidationInfo) -> dict[str, Any]:
-        """Validate the MCP servers."""
-        if not isinstance(self, dict):
-            raise ValueError("MCPConfig format requires a dictionary of servers.")
-
-        if "mcpServers" not in self:
-            self = {"mcpServers": self}
-
-        return self
+    @classmethod
+    def wrap_servers_at_root(cls, values: dict[str, Any]) -> dict[str, Any]:
+        """If there's no mcpServers key but there are server configs at root, wrap them."""
+        if "mcpServers" not in values:
+            # Check if any values look like server configs
+            has_servers = any(
+                isinstance(v, dict) and ("command" in v or "url" in v)
+                for v in values.values()
+            )
+            if has_servers:
+                # Move all server-like configs under mcpServers
+                return {"mcpServers": values}
+        return values
 
     def add_server(self, name: str, server: MCPServerTypes) -> None:
         """Add or update a server in the configuration."""
@@ -282,7 +302,7 @@ class CanonicalMCPConfig(MCPConfig):
     The format is designed to be client-agnostic and extensible for future use cases.
     """
 
-    mcpServers: dict[str, CanonicalMCPServerTypes]
+    mcpServers: dict[str, CanonicalMCPServerTypes] = Field(default_factory=dict)
 
     @override
     def add_server(self, name: str, server: CanonicalMCPServerTypes) -> None: