抛开官方库，手撸一个轻量级 MCP 服务端

大家好！在昨天的文章 《官方文档没告诉你的：通过抓包，深入揭秘MCP协议底层通信》 中，我们通过Fiddler工具，像侦探一样，一步步揭开了MCP（Model Context Protocol）在无状态HTTP模式下的神秘面纱。我们搞清楚了它的两步握手、SSE（Server-Sent Events）响应机制以及精巧的两种错误处理方式。

然而，仅仅停留在理论分析层面总感觉意犹未尽。更重要的是，当我们审视官方提供的 ModelContextProtocol.AspNetCore 这个NuGet包时（当前版本0.3.0-preview.3），会发现它目前引入了相当多的依赖项：

• Microsoft.Bcl.Memory (>= 9.0.5)
  
• Microsoft.Extensions.AI.Abstractions (>= 9.7.1)
  
• Microsoft.Extensions.Logging.Abstractions (>= 8.0.3)
  
• System.Diagnostics.DiagnosticSource (>= 8.0.1)
  
• System.IO.Pipelines (>= 8.0.0)
  
• System.Net.ServerSentEvents (>= 10.0.0-preview.4.25258.110)
  
• System.Text.Json (>= 8.0.6)
  
• System.Threading.Channels (>= 8.0.0)
  
• Microsoft.Extensions.Hosting.Abstractions (>= 8.0.1)
  
• ModelContextProtocol.Core (>= 0.3.0-preview.3)
  

其中，最令人不安的莫过于 System.Net.ServerSentEvents，它竟然是一个 .NET 10 的预览版包！在生产环境中使用预览版包，通常是大忌。
既然我们已经通过抓包掌握了协议的全部细节，那么，何不自己动手，实现一个轻量级、零预览版依赖的MCP服务端呢？这不仅是一次绝佳的学习实践，也能让我们对协议的理解更上一层楼。
今天，我们就来完成这个挑战：不依赖官方服务端库，直接用纯粹的ASP.NET Core代码，实现一个功能完备的MCP服务端。
我们的目标：保持工具定义的简洁性

在动手之前，我们先定一个目标。我们希望定义工具（Tools）的方式能够尽可能地简洁和直观，几乎和昨天的代码保持一致：

1. using System.ComponentModel;
3. public class Tools(IHttpContextAccessor http)
4. {
5.     [Description("Echoes the message back to the client.")]
6.     public string Echo(string message) => $"hello {message}";
8.     [Description("Returns the IP address of the client.")]
9.     public string EchoIP() => http.HttpContext?.Connection.RemoteIpAddress?.ToString() ?? "Unknown";
11.     [Description("Counts from 0 to n, reporting progress at each step.")]
12.     public async Task<int> Count(int n, IProgress<ProgressNotificationValue> progress)
13.     {
14.         for (int i = 0; i < n; ++i)
15.         {
16.             progress.Report(new ProgressNotificationValue()
17.             {
18.                 Progress = i,
19.                 Total = n,
20.                 Message = $"Step {i} of {n}",
21.             });
22.             await Task.Delay(100);
23.         }
24.         return n;
25.     }
27.     [Description("Throws an exception for testing purposes.")]
28.     public string TestThrow()
29.     {
30.         throw new Exception("This is a test exception");
31.     }
32. }

复制代码

注意到变化了吗？我们去掉了官方库定义的 [McpServerToolType] 和 [McpServerTool] 特性。取而代之的是一种更符合ASP.NET Core直觉的方式：任何 public 方法都自动成为一个工具，并使用标准的 System.ComponentModel.DescriptionAttribute 来提供工具描述。
理想中的使用方式

我们期望最终的使用方式能像下面这样优雅：

1. WebApplicationBuilder builder = WebApplication.CreateBuilder();
3. // 1. 注册原生服务和我们的工具类
4. builder.Services.AddHttpContextAccessor();
5. builder.Services.AddTransient<Tools>();
7. WebApplication app = builder.Build();
9. // 2. 映射 MCP 端点，自动发现并使用 Tools 类
10. app.MapMcpEndpoint<Tools>("/");
12. // 3. 启动应用
13. app.Run();

复制代码

