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

问题背景

在ModelContextProtocol C# SDK的使用过程中，开发者发现当使用PromptMessage类创建提示消息时，Role枚举值的序列化结果与某些MCP客户端的要求存在兼容性问题。具体表现为，当Role属性设置为Role.Assistant时，JSON序列化输出为"Assistant"（首字母大写），而部分客户端（如Claude）严格要求角色值必须为全小写格式。

技术细节分析

该问题本质上是一个JSON序列化过程中的枚举值格式化问题。在C#中，枚举类型默认使用ToString()方法进行序列化，这会保留枚举成员定义时的大小写形式。对于MCP协议规范而言，角色字段的值通常要求统一为小写形式（如"assistant"、"user"等），以保证跨平台兼容性。

解决方案

项目团队已经通过PR #61修复了这个问题。修复方案通常有以下几种技术实现方式：

1. 自定义JsonConverter：为Role枚举类型创建专门的JsonConverter，在序列化时强制转换为小写
2. JsonProperty特性：使用[JsonProperty(PropertyName = "assistant")]为每个枚举成员指定序列化名称
3. 字符串值枚举：将枚举重构为包含字符串值的类型，如使用nameof运算符或常量字符串

最佳实践建议

在处理协议规范的枚举序列化时，建议：

1. 严格遵循协议规范定义的大小写要求
2. 为枚举类型实现自定义序列化逻辑，而非依赖默认行为
3. 在单元测试中加入序列化格式的验证用例
4. 考虑使用代码生成工具来保证与协议规范的严格一致性

影响范围

该问题主要影响以下场景：

• 使用C# SDK与对大小写敏感的MCP客户端交互
• 跨语言系统集成时对协议规范的严格遵循
• 自动化测试中对消息格式的精确校验

总结

枚举值的序列化格式虽然看似是小问题，但在跨平台协议实现中却至关重要。ModelContextProtocol C# SDK对此问题的快速响应体现了对协议规范严格遵循的重视，也为其他协议实现提供了良好的参考范例。开发者在实现类似协议时，应当特别注意这类细节问题，以确保系统的互操作性。