Spring AI MCP 注解模块为 Java 中的模型上下文协议（MCP）服务端和客户端提供基于注解的方法处理能力。它通过简洁、声明式的 Java 注解方式，简化了 MCP 服务端方法和客户端处理器的创建与注册。
MCP 注解让开发者能够使用声明式注解创建并注册 MCP 操作处理器。
这种方式通过减少样板代码并提升可维护性，简化了 MCP 服务端和客户端功能的实现。
该库基于 MCP Java SDK 构建，为实现 MCP 服务端和客户端提供了更高级的、基于注解的编程模型。
架构
MCP 注解模块包含以下内容：
服务端注解
对于 MCP 服务端，提供以下注解：
@McpTool - 实现 MCP 工具，支持自动生成 JSON 模式
@McpResource - 通过 URI 模板提供资源访问能力
@McpPrompt - 生成提示消息
@McpComplete - 提供自动补全功能
客户端注解
对于 MCP 客户端，提供以下注解：
@McpLogging - 处理日志消息通知
@McpSampling - 处理采样请求
@McpElicitation - 处理用于收集额外信息的诱导请求
@McpProgress - 处理长时间运行操作的进度通知
@McpToolListChanged - 处理工具列表变更通知
@McpResourceListChanged - 处理资源列表变更通知
@McpPromptListChanged - 处理提示列表变更通知
特殊参数与注解
McpSyncRequestContext - 同步操作的专用参数类型，提供统一的接口用于访问 MCP 请求上下文，包括原始请求、服务端交换（用于有状态操作）、传输上下文（用于无状态操作），以及日志、进度、采样和诱导的便捷方法。该参数会自动注入，且不纳入 JSON 模式生成。支持在补全、提示、资源和工具方法中使用。
McpAsyncRequestContext - 异步操作的专用参数类型，提供与 McpSyncRequestContext 相同的统一接口，但返回类型为响应式（基于 Mono）。该参数会自动注入，且不纳入 JSON 模式生成。支持在补全、提示、资源和工具方法中使用。
McpTransportContext - 无状态操作的专用参数类型，提供轻量级的传输级上下文访问能力，无需完整的服务端交换功能。该参数会自动注入，且不纳入 JSON 模式生成。
@McpProgressToken - 标记方法参数以接收请求中的进度令牌。该参数会自动注入，且不纳入生成的 JSON 模式。注意：使用 McpSyncRequestContext 或 McpAsyncRequestContext 时，可通过 ctx.request().progressToken() 获取进度令牌，无需使用该注解。
McpMeta - 专用参数类型，提供对 MCP 请求、通知和结果中元数据的访问能力。该参数会自动注入，且不计入参数数量限制，不纳入 JSON 模式生成。注意：使用 McpSyncRequestContext 或 McpAsyncRequestContext 时，可通过 ctx.requestMeta() 获取元数据。
快速入门
依赖
将 MCP 注解依赖添加到你的项目中：
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-mcp-annotations</artifactId> </dependency>
当你使用任意 MCP Boot 启动器时，会自动包含 MCP 注解：
spring-ai-starter-mcp-client
spring-ai-starter-mcp-client-webflux
spring-ai-starter-mcp-server
spring-ai-starter-mcp-server-webflux
spring-ai-starter-mcp-server-webmvc
配置
使用 MCP Boot 启动器时，注解扫描默认启用。你可以通过以下属性配置扫描行为：
客户端注解扫描器
spring: ai: mcp: client: annotation-scanner: enabled: true # 启用/禁用注解扫描
服务端注解扫描器
spring: ai: mcp: server: annotation-scanner: enabled: true # 启用/禁用注解扫描
快速示例
以下是使用 MCP 注解创建计算器工具的简单示例：
@Component
public class CalculatorTools {
@McpTool(name = "add", description = "Add two numbers together")
public int add(
@McpToolParam(description = "First number", required = true) int a,
@McpToolParam(description = "Second number", required = true) int b) {
return a + b;
}
@McpTool(name = "multiply", description = "Multiply two numbers")
public double multiply(
@McpToolParam(description = "First number", required = true) double x,
@McpToolParam(description = "Second number", required = true) double y) {
return x * y;
}
}以及一个用于日志处理的简单客户端处理器：
@Component
public class LoggingHandler {
@McpLogging(clients = "my-server")
public void handleLoggingMessage(LoggingMessageNotification notification) {
System.out.println("Received log: " + notification.level() +
" - " + notification.data());
}
}通过 Spring Boot 自动配置，这些带注解的 Bean 会被自动检测并注册到 MCP 服务端或客户端中。
