Spring AI MCP Server Starter：快速构建MCP服务器

malog_

982人浏览 · 2025-12-19 10:24:51

malog_ · 2025-12-19 10:24:51 发布

Spring AI MCP Server Starter 是为 Spring Boot 应用提供 MCP（模型上下文协议）服务器自动配置 的组件，核心支持 SYNC（默认）/ASYNC 两种服务器类型，提供 STDIO、WebMVC SSE、WebFlux SSE 三种传输协议选项，内置 工具、资源、提示词、补全 四大可按需启用的核心功能，支持变更通知、上下文传递（ToolContext）、自动注册 Spring Bean 规范等特性，能无缝集成 Spring AI 工具框架，快速实现 MCP 服务器搭建与客户端交互。

一、核心定位与整体功能

Spring AI MCP Server Starter 旨在为 Spring Boot 应用简化 MCP（模型上下文协议）服务器的搭建，提供以下核心能力：

自动配置：自动初始化 MCP 服务器组件，无需手动整合核心模块
双模式支持：同步（SYNC，默认）与异步（ASYNC）服务器类型，适配不同应用架构
多传输选项：支持 STDIO、WebMVC SSE、WebFlux SSE 三种传输协议，覆盖本地与远程交互场景
功能可配置：工具、资源、提示词、补全四大功能可独立启用 / 禁用
变更通知：支持工具、资源、提示词变更后的客户端通知
生态集成：无缝对接 Spring AI 工具框架，自动转换 Spring Bean 为 MCP 规范

二、Starter 类型与依赖配置

Starter 类型	依赖坐标	核心传输协议	关键特性
标准 MCP Server	`org.springframework.ai:spring-ai-mcp-server-spring-boot-starter`	STDIO	适用于命令行 / 桌面工具，无需 Web 依赖，激活`McpServerAutoConfiguration`
WebMVC Server	`org.springframework.ai:spring-ai-starter-mcp-server-webmvc`	WebMVC SSE（HTTP）	支持可选 STDIO 传输，激活`McpWebMvcServerAutoConfiguration` ，含`spring-boot-starter-web` 依赖
WebFlux Server	`org.springframework.ai:spring-ai-starter-mcp-server-webflux`	WebFlux SSE（响应式）	支持可选 STDIO 传输，激活`McpWebFluxServerAutoConfiguration` ，含`spring-boot-starter-webflux` 依赖

三、核心配置属性（前缀：`spring.ai.mcp.server`）

属性分类	属性名	说明	默认值
基础配置	`enabled`	启用 / 禁用 MCP 服务器	`true`
	`name`	服务器标识名称	`mcp-server`
	`version`	服务器版本	`1.0.0`
	`type`	服务器类型（SYNC/ASYNC）	`SYNC`
	`instructions`	客户端交互指导说明	`null`
功能开关	`capabilities.tool`	启用 / 禁用工具功能	`true`
	`capabilities.resource`	启用 / 禁用资源功能	`true`
	`capabilities.prompt`	启用 / 禁用提示词功能	`true`
	`capabilities.completion`	启用 / 禁用补全功能	`true`
传输配置	`stdio`	启用 STDIO 传输（仅 WebMVC/WebFlux Starter 支持）	`false`
	`sse-endpoint`	SSE 端点路径（Web 传输）	`/sse`
	`sse-message-endpoint`	客户端消息发送 SSE 端点（Web 传输）	`/mcp/message`
	`base-url`	URL 前缀（拼接端点路径）	-
超时与通知	`request-timeout`	服务器响应超时时间	`20秒`
	`tool-change-notification`	启用工具变更通知	`true`
	`resource-change-notification`	启用资源变更通知	`true`
	`prompt-change-notification`	启用提示词变更通知	`true`
工具响应配置	`tool-response-mime-type`	工具响应 MIME 类型（如 generateImage=image/png）	-

四、服务器类型（双模式特性）

1. 同步服务器（SYNC）

实现类：McpSyncServer
适配场景：简单请求 - 响应模式，传统阻塞式应用
配置方式：spring.ai.mcp.server.type=SYNC（默认）
特性：自动处理同步工具、资源等规范配置

2. 异步服务器（ASYNC）

实现类：McpAsyncServer
适配场景：非阻塞操作，响应式应用（如 WebFlux）
配置方式：spring.ai.mcp.server.type=ASYNC
特性：内置 Project Reactor 支持，自动转换为异步规范

五、四大核心功能详解

1. 工具功能

核心作用：向客户端暴露可调用工具，支持 Spring AI 工具自动转换
注册方式：通过 Spring Bean 自动注册，支持三类组件：

- 独立ToolCallback Bean
- ToolCallback Bean 列表
- ToolCallbackProvider Bean（推荐，示例：MethodToolCallbackProvider）

关键特性：

- 工具按名称去重，保留首次出现实例
- 支持ToolContext，可通过McpToolUtils.getMcpExchange(toolContext)获取上下文
- 支持工具变更通知（默认启用）

2. 资源管理功能

核心作用：标准化暴露静态 / 动态资源
关键特性：

- 支持资源模板与变更通知（默认启用）
- 同步 / 异步资源规范自动转换

注册方式：通过McpServerFeatures.SyncResourceSpecification/AsyncResourceSpecification Bean 注册

3. 提示词管理功能

核心作用：暴露提示词模板，支持个性化交互
关键特性：

- 支持模板版本控制与变更通知（默认启用）
- 同步 / 异步提示词规范自动转换

注册方式：通过McpServerFeatures.SyncPromptSpecification/AsyncPromptSpecification Bean 注册

4. 补全管理功能

核心作用：提供代码补全、内容补全等功能
关键特性：支持同步 / 异步补全规范
注册方式：通过McpServerFeatures.SyncCompletionSpecification/AsyncCompletionSpecification Bean 注册

六、传输协议对比

传输协议	适用场景	依赖 Starter	核心优势
STDIO	命令行工具、桌面应用、本地交互	所有 Starter（标准 Starter 默认启用）	配置简单，无需 Web 服务器
WebMVC SSE	远程同步交互、传统 Web 应用	WebMVC Server Starter	基于 HTTP，适配 Spring MVC 架构
WebFlux SSE	远程非阻塞交互、响应式应用	WebFlux Server Starter	高并发支持，生产环境推荐

七、使用示例

1. 配置示例（YAML）

标准 STDIO 服务器：

spring:
  ai:
    mcp:
      server:
        name: stdio-mcp-server
        version: 1.0.0
        type: SYNC

WebFlux 服务器（响应式）：

spring:
  ai:
    mcp:
      server:
        name: webflux-mcp-server
        version: 1.0.0
        type: ASYNC
        instructions: "提供天气查询工具"
        sse-message-endpoint: /mcp/messages

2. 代码示例（暴露工具）

// 1. 工具服务类
@Service
public class WeatherService {
    @Tool(description = "根据城市名查询天气")
    public String getWeather(String cityName) {
        // 业务实现：调用天气API获取数据
        return "北京：晴，25℃";
    }
}

// 2. 注册工具回调
@SpringBootApplication
public class McpServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

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