Add abstraction for remote MCP servers (#6664)

* Simpfliy Responses streaming handling

* Add abstraction for remote MCP servers

* Update MCP support to accomodate responses and approvals

---------

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

Author: jozkee

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/RequiredChatToolMode.cs

@@ -41,12 +41,6 @@ public RequiredChatToolMode(string? requiredFunctionName)
         RequiredFunctionName = requiredFunctionName;
     }
 
-    // The reason for not overriding Equals/GetHashCode (e.g., so two instances are equal if they
-    // have the same RequiredFunctionName) is to leave open the option to unseal the type in the
-    // future. If we did define equality based on RequiredFunctionName but a subclass added further
-    // fields, this would lead to wrong behavior unless the subclass author remembers to re-override
-    // Equals/GetHashCode as well, which they likely won't.
-
     /// <summary>Gets a string representing this instance to display in the debugger.</summary>
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private string DebuggerDisplay => $"Required: {RequiredFunctionName ?? "Any"}";

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

@@ -24,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

@@ -0,0 +1,55 @@
+// 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.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>
+/// <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.
+    /// </summary>
+    /// <param name="callId">The tool call ID.</param>
+    /// <param name="toolName">The tool name.</param>
+    /// <param name="serverName">The MCP server name.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="callId"/>, <paramref name="toolName"/>, or <paramref name="serverName"/> are <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="callId"/>, <paramref name="toolName"/>, or <paramref name="serverName"/> are empty or composed entirely of whitespace.</exception>
+    public McpServerToolCallContent(string callId, string toolName, string serverName)
+    {
+        CallId = Throw.IfNullOrWhitespace(callId);
+        ToolName = Throw.IfNullOrWhitespace(toolName);
+        ServerName = Throw.IfNullOrWhitespace(serverName);
+    }
+
+    /// <summary>
+    /// Gets the tool call ID.
+    /// </summary>
+    public string CallId { get; }
+
+    /// <summary>
+    /// Gets the name of the tool called.
+    /// </summary>
+    public string ToolName { get; }
+
+    /// <summary>
+    /// Gets the name of the MCP server.
+    /// </summary>
+    public string ServerName { get; }
+
+    /// <summary>
+    /// Gets or sets the arguments used for the tool call.
+    /// </summary>
+    public IReadOnlyDictionary<string, object?>? Arguments { get; set; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/McpServerToolResultContent.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.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>
+/// <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.
+    /// </summary>
+    /// <param name="callId">The tool call ID.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="callId"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="callId"/> is empty or composed entirely of whitespace.</exception>
+    public McpServerToolResultContent(string callId)
+    {
+        CallId = Throw.IfNullOrWhitespace(callId);
+    }
+
+    /// <summary>
+    /// Gets the tool call ID.
+    /// </summary>
+    public string CallId { get; }
+
+    /// <summary>
+    /// Gets or sets the output of the tool call.
+    /// </summary>
+    public IList<AIContent>? Output { get; set; }
+}

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

@@ -0,0 +1,30 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Indicates that approval is always required for tool calls to a hosted MCP server.
+/// </summary>
+/// <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
+{
+    /// <summary>Initializes a new instance of the <see cref="HostedMcpServerToolAlwaysRequireApprovalMode"/> class.</summary>
+    /// <remarks>Use <see cref="HostedMcpServerToolApprovalMode.AlwaysRequire"/> to get an instance of <see cref="HostedMcpServerToolAlwaysRequireApprovalMode"/>.</remarks>
+    public HostedMcpServerToolAlwaysRequireApprovalMode()
+    {
+    }
+
+    /// <inheritdoc/>
+    public override bool Equals(object? obj) => obj is HostedMcpServerToolAlwaysRequireApprovalMode;
+
+    /// <inheritdoc/>
+    public override int GetHashCode() => typeof(HostedMcpServerToolAlwaysRequireApprovalMode).GetHashCode();
+}

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

