Update MCP support to accomodate responses and approvals

Author: stephentoub

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AIContent.cs

@@ -14,8 +14,6 @@ namespace Microsoft.Extensions.AI;
 [JsonDerivedType(typeof(FunctionResultContent), typeDiscriminator: "functionResult")]
 [JsonDerivedType(typeof(HostedFileContent), typeDiscriminator: "hostedFile")]
 [JsonDerivedType(typeof(HostedVectorStoreContent), typeDiscriminator: "hostedVectorStore")]
-[JsonDerivedType(typeof(McpServerToolCallContent), typeDiscriminator: "mcpServerToolCall")]
-[JsonDerivedType(typeof(McpServerToolResultContent), typeDiscriminator: "mcpServerToolResult")]
 [JsonDerivedType(typeof(TextContent), typeDiscriminator: "text")]
 [JsonDerivedType(typeof(TextReasoningContent), typeDiscriminator: "reasoning")]
 [JsonDerivedType(typeof(UriContent), typeDiscriminator: "uri")]
@@ -26,6 +24,10 @@ namespace Microsoft.Extensions.AI;
 // experimental types in its source generated files.
 // [JsonDerivedType(typeof(FunctionApprovalRequestContent), typeDiscriminator: "functionApprovalRequest")]
 // [JsonDerivedType(typeof(FunctionApprovalResponseContent), typeDiscriminator: "functionApprovalResponse")]
