ModelContextProtocol C SDK中Native AOT环境下工具参数序列化问题的解决方案

背景介绍

在使用ModelContextProtocol C# SDK开发MCP服务器时，开发者可能会遇到一个特殊的序列化异常问题。这个问题特别容易出现在将MCP服务器集成到Native AOT编译的应用程序中时，尤其是当工具方法包含string[]类型参数的情况下。

问题现象

当在Native AOT环境中运行包含工具方法的MCP服务器时，系统会抛出System.NotSupportedException异常，错误信息明确指出JsonTypeInfo metadata for type 'System.String[]' was not provided。这表明JSON序列化器无法找到string[]类型的元数据信息。

根本原因

Native AOT编译环境与常规的JIT编译环境在序列化处理上有显著差异。在Native AOT中：

1. 反射功能受到严格限制
2. 所有需要序列化的类型必须预先注册
3. 即使是基础类型如string[]也需要显式声明
4. 需要利用System.Text.Json的源生成功能来提前生成序列化代码

解决方案

针对这个问题，开发者可以采取以下步骤解决：

1. 创建自定义JsonSerializerContext：需要为所有工具方法中使用的类型（包括string和string[]）创建专门的序列化上下文。

[JsonSerializable(typeof(string))]
[JsonSerializable(typeof(string[]))]
internal partial class MyMcpServerJsonSerializerContext : JsonSerializerContext
{
}

2. 扩展工具注册方法：创建一个自定义的扩展方法，在注册工具时传入自定义的序列化选项。

internal static partial class MyMcpServer
{
    [RequiresUnreferencedCode("Calls Type.GetMethods() with BindingFlags.NonPublic")]
    internal static IMcpServerBuilder WithToolsAndCustomJsonSerializerContext(
        this IMcpServerBuilder builder, 
        Type toolType)
    {
        // 实现细节...
        foreach (var toolMethod in toolType.GetMethods(BindingFlags.Static | BindingFlags.NonPublic))
        {
            if (toolMethod.GetCustomAttribute<McpServerToolAttribute>() is not null)
            {
                builder.Services.AddSingleton(
                    services => McpServerTool.Create(
                        toolMethod,
                        options: new McpServerToolCreateOptions()
                        {
                            Services = services,
                            SerializerOptions = MyMcpServerJsonSerializerContext.Default.Options
                        }));
            }
        }
        return builder;
    }
}

3. 使用扩展方法注册工具：在服务配置时使用新的扩展方法而非默认方法。

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsAndCustomJsonSerializerContext(typeof(MyMcpServerTools))

最佳实践建议

1. 全面类型注册：不仅注册当前需要的类型，还应注册所有可能用到的类型，包括自定义类型
2. 代码组织：将序列化上下文和工具注册扩展方法放在专门的类中
3. 文档记录：在团队内部文档中记录Native AOT环境下的特殊处理要求
4. 测试验证：在Native AOT环境下进行充分的测试，确保所有工具都能正常工作

总结

在Native AOT环境中使用ModelContextProtocol C# SDK时，开发者需要特别注意类型序列化的特殊要求。通过创建自定义的JsonSerializerContext并正确配置工具注册过程，可以解决string[]等类型的序列化问题。这种方法不仅适用于当前问题，也为处理其他类型的序列化问题提供了参考方案。