Add elicitation capability (#467)

* Add elicitation capability

src/ModelContextProtocol/Client/McpClient.cs

@@ -76,6 +76,20 @@ internal sealed partial class McpClient : McpEndpoint, IMcpClient
                     McpJsonUtilities.JsonContext.Default.ListRootsRequestParams,
                     McpJsonUtilities.JsonContext.Default.ListRootsResult);
             }
+
+            if (capabilities.Elicitation is { } elicitationCapability)
+            {
+                if (elicitationCapability.ElicitationHandler is not { } elicitationHandler)
+                {
+                    throw new InvalidOperationException("Elicitation capability was set but it did not provide a handler.");
+                }
+
+                RequestHandlers.Set(
+                    RequestMethods.ElicitationCreate,
+                    (request, _, cancellationToken) => elicitationHandler(request, cancellationToken),
+                    McpJsonUtilities.JsonContext.Default.ElicitRequestParams,
+                    McpJsonUtilities.JsonContext.Default.ElicitResult);
+            }
         }
     }
 

src/ModelContextProtocol/McpJsonUtilities.cs

@@ -96,6 +96,8 @@ public static partial class McpJsonUtilities
     [JsonSerializable(typeof(CompleteResult))]
     [JsonSerializable(typeof(CreateMessageRequestParams))]
     [JsonSerializable(typeof(CreateMessageResult))]
+    [JsonSerializable(typeof(ElicitRequestParams))]
+    [JsonSerializable(typeof(ElicitResult))]
     [JsonSerializable(typeof(EmptyResult))]
     [JsonSerializable(typeof(GetPromptRequestParams))]
     [JsonSerializable(typeof(GetPromptResult))]

src/ModelContextProtocol/Protocol/ClientCapabilities.cs

@@ -58,6 +58,13 @@ public class ClientCapabilities
     [JsonPropertyName("sampling")]
     public SamplingCapability? Sampling { get; set; }
 
+    /// <summary>
+    /// Gets or sets the client's elicitation capability, which indicates whether the client 
+    /// supports elicitation of additional information from the user on behalf of the server.
+    /// </summary>
+    [JsonPropertyName("elicitation")]
+    public ElicitationCapability? Elicitation { get; set; }
+
     /// <summary>Gets or sets notification handlers to register with the client.</summary>
     /// <remarks>
     /// <para>

src/ModelContextProtocol/Protocol/ElicitRequestParams.cs

