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、提示、资源和工具方法。spring-doc.cadn.net.cn

  • McpAsync请求上下文- 异步作的特殊参数类型，提供与McpSyncRequestContext但采用响应式（基于单声道）的返回类型。该参数会自动注入并排除在 JSON 模式生成中。支持Complete、提示、资源和工具方法。spring-doc.cadn.net.cn

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

  • @McpProgressToken- 标记方法参数以接收请求的进度Tokens。该参数会自动注入并排除在生成的 JSON 模式中。注意：使用McpSyncRequestContext或McpAsync请求上下文进度Tokens可以通过以下方式访问ctx.request（）.progressToken（）而不是使用这个注释。spring-doc.cadn.net.cn

  • McpMeta- 特殊参数类型，可访问MCP请求、通知和结果的元数据。该参数会自动注入并排除在参数数量限制和 JSON 模式生成之外。注意：使用McpSyncRequestContext或McpAsync请求上下文，元数据可以通过以下方式获得ctx.requestMeta（）相反。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启动启动程序时，MCP注释会自动包含：spring-doc.cadn.net.cn

配置

使用 MCP 启动启动程序时，标注扫描默认是启用的。您可以使用以下属性配置扫描行为：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 自动配置，这些注释豆会自动被检测并注册给 MCP 服务器或客户端。spring-doc.cadn.net.cn

文档

附加资源