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

fastmcp/resources/template.py

@@ -5,10 +5,15 @@ from __future__ import annotations
 import inspect
 import re
 from collections.abc import Callable
-from typing import Annotated, Any
+from typing import TYPE_CHECKING, Any, ClassVar, overload
 from urllib.parse import parse_qs, unquote
 
+import mcp.types
 from mcp.types import Annotations, Icon
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
 from mcp.types import ResourceTemplate as SDKResourceTemplate
 from pydantic import (
     Field,
@@ -16,9 +21,13 @@ from pydantic import (
     validate_call,
 )
 
-from fastmcp.resources.resource import Resource
-from fastmcp.server.dependencies import get_context, without_injected_parameters
-from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.resources.resource import Resource, ResourceResult
+from fastmcp.server.dependencies import (
+    transform_context_annotations,
+    without_injected_parameters,
+)
+from fastmcp.server.tasks.config import TaskConfig, TaskMeta
+from fastmcp.tools.tool import AuthCheckCallable
 from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.types import get_cached_typeadapter
@@ -84,7 +93,7 @@ def match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None:
         for name in query_param_names:
             if name in parsed_query:
                 # Take first value if multiple provided
-                params[name] = parsed_query[name][0]  # type: ignore[index]
+                params[name] = parsed_query[name][0]
 
     return params
 
@@ -92,6 +101,8 @@ def match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None:
 class ResourceTemplate(FastMCPComponent):
     """A template for dynamically creating resources."""
 
+    KEY_PREFIX: ClassVar[str] = "template"
+
     uri_template: str = Field(
         description="URI template with parameters (e.g. weather://{city}/current)"
     )
@@ -104,54 +115,45 @@ class ResourceTemplate(FastMCPComponent):
     annotations: Annotations | None = Field(
         default=None, description="Optional annotations about the resource's behavior"
     )
+    auth: AuthCheckCallable | list[AuthCheckCallable] | None = Field(
+        default=None,
+        description="Authorization checks for this resource template",
+        exclude=True,
+    )
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(uri_template={self.uri_template!r}, name={self.name!r}, description={self.description!r}, tags={self.tags})"
 
-    def enable(self) -> None:
-        super().enable()
-        try:
-            context = get_context()
-            context._queue_resource_list_changed()  # type: ignore[private-use]
-        except RuntimeError:
-            pass  # No context available
-
-    def disable(self) -> None:
-        super().disable()
-        try:
-            context = get_context()
-            context._queue_resource_list_changed()  # type: ignore[private-use]
-        except RuntimeError:
-            pass  # No context available
-
     @staticmethod
     def from_function(
         fn: Callable[..., Any],
         uri_template: str,
         name: str | None = None,
+        version: str | int | None = None,
         title: str | None = None,
         description: str | None = None,
         icons: list[Icon] | None = None,
         mime_type: str | None = None,
         tags: set[str] | None = None,
-        enabled: bool | None = None,
         annotations: Annotations | None = None,
         meta: dict[str, Any] | None = None,
         task: bool | TaskConfig | None = None,
+        auth: AuthCheckCallable | list[AuthCheckCallable] | None = None,
     ) -> FunctionResourceTemplate:
         return FunctionResourceTemplate.from_function(
             fn=fn,
             uri_template=uri_template,
             name=name,
+            version=version,
             title=title,
             description=description,
             icons=icons,
             mime_type=mime_type,
             tags=tags,
-            enabled=enabled,
             annotations=annotations,
             meta=meta,
             task=task,
+            auth=auth,
         )
 
     @field_validator("mime_type", mode="before")
@@ -166,12 +168,76 @@ class ResourceTemplate(FastMCPComponent):
         """Check if URI matches template and extract parameters."""
         return match_uri_template(uri, self.uri_template)
 
-    async def read(self, arguments: dict[str, Any]) -> str | bytes:
+    async def read(self, arguments: dict[str, Any]) -> str | bytes | ResourceResult:
         """Read the resource content."""
         raise NotImplementedError(
             "Subclasses must implement read() or override create_resource()"
         )
 
+    def convert_result(self, raw_value: Any) -> ResourceResult:
+        """Convert a raw result to ResourceResult.
+
+        This is used in two contexts:
+        1. In _read() to convert user function return values to ResourceResult
+        2. In tasks_result_handler() to convert Docket task results to ResourceResult
+
+        Handles ResourceResult passthrough and converts raw values using
+        ResourceResult's normalization.
+        """
+        if isinstance(raw_value, ResourceResult):
+            return raw_value
+
+        # ResourceResult.__init__ handles all normalization
+        return ResourceResult(raw_value)
+
+    @overload
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: None = None
+    ) -> ResourceResult: ...
+
+    @overload
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: TaskMeta
+    ) -> mcp.types.CreateTaskResult: ...
+
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: TaskMeta | None = None
+    ) -> ResourceResult | mcp.types.CreateTaskResult:
+        """Server entry point that handles task routing.
+
+        This allows ANY ResourceTemplate subclass to support background execution
+        by setting task_config.mode to "supported" or "required". The server calls
+        this method instead of create_resource()/read() directly.
+
+        Args:
+            uri: The concrete URI being read
+            params: Template parameters extracted from the URI
+            task_meta: If provided, execute as a background task and return
+                CreateTaskResult. If None (default), execute synchronously and
+                return ResourceResult.
+
+        Returns:
+            ResourceResult when task_meta is None.
+            CreateTaskResult when task_meta is provided.
+
+        Subclasses can override this to customize task routing behavior.
+        For example, FastMCPProviderResourceTemplate overrides to delegate to child
+        middleware without submitting to Docket.
+        """
+        from fastmcp.server.tasks.routing import check_background_task
+
+        task_result = await check_background_task(
+            component=self, task_type="template", arguments=params, task_meta=task_meta
+        )
+        if task_result:
+            return task_result
+
+        # Synchronous execution - create resource and read directly
+        # Call resource.read() not resource._read() to avoid task routing on ephemeral resource
+        resource = await self.create_resource(uri, params)
+        result = await resource.read()
+        return self.convert_result(result)
+
     async def create_resource(self, uri: str, params: dict[str, Any]) -> Resource:
         """Create a resource from the template with the given parameters.
 
@@ -185,8 +251,6 @@ class ResourceTemplate(FastMCPComponent):
 
     def to_mcp_template(
         self,
-        *,
-        include_fastmcp_meta: bool | None = None,
         **overrides: Any,
     ) -> SDKResourceTemplate:
         """Convert the resource template to an SDKResourceTemplate."""
@@ -199,8 +263,8 @@ class ResourceTemplate(FastMCPComponent):
             title=overrides.get("title", self.title),
             icons=overrides.get("icons", self.icons),
             annotations=overrides.get("annotations", self.annotations),
-            _meta=overrides.get(
-                "_meta", self.get_meta(include_fastmcp_meta=include_fastmcp_meta)
+            _meta=overrides.get(  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+                "_meta", self.get_meta()
             ),
         )
 
@@ -219,28 +283,96 @@ class ResourceTemplate(FastMCPComponent):
 
     @property
     def key(self) -> str:
+        """The globally unique lookup key for this template."""
+        base_key = self.make_key(self.uri_template)
+        return f"{base_key}@{self.version or ''}"
+
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this template with docket for background execution."""
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.read, names=[self.key])
+
+    async def add_to_docket(  # type: ignore[override]
+        self,
+        docket: Docket,
+        params: dict[str, Any],
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this template for background execution via docket.
+
+        Args:
+            docket: The Docket instance
+            params: Template parameters
+            fn_key: Function lookup key in Docket registry (defaults to self.key)
+            task_key: Redis storage key for the result
+            **kwargs: Additional kwargs passed to docket.add()
         """
-        The key of the component. This is used for internal bookkeeping
-        and may reflect e.g. prefixes or other identifiers. You should not depend on
-        keys having a certain value, as the same tool loaded from different
-        hierarchies of servers may have different keys.
-        """
-        return self._key or self.uri_template
+        lookup_key = fn_key or self.key
+        if task_key:
+            kwargs["key"] = task_key
+        return await docket.add(lookup_key, **kwargs)(params)
+
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.component.type": "resource_template",
+            "fastmcp.provider.type": "LocalProvider",
+        }
 
 
 class FunctionResourceTemplate(ResourceTemplate):
     """A template for dynamically creating resources."""
 
     fn: Callable[..., Any]
