Lzh on GitHub

MCP 注解

Spring AI MCP 注解模块为 Java 中的 模型上下文协议（MCP） 服务器和客户端提供基于注解的方法处理。它通过使用 Java 注解的清晰声明式方式，简化了 MCP 服务器方法和客户端处理器的创建与注册。

Spring AI MCP 注解模块为 Java 中的 模型上下文协议（MCP） 服务器和客户端提供基于注解的方法处理。它通过使用 Java 注解的清晰声明式方式，简化了 MCP 服务器方法和客户端处理器的创建与注册。

MCP 注解使开发者能够使用声明式注解创建和注册 MCP 操作处理器。 这种方法通过减少样板代码、提升可维护性，从而简化了 MCP 服务器和客户端功能的实现。

该库构建于 MCP Java SDK 之上，为实现 MCP 服务器和客户端提供了更高级别的、基于注解的编程模型。

架构

MCP 注解模块包括以下内容：

服务器注解

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

  • @McpTool — 实现 MCP 工具，并自动生成 JSON 模式
  • @McpResource — 通过 URI 模板访问资源
  • @McpPrompt — 生成提示（prompt）消息
  • @McpComplete — 提供自动补全功能

客户端注解

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

  • @McpLogging — 处理日志消息通知
  • @McpSampling — 处理采样请求
  • @McpElicitation — 处理引导请求，用于收集附加信息
  • @McpProgress — 在长时间运行操作中处理进度通知
  • @McpToolListChanged — 处理工具列表变更通知
  • @McpResourceListChanged — 处理资源列表变更通知
  • @McpPromptListChanged — 处理提示（prompt）列表变更通知

特殊参数与注解

  • McpSyncRequestContext — 用于同步操作的特殊参数类型，提供统一接口以访问 MCP 请求上下文，包括原始请求、服务器交换对象（针对有状态操作）、传输上下文（针对无状态操作），以及便捷的方法用于日志记录、进度、采样和引导（elicitation）。该参数会被自动注入，并且不会出现在 JSON Schema 中。在 Complete、Prompt、Resource 和 Tool 方法中受支持。
  • McpAsyncRequestContext — 用于异步操作的特殊参数类型，提供与 McpSyncRequestContext 相同的统一接口，但返回类型为反应式（基于 Mono）。该参数会被自动注入，并且不会出现在 JSON Schema 中。在 Complete、Prompt、Resource 和 Tool 方法中受支持。
  • McpTransportContext — 用于无状态操作的特殊参数类型，提供对传输层上下文的轻量访问，不包含完整的服务器交换功能。该参数会被自动注入，并且不会出现在 JSON Schema 中。
  • @McpProgressToken — 用于标记方法参数，以接收请求中的进度令牌（progress token）。该参数会被自动注入，并且不会出现在生成的 JSON Schema 中。注意：在使用 McpSyncRequestContext 或 McpAsyncRequestContext 时，可通过 ctx.request().progressToken() 访问进度令牌，而无需使用此注解。
  • McpMeta — 特殊参数类型，用于访问 MCP 请求、通知和结果中的元数据。该参数会被自动注入，不计入参数数量限制，也不会出现在 JSON Schema 中。注意：在使用 McpSyncRequestContext 或 McpAsyncRequestContext 时，可通过 ctx.requestMeta() 获取元数据。

入门指南

依赖项

将 MCP Annotations 依赖添加到项目中：

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

当使用任何 MCP Boot Starter 时，MCP Annotations 会被自动包含：

  • 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  # 启用/禁用注解扫描

服务端注解扫描器：

spring:
  ai:
    mcp:
      server:
        annotation-scanner:
          enabled: true  # 启用/禁用注解扫描

快速示例

下面是使用 MCP 注解创建一个计算器工具的简单示例：

@Component
public class CalculatorTools {

    @McpTool(name = "add", description = "将两个数字相加")
    public int add(
            @McpToolParam(description = "第一个数字", required = true) int a,
            @McpToolParam(description = "第二个数字", required = true) int b) {
        return a + b;
    }

    @McpTool(name = "multiply", description = "将两个数字相乘")
    public double multiply(
            @McpToolParam(description = "第一个数字", required = true) double x,
            @McpToolParam(description = "第二个数字", required = true) double y) {
        return x * y;
    }
}

以及一个用于日志的简单客户端处理器：

@Component
public class LoggingHandler {

    @McpLogging(clients = "my-server")
    public void handleLoggingMessage(LoggingMessageNotification notification) {
        System.out.println("收到日志: " + notification.level() +
                          " - " + notification.data());
    }
}

通过 Spring Boot 的自动配置，这些带注解的 Bean 会被自动检测并注册到 MCP 服务器或客户端。

文档

附加资源