fastmcp 2.13.3__py3-none-any.whl → 2.14.1__py3-none-any.whl

fastmcp/server/low_level.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Any
 import anyio
 import mcp.types
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from mcp import McpError
 from mcp.server.lowlevel.server import (
     LifespanResultT,
     NotificationOptions,
@@ -35,6 +36,8 @@ class MiddlewareServerSession(ServerSession):
     def __init__(self, fastmcp: FastMCP, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self._fastmcp_ref: weakref.ref[FastMCP] = weakref.ref(fastmcp)
+        # Task group for subscription tasks (set during session run)
+        self._subscription_task_group: anyio.TaskGroup | None = None  # type: ignore[valid-type]
 
     @property
     def fastmcp(self) -> FastMCP:
@@ -49,23 +52,46 @@ class MiddlewareServerSession(ServerSession):
         responder: RequestResponder[mcp.types.ClientRequest, mcp.types.ServerResult],
     ):
         """
-        Override the _received_request method to route initialization requests
+        Override the _received_request method to route special requests
         through FastMCP middleware.
 
-        These are not handled by routes that FastMCP typically overrides and
-        require special handling.
+        Handles initialization requests and SEP-1686 task methods.
         """
         import fastmcp.server.context
         from fastmcp.server.middleware.middleware import MiddlewareContext
 
         if isinstance(responder.request.root, mcp.types.InitializeRequest):
+            # The MCP SDK's ServerSession._received_request() handles the
+            # initialize request internally by calling responder.respond()
+            # to send the InitializeResult directly to the write stream, then
+            # returning None. This bypasses the middleware return path entirely,
+            # so middleware would only see the request, never the response.
+            #
+            # To expose the response to middleware (e.g., for logging server
+            # capabilities), we wrap responder.respond() to capture the
+            # InitializeResult before it's sent, then return it from
+            # call_original_handler so it flows back through the middleware chain.
+            captured_response: mcp.types.ServerResult | None = None
+            original_respond = responder.respond
+
+            async def capturing_respond(
+                response: mcp.types.ServerResult,
+            ) -> None:
+                nonlocal captured_response
+                captured_response = response
+                return await original_respond(response)
+
+            responder.respond = capturing_respond  # type: ignore[method-assign]
 
             async def call_original_handler(
                 ctx: MiddlewareContext,
-            ) -> None:
-                return await super(MiddlewareServerSession, self)._received_request(
-                    responder
-                )
+            ) -> mcp.types.InitializeResult | None:
+                await super(MiddlewareServerSession, self)._received_request(responder)
+                if captured_response is not None and isinstance(
+                    captured_response.root, mcp.types.InitializeResult
+                ):
+                    return captured_response.root
+                return None
 
             async with fastmcp.server.context.Context(
                 fastmcp=self.fastmcp
@@ -79,11 +105,26 @@ class MiddlewareServerSession(ServerSession):
                     fastmcp_context=fastmcp_ctx,
                 )
 
-                return await self.fastmcp._apply_middleware(
-                    mw_context, call_original_handler
-                )
-        else:
-            return await super()._received_request(responder)
+                try:
+                    return await self.fastmcp._apply_middleware(
+                        mw_context, call_original_handler
+                    )
+                except McpError as e:
+                    # McpError can be thrown from middleware in `on_initialize`
+                    # send the error to responder.
+                    if not responder._completed:
+                        with responder:
+                            await responder.respond(e.error)
+                    else:
+                        # Don't re-raise: prevents responding to initialize request twice
+                        logger.warning(
+                            "Received McpError but responder is already completed. "
+                            "Cannot send error response as response was already sent.",
+                            exc_info=e,
+                        )
+
+        # Fall through to default handling (task methods now handled via registered handlers)
+        return await super()._received_request(responder)
 
 
 class LowLevelServer(_Server[LifespanResultT, RequestT]):
@@ -146,6 +187,9 @@ class LowLevelServer(_Server[LifespanResultT, RequestT]):
             )
 
             async with anyio.create_task_group() as tg:
