MCP 注解

Spring AI MCP 注解模块为模型上下文协议 (MCP) 服务器和客户端在 Java 中提供了基于注解的方法处理。它通过使用 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 注解模块包括：

服务器注解

对于 MCP 服务器，提供了以下注解：

@McpTool - 实现 MCP 工具并自动生成 JSON 模式
@McpResource - 通过 URI 模板提供对资源的访问
@McpPrompt - 生成提示消息
@McpComplete - 提供自动补全功能

客户端注解

对于 MCP 客户端，提供了以下注解：

@McpLogging - 处理日志消息通知
@McpSampling - 处理采样请求
@McpElicitation - 处理用于收集额外信息的启发式请求
@McpProgress - 处理长时间运行操作期间的进度通知
@McpToolListChanged - 处理工具列表更改通知
@McpResourceListChanged - 处理资源列表更改通知
@McpPromptListChanged - 处理提示列表更改通知

特殊参数和注解

McpSyncRequestContext - 用于同步操作的特殊参数类型，提供一个统一接口来访问 MCP 请求上下文，包括原始请求、服务器交换（用于有状态操作）、传输上下文（用于无状态操作），以及用于日志记录、进度、采样和启发式方法的便捷方法。此参数会自动注入并排除在 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() 获取元数据。

入门

依赖关系

将 MCP 注解依赖项添加到您的项目

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-annotations</artifactId>
</dependency>

当您使用任何 MCP Boot Starters 时，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 服务器或客户端。

文档

客户端注解 - 客户端注解的详细指南
服务器注解 - 服务器端注解的详细指南
特殊参数 - 特殊参数类型的指南
示例 - 综合示例和用例