Decouple Handlers and Collections from protocol types (#765)

* Decouple Handlers and Collections (e.g. ToolsHandler and ToolsCollection) from Capabilities by promoting them to the options types.

Also, group all handlers in container classes, for server, I decided to move McpServerHandlers down to Mcp.Core and move the NotificationHandlers there too.

Also, Fix ListResourceTemplatesHandler issue.

* Add remarks for empty protocol capability types

* Keep JsonIgnore properties and mark them as Obsolete

* Continue supporting Obsolete members

* Update Obsolete messages to indicate the member will be removed

* Add EditorBrowsable Never to the remaining obsolete members

Author: jozkee

README.md

@@ -174,54 +174,51 @@ using System.Text.Json;
 McpServerOptions options = new()
 {
     ServerInfo = new Implementation { Name = "MyServer", Version = "1.0.0" },
-    Capabilities = new ServerCapabilities
+    Handlers = new McpServerHandlers()
     {
-        Tools = new ToolsCapability
-        {
-            ListToolsHandler = (request, cancellationToken) =>
-                ValueTask.FromResult(new ListToolsResult
-                {
-                    Tools =
-                    [
-                        new Tool
-                        {
-                            Name = "echo",
-                            Description = "Echoes the input back to the client.",
-                            InputSchema = JsonSerializer.Deserialize<JsonElement>("""
-                                {
-                                    "type": "object",
-                                    "properties": {
-                                      "message": {
-                                        "type": "string",
-                                        "description": "The input to echo back"
-                                      }
-                                    },
-                                    "required": ["message"]
-                                }
-                                """),
-                        }
-                    ]
-                }),
-
-            CallToolHandler = (request, cancellationToken) =>
+        ListToolsHandler = (request, cancellationToken) =>
+            ValueTask.FromResult(new ListToolsResult
             {
-                if (request.Params?.Name == "echo")
-                {
-                    if (request.Params.Arguments?.TryGetValue("message", out var message) is not true)
+                Tools =
+                [
+                    new Tool
                     {
-                        throw new McpException("Missing required argument 'message'");
+                        Name = "echo",
+                        Description = "Echoes the input back to the client.",
+                        InputSchema = JsonSerializer.Deserialize<JsonElement>("""
+                            {
+                                "type": "object",
+                                "properties": {
+                                  "message": {
+                                    "type": "string",
+                                    "description": "The input to echo back"
+                                  }
+                                },
+                                "required": ["message"]
+                            }
+                            """),
                     }
+                ]
+            }),
 
-                    return ValueTask.FromResult(new CallToolResult
-                    {
-                        Content = [new TextContentBlock { Text = $"Echo: {message}", Type = "text" }]
-                    });
+        CallToolHandler = (request, cancellationToken) =>
+        {
+            if (request.Params?.Name == "echo")
+            {
+                if (request.Params.Arguments?.TryGetValue("message", out var message) is not true)
+                {
+                    throw new McpException("Missing required argument 'message'");
                 }
 
-                throw new McpException($"Unknown tool: '{request.Params?.Name}'");
-            },
+                return ValueTask.FromResult(new CallToolResult
+                {
+                    Content = [new TextContentBlock { Text = $"Echo: {message}", Type = "text" }]
+                });
+            }
+
+            throw new McpException($"Unknown tool: '{request.Params?.Name}'");
         }
-    },
+    }
 };
 
 await using McpServer server = McpServer.Create(new StdioServerTransport("MyServer"), options);

docs/concepts/elicitation/samples/client/Program.cs

@@ -18,12 +18,9 @@
         Name = "ElicitationClient",
         Version = "1.0.0"
     },
-    Capabilities = new()
+    Handlers = new()
     {
-        Elicitation = new()
-        {
-            ElicitationHandler = HandleElicitationAsync
-        }
+        ElicitationHandler = HandleElicitationAsync
     }
 };
 

samples/AspNetCoreMcpPerSessionTools/Program.cs

@@ -24,7 +24,7 @@
             {
                 mcpOptions.Capabilities = new();
                 mcpOptions.Capabilities.Tools = new();
-                var toolCollection = mcpOptions.Capabilities.Tools.ToolCollection = new();
+                var toolCollection = mcpOptions.ToolCollection = new();
 
                 foreach (var tool in tools)
                 {

samples/ChatWithTools/Program.cs

@@ -41,7 +41,10 @@
     }),
     clientOptions: new()
     {
-        Capabilities = new() { Sampling = new() { SamplingHandler = samplingClient.CreateSamplingHandler() } },
+        Handlers = new()
+        {
+            SamplingHandler = samplingClient.CreateSamplingHandler()
+        }
     },
     loggerFactory: loggerFactory);
 

samples/InMemoryTransport/Program.cs

@@ -10,13 +10,7 @@
     new StreamServerTransport(clientToServerPipe.Reader.AsStream(), serverToClientPipe.Writer.AsStream()),
     new McpServerOptions()
     {
-        Capabilities = new()
-        {
-            Tools = new()
-            {
-                ToolCollection = [McpServerTool.Create((string arg) => $"Echo: {arg}", new() { Name = "Echo" })]
-            }
-        }
+        ToolCollection = [McpServerTool.Create((string arg) => $"Echo: {arg}", new() { Name = "Echo" })]
     });
 _ = server.RunAsync();
 

src/ModelContextProtocol.Core/Client/IMcpClient.cs

@@ -1,11 +1,13 @@
 using ModelContextProtocol.Protocol;
+using System.ComponentModel;
 
 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.")] // See: https://github.com/modelcontextprotocol/csharp-sdk/issues/774
+[Obsolete($"Use {nameof(McpClient)} instead. This member will be removed in a subsequent release.")] // See: https://github.com/modelcontextprotocol/csharp-sdk/issues/774
+[EditorBrowsable(EditorBrowsableState.Never)]
 public interface IMcpClient : IMcpEndpoint
 {
     /// <summary>

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

@@ -631,11 +631,11 @@ internal static CreateMessageResult ToCreateMessageResult(ChatResponse chatRespo
     }
 
     /// <summary>
-    /// Creates a sampling handler for use with <see cref="SamplingCapability.SamplingHandler"/> that will
+    /// Creates a sampling handler for use with <see cref="McpClientHandlers.SamplingHandler"/> that will
     /// satisfy sampling requests using the specified <see cref="IChatClient"/>.
     /// </summary>
     /// <param name="chatClient">The <see cref="IChatClient"/> with which to satisfy sampling requests.</param>
-    /// <returns>The created handler delegate that can be assigned to <see cref="SamplingCapability.SamplingHandler"/>.</returns>
+    /// <returns>The created handler delegate that can be assigned to <see cref="McpClientHandlers.SamplingHandler"/>.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="chatClient"/> is <see langword="null"/>.</exception>
     public static Func<CreateMessageRequestParams?, IProgress<ProgressNotificationValue>, CancellationToken, ValueTask<CreateMessageResult>> CreateSamplingHandler(
         IChatClient chatClient)