Introduce distinct MCPEXP002 diagnostic for subclassing McpClient/McpServer

Co-authored-by: jeffhandley <1031940+jeffhandley@users.noreply.github.com>

Author: Copilot

docs/list-of-diagnostics.md

@@ -23,4 +23,5 @@ If you use experimental APIs, you will get one of the diagnostics shown below. T
 
 | Diagnostic ID | Description |
 | :------------ | :---------- |
-| `MCPEXP001` | MCP experimental APIs including Tasks and Extensions. Tasks provide a mechanism for asynchronous long-running operations that can be polled for status and results (see [MCP Tasks specification](https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks)). Extensions provide a framework for extending the Model Context Protocol while maintaining interoperability (see [SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)). |
+| `MCPEXP001` | MCP experimental APIs including Tasks and Extensions. Tasks provide a mechanism for asynchronous long-running operations that can be polled for status and results (see [MCP Tasks specification](https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks)). Extensions provide a framework for extending the Model Context Protocol while maintaining interoperability (see [SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)). |
+| `MCPEXP002` | Subclassing `McpClient` and `McpServer` is experimental and subject to change (see [#1363](https://github.com/modelcontextprotocol/csharp-sdk/pull/1363)). |

src/Common/Experimentals.cs

@@ -56,4 +56,19 @@ internal static class Experimentals
     /// URL for the experimental MCP Extensions feature.
     /// </summary>
     public const string Extensions_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#mcpexp001";
+
+    /// <summary>
+    /// Diagnostic ID for experimental subclassing of McpClient and McpServer.
+    /// </summary>
+    public const string Subclassing_DiagnosticId = "MCPEXP002";
+
+    /// <summary>
+    /// Message for experimental subclassing of McpClient and McpServer.
+    /// </summary>
+    public const string Subclassing_Message = "Subclassing McpClient and McpServer is experimental and subject to change.";
+
+    /// <summary>
+    /// URL for experimental subclassing of McpClient and McpServer.
+    /// </summary>
+    public const string Subclassing_Url = "https://github.com/modelcontextprotocol/csharp-sdk/pull/1363";
 }

src/ModelContextProtocol.Core/Client/McpClient.cs

@@ -11,7 +11,7 @@ public abstract partial class McpClient : McpSession
     /// <summary>
     /// Initializes a new instance of the <see cref="McpClient"/> class.
     /// </summary>
-    [Experimental(Experimentals.Tasks_DiagnosticId, UrlFormat = Experimentals.Tasks_Url)]
+    [Experimental(Experimentals.Subclassing_DiagnosticId, UrlFormat = Experimentals.Subclassing_Url)]
     protected McpClient()
     {
     }

src/ModelContextProtocol.Core/Client/McpClientImpl.cs

@@ -6,10 +6,9 @@
 namespace ModelContextProtocol.Client;
 
 /// <inheritdoc/>
-#pragma warning disable MCPEXP001
+#pragma warning disable MCPEXP002
 internal sealed partial class McpClientImpl : McpClient
 {
-#pragma warning restore MCPEXP001
     private static Implementation DefaultImplementation { get; } = new()
     {
         Name = AssemblyNameHelper.DefaultAssemblyName.Name ?? nameof(McpClient),
@@ -39,6 +38,7 @@ internal sealed partial class McpClientImpl : McpClient
     /// <param name="options">Options for the client, defining protocol version and capabilities.</param>
     /// <param name="loggerFactory">The logger factory.</param>
     internal McpClientImpl(ITransport transport, string endpointName, McpClientOptions? options, ILoggerFactory? loggerFactory)
+#pragma warning restore MCPEXP002
     {
         options ??= new();
 

src/ModelContextProtocol.Core/Server/DestinationBoundMcpServer.cs

@@ -3,9 +3,9 @@
 
 namespace ModelContextProtocol.Server;
 
-#pragma warning disable MCPEXP001
+#pragma warning disable MCPEXP002
 internal sealed class DestinationBoundMcpServer(McpServerImpl server, ITransport? transport) : McpServer
-#pragma warning restore MCPEXP001
+#pragma warning restore MCPEXP002
 {
     public override string? SessionId => transport?.SessionId ?? server.SessionId;
     public override string? NegotiatedProtocolVersion => server.NegotiatedProtocolVersion;

src/ModelContextProtocol.Core/Server/McpServer.cs

@@ -11,7 +11,7 @@ public abstract partial class McpServer : McpSession
     /// <summary>
     /// Initializes a new instance of the <see cref="McpServer"/> class.
     /// </summary>
-    [Experimental(Experimentals.Tasks_DiagnosticId, UrlFormat = Experimentals.Tasks_Url)]
+    [Experimental(Experimentals.Subclassing_DiagnosticId, UrlFormat = Experimentals.Subclassing_Url)]
     protected McpServer()
     {
     }

src/ModelContextProtocol.Core/Server/McpServerImpl.cs

@@ -9,10 +9,9 @@
 namespace ModelContextProtocol.Server;
 
 /// <inheritdoc />
-#pragma warning disable MCPEXP001
+#pragma warning disable MCPEXP002
 internal sealed partial class McpServerImpl : McpServer
 {
-#pragma warning restore MCPEXP001
     internal static Implementation DefaultImplementation { get; } = new()
     {
         Name = AssemblyNameHelper.DefaultAssemblyName.Name ?? nameof(McpServer),
@@ -56,6 +55,7 @@ internal sealed partial class McpServerImpl : McpServer
     /// <param name="serviceProvider">Optional service provider to use for dependency injection</param>
     /// <exception cref="McpException">The server was incorrectly configured.</exception>
     public McpServerImpl(ITransport transport, McpServerOptions options, ILoggerFactory? loggerFactory, IServiceProvider? serviceProvider)
+#pragma warning restore MCPEXP002
     {
         Throw.IfNull(transport);
         Throw.IfNull(options);

tests/ModelContextProtocol.Tests/Server/McpServerTests.cs

@@ -943,9 +943,9 @@ private static async Task InitializeServerAsync(TestServerTransport transport, C
         await tcs.Task.WaitAsync(TestConstants.DefaultTimeout, cancellationToken);
     }
 
-#pragma warning disable MCPEXP001
+#pragma warning disable MCPEXP002
     private sealed class TestServerForIChatClient(bool supportsSampling) : McpServer
-#pragma warning restore MCPEXP001
+#pragma warning restore MCPEXP002
     {
         public override ClientCapabilities? ClientCapabilities =>
             supportsSampling ? new ClientCapabilities { Sampling = new SamplingCapability() } :