-    task_config: Annotated[
-        TaskConfig,
-        Field(description="Background task execution configuration (SEP-1686)."),
-    ] = Field(default_factory=lambda: TaskConfig(mode="forbidden"))
+
+    @overload
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: None = None
+    ) -> ResourceResult: ...
+
+    @overload
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: TaskMeta
+    ) -> mcp.types.CreateTaskResult: ...
+
+    async def _read(
+        self, uri: str, params: dict[str, Any], task_meta: TaskMeta | None = None
+    ) -> ResourceResult | mcp.types.CreateTaskResult:
+        """Optimized server entry point that skips ephemeral resource creation.
+
+        For FunctionResourceTemplate, we can call read() directly instead of
+        creating a temporary resource, which is more efficient.
+
+        Args:
+            uri: The concrete URI being read
+            params: Template parameters extracted from the URI
+            task_meta: If provided, execute as a background task and return
+                CreateTaskResult. If None (default), execute synchronously and
+                return ResourceResult.
+
+        Returns:
+            ResourceResult when task_meta is None.
+            CreateTaskResult when task_meta is provided.
+        """
+        from fastmcp.server.tasks.routing import check_background_task
+
+        task_result = await check_background_task(
+            component=self, task_type="template", arguments=params, task_meta=task_meta
+        )
+        if task_result:
+            return task_result
+
+        # Synchronous execution - call read() directly, skip resource creation
+        result = await self.read(arguments=params)
+        return self.convert_result(result)
 
     async def create_resource(self, uri: str, params: dict[str, Any]) -> Resource:
         """Create a resource from the template with the given parameters."""
 
