fastmcp 2.10.5__py3-none-any.whl → 2.11.0__py3-none-any.whl

fastmcp/server/http.py

@@ -3,18 +3,20 @@ from __future__ import annotations
 from collections.abc import AsyncGenerator, Callable, Generator
 from contextlib import asynccontextmanager, contextmanager
 from contextvars import ContextVar
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
 from mcp.server.auth.middleware.bearer_auth import (
     BearerAuthBackend,
     RequireAuthMiddleware,
 )
+from mcp.server.auth.provider import TokenVerifier as TokenVerifierProtocol
 from mcp.server.auth.routes import create_auth_routes
 from mcp.server.lowlevel.server import LifespanResultT
 from mcp.server.sse import SseServerTransport
 from mcp.server.streamable_http import EventStore
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+from pydantic import AnyHttpUrl
 from starlette.applications import Starlette
 from starlette.middleware import Middleware
 from starlette.middleware.authentication import AuthenticationMiddleware
@@ -23,7 +25,7 @@ from starlette.responses import Response
 from starlette.routing import BaseRoute, Mount, Route
 from starlette.types import Lifespan, Receive, Scope, Send
 
-from fastmcp.server.auth.auth import OAuthProvider
+from fastmcp.server.auth.auth import AuthProvider, OAuthProvider, TokenVerifier
 from fastmcp.utilities.logging import get_logger
 
 if TYPE_CHECKING:
@@ -70,39 +72,46 @@ class RequestContextMiddleware:
 
 
 def setup_auth_middleware_and_routes(
-    auth: OAuthProvider,
-) -> tuple[list[Middleware], list[BaseRoute], list[str]]:
+    auth: AuthProvider,
+) -> tuple[list[Middleware], list[Route], list[str]]:
     """Set up authentication middleware and routes if auth is enabled.
 
     Args:
-        auth: The OAuthProvider authorization server provider
+        auth: An AuthProvider for authentication (TokenVerifier or OAuthProvider)
 
     Returns:
         Tuple of (middleware, auth_routes, required_scopes)
     """
