Spring AI / Model Context Protocol (MCP) / MCP Server Boot Starters

Spring AI

参考文档

模型上下文协议 (MCP)

MCP 服务端启动器

模型上下文协议 (MCP) 服务端是能够通过标准化协议接口向 AI 应用程序暴露特定功能的程序。每个服务端都为特定领域提供聚焦的功能。

Spring AI MCP 服务端启动器为在 Spring Boot 应用中设置 MCP 服务端提供了自动配置。它们实现了 MCP 服务端功能与 Spring Boot 自动配置系统的无缝集成。

MCP 服务端启动器提供以下功能：

自动配置 MCP 服务端组件，包括工具（Tools）、资源（Resources）和提示（Prompts）
支持不同的 MCP 协议版本，包括 STDIO、SSE、Streamable-HTTP 和无状态（Stateless）服务端
支持同步和异步两种操作模式
多种传输层选项
灵活的工具、资源和提示规范
变更通知能力
基于注解的服务端开发，具备自动 Bean 扫描和注册功能

MCP 服务端启动器

MCP 服务端支持多种协议和传输机制。使用专用的启动器和正确的 spring.ai.mcp.server.protocol 属性来配置您的服务端：

STDIO

服务端类型	依赖	属性
标准输入/输出 (STDIO)	`spring-ai-starter-mcp-server`	`spring.ai.mcp.server.stdio=true`

WebMVC

服务端类型	依赖	属性
SSE WebMVC (自 2.0.0 版本起已弃用，请使用 STREAMABLE)	`spring-ai-starter-mcp-server-webmvc`	`spring.ai.mcp.server.protocol=SSE`
Streamable-HTTP WebMVC	`spring-ai-starter-mcp-server-webmvc`	`spring.ai.mcp.server.protocol=STREAMABLE`
无状态 WebMVC	`spring-ai-starter-mcp-server-webmvc`	`spring.ai.mcp.server.protocol=STATELESS`

WebFlux (响应式)

服务端类型	依赖	属性
SSE WebFlux (自 2.0.0 版本起已弃用，请使用 STREAMABLE)	`spring-ai-starter-mcp-server-webflux`	`spring.ai.mcp.server.protocol=SSE`
Streamable-HTTP WebFlux	`spring-ai-starter-mcp-server-webflux`	`spring.ai.mcp.server.protocol=STREAMABLE`
无状态 WebFlux	`spring-ai-starter-mcp-server-webflux`	`spring.ai.mcp.server.protocol=STATELESS`

服务端能力

根据服务端和传输类型的不同，MCP 服务端可以支持多种能力，例如：

工具 - 允许服务端向语言模型暴露可调用的工具
资源 - 为服务端向客户端暴露资源提供标准化方式
提示 - 为服务端向客户端暴露提示模板提供标准化方式
实用功能/补全 - 为服务端提供提示和资源 URI 的参数自动补全建议提供标准化方式
实用功能/日志 - 为服务端向客户端发送结构化日志消息提供标准化方式
实用功能/进度 - 通过通知消息为长时间运行的操作提供可选的进度跟踪
实用功能/Ping - 为服务端报告其状态提供可选的健康检查机制

所有能力默认启用。禁用某项能力将阻止服务端向客户端注册和暴露相应的功能。

服务端协议

MCP 提供了几种协议类型，包括：

STDIO - 进程内（例如，服务端在宿主应用内部运行）协议。通过标准输入和标准输出进行通信。设置 spring.ai.mcp.server.stdio=true 以启用 STDIO。
SSE - 用于实时更新的服务器发送事件协议。服务端作为一个独立进程运行，可以处理多个客户端连接。
Streamable-HTTP - Streamable HTTP 传输允许 MCP 服务端作为独立进程运行，使用 HTTP POST 和 GET 请求处理多个客户端连接，并可选择使用服务器发送事件 (SSE) 流式传输多个服务端消息。它取代了 SSE 传输。设置 spring.ai.mcp.server.protocol=STREAMABLE 以启用 STREAMABLE 协议。
无状态 - 无状态 MCP 服务端专为简化部署而设计，不在请求之间维护会话状态。它们非常适合微服务架构和云原生部署。设置 spring.ai.mcp.server.protocol=STATELESS 以启用 STATELESS 协议。

同步/异步服务端 API 选项

MCP 服务端 API 支持命令式（即同步）和响应式（例如异步）编程模型。

同步服务端 - 使用 McpSyncServer 实现的默认服务端类型。它专为应用中的简单请求-响应模式而设计。在您的配置中设置 spring.ai.mcp.server.type=SYNC 以启用此服务端类型。激活后，它会自动处理同步工具规范的配置。

