ModelContextProtocol C SDK 中自定义 JSON Schema 生成的实践指南

在开发基于 ModelContextProtocol (MCP) 的工具时，正确处理输入参数的 JSON Schema 定义对于 AI 代理理解数据类型至关重要。本文将深入探讨如何在 C# SDK 中自定义 JSON Schema 生成，特别是处理 .NET 特有的日期时间类型。

背景与挑战

当开发者定义 MCP 工具时，输入参数的 Schema 会自动生成。对于包含 .NET 特有类型（如 DateTime、DateTimeOffset 和 TimeSpan）的输入类，默认生成的 Schema 可能不足以清晰表达这些类型的语义。

例如，对于以下输入类：

public class TemporalData
{
    [JsonPropertyName("dateTimeValue")]
    public DateTime DateTimeValue { get; set; }

    [JsonPropertyName("dateTimeOffsetValue")]
    public DateTimeOffset DateTimeOffsetValue { get; set; }

    [JsonPropertyName("timeSpanValue")]
    public TimeSpan TimeSpanValue { get; set; }
}

默认生成的 Schema 中，只有 TimeSpan 类型会带有注释说明其 .NET 类型信息，而 DateTime 和 DateTimeOffset 则缺乏足够的元数据描述。

解决方案

1. 使用 TransformSchemaNode 自定义 Schema

对于动态创建的工具，可以通过 SchemaCreateOptions 的 TransformSchemaNode 回调来自定义 Schema 生成：

var tool = McpServerTool.Create((TemporalData input) => "received data", new()
{
    SchemaCreateOptions = new()
    {
        TransformSchemaNode = (ctx, node) =>
        {
            Type? t = ctx.PropertyInfo?.PropertyType;
            if (t == typeof(DateTime) || t == typeof(DateTimeOffset))
            {
                node["format"] = "date-time";
            }
            else if (t == typeof(TimeSpan))
            {
                node["format"] = "duration";
            }
            return node;
        },
    },
});

这种方法可以灵活地为特定类型添加格式(format)信息，使生成的 Schema 更加精确。

2. 内置类型映射改进

最新版本的 SDK 已经内置了对常见 .NET 类型的支持，包括：

• DateTime 和 DateTimeOffset 会被标记为 "date-time" 格式
• TimeSpan 会被标记为 "duration" 格式

这些改进使得 Schema 生成更加符合 JSON Schema 规范，无需开发者额外配置。

3. 静态工具方法的限制与替代方案

对于使用 [McpServerTool] 属性标记的静态方法，目前不支持直接通过属性参数来自定义 Schema 生成。开发者可以考虑以下替代方案：

1. 改用动态工具创建方式，获得更细粒度的控制
2. 创建自定义工具包装器，继承或组合现有的工具实例
3. 实现自己的工具发现和注册逻辑，替代属性标记方式

最佳实践建议

1. 优先使用最新版本：确保使用包含内置类型映射改进的 SDK 版本
2. 明确类型语义：对于自定义类型，考虑添加格式(format)和注释(comment)信息
3. 保持一致性：在整个项目中采用统一的 Schema 自定义策略
4. 文档化约定：记录团队对特殊类型的处理方式，便于维护

总结

ModelContextProtocol C# SDK 提供了多种方式来定制 JSON Schema 生成，从简单的回调函数到内置的类型映射支持。理解这些机制可以帮助开发者创建更精确、更易于 AI 代理理解的工具接口定义。对于需要精细控制的场景，推荐使用动态工具创建方式；而对于简单用例，则可以依赖 SDK 的内置支持。

随着 SDK 的不断演进，未来可能会提供更多便捷的方式来定制 Schema 生成，开发者应保持对更新日志的关注，及时采用新的最佳实践。