Spring AI

参考
模型上下文协议 (MCP)
MCP 注解

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

MCP 注解使开发人员能够使用声明式注解来创建和注册 MCP 操作处理程序。这种方法通过减少样板代码并提高可维护性，简化了 MCP 服务器和客户端功能的实现。该库构建于 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() 获取元数据。
• 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 Starter 时，注解扫描默认启用。您可以使用以下属性配置扫描行为：

客户端注解扫描器

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 服务器或客户端。

文档

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

其他资源

• MCP 概述
• MCP Client Boot Starter
• MCP Server Boot Starter
• 模型上下文协议规范