Mikel
来源： 抛开官方库，手撸一个轻量级 MCP 服务端 – .NET骚操作 – 博客园
大家好！在昨天的文章 《官方文档没告诉你的：通过抓包，深入揭秘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）的方式能够尽可能地简洁和直观，几乎和昨天的代码保持一致：
using System.ComponentModel;
public class Tools(IHttpContextAccessor http)
{
[Description("Echoes the message back to the client.")]
public string Echo(string message) => $"hello {message}";
[Description("Returns the IP address of the client.")]
public string EchoIP() => http.HttpContext?.Connection.RemoteIpAddress?.ToString() ?? "Unknown";
[Description("Counts from 0 to n, reporting progress at each step.")]
public async Task<int> Count(int n, IProgress<ProgressNotificationValue> progress)
{
for (int i = 0; i < n; ++i)
{
progress.Report(new ProgressNotificationValue()
{
Progress = i,
Total = n,
Message = $"Step {i} of {n}",
});
await Task.Delay(100);
}
return n;
}
[Description("Throws an exception for testing purposes.")]
public string TestThrow()
{
throw new Exception("This is a test exception");
}
}
注意到变化了吗？我们去掉了官方库定义的 [McpServerToolType] 和 [McpServerTool] 特性。取而代之的是一种更符合ASP.NET Core直觉的方式：任何 public 方法都自动成为一个工具，并使用标准的 System.ComponentModel.DescriptionAttribute 来提供工具描述。
理想中的使用方式
我们期望最终的使用方式能像下面这样优雅：
WebApplicationBuilder builder = WebApplication.CreateBuilder();
// 1. 注册原生服务和我们的工具类
builder.Services.AddHttpContextAccessor();
builder.Services.AddTransient<Tools>();
WebApplication app = builder.Build();
// 2. 映射 MCP 端点，自动发现并使用 Tools 类
app.MapMcpEndpoint<Tools>("/");
// 3. 启动应用
app.Run();
是的，你没看错。核心就在于 builder.Services.AddTransient<Tools>(); 和 app.MapMcpEndpoint<Tools>("/"); 这两行。前者负责将我们的工具类注册到依赖注入容器，后者则是我们即将创建的魔法扩展方法，它会自动处理所有MCP协议的细节。
第一步：定义协议的“语言” – DTOs
要实现协议，首先要定义好通信双方所使用的“语言”，也就是数据传输对象（DTOs）。根据昨天的抓包分析，我们用C#的 record 类型来精确描述这些JSON结构。
using System.Text.Json.Serialization;
// --- JSON-RPC Base Structures ---
public record JsonRpcRequest(
[property: JsonPropertyName("jsonrpc")] string JsonRpc,
[property: JsonPropertyName("method")] string Method,
[property: JsonPropertyName("params")] object? Params,
[property: JsonPropertyName("id")] int? Id
);
public record JsonRpcResponse(
[property: JsonPropertyName("jsonrpc")] string JsonRpc,
[property: JsonPropertyName("result")] object? Result,
[property: JsonPropertyName("error")] object? Error,
[property: JsonPropertyName("id")] int? Id
);
public record JsonRpcError(
[property: JsonPropertyName("code")] int Code,
[property: JsonPropertyName("message")] string Message
);
// --- MCP Specific Payloads ---
// For initialize method
public record InitializeParams(
[property: JsonPropertyName("protocolVersion")] string ProtocolVersion,
[property: JsonPropertyName("clientInfo")] ClientInfo ClientInfo
);
public record ClientInfo([property: JsonPropertyName("name")] string Name, [property: JsonPropertyName("version")] string Version);
public record InitializeResult(
[property: JsonPropertyName("protocolVersion")] string ProtocolVersion,
[property: JsonPropertyName("capabilities")] ServerCapabilities Capabilities,
[property: JsonPropertyName("serverInfo")] ClientInfo ServerInfo
);
public record ServerCapabilities([property: JsonPropertyName("tools")] object Tools);
// For tools/call method
public record ToolCallParams(
[property: JsonPropertyName("name")] string Name,
[property: JsonPropertyName("arguments")] Dictionary<string, object?> Arguments,
[property: JsonPropertyName("_meta")] ToolCallMeta? Meta
);
public record ToolCallMeta([property: JsonPropertyName("progressToken")] string ProgressToken);
// For tool call results
public record ToolCallResult(
[property: JsonPropertyName("content")] List<ContentItem> Content,
[property: JsonPropertyName("isError")] bool IsError = false
);
public record ContentItem([property: JsonPropertyName("type")] string Type, [property: JsonPropertyName("text")] string Text);
// For tools/list results
public record ToolListResult(
[property: JsonPropertyName("tools")] List<ToolDefinition> Tools
);
public record ToolDefinition(
[property: JsonPropertyName("name")] string Name,
[property: JsonPropertyName("description")] string Description,
[property: JsonPropertyName("inputSchema")] object InputSchema
);
// For progress notifications
public record ProgressNotification(
[property: JsonPropertyName("jsonrpc")] string JsonRpc,
[property: JsonPropertyName("method")] string Method,
[property: JsonPropertyName("params")] ProgressParams Params
);
public record ProgressParams(
[property: JsonPropertyName("progressToken")] string ProgressToken,
[property: JsonPropertyName("progress")] int Progress,
[property: JsonPropertyName("total")] int Total,
[property: JsonPropertyName("message")] string Message
);
// This class is for the IProgress<T> interface in our Tools methods
public class ProgressNotificationValue
{
public int Progress { get; set; }
public int Total { get; set; }
public string Message { get; set; } = string.Empty;
}
第二步：打造核心引擎 – McpEndpointExtensions
接下来，就是实现我们魔法的源泉：一个IEndpointRouteBuilder的扩展方法。我们将所有逻辑都封装在一个静态类 McpEndpointExtensions 中。
这个类将负责：
- 路由映射：监听指定路径的
POST和GET请求。 - 请求分发：根据JSON-RPC请求中的
method字段，调用不同的处理函数。 - 工具发现与调用：使用反射来查找和执行
TTools类中的工具方法。 - 响应构建：手动构建符合SSE规范的响应流。
- 错误处理：精确复现抓包分析中发现的两种错误模型。
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.WebUtilities;
using Microsoft.Extensions.Primitives;
using System.ComponentModel;
using System.Reflection;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
public static class McpEndpointExtensions
{
// JSON-RPC Error Codes from your article's findings
private const int InvalidParamsErrorCode = -32602; // Invalid params
private const int MethodNotFoundErrorCode = -32601; // Method not found
private static readonly JsonSerializerOptions s_jsonOptions = new()
{
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
};
/// <summary>
/// Maps an endpoint that speaks the Model Context Protocol.
/// </summary>
public static IEndpointRouteBuilder MapMcpEndpoint<TTools>(this IEndpointRouteBuilder app, string pattern) where TTools : class
{
// 预先通过反射发现所有工具方法，并转换为snake_case以匹配MCP命名习惯
Dictionary<string, MethodInfo> methods = typeof(TTools).GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly)
.ToDictionary(k => ToSnakeCase(k.Name), v => v);
app.MapPost(pattern, async (HttpContext context, [FromServices] IServiceProvider sp) =>
{
JsonRpcRequest? request = await JsonSerializer.DeserializeAsync<JsonRpcRequest>(context.Request.Body, s_jsonOptions);
if (request == null)
{
context.Response.StatusCode = 400; // Bad Request
return;
}
// 核心：处理不同的MCP方法
switch (request.Method)
{
case "initialize":
await HandleInitialize(context, request);
break;
case "notifications/initialized":
// 在无状态模式下，这个请求只是一个确认，我们返回与initialize类似的信息
await HandleInitialize(context, request);
break;
case "tools/list":
await HandleToolList<TTools>(context, request);
break;
case "tools/call":
await HandleToolCall<TTools>(context, request, sp, methods);
break;
default:
JsonRpcResponse errorResponse = new("2.0", null, new JsonRpcError(MethodNotFoundErrorCode, "Method not found"), request.Id);
await WriteSseMessageAsync(context.Response, errorResponse);
break;
}
});
// 旧版SDK会发送GET请求，我们明确返回405
app.MapGet(pattern, context =>
{
context.Response.StatusCode = StatusCodes.Status405MethodNotAllowed;
context.Response.Headers.Allow = "POST";
return Task.CompletedTask;
});
return app;
}
private static string ToSnakeCase(string name)
{
if (string.IsNullOrEmpty(name)) return name;
var sb = new StringBuilder(name.Length);
for (int i = 0; i < name.Length; i++)
{
char c = name[i];
if (char.IsUpper(c))
{
if (sb.Length > 0 && i > 0 && !char.IsUpper(name[i-1])) sb.Append('_');
sb.Append(char.ToLowerInvariant(c));
}
else
{
sb.Append(c);
}
}
return sb.ToString();
}
private static async Task HandleInitialize(HttpContext context, JsonRpcRequest request)
{
// 复用或创建 Session ID
string sessionId = context.Request.Headers.TryGetValue("Mcp-Session-Id", out StringValues existingSessionId)
? existingSessionId.ToString()
: WebEncoders.Base64UrlEncode(Guid.NewGuid().ToByteArray());
context.Response.Headers["Mcp-Session-Id"] = sessionId;
// 构建与抓包一致的响应
InitializeResult result = new(
"2025-06-18", // Echo the protocol version
new ServerCapabilities(new { listChanged = true }), // Mimic the capabilities
new ClientInfo("PureAspNetCoreMcpServer", "1.0.0")
);
JsonRpcResponse response = new("2.0", result, null, request.Id);
await WriteSseMessageAsync(context.Response, response);
}
private static async Task HandleToolList<TTools>(HttpContext context, JsonRpcRequest request) where TTools : class
{
EchoSessionId(context);
List<ToolDefinition> toolDefs = [];
MethodInfo[] toolMethods = typeof(TTools).GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly);
foreach (MethodInfo method in toolMethods)
{
string description = method.GetCustomAttribute<DescriptionAttribute>()?.Description ?? "No description.";
// 简化的动态Schema生成
Dictionary<string, object> properties = [];
List<string> required = [];
foreach (ParameterInfo param in method.GetParameters())
{
if (param.ParameterType == typeof(IProgress<ProgressNotificationValue>)) continue; // 忽略进度报告参数
properties[param.Name!] = new { type = GetJsonType(param.ParameterType) };
if (!param.IsOptional)
{
required.Add(param.Name!);
}
}
var schema = new { type = "object", properties, required };
toolDefs.Add(new ToolDefinition(ToSnakeCase(method.Name), description, schema));
}
ToolListResult result = new(toolDefs);
JsonRpcResponse response = new("2.0", result, null, request.Id);
await WriteSseMessageAsync(context.Response, response);
}
private static async Task HandleToolCall<TTools>(HttpContext context, JsonRpcRequest request, IServiceProvider sp, Dictionary<string, MethodInfo> methods) where TTools : class
{
EchoSessionId(context);
ToolCallParams? toolCallParams = JsonSerializer.Deserialize<ToolCallParams>(JsonSerializer.Serialize(request.Params, s_jsonOptions), s_jsonOptions);
if (toolCallParams == null) return;
string toolName = toolCallParams.Name;
methods.TryGetValue(toolName, out MethodInfo? method);
// 场景1: 调用不存在的工具 -> 返回标准JSON-RPC错误
if (method == null)
{
JsonRpcError error = new(InvalidParamsErrorCode, $"Unknown tool: '{toolName}'");
JsonRpcResponse response = new("2.0", null, error, request.Id);
await WriteSseMessageAsync(context.Response, response);
return;
}
// 使用DI容器创建工具类的实例
using IServiceScope scope = sp.CreateScope();
TTools toolInstance = scope.ServiceProvider.GetRequiredService<TTools>();
object? resultValue;
bool isError = false;
try
{
// 通过反射准备方法参数
ParameterInfo[] methodParams = method.GetParameters();
object?[] args = new object?[methodParams.Length];
for (int i = 0; i < methodParams.Length; i++)
{
ParameterInfo p = methodParams[i];
if (p.ParameterType == typeof(IProgress<ProgressNotificationValue>))
{
// 创建一个IProgress<T>的实现，它会将进度作为SSE消息发回客户端
args[i] = new ProgressReporter(context.Response, toolCallParams.Meta!.ProgressToken);
}
else if (toolCallParams.Arguments.TryGetValue(p.Name!, out object? argValue) && argValue is JsonElement element)
{
args[i] = element.Deserialize(p.ParameterType, s_jsonOptions);
}
else if (p.IsOptional)
{
args[i] = p.DefaultValue;
}
else
{
// 场景2a: 缺少必要参数 -> 抛出异常，进入catch块
throw new TargetParameterCountException($"Tool '{toolName}' requires parameter '{p.Name}' but it was not provided.");
}
}
object? invokeResult = method.Invoke(toolInstance, args);
// 处理异步方法
if (invokeResult is Task task)
{
await task;
resultValue = task.GetType().IsGenericType ? task.GetType().GetProperty("Result")?.GetValue(task) : null;
}
else
{
resultValue = invokeResult;
}
}
// 场景2b: 工具执行时内部抛出异常 -> isError: true
catch (Exception ex)
{
isError = true;
// 将异常信息包装在result中，而不是顶层error
resultValue = $"An error occurred invoking '{toolName}'. Details: {ex.InnerException?.Message ?? ex.Message}";
}
List<ContentItem> content = [new("text", resultValue?.ToString() ?? string.Empty)];
ToolCallResult result = new(content, isError);
JsonRpcResponse finalResponse = new("2.0", result, null, request.Id);
await WriteSseMessageAsync(context.Response, finalResponse);
}
// 手动实现SSE消息写入，告别预览版包
private static async Task WriteSseMessageAsync(HttpResponse response, object data)
{
if (!response.Headers.ContainsKey("Content-Type"))
{
response.ContentType = "text/event-stream";
response.Headers.CacheControl = "no-cache,no-store";
response.Headers.ContentEncoding = "identity";
response.Headers.KeepAlive = "true";
}
string json = JsonSerializer.Serialize(data, s_jsonOptions);
string message = $"event: message\ndata: {json}\n\n";
await response.WriteAsync(message);
await response.Body.FlushAsync();
}
private static void EchoSessionId(HttpContext context)
{
if (context.Request.Headers.TryGetValue("Mcp-Session-Id", out StringValues sessionId))
{
context.Response.Headers["Mcp-Session-Id"] = sessionId;
}
}
private static string GetJsonType(Type type) => Type.GetTypeCode(type) switch
{
TypeCode.String => "string",
TypeCode.Int32 or TypeCode.Int64 or TypeCode.Int16 or TypeCode.UInt32 => "integer",
TypeCode.Double or TypeCode.Single or TypeCode.Decimal => "number",
TypeCode.Boolean => "boolean",
_ => "object"
};
// 专门用于处理进度报告的辅助类
private class ProgressReporter(HttpResponse response, string token) : IProgress<ProgressNotificationValue>
{
public void Report(ProgressNotificationValue value)
{
ProgressParams progressParams = new(token, value.Progress, value.Total, value.Message);
ProgressNotification notification = new("2.0", "notifications/progress", progressParams);
// 警告: 在同步方法中调用异步代码，在真实生产环境中需要更优雅的处理
WriteSseMessageAsync(response, notification).GetAwaiter().GetResult();
}
}
}
完整代码已备好！
为了方便大家动手实践，我已经将上述所有可直接运行的示例代码上传到了 GitHub Gist。您可以通过以下链接访问：
该Gist中包含了两个文件：
mcp-server-raw.linq: 我们刚刚从零开始构建的轻量级MCP服务端。mcp-client.linq: 用于测试的客户端。
这两个文件都可以直接在最新版的 LINQPad 中打开并运行，让您能够立即体验和调试，如果您访问 Github Gist 有困难，则可以访问这个备用地址：https://github.com/sdcb/blog-data/tree/master/2025
第三步：见证奇迹的时刻
现在，我们所有的准备工作都已就绪。我们可以用和昨天一模一样的客户端代码来测试我们的新服务端了：
// 客户端代码完全不变！
var clientTransport = new SseClientTransport(new SseClientTransportOptions()
{
Name = "MyServer",
Endpoint = new Uri("http://localhost:5000"), // 注意端口可能不同
});
var client = await McpClientFactory.CreateAsync(clientTransport);
// 1. 列出工具
(await client.ListToolsAsync()).Select(x => new { x.Name, Desc = JsonObject.Parse(x.JsonSchema.ToString()) }).Dump();
// 2. 调用简单工具
(await client.CallToolAsync(
"echo",
new Dictionary<string, object?>() { ["message"] = ".NET is awesome!" },
cancellationToken: CancellationToken.None)).Dump();
// 3. 调用带进度的工具
(await client.CallToolAsync(
"count",
new Dictionary<string, object?>() { ["n"] = 5 },
new Reporter(),
cancellationToken: CancellationToken.None)).Dump();
// 4. 调用会抛出异常的工具
(await client.CallToolAsync("test_throw", cancellationToken: CancellationToken.None)).Dump();
// 5. 调用不存在的工具
(await client.CallToolAsync("not-existing-tool", cancellationToken: CancellationToken.None)).Dump();
// ... 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
