fastmcp 2.14.4__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

fastmcp/server/middleware/authorization.py

@@ -0,0 +1,312 @@
+"""Authorization middleware for FastMCP.
+
+This module provides middleware-based authorization using callable auth checks.
+AuthMiddleware applies auth checks globally to all components on the server.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth import require_auth, require_scopes, restrict_tag
+    from fastmcp.server.middleware import AuthMiddleware
+
+    # Require auth for all components
+    mcp = FastMCP(middleware=[
+        AuthMiddleware(auth=require_auth)
+    ])
+
+    # Tag-based: components tagged "admin" require "admin" scope
+    mcp = FastMCP(middleware=[
+        AuthMiddleware(auth=restrict_tag("admin", scopes=["admin"]))
+    ])
+    ```
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+import mcp.types as mt
+
+from fastmcp.exceptions import AuthorizationError
+from fastmcp.prompts.prompt import Prompt, PromptResult
+from fastmcp.resources.resource import Resource, ResourceResult
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.auth.authorization import (
+    AuthCheck,
+    AuthContext,
+    run_auth_checks,
+)
+from fastmcp.server.dependencies import get_access_token
+from fastmcp.server.middleware.middleware import (
+    CallNext,
+    Middleware,
+    MiddlewareContext,
+)
+from fastmcp.tools.tool import Tool, ToolResult
+
+logger = logging.getLogger(__name__)
+
+
+class AuthMiddleware(Middleware):
+    """Global authorization middleware using callable checks.
+
+    This middleware applies auth checks to all components (tools, resources,
+    prompts) on the server. It uses the same callable API as component-level
+    auth checks.
+
+    The middleware:
+    - Filters tools/resources/prompts from list responses based on auth checks
+    - Checks auth before tool execution, resource read, and prompt render
+    - Skips all auth checks for STDIO transport (no OAuth concept)
+
+    Args:
+        auth: A single auth check function or list of check functions.
+            All checks must pass for authorization to succeed (AND logic).
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth import require_auth, require_scopes
+
+        # Require any authentication for all components
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=require_auth)])
+
+        # Require specific scope for all components
+        mcp = FastMCP(middleware=[AuthMiddleware(auth=require_scopes("api"))])
+
+        # Combined checks (AND logic)
+        mcp = FastMCP(middleware=[
+            AuthMiddleware(auth=[require_auth, require_scopes("api")])
+        ])
+        ```
+    """
+
+    def __init__(self, auth: AuthCheck | list[AuthCheck]) -> None:
+        self.auth = auth
+
+    async def on_list_tools(
+        self,
+        context: MiddlewareContext[mt.ListToolsRequest],
+        call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]],
+    ) -> Sequence[Tool]:
+        """Filter tools/list response based on auth checks."""
+        tools = await call_next(context)
+
+        # STDIO has no auth concept, skip filtering
+        # Late import to avoid circular import with context.py
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return tools
+
+        token = get_access_token()
+
+        authorized_tools: list[Tool] = []
+        for tool in tools:
+            ctx = AuthContext(token=token, component=tool)
+            if run_auth_checks(self.auth, ctx):
+                authorized_tools.append(tool)
+
+        return authorized_tools
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mt.CallToolRequestParams],
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        """Check auth before tool execution."""
+        # STDIO has no auth concept, skip enforcement
+        # Late import to avoid circular import with context.py
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return await call_next(context)
+
+        # Get the tool being called
+        tool_name = context.message.name
+        fastmcp = context.fastmcp_context
+        if fastmcp is None:
+            # Fail closed: deny access when context is missing
+            logger.warning(
+                f"AuthMiddleware: fastmcp_context is None for tool '{tool_name}'. "
+                "Denying access for security."
+            )
+            raise AuthorizationError(
+                f"Authorization failed for tool '{tool_name}': missing context"
+            )
+
+        # Get tool (component auth is checked in get_tool, raises if unauthorized)
+        tool = await fastmcp.fastmcp.get_tool(tool_name)
+        if tool is None:
+            raise AuthorizationError(
+                f"Authorization failed for tool '{tool_name}': tool not found"
+            )
+
+        # Global auth check
+        token = get_access_token()
+        ctx = AuthContext(token=token, component=tool)
+        if not run_auth_checks(self.auth, ctx):
+            raise AuthorizationError(
+                f"Authorization failed for tool '{tool_name}': insufficient permissions"
+            )
+
+        return await call_next(context)
+
+    async def on_list_resources(
+        self,
+        context: MiddlewareContext[mt.ListResourcesRequest],
+        call_next: CallNext[mt.ListResourcesRequest, Sequence[Resource]],
+    ) -> Sequence[Resource]:
+        """Filter resources/list response based on auth checks."""
+        resources = await call_next(context)
+
+        # STDIO has no auth concept, skip filtering
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return resources
+
+        token = get_access_token()
+
+        authorized_resources: list[Resource] = []
+        for resource in resources:
+            ctx = AuthContext(token=token, component=resource)
+            if run_auth_checks(self.auth, ctx):
+                authorized_resources.append(resource)
+
+        return authorized_resources
+
+    async def on_read_resource(
+        self,
+        context: MiddlewareContext[mt.ReadResourceRequestParams],
+        call_next: CallNext[mt.ReadResourceRequestParams, ResourceResult],
+    ) -> ResourceResult:
+        """Check auth before resource read."""
+        # STDIO has no auth concept, skip enforcement
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return await call_next(context)
+
+        # Get the resource being read
+        uri = context.message.uri
+        fastmcp = context.fastmcp_context
+        if fastmcp is None:
+            logger.warning(
+                f"AuthMiddleware: fastmcp_context is None for resource '{uri}'. "
+                "Denying access for security."
+            )
+            raise AuthorizationError(
+                f"Authorization failed for resource '{uri}': missing context"
+            )
+
+        # Get resource/template (component auth is checked in get_*, raises if unauthorized)
+        component = await fastmcp.fastmcp.get_resource(str(uri))
+        if component is None:
+            component = await fastmcp.fastmcp.get_resource_template(str(uri))
+        if component is None:
+            raise AuthorizationError(
+                f"Authorization failed for resource '{uri}': resource not found"
+            )
+
+        # Global auth check
+        token = get_access_token()
+        ctx = AuthContext(token=token, component=component)
+        if not run_auth_checks(self.auth, ctx):
+            raise AuthorizationError(
+                f"Authorization failed for resource '{uri}': insufficient permissions"
+            )
+
+        return await call_next(context)
+
+    async def on_list_resource_templates(
+        self,
+        context: MiddlewareContext[mt.ListResourceTemplatesRequest],
+        call_next: CallNext[
+            mt.ListResourceTemplatesRequest, Sequence[ResourceTemplate]
+        ],
+    ) -> Sequence[ResourceTemplate]:
+        """Filter resource templates/list response based on auth checks."""
+        templates = await call_next(context)
+
+        # STDIO has no auth concept, skip filtering
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return templates
+
+        token = get_access_token()
+
+        authorized_templates: list[ResourceTemplate] = []
+        for template in templates:
+            ctx = AuthContext(token=token, component=template)
+            if run_auth_checks(self.auth, ctx):
+                authorized_templates.append(template)
+
+        return authorized_templates
+
+    async def on_list_prompts(
+        self,
+        context: MiddlewareContext[mt.ListPromptsRequest],
+        call_next: CallNext[mt.ListPromptsRequest, Sequence[Prompt]],
+    ) -> Sequence[Prompt]:
+        """Filter prompts/list response based on auth checks."""
+        prompts = await call_next(context)
+
+        # STDIO has no auth concept, skip filtering
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return prompts
+
+        token = get_access_token()
+
+        authorized_prompts: list[Prompt] = []
+        for prompt in prompts:
+            ctx = AuthContext(token=token, component=prompt)
+            if run_auth_checks(self.auth, ctx):
+                authorized_prompts.append(prompt)
+
+        return authorized_prompts
+
+    async def on_get_prompt(
+        self,
+        context: MiddlewareContext[mt.GetPromptRequestParams],
+        call_next: CallNext[mt.GetPromptRequestParams, PromptResult],
+    ) -> PromptResult:
+        """Check auth before prompt render."""
+        # STDIO has no auth concept, skip enforcement
+        from fastmcp.server.context import _current_transport
+
+        if _current_transport.get() == "stdio":
+            return await call_next(context)
+
+        # Get the prompt being rendered
+        prompt_name = context.message.name
+        fastmcp = context.fastmcp_context
+        if fastmcp is None:
+            logger.warning(
+                f"AuthMiddleware: fastmcp_context is None for prompt '{prompt_name}'. "
+                "Denying access for security."
+            )
+            raise AuthorizationError(
+                f"Authorization failed for prompt '{prompt_name}': missing context"
+            )
+
+        # Get prompt (component auth is checked in get_prompt, raises if unauthorized)
+        prompt = await fastmcp.fastmcp.get_prompt(prompt_name)
+        if prompt is None:
+            raise AuthorizationError(
+                f"Authorization failed for prompt '{prompt_name}': prompt not found"
+            )
+
+        # Global auth check
+        token = get_access_token()
+        ctx = AuthContext(token=token, component=prompt)
+        if not run_auth_checks(self.auth, ctx):
+            raise AuthorizationError(
+                f"Authorization failed for prompt '{prompt_name}': insufficient permissions"
+            )
+
+        return await call_next(context)

fastmcp/server/middleware/caching.py

@@ -14,15 +14,15 @@ from key_value.aio.wrappers.statistics import StatisticsWrapper
 from key_value.aio.wrappers.statistics.wrapper import (
     KVStoreCollectionStatistics,
 )
-from mcp.server.lowlevel.helper_types import ReadResourceContents
-from pydantic import BaseModel, Field
+from pydantic import Field
 from typing_extensions import NotRequired, Self, override
 
-from fastmcp.prompts.prompt import Prompt
-from fastmcp.resources.resource import Resource
+from fastmcp.prompts.prompt import Message, Prompt, PromptResult
+from fastmcp.resources.resource import Resource, ResourceContent, ResourceResult
 from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
 from fastmcp.tools.tool import Tool, ToolResult
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import FastMCPBaseModel
 
 logger: Logger = get_logger(name=__name__)
 
@@ -35,32 +35,48 @@ ONE_MB_IN_BYTES = 1024 * 1024
 GLOBAL_KEY = "__global__"
 
 
-class CachableReadResourceContents(BaseModel):
-    """A wrapper for ReadResourceContents that can be cached."""
+class CachableResourceContent(FastMCPBaseModel):
+    """A wrapper for ResourceContent that can be cached."""
 
     content: str | bytes
     mime_type: str | None = None
+    meta: dict[str, Any] | None = None
+
+
+class CachableResourceResult(FastMCPBaseModel):
+    """A wrapper for ResourceResult that can be cached."""
+
+    contents: list[CachableResourceContent]
+    meta: dict[str, Any] | None = None
 
     def get_size(self) -> int:
         return len(self.model_dump_json())
 
     @classmethod
-    def get_sizes(cls, values: Sequence[Self]) -> int:
-        return sum(item.get_size() for item in values)
-
-    @classmethod
-    def wrap(cls, values: Sequence[ReadResourceContents]) -> list[Self]:
-        return [cls(content=item.content, mime_type=item.mime_type) for item in values]
+    def wrap(cls, value: ResourceResult) -> Self:
+        return cls(
+            contents=[
+                CachableResourceContent(
+                    content=item.content, mime_type=item.mime_type, meta=item.meta
+                )
+                for item in value.contents
+            ],
+            meta=value.meta,
+        )
 
-    @classmethod
-    def unwrap(cls, values: Sequence[Self]) -> list[ReadResourceContents]:
-        return [
-            ReadResourceContents(content=item.content, mime_type=item.mime_type)
-            for item in values
-        ]
+    def unwrap(self) -> ResourceResult:
+        return ResourceResult(
+            contents=[
+                ResourceContent(
+                    content=item.content, mime_type=item.mime_type, meta=item.meta
+                )
+                for item in self.contents
+            ],
+            meta=self.meta,
+        )
 
 
-class CachableToolResult(BaseModel):
+class CachableToolResult(FastMCPBaseModel):
     content: list[mcp.types.ContentBlock]
     structured_content: dict[str, Any] | None
     meta: dict[str, Any] | None
@@ -81,6 +97,44 @@ class CachableToolResult(BaseModel):
         )
 
 
+class CachableMessage(FastMCPBaseModel):
+    """A wrapper for Message that can be cached."""
+
+    role: str
+    content: mcp.types.TextContent | mcp.types.EmbeddedResource
+
+
+class CachablePromptResult(FastMCPBaseModel):
+    """A wrapper for PromptResult that can be cached."""
+
+    messages: list[CachableMessage]
+    description: str | None = None
+    meta: dict[str, Any] | None = None
+
+    def get_size(self) -> int:
+        return len(self.model_dump_json())
+
+    @classmethod
+    def wrap(cls, value: PromptResult) -> Self:
+        return cls(
+            messages=[
+                CachableMessage(role=m.role, content=m.content) for m in value.messages
+            ],
+            description=value.description,
+            meta=value.meta,
+        )
+
+    def unwrap(self) -> PromptResult:
+        return PromptResult(
+            messages=[
+                Message(content=m.content, role=m.role)  # type: ignore[arg-type]
+                for m in self.messages
+            ],
+            description=self.description,
+            meta=self.meta,
+        )
+
+
 class SharedMethodSettings(TypedDict):
     """Shared config for a cache method."""
 
@@ -115,7 +169,7 @@ class GetPromptSettings(SharedMethodSettings):
     """Configuration options for Prompt-related caching."""
 
 
-class ResponseCachingStatistics(BaseModel):
+class ResponseCachingStatistics(FastMCPBaseModel):
     list_tools: KVStoreCollectionStatistics | None = Field(default=None)
     list_resources: KVStoreCollectionStatistics | None = Field(default=None)
     list_prompts: KVStoreCollectionStatistics | None = Field(default=None)
@@ -189,43 +243,43 @@ class ResponseCachingMiddleware(Middleware):
             call_tool_settings or CallToolSettings()
         )
 
+        # PydanticAdapter type signature will be fixed to accept generic aliases
+        # See: https://github.com/strawgate/py-key-value/pull/250
         self._list_tools_cache: PydanticAdapter[list[Tool]] = PydanticAdapter(
             key_value=self._stats,
-            pydantic_model=list[Tool],
+            pydantic_model=list[Tool],  # type: ignore[arg-type]
             default_collection="tools/list",
         )
 
         self._list_resources_cache: PydanticAdapter[list[Resource]] = PydanticAdapter(
             key_value=self._stats,
-            pydantic_model=list[Resource],
+            pydantic_model=list[Resource],  # type: ignore[arg-type]
             default_collection="resources/list",
         )
 
         self._list_prompts_cache: PydanticAdapter[list[Prompt]] = PydanticAdapter(
             key_value=self._stats,
-            pydantic_model=list[Prompt],
+            pydantic_model=list[Prompt],  # type: ignore[arg-type]
             default_collection="prompts/list",
         )
 
-        self._read_resource_cache: PydanticAdapter[
-            list[CachableReadResourceContents]
-        ] = PydanticAdapter(
-            key_value=self._stats,
-            pydantic_model=list[CachableReadResourceContents],
-            default_collection="resources/read",
-        )
-
-        self._get_prompt_cache: PydanticAdapter[mcp.types.GetPromptResult] = (
+        self._read_resource_cache: PydanticAdapter[CachableResourceResult] = (
             PydanticAdapter(
                 key_value=self._stats,
-                pydantic_model=mcp.types.GetPromptResult,
-                default_collection="prompts/get",
+                pydantic_model=CachableResourceResult,  # type: ignore[arg-type]
+                default_collection="resources/read",
             )
         )
 
+        self._get_prompt_cache: PydanticAdapter[CachablePromptResult] = PydanticAdapter(
+            key_value=self._stats,
+            pydantic_model=CachablePromptResult,  # type: ignore[arg-type]
+            default_collection="prompts/get",
+        )
+
         self._call_tool_cache: PydanticAdapter[CachableToolResult] = PydanticAdapter(
             key_value=self._stats,
-            pydantic_model=CachableToolResult,
+            pydantic_model=CachableToolResult,  # type: ignore[arg-type]
             default_collection="tools/call",
         )
 
@@ -256,7 +310,6 @@ class ResponseCachingMiddleware(Middleware):
                 annotations=tool.annotations,
                 meta=tool.meta,
                 tags=tool.tags,
-                enabled=tool.enabled,
             )
             for tool in tools
         ]
@@ -295,7 +348,6 @@ class ResponseCachingMiddleware(Middleware):
                 meta=resource.meta,
                 mime_type=resource.mime_type,
                 annotations=resource.annotations,
-                enabled=resource.enabled,
                 uri=resource.uri,
             )
             for resource in resources
@@ -333,7 +385,6 @@ class ResponseCachingMiddleware(Middleware):
                 description=prompt.description,
                 tags=prompt.tags,
                 meta=prompt.meta,
-                enabled=prompt.enabled,
                 arguments=prompt.arguments,
             )
             for prompt in prompts
@@ -384,23 +435,21 @@ class ResponseCachingMiddleware(Middleware):
     async def on_read_resource(
         self,
         context: MiddlewareContext[mcp.types.ReadResourceRequestParams],
-        call_next: CallNext[
-            mcp.types.ReadResourceRequestParams, Sequence[ReadResourceContents]
-        ],
-    ) -> Sequence[ReadResourceContents]:
+        call_next: CallNext[mcp.types.ReadResourceRequestParams, ResourceResult],
+    ) -> ResourceResult:
         """Read a resource from the cache, if caching is enabled, and the result is in the cache. Otherwise,
         otherwise call the next middleware and store the result in the cache if caching is enabled."""
         if self._read_resource_settings.get("enabled") is False:
             return await call_next(context=context)
 
         cache_key: str = str(context.message.uri)
-        cached_value: list[CachableReadResourceContents] | None
+        cached_value: CachableResourceResult | None
 
         if cached_value := await self._read_resource_cache.get(key=cache_key):
-            return CachableReadResourceContents.unwrap(values=cached_value)
+            return cached_value.unwrap()
 
-        value: Sequence[ReadResourceContents] = await call_next(context=context)
-        cached_value = CachableReadResourceContents.wrap(values=value)
+        value: ResourceResult = await call_next(context=context)
+        cached_value = CachableResourceResult.wrap(value)
 
         await self._read_resource_cache.put(
             key=cache_key,
@@ -408,16 +457,14 @@ class ResponseCachingMiddleware(Middleware):
             ttl=self._read_resource_settings.get("ttl", ONE_HOUR_IN_SECONDS),
         )
 
-        return CachableReadResourceContents.unwrap(values=cached_value)
+        return cached_value.unwrap()
 
     @override
     async def on_get_prompt(
         self,
         context: MiddlewareContext[mcp.types.GetPromptRequestParams],
-        call_next: CallNext[
-            mcp.types.GetPromptRequestParams, mcp.types.GetPromptResult
-        ],
-    ) -> mcp.types.GetPromptResult:
+        call_next: CallNext[mcp.types.GetPromptRequestParams, PromptResult],
+    ) -> PromptResult:
         """Get a prompt from the cache, if caching is enabled, and the result is in the cache. Otherwise,
         otherwise call the next middleware and store the result in the cache if caching is enabled."""
         if self._get_prompt_settings.get("enabled") is False:
@@ -426,13 +473,13 @@ class ResponseCachingMiddleware(Middleware):
         cache_key: str = f"{context.message.name}:{_get_arguments_str(arguments=context.message.arguments)}"
 
         if cached_value := await self._get_prompt_cache.get(key=cache_key):
-            return cached_value
+            return cached_value.unwrap()
 
-        value: mcp.types.GetPromptResult = await call_next(context=context)
+        value: PromptResult = await call_next(context=context)
 
         await self._get_prompt_cache.put(
             key=cache_key,
-            value=value,
+            value=CachablePromptResult.wrap(value),
             ttl=self._get_prompt_settings.get("ttl", ONE_HOUR_IN_SECONDS),
         )
 

fastmcp/server/middleware/middleware.py

@@ -15,11 +15,10 @@ from typing import (
 )
 
 import mcp.types as mt
-from mcp.server.lowlevel.helper_types import ReadResourceContents
 from typing_extensions import TypeVar
 
-from fastmcp.prompts.prompt import Prompt
-from fastmcp.resources.resource import Resource
+from fastmcp.prompts.prompt import Prompt, PromptResult
+from fastmcp.resources.resource import Resource, ResourceResult
 from fastmcp.resources.template import ResourceTemplate
 from fastmcp.tools.tool import Tool, ToolResult
 
@@ -164,17 +163,15 @@ class Middleware:
     async def on_read_resource(
         self,
         context: MiddlewareContext[mt.ReadResourceRequestParams],
-        call_next: CallNext[
-            mt.ReadResourceRequestParams, Sequence[ReadResourceContents]
-        ],
-    ) -> Sequence[ReadResourceContents]:
+        call_next: CallNext[mt.ReadResourceRequestParams, ResourceResult],
+    ) -> ResourceResult:
         return await call_next(context)
 
     async def on_get_prompt(
         self,
         context: MiddlewareContext[mt.GetPromptRequestParams],
-        call_next: CallNext[mt.GetPromptRequestParams, mt.GetPromptResult],
-    ) -> mt.GetPromptResult:
+        call_next: CallNext[mt.GetPromptRequestParams, PromptResult],
+    ) -> PromptResult:
         return await call_next(context)
 
     async def on_list_tools(