@@ -0,0 +1,48 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// 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;
+
+/// <summary>
+/// Describes how approval is required for tool calls to a hosted MCP server.
+/// </summary>
+/// <remarks>
+/// 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")]
+[JsonDerivedType(typeof(HostedMcpServerToolRequireSpecificApprovalMode), typeDiscriminator: "requireSpecific")]
+#pragma warning disable CA1052 // Static holder types should be Static or NotInheritable
+public class HostedMcpServerToolApprovalMode
+#pragma warning restore CA1052
+{
+    /// <summary>
+    /// Gets a predefined <see cref="HostedMcpServerToolApprovalMode"/> indicating that all tool calls to a hosted MCP server always require approval.
+    /// </summary>
+    public static HostedMcpServerToolAlwaysRequireApprovalMode AlwaysRequire { get; } = new();
+
+    /// <summary>
+    /// Gets a predefined <see cref="HostedMcpServerToolApprovalMode"/> indicating that all tool calls to a hosted MCP server never require approval.
+    /// </summary>
+    public static HostedMcpServerToolNeverRequireApprovalMode NeverRequire { get; } = new();
+
+    private protected HostedMcpServerToolApprovalMode()
+    {
+    }
+
+    /// <summary>
+    /// Instantiates a <see cref="HostedMcpServerToolApprovalMode"/> that specifies approval behavior for individual tool names.
+    /// </summary>
+    /// <param name="alwaysRequireApprovalToolNames">The list of tools names that always require approval.</param>
+    /// <param name="neverRequireApprovalToolNames">The list of tools names that never require approval.</param>
+    /// <returns>An instance of <see cref="HostedMcpServerToolRequireSpecificApprovalMode"/> for the specified tool names.</returns>
+    public static HostedMcpServerToolRequireSpecificApprovalMode RequireSpecific(IList<string>? alwaysRequireApprovalToolNames, IList<string>? neverRequireApprovalToolNames)
+        => new(alwaysRequireApprovalToolNames, neverRequireApprovalToolNames);
+}

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

@@ -0,0 +1,30 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Indicates that approval is never required for tool calls to a hosted MCP server.
+/// </summary>
+/// <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
+{
+    /// <summary>Initializes a new instance of the <see cref="HostedMcpServerToolNeverRequireApprovalMode"/> class.</summary>
+    /// <remarks>Use <see cref="HostedMcpServerToolApprovalMode.NeverRequire"/> to get an instance of <see cref="HostedMcpServerToolNeverRequireApprovalMode"/>.</remarks>
+    public HostedMcpServerToolNeverRequireApprovalMode()
+    {
+    }
+
+    /// <inheritdoc/>
+    public override bool Equals(object? obj) => obj is HostedMcpServerToolNeverRequireApprovalMode;
+
+    /// <inheritdoc/>
+    public override int GetHashCode() => typeof(HostedMcpServerToolNeverRequireApprovalMode).GetHashCode();
+}

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

@@ -0,0 +1,66 @@
+// 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.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>
+    /// Initializes a new instance of the <see cref="HostedMcpServerToolRequireSpecificApprovalMode"/> class that specifies approval behavior for individual tool names.
+    /// </summary>
+    /// <param name="alwaysRequireApprovalToolNames">The list of tools names that always require approval.</param>
+    /// <param name="neverRequireApprovalToolNames">The list of tools names that never require approval.</param>
+    public HostedMcpServerToolRequireSpecificApprovalMode(IList<string>? alwaysRequireApprovalToolNames, IList<string>? neverRequireApprovalToolNames)
+    {
+        AlwaysRequireApprovalToolNames = alwaysRequireApprovalToolNames;
+        NeverRequireApprovalToolNames = neverRequireApprovalToolNames;
+    }
+
+    /// <summary>
+    /// Gets or sets the list of tool names that always require approval.
+    /// </summary>
+    public IList<string>? AlwaysRequireApprovalToolNames { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of tool names that never require approval.
+    /// </summary>
+    public IList<string>? NeverRequireApprovalToolNames { get; set; }
+
+    /// <inheritdoc/>
+    public override bool Equals(object? obj) => obj is HostedMcpServerToolRequireSpecificApprovalMode other &&
+        ListEquals(AlwaysRequireApprovalToolNames, other.AlwaysRequireApprovalToolNames) &&
+        ListEquals(NeverRequireApprovalToolNames, other.NeverRequireApprovalToolNames);
+
+    /// <inheritdoc/>
+    public override int GetHashCode() =>
+        HashCode.Combine(GetListHashCode(AlwaysRequireApprovalToolNames), GetListHashCode(NeverRequireApprovalToolNames));
+
+    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)
+    {
+        if (list is null)
+        {
+            return 0;
+        }
+
+        HashCode hc = default;
+        foreach (string item in list)
+        {
+            hc.Add(item);
+        }
+
+        return hc.ToHashCode();
+    }
+}