MCP .NET SDK 中实现数据注解支持的JSON Schema生成方案

在MCP .NET SDK开发中，JSON Schema生成是一个关键功能，它直接影响着工具参数的验证约束表达能力。当前版本存在一个明显的功能缺口——无法识别和处理System.ComponentModel.DataAnnotations命名空间下的标准验证属性。

现状分析

开发者在使用记录类型定义工具参数时，通常会应用各种数据注解属性来确保参数的有效性。例如，一个典型的参数定义可能如下：

public record SimulationSettings(
    [Range(-1, 10, ErrorMessage = "必须在-1到10之间")]
    decimal MarketROR
);

然而，当前生成的JSON Schema仅包含最基本的类型信息，完全忽略了这些精心设计的验证约束：

{
  "marketROR": {
    "type": "number"
  }
}

这种局限性导致两个主要问题：首先，开发者被迫在运行时重复实现本应在Schema层面解决的验证逻辑；其次，大型语言模型(LLM)无法利用完整的Schema约束信息一次性生成合规的输入数据，导致需要多次迭代才能获得有效输入。

技术实现方案

核心设计思路

理想的解决方案应该将.NET生态中广泛使用的数据注解属性无缝映射到JSON Schema的验证关键字。这种映射关系包括但不限于：

1. 范围约束：[Range] → minimum/maximum
2. 必填字段：[Required] → required数组
3. 字符串限制：[StringLength] → maxLength
4. 格式验证：[EmailAddress] → format: "email"
5. 正则匹配：[RegularExpression] → pattern

架构层级选择

经过技术团队深入讨论，这一功能的最佳实现位置存在几个候选方案：

1. 最底层实现：在System.Text.Json(STJ)层面直接支持
2. 中间层实现：在Microsoft.Extensions.AI.Abstractions的AIJsonUtilities中处理
3. 应用层实现：在MCP SDK层面定制

考虑到STJ需要保持轻量级且不依赖DataAnnotations，而MCP层又过于具体，中间层实现成为平衡各方需求的最佳选择。

配置扩展方案

为保持灵活性，建议通过构建器模式提供配置选项：

builder.Services
    .AddMcpServer()
    .WithToolsFromAssembly(options =>
    {
        options.EnableDataAnnotationsSupport = true;
        options.SchemaGenerationOptions = new() {
            // 自定义转换规则
        };
    });

技术优势

实现这一增强后将带来多方面收益：

1. 开发效率提升：开发者可以使用熟悉的.NET验证模式，减少重复代码
2. 验证前移：客户端可以在调用工具前就完成参数验证
3. LLM友好性：完整的约束信息帮助大型语言模型一次性生成合规输入
4. 文档自描述：生成的Schema本身就是完善的API文档
5. 生态一致性：与ASP.NET Core等主流框架保持相同的行为模式

实施路径

建议的技术实现分为三个阶段：

1. 基础属性映射：首先支持最常用的5-6种核心验证属性
2. 自定义扩展点：允许开发者注册特殊属性的处理逻辑
3. 性能优化：对反射操作进行缓存，确保生成效率

总结

在MCP .NET SDK中完善数据注解到JSON Schema的转换能力，不仅解决了当前的验证约束表达问题，更是将.NET生态的验证体系与现代AI开发工具链进行了深度整合。这一改进将显著提升开发体验和工具可靠性，同时也为未来可能的底层支持积累了宝贵经验。