Remove obsolete APIs from codebase and standardize MCP diagnostic IDs (#985)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: MackinnonBuck <10456961+MackinnonBuck@users.noreply.github.com>
Co-authored-by: eiriktsarpalis <2813363+eiriktsarpalis@users.noreply.github.com>
Co-authored-by: Mackinnon Buck <mackinnon.buck@gmail.com>
Co-authored-by: jeffhandley <1031940+jeffhandley@users.noreply.github.com>
Co-authored-by: Jeff Handley <jeffhandley@users.noreply.github.com>

Author: 4 people

src/Common/Experimentals.cs

@@ -0,0 +1,27 @@
+using System.Diagnostics.CodeAnalysis;
+
+namespace ModelContextProtocol;
+
+/// <summary>
+/// Defines diagnostic IDs, Messages, and Urls for APIs annotated with <see cref="ExperimentalAttribute"/>.
+/// </summary>
+/// <remarks>
+/// When an experimental API is associated with an experimental specification, the message
+/// should refer to the specification version that introduces the feature and the SEP
+/// when available. If there is a SEP associated with the experimental API, the Url should
+/// point to the SEP issue.
+/// <para>
+/// Experimental diagnostic IDs are in the format MCP5###.
+/// </para>
+/// <para>
+/// Diagnostic IDs cannot be reused when experimental API are removed or promoted to stable.
+/// This ensures that users do not suppress warnings for new diagnostics with existing
+/// suppressions that might be left in place from prior uses of the same diagnostic ID.
+/// </para>
+/// </remarks>
+internal static class Experimentals
+{
+    // public const string Tasks_DiagnosticId = "MCP5001";
+    // public const string Tasks_Message = "The Tasks feature is experimental within specification version 2025-11-25 and is subject to change. See SEP-1686 for more information.";
+    // public const string Tasks_Url = "https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1686";
+}

src/Common/Obsoletions.cs

@@ -0,0 +1,25 @@
+namespace ModelContextProtocol;
+
+/// <summary>
+/// Defines diagnostic IDs, Messages, and Urls for APIs annotated with <see cref="ObsoleteAttribute"/>.
+/// </summary>
+/// <remarks>
+/// When a deprecated API is associated with an specification change, the message
+/// should refer to the specification version that introduces the change and the SEP
+/// when available. If there is a SEP associated with the experimental API, the Url should
+/// point to the SEP issue.
+/// <para>
+/// Obsolete diagnostic IDs are in the format MCP9###.
+/// </para>
+/// <para>
+/// Diagnostic IDs cannot be reused when obsolete APIs are removed or restored.
+/// This ensures that users do not suppress warnings for new diagnostics with existing
+/// suppressions that might be left in place from prior uses of the same diagnostic ID.
+/// </para>
+/// </remarks>
+internal static class Obsoletions
+{
+    public const string LegacyTitledEnumSchema_DiagnosticId = "MCP9001";
+    public const string LegacyTitledEnumSchema_Message = "The EnumSchema and LegacyTitledEnumSchema APIs are deprecated as of specification version 2025-11-25 and will be removed in a future major version. See SEP-1330 for more information.";
+    public const string LegacyTitledEnumSchema_Url = "https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1330";
+}

src/Common/Polyfills/System/Diagnostics/CodeAnalysis/ExperimentalAttribute.cs

@@ -0,0 +1,65 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#if !NET
+namespace System.Diagnostics.CodeAnalysis;
+
+/// <summary>
+///  Indicates that an API is experimental and it may change in the future.
+/// </summary>
+/// <remarks>
+///   This attribute allows call sites to be flagged with a diagnostic that indicates that an experimental
+///   feature is used. Authors can use this attribute to ship preview features in their assemblies.
+/// </remarks>
+[AttributeUsage(AttributeTargets.Assembly |
+                AttributeTargets.Module |
+                AttributeTargets.Class |
+                AttributeTargets.Struct |
+                AttributeTargets.Enum |
+                AttributeTargets.Constructor |
+                AttributeTargets.Method |
+                AttributeTargets.Property |
+                AttributeTargets.Field |
+                AttributeTargets.Event |
+                AttributeTargets.Interface |
+                AttributeTargets.Delegate, Inherited = false)]
+internal sealed class ExperimentalAttribute : Attribute
+{
+    /// <summary>
+    ///  Initializes a new instance of the <see cref="ExperimentalAttribute"/> class, specifying the ID that the compiler will use
+    ///  when reporting a use of the API the attribute applies to.
+    /// </summary>
+    /// <param name="diagnosticId">The ID that the compiler will use when reporting a use of the API the attribute applies to.</param>
+    public ExperimentalAttribute(string diagnosticId)
+    {
+        DiagnosticId = diagnosticId;
+    }
+
+    /// <summary>
+    ///  Gets the ID that the compiler will use when reporting a use of the API the attribute applies to.
+    /// </summary>
+    /// <value>The unique diagnostic ID.</value>
+    /// <remarks>
+    ///  The diagnostic ID is shown in build output for warnings and errors.
+    ///  <para>This property represents the unique ID that can be used to suppress the warnings or errors, if needed.</para>
+    /// </remarks>
+    public string DiagnosticId { get; }
+
+    /// <summary>
+    ///  Gets or sets an optional message associated with the experimental attribute.
+    /// </summary>
+    /// <value>The message that provides additional information about the experimental feature.</value>
+    /// <remarks>
+    ///  This message can be used to provide more context or guidance about the experimental feature.
+    /// </remarks>
+    public string? Message { get; set; }
+
+    /// <summary>
+    ///  Gets or sets the URL for corresponding documentation.
+    ///  The API accepts a format string instead of an actual URL, creating a generic URL that includes the diagnostic ID.
+    /// </summary>
+    /// <value>The format string that represents a URL to corresponding documentation.</value>
+    /// <remarks>An example format string is <c>https://contoso.com/obsoletion-warnings/{0}</c>.</remarks>
+    public string? UrlFormat { get; set; }
+}
+#endif

src/Common/Polyfills/System/ObsoleteAttribute.cs

@@ -0,0 +1,38 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#if !NET
+namespace System;
+
+/// <summary>
+/// Marks program elements that are no longer in use.
+/// </summary>
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Enum |
+    AttributeTargets.Interface | AttributeTargets.Constructor | AttributeTargets.Method | AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Event | AttributeTargets.Delegate,
+    Inherited = false)]
+internal sealed class ObsoleteAttribute : Attribute
+{
+    public ObsoleteAttribute()
+    {
+    }
+
+    public ObsoleteAttribute(string? message)
+    {
+        Message = message;
+    }
+
+    public ObsoleteAttribute(string? message, bool error)
+    {
+        Message = message;
+        IsError = error;
+    }
+
+    public string? Message { get; }
+
+    public bool IsError { get; }
+
+    public string? DiagnosticId { get; set; }
+
+    public string? UrlFormat { get; set; }
+}
+#endif

