Implement MCP task support (SEP-1686) (#1170)

Co-authored-by: Stephen Halter <halter73@gmail.com>

src/ModelContextProtocol.Core/Protocol/McpTask.cs

@@ -0,0 +1,104 @@
+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}" : "");
+}