Add ElicitAsync<T> (#630) (#715)

* Add ElicitAsync<T> (#630)

- Refactored `ElicitResult` to a generic class `ElicitResult<T>` for typed content.
- Added `ElicitAsync<T>` method in `McpServerExtensions.cs` to request user input and construct schemas based on type `T`.
- Implemented schema building logic to handle primitive types and enums, ignoring unsupported types.
- Introduced `ElicitationTypedTests.cs` for testing the new elicitation functionality with typed forms.
- Verified naming policies in tests to ensure correct serialization casing.
- Defined `SampleForm` and `CamelForm` classes for expected input shapes, including unsupported properties for schema testing.
- Created JSON serialization contexts for both forms using source generation for improved performance.

* Fix the enum issue. for ElicitAsync<T>.

* Use AIJsonUtilities.CreateJsonSchema to create PrimitiveSchemaDefinition. #630

Renamed `BuildRequestSchemaFor<T>` to `BuildRequestSchema<T>`.
Updated the implementation to use `CreatePrimitiveSchema` and
enhanced type checks for supported primitives with
`AIJsonUtilities.CreateJsonSchema`. Streamlined handling of
unsupported types by consolidating return statements.

* Simplify ElicitAsync for schema validation. #630

Simplified the `ElicitAsync` method in `McpServerExtensions.cs` by removing unnecessary JSON object construction and directly deserializing `raw.Content`. Updated `CreatePrimitiveSchema` to use `JsonTypeInfo` for type checking and adjusted return logic for unsupported types.

In `ElicitationTypedTests.cs`, modified the `Can_Elicit_Typed_Information` test to account for the new `Created` property in `SampleForm`, increasing the expected property count from 5 to 6. Added assertions for the type and format of the `Created` property and included its deserialization in the test setup.

* Add error handling for unsupported elicitation types #630

Introduce exception handling in `McpServerExtensions.cs` for unsupported types. Add a test case in `ElicitationTypedTests.cs` to verify exception throwing for unsupported types. Define a new `UnsupportedForm` class with nested properties and include JSON serialization attributes for proper handling.

* Validate generic types in BuildRequestSchema #630

Introduce validation to ensure only object types are supported for elicitation requests in the `BuildRequestSchema` method. An exception is thrown for non-object types. Update the test suite with a new test case to verify this behavior, ensuring that an exception is raised when eliciting a non-object generic type (e.g., string) and that the elicitation handler is not invoked in this scenario.

* Move nullable types handling logic to ElicitationRequestParams.Coverter. #630

* Add schema validation for elicitation requests

Introduce `TryValidateElicitationPrimitiveSchema` method to validate JSON schemas for elicitation requests. This method checks for object type, verifies the "type" property, and ensures compliance with allowed properties based on primitive types (string, boolean, number). Integrate this validation in the `BuildRequestSchema` method to ensure generated schemas are valid before further processing.

* Refactor nullable type pattern matching. #630

* Update src/ModelContextProtocol.Core/Server/McpServerExtensions.cs

Co-authored-by: Eirik Tsarpalis <[email protected]>

* Update src/ModelContextProtocol.Core/Server/McpServerExtensions.cs

Co-authored-by: Eirik Tsarpalis <[email protected]>

* Update src/ModelContextProtocol.Core/Server/McpServerExtensions.cs

Co-authored-by: Eirik Tsarpalis <[email protected]>

* Update src/ModelContextProtocol.Core/Server/McpServerExtensions.cs

Co-authored-by: Eirik Tsarpalis <[email protected]>

* Update src/ModelContextProtocol.Core/Server/McpServerExtensions.cs

Co-authored-by: Eirik Tsarpalis <[email protected]>

* Add ElicitResultSchemaCache. #630

* Prepopulate elicit schema validation logic. #630

- Introduced `LazyElicitAllowedProperties` to cache allowed property names for primitive types, replacing hardcoded logic.
- Streamlined `TryValidateElicitationPrimitiveSchema` method by consolidating type checks using pattern matching.
- Removed manual addition of allowed properties and now retrieve them directly from the new dictionary.
- Updated handling of "integer" type to be treated as "number" for consistency.

* Use Nullable.GetUnderlyingType to handle nullable types on elicitation. #630

- Update `ElicitRequestParams.cs` to throw a `JsonException` for non-string "type" properties, simplifying error handling.
- Modify `CreatePrimitiveSchema` in `McpServerExtensions.cs` to better handle nullable types and improve error messages.
- Revise `TryValidateElicitationPrimitiveSchema` to accept schema as the first parameter, enhancing clarity in error reporting.
- Simplify validation logic for the "type" keyword by directly retrieving string values, ensuring unsupported "type" arrays are flagged as errors.

* Rename static field.

Co-authored-by: Eirik Tsarpalis <[email protected]>

* Fix static field renamings. #630

* Make BuildRequestSchema non-generic. #630

* Avoid closure allocation for serializerOptions on netcore  #630

Updated the `GetOrAdd` method to use a generic type parameter for .NET, allowing for better handling of `JsonSerializerOptions`. Retained the original implementation for other frameworks to ensure compatibility.

* Refactor ElicitRequestParams and McpServerExtensions. #630

- Simplified "type" property handling in Converter.
- Changed s_lazyElicitAllowedProperties to nullable type.
- Updated ElicitAsync to use static lambda for clarity.
- Refactored CreatePrimitiveSchema to handle nullable types.
- Initialized allowed properties in TryValidateElicitationPrimitiveSchema.
- Updated ElicitationTypedTests for naming conventions and added tests for nullable properties.
- Enforced required properties in SampleForm and introduced NullablePropertyForm.
- Added JSON source generation context for NullablePropertyForm.

* Remove reduntant checks. #630

Refactor JSON schema type handling and add integer support

This commit simplifies the validation logic for the `type` property in the JSON schema by removing unnecessary conditional checks. It directly retrieves the string value from `typeProperty` and assigns it to `typeKeyword`. Additionally, it enhances the `s_lazyElicitAllowedProperties` dictionary to include support for the `integer` type, allowing it to be recognized as a valid type with its corresponding allowed properties.

* Add IsAccepted property and update ElicitAsync return type

- Introduced `IsAccepted` property in `ElicitResult` and `ElicitResult<T>` to indicate if the action was accepted.
- Changed `ElicitAsync<T>` to return `ValueTask<ElicitResult<T>>` instead of `ValueTask<ElicitResult<T?>>`, ensuring non-nullable results.
- Updated return statements in `ElicitAsync<T>` to reflect the new return type, treating `Content` as non-nullable.

* Rename to s_elicitAllowedProperties

Co-authored-by: Eirik Tsarpalis <[email protected]>

* Fix renaming s_elicitAllowedProperties. #630

* Remove unnecessary json attributes. #630

* Improve xml comment

Co-authored-by: Eirik Tsarpalis <[email protected]>

* Remove extra IsAccepted property. #630

* Use IsAccepted for checks.

Co-authored-by: Stephen Toub <[email protected]>

* Add IsAccepted to non-generic ElicitResult.

---------

Co-authored-by: Eirik Tsarpalis <[email protected]>
Co-authored-by: Stephen Toub <[email protected]>

Author: 3 people

src/ModelContextProtocol.Core/Protocol/ElicitResult.cs

@@ -33,6 +33,15 @@ public sealed class ElicitResult : Result
     [JsonPropertyName("action")]
     public string Action { get; set; } = "cancel";
 
+    /// <summary>
+    /// Convenience indicator for whether the elicitation was accepted by the user.
+    /// </summary>
+    /// <remarks>
+    ///  Indicates that the elicitation request completed successfully and value of <see cref="Content"/> has been populated with a value.
+    /// </remarks>
+    [JsonIgnore]
+    public bool IsAccepted => string.Equals(Action, "accept", StringComparison.OrdinalIgnoreCase);
+
     /// <summary>
     /// Gets or sets the submitted form data.
     /// </summary>
@@ -48,3 +57,28 @@ public sealed class ElicitResult : Result
     [JsonPropertyName("content")]
     public IDictionary<string, JsonElement>? Content { get; set; }
 }
+
+/// <summary>
+/// Represents the client's response to an elicitation request, with typed content payload.
+/// </summary>
+/// <typeparam name="T">The type of the expected content payload.</typeparam>
+public sealed class ElicitResult<T> : Result
+{
+    /// <summary>
+    /// Gets or sets the user action in response to the elicitation.
+    /// </summary>
+    public string Action { get; set; } = "cancel";
+
+    /// <summary>
+    /// Convenience indicator for whether the elicitation was accepted by the user.
+    /// </summary>
+    /// <remarks>
+    ///  Indicates that the elicitation request completed successfully and value of <see cref="Content"/> has been populated with a value.
+    /// </remarks>
+    public bool IsAccepted => string.Equals(Action, "accept", StringComparison.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Gets or sets the submitted form data as a typed value.
+    /// </summary>
+    public T? Content { get; set; }
+}

src/ModelContextProtocol.Core/Server/McpServerExtensions.cs

@@ -1,9 +1,13 @@
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.Logging;
 using ModelContextProtocol.Protocol;
+using System.Collections.Concurrent;
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Text;
 using System.Text.Json;
+using System.Text.Json.Nodes;
+using System.Text.Json.Serialization.Metadata;
 
 namespace ModelContextProtocol.Server;
 
@@ -12,6 +16,13 @@ namespace ModelContextProtocol.Server;
 /// </summary>
 public static class McpServerExtensions
 {
+    /// <summary>
+    /// Caches request schemas for elicitation requests based on the type and serializer options.
+    /// </summary>
+    private static readonly ConditionalWeakTable<JsonSerializerOptions, ConcurrentDictionary<Type, ElicitRequestParams.RequestSchema>> s_elicitResultSchemaCache = new();
+
+    private static Dictionary<string, HashSet<string>>? s_elicitAllowedProperties = null;
+
     /// <summary>
     /// Requests to sample an LLM via the client using the specified request parameters.
     /// </summary>
@@ -234,6 +245,190 @@ public static ValueTask<ElicitResult> ElicitAsync(
             cancellationToken: cancellationToken);
     }
 
+    /// <summary>
+    /// Requests additional information from the user via the client, constructing a request schema from the
+    /// public serializable properties of <typeparamref name="T"/> and deserializing the response into <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The type describing the expected input shape. Only primitive members are supported (string, number, boolean, enum).</typeparam>
+    /// <param name="server">The server initiating the request.</param>
+    /// <param name="message">The message to present to the user.</param>
+    /// <param name="serializerOptions">Serializer options that influence property naming and deserialization.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
+    /// <returns>An <see cref="ElicitResult{T}"/> with the user's response, if accepted.</returns>
+    /// <remarks>
+    /// Elicitation uses a constrained subset of JSON Schema and only supports strings, numbers/integers, booleans and string enums.
+    /// Unsupported member types are ignored when constructing the schema.
+    /// </remarks>
+    public static async ValueTask<ElicitResult<T>> ElicitAsync<T>(
+        this IMcpServer server,
+        string message,
+        JsonSerializerOptions? serializerOptions = null,
+        CancellationToken cancellationToken = default)
+    {
+        Throw.IfNull(server);
+        ThrowIfElicitationUnsupported(server);
+
+        serializerOptions ??= McpJsonUtilities.DefaultOptions;
+        serializerOptions.MakeReadOnly();
+
+        var dict = s_elicitResultSchemaCache.GetValue(serializerOptions, _ => new());
+
+#if NET
+        var schema = dict.GetOrAdd(typeof(T), static (t, s) => BuildRequestSchema(t, s), serializerOptions);
+#else
+        var schema = dict.GetOrAdd(typeof(T), type => BuildRequestSchema(type, serializerOptions));
+#endif
+
+        var request = new ElicitRequestParams
+        {
+            Message = message,
+            RequestedSchema = schema,
+        };
+
+        var raw = await server.ElicitAsync(request, cancellationToken).ConfigureAwait(false);
+
+        if (!raw.IsAccepted || raw.Content is null)
+        {
+            return new ElicitResult<T> { Action = raw.Action, Content = default };
+        }
+
+        var obj = new JsonObject();
+        foreach (var kvp in raw.Content)
+        {
+            obj[kvp.Key] = JsonNode.Parse(kvp.Value.GetRawText());
+        }
+
+        T? typed = JsonSerializer.Deserialize(obj, serializerOptions.GetTypeInfo<T>());
+        return new ElicitResult<T> { Action = raw.Action, Content = typed };
+    }
+
+    /// <summary>
+    /// Builds a request schema for elicitation based on the public serializable properties of <paramref name="type"/>.
+    /// </summary>
+    /// <param name="type">The type of the schema being built.</param>
+    /// <param name="serializerOptions">The serializer options to use.</param>
+    /// <returns>The built request schema.</returns>
+    /// <exception cref="McpException"></exception>
+    private static ElicitRequestParams.RequestSchema BuildRequestSchema(Type type, JsonSerializerOptions serializerOptions)
+    {
+        var schema = new ElicitRequestParams.RequestSchema();
+        var props = schema.Properties;
+
+        JsonTypeInfo typeInfo = serializerOptions.GetTypeInfo(type);
+
+        if (typeInfo.Kind != JsonTypeInfoKind.Object)
+        {
+            throw new McpException($"Type '{type.FullName}' is not supported for elicitation requests.");
+        }
+
+        foreach (JsonPropertyInfo pi in typeInfo.Properties)
+        {
+            var def = CreatePrimitiveSchema(pi.PropertyType, serializerOptions);
+            props[pi.Name] = def;
+        }
+
+        return schema;
+    }
+
+    /// <summary>
+    /// Creates a primitive schema definition for the specified type, if supported.
+    /// </summary>
+    /// <param name="type">The type to create the schema for.</param>
+    /// <param name="serializerOptions">The serializer options to use.</param>
+    /// <returns>The created primitive schema definition.</returns>
+    /// <exception cref="McpException">Thrown when the type is not supported.</exception>
+    private static ElicitRequestParams.PrimitiveSchemaDefinition CreatePrimitiveSchema(Type type, JsonSerializerOptions serializerOptions)
+    {
+        if (type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Nullable<>))
+        {
+            throw new McpException($"Type '{type.FullName}' is not a supported property type for elicitation requests. Nullable types are not supported.");
+        }
+
+        var typeInfo = serializerOptions.GetTypeInfo(type);
+
+        if (typeInfo.Kind != JsonTypeInfoKind.None)
+        {
+            throw new McpException($"Type '{type.FullName}' is not a supported property type for elicitation requests.");
+        }
+
+        var jsonElement = AIJsonUtilities.CreateJsonSchema(type, serializerOptions: serializerOptions);
+
+        if (!TryValidateElicitationPrimitiveSchema(jsonElement, type, out var error))
+        {
+            throw new McpException(error);
+        }
+
+        var primitiveSchemaDefinition =
+            jsonElement.Deserialize(McpJsonUtilities.JsonContext.Default.PrimitiveSchemaDefinition);
+        
+        if (primitiveSchemaDefinition is null)
+            throw new McpException($"Type '{type.FullName}' is not a supported property type for elicitation requests.");
+
+        return primitiveSchemaDefinition;
+    }
+
+    /// <summary>
+    /// Validate the produced schema strictly to the subset we support. We only accept an object schema
+    /// with a supported primitive type keyword and no additional unsupported keywords.Reject things like
+    /// {}, 'true', or schemas that include unrelated keywords(e.g.items, properties, patternProperties, etc.).
+    /// </summary>
+    /// <param name="schema">The schema to validate.</param>
+    /// <param name="type">The type of the schema being validated, just for reporting errors.</param>
+    /// <param name="error">The error message, if validation fails.</param>
+    /// <returns></returns>
+    private static bool TryValidateElicitationPrimitiveSchema(JsonElement schema, Type type,
+        [NotNullWhen(false)] out string? error)
+    {
+        if (schema.ValueKind is not JsonValueKind.Object)
+        {
+            error = $"Schema generated for type '{type.FullName}' is invalid: expected an object schema.";
+            return false;
+        }
+
+        if (!schema.TryGetProperty("type", out JsonElement typeProperty)
+            || typeProperty.ValueKind is not JsonValueKind.String)
+        {
+            error = $"Schema generated for type '{type.FullName}' is invalid: missing or invalid 'type' keyword.";
+            return false;
+        }
+
+        var typeKeyword = typeProperty.GetString();
+
+        if (string.IsNullOrEmpty(typeKeyword))
+        {
+            error = $"Schema generated for type '{type.FullName}' is invalid: empty 'type' value.";
+            return false;
+        }
+
+        if (typeKeyword is not ("string" or "number" or "integer" or "boolean"))
+        {
+            error = $"Schema generated for type '{type.FullName}' is invalid: unsupported primitive type '{typeKeyword}'.";
+            return false;
+        }
+
+        s_elicitAllowedProperties ??= new()
+        {
+            ["string"] = ["type", "title", "description", "minLength", "maxLength", "format", "enum", "enumNames"],
+            ["number"] = ["type", "title", "description", "minimum", "maximum"],
+            ["integer"] = ["type", "title", "description", "minimum", "maximum"],
+            ["boolean"] = ["type", "title", "description", "default"]
+        };
+
+        var allowed = s_elicitAllowedProperties[typeKeyword];
+
+        foreach (JsonProperty prop in schema.EnumerateObject())
+        {
+            if (!allowed.Contains(prop.Name))
+            {
+                error = $"The property '{type.FullName}.{prop.Name}' is not supported for elicitation.";
+                return false;
+            }
+        }
+
+        error = string.Empty;
+        return true;
+    }
+
     private static void ThrowIfSamplingUnsupported(IMcpServer server)
     {
         if (server.ClientCapabilities?.Sampling is null)