MCP Server Framework - v1.0.0
    Preparing search index...

    Interface TaskToolHandler<TInput>Experimental

    Handler interface for task-based tool execution.

    Task tools use a three-method handler instead of a single callback, enabling long-running operations with a create → poll → result lifecycle:

    1. createTask — Initiate the task, return immediately with a task ID
    2. getTask — Return current task status (clients poll this)
    3. getTaskResult — Return the final result when the task completes
    const handler: TaskToolHandler<typeof inputSchema> = {
      createTask: async (args, ctx) => {
        const task = await ctx.taskStore.createTask({});
        startBackgroundWork(task.taskId, args);
        return { task };
      },
      getTask: async (_args, ctx) => {
        return ctx.taskStore.getTask(ctx.taskId);
      },
      getTaskResult: async (_args, ctx) => {
        return ctx.taskStore.getTaskResult(ctx.taskId);
      },
    };
    interface TaskToolHandler<TInput extends ZodTypeAny = ZodTypeAny> {
        createTask: (
            args: TypeOf<TInput>,
            context: TaskCreateContext,
        ) => Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                task: {
                    createdAt: string;
                    lastUpdatedAt: string;
                    pollInterval?: number;
                    status: | "working"
                    | "input_required"
                    | "completed"
                    | "failed"
                    | "cancelled";
                    statusMessage?: string;
                    taskId: string;
                    ttl: number
                    | null;
                };
                [key: string]: unknown;
            },
        >;
        getTask: (
            args: TypeOf<TInput>,
            context: TaskOperationContext,
        ) => Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                createdAt: string;
                lastUpdatedAt: string;
                pollInterval?: number;
                status: | "working"
                | "input_required"
                | "completed"
                | "failed"
                | "cancelled";
                statusMessage?: string;
                taskId: string;
                ttl: number
                | null;
            },
        >;
        getTaskResult: (
            args: TypeOf<TInput>,
            context: TaskOperationContext,
        ) => Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                content: (
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        mimeType?: string;
                        name: string;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: string]: unknown };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        >;
    }

    Type Parameters

    • TInput extends ZodTypeAny = ZodTypeAny

      Zod schema type for input validation (inferred)

      MCP Tasks is an experimental SDK feature

    Index

    Properties

    createTask getTask getTaskResult

    Properties

    createTask: (
        args: TypeOf<TInput>,
        context: TaskCreateContext,
    ) => Promise<
        {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            task: {
                createdAt: string;
                lastUpdatedAt: string;
                pollInterval?: number;
                status: | "working"
                | "input_required"
                | "completed"
                | "failed"
                | "cancelled";
                statusMessage?: string;
                taskId: string;
                ttl: number
                | null;
            };
            [key: string]: unknown;
        },
    >

    Create and start a new task.

    Called when the client issues a tools/call with task parameters. Should initiate the background work and return immediately.

    Type Declaration

      • (
            args: TypeOf<TInput>,
            context: TaskCreateContext,
        ): Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                task: {
                    createdAt: string;
                    lastUpdatedAt: string;
                    pollInterval?: number;
                    status: | "working"
                    | "input_required"
                    | "completed"
                    | "failed"
                    | "cancelled";
                    statusMessage?: string;
                    taskId: string;
                    ttl: number
                    | null;
                };
                [key: string]: unknown;
            },
        >

      • Parameters

        Returns Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                task: {
                    createdAt: string;
                    lastUpdatedAt: string;
                    pollInterval?: number;
                    status: | "working"
                    | "input_required"
                    | "completed"
                    | "failed"
                    | "cancelled";
                    statusMessage?: string;
                    taskId: string;
                    ttl: number
                    | null;
                };
                [key: string]: unknown;
            },
        >

        Object containing the created task

    getTask: (
        args: TypeOf<TInput>,
        context: TaskOperationContext,
    ) => Promise<
        {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            createdAt: string;
            lastUpdatedAt: string;
            pollInterval?: number;
            status: | "working"
            | "input_required"
            | "completed"
            | "failed"
            | "cancelled";
            statusMessage?: string;
            taskId: string;
            ttl: number
            | null;
        },
    >

    Get the current status of a task.

    Called when the client polls via tasks/get. Return the task with its current status.

    Type Declaration

      • (
            args: TypeOf<TInput>,
            context: TaskOperationContext,
        ): Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                createdAt: string;
                lastUpdatedAt: string;
                pollInterval?: number;
                status: | "working"
                | "input_required"
                | "completed"
                | "failed"
                | "cancelled";
                statusMessage?: string;
                taskId: string;
                ttl: number
                | null;
            },
        >

      • Parameters

        Returns Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                createdAt: string;
                lastUpdatedAt: string;
                pollInterval?: number;
                status: | "working"
                | "input_required"
                | "completed"
                | "failed"
                | "cancelled";
                statusMessage?: string;
                taskId: string;
                ttl: number
                | null;
            },
        >

        Task status result

    getTaskResult: (
        args: TypeOf<TInput>,
        context: TaskOperationContext,
    ) => Promise<
        {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            content: (
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    text: string;
                    type: "text";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "image";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "audio";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    description?: string;
                    icons?: {
                        mimeType?: string;
                        sizes?: (...)[];
                        src: string;
                        theme?: "light" | "dark";
                    }[];
                    mimeType?: string;
                    name: string;
                    title?: string;
                    type: "resource_link";
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    resource: | {
                        _meta?: { [key: string]: unknown };
                        mimeType?: string;
                        text: string;
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        blob: string;
                        mimeType?: string;
                        uri: string;
                    };
                    type: "resource";
                }
            )[];
            isError?: boolean;
            structuredContent?: { [key: string]: unknown };
            [key: string]: unknown;
        },
    >

    Get the final result of a completed task.

    Called when the client requests the result via tasks/result. Should return the tool's final output.

    Type Declaration

      • (
            args: TypeOf<TInput>,
            context: TaskOperationContext,
        ): Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                content: (
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        mimeType?: string;
                        name: string;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: string]: unknown };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        >

      • Parameters

        Returns Promise<
            {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                content: (
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        mimeType?: string;
                        name: string;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: string]: unknown };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        >

        MCP CallToolResult (use response helpers: text(), json(), error())

    Settings

    Member Visibility

    On This Page

    Properties