+// [JsonDerivedType(typeof(McpServerToolCallContent), typeDiscriminator: "mcpServerToolCall")]
+// [JsonDerivedType(typeof(McpServerToolResultContent), typeDiscriminator: "mcpServerToolResult")]
+// [JsonDerivedType(typeof(McpServerToolApprovalRequestContent), typeDiscriminator: "mcpServerToolApprovalRequest")]
+// [JsonDerivedType(typeof(McpServerToolApprovalResponseContent), typeDiscriminator: "mcpServerToolApprovalResponse")]
 
 public class AIContent
 {

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/McpServerToolApprovalRequestContent.cs

@@ -0,0 +1,41 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a request for user approval of an MCP server tool call.
+/// </summary>
+[Experimental("MEAI001")]
+public sealed class McpServerToolApprovalRequestContent : UserInputRequestContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="McpServerToolApprovalRequestContent"/> class.
+    /// </summary>
+    /// <param name="id">The ID that uniquely identifies the MCP server tool approval request/response pair.</param>
+    /// <param name="toolCall">The tool call that requires user approval.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="id"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="id"/> is empty or composed entirely of whitespace.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="toolCall"/> is <see langword="null"/>.</exception>
+    public McpServerToolApprovalRequestContent(string id, McpServerToolCallContent toolCall)
+        : base(id)
+    {
+        ToolCall = Throw.IfNull(toolCall);
+    }
+
+    /// <summary>
+    /// Gets the tool call that pre-invoke approval is required for.
+    /// </summary>
+    public McpServerToolCallContent ToolCall { get; }
+
+    /// <summary>
+    /// Creates a <see cref="McpServerToolApprovalResponseContent"/> to indicate whether the function call is approved or rejected based on the value of <paramref name="approved"/>.
+    /// </summary>
+    /// <param name="approved"><see langword="true"/> if the function call is approved; otherwise, <see langword="false"/>.</param>
+    /// <returns>The <see cref="FunctionApprovalResponseContent"/> representing the approval response.</returns>
+    public McpServerToolApprovalResponseContent CreateResponse(bool approved) => new(Id, approved);
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/McpServerToolApprovalResponseContent.cs

@@ -0,0 +1,32 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a response to an MCP server tool approval request.
+/// </summary>
+[Experimental("MEAI001")]
+public sealed class McpServerToolApprovalResponseContent : UserInputResponseContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="McpServerToolApprovalResponseContent"/> class.
+    /// </summary>
+    /// <param name="id">The ID that uniquely identifies the MCP server tool approval request/response pair.</param>
+    /// <param name="approved"><see langword="true"/> if the MCP server tool call is approved; otherwise, <see langword="false"/>.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="id"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="id"/> is empty or composed entirely of whitespace.</exception>
+    public McpServerToolApprovalResponseContent(string id, bool approved)
+        : base(id)
+    {
+        Approved = approved;
+    }
+
+    /// <summary>
+    /// Gets a value indicating whether the user approved the request.
+    /// </summary>
+    public bool Approved { get; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/McpServerToolCallContent.cs

@@ -3,14 +3,20 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents a tool call request to a MCP server.
 /// </summary>
-public class McpServerToolCallContent : AIContent
+/// <remarks>
+/// This content type is used to represent an invocation of an MCP server tool by a hosted service.
+/// It is informational only.
+/// </remarks>
+[Experimental("MEAI001")]
+public sealed class McpServerToolCallContent : AIContent
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="McpServerToolCallContent"/> class.

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/McpServerToolResultContent.cs

@@ -3,14 +3,20 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents the result of a MCP server tool call.
 /// </summary>
-public class McpServerToolResultContent : AIContent
+/// <remarks>
+/// This content type is used to represent the result of an invocation of an MCP server tool by a hosted service.
+/// It is informational only.
+/// </remarks>
+[Experimental("MEAI001")]
+public sealed class McpServerToolResultContent : AIContent
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="McpServerToolResultContent"/> class.

src/Libraries/Microsoft.Extensions.AI.Abstractions/HostedMcpServerToolAlwaysRequireApprovalMode.cs

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 
 namespace Microsoft.Extensions.AI;
 
@@ -11,6 +12,7 @@ namespace Microsoft.Extensions.AI;
 /// <remarks>
 /// Use <see cref="HostedMcpServerToolApprovalMode.AlwaysRequire"/> to get an instance of <see cref="HostedMcpServerToolAlwaysRequireApprovalMode"/>.
 /// </remarks>
+[Experimental("MEAI001")]
 [DebuggerDisplay(nameof(AlwaysRequire))]
 public sealed class HostedMcpServerToolAlwaysRequireApprovalMode : HostedMcpServerToolApprovalMode
 {

src/Libraries/Microsoft.Extensions.AI.Abstractions/HostedMcpServerToolApprovalMode.cs

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
 
 namespace Microsoft.Extensions.AI;
@@ -13,6 +14,7 @@ namespace Microsoft.Extensions.AI;
 /// The predefined values <see cref="AlwaysRequire" />, and <see cref="NeverRequire"/> are provided to specify handling for all tools.
 /// To specify approval behavior for individual tool names, use <see cref="RequireSpecific(IList{string}, IList{string})"/>.
 /// </remarks>
+[Experimental("MEAI001")]
 [JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
 [JsonDerivedType(typeof(HostedMcpServerToolNeverRequireApprovalMode), typeDiscriminator: "never")]
 [JsonDerivedType(typeof(HostedMcpServerToolAlwaysRequireApprovalMode), typeDiscriminator: "always")]

src/Libraries/Microsoft.Extensions.AI.Abstractions/HostedMcpServerToolNeverRequireApprovalMode.cs

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 
 namespace Microsoft.Extensions.AI;
 
@@ -11,6 +12,7 @@ namespace Microsoft.Extensions.AI;
 /// <remarks>
 /// Use <see cref="HostedMcpServerToolApprovalMode.NeverRequire"/> to get an instance of <see cref="HostedMcpServerToolNeverRequireApprovalMode"/>.
 /// </remarks>
+[Experimental("MEAI001")]
 [DebuggerDisplay(nameof(NeverRequire))]
 public sealed class HostedMcpServerToolNeverRequireApprovalMode : HostedMcpServerToolApprovalMode
 {

src/Libraries/Microsoft.Extensions.AI.Abstractions/HostedMcpServerToolRequireSpecificApprovalMode.cs

@@ -3,13 +3,15 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents a mode where approval behavior is specified for individual tool names.
 /// </summary>
+[Experimental("MEAI001")]
 public sealed class HostedMcpServerToolRequireSpecificApprovalMode : HostedMcpServerToolApprovalMode
 {
     /// <summary>
@@ -42,20 +44,9 @@ public override bool Equals(object? obj) => obj is HostedMcpServerToolRequireSpe
     public override int GetHashCode() =>
         HashCode.Combine(GetListHashCode(AlwaysRequireApprovalToolNames), GetListHashCode(NeverRequireApprovalToolNames));
 
-    private static bool ListEquals(IList<string>? list1, IList<string>? list2)
-    {
-        if (ReferenceEquals(list1, list2))
-        {
-            return true;
-        }
-
-        if (list1 is null || list2 is null)
-        {
-            return false;
-        }
-
-        return list1.SequenceEqual(list2);
-    }
+    private static bool ListEquals(IList<string>? list1, IList<string>? list2) =>
+        ReferenceEquals(list1, list2) ||
+        (list1 is not null && list2 is not null && list1.SequenceEqual(list2));
 
     private static int GetListHashCode(IList<string>? list)
     {
@@ -64,7 +55,7 @@ private static int GetListHashCode(IList<string>? list)
             return 0;
         }
 
-        var hc = default(HashCode);
+        HashCode hc = default;
         foreach (string item in list)
         {
             hc.Add(item);