Spring AI 1.x 系列【43】基于标准输入输出 (STDIO) 与服务端推送事件 (SSE) 的 MCP 服务端

1. 概述

STDIO 和 SSE MCP 服务端支持多种传输机制，每种机制对应专用的启动器。使用 STDIO 客户端或 SSE 客户端即可连接对应的服务端。

2. 启动器类型

2.1 STDIO MCP Server

完整的 MCP 服务端功能，基于 STDIO 传输。

xml 复制代码

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

特点：

适用于命令行和桌面工具
无需额外的 Web 依赖
支持基础服务端组件配置
支持工具、资源、提示词声明处理
支持服务端能力管理与变更通知
同时支持同步(SYNC)和异步(ASYNC)实现

2.2 SSE WebMVC Server

完整的 MCP 服务端功能，基于 Spring MVC 的 SSE（Server-Sent Events）传输，可选配 STDIO 传输。

xml 复制代码

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

特点：

基于 Spring MVC 的 HTTP 传输（WebMvcSseServerTransportProvider）
自动配置 SSE 端点
可选 STDIO 传输（设置 spring.ai.mcp.server.stdio=true 启用）
包含 spring-boot-starter-web 和 mcp-spring-webmvc 依赖

2.3 SSE WebFlux Server

完整的 MCP 服务端功能，基于 Spring WebFlux 的 SSE 传输，可选配 STDIO 传输。

xml 复制代码

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

该启动器激活 McpWebFluxServerAutoConfiguration 和 McpServerAutoConfiguration 自动配置，提供：

基于 Spring WebFlux 的响应式传输（WebFluxSseServerTransportProvider）
自动配置响应式 SSE 端点
可选 STDIO 传输（设置 spring.ai.mcp.server.stdio=true 启用）
包含 spring-boot-starter-webflux 和 mcp-spring-webflux 依赖

注意： 根据 Spring Boot 默认行为，当 classpath 上同时存在 org.springframework.web.servlet.DispatcherServlet 和 org.springframework.web.reactive.DispatcherHandler 时，Spring Boot 会优先使用 DispatcherServlet。因此，如果你的项目使用了 spring-boot-starter-web，建议使用 spring-ai-starter-mcp-server-webmvc 而非 WebFlux 版本。

3. 配置项说明

3.1 通用配置

配置前缀：spring.ai.mcp.server

配置项	说明	默认值
enabled	开启/关闭 MCP 服务端	true
tool-callback-converter	开启/关闭 Spring AI ToolCallback 到 MCP Tool 声明的自动转换	true
stdio	开启/关闭 STDIO 传输	false
name	服务端标识名称	mcp-server
version	服务端版本	1.0.0
instructions	可选的服务使用指引，用于告知客户端如何与此服务端交互	null
type	服务端类型：SYNC(同步) / ASYNC(异步)	SYNC
capabilities.resource	开启/关闭资源能力	true
capabilities.tool	开启/关闭工具能力	true
capabilities.prompt	开启/关闭提示词能力	true
capabilities.completion	开启/关闭补全能力	true
resource-change-notification	开启资源变更通知	true
prompt-change-notification	开启提示词变更通知	true
tool-change-notification	开启工具变更通知	true
tool-response-mime-type	按工具名配置响应 MIME 类型。例如 `spring.ai.mcp.server.tool-response-mime-type.generateImage=image/png` 将 `image/png` 与 `generateImage()` 工具关联	-
request-timeout	请求超时时间，适用于工具调用、资源访问、提示词操作等所有客户端请求	20s

3.2 MCP 注解配置

MCP 服务端注解提供了一种声明式方式，使用 Java 注解来实现 MCP 服务端处理器。

配置前缀：spring.ai.mcp.server.annotation-scanner

配置项	说明	默认值
enabled	开启/关闭 MCP 服务端注解自动扫描	true

3.3 SSE 配置

配置前缀：spring.ai.mcp.server

出于向后兼容考虑，SSE 属性没有额外的后缀（如 .sse）。