是的，你没看错。核心就在于 builder.Services.AddTransient(); 和 app.MapMcpEndpoint("/"); 这两行。前者负责将我们的工具类注册到依赖注入容器，后者则是我们即将创建的魔法扩展方法，它会自动处理所有MCP协议的细节。
第一步：定义协议的“语言” - DTOs

要实现协议，首先要定义好通信双方所使用的“语言”，也就是数据传输对象（DTOs）。根据昨天的抓包分析，我们用C#的 record 类型来精确描述这些JSON结构。

1. using System.Text.Json.Serialization;
3. // --- JSON-RPC Base Structures ---
4. public record JsonRpcRequest(
5.     [property: JsonPropertyName("jsonrpc")] string JsonRpc,
6.     [property: JsonPropertyName("method")] string Method,
7.     [property: JsonPropertyName("params")] object? Params,
8.     [property: JsonPropertyName("id")] int? Id
9. );
11. public record JsonRpcResponse(
12.     [property: JsonPropertyName("jsonrpc")] string JsonRpc,
13.     [property: JsonPropertyName("result")] object? Result,
14.     [property: JsonPropertyName("error")] object? Error,
15.     [property: JsonPropertyName("id")] int? Id
16. );
18. public record JsonRpcError(
19.     [property: JsonPropertyName("code")] int Code,
20.     [property: JsonPropertyName("message")] string Message
21. );
23. // --- MCP Specific Payloads ---
25. // For initialize method
26. public record InitializeParams(
27.     [property: JsonPropertyName("protocolVersion")] string ProtocolVersion,
28.     [property: JsonPropertyName("clientInfo")] ClientInfo ClientInfo
29. );
30. public record ClientInfo([property: JsonPropertyName("name")] string Name, [property: JsonPropertyName("version")] string Version);
32. public record InitializeResult(
33.     [property: JsonPropertyName("protocolVersion")] string ProtocolVersion,
34.     [property: JsonPropertyName("capabilities")] ServerCapabilities Capabilities,
35.     [property: JsonPropertyName("serverInfo")] ClientInfo ServerInfo
36. );
37. public record ServerCapabilities([property: JsonPropertyName("tools")] object Tools);
40. // For tools/call method
41. public record ToolCallParams(
42.     [property: JsonPropertyName("name")] string Name,
43.     [property: JsonPropertyName("arguments")] Dictionary<string, object?> Arguments,
44.     [property: JsonPropertyName("_meta")] ToolCallMeta? Meta
45. );
46. public record ToolCallMeta([property: JsonPropertyName("progressToken")] string ProgressToken);
48. // For tool call results
49. public record ToolCallResult(
50.     [property: JsonPropertyName("content")] List<ContentItem> Content,
51.     [property: JsonPropertyName("isError")] bool IsError = false
52. );
53. public record ContentItem([property: JsonPropertyName("type")] string Type, [property: JsonPropertyName("text")] string Text);
55. // For tools/list results
56. public record ToolListResult(
57.     [property: JsonPropertyName("tools")] List<ToolDefinition> Tools
58. );
60. public record ToolDefinition(
61.     [property: JsonPropertyName("name")] string Name,
62.     [property: JsonPropertyName("description")] string Description,
63.     [property: JsonPropertyName("inputSchema")] object InputSchema
64. );
66. // For progress notifications
67. public record ProgressNotification(
68.     [property: JsonPropertyName("jsonrpc")] string JsonRpc,
69.     [property: JsonPropertyName("method")] string Method,
70.     [property: JsonPropertyName("params")] ProgressParams Params
71. );
72. public record ProgressParams(
73.     [property: JsonPropertyName("progressToken")] string ProgressToken,
74.     [property: JsonPropertyName("progress")] int Progress,
75.     [property: JsonPropertyName("total")] int Total,
76.     [property: JsonPropertyName("message")] string Message
77. );
79. // This class is for the IProgress<T> interface in our Tools methods
80. public class ProgressNotificationValue
81. {
82.     public int Progress { get; set; }
83.     public int Total { get; set; }
84.     public string Message { get; set; } = string.Empty;
85. }

复制代码

第二步：打造核心引擎 - McpEndpointExtensions

