Spring AI 中 MCP 架构与工具调用技术详解

这篇文章主要是概述MCP是什么，Spring AI如何结合它。如果想要了解如何搭建spring工程并结合MCP开发，可以看我的另外一篇：Spring AI + MCP最详细实践：从配置开始到服务搭建（踩坑无数版）

一、MCP 架构概述

MCP（Message Communication Protocol）是 Spring AI 用于支持 AI 模型交互的消息通信协议，在客户端与服务端之间搭建桥梁，支持多种传输层协议，提供标准化消息格式定义，实现 AI 能力的高效交互与管理。其核心流程为：客户端接收用户输入，通过大模型判断是否调用 MCP 服务器中的工具；若需调用，客户端向 MCP 服务器发起请求，服务器执行对应工具并返回结果，大模型整合结果后生成最终回答。

二、基于 @Tool 注解的工具实现

2.1 工具类定义

在 Spring AI 中，@Tool 注解可简化工具类开发，无需手动实现 Tool 接口。通过该注解，开发者只需专注于工具执行逻辑的编写，示例如下：

import ai.spring.sdk.tool.Tool;
import org.springframework.stereotype.Component;

@Component
@Tool(
    name = "weather",
    description = "获取指定城市的天气信息，参数为城市名称"
)
public class WeatherTool {
    public String execute(String city) {
        // 调用天气API的逻辑
        return "北京当前天气：晴，25℃";
    }
}

上述代码中，@Tool 注解定义了工具名称和描述，execute 方法负责具体工具执行逻辑。

2.2 复杂参数配置

如需更复杂的参数定义，可使用 @Parameter 注解对每个参数进行详细描述，便于大模型理解和调用：

@Component
@Tool(
    name = "weather",
    description = "获取指定城市的天气信息"
)
public class WeatherTool {
    public String execute(
        @Parameter(description = "城市名称") String city,
        @Parameter(description = "日期，格式YYYY-MM-DD，默认为今天") String date
    ) {
        // 实现逻辑
    }
}

三、ToolCallbackProvider 方式暴露 MCP 工具

3.1 核心原理

ToolCallbackProvider 是 Spring AI 中用于注册和管理工具的核心接口，通过 MethodToolCallbackProvider 可以将任意 Spring Bean 中的方法转换为可调用的工具。该方式具备松耦合设计、统一管理、类型安全等优势，能够将工具实现与框架解耦，基于 Java 方法参数和返回值确保工具调用的类型正确性。

3.2 基于 @Bean 的工具注册实现

以下是一个完整的实现示例，展示如何通过 ToolCallbackProvider 注册多个工具：

import ai.spring.sdk.tool.Tool;
import ai.spring.sdk.tool.ToolCallbackProvider;
import ai.spring.sdk.tool.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ToolConfig {

    @Bean
    public ToolCallbackProvider allAvailableTools(
        WeatherTool weatherTool,
        CalculatorTool calculatorTool,
        EmailService emailService
    ) {
        return MethodToolCallbackProvider.builder()
            .toolObjects(weatherTool, calculatorTool, emailService)
            .build();
    }
}

// 天气工具实现
@Component
public class WeatherTool {
    @Tool(name = "weather", description = "获取指定城市的天气信息")
    public String getWeather(@Parameter(name = "city") String city) {
        // 调用天气API的逻辑
        return "北京当前天气：晴，25℃";
    }
}

// 计算器工具实现
@Component
public class CalculatorTool {
    @Tool(name = "calculator", description = "执行数学计算")
    public double calculate(@Parameter(name = "expression") String expression) {
        // 执行计算逻辑
        return 42.0;
    }
}

// 邮件服务工具实现
@Component
public class EmailService {
    @Tool(name = "sendEmail", description = "发送电子邮件")
    public void sendEmail(
        @Parameter(name = "to") String to,
        @Parameter(name = "subject") String subject,
        @Parameter(name = "content") String content
    ) {
        // 发送邮件逻辑
    }
}

3.3 工具元数据与参数描述

使用 @Tool 和 @Parameter 注解可以为工具提供详细的元数据，帮助大模型理解工具功能和参数要求：

@Tool(
    name = "getStockPrice",
    description = "获取指定股票代码的当前价格",
    parameters = {
        @Parameter(name = "symbol", description = "股票代码，如 AAPL, MSFT"),
        @Parameter(name = "date", description = "日期，格式 YYYY-MM-DD，默认为今天")
    }
)
public double getStockPrice(String symbol, @Nullable String date) {
    // 实现逻辑
}

3.4 工具调用流程

1. 工具注册阶段：Spring 容器启动时，扫描所有带有 @Tool 注解的方法；ToolCallbackProvider 将这些方法封装为工具定义；工具元数据（名称、描述、参数）被收集并存储在工具注册表中。
2. 客户端发现阶段：MCP 服务器通过专用接口（如 /mcp/tools/metadata）暴露所有工具信息；客户端（或大模型）获取工具清单并了解其功能。
3. 工具调用阶段：大模型根据用户问题选择合适的工具；客户端向 MCP 服务器发送工具调用请求（包含工具名称和参数）；MCP 服务器根据工具名称路由到对应的方法并执行；执行结果返回给客户端，最终整合到用户响应中。

3.5 高级应用：自定义工具过滤器

开发者可以通过实现 ToolFilter 接口来动态控制工具可见性，例如只对管理员用户暴露敏感工具：

@Component
public class AdminToolFilter implements ToolFilter {
    @Override
    public boolean accept(Tool tool, Authentication authentication) {
        // 只对管理员用户暴露敏感工具
        return authentication != null && authentication.getAuthorities()
            .stream().anyMatch(a -> a.getAuthority().equals("ROLE_ADMIN"));
    }
}

然后在工具配置中应用过滤器：

@Bean
public ToolCallbackProvider filteredTools(AdminToolFilter filter) {
    return MethodToolCallbackProvider.builder()
        .toolObjects(adminOnlyTool)
        .toolFilter(filter)
        .build();
}

四、MCP 架构优势与应用场景

4.1 核心优势

1. 协议抽象：统一不同传输层协议交互逻辑，客户端无需关注底层通信细节。
2. 智能决策：通过大模型判断工具调用需求，实现任务的智能处理。
3. 高效集成：无缝集成外部工具，拓展 AI 系统处理复杂任务的能力。
4. 可扩展性：基于 Spring 框架扩展点设计，支持自定义协议、模型适配器和消息处理器。

4.2 典型应用场景

1. 对话式 AI 服务：构建聊天机器人后端，支持多轮对话上下文保持和流式响应。
2. AI 工具集成：为前端应用提供统一 AI 能力接口，如文本生成、代码补全。
3. 多模态交互：处理文本、图像、语音等多类型输入的模型推理请求。
4. 企业级 AI 中台：作为 AI 能力中台通信层，统一管理模型调用和资源分配 。

通过上述内容，可深入理解 Spring AI 中 MCP 架构的原理与实现，基于 @Tool 注解和 ToolCallbackProvider 快速开发和集成工具，构建功能强大的 AI 应用系统。