一、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("任务完成")