配置项	说明	默认值
sse-message-endpoint	自定义 SSE 消息端点路径，供客户端发送消息	/mcp/message
sse-endpoint	自定义 SSE 端点路径	/sse
base-url	可选的 URL 前缀。例如 `base-url=/api/v1` 表示客户端应访问 `/api/v1` + `sse-endpoint`，消息端点为 `/api/v1` + `sse-message-endpoint`	-
keep-alive-interval	连接保活间隔	null（禁用）

4. 功能与能力

MCP Server Boot Starter 允许服务端向客户端暴露工具、资源、提示词，并自动将注册为 Spring Bean 的自定义能力处理器转换为对应的同步/异步声明。

4.1 工具（Tools）

允许服务端暴露可供语言模型调用的工具。提供以下特性：

变更通知支持
Spring AI 工具根据服务端类型自动转换为同步/异步声明
通过 Spring Bean 自动注册工具声明

高级 API 注册方式：

java 复制代码

@Bean
public ToolCallbackProvider myTools(...) {
    List<ToolCallback> tools = ...
    return ToolCallbackProvider.from(tools);
}

底层 API 注册方式：

java 复制代码

@Bean
public List<McpServerFeatures.SyncToolSpecification> myTools(...) {
    List<McpServerFeatures.SyncToolSpecification> tools = ...
    return tools;
}

自动配置会检测并注册以下来源的所有工具回调：

单个 ToolCallback Bean
ToolCallback 列表 Bean
ToolCallbackProvider Bean

工具按名称去重，重名工具以首次出现的为准。设置 tool-callback-converter=false 可禁用自动检测与注册。

4.1.1 工具上下文支持

支持 ToolContext，可将上下文信息传递给工具调用。上下文在 exchange 键下包含一个 McpSyncServerExchange 实例，可通过 McpToolUtils.getMcpExchange(toolContext) 访问，用于调用 exchange.loggingNotification(...) 和 exchange.createMessage(...) 等方法。

4.2 资源（Resources）

以标准化方式向客户端暴露资源。提供以下特性：

静态和动态资源声明
可选的变更通知
资源模板支持
同步/异步资源声明自动转换

注册方式：

java 复制代码

@Bean
public List<McpServerFeatures.SyncResourceSpecification> myResources(...) {
    var systemInfoResource = new McpSchema.Resource(...);
    var resourceSpecification = new McpServerFeatures.SyncResourceSpecification(
        systemInfoResource,
        (exchange, request) -> {
            try {
                var systemInfo = Map.of(...);
                String jsonContent = new ObjectMapper().writeValueAsString(systemInfo);
                return new McpSchema.ReadResourceResult(
                    List.of(new McpSchema.TextResourceContents(
                        request.uri(), "application/json", jsonContent)));
            } catch (Exception e) {
                throw new RuntimeException("Failed to generate system info", e);
            }
        }
    );
    return List.of(resourceSpecification);
}

4.3 提示词（Prompts）

以标准化方式向客户端暴露提示词模板。提供以下特性：

变更通知支持
模板版本管理
同步/异步提示词声明自动转换

注册方式：

java 复制代码

@Bean
public List<McpServerFeatures.SyncPromptSpecification> myPrompts() {
    var prompt = new McpSchema.Prompt("greeting", "A friendly greeting prompt",
        List.of(new McpSchema.PromptArgument("name", "The name to greet", true)));

    var promptSpecification = new McpServerFeatures.SyncPromptSpecification(
        prompt,
        (exchange, getPromptRequest) -> {
            String nameArgument = (String) getPromptRequest.arguments().get("name");
            if (nameArgument == null) { nameArgument = "friend"; }
            var userMessage = new PromptMessage(Role.USER,
                new TextContent("Hello " + nameArgument + "! How can I assist you today?"));
            return new GetPromptResult("A personalized greeting message", List.of(userMessage));
        }
    );
    return List.of(promptSpecification);
}

4.4 补全（Completions）

以标准化方式向客户端暴露自动补全能力。支持同步和异步补全声明。

注册方式：

java 复制代码

@Bean
public List<McpServerFeatures.SyncCompletionSpecification> myCompletions() {
    var completion = new McpServerFeatures.SyncCompletionSpecification(
        new McpSchema.PromptReference("ref/prompt", "code-completion",
            "Provides code completion suggestions"),
        (exchange, request) -> {
            return new McpSchema.CompleteResult(
                List.of("python", "pytorch", "pyside"), 10, true);
        }
    );
    return List.of(completion);
}

