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

fastmcp/server/tasks/converters.py

@@ -1,206 +0,0 @@
-"""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):
-            # PromptMessage is imported from mcp.types - use directly
-            messages.append(msg)
-        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/protocol.py

@@ -1,359 +0,0 @@
-"""SEP-1686 task protocol handlers.
-
-Implements MCP task protocol methods: tasks/get, tasks/result, tasks/list, tasks/cancel, tasks/delete.
-"""
-
-from __future__ import annotations
-
-from datetime import datetime, timedelta, timezone
-from typing import TYPE_CHECKING, Any
-
-import mcp.types
-from docket.execution import ExecutionState
-from mcp.shared.exceptions import McpError
-from mcp.types import (
-    INTERNAL_ERROR,
-    INVALID_PARAMS,
-    CancelTaskResult,
-    ErrorData,
-    GetTaskResult,
-    ListTasksResult,
-)
-
-from fastmcp.server.tasks.converters import (
-    convert_prompt_result,
-    convert_resource_result,
-    convert_tool_result,
-)
-from fastmcp.server.tasks.keys import parse_task_key
-
-if TYPE_CHECKING:
-    from fastmcp.server.server import FastMCP
-
-# Map Docket execution states to MCP task status strings
-# Per SEP-1686 final spec (line 381): tasks MUST begin in "working" status
-DOCKET_TO_MCP_STATE: dict[ExecutionState, str] = {
-    ExecutionState.SCHEDULED: "working",  # Initial state per spec
-    ExecutionState.QUEUED: "working",  # Initial state per spec
-    ExecutionState.RUNNING: "working",
-    ExecutionState.COMPLETED: "completed",
-    ExecutionState.FAILED: "failed",
-    ExecutionState.CANCELLED: "cancelled",
-}
-
-
-async def tasks_get_handler(server: FastMCP, params: dict[str, Any]) -> GetTaskResult:
-    """Handle MCP 'tasks/get' request (SEP-1686).
-
-    Args:
-        server: FastMCP server instance
-        params: Request params containing taskId
-
-    Returns:
-        GetTaskResult: Task status response with spec-compliant fields
-    """
-    import fastmcp.server.context
-
-    async with fastmcp.server.context.Context(fastmcp=server) as ctx:
-        client_task_id = params.get("taskId")
-        if not client_task_id:
-            raise McpError(
-                ErrorData(
-                    code=INVALID_PARAMS, message="Missing required parameter: taskId"
-                )
-            )
-
-        # Get session ID from Context
-        session_id = ctx.session_id
-
-        # Get execution from Docket (use instance attribute for cross-task access)
-        docket = server._docket
-        if docket is None:
-            raise McpError(
-                ErrorData(
-                    code=INTERNAL_ERROR,
-                    message="Background tasks require Docket",
-                )
-            )
-
-        # Look up full task key and creation timestamp from Redis
-        task_meta_key = docket.key(f"fastmcp:task:{session_id}:{client_task_id}")
-        created_at_key = docket.key(
-            f"fastmcp:task:{session_id}:{client_task_id}:created_at"
-        )
-        async with docket.redis() as redis:
-            task_key_bytes = await redis.get(task_meta_key)
-            created_at_bytes = await redis.get(created_at_key)
-
-        task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
-        created_at = (
-            None if created_at_bytes is None else created_at_bytes.decode("utf-8")
-        )
-
-        if task_key is None:
-            # Task not found - raise error per MCP protocol
-            raise McpError(
-                ErrorData(
-                    code=INVALID_PARAMS, message=f"Task {client_task_id} not found"
-                )
-            )
-
-        execution = await docket.get_execution(task_key)
-        if execution is None:
-            # Task key exists but no execution - raise error
-            raise McpError(
-                ErrorData(
-                    code=INVALID_PARAMS,
-                    message=f"Task {client_task_id} execution not found",
-                )
-            )
-
-        # Sync state from Redis
-        await execution.sync()
-
-        # Map Docket state to MCP state
-        mcp_state = DOCKET_TO_MCP_STATE.get(execution.state, "failed")
-
-        # Build response (use default ttl since we don't track per-task values)
-        # createdAt is REQUIRED per SEP-1686 final spec (line 430)
-        # Per spec lines 447-448: SHOULD NOT include related-task metadata in tasks/get
-        error_message = None
-        status_message = None
-
-        if execution.state == ExecutionState.FAILED:
-            try:
-                await execution.get_result(timeout=timedelta(seconds=0))
-            except Exception as error:
-                error_message = str(error)
-                status_message = f"Task failed: {error_message}"
-        elif execution.progress and execution.progress.message:
-            # Extract progress message from Docket if available (spec line 403)
-            status_message = execution.progress.message
-
-        return GetTaskResult(
-            taskId=client_task_id,
-            status=mcp_state,  # type: ignore[arg-type]
-            createdAt=created_at,  # type: ignore[arg-type]
-            lastUpdatedAt=datetime.now(timezone.utc),
-            ttl=60000,
-            pollInterval=1000,
-            statusMessage=status_message,
-        )
-
-
-async def tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any:
-    """Handle MCP 'tasks/result' request (SEP-1686).
-
-    Converts raw task return values to MCP types based on task type.
-
-    Args:
-        server: FastMCP server instance
-        params: Request params containing taskId
-
-    Returns:
-        MCP result (CallToolResult, GetPromptResult, or ReadResourceResult)
-    """
-    import fastmcp.server.context
-
-    async with fastmcp.server.context.Context(fastmcp=server) as ctx:
-        client_task_id = params.get("taskId")
-        if not client_task_id:
-            raise McpError(
-                ErrorData(
-                    code=INVALID_PARAMS, message="Missing required parameter: taskId"
-                )
-            )
-
-        # Get session ID from Context
-        session_id = ctx.session_id
-
-        # Get execution from Docket (use instance attribute for cross-task access)
-        docket = server._docket
-        if docket is None:
-            raise McpError(
-                ErrorData(
-                    code=INTERNAL_ERROR,
-                    message="Background tasks require Docket",
-                )
-            )
-
-        # Look up full task key from Redis
-        task_meta_key = docket.key(f"fastmcp:task:{session_id}:{client_task_id}")
-        async with docket.redis() as redis:
-            task_key_bytes = await redis.get(task_meta_key)
-
-        task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
-
-        if task_key is None:
-            raise McpError(
-                ErrorData(
-                    code=INVALID_PARAMS,
-                    message=f"Invalid taskId: {client_task_id} not found",
-                )
-            )
-
-        execution = await docket.get_execution(task_key)
-        if execution is None:
-            raise McpError(
-                ErrorData(
-                    code=INVALID_PARAMS,
-                    message=f"Invalid taskId: {client_task_id} not found",
-                )
-            )
-
-        # Sync state from Redis
-        await execution.sync()
-
-        # Check if completed
-        if execution.state not in (ExecutionState.COMPLETED, ExecutionState.FAILED):
-            mcp_state = DOCKET_TO_MCP_STATE.get(execution.state, "failed")
-            raise McpError(
-                ErrorData(
-                    code=INVALID_PARAMS,
-                    message=f"Task not completed yet (current state: {mcp_state})",
-                )
-            )
-
-        # Get result from Docket
-        try:
-            raw_value = await execution.get_result(timeout=timedelta(seconds=0))
-        except Exception as error:
-            # Task failed - return error result
-            return mcp.types.CallToolResult(
-                content=[mcp.types.TextContent(type="text", text=str(error))],
-                isError=True,
-                _meta={
-                    "modelcontextprotocol.io/related-task": {
-                        "taskId": client_task_id,
-                    }
-                },
-            )
-
-        # Parse task key to get type and component info
-        key_parts = parse_task_key(task_key)
-        task_type = key_parts["task_type"]
-
-        # Convert based on task type (pass client_task_id for metadata)
-        if task_type == "tool":
-            return await convert_tool_result(
-                server, raw_value, key_parts["component_identifier"], client_task_id
-            )
-        elif task_type == "prompt":
-            return await convert_prompt_result(
-                server, raw_value, key_parts["component_identifier"], client_task_id
-            )
-        elif task_type == "resource":
-            return await convert_resource_result(
-                server, raw_value, key_parts["component_identifier"], client_task_id
-            )
-        else:
-            raise McpError(
-                ErrorData(
-                    code=INTERNAL_ERROR,
-                    message=f"Internal error: Unknown task type: {task_type}",
-                )
-            )
-
-
-async def tasks_list_handler(
-    server: FastMCP, params: dict[str, Any]
-) -> ListTasksResult:
-    """Handle MCP 'tasks/list' request (SEP-1686).
-
-    Note: With client-side tracking, this returns minimal info.
-
-    Args:
-        server: FastMCP server instance
-        params: Request params (cursor, limit)
-
-    Returns:
-        ListTasksResult: Response with tasks list and pagination
-    """
-    # Return empty list - client tracks tasks locally
-    return ListTasksResult(tasks=[], nextCursor=None)
-
-
-async def tasks_cancel_handler(
-    server: FastMCP, params: dict[str, Any]
-) -> CancelTaskResult:
-    """Handle MCP 'tasks/cancel' request (SEP-1686).
-
-    Cancels a running task, transitioning it to cancelled state.
-
-    Args:
-        server: FastMCP server instance
-        params: Request params containing taskId
-
-    Returns:
-        CancelTaskResult: Task status response showing cancelled state
-    """
-    import fastmcp.server.context
-
-    async with fastmcp.server.context.Context(fastmcp=server) as ctx:
-        client_task_id = params.get("taskId")
-        if not client_task_id:
-            raise McpError(
-                ErrorData(
-                    code=INVALID_PARAMS, message="Missing required parameter: taskId"
-                )
-            )
-
-        # Get session ID from Context
-        session_id = ctx.session_id
-
-        docket = server._docket
-        if docket is None:
-            raise McpError(
-                ErrorData(
-                    code=INTERNAL_ERROR,
-                    message="Background tasks require Docket",
-                )
-            )
-
-        # Look up full task key and creation timestamp from Redis
-        task_meta_key = docket.key(f"fastmcp:task:{session_id}:{client_task_id}")
-        created_at_key = docket.key(
-            f"fastmcp:task:{session_id}:{client_task_id}:created_at"
-        )
-        async with docket.redis() as redis:
-            task_key_bytes = await redis.get(task_meta_key)
-            created_at_bytes = await redis.get(created_at_key)
-
-        task_key = None if task_key_bytes is None else task_key_bytes.decode("utf-8")
-        created_at = (
-            None if created_at_bytes is None else created_at_bytes.decode("utf-8")
-        )
-
-        if task_key is None:
-            raise McpError(
-                ErrorData(
-                    code=INVALID_PARAMS,
-                    message=f"Invalid taskId: {client_task_id} not found",
-                )
-            )
-
-        # Check if task exists
-        execution = await docket.get_execution(task_key)
-        if execution is None:
-            raise McpError(
-                ErrorData(
-                    code=INVALID_PARAMS,
-                    message=f"Invalid taskId: {client_task_id} not found",
-                )
-            )
-
-        # Cancel via Docket (now sets CANCELLED state natively)
-        await docket.cancel(task_key)
-
-        # Return task status with cancelled state
-        # createdAt is REQUIRED per SEP-1686 final spec (line 430)
-        # Per spec lines 447-448: SHOULD NOT include related-task metadata in tasks/cancel
-        return CancelTaskResult(
-            taskId=client_task_id,
-            status="cancelled",
-            createdAt=created_at or datetime.now(timezone.utc).isoformat(),
-            lastUpdatedAt=datetime.now(timezone.utc),
-            ttl=60_000,
-            pollInterval=1000,
-            statusMessage="Task cancelled",
-        )