Add back old API, but obsoleted

Author: MackinnonBuck

src/ModelContextProtocol.Core/Client/IMcpClient.cs

@@ -0,0 +1,48 @@
+using ModelContextProtocol.Protocol;
+
+namespace ModelContextProtocol.Client;
+
+/// <summary>
+/// Represents an instance of a Model Context Protocol (MCP) client that connects to and communicates with an MCP server.
+/// </summary>
+[Obsolete($"Use {nameof(McpClient)} instead.")]
+public interface IMcpClient : IMcpEndpoint
+{
+    /// <summary>
+    /// Gets the capabilities supported by the connected server.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">The client is not connected.</exception>
+    ServerCapabilities ServerCapabilities { get; }
+
+    /// <summary>
+    /// Gets the implementation information of the connected server.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This property provides identification details about the connected server, including its name and version.
+    /// It is populated during the initialization handshake and is available after a successful connection.
+    /// </para>
+    /// <para>
+    /// This information can be useful for logging, debugging, compatibility checks, and displaying server
+    /// information to users.
+    /// </para>
+    /// </remarks>
+    /// <exception cref="InvalidOperationException">The client is not connected.</exception>
+    Implementation ServerInfo { get; }
+
+    /// <summary>
+    /// Gets any instructions describing how to use the connected server and its features.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This property contains instructions provided by the server during initialization that explain
+    /// how to effectively use its capabilities. These instructions can include details about available
+    /// tools, expected input formats, limitations, or any other helpful information.
+    /// </para>
+    /// <para>
+    /// This can be used by clients to improve an LLM's understanding of available tools, prompts, and resources. 
+    /// It can be thought of like a "hint" to the model and may be added to a system prompt.
+    /// </para>
+    /// </remarks>
+    string? ServerInstructions { get; }
+}

src/ModelContextProtocol.Core/Client/McpClient.cs

