fastmcp 2.10.1__py3-none-any.whl → 2.10.3__py3-none-any.whl

fastmcp/server/proxy.py

@@ -1,9 +1,14 @@
 from __future__ import annotations
 
+import warnings
+from collections.abc import Callable
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
 from urllib.parse import quote
 
 import mcp.types
+from mcp.client.session import ClientSession
+from mcp.shared.context import LifespanContextT, RequestContext
 from mcp.shared.exceptions import McpError
 from mcp.types import (
     METHOD_NOT_FOUND,
@@ -13,14 +18,21 @@ from mcp.types import (
 )
 from pydantic.networks import AnyUrl
 
-from fastmcp.client import Client
+import fastmcp
+from fastmcp.client.client import Client, FastMCP1Server
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.client.logging import LogMessage
+from fastmcp.client.roots import RootsList
+from fastmcp.client.transports import ClientTransportT
 from fastmcp.exceptions import NotFoundError, ResourceError, ToolError
+from fastmcp.mcp_config import MCPConfig
 from fastmcp.prompts import Prompt, PromptMessage
 from fastmcp.prompts.prompt import PromptArgument
 from fastmcp.prompts.prompt_manager import PromptManager
 from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.resources.resource_manager import ResourceManager
 from fastmcp.server.context import Context
+from fastmcp.server.dependencies import get_context
 from fastmcp.server.server import FastMCP
 from fastmcp.tools.tool import Tool, ToolResult
 from fastmcp.tools.tool_manager import ToolManager
@@ -35,9 +47,9 @@ logger = get_logger(__name__)
 class ProxyToolManager(ToolManager):
     """A ToolManager that sources its tools from a remote client in addition to local and mounted tools."""
 
-    def __init__(self, client: Client, **kwargs):
+    def __init__(self, client_factory: Callable[[], Client], **kwargs):
         super().__init__(**kwargs)
-        self.client = client
+        self.client_factory = client_factory
 
     async def get_tools(self) -> dict[str, Tool]:
         """Gets the unfiltered tool inventory including local, mounted, and proxy tools."""
@@ -46,13 +58,12 @@ class ProxyToolManager(ToolManager):
 
         # Then add proxy tools, but don't overwrite existing ones
         try:
-            async with self.client:
-                client_tools = await self.client.list_tools()
+            client = self.client_factory()
+            async with client:
+                client_tools = await client.list_tools()
                 for tool in client_tools:
                     if tool.name not in all_tools:
-                        all_tools[tool.name] = ProxyTool.from_mcp_tool(
-                            self.client, tool
-                        )
+                        all_tools[tool.name] = ProxyTool.from_mcp_tool(client, tool)
         except McpError as e:
             if e.error.code == METHOD_NOT_FOUND:
                 pass  # No tools available from proxy
@@ -73,8 +84,9 @@ class ProxyToolManager(ToolManager):
             return await super().call_tool(key, arguments)
         except NotFoundError:
             # If not found locally, try proxy
-            async with self.client:
-                result = await self.client.call_tool(key, arguments)
+            client = self.client_factory()
+            async with client:
+                result = await client.call_tool(key, arguments)
                 return ToolResult(
                     content=result.content,
                     structured_content=result.structured_content,
@@ -84,9 +96,9 @@ class ProxyToolManager(ToolManager):
 class ProxyResourceManager(ResourceManager):
     """A ResourceManager that sources its resources from a remote client in addition to local and mounted resources."""
 
-    def __init__(self, client: Client, **kwargs):
+    def __init__(self, client_factory: Callable[[], Client], **kwargs):
         super().__init__(**kwargs)
-        self.client = client
+        self.client_factory = client_factory
 
     async def get_resources(self) -> dict[str, Resource]:
         """Gets the unfiltered resource inventory including local, mounted, and proxy resources."""
@@ -95,12 +107,13 @@ class ProxyResourceManager(ResourceManager):
 
         # Then add proxy resources, but don't overwrite existing ones
         try:
-            async with self.client:
-                client_resources = await self.client.list_resources()
+            client = self.client_factory()
+            async with client:
+                client_resources = await client.list_resources()
                 for resource in client_resources:
                     if str(resource.uri) not in all_resources:
                         all_resources[str(resource.uri)] = (
-                            ProxyResource.from_mcp_resource(self.client, resource)
+                            ProxyResource.from_mcp_resource(client, resource)
                         )
         except McpError as e:
             if e.error.code == METHOD_NOT_FOUND:
@@ -117,12 +130,13 @@ class ProxyResourceManager(ResourceManager):
 
         # Then add proxy templates, but don't overwrite existing ones
         try:
-            async with self.client:
-                client_templates = await self.client.list_resource_templates()
+            client = self.client_factory()
+            async with client:
+                client_templates = await client.list_resource_templates()
                 for template in client_templates:
                     if template.uriTemplate not in all_templates:
                         all_templates[template.uriTemplate] = (
-                            ProxyTemplate.from_mcp_template(self.client, template)
+                            ProxyTemplate.from_mcp_template(client, template)
                         )
         except McpError as e:
             if e.error.code == METHOD_NOT_FOUND:
@@ -149,8 +163,9 @@ class ProxyResourceManager(ResourceManager):
             return await super().read_resource(uri)
         except NotFoundError:
             # If not found locally, try proxy
-            async with self.client:
-                result = await self.client.read_resource(uri)
+            client = self.client_factory()
+            async with client:
+                result = await client.read_resource(uri)
                 if isinstance(result[0], TextResourceContents):
                     return result[0].text
                 elif isinstance(result[0], BlobResourceContents):
@@ -162,9 +177,9 @@ class ProxyResourceManager(ResourceManager):
 class ProxyPromptManager(PromptManager):
     """A PromptManager that sources its prompts from a remote client in addition to local and mounted prompts."""
 
-    def __init__(self, client: Client, **kwargs):
+    def __init__(self, client_factory: Callable[[], Client], **kwargs):
         super().__init__(**kwargs)
-        self.client = client
+        self.client_factory = client_factory
 
     async def get_prompts(self) -> dict[str, Prompt]:
         """Gets the unfiltered prompt inventory including local, mounted, and proxy prompts."""
@@ -173,12 +188,13 @@ class ProxyPromptManager(PromptManager):
 
         # Then add proxy prompts, but don't overwrite existing ones
         try:
-            async with self.client:
-                client_prompts = await self.client.list_prompts()
+            client = self.client_factory()
+            async with client:
+                client_prompts = await client.list_prompts()
                 for prompt in client_prompts:
                     if prompt.name not in all_prompts:
                         all_prompts[prompt.name] = ProxyPrompt.from_mcp_prompt(
-                            self.client, prompt
+                            client, prompt
                         )
         except McpError as e:
             if e.error.code == METHOD_NOT_FOUND:
@@ -204,8 +220,9 @@ class ProxyPromptManager(PromptManager):
             return await super().render_prompt(name, arguments)
         except NotFoundError:
             # If not found locally, try proxy
-            async with self.client:
-                result = await self.client.get_prompt(name, arguments)
+            client = self.client_factory()
+            async with client:
+                result = await client.get_prompt(name, arguments)
                 return result
 
 
@@ -236,7 +253,6 @@ class ProxyTool(Tool):
         context: Context | None = None,
     ) -> ToolResult:
         """Executes the tool by making a call through the client."""
-        # This is where the remote execution logic lives.
         async with self._client:
             result = await self._client.call_tool_mcp(
                 name=self.name,
@@ -258,14 +274,22 @@ class ProxyResource(Resource):
     _client: Client
     _value: str | bytes | None = None
 
-    def __init__(self, client: Client, *, _value: str | bytes | None = None, **kwargs):
+    def __init__(
+        self,
+        client: Client,
+        *,
+        _value: str | bytes | None = None,
+        **kwargs,
+    ):
         super().__init__(**kwargs)
         self._client = client
         self._value = _value
 
     @classmethod
     def from_mcp_resource(
-        cls, client: Client, mcp_resource: mcp.types.Resource
+        cls,
+        client: Client,
+        mcp_resource: mcp.types.Resource,
     ) -> ProxyResource:
         """Factory method to create a ProxyResource from a raw MCP resource schema."""
         return cls(
@@ -388,21 +412,166 @@ class ProxyPrompt(Prompt):
 class FastMCPProxy(FastMCP):
     """
     A FastMCP server that acts as a proxy to a remote MCP-compliant server.
-    It uses specialized managers that fulfill requests via an HTTP client.
+    It uses specialized managers that fulfill requests via a client factory.
     """
 
-    def __init__(self, client: Client, **kwargs):
+    def __init__(
+        self,
+        client: Client | None = None,
+        *,
+        client_factory: Callable[[], Client] | None = None,
+        **kwargs,
+    ):
         """
         Initializes the proxy server.
 
+        FastMCPProxy requires explicit session management via client_factory.
+        Use FastMCP.as_proxy() for convenience with automatic session strategy.
+
         Args:
-            client: The FastMCP client connected to the backend server.
+            client: [DEPRECATED] A Client instance. Use client_factory instead for explicit
+                   session management. When provided, a client_factory will be automatically
+                   created that provides session isolation for backwards compatibility.
+            client_factory: A callable that returns a Client instance when called.
+                           This gives you full control over session creation and reuse.
             **kwargs: Additional settings for the FastMCP server.
         """
+
         super().__init__(**kwargs)
-        self.client = client
+
+        # Handle client and client_factory parameters
+        if client is not None and client_factory is not None:
+            raise ValueError("Cannot specify both 'client' and 'client_factory'")
+
+        if client is not None:
+            # Deprecated in 2.10.3
+            if fastmcp.settings.deprecation_warnings:
+                warnings.warn(
+                    "Passing 'client' to FastMCPProxy is deprecated. Use 'client_factory' instead for explicit session management. "
+                    "For automatic session strategy, use FastMCP.as_proxy().",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+
+            # Create a factory that provides session isolation for backwards compatibility
+            def deprecated_client_factory():
+                return client.new()
+
+            self.client_factory = deprecated_client_factory
+        elif client_factory is not None:
+            self.client_factory = client_factory
+        else:
+            raise ValueError("Must specify 'client_factory'")
 
         # Replace the default managers with our specialized proxy managers.
-        self._tool_manager = ProxyToolManager(client=self.client)
-        self._resource_manager = ProxyResourceManager(client=self.client)
-        self._prompt_manager = ProxyPromptManager(client=self.client)
+        self._tool_manager = ProxyToolManager(client_factory=self.client_factory)
+        self._resource_manager = ProxyResourceManager(
+            client_factory=self.client_factory
+        )
+        self._prompt_manager = ProxyPromptManager(client_factory=self.client_factory)
+
+
+async def default_proxy_roots_handler(
+    context: RequestContext[ClientSession, LifespanContextT],
+) -> RootsList:
+    """
+    A handler that forwards the list roots request from the remote server to the proxy's connected clients and relays the response back to the remote server.
+    """
+    ctx = get_context()
+    return await ctx.list_roots()
+
+
+class ProxyClient(Client[ClientTransportT]):
+    """
+    A proxy client that forwards advanced interactions between a remote MCP server and the proxy's connected clients.
+    Supports forwarding roots, sampling, elicitation, logging, and progress.
+    """
+
+    def __init__(
+        self,
+        transport: ClientTransportT
+        | FastMCP
+        | FastMCP1Server
+        | AnyUrl
+        | Path
+        | MCPConfig
+        | dict[str, Any]
+        | str,
+        **kwargs,
+    ):
+        if "roots" not in kwargs:
+            kwargs["roots"] = default_proxy_roots_handler
+        if "sampling_handler" not in kwargs:
+            kwargs["sampling_handler"] = ProxyClient.default_sampling_handler
+        if "elicitation_handler" not in kwargs:
+            kwargs["elicitation_handler"] = ProxyClient.default_elicitation_handler
+        if "log_handler" not in kwargs:
+            kwargs["log_handler"] = ProxyClient.default_log_handler
+        if "progress_handler" not in kwargs:
+            kwargs["progress_handler"] = ProxyClient.default_progress_handler
+        super().__init__(**kwargs | dict(transport=transport))
+
+    @classmethod
+    async def default_sampling_handler(
+        cls,
+        messages: list[mcp.types.SamplingMessage],
+        params: mcp.types.CreateMessageRequestParams,
+        context: RequestContext[ClientSession, LifespanContextT],
+    ) -> mcp.types.CreateMessageResult:
+        """
+        A handler that forwards the sampling request from the remote server to the proxy's connected clients and relays the response back to the remote server.
+        """
+        ctx = get_context()
+        content = await ctx.sample(
+            [msg for msg in messages],
+            system_prompt=params.systemPrompt,
+            temperature=params.temperature,
+            max_tokens=params.maxTokens,
+            model_preferences=params.modelPreferences,
+        )
+        if isinstance(content, mcp.types.ResourceLink | mcp.types.EmbeddedResource):
+            raise RuntimeError("Content is not supported")
+        return mcp.types.CreateMessageResult(
+            role="assistant",
+            model="fastmcp-client",
+            content=content,
+        )
+
+    @classmethod
+    async def default_elicitation_handler(
+        cls,
+        message: str,
+        response_type: type,
+        params: mcp.types.ElicitRequestParams,
+        context: RequestContext[ClientSession, LifespanContextT],
+    ) -> ElicitResult:
+        """
+        A handler that forwards the elicitation request from the remote server to the proxy's connected clients and relays the response back to the remote server.
+        """
+        ctx = get_context()
+        result = await ctx.elicit(message, response_type)
+        if result.action == "accept":
+            return result.data
+        else:
+            return ElicitResult(action=result.action)
+
+    @classmethod
+    async def default_log_handler(cls, message: LogMessage) -> None:
+        """
+        A handler that forwards the log notification from the remote server to the proxy's connected clients.
+        """
+        ctx = get_context()
+        await ctx.log(message.data, level=message.level, logger_name=message.logger)
+
+    @classmethod
+    async def default_progress_handler(
+        cls,
+        progress: float,
+        total: float | None,
+        message: str | None,
+    ) -> None:
+        """
+        A handler that forwards the progress notification from the remote server to the proxy's connected clients.
+        """
+        ctx = get_context()
+        await ctx.report_progress(progress, total, message)

fastmcp/server/server.py

@@ -43,6 +43,7 @@ from starlette.routing import BaseRoute, Route
 import fastmcp
 import fastmcp.server
 from fastmcp.exceptions import DisabledError, NotFoundError
+from fastmcp.mcp_config import MCPConfig
 from fastmcp.prompts import Prompt, PromptManager
 from fastmcp.prompts.prompt import FunctionPrompt
 from fastmcp.resources import Resource, ResourceManager
@@ -60,9 +61,9 @@ from fastmcp.settings import Settings
 from fastmcp.tools import ToolManager
 from fastmcp.tools.tool import FunctionTool, Tool, ToolResult
 from fastmcp.utilities.cache import TimedCache
+from fastmcp.utilities.cli import log_server_banner
 from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.logging import get_logger
-from fastmcp.utilities.mcp_config import MCPConfig
 from fastmcp.utilities.types import NotSet, NotSetT
 
 if TYPE_CHECKING:
@@ -285,6 +286,7 @@ class FastMCP(Generic[LifespanResultT]):
     async def run_async(
         self,
         transport: Transport | None = None,
+        show_banner: bool = True,
         **transport_kwargs: Any,
     ) -> None:
         """Run the FastMCP server asynchronously.
@@ -298,15 +300,23 @@ class FastMCP(Generic[LifespanResultT]):
             raise ValueError(f"Unknown transport: {transport}")
 
         if transport == "stdio":
-            await self.run_stdio_async(**transport_kwargs)
+            await self.run_stdio_async(
+                show_banner=show_banner,
+                **transport_kwargs,
+            )
         elif transport in {"http", "sse", "streamable-http"}:
-            await self.run_http_async(transport=transport, **transport_kwargs)
+            await self.run_http_async(
+                transport=transport,
+                show_banner=show_banner,
+                **transport_kwargs,
+            )
         else:
             raise ValueError(f"Unknown transport: {transport}")
 
     def run(
         self,
         transport: Transport | None = None,
+        show_banner: bool = True,
         **transport_kwargs: Any,
     ) -> None:
         """Run the FastMCP server. Note this is a synchronous function.
@@ -315,7 +325,14 @@ class FastMCP(Generic[LifespanResultT]):
             transport: Transport protocol to use ("stdio", "sse", or "streamable-http")
         """
 
-        anyio.run(partial(self.run_async, transport, **transport_kwargs))
+        anyio.run(
+            partial(
+                self.run_async,
+                transport,
+                show_banner=show_banner,
+                **transport_kwargs,
+            )
+        )
 
     def _setup_handlers(self) -> None:
         """Set up core MCP protocol handlers."""
@@ -1321,8 +1338,16 @@ class FastMCP(Generic[LifespanResultT]):
             enabled=enabled,
         )
 
-    async def run_stdio_async(self) -> None:
+    async def run_stdio_async(self, show_banner: bool = True) -> None:
         """Run the server using stdio transport."""
+
+        # Display server banner
+        if show_banner:
+            log_server_banner(
+                server=self,
+                transport="stdio",
+            )
+
         async with stdio_server() as (read_stream, write_stream):
             logger.info(f"Starting MCP server {self.name!r} with transport 'stdio'")
             await self._mcp_server.run(
@@ -1335,6 +1360,7 @@ class FastMCP(Generic[LifespanResultT]):
 
     async def run_http_async(
         self,
+        show_banner: bool = True,
         transport: Literal["http", "streamable-http", "sse"] = "http",
         host: str | None = None,
         port: int | None = None,
@@ -1342,6 +1368,7 @@ class FastMCP(Generic[LifespanResultT]):
         path: str | None = None,
         uvicorn_config: dict[str, Any] | None = None,
         middleware: list[ASGIMiddleware] | None = None,
+        stateless_http: bool | None = None,
     ) -> None:
         """Run the server using HTTP transport.
 
@@ -1352,15 +1379,39 @@ class FastMCP(Generic[LifespanResultT]):
             log_level: Log level for the server (defaults to settings.log_level)
             path: Path for the endpoint (defaults to settings.streamable_http_path or settings.sse_path)
             uvicorn_config: Additional configuration for the Uvicorn server
+            middleware: A list of middleware to apply to the app
+            stateless_http: Whether to use stateless HTTP (defaults to settings.stateless_http)
         """
+
         host = host or self._deprecated_settings.host
         port = port or self._deprecated_settings.port
         default_log_level_to_use = (
             log_level or self._deprecated_settings.log_level
         ).lower()
 
-        app = self.http_app(path=path, transport=transport, middleware=middleware)
+        app = self.http_app(
+            path=path,
+            transport=transport,
+            middleware=middleware,
+            stateless_http=stateless_http,
+        )
+
+        # Get the path for the server URL
+        server_path = (
+            app.state.path.lstrip("/")
+            if hasattr(app, "state") and hasattr(app.state, "path")
+            else path or ""
+        )
 
+        # Display server banner
+        if show_banner:
+            log_server_banner(
+                server=self,
+                transport=transport,
+                host=host,
+                port=port,
+                path=server_path,
+            )
         _uvicorn_config_from_user = uvicorn_config or {}
 
         config_kwargs: dict[str, Any] = {
@@ -1378,6 +1429,7 @@ class FastMCP(Generic[LifespanResultT]):
         logger.info(
             f"Starting MCP server {self.name!r} with transport {transport!r} on http://{host}:{port}/{path}"
         )
+
         await server.serve()
 
     async def run_sse_async(
@@ -1591,9 +1643,8 @@ class FastMCP(Generic[LifespanResultT]):
             resource_separator: Deprecated. Separator character for resource URIs.
             prompt_separator: Deprecated. Separator character for prompt names.
         """
-        from fastmcp import Client
         from fastmcp.client.transports import FastMCPTransport
-        from fastmcp.server.proxy import FastMCPProxy
+        from fastmcp.server.proxy import FastMCPProxy, ProxyClient
 
         # Deprecated since 2.9.0
         # Prior to 2.9.0, the first positional argument was the prefix and the
@@ -1645,7 +1696,7 @@ class FastMCP(Generic[LifespanResultT]):
             as_proxy = server._has_lifespan
 
         if as_proxy and not isinstance(server, FastMCPProxy):
-            server = FastMCPProxy(Client(transport=FastMCPTransport(server)))
+            server = FastMCPProxy(ProxyClient(transport=FastMCPTransport(server)))
 
         # Delegate mounting to all three managers
         mounted_server = MountedServer(
@@ -1856,14 +1907,16 @@ class FastMCP(Generic[LifespanResultT]):
     @classmethod
     def as_proxy(
         cls,
-        backend: Client[ClientTransportT]
-        | ClientTransport
-        | FastMCP[Any]
-        | AnyUrl
-        | Path
-        | MCPConfig
-        | dict[str, Any]
-        | str,
+        backend: (
+            Client[ClientTransportT]
+            | ClientTransport
+            | FastMCP[Any]
+            | AnyUrl
+            | Path
+            | MCPConfig
+            | dict[str, Any]
+            | str
+        ),
         **settings: Any,
     ) -> FastMCPProxy:
         """Create a FastMCP proxy server for the given backend.
@@ -1874,14 +1927,43 @@ class FastMCP(Generic[LifespanResultT]):
         `fastmcp.client.Client` constructor.
         """
         from fastmcp.client.client import Client
-        from fastmcp.server.proxy import FastMCPProxy
+        from fastmcp.server.proxy import FastMCPProxy, ProxyClient
 
         if isinstance(backend, Client):
             client = backend
+            # Session strategy based on client connection state:
+            # - Connected clients: reuse existing session for all requests
+            # - Disconnected clients: create fresh sessions per request for isolation
+            if client.is_connected():
+                from fastmcp.utilities.logging import get_logger
+
+                logger = get_logger(__name__)
+                logger.info(
+                    "Proxy detected connected client - reusing existing session for all requests. "
+                    "This may cause context mixing in concurrent scenarios."
+                )
+
+                # Reuse sessions - return the same client instance
+                def reuse_client_factory():
+                    return client
+
+                client_factory = reuse_client_factory
+            else:
+                # Fresh sessions per request
+                def fresh_client_factory():
+                    return client.new()
+
+                client_factory = fresh_client_factory
         else:
-            client = Client(backend)
+            base_client = ProxyClient(backend)
+
+            # Fresh client created from transport - use fresh sessions per request
+            def proxy_client_factory():
+                return base_client.new()
+
+            client_factory = proxy_client_factory
 
-        return FastMCPProxy(client=client, **settings)
+        return FastMCPProxy(client_factory=client_factory, **settings)
 
     @classmethod
     def from_client(

fastmcp/settings.py

@@ -1,6 +1,7 @@
 from __future__ import annotations as _annotations
 
 import inspect
+import warnings
 from pathlib import Path
 from typing import Annotated, Any, Literal
 
@@ -258,4 +259,21 @@ class Settings(BaseSettings):
     ] = None
 
 
-settings = Settings()
+def __getattr__(name: str):
+    """
+    Used to deprecate the module-level Image class; can be removed once it is no longer imported to root.
+    """
+    if name == "settings":
+        import fastmcp
+
+        settings = fastmcp.settings
+        # Deprecated in 2.10.2
+        if settings.deprecation_warnings:
+            warnings.warn(
+                "`from fastmcp.settings import settings` is deprecated. use `fasmtpc.settings` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return settings
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

fastmcp/tools/tool.py

@@ -46,7 +46,7 @@ class _UnserializableType:
 
 
 def default_serializer(data: Any) -> str:
-    return pydantic_core.to_json(data, fallback=str, indent=2).decode()
+    return pydantic_core.to_json(data, fallback=str).decode()
 
 
 class ToolResult:
@@ -434,6 +434,7 @@ def _convert_to_content(
     _process_as_single_item: bool = False,
 ) -> list[ContentBlock]:
     """Convert a result to a sequence of content objects."""
+
     if result is None:
         return []
 
@@ -467,7 +468,7 @@ def _convert_to_content(
 
         if other_content:
             other_content = _convert_to_content(
-                other_content[0] if len(other_content) == 1 else other_content,
+                other_content,
                 serializer=serializer,
                 _process_as_single_item=True,
             )