接下来，就是实现我们魔法的源泉：一个IEndpointRouteBuilder的扩展方法。我们将所有逻辑都封装在一个静态类 McpEndpointExtensions 中。
这个类将负责：

• 路由映射：监听指定路径的 POST 和 GET 请求。
  
• 请求分发：根据JSON-RPC请求中的method字段，调用不同的处理函数。
  
• 工具发现与调用：使用反射来查找和执行TTools类中的工具方法。
  
• 响应构建：手动构建符合SSE规范的响应流。
  
• 错误处理：精确复现抓包分析中发现的两种错误模型。
  

1. using Microsoft.AspNetCore.Mvc;
2. using Microsoft.AspNetCore.WebUtilities;
3. using Microsoft.Extensions.Primitives;
4. using System.ComponentModel;
5. using System.Reflection;
6. using System.Text;
7. using System.Text.Json;
8. using System.Text.Json.Serialization;
10. public static class McpEndpointExtensions
11. {
12.     // JSON-RPC Error Codes from your article's findings
13.     private const int InvalidParamsErrorCode = -32602; // Invalid params
14.     private const int MethodNotFoundErrorCode = -32601; // Method not found
16.     private static readonly JsonSerializerOptions s_jsonOptions = new()
17.     {
18.         DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
19.         PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
20.     };
22.     /// <summary>
23.     /// Maps an endpoint that speaks the Model Context Protocol.
24.     /// </summary>
25.     public static IEndpointRouteBuilder MapMcpEndpoint<TTools>(this IEndpointRouteBuilder app, string pattern) where TTools : class
26.     {
27.         // 预先通过反射发现所有工具方法，并转换为snake_case以匹配MCP命名习惯
28.         Dictionary<string, MethodInfo> methods = typeof(TTools).GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly)
29.             .ToDictionary(k => ToSnakeCase(k.Name), v => v);
31.         app.MapPost(pattern, async (HttpContext context, [FromServices] IServiceProvider sp) =>
32.         {
33.             JsonRpcRequest? request = await JsonSerializer.DeserializeAsync<JsonRpcRequest>(context.Request.Body, s_jsonOptions);
34.             if (request == null)
35.             {
36.                 context.Response.StatusCode = 400; // Bad Request
37.                 return;
38.             }
40.             // 核心：处理不同的MCP方法
41.             switch (request.Method)
42.             {
43.                 case "initialize":
44.                     await HandleInitialize(context, request);
45.                     break;
46.                 case "notifications/initialized":
47.                     // 在无状态模式下，这个请求只是一个确认，我们返回与initialize类似的信息
48.                     await HandleInitialize(context, request);
49.                     break;
50.                 case "tools/list":
51.                     await HandleToolList<TTools>(context, request);
52.                     break;
53.                 case "tools/call":
54.                     await HandleToolCall<TTools>(context, request, sp, methods);
55.                     break;
56.                 default:
57.                     JsonRpcResponse errorResponse = new("2.0", null, new JsonRpcError(MethodNotFoundErrorCode, "Method not found"), request.Id);
58.                     await WriteSseMessageAsync(context.Response, errorResponse);
59.                     break;
60.             }
61.         });
63.         // 旧版SDK会发送GET请求，我们明确返回405
64.         app.MapGet(pattern, context =>
65.         {
66.             context.Response.StatusCode = StatusCodes.Status405MethodNotAllowed;
67.             context.Response.Headers.Allow = "POST";
68.             return Task.CompletedTask;
69.         });
71.         return app;
72.     }
74.     private static string ToSnakeCase(string name)
75.     {
76.         if (string.IsNullOrEmpty(name)) return name;
77.         var sb = new StringBuilder(name.Length);
78.         for (int i = 0; i < name.Length; i++)
79.         {
80.             char c = name[i];
81.             if (char.IsUpper(c))
82.             {
83.                 if (sb.Length > 0 && i > 0 && !char.IsUpper(name[i-1])) sb.Append('_');
84.                 sb.Append(char.ToLowerInvariant(c));
85.             }
86.             else
87.             {
88.                 sb.Append(c);
89.             }
90.         }
91.         return sb.ToString();
92.     }
94.     private static async Task HandleInitialize(HttpContext context, JsonRpcRequest request)
95.     {
96.         // 复用或创建 Session ID
97.         string sessionId = context.Request.Headers.TryGetValue("Mcp-Session-Id", out StringValues existingSessionId)
98.             ? existingSessionId.ToString()
99.             : WebEncoders.Base64UrlEncode(Guid.NewGuid().ToByteArray());
101.         context.Response.Headers["Mcp-Session-Id"] = sessionId;
103.         // 构建与抓包一致的响应
104.         InitializeResult result = new(
105.             "2025-06-18", // Echo the protocol version
106.             new ServerCapabilities(new { listChanged = true }), // Mimic the capabilities
107.             new ClientInfo("PureAspNetCoreMcpServer", "1.0.0")
108.         );
109.         JsonRpcResponse response = new("2.0", result, null, request.Id);
110.         await WriteSseMessageAsync(context.Response, response);
111.     }
113.     private static async Task HandleToolList<TTools>(HttpContext context, JsonRpcRequest request) where TTools : class
114.     {
115.         EchoSessionId(context);
117.         List<ToolDefinition> toolDefs = [];
118.         MethodInfo[] toolMethods = typeof(TTools).GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly);
120.         foreach (MethodInfo method in toolMethods)
121.         {
122.             string description = method.GetCustomAttribute<DescriptionAttribute>()?.Description ?? "No description.";
124.             // 简化的动态Schema生成
125.             Dictionary<string, object> properties = [];
126.             List<string> required = [];
127.             foreach (ParameterInfo param in method.GetParameters())
128.             {
129.                 if (param.ParameterType == typeof(IProgress<ProgressNotificationValue>)) continue; // 忽略进度报告参数
130.                 properties[param.Name!] = new { type = GetJsonType(param.ParameterType) };
131.                 if (!param.IsOptional)
132.                 {
133.                     required.Add(param.Name!);
134.                 }
135.             }
136.             var schema = new { type = "object", properties, required };
137.             toolDefs.Add(new ToolDefinition(ToSnakeCase(method.Name), description, schema));
138.         }
140.         ToolListResult result = new(toolDefs);
141.         JsonRpcResponse response = new("2.0", result, null, request.Id);
142.         await WriteSseMessageAsync(context.Response, response);
143.     }
145.     private static async Task HandleToolCall<TTools>(HttpContext context, JsonRpcRequest request, IServiceProvider sp, Dictionary<string, MethodInfo> methods) where TTools : class
146.     {
147.         EchoSessionId(context);
149.         ToolCallParams? toolCallParams = JsonSerializer.Deserialize<ToolCallParams>(JsonSerializer.Serialize(request.Params, s_jsonOptions), s_jsonOptions);
150.         if (toolCallParams == null) return;
152.         string toolName = toolCallParams.Name;
153.         methods.TryGetValue(toolName, out MethodInfo? method);
155.         // 场景1: 调用不存在的工具 -> 返回标准JSON-RPC错误
156.         if (method == null)
157.         {
158.             JsonRpcError error = new(InvalidParamsErrorCode, $"Unknown tool: '{toolName}'");
159.             JsonRpcResponse response = new("2.0", null, error, request.Id);
160.             await WriteSseMessageAsync(context.Response, response);
161.             return;
162.         }
164.         // 使用DI容器创建工具类的实例
165.         using IServiceScope scope = sp.CreateScope();
166.         TTools toolInstance = scope.ServiceProvider.GetRequiredService<TTools>();
168.         object? resultValue;
169.         bool isError = false;
171.         try
172.         {
173.             // 通过反射准备方法参数
174.             ParameterInfo[] methodParams = method.GetParameters();
175.             object?[] args = new object?[methodParams.Length];
176.             for (int i = 0; i < methodParams.Length; i++)
177.             {
178.                 ParameterInfo p = methodParams[i];
179.                 if (p.ParameterType == typeof(IProgress<ProgressNotificationValue>))
180.                 {
181.                     // 创建一个IProgress<T>的实现，它会将进度作为SSE消息发回客户端
182.                     args[i] = new ProgressReporter(context.Response, toolCallParams.Meta!.ProgressToken);
183.                 }
184.                 else if (toolCallParams.Arguments.TryGetValue(p.Name!, out object? argValue) && argValue is JsonElement element)
185.                 {
186.                     args[i] = element.Deserialize(p.ParameterType, s_jsonOptions);
187.                 }
188.                 else if (p.IsOptional)
189.                 {
190.                     args[i] = p.DefaultValue;
191.                 }
192.                 else
193.                 {
194.                      // 场景2a: 缺少必要参数 -> 抛出异常，进入catch块
195.                     throw new TargetParameterCountException($"Tool '{toolName}' requires parameter '{p.Name}' but it was not provided.");
196.                 }
197.             }
199.             object? invokeResult = method.Invoke(toolInstance, args);
201.             // 处理异步方法
202.             if (invokeResult is Task task)
203.             {
204.                 await task;
205.                 resultValue = task.GetType().IsGenericType ? task.GetType().GetProperty("Result")?.GetValue(task) : null;
206.             }
207.             else
208.             {
209.                 resultValue = invokeResult;
210.             }
211.         }
212.         // 场景2b: 工具执行时内部抛出异常 -> isError: true
213.         catch (Exception ex)
214.         {
215.             isError = true;
216.             // 将异常信息包装在result中，而不是顶层error
217.             resultValue = $"An error occurred invoking '{toolName}'. Details: {ex.InnerException?.Message ?? ex.Message}";
218.         }
220.         List<ContentItem> content = [new("text", resultValue?.ToString() ?? string.Empty)];
221.         ToolCallResult result = new(content, isError);
222.         JsonRpcResponse finalResponse = new("2.0", result, null, request.Id);
223.         await WriteSseMessageAsync(context.Response, finalResponse);
224.     }
226.     // 手动实现SSE消息写入，告别预览版包
227.     private static async Task WriteSseMessageAsync(HttpResponse response, object data)
228.     {
229.         if (!response.Headers.ContainsKey("Content-Type"))
230.         {
231.             response.ContentType = "text/event-stream";
232.             response.Headers.CacheControl = "no-cache,no-store";
233.             response.Headers.ContentEncoding = "identity";
234.             response.Headers.KeepAlive = "true";
235.         }
237.         string json = JsonSerializer.Serialize(data, s_jsonOptions);
238.         string message = $"event: message\ndata: {json}\n\n";
239.         await response.WriteAsync(message);
240.         await response.Body.FlushAsync();
241.     }
243.     private static void EchoSessionId(HttpContext context)
244.     {
245.         if (context.Request.Headers.TryGetValue("Mcp-Session-Id", out StringValues sessionId))
246.         {
247.             context.Response.Headers["Mcp-Session-Id"] = sessionId;
248.         }
249.     }
251.     private static string GetJsonType(Type type) => Type.GetTypeCode(type) switch
252.     {
253.         TypeCode.String => "string",
254.         TypeCode.Int32 or TypeCode.Int64 or TypeCode.Int16 or TypeCode.UInt32 => "integer",
255.         TypeCode.Double or TypeCode.Single or TypeCode.Decimal => "number",
256.         TypeCode.Boolean => "boolean",
257.         _ => "object"
258.     };
260.     // 专门用于处理进度报告的辅助类
261.     private class ProgressReporter(HttpResponse response, string token) : IProgress<ProgressNotificationValue>
262.     {
263.         public void Report(ProgressNotificationValue value)
264.         {
265.             ProgressParams progressParams = new(token, value.Progress, value.Total, value.Message);
266.             ProgressNotification notification = new("2.0", "notifications/progress", progressParams);
267.             // 警告: 在同步方法中调用异步代码，在真实生产环境中需要更优雅的处理
268.             WriteSseMessageAsync(response, notification).GetAwaiter().GetResult();
269.         }
270.     }
271. }

