Spring AI项目中MCP工具列表调用异常的分析与解决

问题背景

在使用Spring AI项目的Model Context Protocol(MCP)组件时，开发者可能会遇到一个常见的异常情况：当尝试通过MCP客户端调用服务端的工具列表功能时，系统抛出"Method not found: tools/list"错误。这个错误表面上看是方法未找到，但实际上反映了更深层次的配置问题。

异常现象分析

当开发者按照常规方式配置MCP客户端并尝试调用listTools()方法时，控制台会输出详细的错误堆栈，核心错误信息显示为"Method not found: tools/list"。这个错误发生在MCP协议的通信层，表明客户端请求的服务端端点不存在或不可用。

根本原因

经过深入分析，这个问题并非真正的"方法不存在"，而是由于服务端缺少必要的工具配置导致的。在Spring AI的MCP架构中，服务端需要显式地通过ToolCallbackProvider来配置可用的工具集合，否则客户端无法发现任何工具。

解决方案

要解决这个问题，开发者需要在服务端应用中添加以下配置：

@Bean
public ToolCallbackProvider yourMCPTools(YourMCPService mcpService) {
    return MethodToolCallbackProvider.builder()
           .toolObjects(mcpService)
           .build();
}

这个配置的作用是：

1. 创建一个ToolCallbackProvider类型的Spring Bean
2. 使用MethodToolCallbackProvider构建器模式
3. 将包含实际工具方法的服务类(如YourMCPService)注册到MCP框架中

技术细节

1. ToolCallbackProvider：这是Spring AI MCP中定义工具回调的核心接口，负责将Java方法暴露为MCP可调用的工具。

2. MethodToolCallbackProvider：一个具体的实现类，能够将普通Java对象的方法转换为MCP工具。

3. 工具配置机制：MCP服务端启动时会扫描所有配置的ToolCallbackProvider，收集可用的工具方法，并建立对应的端点路由。如果缺少这个配置步骤，客户端请求的tools/list端点自然就不存在。

最佳实践建议

1. 版本兼容性：注意Spring AI 1.0.0-M7版本会更改starter的artifactId命名，升级时需要参考官方文档进行调整。

2. 错误处理：虽然当前错误信息不够直观，但开发者应理解这是服务端配置不完整的表现，而非客户端调用错误。

3. 工具设计：建议将相关工具方法组织在专门的服务类中，保持清晰的职责划分。

总结

Spring AI的MCP组件提供了强大的工具调用能力，但需要正确的服务端配置才能正常工作。遇到"Method not found"错误时，开发者应首先检查服务端是否已正确配置工具提供者。通过本文介绍的方式配置ToolCallbackProvider，可以确保工具列表功能正常可用，为后续的工具调用奠定基础。