+                # Store task group on session for subscription tasks (SEP-1686)
+                session._subscription_task_group = tg
+
                 async for message in session.incoming_messages:
                     tg.start_soon(
                         self._handle_message,

fastmcp/server/middleware/middleware.py

@@ -150,8 +150,8 @@ class Middleware:
     async def on_initialize(
         self,
         context: MiddlewareContext[mt.InitializeRequest],
-        call_next: CallNext[mt.InitializeRequest, None],
-    ) -> None:
+        call_next: CallNext[mt.InitializeRequest, mt.InitializeResult | None],
+    ) -> mt.InitializeResult | None:
         return await call_next(context)
 
     async def on_call_tool(

fastmcp/server/openapi/__init__.py

@@ -0,0 +1,35 @@
+"""OpenAPI server implementation for FastMCP - refactored for better maintainability."""
+
+# Import from server
+from .server import FastMCPOpenAPI
+
+# Import from routing
+from .routing import (
+    MCPType,
+    RouteMap,
+    RouteMapFn,
+    ComponentFn,
+    DEFAULT_ROUTE_MAPPINGS,
+    _determine_route_type,
+)
+
+# Import from components
+from .components import (
+    OpenAPITool,
+    OpenAPIResource,
+    OpenAPIResourceTemplate,
+)
+
+# Export public symbols - maintaining backward compatibility
+__all__ = [
+    "DEFAULT_ROUTE_MAPPINGS",
+    "ComponentFn",
+    "FastMCPOpenAPI",
+    "MCPType",
+    "OpenAPIResource",
+    "OpenAPIResourceTemplate",
+    "OpenAPITool",
+    "RouteMap",
+    "RouteMapFn",
+    "_determine_route_type",
+]

fastmcp/{experimental/server → server}/openapi/components.py

@@ -9,14 +9,15 @@ import httpx
 from mcp.types import ToolAnnotations
 from pydantic.networks import AnyUrl
 
-# Import from our new utilities
-from fastmcp.experimental.utilities.openapi import HTTPRoute
-from fastmcp.experimental.utilities.openapi.director import RequestDirector
 from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.server.dependencies import get_http_headers
 from fastmcp.tools.tool import Tool, ToolResult
 from fastmcp.utilities.logging import get_logger
 
+# Import from our new utilities
+from fastmcp.utilities.openapi import HTTPRoute
+from fastmcp.utilities.openapi.director import RequestDirector
+
 if TYPE_CHECKING:
     from fastmcp.server import Context
 

fastmcp/{experimental/server → server}/openapi/routing.py

@@ -14,8 +14,8 @@ if TYPE_CHECKING:
         OpenAPITool,
     )
 # Import from our new utilities
-from fastmcp.experimental.utilities.openapi import HttpMethod, HTTPRoute
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.openapi import HttpMethod, HTTPRoute
 
 logger = get_logger(__name__)
 

fastmcp/{experimental/server → server}/openapi/server.py

@@ -7,16 +7,17 @@ from typing import Any, Literal
 import httpx
 from jsonschema_path import SchemaPath
 
+from fastmcp.server.server import FastMCP
+from fastmcp.utilities.logging import get_logger
+
 # Import from our new utilities and components