@@ -0,0 +1,230 @@
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents a message issued from the server to elicit additional information from the user via the client.
+/// </summary>
+public class ElicitRequestParams
+{
+    /// <summary>
+    /// Gets or sets the message to present to the user.
+    /// </summary>
+    [JsonPropertyName("message")]
+    public string Message { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the requested schema.
+    /// </summary>
+    /// <remarks>
+    /// May be one of <see cref="StringSchema"/>, <see cref="NumberSchema"/>, <see cref="BooleanSchema"/>, or <see cref="EnumSchema"/>.
+    /// </remarks>
+    [JsonPropertyName("requestedSchema")]
+    [field: MaybeNull]
+    public RequestSchema RequestedSchema
+    {
+        get => field ??= new RequestSchema();
+        set => field = value;
+    }
+
+    /// <summary>Represents a request schema used in an elicitation request.</summary>
+    public class RequestSchema
+    {
+        /// <summary>Gets the type of the schema.</summary>
+        /// <remarks>This is always "object".</remarks>
+        [JsonPropertyName("type")]
+        public string Type => "object";
+
+        /// <summary>Gets or sets the properties of the schema.</summary>
+        [JsonPropertyName("properties")]
+        [field: MaybeNull]
+        public IDictionary<string, PrimitiveSchemaDefinition> Properties
+        {
+            get => field ??= new Dictionary<string, PrimitiveSchemaDefinition>();
+            set
+            {
+                Throw.IfNull(value);
+                field = value;
+            }
+        }
+
+        /// <summary>Gets or sets the required properties of the schema.</summary>
+        [JsonPropertyName("required")]
+        public IList<string>? Required { get; set; }
+    }
+
+
+    /// <summary>
+    /// Represents restricted subset of JSON Schema: 
+    /// <see cref="StringSchema"/>, <see cref="NumberSchema"/>, <see cref="BooleanSchema"/>, or <see cref="EnumSchema"/>.
+    /// </summary>
+    [JsonDerivedType(typeof(BooleanSchema))]
+    [JsonDerivedType(typeof(EnumSchema))]
+    [JsonDerivedType(typeof(NumberSchema))]
+    [JsonDerivedType(typeof(StringSchema))]
+    public abstract class PrimitiveSchemaDefinition
+    {
+        protected private PrimitiveSchemaDefinition()
+        {
+        }
+    }
+
+    /// <summary>Represents a schema for a string type.</summary>
+    public sealed class StringSchema : PrimitiveSchemaDefinition
+    {
+        /// <summary>Gets the type of the schema.</summary>
+        /// <remarks>This is always "string".</remarks>
+        [JsonPropertyName("type")]
+        public string Type => "string";
+
+        /// <summary>Gets or sets a title for the string.</summary>
+        [JsonPropertyName("title")]
+        public string? Title { get; set; }
+
+        /// <summary>Gets or sets a description for the string.</summary>
+        [JsonPropertyName("description")]
+        public string? Description { get; set; }
+
+        /// <summary>Gets or sets the minimum length for the string.</summary>
+        [JsonPropertyName("minLength")]
+        public int? MinLength
+        {
+            get => field;
+            set
+            {
+                if (value < 0)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), "Minimum length cannot be negative.");
+                }
+
+                field = value;
+            }
+        }
+
+        /// <summary>Gets or sets the maximum length for the string.</summary>
+        [JsonPropertyName("maxLength")]
+        public int? MaxLength
+        {
+            get => field;
+            set
+            {
+                if (value < 0)
+                {
+                    throw new ArgumentOutOfRangeException(nameof(value), "Maximum length cannot be negative.");
+                }
+
+                field = value;
+            }
+        }
+
+        /// <summary>Gets or sets a specific format for the string ("email", "uri", "date", or "date-time").</summary>
+        [JsonPropertyName("format")]
+        public string? Format
+        {
+            get => field;
+            set
+            {
+                if (value is not (null or "email" or "uri" or "date" or "date-time"))
+                {
+                    throw new ArgumentException("Format must be 'email', 'uri', 'date', or 'date-time'.", nameof(value));
+                }
+
+                field = value;
+            }
+        }
+    }
+
+    /// <summary>Represents a schema for a number or integer type.</summary>
+    public sealed class NumberSchema : PrimitiveSchemaDefinition
+    {
+        /// <summary>Gets the type of the schema.</summary>
+        /// <remarks>This should be "number" or "integer".</remarks>
+        [JsonPropertyName("type")]
+        [field: MaybeNull]
+        public string Type
+        {
+            get => field ??= "number";
+            set
+            {
+                if (value is not ("number" or "integer"))
+                {
+                    throw new ArgumentException("Type must be 'number' or 'integer'.", nameof(value));
+                }
+
+                field = value;
+            }
+        }
+
+        /// <summary>Gets or sets a title for the number input.</summary>
+        [JsonPropertyName("title")]
+        public string? Title { get; set; }
+
+        /// <summary>Gets or sets a description for the number input.</summary>
+        [JsonPropertyName("description")]
+        public string? Description { get; set; }
+
+        /// <summary>Gets or sets the minimum allowed value.</summary>
+        [JsonPropertyName("minimum")]
+        public double? Minimum { get; set; }
+
+        /// <summary>Gets or sets the maximum allowed value.</summary>
+        [JsonPropertyName("maximum")]
+        public double? Maximum { get; set; }
+    }
+
+    /// <summary>Represents a schema for a Boolean type.</summary>
+    public sealed class BooleanSchema : PrimitiveSchemaDefinition
+    {
+        /// <summary>Gets the type of the schema.</summary>
+        /// <remarks>This is always "boolean".</remarks>
+        [JsonPropertyName("type")]
+        public string Type => "boolean";
+
+        /// <summary>Gets or sets a title for the Boolean.</summary>
+        [JsonPropertyName("title")]
+        public string? Title { get; set; }
+
+        /// <summary>Gets or sets a description for the Boolean.</summary>
+        [JsonPropertyName("description")]
+        public string? Description { get; set; }
+
+        /// <summary>Gets or sets the default value for the Boolean.</summary>
+        [JsonPropertyName("default")]
+        public bool? Default { get; set; }
+    }
+
+    /// <summary>Represents a schema for an enum type.</summary>
+    public sealed class EnumSchema : PrimitiveSchemaDefinition
+    {
+        /// <summary>Gets the type of the schema.</summary>
+        /// <remarks>This is always "string".</remarks>
+        [JsonPropertyName("type")]
+        public string Type => "string";
+
+        /// <summary>Gets or sets a title for the enum.</summary>
+        [JsonPropertyName("title")]
+        public string? Title { get; set; }
+
+        /// <summary>Gets or sets a description for the enum.</summary>
+        [JsonPropertyName("description")]
+        public string? Description { get; set; }
+
+        /// <summary>Gets or sets the list of allowed string values for the enum.</summary>
+        [JsonPropertyName("enum")]
+        [field: MaybeNull]
+        public IList<string> Enum
+        {
+            get => field ??= [];
+            set
+            {
+                Throw.IfNull(value);
+                field = value;
+            }
+        }
+
+        /// <summary>Gets or sets optional display names corresponding to the enum values.</summary>
+        [JsonPropertyName("enumNames")]
+        public IList<string>? EnumNames { get; set; }
+    }
+}

