ModelContextProtocol C SDK中枚举值的OpenAPI规范问题解析

问题背景

在使用ModelContextProtocol C# SDK开发MCP工具时，开发者发现当工具返回结构化JSON输出时，list-tools请求返回的模型没有正确声明枚举类型的可能值。这导致输入模式无法了解每个枚举值的潜在选项及其含义，影响了LLM等系统对输入参数的准确理解。

技术分析

枚举序列化机制

默认情况下，C#中的枚举类型会被序列化为整数而非字符串。这在OpenAPI规范中表现为简单的数值类型，缺乏对枚举值的描述性信息。这种默认行为虽然高效，但牺牲了API文档的可读性和自描述性。

解决方案

方案一：JsonStringEnumConverter注解

最直接的解决方案是为枚举类型添加JsonStringEnumConverter注解：

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum Animal {
    Cat,
    Dog,
    Elephant,
    Frog
}

对于需要AOT兼容的场景，建议使用泛型版本：

[JsonConverter(typeof(JsonStringEnumConverter<Animal>))]
public enum Animal {
    Cat,
    Dog,
    Elephant,
    Frog
}

方案二：全局配置

当无法直接修改枚举定义时（如gRPC生成的类），可以通过全局配置实现：

var options = new JsonSerializerOptions(McpJsonUtilities.DefaultOptions) { 
    Converters = { new JsonStringEnumConverter() } 
};

在MCP服务器端，可以通过WithTools/WithToolsFromAssembly方法应用这些配置。

方案三：源生成器配置

对于高级场景，可以使用源生成器进行配置：

[JsonSourceGenerationOptions(UseStringEnumConverter = true)]
[JsonSerializable(typeof(MyEnumType))]
internal partial class EnumJsonContext : JsonSerializerContext;

最佳实践建议

1. 优先使用字符串枚举：在API设计中，字符串枚举比数值枚举更具可读性和稳定性

2. 统一命名规范：确保枚举值名称遵循一致的命名约定（如PascalCase）

3. 文档补充：即使使用字符串枚举，也建议在Swagger文档中添加额外的描述信息

4. 版本兼容性：当修改现有枚举时，考虑向后兼容性策略

总结

ModelContextProtocol C# SDK中的枚举序列化问题可以通过多种方式解决，开发者应根据具体场景选择最适合的方案。理解这些技术细节有助于构建更健壮、更易用的API接口，特别是在需要与LLM等智能系统交互的场景中。正确的枚举配置不仅能改善API文档质量，还能提升整个系统的可维护性和可扩展性。