-from fastmcp.experimental.utilities.openapi import (
+from fastmcp.utilities.openapi import (
     HTTPRoute,
     extract_output_schema_from_responses,
     format_simple_description,
     parse_openapi_to_http_routes,
 )
-from fastmcp.experimental.utilities.openapi.director import RequestDirector
-from fastmcp.server.server import FastMCP
-from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.openapi.director import RequestDirector
 
 from .components import (
     OpenAPIResource,
@@ -247,7 +248,7 @@ class FastMCPOpenAPI(FastMCP):
             # Create the new name
             new_name = f"{name}_{self._used_names[component_type][name]}"
             logger.debug(
-                f"Name collision detected: '{name}' already exists as a {component_type[:-1]}. "
+                f"Name collision detected: '{name}' already exists as a {component_type}. "
                 f"Using '{new_name}' instead."
             )
 

fastmcp/server/proxy.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import inspect
-import warnings
 from collections.abc import Awaitable, Callable
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
@@ -15,12 +14,12 @@ from mcp.shared.exceptions import McpError
 from mcp.types import (
     METHOD_NOT_FOUND,
     BlobResourceContents,
+    ElicitRequestFormParams,
     GetPromptResult,
     TextResourceContents,
 )
 from pydantic.networks import AnyUrl
 
-import fastmcp
 from fastmcp.client.client import Client, FastMCP1Server
 from fastmcp.client.elicitation import ElicitResult
 from fastmcp.client.logging import LogMessage
@@ -36,6 +35,7 @@ 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.server.tasks.config import TaskConfig
 from fastmcp.tools.tool import Tool, ToolResult
 from fastmcp.tools.tool_manager import ToolManager
 from fastmcp.tools.tool_transform import (
@@ -117,6 +117,7 @@ class ProxyToolManager(ToolManager, ProxyManagerMixin):
                 return ToolResult(
                     content=result.content,
                     structured_content=result.structured_content,
+                    meta=result.meta,
                 )
 
 
@@ -260,6 +261,8 @@ class ProxyTool(Tool, MirroredComponent):
     A Tool that represents and executes a tool on a remote server.
     """
 
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
+
     def __init__(self, client: Client, **kwargs: Any):
         super().__init__(**kwargs)
         self._client = client
@@ -288,15 +291,37 @@ class ProxyTool(Tool, MirroredComponent):
     ) -> ToolResult:
         """Executes the tool by making a call through the client."""
         async with self._client:
+            context = get_context()
+            # Build meta dict from request context
+            meta: dict[str, Any] | None = None
+            if hasattr(context, "request_context"):
+                req_ctx = context.request_context
+                # Start with existing meta if present
+                if hasattr(req_ctx, "meta") and req_ctx.meta:
+                    meta = dict(req_ctx.meta)
+                # Add task metadata if this is a task request
+                if (
+                    hasattr(req_ctx, "experimental")
+                    and hasattr(req_ctx.experimental, "is_task")
+                    and req_ctx.experimental.is_task
+                ):
+                    task_metadata = req_ctx.experimental.task_metadata
+                    if task_metadata:
+                        meta = meta or {}
+                        meta["modelcontextprotocol.io/task"] = task_metadata.model_dump(
+                            exclude_none=True
+                        )
+
             result = await self._client.call_tool_mcp(
-                name=self.name,
-                arguments=arguments,
+                name=self.name, arguments=arguments, meta=meta
             )
         if result.isError:
             raise ToolError(cast(mcp.types.TextContent, result.content[0]).text)
+        # Preserve backend's meta (includes task metadata for background tasks)
         return ToolResult(
             content=result.content,
             structured_content=result.structuredContent,
+            meta=result.meta,
         )
 
 
@@ -305,6 +330,7 @@ class ProxyResource(Resource, MirroredComponent):
     A Resource that represents and reads a resource from a remote server.
     """
 
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
     _client: Client
     _value: str | bytes | None = None
 
@@ -337,6 +363,7 @@ class ProxyResource(Resource, MirroredComponent):
             icons=mcp_resource.icons,
             meta=mcp_resource.meta,
             tags=(mcp_resource.meta or {}).get("_fastmcp", {}).get("tags", []),
+            task_config=TaskConfig(mode="forbidden"),
             _mirrored=True,
         )
 
@@ -360,12 +387,14 @@ class ProxyTemplate(ResourceTemplate, MirroredComponent):
     A ResourceTemplate that represents and creates resources from a remote server template.
     """
 
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
+
     def __init__(self, client: Client, **kwargs: Any):
         super().__init__(**kwargs)
         self._client = client
 
     @classmethod
-    def from_mcp_template(
+    def from_mcp_template(  # type: ignore[override]
         cls, client: Client, mcp_template: mcp.types.ResourceTemplate
     ) -> ProxyTemplate:
         """Factory method to create a ProxyTemplate from a raw MCP template schema."""
@@ -380,6 +409,7 @@ class ProxyTemplate(ResourceTemplate, MirroredComponent):
             parameters={},  # Remote templates don't have local parameters
             meta=mcp_template.meta,
             tags=(mcp_template.meta or {}).get("_fastmcp", {}).get("tags", []),
+            task_config=TaskConfig(mode="forbidden"),
             _mirrored=True,
         )
 
@@ -425,6 +455,7 @@ class ProxyPrompt(Prompt, MirroredComponent):
     A Prompt that represents and renders a prompt from a remote server.
     """
 
+    task_config: TaskConfig = TaskConfig(mode="forbidden")
     _client: Client
 
     def __init__(self, client: Client, **kwargs):
@@ -453,10 +484,11 @@ class ProxyPrompt(Prompt, MirroredComponent):
             icons=mcp_prompt.icons,
             meta=mcp_prompt.meta,
             tags=(mcp_prompt.meta or {}).get("_fastmcp", {}).get("tags", []),
+            task_config=TaskConfig(mode="forbidden"),
             _mirrored=True,
         )
 
-    async def render(self, arguments: dict[str, Any]) -> list[PromptMessage]:
+    async def render(self, arguments: dict[str, Any]) -> list[PromptMessage]:  # type: ignore[override]
         """Render the prompt by making a call through the client."""
         async with self._client:
             result = await self._client.get_prompt(self.name, arguments)
@@ -471,9 +503,8 @@ class FastMCPProxy(FastMCP):
 
     def __init__(
         self,
-        client: Client | None = None,
         *,
-        client_factory: ClientFactoryT | None = None,
+        client_factory: ClientFactoryT,
         **kwargs,
     ):
         """
@@ -483,9 +514,6 @@ class FastMCPProxy(FastMCP):
         Use FastMCP.as_proxy() for convenience with automatic session strategy.
 
         Args:
-            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.
                            Can be either a synchronous or asynchronous function.
@@ -494,29 +522,7 @@ class FastMCPProxy(FastMCP):
 
         super().__init__(**kwargs)
 
-        # 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'")
+        self.client_factory = client_factory
 
         # Replace the default managers with our specialized proxy managers.
         self._tool_manager = ProxyToolManager(
@@ -583,19 +589,20 @@ class ProxyClient(Client[ClientTransportT]):
         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(
+        result = await ctx.sample(
             list(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")
+        # Create TextContent from the result text
+        content = mcp.types.TextContent(type="text", text=result.text or "")
         return mcp.types.CreateMessageResult(
             role="assistant",
             model="fastmcp-client",
-            content=content,
+            # TODO(ty): remove when ty supports isinstance exclusion narrowing
+            content=content,  # type: ignore[arg-type]
         )
 
     @classmethod
@@ -610,9 +617,15 @@ class ProxyClient(Client[ClientTransportT]):
         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()
+        # requestedSchema only exists on ElicitRequestFormParams, not ElicitRequestURLParams
+        requested_schema = (
+            params.requestedSchema
+            if isinstance(params, ElicitRequestFormParams)
+            else {"type": "object", "properties": {}}
+        )
         result = await ctx.session.elicit(
             message=message,
-            requestedSchema=params.requestedSchema,
+            requestedSchema=requested_schema,
             related_request_id=ctx.request_id,
         )
         return ElicitResult(action=result.action, content=result.content)
@@ -656,7 +669,7 @@ class StatefulProxyClient(ProxyClient[ClientTransportT]):
         super().__init__(*args, **kwargs)
         self._caches: dict[ServerSession, Client[ClientTransportT]] = {}
 
-    async def __aexit__(self, exc_type, exc_value, traceback) -> None:
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:  # type: ignore[override]
         """
         The stateful proxy client will be forced disconnected when the session is exited.
         So we do nothing here.

fastmcp/server/sampling/__init__.py

@@ -0,0 +1,10 @@
+"""Sampling module for FastMCP servers."""
+
+from fastmcp.server.sampling.run import SampleStep, SamplingResult
+from fastmcp.server.sampling.sampling_tool import SamplingTool
+
+__all__ = [
+    "SampleStep",
+    "SamplingResult",
+    "SamplingTool",
+]