filmorago pro会员解锁专业版
84.37M · 2025-10-04
本教程旨在帮助开发者快速掌握 spring-ai-mcp-client-spring-boot-starter 中 Tool 注解 的核心功能与使用方法。通过 Tool 注解，开发者可以轻松将自定义业务逻辑封装为 AI 可调用的工具，实现 AI 与本地服务的无缝集成，适用于智能对话、任务调度、自动化处理等场景。
在开始前，请确保环境满足以下条件：
@Tool 是 spring-ai-mcp-client-spring-boot-starter 提供的核心注解，用于标记可被 AI 调用的工具类或方法。通过该注解，框架会自动扫描并注册标记的组件，AI 模型可根据需求主动调用这些工具，执行具体业务逻辑（如数据库查询、API 调用、文件处理等）。
在 Spring Boot 项目的 pom.xml（Maven）或 build.gradle（Gradle）中引入 spring-ai-mcp-client-spring-boot-starter 依赖。
<dependencies>
<!-- spring-ai-mcp-client 核心依赖 -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
<version>1.0.0</version> <!-- 替换为最新版本 -->
</dependency>
<!-- Spring Boot Web 依赖（如需提供 HTTP 接口） -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- 参数校验依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
</dependencies>
dependencies {
// spring-ai-mcp-client 核心依赖
implementation 'org.springframework.ai:spring-ai-mcp-client-spring-boot-starter:1.0.0' // 替换为最新版本
// Spring Boot Web 依赖
implementation 'org.springframework.boot:spring-boot-starter-web'
// 参数校验依赖
implementation 'org.springframework.boot:spring-boot-starter-validation'
}
在 application.yml 或 application.properties 中配置 MCP（Model Control Plane）客户端参数，确保工具能与 AI 模型正常通信。
spring:
ai:
mcp:
client:
base-url: http://localhost:8080/mcp # MCP 服务地址
api-key: your-api-key # 访问 MCP 服务的 API 密钥（如有）
connect-timeout: 5000 # 连接超时时间（毫秒）
read-timeout: 10000 # 读取超时时间（毫秒）
tool:
scan-base-packages: com.example.ai.tool # Tool 注解扫描的基础包路径（必填）
@Tool 注解支持以下属性，用于定义工具的元数据信息：
| 属性名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| name | String | 否 | 工具名称，默认值为类名或方法名（首字母小写），建议手动指定唯一名称。 |
| description | String | 是 | 工具功能描述，需清晰说明工具用途（AI 会根据描述判断是否调用该工具）。 |
| parameters | @ToolParam[] | 否 | 工具参数列表，用于定义参数名称、类型、描述及是否必填（复杂参数时使用）。 |
当工具方法参数较多或需要详细说明时，可通过 @ToolParam 注解标记参数，属性如下：
| 属性名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| name | String | 是 | 参数名称（需与方法参数名一致）。 |
| description | String | 是 | 参数描述，帮助 AI 理解参数含义及传入格式。 |
| required | boolean | 否 | 是否为必填参数，默认值为 true。 |
将 @Tool 注解标记在类上，类中所有公共方法（public）会被自动识别为工具的子方法，适用于功能关联的一组工具（如订单相关工具：创建订单、查询订单、取消订单）。
示例：订单工具类
package com.example.ai.tool;
import org.springframework.ai.mcp.client.annotation.Tool;
import org.springframework.ai.mcp.client.annotation.ToolParam;
import org.springframework.validation.annotation.Validated;
// 类级别 Tool 注解，定义工具组名称和描述
@Tool(name = "orderTool", description = "订单相关操作工具，支持创建、查询、取消订单")
@Validated // 开启参数校验
public class OrderTool {
/**
* 创建订单
* @param orderId 订单ID（必填，格式：ORD-2024xxxx）
* @param amount 订单金额（必填，单位：元，需大于0）
* @param userId 用户ID（必填）
* @return 订单创建结果
*/
public String createOrder(
@ToolParam(name = "orderId", description = "订单ID，格式为 ORD-2024xxxx")
@NotBlank(message = "订单ID不能为空")
@Pattern(regexp = "ORD-d{8}", message = "订单ID格式错误，需符合 ORD-2024xxxx")
String orderId,
@ToolParam(name = "amount", description = "订单金额，单位：元，需大于0")
@DecimalMin(value = "0.01", message = "订单金额需大于0")
BigDecimal amount,
@ToolParam(name = "userId", description = "用户ID")
@NotBlank(message = "用户ID不能为空")
String userId
) {
// 业务逻辑：调用订单服务创建订单
return String.format("订单创建成功！订单ID：%s，用户ID：%s，金额：%.2f元", orderId, userId, amount);
}
/**
* 查询订单
* @param orderId 订单ID（必填）
* @return 订单详情
*/
public String queryOrder(
@ToolParam(name = "orderId", description = "要查询的订单ID")
@NotBlank(message = "订单ID不能为空")
String orderId
) {
// 业务逻辑：调用订单服务查询订单
return String.format("订单详情：订单ID：%s，状态：已支付，金额：99.00元，创建时间：2024-05-20 14:30:00", orderId);
}
}
将 @Tool 注解直接标记在方法上，每个方法对应一个独立工具，适用于功能单一的工具（如日期格式化、天气查询）。
示例：日期工具类
package com.example.ai.tool;
import org.springframework.ai.mcp.client.annotation.Tool;
import org.springframework.ai.mcp.client.annotation.ToolParam;
import org.springframework.stereotype.Component;
import org.springframework.validation.annotation.Validated;
import java.text.SimpleDateFormat;
import java.util.Date;
@Component // 需注入 Spring 容器
@Validated
public class DateTool {
/**
* 日期格式化工具
* @param date 原始日期（必填，格式：yyyy-MM-dd HH:mm:ss）
* @param pattern 目标格式（可选，默认：yyyy-MM-dd，支持 yyyy/MM/dd、MM-dd-yyyy 等）
* @return 格式化后的日期字符串
* @throws Exception 日期格式错误时抛出异常
*/
@Tool(
name = "dateFormatter",
description = "日期格式化工具，支持将原始日期转换为指定格式",
parameters = {
@ToolParam(name = "date", description = "原始日期，格式为 yyyy-MM-dd HH:mm:ss（必填）"),
@ToolParam(name = "pattern", description = "目标日期格式，默认 yyyy-MM-dd（可选）", required = false)
}
)
public String formatDate(
@NotBlank(message = "原始日期不能为空")
String date,
String pattern
) throws Exception {
// 默认格式
if (pattern == null || pattern.isEmpty()) {
pattern = "yyyy-MM-dd";
}
// 解析原始日期
SimpleDateFormat inputFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
Date parsedDate = inputFormat.parse(date);
// 格式化目标日期
SimpleDateFormat outputFormat = new SimpleDateFormat(pattern);
return outputFormat.format(parsedDate);
}
}
框架会自动扫描 application.yml 中 spring.ai.mcp.client.tool.scan-base-packages 配置的包路径下所有标记了 @Tool 的类或方法，并将其注册为可用工具。
spring-ai-mcp-client-spring-boot-starter 提供了 McpClient 接口，可用于手动调用已注册的工具（也可由 AI 自动触发调用）。
示例：在 Service 中调用订单工具
package com.example.ai.service;
import org.springframework.ai.mcp.client.McpClient;
import org.springframework.ai.mcp.client.model.ToolCallRequest;
import org.springframework.ai.mcp.client.model.ToolCallResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.HashMap;
import java.util.Map;
@Service
public class AiOrderService {
@Autowired
private McpClient mcpClient;
/**
* 调用订单工具创建订单
*/
public String createOrderByTool(String orderId, BigDecimal amount, String userId) {
// 1. 构建工具调用请求
Map<String, Object> parameters = new HashMap<>();
parameters.put("orderId", orderId);
parameters.put("amount", amount);
parameters.put("userId", userId);
ToolCallRequest request = ToolCallRequest.builder()
.toolName("orderTool") // 工具名称（与 @Tool(name) 一致）
.methodName("createOrder") // 方法名称（类级别 Tool 时需指定）
.parameters(parameters) // 工具参数
.build();
// 2. 调用工具
ToolCallResponse response = mcpClient.callTool(request);
// 3. 处理调用结果
if (response.isSuccess()) {
return "工具调用成功，结果：" + response.getResult();
} else {
return "工具调用失败，原因：" + response.getErrorMessage();
}
}
}
当集成 AI 模型（如 ChatGPT、通义千问）时，AI 会根据用户需求自动判断是否需要调用工具，并通过 MCP 客户端执行。开发者无需手动触发，只需确保工具已正确注册。
示例：AI 对话中自动调用日期工具
用户输入："把 2024-05-20 14:30:00 转换成 MM/dd/yyyy 格式"
AI 思考：用户需要日期格式化，需调用 dateFormatter 工具。
AI 调用：自动构建 ToolCallRequest（toolName=dateFormatter，parameters={date:"2024-05-20 14:30:00", pattern:"MM/dd/yyyy"}）
工具返回："05/20/2024"
AI 回复："转换后的日期格式为：05/20/2024"
通过本教程，开发者已掌握 spring-ai-mcp-client-spring-boot-starter 中 Tool 注解的核心使用方法，包括工具定义、配置、调用及问题排查。Tool 注解的设计简化了 AI 与本地服务的集成流程，开发者可基于此扩展更多场景：
如需进一步了解 spring-ai-mcp-client-spring-boot-starter 的其他功能，可参考官方文档：Spring AI 官方文档。
84.37M · 2025-10-04
97.24MB · 2025-10-04
132.36MB · 2025-10-04
