Spring AI项目中MCP工具调用与ToolContext的兼容性问题解析

背景介绍

在Spring AI 1.0.0-M6版本中，开发者尝试将Model Context Protocol (MCP)工具集成到现有Spring AI应用时遇到了一个关键的技术挑战。当应用中设置了ToolContext并尝试调用MCP工具时，系统会抛出UnsupportedOperationException异常，提示"Tool context is not supported!"。

问题本质

这个问题的核心在于Spring AI框架中的工具调用机制与MCP协议之间的兼容性差异。具体表现为：

1. ToolContext的设计初衷：Spring AI中的ToolContext原本是为本地工具调用设计的上下文传递机制，允许在工具调用过程中携带额外的上下文信息。

2. MCP协议的限制：MCP作为一种通用的模型上下文协议，其标准实现并未考虑ToolContext这种Spring AI特有的上下文传递机制。

3. 框架实现冲突：当开发者同时使用本地Spring AI工具和远程MCP工具时，框架会统一尝试传递ToolContext，导致与MCP工具的不兼容。

技术细节分析

深入代码层面，问题出现在SyncMcpToolCallback类的实现上。这个类继承自ToolCallback，但没有覆盖处理ToolContext的方法。当框架尝试调用带有ToolContext的工具时，会触发父类的默认实现，从而抛出UnsupportedOperationException。

在Spring AI的核心代码中，ToolCallback类的call方法明确声明不支持ToolContext：

public String call(String toolInput, ToolContext toolContext) {
    throw new UnsupportedOperationException("Tool context is not supported!");
}

解决方案演进

Spring AI团队针对这个问题提出了两种解决方案：

1. 忽略ToolContext：对于MCP工具调用，简单地忽略传入的ToolContext参数。这种方案适用于不需要上下文信息的简单工具调用场景。

2. 协议扩展：长期来看，可以考虑扩展MCP协议本身，使其支持某种形式的上下文传递机制。这将需要与MCP社区协作，制定统一的标准。

在实际修复中，团队选择了第一种方案作为临时解决方案，通过修改SyncMcpToolCallback和AsyncMcpToolCallback的实现，使其能够处理（但忽略）ToolContext参数，从而避免异常抛出。

最佳实践建议

对于开发者而言，在使用Spring AI集成MCP工具时，可以遵循以下实践：

1. 避免混合使用：尽量不要在同一调用中混用需要ToolContext的本地工具和MCP远程工具。

2. 上下文替代方案：对于需要传递上下文信息的场景（如身份验证令牌），可以考虑：

   • 将必要信息直接编码到工具输入参数中
   • 使用MethodToolCallback将工具实现本地化
   • 通过其他机制（如线程局部变量）传递上下文

3. 版本选择：确保使用包含修复的Spring AI版本（1.0.0-SNAPSHOT或更高）。

技术展望

这个问题反映了分布式AI系统开发中的一个常见挑战：如何在保持协议通用性的同时，支持特定框架的高级功能。未来可能的改进方向包括：

1. 标准化上下文传递：推动MCP协议增加对上下文的支持，使其成为可选扩展。

2. 适配层设计：在框架中实现更智能的上下文适配机制，能够根据工具类型自动处理或转换上下文。

3. 开发者工具增强：提供更清晰的文档和编译时检查，帮助开发者避免不兼容的工具组合。

通过理解这个问题及其解决方案，开发者可以更有效地在Spring AI生态系统中集成MCP工具，同时为未来的协议演进做好准备。