MCP 注释
Spring AI MCP Annotations 模块为 Java 中的 Model Context Protocol (MCP) 服务器和客户端提供基于注解的方法处理。它通过采用基于 Java 注解的简洁、声明式方法，简化了 MCP 服务器方法和客户端处理器的创建与注册。
The MCP Annotations enable developers to create and register MCP operation handlers using declarative annotations.
This approach simplifies implementing MCP server and client functionality by reducing boilerplate code and improving maintainability.
该库基于 MCP Java SDK 构建，提供了更高层次的、基于注解的编程模型，用于实现 MCP 服务器和客户端。
架构
MCP Annotations 模块由以下部分组成：
服务器注释
对于 MCP 服务器，提供以下注释：
@McpTool- 实现 MCP 工具，并支持自动生成 JSON schema@McpResource- 通过 URI 模板提供对资源的访问@McpPrompt- 生成提示消息@McpComplete- 提供自动补全功能
客户端注解
对于 MCP 客户端，提供了以下注释：
-
@McpLogging- 处理日志消息通知 -
@McpSampling- 处理采样请求 -
@McpElicitation- 处理用于收集额外信息的征询请求 -
@McpProgress- 处理长时间运行操作期间的进度通知 -
@McpToolListChanged- 处理工具列表变更通知 -
@McpResourceListChanged- 处理资源列表变更通知 -
@McpPromptListChanged- 处理提示词列表变更通知
特殊参数与注释
-
McpSyncRequestContext- 用于同步操作的特殊参数类型，提供统一的接口以访问 MCP 请求上下文，包括原始请求、服务器交换（用于有状态操作）、传输上下文（用于无状态操作），以及用于日志记录、进度、采样、提示和根访问的便捷方法。该参数会自动注入，并从 JSON schema 生成中排除。支持在 Complete、Prompt、Resource 和 Tool 方法中使用。 -
McpAsyncRequestContext- 用于异步操作的特殊参数类型，提供与McpSyncRequestContext相同的统一接口，但返回类型为响应式（基于 Mono）。该参数会自动注入，并从 JSON schema 生成中排除。支持在 Complete、Prompt、Resource 和 Tool 方法中使用。 -
McpTransportContext- 用于无状态操作的特殊参数类型，提供对传输级上下文的轻量级访问，而不具备完整的服务器交换功能。该参数会自动注入，并从 JSON schema 生成中排除 -
@McpProgressToken- 标记方法参数以接收请求中的进度令牌。该参数会自动注入，并从生成的 JSON schema 中排除。注意： 当使用McpSyncRequestContext或McpAsyncRequestContext时，可以通过ctx.request().progressToken()访问进度令牌，而无需使用此注解。 -
McpMeta- 一种特殊参数类型，提供对 MCP 请求、通知和结果中元数据的访问。该参数会自动注入，并排除在参数数量限制和 JSON schema 生成之外。注意： 当使用McpSyncRequestContext或McpAsyncRequestContext时，可以通过ctx.requestMeta()获取元数据。 -
MetaProvider- 一个接口，用于为工具、提示和资源声明提供_meta字段数据。通过@McpTool、@McpPrompt和@McpResource的metaProvider属性引用。
入门指南
依赖项
在您的项目 中添加 MCP 注解 依赖：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-annotations</artifactId>
</dependency>
在使用任何 MCP Boot Starter 时，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 Starters 时，默认会启用注解扫描。你可以使用以下属性来配置扫描行为：
客户端注解扫描器
spring:
ai:
mcp:
client:
annotation-scanner:
enabled: true # Enable/disable annotation scanning
服务器注解扫描器
spring:
ai:
mcp:
server:
annotation-scanner:
enabled: true # Enable/disable annotation scanning
快速示例
下面是一个使用 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 服务器或客户端中。
文档
其他资源
章节摘要
客户端注解
MCP 客户端注解提供了一种声明式的方式，用于使用 Java 注解实现 MCP 客户端处理器。这些注解简化了对服务器通知和客户端操作的处理。
服务器注释
MCP Server Annotations 提供了一种通过 Java 注解声明式实现 MCP 服务器功能的方式。这些注解简化了工具、资源、提示词和补全处理器的创建过程。
特殊参数
MCP Annotations 支持几种特殊的参数类型，可为被标注的方法提供额外的上下文和功能。这些参数由框架自动注入，并会从 JSON Schema 生成中排除。
MCP 注解示例
此页面提供了在 Spring AI 应用中结合使用 MCP 注释的详细示例。