src/ModelContextProtocol/Protocol/ElicitResult.cs

@@ -0,0 +1,41 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the client's response to an elicitation request.
+/// </summary>
+public class ElicitResult
+{
+    /// <summary>
+    /// Gets or sets the user action in response to the elicitation.
+    /// </summary>
+    /// <remarks>
+    /// <list type="bullet">
+    ///   <item>
+    ///     <term>"accept"</term>
+    ///     <description>User submitted the form/confirmed the action</description>
+    ///   </item>
+    ///   <item>
+    ///     <term>"decline"</term>
+    ///     <description>User explicitly declined the action</description>
+    ///   </item>
+    ///   <item>
+    ///     <term>"cancel"</term>
+    ///     <description>User dismissed without making an explicit choice</description>
+    ///   </item>
+    /// </list>
+    /// </remarks>
+    [JsonPropertyName("action")]
+    public string Action { get; set; } = "cancel";
+
+    /// <summary>
+    /// Gets or sets the submitted form data.
+    /// </summary>
+    /// <remarks>
+    /// This is typically omitted if the action is "cancel" or "decline".
+    /// </remarks>
+    [JsonPropertyName("content")]
+    public JsonElement? Content { get; set; }
+}

src/ModelContextProtocol/Protocol/ElicitationCapability.cs

@@ -0,0 +1,36 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents the capability for a client to provide server-requested additional information during interactions.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This capability enables the MCP client to respond to elicitation requests from an MCP server.
+/// </para>
+/// <para>
+/// When this capability is enabled, an MCP server can request the client to provide additional information
+/// during interactions. The client must set a <see cref="ElicitationHandler"/> to process these requests.
+/// </para>
+/// </remarks>
+public class ElicitationCapability
+{
+    // Currently empty in the spec, but may be extended in the future.
+
+    /// <summary>
+    /// Gets or sets the handler for processing <see cref="RequestMethods.ElicitationCreate"/> requests.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This handler function is called when an MCP server requests the client to provide additional
+    /// information during interactions. The client must set this property for the elicitation capability to work.
+    /// </para>
+    /// <para>
+    /// The handler receives message parameters and a cancellation token.
+    /// It should return a <see cref="ElicitResult"/> containing the response to the elicitation request.
+    /// </para>
+    /// </remarks>
+    [JsonIgnore]
+    public Func<ElicitRequestParams?, CancellationToken, ValueTask<ElicitResult>>? ElicitationHandler { get; set; }
+}

src/ModelContextProtocol/Protocol/RequestMethods.cs

@@ -93,6 +93,15 @@ public static class RequestMethods
     /// </remarks>
     public const string SamplingCreateMessage = "sampling/createMessage";
 
+    /// <summary>
+    /// The name of the request method sent from the client to the server to elicit additional information from the user via the client.
+    /// </summary>
+    /// <remarks>
+    /// This request is used when the server needs more information from the client to proceed with a task or interaction.
+    /// Servers can request structured data from users, with optional JSON schemas to validate responses.
+    /// </remarks>
+    public const string ElicitationCreate = "elicitation/create";
+
     /// <summary>
     /// The name of the request method sent from the client to the server when it first connects, asking it initialize.
     /// </summary>

src/ModelContextProtocol/Server/McpServerExtensions.cs

@@ -20,13 +20,13 @@ public static class McpServerExtensions
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
     /// <returns>A task containing the sampling result from the client.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="server"/> is <see langword="null"/>.</exception>
-    /// <exception cref="ArgumentException">The client does not support sampling.</exception>
+    /// <exception cref="InvalidOperationException">The client does not support sampling.</exception>
     /// <remarks>
     /// This method requires the client to support sampling capabilities.
     /// It allows detailed control over sampling parameters including messages, system prompt, temperature, 
     /// and token limits.
     /// </remarks>
