76_Spring AI 干货笔记之 MCP 服务器注解 - 教程

一、MCP 服务器注解

MCP 服务器注解提供了一种使用 Java 注解来实现 MCP 服务器功能的声明式方法。这些注解简化了工具、资源、提示词和补全处理器的创建。

二、服务器注解

2.1 @McpTool

@McpTool 注解将一个方法标记为 MCP 工具实现，并自动生成 JSON 架构。

2.1.1 基本用法

@Component
public class CalculatorTools {

@McpTool(name = "add", description = "将两个数字相加")
public int add(
@McpToolParam(description = "第一个数字", required = true) int a,
@McpToolParam(description = "第二个数字", required = true) int b) {

return a + b;
}
}

2.1.2 高级功能

@McpTool(name = "calculate-area",
description = "计算矩形面积",
annotations = McpTool.McpAnnotations(
title = "矩形面积计算器",
readOnlyHint = true,
destructiveHint = false,
idempotentHint = true
))
public AreaResult calculateRectangleArea(
@McpToolParam(description = "宽度", required = true) double width,
@McpToolParam(description = "高度", required = true) double height) {

return new AreaResult(width * height, "平方单位");
}

2.1.3 使用请求上下文

工具可以访问请求上下文以进行高级操作：

@McpTool(name = "process-data", description = "使用请求上下文处理数据")
public String processData(
McpSyncRequestContext context,
@McpToolParam(description = "要处理的数据", required = true) String data) {

// 发送日志通知
context.info("正在处理数据: " + data);
// 发送进度通知（使用便捷方法）
context.progress(p -> p.progress(0.5).total(1.0).message("处理中..."));
// 向客户端发送 ping
context.ping();
return "已处理: " + data.toUpperCase();
}

2.1.4 动态架构支持

工具可以接受 CallToolRequest 以进行运行时架构处理：

@McpTool(name = "flexible-tool", description = "处理动态架构")
public CallToolResult processDynamic(CallToolRequest request) {

Map<String, Object> args = request.arguments();
  // 基于运行时架构进行处理
  String result = "动态处理了 " + args.size() + " 个参数";
  return CallToolResult.builder()
  .addTextContent(result)
  .build();
  }

2.1.5 进度跟踪

工具可以接收进度令牌来跟踪长时间运行的操作：

@McpTool(name = "long-task", description = "带有进度的长时间运行任务")
public String performLongTask(
McpSyncRequestContext context,
@McpToolParam(description = "任务名称", required = true) String taskName) {

// 从上下文中访问进度令牌
String progressToken = context.request().progressToken();
if (progressToken != null) {

context.progress(p -> p.progress(0.0).total(1.0).message("开始任务"));
// 执行工作...
context.progress(p -> p.progress(1.0).total(1.0).message("任务完成")