-    middleware: list[Middleware] = []
-    auth_routes: list[BaseRoute] = []
-    required_scopes: list[str] = []
-
-    middleware = [
+    middleware: list[Middleware] = [
         Middleware(
             AuthenticationMiddleware,
-            backend=BearerAuthBackend(auth),
+            backend=BearerAuthBackend(cast(TokenVerifierProtocol, auth)),
         ),
         Middleware(AuthContextMiddleware),
     ]
 
-    required_scopes = auth.required_scopes or []
-
-    auth_routes.extend(
-        create_auth_routes(
-            provider=auth,
-            issuer_url=auth.issuer_url,
-            service_documentation_url=auth.service_documentation_url,
-            client_registration_options=auth.client_registration_options,
-            revocation_options=auth.revocation_options,
+    auth_routes: list[Route] = []
+    required_scopes: list[str] = auth.required_scopes or []
+
+    # Check if it's an OAuthProvider (has OAuth server capability)
+    if isinstance(auth, OAuthProvider):
+        # OAuthProvider: create standard OAuth routes first
+        standard_routes = list(
+            create_auth_routes(
+                provider=auth,
+                issuer_url=auth.issuer_url,
+                service_documentation_url=auth.service_documentation_url,
+                client_registration_options=auth.client_registration_options,
+                revocation_options=auth.revocation_options,
+            )
         )
-    )
+
+        # Allow provider to customize routes (e.g., for proxy behavior or metadata endpoints)
+        auth_routes = auth.customize_auth_routes(standard_routes)
+    else:
+        # Simple AuthProvider or TokenVerifier: start with empty routes
+        # Allow provider to add custom routes (e.g., metadata endpoints)
+        auth_routes = auth.customize_auth_routes([])
 
     return middleware, auth_routes, required_scopes
 
@@ -139,7 +148,7 @@ def create_sse_app(
     server: FastMCP[LifespanResultT],
     message_path: str,
     sse_path: str,
-    auth: OAuthProvider | None = None,
+    auth: AuthProvider | None = None,
     debug: bool = False,
     routes: list[BaseRoute] | None = None,
     middleware: list[Middleware] | None = None,
@@ -150,7 +159,7 @@ def create_sse_app(
         server: The FastMCP server instance
         message_path: Path for SSE messages
         sse_path: Path for SSE connections
-        auth: Optional auth provider
+        auth: Optional authentication provider (AuthProvider)
         debug: Whether to enable debug mode
         routes: Optional list of custom routes
         middleware: Optional list of middleware
@@ -175,8 +184,6 @@ def create_sse_app(
         return Response()
 
     # Get auth middleware and routes
-
-    # Add SSE routes with or without auth
     if auth:
         auth_middleware, auth_routes, required_scopes = (
             setup_auth_middleware_and_routes(auth)
@@ -184,18 +191,32 @@ def create_sse_app(
 
         server_routes.extend(auth_routes)
         server_middleware.extend(auth_middleware)
+
+        # Determine resource_metadata_url for TokenVerifier
+        resource_metadata_url = None
+        if isinstance(auth, TokenVerifier) and auth.resource_server_url:
+            # Add .well-known path for RFC 9728 compliance
+            resource_metadata_url = AnyHttpUrl(
+                str(auth.resource_server_url).rstrip("/")
+                + "/.well-known/oauth-protected-resource"
+            )
+
         # Auth is enabled, wrap endpoints with RequireAuthMiddleware
         server_routes.append(
             Route(
                 sse_path,
-                endpoint=RequireAuthMiddleware(handle_sse, required_scopes),
+                endpoint=RequireAuthMiddleware(
+                    handle_sse, required_scopes, resource_metadata_url
+                ),
                 methods=["GET"],
             )
         )
         server_routes.append(
             Mount(
                 message_path,
-                app=RequireAuthMiddleware(sse.handle_post_message, required_scopes),
+                app=RequireAuthMiddleware(
+                    sse.handle_post_message, required_scopes, resource_metadata_url
+                ),
             )
         )
     else:
@@ -243,7 +264,7 @@ def create_streamable_http_app(
     server: FastMCP[LifespanResultT],
     streamable_http_path: str,
     event_store: EventStore | None = None,
-    auth: OAuthProvider | None = None,
+    auth: AuthProvider | None = None,
     json_response: bool = False,
     stateless_http: bool = False,
     debug: bool = False,
@@ -256,7 +277,7 @@ def create_streamable_http_app(
         server: The FastMCP server instance
         streamable_http_path: Path for StreamableHTTP connections
         event_store: Optional event store for session management
-        auth: Optional auth provider
+        auth: Optional authentication provider (AuthProvider)
         json_response: Whether to use JSON response format
         stateless_http: Whether to use stateless mode (new transport per request)
         debug: Whether to enable debug mode
@@ -314,11 +335,22 @@ def create_streamable_http_app(
         server_routes.extend(auth_routes)
         server_middleware.extend(auth_middleware)
 
+        # Determine resource_metadata_url for TokenVerifier
+        resource_metadata_url = None
+        if isinstance(auth, TokenVerifier) and auth.resource_server_url:
+            # Add .well-known path for RFC 9728 compliance
+            resource_metadata_url = AnyHttpUrl(
+                str(auth.resource_server_url).rstrip("/")
+                + "/.well-known/oauth-protected-resource"
+            )
+
         # Auth is enabled, wrap endpoint with RequireAuthMiddleware
         server_routes.append(
             Mount(
                 streamable_http_path,
-                app=RequireAuthMiddleware(handle_streamable_http, required_scopes),
+                app=RequireAuthMiddleware(
+                    handle_streamable_http, required_scopes, resource_metadata_url
+                ),
             )
         )
     else:

fastmcp/server/middleware/middleware.py

@@ -20,7 +20,7 @@ import mcp.types as mt
 from fastmcp.prompts.prompt import Prompt
 from fastmcp.resources.resource import Resource
 from fastmcp.resources.template import ResourceTemplate
-from fastmcp.tools.tool import Tool
+from fastmcp.tools.tool import Tool, ToolResult
 
 if TYPE_CHECKING:
     from fastmcp.server.context import Context
@@ -43,26 +43,6 @@ class CallNext(Protocol[T, R]):
     def __call__(self, context: MiddlewareContext[T]) -> Awaitable[R]: ...
 
 
-ServerResultT = TypeVar(
-    "ServerResultT",
-    bound=mt.EmptyResult
-    | mt.InitializeResult
-    | mt.CompleteResult
-    | mt.GetPromptResult
-    | mt.ListPromptsResult
-    | mt.ListResourcesResult
-    | mt.ListResourceTemplatesResult
-    | mt.ReadResourceResult
-    | mt.CallToolResult
-    | mt.ListToolsResult,
-)
-
-
-@runtime_checkable
-class ServerResultProtocol(Protocol[ServerResultT]):
-    root: ServerResultT
-
-
 @dataclass(kw_only=True, frozen=True)
 class MiddlewareContext(Generic[T]):
     """
@@ -167,8 +147,8 @@ class Middleware:
     async def on_call_tool(
         self,
         context: MiddlewareContext[mt.CallToolRequestParams],
-        call_next: CallNext[mt.CallToolRequestParams, mt.CallToolResult],
-    ) -> mt.CallToolResult:
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
         return await call_next(context)
 
     async def on_read_resource(

fastmcp/server/openapi.py

@@ -344,18 +344,28 @@ class OpenAPITool(Tool):
                 suffixed_name = f"{p.name}__{p.location}"
                 param_value = None
 
+                suffixed_value = arguments.get(suffixed_name)
                 if (
                     suffixed_name in arguments
-                    and arguments.get(suffixed_name) is not None
-                    and arguments.get(suffixed_name) != ""
+                    and suffixed_value is not None
+                    and suffixed_value != ""
+                    and not (
+                        isinstance(suffixed_value, list | dict)
+                        and len(suffixed_value) == 0
+                    )
                 ):
                     param_value = arguments[suffixed_name]
-                elif (
-                    p.name in arguments
-                    and arguments.get(p.name) is not None
-                    and arguments.get(p.name) != ""
-                ):
-                    param_value = arguments[p.name]
+                else:
+                    name_value = arguments.get(p.name)
+                    if (
+                        p.name in arguments
+                        and name_value is not None
+                        and name_value != ""
+                        and not (
+                            isinstance(name_value, list | dict) and len(name_value) == 0
+                        )
+                    ):
+                        param_value = arguments[p.name]
 
                 if param_value is not None:
                     # Handle different parameter styles and types
@@ -367,7 +377,11 @@ class OpenAPITool(Tool):
                     )  # Default explode for query is True
 
                     # Handle deepObject style for object parameters
-                    if param_style == "deepObject" and isinstance(param_value, dict):
+                    if (
+                        param_style == "deepObject"
+                        and isinstance(param_value, dict)
+                        and len(param_value) > 0
+                    ):
                         if param_explode:
                             # deepObject with explode=true: object properties become separate parameters
                             # e.g., target[id]=123&target[type]=user
@@ -386,6 +400,7 @@ class OpenAPITool(Tool):
                     elif (
                         isinstance(param_value, list)
                         and p.schema_.get("type") == "array"
+                        and len(param_value) > 0
                     ):
                         if param_explode:
                             # When explode=True, we pass the array directly, which HTTPX will serialize
@@ -444,9 +459,7 @@ class OpenAPITool(Tool):
                     params_to_exclude.add(p.name)
 
             body_params = {
-                k: v
-                for k, v in arguments.items()
-                if k not in params_to_exclude and k != "context"
+                k: v for k, v in arguments.items() if k not in params_to_exclude
             }
 
             if body_params:
@@ -879,7 +892,7 @@ class FastMCPOpenAPI(FastMCP):
 
         # Extract output schema from OpenAPI responses
         output_schema = extract_output_schema_from_responses(
-            route.responses, route.schema_definitions
+            route.responses, route.schema_definitions, route.openapi_version
         )
 
         # Get a unique tool name

fastmcp/server/proxy.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Any, cast
 from urllib.parse import quote
 
 import mcp.types
+from mcp import ServerSession
 from mcp.client.session import ClientSession
 from mcp.shared.context import LifespanContextT, RequestContext
 from mcp.shared.exceptions import McpError
@@ -36,6 +37,9 @@ 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
+from fastmcp.tools.tool_transform import (
+    apply_transformations_to_tools,
+)
 from fastmcp.utilities.components import MirroredComponent
 from fastmcp.utilities.logging import get_logger
 
@@ -71,7 +75,12 @@ class ProxyToolManager(ToolManager):
             else:
                 raise e
 
-        return all_tools
+        transformed_tools = apply_transformations_to_tools(
+            tools=all_tools,
+            transformations=self.transformations,
+        )
+
+        return transformed_tools
 
     async def list_tools(self) -> list[Tool]:
         """Gets the filtered list of tools including local, mounted, and proxy tools."""
@@ -246,6 +255,8 @@ class ProxyTool(Tool, MirroredComponent):
             parameters=mcp_tool.inputSchema,
             annotations=mcp_tool.annotations,
             output_schema=mcp_tool.outputSchema,
+            meta=mcp_tool.meta,
+            tags=(mcp_tool.meta or {}).get("_fastmcp", {}).get("tags", []),
             _mirrored=True,
         )
 
@@ -294,12 +305,15 @@ class ProxyResource(Resource, MirroredComponent):
         mcp_resource: mcp.types.Resource,
     ) -> ProxyResource:
         """Factory method to create a ProxyResource from a raw MCP resource schema."""
+
         return cls(
             client=client,
             uri=mcp_resource.uri,
             name=mcp_resource.name,
             description=mcp_resource.description,
             mime_type=mcp_resource.mimeType or "text/plain",
+            meta=mcp_resource.meta,
+            tags=(mcp_resource.meta or {}).get("_fastmcp", {}).get("tags", []),
             _mirrored=True,
         )
 
@@ -339,6 +353,8 @@ class ProxyTemplate(ResourceTemplate, MirroredComponent):
             description=mcp_template.description,
             mime_type=mcp_template.mimeType or "text/plain",
             parameters={},  # Remote templates don't have local parameters
+            meta=mcp_template.meta,
+            tags=(mcp_template.meta or {}).get("_fastmcp", {}).get("tags", []),
             _mirrored=True,
         )
 
@@ -371,6 +387,8 @@ class ProxyTemplate(ResourceTemplate, MirroredComponent):
             name=self.name,
             description=self.description,
             mime_type=result[0].mimeType,
+            meta=self.meta,
+            tags=(self.meta or {}).get("_fastmcp", {}).get("tags", []),
             _value=value,
         )
 
@@ -404,6 +422,8 @@ class ProxyPrompt(Prompt, MirroredComponent):
             name=mcp_prompt.name,
             description=mcp_prompt.description,
             arguments=arguments,
+            meta=mcp_prompt.meta,
+            tags=(mcp_prompt.meta or {}).get("_fastmcp", {}).get("tags", []),
             _mirrored=True,
         )
 
@@ -469,7 +489,11 @@ class FastMCPProxy(FastMCP):
             raise ValueError("Must specify 'client_factory'")
 
         # Replace the default managers with our specialized proxy managers.
-        self._tool_manager = ProxyToolManager(client_factory=self.client_factory)
+        self._tool_manager = ProxyToolManager(
+            client_factory=self.client_factory,
+            # Propagate the transformations from the base class tool manager
+            transformations=self._tool_manager.transformations,
+        )
         self._resource_manager = ProxyResourceManager(
             client_factory=self.client_factory
         )
@@ -554,11 +578,12 @@ 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()
-        result = await ctx.elicit(message, response_type)
-        if result.action == "accept":
-            return result.data
-        else:
-            return ElicitResult(action=result.action)
+        result = await ctx.session.elicit(
+            message=message,
+            requestedSchema=params.requestedSchema,
+            related_request_id=ctx.request_id,
+        )
+        return ElicitResult(action=result.action, content=result.content)
 
     @classmethod
     async def default_log_handler(cls, message: LogMessage) -> None:
@@ -566,7 +591,9 @@ class ProxyClient(Client[ClientTransportT]):
         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)
+        msg = message.data.get("msg")
+        extra = message.data.get("extra")
+        await ctx.log(msg, level=message.level, logger_name=message.logger, extra=extra)
 
     @classmethod
     async def default_progress_handler(
@@ -580,3 +607,57 @@ class ProxyClient(Client[ClientTransportT]):
         """
         ctx = get_context()
         await ctx.report_progress(progress, total, message)
+
+
+class StatefulProxyClient(ProxyClient[ClientTransportT]):
+    """
+    A proxy client that provides a stateful client factory for the proxy server.
+
+    The stateful proxy client bound its copy to the server session.
+    And it will be disconnected when the session is exited.
+
+    This is useful to proxy a stateful mcp server such as the Playwright MCP server.
+    Note that it is essential to ensure that the proxy server itself is also stateful.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._caches: dict[ServerSession, Client[ClientTransportT]] = {}
+
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:
+        """
+        The stateful proxy client will be forced disconnected when the session is exited.
+        So we do nothing here.
+        """
+        pass
+
+    async def clear(self):
+        """
+        Clear all cached clients and force disconnect them.
+        """
+        while self._caches:
+            _, cache = self._caches.popitem()
+            await cache._disconnect(force=True)
+
+    def new_stateful(self) -> Client[ClientTransportT]:
+        """
+        Create a new stateful proxy client instance with the same configuration.
+
+        Use this method as the client factory for stateful proxy server.
+        """
+        session = get_context().session
+        proxy_client = self._caches.get(session, None)
+
+        if proxy_client is None:
+            proxy_client = self.new()
+            logger.debug(f"{proxy_client} created for {session}")
+            self._caches[session] = proxy_client
+
+            async def _on_session_exit():
+                self._caches.pop(session)
+                logger.debug(f"{proxy_client} will be disconnect")
+                await proxy_client._disconnect(force=True)
+
+            session._exit_stack.push_async_callback(_on_session_exit)
+
+        return proxy_client