src/ModelContextProtocol.Analyzers/Diagnostics.cs

@@ -9,6 +9,14 @@
 namespace ModelContextProtocol.Analyzers;
 
 /// <summary>Provides the diagnostic descriptors used by the assembly.</summary>
+/// <remarks>
+/// Analyzer diagnostic IDs are in the format MCP### (or MCP1### if ever needed).
+/// <para>
+/// Diagnostic IDs cannot be reused if an analyzer is removed.
+/// This ensures that users do not suppress warnings for new diagnostics with existing
+/// suppressions that might be left in place from prior uses of the same diagnostic ID.
+/// </para>
+/// </remarks>
 internal static class Diagnostics
 {
     public static DiagnosticDescriptor InvalidXmlDocumentation { get; } = new(

src/ModelContextProtocol.Core/Client/IMcpClient.cs

@@ -10,9 +10,7 @@ namespace ModelContextProtocol.Client;
 /// <summary>
 /// Represents an instance of a Model Context Protocol (MCP) client session that connects to and communicates with an MCP server.
 /// </summary>
-#pragma warning disable CS0618 // Type or member is obsolete
-public abstract partial class McpClient : McpSession, IMcpClient
-#pragma warning restore CS0618 // Type or member is obsolete
+public abstract partial class McpClient : McpSession
 {
     /// <summary>Creates an <see cref="McpClient"/>, connecting it to the specified server.</summary>
     /// <param name="clientTransport">The transport instance used to communicate with the server.</param>

src/ModelContextProtocol.Core/Client/McpClient.Methods.cs

@@ -5,9 +5,7 @@ namespace ModelContextProtocol.Client;
 /// <summary>
 /// Represents an instance of a Model Context Protocol (MCP) client session that connects to and communicates with an MCP server.
 /// </summary>
-#pragma warning disable CS0618 // Type or member is obsolete
-public abstract partial class McpClient : McpSession, IMcpClient
-#pragma warning restore CS0618 // Type or member is obsolete
+public abstract partial class McpClient : McpSession
 {
     /// <summary>
     /// Gets the capabilities supported by the connected server.