ModelContextProtocol C SDK：处理复杂对象参数的最佳实践

引言

在使用ModelContextProtocol（MCP）C# SDK开发AI工具时，开发人员经常会遇到需要传递复杂对象作为参数的情况。本文将通过一个实际案例，深入分析如何在MCP工具方法中正确接收和处理复杂对象参数，避免常见的陷阱。

问题背景

在开发基于MCP的AI工具时，我们通常会定义一些服务方法供AI模型调用。这些方法可以接收基本类型参数，也可以接收自定义的复杂对象。然而，当尝试传递复杂对象时，可能会遇到AI客户端（如Copilot Studio）无法正确识别和构造参数对象的问题。

典型错误示例

考虑以下代码示例，其中定义了一个AzureCommunicationServices工具类，包含一个接收PersonToCall复杂对象的方法：

[McpServerToolType]
public class AzureCommunicationServices
{
    [McpServerTool, Description("Makes a phone call to the user.")]
    public static Task CallUser(PersonToCall person) 
    {
        Console.WriteLine($"Calling the user {person.name}");
        return Task.CompletedTask;
    }
}

public class PersonToCall
{
    public required string? phoneNumber { get; set; }
    public required string? name { get; set; }
    public required string? greeting { get; set; }
}

这种情况下，Copilot Studio等AI客户端可能会混淆参数名称和对象结构，导致无法正确构造调用参数。

问题根源分析

经过深入调查，发现问题主要出在复杂对象的属性定义上。具体表现为：

1. 可空类型问题：属性使用了string?可空类型声明，同时标记为required，这种组合会导致AI客户端在构造对象时产生困惑。

2. 模式识别困难：AI客户端虽然能获取到MCP生成的JSON Schema，但对于某些复杂的类型组合理解不够准确。

解决方案

方案一：简化对象定义

最直接的解决方案是修改复杂对象的属性定义，避免使用required和可空类型的组合：

public class PersonToCall
{
    public string phoneNumber { get; set; } = string.Empty;
    public string name { get; set; } = string.Empty;
    public string greeting { get; set; } = string.Empty;
}

方案二：使用基本类型参数

如果AI客户端对复杂对象支持不佳，可以考虑将方法参数拆分为基本类型：

[McpServerTool, Description("Makes a phone call to the user.")]
public static Task CallUser(string name, string greeting, string phonenumber)
{ 
    Console.WriteLine($"Calling the user {name}");
    return Task.CompletedTask;
}

最佳实践

1. 属性定义原则：

   • 避免同时使用required和可空类型
   • 为属性提供合理的默认值
   • 保持属性类型简单明确

2. 工具方法设计：

   • 对于简单场景，优先使用基本类型参数
   • 对于复杂数据结构，确保对象定义清晰明确
   • 在文档中添加清晰的参数说明

3. 调试技巧：

   • 使用MCP Inspector验证工具方法的可用性
   • 检查AI客户端接收到的JSON Schema
   • 逐步构建复杂对象，验证每个属性的识别情况

结论

在ModelContextProtocol C# SDK中处理复杂对象参数时，关键在于保持对象定义的简洁性和一致性。通过遵循上述最佳实践，开发人员可以确保AI客户端能够正确识别和构造复杂参数对象，从而实现更强大的工具功能。记住，AI系统对代码模式的识别能力有限，因此简单明确的定义往往能带来最好的兼容性。