@@ -10,7 +10,9 @@ 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>
-public abstract class McpClient : McpSession
+#pragma warning disable CS0618 // Type or member is obsolete
+public abstract class McpClient : McpSession, IMcpClient
+#pragma warning restore CS0618 // Type or member is obsolete
 {
     /// <summary>
     /// Gets the capabilities supported by the connected server.

src/ModelContextProtocol.Core/Client/McpClientExtensions.cs

@@ -0,0 +1,83 @@
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+
+namespace ModelContextProtocol;
+
+/// <summary>
+/// Represents a client or server Model Context Protocol (MCP) endpoint.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The MCP endpoint provides the core communication functionality used by both clients and servers:
+/// <list type="bullet">
+///   <item>Sending JSON-RPC requests and receiving responses.</item>
+///   <item>Sending notifications to the connected endpoint.</item>
+///   <item>Registering handlers for receiving notifications.</item>
+/// </list>
+/// </para>
+/// <para>
+/// <see cref="IMcpEndpoint"/> serves as the base interface for both <see cref="IMcpClient"/> and 
+/// <see cref="IMcpServer"/> interfaces, providing the common functionality needed for MCP protocol 
+/// communication. Most applications will use these more specific interfaces rather than working with 
+/// <see cref="IMcpEndpoint"/> directly.
+/// </para>
+/// <para>
+/// All MCP endpoints should be properly disposed after use as they implement <see cref="IAsyncDisposable"/>.
+/// </para>
+/// </remarks>
+[Obsolete($"Use {nameof(McpSession)} instead.")]
+public interface IMcpEndpoint : IAsyncDisposable
+{
+    /// <summary>Gets an identifier associated with the current MCP session.</summary>
+    /// <remarks>
+    /// Typically populated in transports supporting multiple sessions such as Streamable HTTP or SSE.
+    /// Can return <see langword="null"/> if the session hasn't initialized or if the transport doesn't
+    /// support multiple sessions (as is the case with STDIO).
+    /// </remarks>
+    string? SessionId { get; }
+
+    /// <summary>
+    /// Sends a JSON-RPC request to the connected endpoint and waits for a response.
+    /// </summary>
+    /// <param name="request">The JSON-RPC request to send.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task containing the endpoint's response.</returns>
+    /// <exception cref="InvalidOperationException">The transport is not connected, or another error occurs during request processing.</exception>
+    /// <exception cref="McpException">An error occured during request processing.</exception>
+    /// <remarks>
+    /// This method provides low-level access to send raw JSON-RPC requests. For most use cases,
+    /// consider using the strongly-typed extension methods that provide a more convenient API.
+    /// </remarks>
+    Task<JsonRpcResponse> SendRequestAsync(JsonRpcRequest request, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Sends a JSON-RPC message to the connected endpoint.
+    /// </summary>
+    /// <param name="message">
+    /// The JSON-RPC message to send. This can be any type that implements JsonRpcMessage, such as
+    /// JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, or JsonRpcError.
+    /// </param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous send operation.</returns>
+    /// <exception cref="InvalidOperationException">The transport is not connected.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="message"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// <para>
+    /// This method provides low-level access to send any JSON-RPC message. For specific message types,
+    /// consider using the higher-level methods such as <see cref="SendRequestAsync"/> or extension methods
+    /// like <see cref="McpEndpointExtensions.SendNotificationAsync(IMcpEndpoint, string, CancellationToken)"/>,
+    /// which provide a simpler API.
+    /// </para>
+    /// <para>
+    /// The method will serialize the message and transmit it using the underlying transport mechanism.
+    /// </para>
+    /// </remarks>
+    Task SendMessageAsync(JsonRpcMessage message, CancellationToken cancellationToken = default);
+
+    /// <summary>Registers a handler to be invoked when a notification for the specified method is received.</summary>
+    /// <param name="method">The notification method.</param>
+    /// <param name="handler">The handler to be invoked.</param>
+    /// <returns>An <see cref="IDisposable"/> that will remove the registered handler when disposed.</returns>
+    IAsyncDisposable RegisterNotificationHandler(string method, Func<JsonRpcNotification, CancellationToken, ValueTask> handler);
+}

src/ModelContextProtocol.Core/IMcpEndpoint.cs

@@ -0,0 +1,148 @@
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using System.Text.Json.Serialization.Metadata;
+
+namespace ModelContextProtocol;
+
+/// <summary>
+/// Provides extension methods for interacting with an <see cref="IMcpEndpoint"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This class provides strongly-typed methods for working with the Model Context Protocol (MCP) endpoints,
+/// simplifying JSON-RPC communication by handling serialization and deserialization of parameters and results.
+/// </para>
+/// <para>
+/// These extension methods are designed to be used with both client (<see cref="IMcpClient"/>) and
+/// server (<see cref="IMcpServer"/>) implementations of the <see cref="IMcpEndpoint"/> interface.
+/// </para>
+/// </remarks>
+public static class McpEndpointExtensions
+{
+    /// <summary>
+    /// Sends a JSON-RPC request and attempts to deserialize the result to <typeparamref name="TResult"/>.
+    /// </summary>
+    /// <typeparam name="TParameters">The type of the request parameters to serialize from.</typeparam>
+    /// <typeparam name="TResult">The type of the result to deserialize to.</typeparam>
+    /// <param name="endpoint">The MCP client or server instance.</param>
+    /// <param name="method">The JSON-RPC method name to invoke.</param>
+    /// <param name="parameters">Object representing the request parameters.</param>
+    /// <param name="requestId">The request id for the request.</param>
+    /// <param name="serializerOptions">The options governing request serialization.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the deserialized result.</returns>
+    [Obsolete($"Use {nameof(McpSession)}.{nameof(McpSession.SendRequestAsync)} instead.")]
+    public static ValueTask<TResult> SendRequestAsync<TParameters, TResult>(
+        this IMcpEndpoint endpoint,
+        string method,
+        TParameters parameters,
+        JsonSerializerOptions? serializerOptions = null,
+        RequestId requestId = default,
+        CancellationToken cancellationToken = default)
+        where TResult : notnull
+        => AsSessionOrThrow(endpoint).SendRequestAsync<TParameters, TResult>(method, parameters, serializerOptions, requestId, cancellationToken);
+
+    /// <summary>
+    /// Sends a parameterless notification to the connected endpoint.
+    /// </summary>
+    /// <param name="client">The MCP client or server instance.</param>
+    /// <param name="method">The notification method name.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous send operation.</returns>
+    /// <remarks>
+    /// <para>
+    /// This method sends a notification without any parameters. Notifications are one-way messages 
+    /// that don't expect a response. They are commonly used for events, status updates, or to signal 
+    /// changes in state.
+    /// </para>
+    /// </remarks>
+    [Obsolete($"Use {nameof(McpSession)}.{nameof(McpSession.SendNotificationAsync)} instead.")]
+    public static Task SendNotificationAsync(this IMcpEndpoint client, string method, CancellationToken cancellationToken = default)
+        => AsSessionOrThrow(client).SendNotificationAsync(method, cancellationToken);
+
+    /// <summary>
+    /// Sends a notification with parameters to the connected endpoint.
+    /// </summary>
+    /// <typeparam name="TParameters">The type of the notification parameters to serialize.</typeparam>
+    /// <param name="endpoint">The MCP client or server instance.</param>
+    /// <param name="method">The JSON-RPC method name for the notification.</param>
+    /// <param name="parameters">Object representing the notification parameters.</param>
+    /// <param name="serializerOptions">The options governing parameter serialization. If null, default options are used.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous send operation.</returns>
+    /// <remarks>
+    /// <para>
+    /// This method sends a notification with parameters to the connected endpoint. Notifications are one-way 
+    /// messages that don't expect a response, commonly used for events, status updates, or signaling changes.
+    /// </para>
+    /// <para>
+    /// The parameters object is serialized to JSON according to the provided serializer options or the default 
+    /// options if none are specified.
+    /// </para>
+    /// <para>
+    /// The Model Context Protocol defines several standard notification methods in <see cref="NotificationMethods"/>,
+    /// but custom methods can also be used for application-specific notifications.
+    /// </para>
+    /// </remarks>
+    [Obsolete($"Use {nameof(McpSession)}.{nameof(McpSession.SendNotificationAsync)} instead.")]
+    public static Task SendNotificationAsync<TParameters>(
+        this IMcpEndpoint endpoint,
+        string method,
+        TParameters parameters,
+        JsonSerializerOptions? serializerOptions = null,
+        CancellationToken cancellationToken = default)
+        => AsSessionOrThrow(endpoint).SendNotificationAsync(method, parameters, serializerOptions, cancellationToken);
+
+    /// <summary>
+    /// Notifies the connected endpoint of progress for a long-running operation.
+    /// </summary>
+    /// <param name="endpoint">The endpoint issuing the notification.</param>
+    /// <param name="progressToken">The <see cref="ProgressToken"/> identifying the operation for which progress is being reported.</param>
+    /// <param name="progress">The progress update to send, containing information such as percentage complete or status message.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task representing the completion of the notification operation (not the operation being tracked).</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="endpoint"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// <para>
+    /// This method sends a progress notification to the connected endpoint using the Model Context Protocol's
+    /// standardized progress notification format. Progress updates are identified by a <see cref="ProgressToken"/>
+    /// that allows the recipient to correlate multiple updates with a specific long-running operation.
+    /// </para>
+    /// <para>
+    /// Progress notifications are sent asynchronously and don't block the operation from continuing.
+    /// </para>
+    /// </remarks>
+    [Obsolete($"Use {nameof(McpSession)}.{nameof(McpSession.NotifyProgressAsync)} instead.")]
+    public static Task NotifyProgressAsync(
+        this IMcpEndpoint endpoint,
+        ProgressToken progressToken,
+        ProgressNotificationValue progress,
+        CancellationToken cancellationToken = default)
+        => AsSessionOrThrow(endpoint).NotifyProgressAsync(progressToken, progress, cancellationToken);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+#pragma warning disable CS0618 // Type or member is obsolete
+    private static McpSession AsSessionOrThrow(IMcpEndpoint endpoint, [CallerMemberName] string memberName = "")
+#pragma warning restore CS0618 // Type or member is obsolete
+    {
+        if (endpoint is not McpSession session)
+        {
+            ThrowInvalidEndpointType(memberName);
+        }
+
+        return session;
+
+        [DoesNotReturn]
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        static void ThrowInvalidEndpointType(string memberName)
+            => throw new InvalidOperationException(
+                $"Only arguments assignable to '{nameof(McpSession)}' are supported. " +
+                $"Prefer using '{nameof(McpServer)}.{memberName}' instead, as " +
+                $"'{nameof(McpEndpointExtensions)}.{memberName}' is obsolete and will be " +
+                $"removed in the future.");
+    }
+}

src/ModelContextProtocol.Core/McpEndpointExtensions.cs

@@ -29,7 +29,9 @@ namespace ModelContextProtocol;
 /// All MCP sessions should be properly disposed after use as they implement <see cref="IAsyncDisposable"/>.
 /// </para>
 /// </remarks>
-public abstract class McpSession : IAsyncDisposable
+#pragma warning disable CS0618 // Type or member is obsolete
+public abstract class McpSession : IMcpEndpoint, IAsyncDisposable
+#pragma warning restore CS0618 // Type or member is obsolete
 {
     /// <summary>Gets an identifier associated with the current MCP session.</summary>
     /// <remarks>

src/ModelContextProtocol.Core/McpSession.cs

@@ -0,0 +1,63 @@
+using ModelContextProtocol.Protocol;
+
+namespace ModelContextProtocol.Server;
+
+/// <summary>
+/// Represents an instance of a Model Context Protocol (MCP) server that connects to and communicates with an MCP client.
+/// </summary>
+[Obsolete($"Use {nameof(McpServer)} instead.")]
+public interface IMcpServer : IMcpEndpoint
+{
+    /// <summary>
+    /// Gets the capabilities supported by the client.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// These capabilities are established during the initialization handshake and indicate
+    /// which features the client supports, such as sampling, roots, and other
+    /// protocol-specific functionality.
+    /// </para>
+    /// <para>
+    /// Server implementations can check these capabilities to determine which features
+    /// are available when interacting with the client.
+    /// </para>
+    /// </remarks>
+    ClientCapabilities? ClientCapabilities { get; }
+
+    /// <summary>
+    /// Gets the version and implementation information of the connected client.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This property contains identification information about the client that has connected to this server,
+    /// including its name and version. This information is provided by the client during initialization.
+    /// </para>
+    /// <para>
+    /// Server implementations can use this information for logging, tracking client versions, 
+    /// or implementing client-specific behaviors.
+    /// </para>
+    /// </remarks>
+    Implementation? ClientInfo { get; }
+
+    /// <summary>
+    /// Gets the options used to construct this server.
+    /// </summary>
+    /// <remarks>
+    /// These options define the server's capabilities, protocol version, and other configuration
+    /// settings that were used to initialize the server.
+    /// </remarks>
+    McpServerOptions ServerOptions { get; }
+
+    /// <summary>
+    /// Gets the service provider for the server.
+    /// </summary>
+    IServiceProvider? Services { get; }
+
+    /// <summary>Gets the last logging level set by the client, or <see langword="null"/> if it's never been set.</summary>
+    LoggingLevel? LoggingLevel { get; }
+
+    /// <summary>
+    /// Runs the server, listening for and handling client requests.
+    /// </summary>
+    Task RunAsync(CancellationToken cancellationToken = default);
+}

src/ModelContextProtocol.Core/Server/IMcpServer.cs

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