mark3labs
diff --git a/‎mcp/tasks.go‎
Lines changed: 151 additions & 0 deletions b/‎mcp/tasks.go‎
Lines changed: 151 additions & 0 deletions
diff --git a/‎mcp/types.go‎
Lines changed: 182 additions & 0 deletions b/‎mcp/types.go‎
Lines changed: 182 additions & 0 deletions
@@ -0,0 +1,151 @@
+package mcp
+
+import (
+	"time"
+)
+
+// TaskOption is a function that configures a Task.
+// It provides a flexible way to set various properties of a Task using the functional options pattern.
+type TaskOption func(*Task)
+
+//
+// Core Task Functions
+//
+
+// NewTask creates a new Task with the given ID and options.
+// The task will be configured based on the provided options.
+// Options are applied in order, allowing for flexible task configuration.
+func NewTask(taskId string, opts ...TaskOption) Task {
+	task := Task{
+		TaskId:    taskId,
+		Status:    TaskStatusWorking,
+		CreatedAt: time.Now().UTC().Format(time.RFC3339),
+	}
+
+	for _, opt := range opts {
+		opt(&task)
+	}
+
+	return task
+}
+
+// WithTaskStatus sets the status of the task.
+func WithTaskStatus(status TaskStatus) TaskOption {
+	return func(t *Task) {
+		t.Status = status
+	}
+}
+
+// WithTaskStatusMessage sets a human-readable status message for the task.
+func WithTaskStatusMessage(message string) TaskOption {
+	return func(t *Task) {
+		t.StatusMessage = message
+	}
+}
+
+// WithTaskTTL sets the time-to-live for the task in milliseconds.
+// After this duration from creation, the task may be deleted.
+func WithTaskTTL(ttlMs int64) TaskOption {
+	return func(t *Task) {
+		t.TTL = &ttlMs
+	}
+}
+
+// WithTaskPollInterval sets the suggested polling interval in milliseconds.
+func WithTaskPollInterval(intervalMs int64) TaskOption {
+	return func(t *Task) {
+		t.PollInterval = &intervalMs
+	}
+}
+
+// WithTaskCreatedAt sets a specific creation timestamp for the task.
+// By default, NewTask uses the current time.
+func WithTaskCreatedAt(createdAt string) TaskOption {
+	return func(t *Task) {
+		t.CreatedAt = createdAt
+	}
+}
+
+//
+// Task Helper Functions
+//
+
+// NewTaskParams creates TaskParams with the given TTL.
+func NewTaskParams(ttlMs *int64) TaskParams {
+	return TaskParams{
+		TTL: ttlMs,
+	}
+}
+
+// NewCreateTaskResult creates a CreateTaskResult with the given task.
+func NewCreateTaskResult(task Task) CreateTaskResult {
+	return CreateTaskResult{
+		Task: task,
+	}
+}
+
+// NewGetTaskResult creates a GetTaskResult from a Task.
+func NewGetTaskResult(task Task) GetTaskResult {
+	return GetTaskResult{
+		Task: task,
+	}
+}
+
+// NewListTasksResult creates a ListTasksResult with the given tasks.
+func NewListTasksResult(tasks []Task) ListTasksResult {
+	return ListTasksResult{
+		Tasks: tasks,
+	}
+}
+
+// NewCancelTaskResult creates a CancelTaskResult from a Task.
+func NewCancelTaskResult(task Task) CancelTaskResult {
+	return CancelTaskResult{
+		Task: task,
+	}
+}
+
+// NewTaskStatusNotification creates a notification for a task status change.
+func NewTaskStatusNotification(task Task) TaskStatusNotification {
+	return TaskStatusNotification{
+		Notification: Notification{
+			Method: string(MethodNotificationTasksStatus),
+		},
+		Params: TaskStatusNotificationParams{
+			Task: task,
+		},
+	}
+}
+
+//
+// Task Capability Helper Functions
+//
+
+// NewTasksCapability creates a TasksCapability with all operations enabled.
+func NewTasksCapability() *TasksCapability {
+	return &TasksCapability{
+		List:   &struct{}{},
+		Cancel: &struct{}{},
+		Requests: &TaskRequestsCapability{
+			Tools: &struct {
+				Call *struct{} `json:"call,omitempty"`
+			}{
+				Call: &struct{}{},
+			},
+		},
+	}
+}
+
+// NewTasksCapabilityWithToolsOnly creates a TasksCapability with only tool call support.
+// List and Cancel operations are not enabled with this capability.
+func NewTasksCapabilityWithToolsOnly() *TasksCapability {
+	return &TasksCapability{
+		Requests: &TaskRequestsCapability{
+			Tools: &struct {
+				Call *struct{} `json:"call,omitempty"`
+			}{
+				Call: &struct{}{},
+			},
+		},
+	}
+}
@@ -63,6 +63,22 @@ const (
 	// https://modelcontextprotocol.io/specification/2025-06-18/client/roots
 	MethodListRoots MCPMethod = "roots/list"
 
+	// MethodTasksGet retrieves the current status of a task.
+	// https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks
+	MethodTasksGet MCPMethod = "tasks/get"
+
+	// MethodTasksList lists all tasks for the current session.
+	// https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks
+	MethodTasksList MCPMethod = "tasks/list"
+
+	// MethodTasksResult retrieves the result of a completed task.
+	// https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks
+	MethodTasksResult MCPMethod = "tasks/result"
+
+	// MethodTasksCancel cancels an in-progress task.
+	// https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks
+	MethodTasksCancel MCPMethod = "tasks/cancel"
+
 	// MethodNotificationResourcesListChanged notifies when the list of available resources changes.
 	// https://modelcontextprotocol.io/specification/2025-03-26/server/resources#list-changed-notification
 	MethodNotificationResourcesListChanged = "notifications/resources/list_changed"
@@ -80,6 +96,10 @@ const (
 	// MethodNotificationRootsListChanged notifies when the list of available roots changes.
 	// https://modelcontextprotocol.io/specification/2025-06-18/client/roots#root-list-changes
 	MethodNotificationRootsListChanged = "notifications/roots/list_changed"
+
+	// MethodNotificationTasksStatus notifies when a task's status changes.
+	// https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks
+	MethodNotificationTasksStatus = "notifications/tasks/status"
 )
 
 type URITemplate struct {
@@ -491,6 +511,8 @@ type ClientCapabilities struct {
 	Sampling *struct{} `json:"sampling,omitempty"`
 	// Present if the client supports elicitation requests from the server.
 	Elicitation *struct{} `json:"elicitation,omitempty"`
+	// Present if the client supports task-based execution.
+	Tasks *TasksCapability `json:"tasks,omitempty"`
 }
 
 // ServerCapabilities represents capabilities that a server may support. Known
@@ -525,6 +547,8 @@ type ServerCapabilities struct {
 	Elicitation *struct{} `json:"elicitation,omitempty"`
 	// Present if the server supports roots requests to the client.
 	Roots *struct{} `json:"roots,omitempty"`
+	// Present if the server supports task-based execution.
+	Tasks *TasksCapability `json:"tasks,omitempty"`
 }
 
 // Icon represents a visual identifier for MCP entities.
@@ -1214,6 +1238,164 @@ type RootsListChangedNotification struct {
 	Notification
 }
 
+/* Tasks */
+
+// TasksCapability represents the task capabilities that a client or server may support.
+// Tasks enable long-running, asynchronous operations with status polling.
+type TasksCapability struct {
+	// Whether the party supports the tasks/list operation.
+	List *struct{} `json:"list,omitempty"`
+	// Whether the party supports the tasks/cancel operation.
+	Cancel *struct{} `json:"cancel,omitempty"`
+	// Requests that can be augmented with task metadata.
+	Requests *TaskRequestsCapability `json:"requests,omitempty"`
+}
+
+// TaskRequestsCapability indicates which request types support task augmentation.
+type TaskRequestsCapability struct {
+	// Tool-related capabilities.
+	Tools *struct {
+		// Whether tools/call can be augmented with task metadata.
+		Call *struct{} `json:"call,omitempty"`
+	} `json:"tools,omitempty"`
+	// Sampling-related capabilities.
+	Sampling *struct {
+		// Whether sampling/createMessage can be augmented with task metadata.
+		CreateMessage *struct{} `json:"createMessage,omitempty"`
+	} `json:"sampling,omitempty"`
+	// Elicitation-related capabilities.
+	Elicitation *struct {
+		// Whether elicitation/create can be augmented with task metadata.
+		Create *struct{} `json:"create,omitempty"`
+	} `json:"elicitation,omitempty"`
+}
+
+// TaskStatus represents the execution state of a task.
+type TaskStatus string
+
+const (
+	// TaskStatusWorking indicates the request is currently being processed.
+	TaskStatusWorking TaskStatus = "working"
+	// TaskStatusInputRequired indicates the receiver needs input from the requestor.
+	TaskStatusInputRequired TaskStatus = "input_required"
+	// TaskStatusCompleted indicates the request completed successfully.
+	TaskStatusCompleted TaskStatus = "completed"
+	// TaskStatusFailed indicates the request did not complete successfully.
+	TaskStatusFailed TaskStatus = "failed"
+	// TaskStatusCancelled indicates the request was cancelled before completion.
+	TaskStatusCancelled TaskStatus = "cancelled"
+)
+
+// IsTerminal returns true if the task status is terminal (completed, failed, or cancelled).
+func (s TaskStatus) IsTerminal() bool {
+	return s == TaskStatusCompleted || s == TaskStatusFailed || s == TaskStatusCancelled
+}
+
+// Task represents the execution state of a request.
+type Task struct {
+	// Unique identifier for the task.
+	TaskId string `json:"taskId"`
+	// Current state of the task execution.
+	Status TaskStatus `json:"status"`
+	// Optional human-readable message describing the current state.
+	StatusMessage string `json:"statusMessage,omitempty"`
+	// ISO 8601 timestamp when the task was created.
+	CreatedAt string `json:"createdAt"`
+	// Time in milliseconds from creation before task may be deleted.
+	// If null, the task has no expiration.
+	TTL *int64 `json:"ttl"`
+	// Suggested time in milliseconds between status checks.
+	PollInterval *int64 `json:"pollInterval,omitempty"`
+}
+
+// TaskParams represents the task metadata included when augmenting a request.
+type TaskParams struct {
+	// Requested duration in milliseconds to retain task from creation.
+	TTL *int64 `json:"ttl,omitempty"`
+}
+
+// CreateTaskResult is returned immediately when a task-augmented request is accepted.
+// It contains task metadata rather than the actual operation result.
+type CreateTaskResult struct {
+	Result
+	Task Task `json:"task"`
+}
+
+// GetTaskRequest retrieves the current status of a task.
+type GetTaskRequest struct {
+	Request
+	Header http.Header     `json:"-"`
+	Params GetTaskParams   `json:"params"`
+}
+
+type GetTaskParams struct {
+	TaskId string `json:"taskId"`
+}
+
+// GetTaskResult returns the current state of a task.
+type GetTaskResult struct {
+	Result
+	Task
+}
+
+// ListTasksRequest retrieves a paginated list of tasks.
+type ListTasksRequest struct {
+	PaginatedRequest
+	Header http.Header `json:"-"`
+}
+
+// ListTasksResult returns a list of tasks.
+type ListTasksResult struct {
+	PaginatedResult
+	Tasks []Task `json:"tasks"`
+}
+
+// TaskResultRequest retrieves the result of a completed task.
+type TaskResultRequest struct {
+	Request
+	Header http.Header        `json:"-"`
+	Params TaskResultParams   `json:"params"`
+}
+
+type TaskResultParams struct {
+	TaskId string `json:"taskId"`
+}
+
+// TaskResultResult contains the actual operation result.
+// The structure depends on the original request type.
+type TaskResultResult struct {
+	Result
+	// The actual result varies by request type (e.g., CallToolResult for tools/call).
+	// This will be handled by the specific implementation.
+}
+
+// CancelTaskRequest cancels an in-progress task.
+type CancelTaskRequest struct {
+	Request
+	Header http.Header       `json:"-"`
+	Params CancelTaskParams  `json:"params"`
+}
+
+type CancelTaskParams struct {
+	TaskId string `json:"taskId"`
+}
+
+// CancelTaskResult returns the cancelled task state.
+type CancelTaskResult struct {
+	Result
+	Task
+}
+
+// TaskStatusNotification is sent when a task's status changes.
+type TaskStatusNotification struct {
+	Notification
+	Params TaskStatusNotificationParams `json:"params"`
+}
+
+type TaskStatusNotificationParams struct {
+	Task
+}
+
 // ClientRequest represents any request that can be sent from client to server.
 type ClientRequest any