104 lines
4.1 KiB
C#
104 lines
4.1 KiB
C#
using System.Diagnostics;
|
|
using System.Diagnostics.CodeAnalysis;
|
|
using System.Text.Json.Serialization;
|
|
|
|
namespace ModelContextProtocol.Protocol;
|
|
|
|
/// <summary>
|
|
/// Represents an MCP task, which is a durable state machine carrying information
|
|
/// about the underlying execution state of a request.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>
|
|
/// Tasks are useful for representing expensive computations and batch processing requests.
|
|
/// Each task is uniquely identifiable by a receiver-generated task ID.
|
|
/// </para>
|
|
/// <para>
|
|
/// Tasks follow a defined lifecycle through the <see cref="Status"/> property. They begin
|
|
/// in the <see cref="McpTaskStatus.Working"/> status and may transition through various states
|
|
/// before reaching a terminal status (<see cref="McpTaskStatus.Completed"/>, <see cref="McpTaskStatus.Failed"/>,
|
|
/// or <see cref="McpTaskStatus.Cancelled"/>).
|
|
/// </para>
|
|
/// <para>
|
|
/// See the <see href="https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/draft/basic/utilities/tasks.mdx">tasks specification</see> for details.
|
|
/// </para>
|
|
/// </remarks>
|
|
[DebuggerDisplay("{DebuggerDisplay,nq}")]
|
|
[Experimental(Experimentals.Tasks_DiagnosticId, UrlFormat = Experimentals.Tasks_Url)]
|
|
public sealed class McpTask
|
|
{
|
|
/// <summary>
|
|
/// Gets or sets the unique identifier for the task.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Task IDs are generated by the receiver when creating a task and must be unique
|
|
/// among all tasks controlled by that receiver.
|
|
/// </remarks>
|
|
[JsonPropertyName("taskId")]
|
|
public required string TaskId { get; set; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the current state of the task execution.
|
|
/// </summary>
|
|
[JsonPropertyName("status")]
|
|
public required McpTaskStatus Status { get; set; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets an optional human-readable message describing the current state.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// This message can be present for any status, including error details for failed tasks.
|
|
/// </remarks>
|
|
[JsonPropertyName("statusMessage")]
|
|
public string? StatusMessage { get; set; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the ISO 8601 timestamp when the task was created.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Receivers must include this timestamp in all task responses to indicate when
|
|
/// the task was created.
|
|
/// </remarks>
|
|
[JsonPropertyName("createdAt")]
|
|
public required DateTimeOffset CreatedAt { get; set; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the ISO 8601 timestamp when the task status was last updated.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Receivers must include this timestamp in all task responses to indicate when
|
|
/// the task was last updated.
|
|
/// </remarks>
|
|
[JsonPropertyName("lastUpdatedAt")]
|
|
public required DateTimeOffset LastUpdatedAt { get; set; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the time to live (retention duration) from creation before the task may be deleted.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>
|
|
/// A null value indicates unlimited lifetime. After a task's TTL lifetime has elapsed,
|
|
/// receivers may delete the task and its results, regardless of the task status.
|
|
/// </para>
|
|
/// <para>
|
|
/// Receivers may override the requested TTL duration and must include the actual TTL
|
|
/// duration (or null for unlimited) in task responses.
|
|
/// </para>
|
|
/// </remarks>
|
|
[JsonPropertyName("ttl")]
|
|
[JsonConverter(typeof(TimeSpanMillisecondsConverter))]
|
|
public TimeSpan? TimeToLive { get; set; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the suggested time between status checks.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Requestors should respect this value when provided to avoid excessive polling.
|
|
/// This value is optional and may not be present in all task responses.
|
|
/// </remarks>
|
|
[JsonPropertyName("pollInterval")]
|
|
[JsonConverter(typeof(TimeSpanMillisecondsConverter))]
|
|
public TimeSpan? PollInterval { get; set; }
|
|
|
|
private string DebuggerDisplay => $"Task {TaskId}: {Status}" + (StatusMessage != null ? $" - {StatusMessage}" : "");
|
|
}
|