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

fastmcp/resources/resource.py

@@ -2,10 +2,19 @@
 
 from __future__ import annotations
 
-import inspect
+import base64
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Annotated, Any
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, overload
 
+import mcp.types
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+
+    from fastmcp.resources.function_resource import FunctionResource
+
+import pydantic
 import pydantic_core
 from mcp.types import Annotations, Icon
 from mcp.types import Resource as SDKResource
@@ -19,20 +28,189 @@ from pydantic import (
 )
 from typing_extensions import Self
 
-from fastmcp.server.dependencies import get_context, without_injected_parameters
-from fastmcp.server.tasks.config import TaskConfig
+from fastmcp.server.tasks.config import TaskConfig, TaskMeta
+from fastmcp.tools.tool import AuthCheckCallable
 from fastmcp.utilities.components import FastMCPComponent
-from fastmcp.utilities.types import (
-    get_fn_name,
-)
 
-if TYPE_CHECKING:
-    pass
+
+class ResourceContent(pydantic.BaseModel):
+    """Wrapper for resource content with optional MIME type and metadata.
+
+    Accepts any value for content - strings and bytes pass through directly,
+    other types (dict, list, BaseModel, etc.) are automatically JSON-serialized.
+
+    Example:
+        ```python
+        from fastmcp.resources import ResourceContent
+
+        # String content
+        ResourceContent("plain text")
+
+        # Binary content
+        ResourceContent(b"binary data", mime_type="application/octet-stream")
+
+        # Auto-serialized to JSON
+        ResourceContent({"key": "value"})
+        ResourceContent(["a", "b", "c"])
+        ```
+    """
+
+    content: str | bytes
+    mime_type: str | None = None
+    meta: dict[str, Any] | None = None
+
+    def __init__(
+        self,
+        content: Any,
+        mime_type: str | None = None,
+        meta: dict[str, Any] | None = None,
+    ):
+        """Create ResourceContent with automatic serialization.
+
+        Args:
+            content: The content value. str and bytes pass through directly.
+                     Other types (dict, list, BaseModel) are JSON-serialized.
+            mime_type: Optional MIME type. Defaults based on content type:
+                       str → "text/plain", bytes → "application/octet-stream",
+                       other → "application/json"
+            meta: Optional metadata dictionary.
+        """
+        if isinstance(content, str):
+            normalized_content: str | bytes = content
+            mime_type = mime_type or "text/plain"
+        elif isinstance(content, bytes):
+            normalized_content = content
+            mime_type = mime_type or "application/octet-stream"
+        else:
+            # dict, list, BaseModel, etc → JSON
+            normalized_content = pydantic_core.to_json(content, fallback=str).decode()
+            mime_type = mime_type or "application/json"
+
+        super().__init__(content=normalized_content, mime_type=mime_type, meta=meta)
+
+    def to_mcp_resource_contents(
+        self, uri: AnyUrl | str
+    ) -> mcp.types.TextResourceContents | mcp.types.BlobResourceContents:
+        """Convert to MCP resource contents type.
+
+        Args:
+            uri: The URI of the resource (required by MCP types)
+
+        Returns:
+            TextResourceContents for str content, BlobResourceContents for bytes
+        """
+        if isinstance(self.content, str):
+            return mcp.types.TextResourceContents(
+                uri=AnyUrl(uri) if isinstance(uri, str) else uri,
+                text=self.content,
+                mimeType=self.mime_type or "text/plain",
+                _meta=self.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+            )
+        else:
+            return mcp.types.BlobResourceContents(
+                uri=AnyUrl(uri) if isinstance(uri, str) else uri,
+                blob=base64.b64encode(self.content).decode(),
+                mimeType=self.mime_type or "application/octet-stream",
+                _meta=self.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+            )
+
+
+class ResourceResult(pydantic.BaseModel):
+    """Canonical result type for resource reads.
+
+    Provides explicit control over resource responses: multiple content items,
+    per-item MIME types, and metadata at both the item and result level.
+
+    Accepts:
+        - str: Wrapped as single ResourceContent (text/plain)
+        - bytes: Wrapped as single ResourceContent (application/octet-stream)
+        - list[ResourceContent]: Used directly for multiple items or custom MIME types
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.resources import ResourceResult, ResourceContent
+
+        mcp = FastMCP()
+
+        # Simple string content
+        @mcp.resource("data://simple")
+        def get_simple() -> ResourceResult:
+            return ResourceResult("hello world")
+
+        # Multiple items with custom MIME types
+        @mcp.resource("data://items")
+        def get_items() -> ResourceResult:
+            return ResourceResult(
+                contents=[
+                    ResourceContent({"key": "value"}),  # auto-serialized to JSON
+                    ResourceContent(b"binary data"),
+                ],
+                meta={"count": 2}
+            )
+        ```
+    """
+
+    contents: list[ResourceContent]
+    meta: dict[str, Any] | None = None
+
+    def __init__(
+        self,
+        contents: str | bytes | list[ResourceContent],
+        meta: dict[str, Any] | None = None,
+    ):
+        """Create ResourceResult.
+
+        Args:
+            contents: String, bytes, or list of ResourceContent objects.
+            meta: Optional metadata about the resource result.
+        """
+        normalized = self._normalize_contents(contents)
+        super().__init__(contents=normalized, meta=meta)
+
+    @staticmethod
+    def _normalize_contents(
+        contents: str | bytes | list[ResourceContent],
+    ) -> list[ResourceContent]:
+        """Normalize input to list[ResourceContent]."""
+        if isinstance(contents, str):
+            return [ResourceContent(contents)]
+        if isinstance(contents, bytes):
+            return [ResourceContent(contents)]
+        if isinstance(contents, list):
+            # Validate all items are ResourceContent
+            for i, item in enumerate(contents):
+                if not isinstance(item, ResourceContent):
+                    raise TypeError(
+                        f"contents[{i}] must be ResourceContent, got {type(item).__name__}. "
+                        f"Use ResourceContent({item!r}) to wrap the value."
+                    )
+            return contents
+        raise TypeError(
+            f"contents must be str, bytes, or list[ResourceContent], got {type(contents).__name__}"
+        )
+
+    def to_mcp_result(self, uri: AnyUrl | str) -> mcp.types.ReadResourceResult:
+        """Convert to MCP ReadResourceResult.
+
+        Args:
+            uri: The URI of the resource (required by MCP types)
+
+        Returns:
+            MCP ReadResourceResult with converted contents
+        """
+        mcp_contents = [item.to_mcp_resource_contents(uri) for item in self.contents]
+        return mcp.types.ReadResourceResult(
+            contents=mcp_contents,
+            _meta=self.meta,  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
+        )
 
 
 class Resource(FastMCPComponent):
     """Base class for all resources."""
 
+    KEY_PREFIX: ClassVar[str] = "resource"
+
     model_config = ConfigDict(validate_default=True)
 
     uri: Annotated[AnyUrl, UrlConstraints(host_required=False)] = Field(
@@ -47,51 +225,47 @@ class Resource(FastMCPComponent):
         Annotations | None,
         Field(description="Optional annotations about the resource's behavior"),
     ] = None
+    auth: Annotated[
+        AuthCheckCallable | list[AuthCheckCallable] | None,
+        Field(description="Authorization checks for this resource", exclude=True),
+    ] = None
 
-    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
+    @classmethod
     def from_function(
+        cls,
         fn: Callable[..., Any],
         uri: str | AnyUrl,
+        *,
         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,
     ) -> FunctionResource:
+        from fastmcp.resources.function_resource import (
+            FunctionResource,
+        )
+
         return FunctionResource.from_function(
             fn=fn,
             uri=uri,
             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")
@@ -113,18 +287,76 @@ class Resource(FastMCPComponent):
             raise ValueError("Either name or uri must be provided")
         return self
 
-    async def read(self) -> str | bytes:
+    async def read(
+        self,
+    ) -> str | bytes | ResourceResult:
         """Read the resource content.
 
-        This method is not implemented in the base Resource class and must be
-        implemented by subclasses.
+        Subclasses implement this to return resource data. Supported return types:
+            - str: Text content
+            - bytes: Binary content
+            - ResourceResult: Full control over contents and result-level meta
         """
         raise NotImplementedError("Subclasses must implement read()")
 
+    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, task_meta: None = None) -> ResourceResult: ...
+
+    @overload
+    async def _read(self, task_meta: TaskMeta) -> mcp.types.CreateTaskResult: ...
+
+    async def _read(
+        self, task_meta: TaskMeta | None = None
+    ) -> ResourceResult | mcp.types.CreateTaskResult:
+        """Server entry point that handles task routing.
+
+        This allows ANY Resource subclass to support background execution by setting
+        task_config.mode to "supported" or "required". The server calls this
+        method instead of read() directly.
+
+        Args:
+            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, FastMCPProviderResource 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="resource", arguments=None, task_meta=task_meta
+        )
+        if task_result:
+            return task_result
+
+        # Synchronous execution - convert result to ResourceResult
+        result = await self.read()
+        return self.convert_result(result)
+
     def to_mcp_resource(
         self,
-        *,
-        include_fastmcp_meta: bool | None = None,
         **overrides: Any,
     ) -> SDKResource:
         """Convert the resource to an SDKResource."""
@@ -137,8 +369,8 @@ class Resource(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()
             ),
         )
 
@@ -147,94 +379,72 @@ class Resource(FastMCPComponent):
 
     @property
     def key(self) -> str:
-        """
-        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 str(self.uri)
+        """The globally unique lookup key for this resource."""
+        base_key = self.make_key(str(self.uri))
+        return f"{base_key}@{self.version or ''}"
 
+    def register_with_docket(self, docket: Docket) -> None:
+        """Register this resource with docket for background execution."""
+        if not self.task_config.supports_tasks():
+            return
+        docket.register(self.read, names=[self.key])
 
-class FunctionResource(Resource):
-    """A resource that defers data loading by wrapping a function.
+    async def add_to_docket(  # type: ignore[override]
+        self,
+        docket: Docket,
+        *,
+        fn_key: str | None = None,
+        task_key: str | None = None,
+        **kwargs: Any,
+    ) -> Execution:
+        """Schedule this resource for background execution via docket.
+
+        Args:
+            docket: The Docket instance
+            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)()
 
-    The function is only called when the resource is read, allowing for lazy loading
-    of potentially expensive data. This is particularly useful when listing resources,
-    as the function won't be called until the resource is actually accessed.
+    def get_span_attributes(self) -> dict[str, Any]:
+        return super().get_span_attributes() | {
+            "fastmcp.component.type": "resource",
+            "fastmcp.provider.type": "LocalProvider",
+        }
 
-    The function can return:
-    - str for text content (default)
-    - bytes for binary content
-    - other types will be converted to JSON
-    """
 
-    fn: Callable[..., Any]
-    task_config: Annotated[
-        TaskConfig,
-        Field(description="Background task execution configuration (SEP-1686)."),
-    ] = Field(default_factory=lambda: TaskConfig(mode="forbidden"))
+__all__ = [
+    "Resource",
+    "ResourceContent",
+    "ResourceResult",
+]
 
-    @classmethod
-    def from_function(
-        cls,
-        fn: Callable[..., Any],
-        uri: str | AnyUrl,
-        name: str | 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,
-    ) -> FunctionResource:
-        """Create a FunctionResource from a function."""
-        if isinstance(uri, str):
-            uri = AnyUrl(uri)
 
-        func_name = name or get_fn_name(fn)
+def __getattr__(name: str) -> Any:
+    """Deprecated re-exports for backwards compatibility."""
+    deprecated_exports = {
+        "FunctionResource": "FunctionResource",
+        "resource": "resource",
+    }
 
-        # Normalize task to TaskConfig and validate
-        if task is None:
-            task_config = TaskConfig(mode="forbidden")
-        elif isinstance(task, bool):
-            task_config = TaskConfig.from_bool(task)
-        else:
-            task_config = task
-        task_config.validate_function(fn, func_name)
+    if name in deprecated_exports:
+        import warnings
 
-        # Wrap fn to handle dependency resolution internally
-        wrapped_fn = without_injected_parameters(fn)
+        import fastmcp
 
-        return cls(
-            fn=wrapped_fn,
-            uri=uri,
-            name=name or get_fn_name(fn),
-            title=title,
-            description=description or inspect.getdoc(fn),
-            icons=icons,
-            mime_type=mime_type or "text/plain",
-            tags=tags or set(),
-            enabled=enabled if enabled is not None else True,
-            annotations=annotations,
-            meta=meta,
-            task_config=task_config,
-        )
+        if fastmcp.settings.deprecation_warnings:
+            warnings.warn(
+                f"Importing {name} from fastmcp.resources.resource is deprecated. "
+                f"Import from fastmcp.resources.function_resource instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        from fastmcp.resources import function_resource
 
-    async def read(self) -> str | bytes:
-        """Read the resource by calling the wrapped function."""
-        # self.fn is wrapped by without_injected_parameters which handles
-        # dependency resolution internally
-        result = self.fn()
-        if inspect.isawaitable(result):
-            result = await result
-
-        if isinstance(result, Resource):
-            return await result.read()
-        elif isinstance(result, bytes | str):
-            return result
-        else:
-            return pydantic_core.to_json(result, fallback=str).decode()
+        return getattr(function_resource, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")