在ModelContextProtocol C SDK中处理工具函数可选参数与默认值

在开发基于ModelContextProtocol C# SDK的AI工具函数时，正确处理函数参数的可选性和默认值是一个常见需求。本文将深入探讨这一技术点，帮助开发者更好地设计符合要求的工具函数接口。

参数可选性与默认值的本质区别

在C#语言层面，函数参数的可选性可以通过两种方式实现：

1. 使用Optional特性标记参数
2. 为参数提供默认值

这两种方式在语义上有所不同。Optional特性主要影响方法调用时的行为，而默认值则提供了参数未传递时的回退值。

SDK中的特殊考量

ModelContextProtocol C# SDK在生成工具函数的JSON Schema时，默认会将所有参数标记为必需(required)。这一设计决策源于与AI服务(如OpenAI)的兼容性考虑——在严格模式下，这些服务会拒绝包含非必需参数的Schema。

实际开发中的最佳实践

1. 优先使用默认值：对于需要默认行为的参数，直接提供默认值即可，无需添加Optional特性。

[McpServerTool(Name = "query_data")]
public static async Task<string> QueryData(
    [Description("是否包含详细信息")] bool includeDetails = false)
{
    // 实现代码
}

2. 必需参数处理：对于必须由调用方提供的参数，不要设置默认值，也不需要使用Optional特性。

3. 复杂场景处理：如果确实需要生成包含可选参数的Schema，目前需要通过修改SDK配置实现。开发者可以期待未来版本可能会提供更灵活的配置选项。

技术实现原理

在底层实现上，SDK使用AIJsonSchemaCreateOptions来控制Schema生成行为。其中的RequireAllProperties属性决定了是否将所有参数标记为必需。当前版本默认设置为true以确保最大兼容性。

总结

理解SDK对参数处理的设计哲学，有助于开发者编写出既符合规范又能满足业务需求的工具函数。随着AI服务生态的发展，相关参数处理机制也可能会进一步演进，开发者应保持对SDK更新的关注。