4.5 日志（Logging）

以标准化方式向客户端发送结构化日志消息。在工具、资源、提示词或补全的调用处理器中，使用 McpSyncServerExchange / McpAsyncServerExchange 对象发送日志：

java 复制代码

(exchange, request) -> {
    exchange.loggingNotification(LoggingMessageNotification.builder()
        .level(LoggingLevel.INFO)
        .logger("test-logger")
        .data("This is a test log message")
        .build());
}

客户端侧可注册日志消费者来处理这些消息：

java 复制代码

mcpClientSpec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
    // 处理日志消息
});

4.6 进度（Progress）

以标准化方式向客户端发送进度更新。在工具、资源、提示词或补全的调用处理器中，使用 McpSyncServerExchange / McpAsyncServerExchange 对象发送进度通知：

java 复制代码

(exchange, request) -> {
    exchange.progressNotification(ProgressNotification.builder()
        .progressToken("test-progress-token")
        .progress(0.25)
        .total(1.0)
        .message("tool call in progress")
        .build());
}

客户端可注册进度消费者来更新 UI：

java 复制代码

mcpClientSpec.progressConsumer((McpSchema.ProgressNotification progress) -> {
    // 处理进度通知
});

4.7 根路径变更（Root List Changes）

当根路径发生变化时，支持 listChanged 的客户端会发送根路径变更通知。

支持监控根路径变化
自动转换为异步消费者以适配响应式应用
通过 Spring Bean 可选注册

java 复制代码

@Bean
public BiConsumer<McpSyncServerExchange, List<McpSchema.Root>> rootsChangeHandler() {
    return (exchange, roots) -> {
        logger.info("Registering root resources: {}", roots);
    };
}

4.8 心跳（Ping）

服务端用于验证客户端是否仍在线的机制。在工具、资源、提示词或补全的调用处理器中，使用 McpSyncServerExchange / McpAsyncServerExchange 发送心跳：

java 复制代码

(exchange, request) -> {
    exchange.ping();
}

4.9 保活（Keep Alive）

服务端可定期向已连接的客户端发送心跳以验证连接健康状态。默认禁用，通过以下配置启用：

yaml 复制代码

spring:
  ai:
    mcp:
      server:
        keep-alive-interval: 30s

5. 使用示例

5.1 STDIO 服务端配置

yaml 复制代码

# 使用 spring-ai-starter-mcp-server
spring:
  ai:
    mcp:
      server:
        name: stdio-mcp-server
        version: 1.0.0
        type: SYNC

5.2 WebMVC 服务端配置

yaml 复制代码

# 使用 spring-ai-starter-mcp-server-webmvc
spring:
  ai:
    mcp:
      server:
        name: webmvc-mcp-server
        version: 1.0.0
        type: SYNC
        instructions: "This server provides weather information tools and resources"
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
        sse-message-endpoint: /mcp/messages
        keep-alive-interval: 30s

5.3 WebFlux 服务端配置

yaml 复制代码

# 使用 spring-ai-starter-mcp-server-webflux
spring:
  ai:
    mcp:
      server:
        name: webflux-mcp-server
        version: 1.0.0
        type: ASYNC  # 响应式应用推荐使用 ASYNC
        instructions: "This reactive server provides weather information tools and resources"
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
        sse-message-endpoint: /mcp/messages
        keep-alive-interval: 30s

5.4 创建 MCP 服务端应用

java 复制代码

@Service
public class WeatherService {

    @Tool(description = "根据城市名称获取天气信息")
    public String getWeather(String cityName) {
        // 实现逻辑
    }
}

@SpringBootApplication
public class McpServerApplication {

    private static final Logger logger = LoggerFactory.getLogger(McpServerApplication.class);

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

    @Bean
    public ToolCallbackProvider weatherTools(WeatherService weatherService) {
        return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
    }
}

自动配置会将工具回调自动注册为 MCP 工具。你可以有多个生成 ToolCallbacks 的 Bean，自动配置会自动合并它们。