-    public static ValueTask<CreateMessageResult> RequestSamplingAsync(
+    public static ValueTask<CreateMessageResult> SampleAsync(
         this IMcpServer server, CreateMessageRequestParams request, CancellationToken cancellationToken = default)
     {
         Throw.IfNull(server);
@@ -50,12 +50,12 @@ public static class McpServerExtensions
     /// <returns>A task containing the chat response from the model.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="server"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentNullException"><paramref name="messages"/> is <see langword="null"/>.</exception>
-    /// <exception cref="ArgumentException">The client does not support sampling.</exception>
+    /// <exception cref="InvalidOperationException">The client does not support sampling.</exception>
     /// <remarks>
     /// This method converts the provided chat messages into a format suitable for the sampling API,
     /// handling different content types such as text, images, and audio.
     /// </remarks>
-    public static async Task<ChatResponse> RequestSamplingAsync(
+    public static async Task<ChatResponse> SampleAsync(
         this IMcpServer server,
         IEnumerable<ChatMessage> messages, ChatOptions? options = default, CancellationToken cancellationToken = default)
     {
@@ -125,7 +125,7 @@ public static class McpServerExtensions
             modelPreferences = new() { Hints = [new() { Name = modelId }] };
         }
 
-        var result = await server.RequestSamplingAsync(new()
+        var result = await server.SampleAsync(new()
             {
                 Messages = samplingMessages,
                 MaxTokens = options?.MaxOutputTokens,
@@ -152,7 +152,7 @@ public static class McpServerExtensions
     /// <param name="server">The server to be wrapped as an <see cref="IChatClient"/>.</param>
     /// <returns>The <see cref="IChatClient"/> that can be used to issue sampling requests to the client.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="server"/> is <see langword="null"/>.</exception>
-    /// <exception cref="ArgumentException">The client does not support sampling.</exception>
+    /// <exception cref="InvalidOperationException">The client does not support sampling.</exception>
     public static IChatClient AsSamplingChatClient(this IMcpServer server)
     {
         Throw.IfNull(server);
@@ -179,7 +179,7 @@ public static class McpServerExtensions
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
     /// <returns>A task containing the list of roots exposed by the client.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="server"/> is <see langword="null"/>.</exception>
-    /// <exception cref="ArgumentException">The client does not support roots.</exception>
+    /// <exception cref="InvalidOperationException">The client does not support roots.</exception>
     /// <remarks>
     /// This method requires the client to support the roots capability.
     /// Root resources allow clients to expose a hierarchical structure of resources that can be
@@ -200,6 +200,32 @@ public static class McpServerExtensions
             cancellationToken: cancellationToken);
     }
 
+    /// <summary>
+    /// Requests additional information from the user via the client, allowing the server to elicit structured data.
+    /// </summary>
+    /// <param name="server">The server initiating the request.</param>
+    /// <param name="request">The parameters for the elicitation request.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
+    /// <returns>A task containing the elicitation result.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="server"/> is <see langword="null"/>.</exception>
+    /// <exception cref="InvalidOperationException">The client does not support elicitation.</exception>
+    /// <remarks>
+    /// This method requires the client to support the elicitation capability.
+    /// </remarks>
+    public static ValueTask<ElicitResult> ElicitAsync(
+        this IMcpServer server, ElicitRequestParams request, CancellationToken cancellationToken = default)
+    {
+        Throw.IfNull(server);
+        ThrowIfElicitationUnsupported(server);
+
+        return server.SendRequestAsync(
+            RequestMethods.ElicitationCreate,
+            request,
+            McpJsonUtilities.JsonContext.Default.ElicitRequestParams,
+            McpJsonUtilities.JsonContext.Default.ElicitResult,
+            cancellationToken: cancellationToken);
+    }
+
     private static void ThrowIfSamplingUnsupported(IMcpServer server)
     {
         if (server.ClientCapabilities?.Sampling is null)
@@ -226,12 +252,25 @@ public static class McpServerExtensions
         }
     }
 
+    private static void ThrowIfElicitationUnsupported(IMcpServer server)
+    {
+        if (server.ClientCapabilities?.Elicitation is null)
+        {
+            if (server.ServerOptions.KnownClientInfo is not null)
+            {
+                throw new InvalidOperationException("Elicitation is not supported in stateless mode.");
+            }
+
+            throw new InvalidOperationException("Client does not support elicitation requests.");
+        }
+    }
+
     /// <summary>Provides an <see cref="IChatClient"/> implementation that's implemented via client sampling.</summary>
     private sealed class SamplingChatClient(IMcpServer server) : IChatClient
     {
         /// <inheritdoc/>
         public Task<ChatResponse> GetResponseAsync(IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken cancellationToken = default) =>
-            server.RequestSamplingAsync(messages, options, cancellationToken);
+            server.SampleAsync(messages, options, cancellationToken);
 
         /// <inheritdoc/>
         async IAsyncEnumerable<ChatResponseUpdate> IChatClient.GetStreamingResponseAsync(