schema.ts

/**
 * MCP Tasks Extension Schema (spec.types.ts)
 * Extension Identifier: io.modelcontextprotocol/tasks
 *
 * This file contains pure TypeScript interface definitions for the MCP Tasks extension.
 * These types are the source of truth and are used to generate Zod schemas via `ts-to-zod`.
 *
 * - Use `@description` JSDoc tags to generate `.describe()` calls on schemas
 * - Run `npm run generate:schemas` to regenerate schemas from these types
 *
 * @see https://modelcontextprotocol.io/seps/2663-tasks-extension
 */

import type {
  Error as JSONRPCErrorObject,
  InputRequests,
  InputResponses,
  JSONRPCNotification,
  JSONRPCRequest,
  NotificationParams,
  Result,
} from "./spec.types.js";

/* Tasks */

/**
 * The status of a task.
 *
 * @category `tasks`
 */
export type TaskStatus =
  | "working" // The request is currently being processed
  | "input_required" // The task is waiting for input (e.g., elicitation or sampling)
  | "completed" // The request completed successfully and results are available
  | "failed" // The associated request failed due to a JSON-RPC error during execution
  | "cancelled"; // The request was cancelled before completion

/**
 * Data associated with a task.
 *
 * @category `tasks`
 */
export interface Task {
  /**
   * The task identifier.
   */
  taskId: string;

  /**
   * Current task status.
   */
  status: TaskStatus;

  /**
   * Optional human-readable message describing the current task state.
   * This can provide context for any status, including:
   * - Progress descriptions for "working"
   * - Work blocked on "input_required"
   * - Reasons for "cancelled" status
   * - Summaries for "completed" status
   * - Diagnostic information for "failed" status (e.g., error details, what went wrong)
   */
  statusMessage?: string;

  /**
   * ISO 8601 timestamp when the task was created.
   */
  createdAt: string;

  /**
   * ISO 8601 timestamp when the task was last updated.
   */
  lastUpdatedAt: string;

  /**
   * Time-to-live duration from creation in integer milliseconds, null for unlimited.
   * The server may discard the task after the TTL elapses. This value MAY change
   * over the lifetime of a task.
   * @format int
   * @nullable
   */
  ttlMs: number | null;

  /**
   * Suggested polling interval in integer milliseconds. Clients SHOULD honor
   * this value to avoid overwhelming the server. This value MAY change over
   * the lifetime of a task.
   * @format int
   */
  pollIntervalMs?: number;
}

/* Detailed Task Variants */

/**
 * A task that is in a normal working state.
 * Used by tasks/get and notifications/tasks.
 *
 * @category `tasks`
 */
export interface WorkingTask extends Task {
  status: "working";
}

/**
 * A task that is waiting for input from the client.
 * Used by tasks/get and notifications/tasks.
 *
 * @category `tasks`
 */
export interface InputRequiredTask extends Task {
  status: "input_required";

  /**
   * Server-to-client requests that need to be fulfilled during task execution.
   * Keys are arbitrary identifiers for matching requests to responses.
   */
  inputRequests: InputRequests;
}

/**
 * A task that has completed successfully.
 * Used by tasks/get and notifications/tasks.
 *
 * @category `tasks`
 */
export interface CompletedTask extends Task {
  status: "completed";

  /**
   * The final result of the task.
   * The structure matches the result type of the original request.
   * For example, a CallToolRequest task would return the CallToolResult structure.
   */
  result: { [key: string]: unknown };
}

/**
 * A task that has failed due to a JSON-RPC error during execution.
 * Used by tasks/get and notifications/tasks.
 *
 * @category `tasks`
 */
export interface FailedTask extends Task {
  status: "failed";

  /**
   * The JSON-RPC error that caused the task to fail.
   */
  error: JSONRPCErrorObject;
}

/**
 * A task that has been cancelled.
 * Used by tasks/get and notifications/tasks.
 *
 * @category `tasks`
 */
export interface CancelledTask extends Task {
  status: "cancelled";
}

/**
 * A union type representing a task with status-specific fields inlined.
 * This type is used by tasks/get responses and notifications/tasks
 * notifications to provide complete task state including terminal results
 * or pending input requests.
 *
 * @category `tasks`
 */