-        async def resource_read_fn() -> str | bytes:
+        async def resource_read_fn() -> str | bytes | ResourceResult:
             # Call function and check if result is a coroutine
             result = await self.read(arguments=params)
             return result
@@ -252,11 +384,11 @@ class FunctionResourceTemplate(ResourceTemplate):
             description=self.description,
             mime_type=self.mime_type,
             tags=self.tags,
-            enabled=self.enabled,
             task=self.task_config,
+            auth=self.auth,
         )
 
-    async def read(self, arguments: dict[str, Any]) -> str | bytes:
+    async def read(self, arguments: dict[str, Any]) -> str | bytes | ResourceResult:
         """Read the resource content."""
         # Type coercion for query parameters (which arrive as strings)
         kwargs = arguments.copy()
@@ -287,21 +419,57 @@ class FunctionResourceTemplate(ResourceTemplate):
 
         return result
 
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this template with docket for background execution.
+
+        FunctionResourceTemplate registers the underlying function, which has the
+        user's Depends parameters for docket to resolve.
+        """
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.fn, names=[self.key])
+
+    async def add_to_docket(
+        self,
+        docket: Docket,
+        params: dict[str, Any],
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this template for background execution via docket.
+
+        FunctionResourceTemplate splats the params dict since .fn expects **kwargs.
+
+        Args:
+            docket: The Docket instance
+            params: Template parameters
+            fn_key: Function lookup key in Docket registry (defaults to self.key)
+            task_key: Redis storage key for the result
+            **kwargs: Additional kwargs passed to docket.add()
+        """
+        lookup_key = fn_key or self.key
+        if task_key:
+            kwargs["key"] = task_key
+        return await docket.add(lookup_key, **kwargs)(**params)
+
     @classmethod
     def from_function(
         cls,
         fn: Callable[..., Any],
         uri_template: str,
         name: str | None = None,
+        version: str | int | None = None,
         title: str | None = None,
         description: str | None = None,
         icons: list[Icon] | None = None,
         mime_type: str | None = None,
         tags: set[str] | None = None,
-        enabled: bool | None = None,
         annotations: Annotations | None = None,
         meta: dict[str, Any] | None = None,
         task: bool | TaskConfig | None = None,
+        auth: AuthCheckCallable | list[AuthCheckCallable] | None = None,
     ) -> FunctionResourceTemplate:
         """Create a template from a function."""
 
