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

fastmcp/server/tasks/__init__.py

@@ -4,7 +4,7 @@ This module implements protocol-level background task execution for MCP servers.
 """
 
 from fastmcp.server.tasks.capabilities import get_task_capabilities
-from fastmcp.server.tasks.config import TaskConfig, TaskMode
+from fastmcp.server.tasks.config import TaskConfig, TaskMeta, TaskMode
 from fastmcp.server.tasks.keys import (
     build_task_key,
     get_client_task_id_from_key,
@@ -13,6 +13,7 @@ from fastmcp.server.tasks.keys import (
 
 __all__ = [
     "TaskConfig",
+    "TaskMeta",
     "TaskMode",
     "build_task_key",
     "get_client_task_id_from_key",

fastmcp/server/tasks/capabilities.py

@@ -1,5 +1,7 @@
 """SEP-1686 task capabilities declaration."""
 
+from importlib.util import find_spec
+
 from mcp.types import (
     ServerTasksCapability,
     ServerTasksRequestsCapability,
@@ -10,15 +12,25 @@ from mcp.types import (
 )
 
 
-def get_task_capabilities() -> ServerTasksCapability:
+def _is_docket_available() -> bool:
+    """Check if pydocket is installed (local to avoid circular import)."""
+    return find_spec("docket") is not None
+
+
+def get_task_capabilities() -> ServerTasksCapability | None:
     """Return the SEP-1686 task capabilities.
 
     Returns task capabilities as a first-class ServerCapabilities field,
     declaring support for list, cancel, and request operations per SEP-1686.
 
+    Returns None if pydocket is not installed (no task support).
+
     Note: prompts/resources are passed via extra_data since the SDK types
     don't include them yet (FastMCP supports them ahead of the spec).
     """
+    if not _is_docket_available():
+        return None
+
     return ServerTasksCapability(
         list=TasksListCapability(),
         cancel=TasksCancelCapability(),

fastmcp/server/tasks/config.py

@@ -7,13 +7,36 @@ handle task-augmented execution as specified in SEP-1686.
 from __future__ import annotations
 
 import inspect
+import warnings
 from collections.abc import Callable
 from dataclasses import dataclass
+from datetime import timedelta
 from typing import Any, Literal
 
 # Task execution modes per SEP-1686 / MCP ToolExecution.taskSupport
 TaskMode = Literal["forbidden", "optional", "required"]
 
+# Default values for task metadata (single source of truth)
+DEFAULT_POLL_INTERVAL = timedelta(seconds=5)  # Default poll interval
+DEFAULT_POLL_INTERVAL_MS = int(DEFAULT_POLL_INTERVAL.total_seconds() * 1000)
+DEFAULT_TTL_MS = 60_000  # Default TTL in milliseconds
+
+
+@dataclass
+class TaskMeta:
+    """Metadata for task-augmented execution requests.
+
+    When passed to call_tool/read_resource/get_prompt, signals that
+    the operation should be submitted as a background task.
+
+    Attributes:
+        ttl: Client-requested TTL in milliseconds. If None, uses server default.
+        fn_key: Docket routing key. Auto-derived from component name if None.
+    """
+
+    ttl: int | None = None
+    fn_key: str | None = None
+
 
 @dataclass
 class TaskConfig:
@@ -28,6 +51,11 @@ class TaskConfig:
     - "required": Component requires task execution. Clients must request task
       augmentation; server returns -32601 if they don't.
 
+    Important:
+        Task-enabled components must be available at server startup to be
+        registered with all Docket workers. Components added dynamically after
+        startup will not be registered for background execution.
+
     Example:
         ```python
         from fastmcp import FastMCP
@@ -46,6 +74,7 @@ class TaskConfig:
     """
 
     mode: TaskMode = "optional"
+    poll_interval: timedelta = DEFAULT_POLL_INTERVAL
 
     @classmethod
     def from_bool(cls, value: bool) -> TaskConfig:
@@ -59,22 +88,41 @@ class TaskConfig:
         """
         return cls(mode="optional" if value else "forbidden")
 
+    def supports_tasks(self) -> bool:
+        """Check if this component supports task execution.
+
+        Returns:
+            True if mode is "optional" or "required", False if "forbidden".
+        """
+        return self.mode != "forbidden"
+
     def validate_function(self, fn: Callable[..., Any], name: str) -> None:
         """Validate that function is compatible with this task config.
 
-        Task execution requires async functions. Raises ValueError if mode
-        is "optional" or "required" but function is synchronous.
+        Task execution requires:
+        1. fastmcp[tasks] to be installed (pydocket)
+        2. Async functions
+
+        Raises ImportError if mode is "optional" or "required" but pydocket
+        is not installed. Raises ValueError if function is synchronous.
 
         Args:
             fn: The function to validate (handles callable classes and staticmethods).
             name: Name for error messages.
 
         Raises:
+            ImportError: If task execution is enabled but pydocket not installed.
             ValueError: If task execution is enabled but function is sync.
         """
-        if self.mode == "forbidden":
+        if not self.supports_tasks():
             return
 
+        # Check that docket is available for task execution
+        # Lazy import to avoid circular: dependencies.py → http.py → tasks/__init__.py → config.py
+        from fastmcp.server.dependencies import require_docket
+
+        require_docket(f"`task=True` on function '{name}'")
+
         # Unwrap callable classes and staticmethods
         fn_to_check = fn
         if not inspect.isroutine(fn) and callable(fn):
@@ -87,3 +135,18 @@ class TaskConfig:
                 f"'{name}' uses a sync function but has task execution enabled. "
                 "Background tasks require async functions."
             )
+
+        # Warn if function uses Context - it won't be available in workers
+        from fastmcp.server.context import Context
+        from fastmcp.utilities.types import find_kwarg_by_type
+
+        context_kwarg = find_kwarg_by_type(fn_to_check, Context)
+        if context_kwarg:
+            warnings.warn(
+                f"'{name}' uses Context but has task execution enabled. "
+                "Context is not available in background task workers because "
+                "there is no active MCP session. Consider using Docket dependencies "
+                "like Progress() instead for worker-compatible functionality.",
+                UserWarning,
+                stacklevel=4,
+            )

fastmcp/server/tasks/handlers.py

@@ -8,55 +8,66 @@ from __future__ import annotations
 import uuid
 from contextlib import suppress
 from datetime import datetime, timezone
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 import mcp.types
 from mcp.shared.exceptions import McpError
 from mcp.types import INTERNAL_ERROR, ErrorData
 
 from fastmcp.server.dependencies import _current_docket, get_context
+from fastmcp.server.tasks.config import TaskMeta
 from fastmcp.server.tasks.keys import build_task_key
 
 if TYPE_CHECKING:
-    from fastmcp.server.server import FastMCP
+    from fastmcp.prompts.prompt import Prompt
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.tool import Tool
 
 # Redis mapping TTL buffer: Add 15 minutes to Docket's execution_ttl
 TASK_MAPPING_TTL_BUFFER_SECONDS = 15 * 60
 
 
-async def handle_tool_as_task(
-    server: FastMCP,
-    tool_name: str,
-    arguments: dict[str, Any],
-    task_meta: dict[str, Any],
-) -> mcp.types.CallToolResult:
-    """Handle tool execution as background task (SEP-1686).
+async def submit_to_docket(
+    task_type: Literal["tool", "resource", "template", "prompt"],
+    key: str,
+    component: Tool | Resource | ResourceTemplate | Prompt,
+    arguments: dict[str, Any] | None = None,
+    task_meta: TaskMeta | None = None,
+) -> mcp.types.CreateTaskResult:
+    """Submit any component to Docket for background execution (SEP-1686).
 
-    Queues the user's actual function to Docket (preserving signature for DI),
-    stores raw return values, converts to MCP types on retrieval.
+    Unified handler for all component types. Called by component's internal
+    methods (_run, _read, _render) when task metadata is present and mode allows.
+
+    Queues the component's method to Docket, stores raw return values,
+    and converts to MCP types on retrieval.
 
     Args:
-        server: FastMCP server instance
-        tool_name: Name of the tool to execute
-        arguments: Tool arguments
-        task_meta: Task metadata from request (contains ttl)
+        task_type: Component type for task key construction
+        key: The component key as seen by MCP layer (with namespace prefix)
+        component: The component instance (Tool, Resource, ResourceTemplate, Prompt)
+        arguments: Arguments/params (None for Resource which has no args)
+        task_meta: Task execution metadata. If task_meta.ttl is provided, it
+            overrides the server default (docket.execution_ttl).
 
     Returns:
-        CallToolResult: Task stub with task metadata in _meta
+        CreateTaskResult: Task stub with proper Task object
     """
     # Generate server-side task ID per SEP-1686 final spec (line 375-377)
     # Server MUST generate task IDs, clients no longer provide them
     server_task_id = str(uuid.uuid4())
 
     # Record creation timestamp per SEP-1686 final spec (line 430)