export type DetailedTask =
  | WorkingTask
  | InputRequiredTask
  | CompletedTask
  | FailedTask
  | CancelledTask;

/* Task Creation */

/**
 * The result returned by a server in lieu of a standard result shape when
 * it elects to process a request asynchronously. The resultType field MUST
 * be set to "task". This type is Result & Task (flat).
 *
 * @category `tasks`
 */
export type CreateTaskResult = Result &
  Task & {
    /**
     * Discriminator distinguishing a task handle from a standard result.
     */
    resultType: "task";
  };

/* Task Operations */

/**
 * A request to retrieve the state of a task.
 *
 * @category `tasks/get`
 */
export type GetTaskRequest = JSONRPCRequest & {
  method: "tasks/get";
  params: {
    /**
     * The task identifier to query.
     */
    taskId: string;
  };
};

/**
 * The response to a tasks/get request. Carries the appropriate DetailedTask
 * variant for the task's current status. The resultType field MUST be set
 * to "complete".
 *
 * @category `tasks/get`
 */
export type GetTaskResult = Result &
  DetailedTask & {
    /**
     * Discriminator marking this as the standard result shape for tasks/get.
     */
    resultType: "complete";
  };

/**
 * A request to provide input responses to a task in the input_required state.
 *
 * @category `tasks/update`
 */
export type UpdateTaskRequest = JSONRPCRequest & {
  method: "tasks/update";
  params: {
    /**
     * The task identifier to update.
     */
    taskId: string;

    /**
     * Responses to outstanding inputRequests previously surfaced by the server.
     * Each key MUST correspond to a currently-outstanding inputRequest key.
     */
    inputResponses: InputResponses;
  };
};

/**
 * The response to a tasks/update request. An empty acknowledgement.
 * The resultType field MUST be set to "complete".
 *
 * @category `tasks/update`
 */
export type UpdateTaskResult = Result & {
  /**
   * Discriminator marking this as the standard result shape for tasks/update.
   */
  resultType: "complete";
};

/**
 * A request to cancel a task.
 *
 * @category `tasks/cancel`
 */
export type CancelTaskRequest = JSONRPCRequest & {
  method: "tasks/cancel";
  params: {
    /**
     * The task identifier to cancel.
     */
    taskId: string;
  };
};

/**
 * The response to a tasks/cancel request. An empty acknowledgement.
 * Cancellation is cooperative and eventually consistent.
 * The resultType field MUST be set to "complete".
 *
 * @category `tasks/cancel`
 */
export type CancelTaskResult = Result & {
  /**
   * Discriminator marking this as the standard result shape for tasks/cancel.
   */
  resultType: "complete";
};

/* Task Notifications */

/**
 * Parameters for a `notifications/tasks` notification.
 * Carries a complete DetailedTask for the current status.
 *
 * @category `notifications/tasks`
 */
export type TaskStatusNotificationParams = NotificationParams &
  DetailedTask & { [key: string]: unknown };

/**
 * An optional notification from the server to the client, informing it that
 * a task's status has changed. Servers are not required to send these notifications.
 * Clients subscribe via subscriptions/listen.
 *
 * @category `notifications/tasks`
 */
export type TaskStatusNotification = JSONRPCNotification & {
  method: "notifications/tasks";
  params: TaskStatusNotificationParams;
};

/* Subscription Additions */

/**
 * Task-specific fields for the subscriptions/listen request.
 * Clients include tasksStatus to subscribe to notifications/tasks
 * for specific task IDs.
 *
 * @category `subscriptions`
 */
export interface TaskSubscriptionNotifications {
  /**
   * Subscribe to notifications/tasks for specific task IDs.
   */
  taskIds?: string[];
}

/**
 * Task-specific fields for the notifications/subscriptions/acknowledged notification.
 * The server includes the list of task IDs it has agreed to send status notifications for.
 *
 * @category `subscriptions`
 */
export interface TaskSubscriptionAcknowledgedNotifications {
  /**
   * Task IDs the server has agreed to send status notifications for.
   */
  taskIds?: string[];
}

/* Extension Capability */

/**
 * The extension capability declaration for the tasks extension.
 * An empty object indicates support; no extension-specific settings are currently defined.
 *
 * @category `tasks`
 */
export type TasksExtensionCapability = Record<string, never>;