@@ -388,6 +556,9 @@ class FunctionResourceTemplate(ResourceTemplate):
         if isinstance(fn, staticmethod):
             fn = fn.__func__
 
+        # Transform Context type annotations to Depends() for unified DI
+        fn = transform_context_annotations(fn)
+
         wrapper_fn = without_injected_parameters(fn)
         type_adapter = get_cached_typeadapter(wrapper_fn)
         parameters = type_adapter.json_schema()
@@ -399,6 +570,7 @@ class FunctionResourceTemplate(ResourceTemplate):
         return cls(
             uri_template=uri_template,
             name=func_name,
+            version=str(version) if version is not None else None,
             title=title,
             description=description,
             icons=icons,
@@ -406,8 +578,8 @@ class FunctionResourceTemplate(ResourceTemplate):
             fn=fn,
             parameters=parameters,
             tags=tags or set(),
-            enabled=enabled if enabled is not None else True,
             annotations=annotations,
             meta=meta,
             task_config=task_config,
+            auth=auth,
         )

fastmcp/resources/types.py

@@ -12,7 +12,7 @@ from pydantic import Field, ValidationInfo
 from typing_extensions import override
 
 from fastmcp.exceptions import ResourceError
-from fastmcp.resources.resource import Resource
+from fastmcp.resources.resource import Resource, ResourceContent, ResourceResult
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger(__name__)
@@ -23,9 +23,11 @@ class TextResource(Resource):
 
     text: str = Field(description="Text content of the resource")
 
-    async def read(self) -> str:
+    async def read(self) -> ResourceResult:
         """Read the text content."""
-        return self.text
+        return ResourceResult(
+            contents=[ResourceContent(content=self.text, mime_type=self.mime_type)]
+        )
 
 
 class BinaryResource(Resource):
@@ -33,9 +35,11 @@ class BinaryResource(Resource):
 
     data: bytes = Field(description="Binary content of the resource")
 
-    async def read(self) -> bytes:
+    async def read(self) -> ResourceResult:
         """Read the binary content."""
-        return self.data
+        return ResourceResult(
+            contents=[ResourceContent(content=self.data, mime_type=self.mime_type)]
+        )
 
 
 class FileResource(Resource):
@@ -76,12 +80,16 @@ class FileResource(Resource):
         return not mime_type.startswith("text/")
 
     @override
-    async def read(self) -> str | bytes:
+    async def read(self) -> ResourceResult:
         """Read the file content."""
         try:
             if self.is_binary:
-                return await self._async_path.read_bytes()
-            return await self._async_path.read_text()
+                content: str | bytes = await self._async_path.read_bytes()
+            else:
+                content = await self._async_path.read_text()
+            return ResourceResult(
+                contents=[ResourceContent(content=content, mime_type=self.mime_type)]
+            )
         except Exception as e:
             raise ResourceError(f"Error reading file {self.path}") from e
 
@@ -95,12 +103,16 @@ class HttpResource(Resource):
     )
 
     @override
-    async def read(self) -> str | bytes:
+    async def read(self) -> ResourceResult:
         """Read the HTTP content."""
         async with httpx.AsyncClient() as client:
             response = await client.get(self.url)
             _ = response.raise_for_status()
-            return response.text
+            return ResourceResult(
+                contents=[
+                    ResourceContent(content=response.text, mime_type=self.mime_type)
+                ]
+            )
 
 
 class DirectoryResource(Resource):
@@ -145,13 +157,16 @@ class DirectoryResource(Resource):
             raise ResourceError(f"Error listing directory {self.path}") from e
 
     @override
-    async def read(self) -> str:  # Always returns JSON string
+    async def read(self) -> ResourceResult:
         """Read the directory listing."""
         try:
             files: list[Path] = await self.list_files()
 
             file_list = [str(f.relative_to(self.path)) for f in files]
 
