ModelContextProtocol C SDK中的JSON Schema兼容性问题解析

在ModelContextProtocol C# SDK开发过程中，我们遇到了一个关于工具输入模式(InputSchema)与MCP规范兼容性的重要技术问题。这个问题涉及到JSON Schema在工具定义中的正确使用方式，以及如何确保与不同客户端的互操作性。

问题背景

当开发者使用AIFunction生成JsonSchema时，会出现一些MCP规范未明确支持的额外属性。这些属性包括"title"、"description"等，虽然它们本身是JSON Schema标准的一部分，但在MCP规范中并未明确要求支持。

某些严格遵循规范的客户端（如某些版本的GitHub Copilot）会拒绝接受这些额外属性，导致即使是最简单的MCP服务器实现也会在这些客户端上运行失败。

技术分析

深入分析MCP规范中定义的元模式(meta-schema)后，我们发现规范并没有明确禁止额外属性的存在。规范中缺少"additionalProperties": false这样的声明，唯一明确的要求是必须包含"type": "object"关键字。

当前C# SDK已经实现了对type关键字的验证逻辑，确保所有输入模式都声明为对象类型。从技术角度来看，强制要求客户端只能处理type、properties或required关键字的做法实际上是不符合MCP规范的。

解决方案

基于上述分析，我们采取了以下技术路线：

1. 保留JSON Schema中必要的关键字，如items、additionalProperties、enum和anyOf等，这些关键字对于描述常见输入类型的模式是不可或缺的。

2. 对于可能引起兼容性问题的冗余属性（如title和description），我们进行了过滤处理。这些属性在包含它们的工具定义中已经存在，因此在输入模式中重复出现确实没有必要。

3. 强化了SDK对MCP规范的遵循，确保核心功能严格符合规范要求，同时保持足够的灵活性以支持各种使用场景。

最佳实践建议

对于使用ModelContextProtocol C# SDK的开发者，我们建议：

1. 在定义工具输入模式时，优先使用MCP规范明确支持的关键字。

2. 避免在输入模式中包含冗余信息，特别是那些已经在工具定义中存在的属性。

3. 在遇到客户端兼容性问题时，首先检查输入模式是否符合MCP规范的基本要求，特别是type关键字的存在和正确性。

4. 对于必须使用的JSON Schema高级特性，确保客户端确实支持这些特性，或者准备好适当的回退方案。

通过遵循这些实践，开发者可以构建出既符合MCP规范，又能与各种客户端良好互操作的MCP服务实现。