主题
MCP 注解
Spring AI MCP 注解模块为 Java 中的 Model Context Protocol (MCP) 服务端和客户端提供基于注解的方法处理。 它通过使用 Java 注解、简洁而声明式的方式，简化了 MCP 服务端方法与客户端处理器的创建和注册。
MCP 注解让开发者能用声明式注解创建并注册 MCP 操作处理器。 这种方法通过减少样板代码、提升可维护性，简化了 MCP 服务端与客户端功能的实现。
该库构建在 MCP Java SDK 之上，为实现 MCP 服务端与客户端提供一种更高层、基于注解的编程模型。
架构
MCP 注解模块由以下部分组成：
服务端注解
对于 MCP 服务端，提供了以下注解：
@McpTool- 实现带自动 JSON 模式生成的 MCP 工具@McpResource- 通过 URI 模板提供对资源的访问@McpPrompt- 生成提示词消息@McpComplete- 提供自动补全功能
客户端注解
对于 MCP 客户端，提供了以下注解：
@McpLogging- 处理日志消息通知@McpSampling- 处理采样请求@McpElicitation- 处理用于收集额外信息的引出（elicitation）请求@McpProgress- 处理长时间运行操作期间的进度通知@McpToolListChanged- 处理工具列表变更通知@McpResourceListChanged- 处理资源列表变更通知@McpPromptListChanged- 处理提示词列表变更通知
特殊参数与注解
McpSyncRequestContext- 用于同步操作的特殊参数类型，提供统一接口以访问 MCP 请求上下文，包括原始请求、服务端交换（用于有状态操作）、传输上下文（用于无状态操作），以及用于日志、进度、采样、引出和 roots 访问的便捷方法。该参数会被自动注入并从 JSON 模式生成中排除。在 Complete、Prompt、Resource 和 Tool 方法中受支持。McpAsyncRequestContext- 用于异步操作的特殊参数类型，提供与McpSyncRequestContext相同的统一接口，但采用响应式（基于 Mono）的返回类型。该参数会被自动注入并从 JSON 模式生成中排除。在 Complete、Prompt、Resource 和 Tool 方法中受支持。McpTransportContext- 用于无状态操作的特殊参数类型，提供对传输层上下文的轻量访问，而无需完整的服务端交换功能。该参数会被自动注入并从 JSON 模式生成中排除@McpProgressToken- 标记一个方法参数以接收来自请求的进度令牌。该参数会被自动注入并从所生成的 JSON 模式中排除。注意： 当使用McpSyncRequestContext或McpAsyncRequestContext时，进度令牌可通过ctx.request().progressToken()访问，而无需使用此注解。McpMeta- 提供对来自 MCP 请求、通知和结果的元数据访问的特殊参数类型。该参数会被自动注入并从参数数量限制与 JSON 模式生成中排除。注意： 当使用McpSyncRequestContext或McpAsyncRequestContext时，元数据可通过ctx.requestMeta()获取。MetaProvider- 为实现而提供的接口，用于为工具、提示词和资源声明供给_meta字段数据。通过@McpTool、@McpPrompt和@McpResource的metaProvider属性引用。
开始使用
依赖
将 MCP 注解依赖添加到你的项目：
xml
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-annotations</artifactId>
</dependency>当你使用任何 MCP Boot Starters 时，MCP 注解会被自动包含：
spring-ai-starter-mcp-clientspring-ai-starter-mcp-client-webfluxspring-ai-starter-mcp-serverspring-ai-starter-mcp-server-webfluxspring-ai-starter-mcp-server-webmvc
配置
使用 MCP Boot Starters 时，注解扫描默认启用。你可以使用以下属性配置扫描行为：
客户端注解扫描器
yaml
spring:
ai:
mcp:
client:
annotation-scanner:
enabled: true # Enable/disable annotation scanning服务端注解扫描器
yaml
spring:
ai:
mcp:
server:
annotation-scanner:
enabled: true # Enable/disable annotation scanning快速示例
下面是一个使用 MCP 注解创建计算器工具的简单示例：
java
@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;
}
}以及一个简单的、用于日志的客户端处理器：
java
@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 服务端或客户端。