复制代码

完整代码已备好！

为了方便大家动手实践，我已经将上述所有可直接运行的示例代码上传到了 GitHub Gist。您可以通过以下链接访问：

• https://gist.github.com/sdcb/80353c3273cd1a89b839c6d40fb1adbc
  

该Gist中包含了两个文件：

• mcp-server-raw.linq: 我们刚刚从零开始构建的轻量级MCP服务端。
  
• mcp-client.linq: 用于测试的客户端。
  

这两个文件都可以直接在最新版的 LINQPad 中打开并运行，让您能够立即体验和调试，如果您访问 Github Gist 有困难，则可以访问这个备用地址：https://github.com/sdcb/blog-data/tree/master/2025

第三步：见证奇迹的时刻

现在，我们所有的准备工作都已就绪。我们可以用和昨天一模一样的客户端代码来测试我们的新服务端了：

1. // 客户端代码完全不变！
2. var clientTransport = new SseClientTransport(new SseClientTransportOptions()
3. {
4.     Name = "MyServer",
5.     Endpoint = new Uri("http://localhost:5000"), // 注意端口可能不同
6. });
8. var client = await McpClientFactory.CreateAsync(clientTransport);
10. // 1. 列出工具
11. (await client.ListToolsAsync()).Select(x => new { x.Name, Desc = JsonObject.Parse(x.JsonSchema.ToString()) }).Dump();
13. // 2. 调用简单工具
14. (await client.CallToolAsync(
15.     "echo",
16.     new Dictionary<string, object?>() { ["message"] = ".NET is awesome!" },
17.     cancellationToken: CancellationToken.None)).Dump();
19. // 3. 调用带进度的工具
20. (await client.CallToolAsync(
21.     "count",
22.     new Dictionary<string, object?>() { ["n"] = 5 },
23.     new Reporter(),
24.     cancellationToken: CancellationToken.None)).Dump();
25.    
26. // 4. 调用会抛出异常的工具
27. (await client.CallToolAsync("test_throw", cancellationToken: CancellationToken.None)).Dump();
29. // 5. 调用不存在的工具
30. (await client.CallToolAsync("not-existing-tool", cancellationToken: CancellationToken.None)).Dump();
32. // ... Reporter class as before ...

