此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！spring-doc.cadn.net.cn

MCP 注解

Spring AI MCP 注解模块为 Java 中的 模型上下文协议 (MCP) 服务器和客户端提供基于注解的方法处理。 它通过一种简洁、声明式的 Java 注解方式，简化了 MCP 服务器方法和客户端处理程序的创建与注册。spring-doc.cadn.net.cn

 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 服务器和客户端提供更高级的、基于注解的编程模型。spring-doc.cadn.net.cn

架构

MCP 注解模块包含：spring-doc.cadn.net.cn

服务器注解

对于 MCP 服务器，提供了以下注解：spring-doc.cadn.net.cn

客户端注解

对于 MCP 客户端，提供了以下注解：spring-doc.cadn.net.cn

特殊参数和注解

  • McpSyncRequestContext - 用于同步操作的特殊参数类型，提供统一的接口来访问 MCP 请求上下文，包括原始请求、服务器交换（用于有状态操作）、传输上下文（用于无状态操作），以及用于日志记录、进度、采样、诱导和根访问的便捷方法。此参数会自动注入，并从 JSON 模式生成中排除。在 Complete、Prompt、Resource 和 Tool 方法中受支持。spring-doc.cadn.net.cn

  • McpAsyncRequestContext - 用于异步操作的特殊参数类型，提供与 McpSyncRequestContext 相同的统一接口，但使用响应式（基于 Mono）的返回类型。该参数会自动注入，并从 JSON 模式生成中排除。在 Complete、Prompt、Resource 和 Tool 方法中受支持。spring-doc.cadn.net.cn

  • McpTransportContext - 用于无状态操作的特殊参数类型，提供对传输级上下文的轻量级访问，而不具备完整的服务器交换功能。该参数会自动注入，并从JSON模式生成中排除spring-doc.cadn.net.cn

  • @McpProgressToken - 标记一个方法参数以接收请求中的进度Tokens。该参数会自动注入，并且不会包含在生成的 JSON 模式中。注意： 当使用 McpSyncRequestContext 或 McpAsyncRequestContext 时，可以通过 ctx.request().progressToken() 访问进度Tokens，而无需使用此注解。spring-doc.cadn.net.cn

  • McpMeta - 一种特殊的参数类型，提供对来自 MCP 请求、通知和结果的元数据的访问。该参数会自动注入，并且不计入参数计数限制和 JSON 模式生成中。注意：当使用 McpSyncRequestContext 或 McpAsyncRequestContext 时，可以通过 ctx.requestMeta() 获取元数据。spring-doc.cadn.net.cn

  • MetaProvider - 实现的接口，用于为工具、提示和资源声明提供 _meta 字段数据。通过 @McpTool、@McpPrompt 和 @McpResource 的 metaProvider 属性引用。spring-doc.cadn.net.cn

快速开始

依赖项

将 MCP 注解依赖项添加到您的项目中：spring-doc.cadn.net.cn

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

当您使用任何 MCP Boot Starters 时，MCP 注解会自动包含在内：spring-doc.cadn.net.cn

配置

在使用 MCP Boot Starters 时，默认启用注解扫描。您可以使用以下属性配置扫描行为：spring-doc.cadn.net.cn

客户端注解扫描器

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 注解创建计算器工具的简单示例：spring-doc.cadn.net.cn

@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;
    }
}

以及一个用于日志记录的简单客户端处理器：spring-doc.cadn.net.cn

@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 服务器或客户端。spring-doc.cadn.net.cn

文档

附加资源