注意：SYNC 服务端将仅注册同步的 MCP 注解方法。异步方法将被忽略。
异步服务端 - 异步服务端实现使用 McpAsyncServer，并针对非阻塞操作进行了优化。要启用此服务端类型，请配置您的应用程序 spring.ai.mcp.server.type=ASYNC。此服务端类型会自动设置带有 Project Reactor 支持的异步工具规范。

注意：ASYNC 服务端将仅注册异步的 MCP 注解方法。同步方法将被忽略。

MCP 服务端注解

MCP 服务端启动器为基于注解的服务端开发提供全面支持，允许您使用声明式 Java 注解而非手动配置来创建 MCP 服务端。

关键注解

@McpTool - 将方法标记为 MCP 工具，并支持自动生成 JSON 模式
@McpResource - 通过 URI 模板提供对资源的访问
@McpPrompt - 为 AI 交互生成提示消息
@McpComplete - 为提示提供自动补全功能

特殊参数

注解系统支持特殊的参数类型，这些类型提供额外的上下文：

McpMeta - 访问来自 MCP 请求的元数据
@McpProgressToken - 为长时间运行的操作接收进度令牌
McpSyncServerExchange / McpAsyncServerExchange - 用于高级操作的完整服务端上下文
McpTransportContext - 用于无状态操作的轻量级上下文
CallToolRequest - 为灵活工具提供动态模式支持

简单示例

java 复制代码

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

    @McpResource(uri = "config://{key}", name = "配置")
    public String getConfig(String key) {
        return configData.get(key);
    }
}

向 McpTransportContext 添加数据

默认情况下，McpTransportContext 是空的 (McpTransportContext.EMPTY)。这是设计使然，目的是保持 MCP 服务端的传输无关性。

如果您需要工具中的传输特定元数据（例如，HTTP 头、远程主机等），请在您的传输提供者上配置一个 TransportContextExtractor。

对于 WebMVC：

java 复制代码

@Bean
public WebMvcStreamableServerTransportProvider transport() {
    return WebMvcStreamableServerTransportProvider.builder()
        .contextExtractor(serverRequest -> {
            String authorization = serverRequest.headers().firstHeader("Authorization");
            return McpTransportContext.create(Map.of("authorization", authorization));
        })
        .build();
}

对于 WebFlux (响应式)：

java 复制代码

@Bean
public WebFluxStreamableServerTransportProvider transport() {
    return WebFluxStreamableServerTransportProvider.builder()
        .contextExtractor(serverRequest -> {
            String authorization = serverRequest.headers().firstHeader("Authorization");
            return McpTransportContext.create(Map.of("authorization", authorization));
        })
        .build();
}

配置完成后，可以在您的工具中通过 McpSyncRequestContext（或 McpAsyncRequestContext）访问此上下文。

java 复制代码

@McpTool
public String accessProtectedResource(McpSyncRequestContext requestContext) {
    McpTransportContext context = requestContext.transportContext();
    String authorization = (String) context.get("authorization");

    return "成功访问受保护资源。";
}

自动配置

借助 Spring Boot 自动配置，带注解的 Bean 会被自动检测并注册：

java 复制代码

@SpringBootApplication
public class McpServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }
}

自动配置将：

扫描带有 MCP 注解的 Bean
创建相应的规范
将它们注册到 MCP 服务端
根据配置处理同步和异步实现

配置属性

配置服务端注解扫描器：

yaml 复制代码

spring:
  ai:
    mcp:
      server:
        type: SYNC  # 或 ASYNC
        annotation-scanner:
          enabled: true

其他资源

服务端注解参考 - 服务端注解完整指南
特殊参数 - 高级参数注入
示例 - 综合示例和使用案例

示例应用程序

Weather Server (SSE WebFlux) - 使用 WebFlux 传输的 Spring AI MCP 服务端启动器
Weather Server (STDIO) - 使用 STDIO 传输的 Spring AI MCP 服务端启动器
Weather Server Manual Configuration - 不使用自动配置，而是使用 Java SDK 手动配置服务端的 Spring AI MCP 服务端启动器
Streamable-HTTP WebFlux/WebMVC 示例 - 待办
无状态 WebFlux/WebMVC 示例 - 待办

其他资源

MCP 服务端注解 - 使用注解进行声明式服务端开发
特殊参数 - 高级参数注入和上下文访问
MCP 注解示例 - 综合示例和使用案例
Spring AI 文档
模型上下文协议规范
Spring Boot 自动配置