复制代码

启动我们的新服务端，再运行客户端代码。打开抓包工具，你会发现，所有HTTP请求和SSE响应的格式、内容和行为，都与昨天分析的官方库实现完全一致！我们成功了！
对错误处理的进一步思考

值得一提的是，昨天的文章没有深入探讨参数错误的情况。比如 count 工具需要一个名为 n 的 int 类型参数，如果客户端错误地传递了一个 n2 参数，会发生什么？
在我今天实现的 HandleToolCall 方法中，参数匹配逻辑会因为找不到名为 n 的键而抛出 TargetParameterCountException。这个异常会被 try-catch 块捕获，然后和 test_throw 的情况一样，返回一个调用“成功”（HTTP 200）、但在 result 载荷中包含 "isError": true 和详细错误信息的响应。这恰好证明了MCP这种错误处理设计的健壮性：它能统一处理业务逻辑层面（工具内部异常）和参数绑定层面（调用约定不匹配）的多种失败情况。
总结

通过本次实践，我们不仅重温了MCP协议的通信原理，更重要的是，我们亲手实现了一个轻量级、无预览版依赖的MCP服务端。这次旅程的核心收获是：

• 协议是根基：一旦深刻理解了协议本身，即使没有官方SDK，我们也能在任何支持HTTP的环境中实现它。
  
• 化繁为简：我们用一个扩展方法和一些辅助类，就替代了官方库及其繁杂的依赖，代码清晰且易于掌控。
  
• 反射与元编程的威力：通过巧妙运用反射，我们实现了工具的自动发现和动态调用，大大提高了代码的灵活性和可扩展性。
  
• 知其然，知其所以然：现在，我们不仅知道MCP如何工作，更通过自己动手理解了它为何如此设计，比如两步握手、SSE流式响应以及分层的错误处理机制。
  

希望本文能帮助你彻底搞懂并掌握MCP协议的实现细节。现在，你拥有了完全控制MCP通信的能力，无论是进行二次开发、跨语言实现，还是仅仅为了满足那份技术探索的好奇心。
感谢您的阅读，如果您有任何问题或想法，欢迎在评论区留言讨论。
也欢迎加入我们的 .NET骚操作 QQ群一起探讨：495782587

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！