Add abstraction for remote MCP servers

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

@@ -14,6 +14,8 @@ 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")]

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

@@ -0,0 +1,49 @@
+// 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 Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a tool call request to a MCP server.
+/// </summary>
+public 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,35 @@
+// 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 Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents the result of a MCP server tool call.
+/// </summary>
+public 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,28 @@
+// 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;
+
+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>
+[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,46 @@
+// 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.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>
+[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,28 @@
+// 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;
+
+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>
+[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,75 @@
+// 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.Linq;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a mode where approval behavior is specified for individual tool names.
+/// </summary>
+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)
+    {
+        if (ReferenceEquals(list1, list2))
+        {
+            return true;
+        }
+
+        if (list1 is null || list2 is null)
+        {
+            return false;
+        }
+
+        return list1.SequenceEqual(list2);
+    }
+
+    private static int GetListHashCode(IList<string>? list)
+    {
+        if (list is null)
+        {
+            return 0;
+        }
+
+        var hc = default(HashCode);
+        foreach (string item in list)
+        {
+            hc.Add(item);
+        }
+
+        return hc.ToHashCode();
+    }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Microsoft.Extensions.AI.Abstractions.csproj

@@ -32,6 +32,7 @@
 
   <ItemGroup Condition="'$(TargetFrameworkIdentifier)' != '.NETCoreApp'">
     <PackageReference Include="System.Text.Json" />
+    <PackageReference Include="Microsoft.Bcl.HashCode" />
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' == 'net462'">