-            return json.dumps({"files": file_list}, indent=2)
+            content = json.dumps({"files": file_list}, indent=2)
+            return ResourceResult(
+                contents=[ResourceContent(content=content, mime_type=self.mime_type)]
+            )
         except Exception as e:
             raise ResourceError(f"Error reading directory {self.path}") from e

fastmcp/server/__init__.py

@@ -1,6 +1,6 @@
-from .server import FastMCP
 from .context import Context
+from .server import FastMCP, create_proxy
 from . import dependencies
 
 
-__all__ = ["Context", "FastMCP"]
+__all__ = ["Context", "FastMCP", "create_proxy"]

fastmcp/server/auth/__init__.py

@@ -5,6 +5,14 @@ from .auth import (
     AccessToken,
     AuthProvider,
 )
+from .authorization import (
+    AuthCheck,
+    AuthContext,
+    require_auth,
+    require_scopes,
+    restrict_tag,
+    run_auth_checks,
+)
 from .providers.debug import DebugTokenVerifier
 from .providers.jwt import JWTVerifier, StaticTokenVerifier
 from .oauth_proxy import OAuthProxy
@@ -13,6 +21,8 @@ from .oidc_proxy import OIDCProxy
 
 __all__ = [
     "AccessToken",
+    "AuthCheck",
+    "AuthContext",
     "AuthProvider",
     "DebugTokenVerifier",
     "JWTVerifier",
@@ -22,4 +32,8 @@ __all__ = [
     "RemoteAuthProvider",
     "StaticTokenVerifier",
     "TokenVerifier",
+    "require_auth",
+    "require_scopes",
+    "restrict_tag",
+    "run_auth_checks",
 ]

fastmcp/server/auth/auth.py

@@ -47,19 +47,19 @@ class AccessToken(_SDKAccessToken):
 
 
 class TokenHandler(_SDKTokenHandler):
-    """TokenHandler that returns OAuth 2.1 compliant error responses.
+    """TokenHandler that returns MCP-compliant error responses.
 
-    The MCP SDK returns `unauthorized_client` for client authentication failures.
-    However, per RFC 6749 Section 5.2, authentication failures should return
-    `invalid_client` with HTTP 401, not `unauthorized_client`.
+    This handler addresses two SDK issues:
 
-    This distinction matters: `unauthorized_client` means "client exists but
-    can't do this", while `invalid_client` means "client doesn't exist or
-    credentials are wrong". Claude's OAuth client uses this to decide whether
-    to re-register.
+    1. Error code: The SDK returns `unauthorized_client` for client authentication
+       failures, but RFC 6749 Section 5.2 requires `invalid_client` with HTTP 401.
+       This distinction matters for client re-registration behavior.
 
-    This handler transforms 401 responses with `unauthorized_client` to use
-    `invalid_client` instead, making the error semantics correct per OAuth spec.
+    2. Status code: The SDK returns HTTP 400 for all token errors including
+       `invalid_grant` (expired/invalid tokens). However, the MCP spec requires:
+       "Invalid or expired tokens MUST receive a HTTP 401 response."
+
+    This handler transforms responses to be compliant with both OAuth 2.1 and MCP specs.
     """
 
     async def handle(self, request: Any):
@@ -85,6 +85,26 @@ class TokenHandler(_SDKTokenHandler):
             except (json.JSONDecodeError, AttributeError):
                 pass  # Not JSON or unexpected format, return as-is
 
+        # Transform 400 invalid_grant -> 401 for expired/invalid tokens
+        # Per MCP spec: "Invalid or expired tokens MUST receive a HTTP 401 response."
+        if response.status_code == 400:
+            try:
+                body = json.loads(response.body)
+                if body.get("error") == "invalid_grant":
+                    return PydanticJSONResponse(
+                        content=TokenErrorResponse(
+                            error="invalid_grant",
+                            error_description=body.get("error_description"),
+                        ),
+                        status_code=401,
+                        headers={
+                            "Cache-Control": "no-store",
+                            "Pragma": "no-cache",
+                        },
+                    )
+            except (json.JSONDecodeError, AttributeError):
+                pass  # Not JSON or unexpected format, return as-is
+
         return response