ModelContextProtocol C SDK中的枚举序列化问题解析

问题背景

在ModelContextProtocol C# SDK的开发过程中，开发人员发现了一个关于枚举序列化的技术问题。当使用GetPromptHandler返回GetPromptResult时，PromptMessage类型中的Role字段在序列化时使用了枚举值的大写形式，而下游工具如Claude和MCP Inspector期望的是小写值。

问题现象

具体表现为，当开发人员尝试通过MCP Inspector调用包含PromptMessage的API时，系统会返回验证错误，提示"Invalid enum value. Expected 'user' | 'assistant', received 'User'"。这表明序列化后的JSON中Role字段的值不符合预期格式。

技术分析

这个问题本质上是.NET中枚举序列化的常见问题。在.NET生态中，默认情况下枚举值会按照其定义时的名称进行序列化，即保持大小写不变。然而，许多Web API和规范要求枚举值使用特定的大小写格式（通常是全小写或蛇形命名法）。

在ModelContextProtocol的案例中，规范明确要求Role枚举值必须是小写形式（"user"和"assistant"），而C#枚举定义通常采用首字母大写（User和Assistant），这就导致了序列化结果不符合规范要求。

解决方案探索

开发团队尝试了几种不同的解决方案：

1. 全局JsonStringEnumConverter配置：最初通过在JsonSerializerOptions中添加JsonStringEnumConverter并指定SnakeCaseLower命名策略来解决问题。这种方法简单直接，但可能会影响项目中所有枚举的序列化行为。

2. 特定枚举的自定义转换器：随后尝试为Role枚举专门创建RoleConverter，继承自JsonStringEnumConverter并指定命名策略。这种方法更加精确，只影响目标枚举。

3. AOT兼容性考虑：由于JsonStringEnumConverter在原生AOT编译中不受支持，解决方案需要同时考虑框架依赖和AOT两种场景。

最终解决方案

结合上述探索，推荐的解决方案是：

1. 为Role枚举添加专门的JsonConverter特性，指定自定义的RoleConverter
2. 在McpJsonUtilities中配置默认的JsonStringEnumConverter时，明确指定SnakeCaseLower命名策略
3. 确保所有相关类型（如ListPromptsResult和GetPromptResult）都被包含在JsonSerializerContext中，以支持AOT编译

这种混合方案既保证了特定枚举的正确序列化，又维持了与AOT编译的兼容性，同时不会过度影响项目中其他枚举的序列化行为。

技术要点总结

1. 枚举序列化控制：在需要精确控制枚举序列化格式时，优先考虑为特定枚举创建自定义转换器。

2. 命名策略选择：根据API规范要求选择合适的命名策略，常见的包括：

   • 原样保留（默认）
   • 驼峰命名（CamelCase）
   • 蛇形命名小写（SnakeCaseLower）
   • 蛇形命名保留大小写（SnakeCase）

3. AOT兼容性：在.NET的AOT编译场景下，需要特别注意：

   • 避免使用某些反射-heavy的转换器
   • 确保所有需要序列化的类型都被正确包含在JsonSerializerContext中
   • 预先注册所有必要的转换器

4. API规范一致性：与外部系统交互时，严格遵守其数据格式规范，包括枚举值的具体表示形式。

这个问题展示了在实际开发中，类型系统、序列化规范和平台特性之间需要仔细协调的重要性，也为处理类似场景提供了有价值的参考模式。