fastmcp 2.12.5__py3-none-any.whl → 2.14.0__py3-none-any.whl

fastmcp/server/tasks/__init__.py

@@ -0,0 +1,21 @@
+"""MCP SEP-1686 background tasks support.
+
+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.keys import (
+    build_task_key,
+    get_client_task_id_from_key,
+    parse_task_key,
+)
+
+__all__ = [
+    "TaskConfig",
+    "TaskMode",
+    "build_task_key",
+    "get_client_task_id_from_key",
+    "get_task_capabilities",
+    "parse_task_key",
+]

fastmcp/server/tasks/capabilities.py

@@ -0,0 +1,22 @@
+"""SEP-1686 task capabilities declaration."""
+
+from typing import Any
+
+
+def get_task_capabilities() -> dict[str, Any]:
+    """Return the SEP-1686 task capabilities structure.
+
+    This is the standard capabilities map advertised to clients,
+    declaring support for list, cancel, and request operations.
+    """
+    return {
+        "tasks": {
+            "list": {},
+            "cancel": {},
+            "requests": {
+                "tools": {"call": {}},
+                "prompts": {"get": {}},
+                "resources": {"read": {}},
+            },
+        }
+    }

fastmcp/server/tasks/config.py

@@ -0,0 +1,89 @@
+"""TaskConfig for MCP SEP-1686 background task execution modes.
+
+This module defines the configuration for how tools, resources, and prompts
+handle task-augmented execution as specified in SEP-1686.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Literal
+
+# Task execution modes per SEP-1686 / MCP ToolExecution.taskSupport
+TaskMode = Literal["forbidden", "optional", "required"]
+
+
+@dataclass
+class TaskConfig:
+    """Configuration for MCP background task execution (SEP-1686).
+
+    Controls how a component handles task-augmented requests:
+
+    - "forbidden": Component does not support task execution. Clients must not
+      request task augmentation; server returns -32601 if they do.
+    - "optional": Component supports both synchronous and task execution.
+      Client may request task augmentation or call normally.
+    - "required": Component requires task execution. Clients must request task
+      augmentation; server returns -32601 if they don't.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.tasks import TaskConfig
+
+        mcp = FastMCP("MyServer")
+
+        # Background execution required
+        @mcp.tool(task=TaskConfig(mode="required"))
+        async def long_running_task(): ...
+
+        # Supports both modes (default when task=True)
+        @mcp.tool(task=TaskConfig(mode="optional"))
+        async def flexible_task(): ...
+        ```
+    """
+
+    mode: TaskMode = "optional"
+
+    @classmethod
+    def from_bool(cls, value: bool) -> TaskConfig:
+        """Convert boolean task flag to TaskConfig.
+
+        Args:
+            value: True for "optional" mode, False for "forbidden" mode.
+
+        Returns:
+            TaskConfig with appropriate mode.
+        """
+        return cls(mode="optional" if value else "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.
+
+        Args:
+            fn: The function to validate (handles callable classes and staticmethods).
+            name: Name for error messages.
+
+        Raises:
+            ValueError: If task execution is enabled but function is sync.
+        """
+        if self.mode == "forbidden":
+            return
+
+        # Unwrap callable classes and staticmethods
+        fn_to_check = fn
+        if not inspect.isroutine(fn) and callable(fn):
+            fn_to_check = fn.__call__
+        if isinstance(fn_to_check, staticmethod):
+            fn_to_check = fn_to_check.__func__
+
+        if not inspect.iscoroutinefunction(fn_to_check):
+            raise ValueError(
+                f"'{name}' uses a sync function but has task execution enabled. "
+                "Background tasks require async functions."
+            )

fastmcp/server/tasks/converters.py

@@ -0,0 +1,205 @@
+"""SEP-1686 task result converters.
+
+Converts raw task return values to MCP result types.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import TYPE_CHECKING, Any
+
+import mcp.types
+import pydantic_core
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+
+async def convert_tool_result(
+    server: FastMCP, raw_value: Any, tool_name: str, client_task_id: str
+) -> mcp.types.CallToolResult:
+    """Convert raw tool return value to MCP CallToolResult.
+
+    Replicates the serialization logic from tool.run() to properly handle
+    output_schema, structured content, etc.
+
+    Args:
+        server: FastMCP server instance
+        raw_value: The raw return value from user's tool function
+        tool_name: Name of the tool (to get output_schema and serializer)
+        client_task_id: Client task ID for related-task metadata
+
+    Returns:
+        CallToolResult with properly formatted content and structured content
+    """
+    # Import here to avoid circular import:
+    # tools/tool.py -> tasks/config.py -> tasks/__init__.py -> converters.py -> tools/tool.py
+    from fastmcp.tools.tool import ToolResult, _convert_to_content
+
+    # Get the tool to access its configuration
+    tool = await server.get_tool(tool_name)
+
+    # Build related-task metadata
+    related_task_meta = {
+        "modelcontextprotocol.io/related-task": {
+            "taskId": client_task_id,
+        }
+    }
+
+    # If raw value is already ToolResult, use it directly
+    if isinstance(raw_value, ToolResult):
+        mcp_result = raw_value.to_mcp_result()
+        if isinstance(mcp_result, mcp.types.CallToolResult):
+            # Add metadata
+            mcp_result._meta = related_task_meta
+            return mcp_result
+        elif isinstance(mcp_result, tuple):
+            content, structured_content = mcp_result
+            return mcp.types.CallToolResult(
+                content=content,
+                structuredContent=structured_content,
+                _meta=related_task_meta,
+            )
+        else:
+            return mcp.types.CallToolResult(content=mcp_result, _meta=related_task_meta)
+
+    # Convert raw value to content blocks
+    unstructured_result = _convert_to_content(raw_value, serializer=tool.serializer)
+
+    # Handle structured content creation (same logic as tool.run())
+    structured_content = None
+
+    if tool.output_schema is None:
+        # Try to serialize as dict for structured content
+        try:
+            sc = pydantic_core.to_jsonable_python(raw_value)
+            if isinstance(sc, dict):
+                structured_content = sc
+        except pydantic_core.PydanticSerializationError:
+            pass
+    else:
+        # Has output_schema - convert to JSON-able types
+        jsonable_value = pydantic_core.to_jsonable_python(raw_value)
+        wrap_result = tool.output_schema.get("x-fastmcp-wrap-result")
+        structured_content = (
+            {"result": jsonable_value} if wrap_result else jsonable_value
+        )
+
+    return mcp.types.CallToolResult(
+        content=unstructured_result,
+        structuredContent=structured_content,
+        _meta=related_task_meta,
+    )
+
+
+async def convert_prompt_result(
+    server: FastMCP, raw_value: Any, prompt_name: str, client_task_id: str
+) -> mcp.types.GetPromptResult:
+    """Convert raw prompt return value to MCP GetPromptResult.
+
+    The user function returns raw values (strings, dicts, lists) that need
+    to be converted to PromptMessage objects.
+
+    Args:
+        server: FastMCP server instance
+        raw_value: The raw return value from user's prompt function
+        prompt_name: Name of the prompt
+        client_task_id: Client task ID for related-task metadata
+
+    Returns:
+        GetPromptResult with properly formatted messages
+    """
+    from fastmcp.prompts.prompt import PromptMessage
+
+    # Get the prompt for metadata
+    prompt = await server.get_prompt(prompt_name)
+
+    # Normalize to list
+    if not isinstance(raw_value, list | tuple):
+        raw_value = [raw_value]
+
+    # Convert to PromptMessages
+    messages: list[mcp.types.PromptMessage] = []
+    for msg in raw_value:
+        if isinstance(msg, PromptMessage):
+            messages.append(msg.to_mcp())
+        elif isinstance(msg, str):
+            messages.append(
+                mcp.types.PromptMessage(
+                    role="user",
+                    content=mcp.types.TextContent(type="text", text=msg),
+                )
+            )
+        elif isinstance(msg, dict):
+            messages.append(mcp.types.PromptMessage.model_validate(msg))
+        else:
+            raise ValueError(f"Invalid message type: {type(msg)}")
+
+    return mcp.types.GetPromptResult(
+        description=prompt.description or "",
+        messages=messages,
+        _meta={
+            "modelcontextprotocol.io/related-task": {
+                "taskId": client_task_id,
+            }
+        },
+    )
+
+
+async def convert_resource_result(
+    server: FastMCP, raw_value: Any, uri: str, client_task_id: str
+) -> dict[str, Any]:
+    """Convert raw resource return value to MCP resource contents dict.
+
+    Args:
+        server: FastMCP server instance
+        raw_value: The raw return value from user's resource function (str or bytes)
+        uri: Resource URI (for the contents response)
+        client_task_id: Client task ID for related-task metadata
+
+    Returns:
+        Dict with 'contents' key containing list of resource contents
+    """
+    # Build related-task metadata
+    related_task_meta = {
+        "modelcontextprotocol.io/related-task": {
+            "taskId": client_task_id,
+        }
+    }
+
+    # Resources return str or bytes directly
+    if isinstance(raw_value, str):
+        return {
+            "contents": [
+                {
+                    "uri": uri,
+                    "text": raw_value,
+                    "mimeType": "text/plain",
+                }
+            ],
+            "_meta": related_task_meta,
+        }
+    elif isinstance(raw_value, bytes):
+        return {
+            "contents": [
+                {
+                    "uri": uri,
+                    "blob": base64.b64encode(raw_value).decode(),
+                    "mimeType": "application/octet-stream",
+                }
+            ],
+            "_meta": related_task_meta,
+        }
+    else:
+        # Fallback: convert to JSON string
+        return {
+            "contents": [
+                {
+                    "uri": uri,
+                    "text": json.dumps(raw_value),
+                    "mimeType": "application/json",
+                }
+            ],
+            "_meta": related_task_meta,
+        }

fastmcp/server/tasks/handlers.py

@@ -0,0 +1,356 @@
+"""SEP-1686 task execution handlers.
+
+Handles queuing tool/prompt/resource executions to Docket as background tasks.
+"""
+
+from __future__ import annotations
+
+import uuid
+from contextlib import suppress
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+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.keys import build_task_key
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+# 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).
+
+    Queues the user's actual function to Docket (preserving signature for DI),
+    stores raw return values, 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)
+
+    Returns:
+        CallToolResult: 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
+
+    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, "tool", tool_name)
+
+    # Get the tool to access user's function
+    tool = await server.get_tool(tool_name)
+
+    # Store task key mapping and creation timestamp in Redis for protocol handlers
+    redis_key = f"fastmcp:task:{session_id}:{server_task_id}"
+    created_at_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(redis_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={},  # Empty params per spec
+        _meta={  # taskId in _meta per spec
+            "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
+
+    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
+    redis_key = f"fastmcp:task:{session_id}:{server_task_id}"
+    created_at_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(redis_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
+
+    docket = _current_docket.get()
+    if docket is None:
+        raise McpError(
+            ErrorData(
+                code=INTERNAL_ERROR,
+                message="Background tasks require Docket",
+            )
+        )
+
+    # 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
+    redis_key = f"fastmcp:task:{session_id}:{server_task_id}"
+    created_at_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(redis_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)
+    else:
+        await docket.add(
+            resource.name,
+            key=task_key,
+        )()
+
+    # 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.ServerResult(
+        mcp.types.ReadResourceResult(
+            contents=[],
+            _meta={
+                "modelcontextprotocol.io/task": {
+                    "taskId": server_task_id,
+                    "status": "working",
+                }
+            },
+        )
+    )