-    # Format as ISO 8601 / RFC 3339 timestamp
-    created_at = datetime.now(timezone.utc).isoformat()
+    created_at = datetime.now(timezone.utc)
 
-    # Get session ID and Docket
+    # Get session ID - use "internal" for programmatic calls without MCP session
     ctx = get_context()
-    session_id = ctx.session_id
+    try:
+        session_id = ctx.session_id
+    except RuntimeError:
+        session_id = "internal"
 
-    # Get Docket from ContextVar (set by Context.__aenter__ at request time)
     docket = _current_docket.get()
     if docket is None:
         raise McpError(
@@ -67,22 +78,28 @@ async def handle_tool_as_task(
         )
 
     # Build full task key with embedded metadata
-    task_key = build_task_key(session_id, server_task_id, "tool", tool_name)
+    task_key = build_task_key(session_id, server_task_id, task_type, key)
 
-    # Get the tool to access user's function
-    tool = await server.get_tool(tool_name)
+    # Determine TTL: use task_meta.ttl if provided, else docket default
+    if task_meta is not None and task_meta.ttl is not None:
+        ttl_ms = task_meta.ttl
+    else:
+        ttl_ms = int(docket.execution_ttl.total_seconds() * 1000)
+    ttl_seconds = int(ttl_ms / 1000) + TASK_MAPPING_TTL_BUFFER_SECONDS
 
-    # Store task key mapping and creation timestamp in Redis for protocol handlers
+    # Store task metadata in Redis for protocol handlers
     task_meta_key = docket.key(f"fastmcp:task:{session_id}:{server_task_id}")
     created_at_key = docket.key(
         f"fastmcp:task:{session_id}:{server_task_id}:created_at"
     )
-    ttl_seconds = int(
-        docket.execution_ttl.total_seconds() + TASK_MAPPING_TTL_BUFFER_SECONDS
+    poll_interval_key = docket.key(
+        f"fastmcp:task:{session_id}:{server_task_id}:poll_interval"
     )
+    poll_interval_ms = int(component.task_config.poll_interval.total_seconds() * 1000)
     async with docket.redis() as redis:
         await redis.set(task_meta_key, task_key, ex=ttl_seconds)
-        await redis.set(created_at_key, created_at, ex=ttl_seconds)
+        await redis.set(created_at_key, created_at.isoformat(), ex=ttl_seconds)
+        await redis.set(poll_interval_key, str(poll_interval_ms), ex=ttl_seconds)
 
     # Send notifications/tasks/created per SEP-1686 (mandatory)
     # Send BEFORE queuing to avoid race where task completes before notification
@@ -90,257 +107,32 @@ async def handle_tool_as_task(
         jsonrpc="2.0",
         method="notifications/tasks/created",
         params={},  # Empty params per spec
-        _meta={  # taskId in _meta per spec
+        _meta={  # type: ignore[call-arg]  # _meta is Pydantic alias for meta field
             "modelcontextprotocol.io/related-task": {
                 "taskId": server_task_id,
             }
         },
     )
-
-    ctx = get_context()
     with suppress(Exception):
         # Don't let notification failures break task creation
         await ctx.session.send_notification(notification)  # type: ignore[arg-type]
 
-    # Queue function to Docket by name (result storage via execution_ttl)
-    # Use tool.key which matches what was registered - prefixed for mounted tools
-    await docket.add(
-        tool.key,
-        key=task_key,
-    )(**arguments)
-
-    # Spawn subscription task to send status notifications (SEP-1686 optional feature)
-    from fastmcp.server.tasks.subscriptions import subscribe_to_task_updates
-
-    # Start subscription in session's task group (persists for connection lifetime)
-    if hasattr(ctx.session, "_subscription_task_group"):
-        tg = ctx.session._subscription_task_group  # type: ignore[attr-defined]
-        if tg:
-            tg.start_soon(  # type: ignore[union-attr]
-                subscribe_to_task_updates,
-                server_task_id,
-                task_key,
-                ctx.session,
-                docket,
-            )
-
-    # Return task stub
-    # Tasks MUST begin in "working" status per SEP-1686 final spec (line 381)
-    return mcp.types.CallToolResult(
-        content=[],
-        _meta={
-            "modelcontextprotocol.io/task": {
-                "taskId": server_task_id,
-                "status": "working",
-            }
-        },
-    )
-
-
-async def handle_prompt_as_task(
-    server: FastMCP,
-    prompt_name: str,
-    arguments: dict[str, Any] | None,
-    task_meta: dict[str, Any],
-) -> mcp.types.GetPromptResult:
-    """Handle prompt execution as background task (SEP-1686).
-
-    Queues the user's actual function to Docket (preserving signature for DI).
-
-    Args:
-        server: FastMCP server instance
-        prompt_name: Name of the prompt to execute
-        arguments: Prompt arguments
-        task_meta: Task metadata from request (contains ttl)
-
-    Returns:
-        GetPromptResult: Task stub with task metadata in _meta
-    """
-    # Generate server-side task ID per SEP-1686 final spec (line 375-377)
-    # Server MUST generate task IDs, clients no longer provide them
-    server_task_id = str(uuid.uuid4())
-
-    # Record creation timestamp per SEP-1686 final spec (line 430)
-    # Format as ISO 8601 / RFC 3339 timestamp
-    created_at = datetime.now(timezone.utc).isoformat()
-
-    # Get session ID and Docket
-    ctx = get_context()
-    session_id = ctx.session_id
-
-    # Get Docket from ContextVar (set by Context.__aenter__ at request time)
-    docket = _current_docket.get()
-    if docket is None:
-        raise McpError(
-            ErrorData(
-                code=INTERNAL_ERROR,
-                message="Background tasks require a running FastMCP server context",
-            )
-        )
-
-    # Build full task key with embedded metadata
-    task_key = build_task_key(session_id, server_task_id, "prompt", prompt_name)
-
-    # Get the prompt
-    prompt = await server.get_prompt(prompt_name)
-
-    # Store task key mapping and creation timestamp in Redis for protocol handlers
-    task_meta_key = docket.key(f"fastmcp:task:{session_id}:{server_task_id}")
-    created_at_key = docket.key(
-        f"fastmcp:task:{session_id}:{server_task_id}:created_at"
-    )
-    ttl_seconds = int(
-        docket.execution_ttl.total_seconds() + TASK_MAPPING_TTL_BUFFER_SECONDS
-    )
-    async with docket.redis() as redis:
-        await redis.set(task_meta_key, task_key, ex=ttl_seconds)
-        await redis.set(created_at_key, created_at, ex=ttl_seconds)
-
-    # Send notifications/tasks/created per SEP-1686 (mandatory)
-    # Send BEFORE queuing to avoid race where task completes before notification
-    notification = mcp.types.JSONRPCNotification(
-        jsonrpc="2.0",
-        method="notifications/tasks/created",
-        params={},
-        _meta={
-            "modelcontextprotocol.io/related-task": {
-                "taskId": server_task_id,
-            }
-        },
-    )
-    with suppress(Exception):
-        await ctx.session.send_notification(notification)  # type: ignore[arg-type]
-
-    # Queue function to Docket by name (result storage via execution_ttl)
-    # Use prompt.key which matches what was registered - prefixed for mounted prompts
-    await docket.add(
-        prompt.key,
-        key=task_key,
-    )(**(arguments or {}))
-
-    # Spawn subscription task to send status notifications (SEP-1686 optional feature)
-    from fastmcp.server.tasks.subscriptions import subscribe_to_task_updates
-
-    # Start subscription in session's task group (persists for connection lifetime)
-    if hasattr(ctx.session, "_subscription_task_group"):
-        tg = ctx.session._subscription_task_group  # type: ignore[attr-defined]
-        if tg:
-            tg.start_soon(  # type: ignore[union-attr]
-                subscribe_to_task_updates,
-                server_task_id,
-                task_key,
-                ctx.session,
-                docket,
-            )
-
-    # Return task stub
-    # Tasks MUST begin in "working" status per SEP-1686 final spec (line 381)
-    return mcp.types.GetPromptResult(
-        description="",
-        messages=[],
-        _meta={
-            "modelcontextprotocol.io/task": {
-                "taskId": server_task_id,
-                "status": "working",
-            }
-        },
-    )
-
-
-async def handle_resource_as_task(
-    server: FastMCP,
-    uri: str,
-    resource,  # Resource or ResourceTemplate
-    task_meta: dict[str, Any],
-) -> mcp.types.ServerResult:
-    """Handle resource read as background task (SEP-1686).
-
-    Queues the user's actual function to Docket.
-
-    Args:
-        server: FastMCP server instance
-        uri: Resource URI
-        resource: Resource or ResourceTemplate object
-        task_meta: Task metadata from request (contains ttl)
-
-    Returns:
-        ServerResult with ReadResourceResult stub
-    """
-    # Generate server-side task ID per SEP-1686 final spec (line 375-377)
-    # Server MUST generate task IDs, clients no longer provide them
-    server_task_id = str(uuid.uuid4())
-
-    # Record creation timestamp per SEP-1686 final spec (line 430)
-    # Format as ISO 8601 / RFC 3339 timestamp
-    created_at = datetime.now(timezone.utc).isoformat()
-
-    # Get session ID and Docket
-    ctx = get_context()
-    session_id = ctx.session_id
-
-    # Get Docket from ContextVar (set by Context.__aenter__ at request time)
-    docket = _current_docket.get()
-    if docket is None:
-        raise McpError(
-            ErrorData(
-                code=INTERNAL_ERROR,
-                message="Background tasks require a running FastMCP server context",
-            )
-        )
-
-    # Build full task key with embedded metadata (use original URI)
-    task_key = build_task_key(session_id, server_task_id, "resource", str(uri))
-
-    # Store task key mapping and creation timestamp in Redis for protocol handlers
-    task_meta_key = docket.key(f"fastmcp:task:{session_id}:{server_task_id}")
-    created_at_key = docket.key(
-        f"fastmcp:task:{session_id}:{server_task_id}:created_at"
-    )
-    ttl_seconds = int(
-        docket.execution_ttl.total_seconds() + TASK_MAPPING_TTL_BUFFER_SECONDS
-    )
-    async with docket.redis() as redis:
-        await redis.set(task_meta_key, task_key, ex=ttl_seconds)
-        await redis.set(created_at_key, created_at, ex=ttl_seconds)
-
-    # Send notifications/tasks/created per SEP-1686 (mandatory)
-    # Send BEFORE queuing to avoid race where task completes before notification
-    notification = mcp.types.JSONRPCNotification(
-        jsonrpc="2.0",
-        method="notifications/tasks/created",
-        params={},
-        _meta={
-            "modelcontextprotocol.io/related-task": {
-                "taskId": server_task_id,
-            }
-        },
-    )
-    with suppress(Exception):
-        await ctx.session.send_notification(notification)  # type: ignore[arg-type]
-
-    # Queue function to Docket by name (result storage via execution_ttl)
-    # Use resource.name which matches what was registered - prefixed for mounted resources
-    # For templates, extract URI params and pass them to the function
-    from fastmcp.resources.template import FunctionResourceTemplate, match_uri_template
-
-    if isinstance(resource, FunctionResourceTemplate):
-        params = match_uri_template(uri, resource.uri_template) or {}
-        await docket.add(
-            resource.name,
-            key=task_key,
-        )(**params)
+    # Queue function to Docket by key (result storage via execution_ttl)
+    # Use component.add_to_docket() which handles calling conventions
+    # `fn_key` is the function lookup key (e.g., "child_multiply")
+    # `task_key` is the task result key (e.g., "fastmcp:task:{session}:{task_id}:tool:child_multiply")
+    # Resources don't take arguments; tools/prompts/templates always pass arguments (even if None/empty)
+    if task_type == "resource":
+        await component.add_to_docket(docket, fn_key=key, task_key=task_key)  # type: ignore[call-arg]
     else:
-        await docket.add(
-            resource.name,
-            key=task_key,
-        )()
+        await component.add_to_docket(docket, arguments, fn_key=key, task_key=task_key)  # type: ignore[call-arg]
 
     # Spawn subscription task to send status notifications (SEP-1686 optional feature)
     from fastmcp.server.tasks.subscriptions import subscribe_to_task_updates
 
     # Start subscription in session's task group (persists for connection lifetime)
     if hasattr(ctx.session, "_subscription_task_group"):
-        tg = ctx.session._subscription_task_group  # type: ignore[attr-defined]
+        tg = ctx.session._subscription_task_group
         if tg:
             tg.start_soon(  # type: ignore[union-attr]
                 subscribe_to_task_updates,
@@ -348,18 +140,18 @@ async def handle_resource_as_task(
                 task_key,
                 ctx.session,
                 docket,
+                poll_interval_ms,
             )
 
-    # Return task stub
+    # Return CreateTaskResult with proper Task object
     # Tasks MUST begin in "working" status per SEP-1686 final spec (line 381)
-    return mcp.types.ServerResult(
-        mcp.types.ReadResourceResult(
-            contents=[],
-            _meta={
-                "modelcontextprotocol.io/task": {
-                    "taskId": server_task_id,
-                    "status": "working",
-                }
-            },
+    return mcp.types.CreateTaskResult(
+        task=mcp.types.Task(
+            taskId=server_task_id,
+            status="working",
+            createdAt=created_at,
+            lastUpdatedAt=created_at,
+            ttl=ttl_ms,
+            pollInterval=poll_interval_ms,
         )
     )

fastmcp/server/tasks/keys.py

@@ -1,7 +1,7 @@
 """Task key management for SEP-1686 background tasks.
 
 Task keys encode security scoping and metadata in the Docket key format:
-    {session_id}:{client_task_id}:{task_type}:{component_identifier}
+    `{session_id}:{client_task_id}:{task_type}:{component_identifier}`
 
 This format provides:
 - Session-based security scoping (prevents cross-session access)
@@ -20,7 +20,7 @@ def build_task_key(
 ) -> str:
     """Build Docket task key with embedded metadata.
 
-    Format: {session_id}:{client_task_id}:{task_type}:{component_identifier}
+    Format: `{session_id}:{client_task_id}:{task_type}:{component_identifier}`
 
     The component_identifier is URI-encoded to handle special characters (colons, slashes, etc.).
 
@@ -55,12 +55,10 @@ def parse_task_key(task_key: str) -> dict[str, str]:
 
     Examples:
         >>> parse_task_key("session123:task456:tool:my_tool")
-        {'session_id': 'session123', 'client_task_id': 'task456',
-         'task_type': 'tool', 'component_identifier': 'my_tool'}
+        `{'session_id': 'session123', 'client_task_id': 'task456', 'task_type': 'tool', 'component_identifier': 'my_tool'}`
 
         >>> parse_task_key("session123:task456:resource:file%3A%2F%2Fdata.txt")
-        {'session_id': 'session123', 'client_task_id': 'task456',
-         'task_type': 'resource', 'component_identifier': 'file://data.txt'}
+        `{'session_id': 'session123', 'client_task_id': 'task456', 'task_type': 'resource', 'component_identifier': 'file://data.txt'}`
     """
     parts = task_key.split(":", 3)
     if len(parts) != 4: