|
最新快照版本请使用Spring AI 1.1.0! |
MCP 服务器启动启动程序
Spring AI MCP(模型上下文协议)服务器启动Starters为在 Spring Boot 应用中设置 MCP 服务器提供了自动配置。它实现了MCP服务器功能与Spring Boot自动配置系统的无缝集成。
MCP 服务器启动Starters提供:
-
MCP服务器组件的自动配置
-
支持同步和异步作模式
-
多传输层选项
-
灵活的工具、资源和提示说明
-
更改通知功能
首先
|
春季AI自动配置、起始模块的工件名称发生了重大变化。 更多信息请参阅升级说明。 |
根据你的交通需求,选择以下起始者之一:
标准MCP服务器
完整的 MCP 服务器功能支持STDIO服务器运输。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>
-
适用于命令行和桌面工具
-
无需额外的网络依赖
Starters会激活McpServerAutoConfiguration自动配置负责:
-
配置基础服务器组件
-
处理工具、资源和提示符规范
-
管理服务器能力和变更通知
-
同时提供同步和异步服务器实现
WebMVC 服务器传输
完整的 MCP 服务器功能支持SSE(服务器发送事件)基于 Spring MVC 的服务器传输,并可选STDIO运输。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>
Starters会激活McpWebMvcServerAutoConfiguration和McpServerAutoConfiguration自动配置以提供:
-
基于HTTP的Spring MVC传输(
WebMvcSseServerTransportProvider) -
自动配置的SSE终端
-
自选
STDIO传输(通过设置启用)spring.ai.mcp.server.stdio=true) -
包括
Spring Boot启动网和MCP-Spring-webmvc依赖
WebFlux 服务器传输
完整的 MCP 服务器功能支持SSE(服务器发送事件)基于 Spring WebFlux 的服务器传输,并可选STDIO运输。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>
Starters会激活McpWebFluxServerAutoConfiguration和McpServerAutoConfiguration自动配置以提供:
-
使用Spring WebFlux的无效传输(
WebFluxSseServerTransportProvider) -
自动配置的响应式SSE端点
-
自选
STDIO传输(通过设置启用)spring.ai.mcp.server.stdio=true) -
包括
Spring BootStarters网流和MCP-Spring-Webflux依赖
|
由于 Spring Boot 的默认行为,当两者 |
配置属性
所有性质前缀为spring.ai.mcp.server:
| 属性 | 描述 | 默认值 |
|---|---|---|
|
启用/禁用MCP服务器 |
|
|
启用/禁用 stdio 传输 |
|
|
用于识别的服务器名称 |
|
|
服务器版本 |
|
|
可选指令,指导客户端如何与该服务器交互 |
|
|
服务器类型(同步/非同步) |
|
|
启用/禁用资源功能 |
|
|
启用/禁用工具功能 |
|
|
启用/禁用提示符功能 |
|
|
启用/禁用完成功能 |
|
|
启用资源变更通知 |
|
|
启用即时变更通知 |
|
|
启用刀具更换通知 |
|
|
(可选)响应 MIME 类型,按工具名称。例如 |
|
|
客户端用于发送消息的自定义SSE消息端点路径,用于网络传输 |
|
|
用于Web传输的自定义SSE端点路径 |
|
|
可选的URL前缀。例如 |
- |
|
等待服务器响应的时间长,然后在超时请求。适用于通过客户端发出的所有请求,包括工具调用、资源访问和提示作。 |
|
同步/异步服务器类型
-
同步服务器——默认服务器类型,采用以下方式实现
McpSyncServer. 它旨在实现应用程序中的直接请求-响应模式。 要启用这种服务器类型,设spring.ai.mcp.server.type=SYNC在你的配置中。 激活后,它会自动处理同步工具规格的配置。 -
异步服务器——异步服务器实现的使用
McpAsyncServer并且针对非阻塞作进行了优化。 要启用这种服务器类型,请配置你的应用程序spring.ai.mcp.server.type=ASYNC. 这种服务器类型会自动设置带有内置 Project Reactor 支持的异步工具规范。
服务器功能
MCP服务器支持四种主要功能类型,可以单独启用或禁用:
-
工具 - 启用/禁用工具功能
spring.ai.mcp.server.capabilities.tool=true|false -
资源 - 启用/禁用资源功能
spring.ai.mcp.server.capabilities.resource=true|false -
提示词 - 启用/禁用提示功能
spring.ai.mcp.server.capabilities.prompt=true|false -
补全——启用/禁用补全功能
spring.ai.mcp.server.capabilities.completion=true|false
所有功能默认都是启用的。禁用某项功能会阻止服务器注册并向客户端展示相应功能。
交通选择
MCP 服务器支持三种传输机制,每种机制都有专用的起始器:
-
标准输入输出(STDIO)-
Spring-AI-starter-mcp-server -
春季MVC(服务器发送事件)-
Spring-AI-starter-MCP-Server-webmvc -
春季WebFlux(响应式SSE)-
Spring-AI-starter-mcp-server-webflux
功能与功能
MCP 服务器启动Starters允许服务器向客户端公开工具、资源和提示。 它会自动将注册为 Spring Beans 的自定义能力处理程序转换为基于服务器类型的同步/非同步规范:
工具
允许服务器暴露可被语言模型调用的工具。MCP 服务器启动Starters提供:
-
变更通知支持
-
Spring AI 工具会自动根据服务器类型转换为同步/非同步规范
-
通过春季豆自动工具配置:
@Bean
public ToolCallbackProvider myTools(...) {
List<ToolCallback> tools = ...
return ToolCallbackProvider.from(tools);
}
或者使用底层 API:
@Bean
public List<McpServerFeatures.SyncToolSpecification> myTools(...) {
List<McpServerFeatures.SyncToolSpecification> tools = ...
return tools;
}
自动配置会自动检测并注册来自以下所有工具回调:
*个人工具回调豆
* 列表工具回调豆
*ToolCallbackProvider豆
工具按名称进行重复处理,每个工具名称首次出现的顺序被使用。
工具上下文支持
支持ToolContext,允许将上下文信息传递给工具调用。它包含一个McpSyncServerExchange实例在交换钥匙,可通过以下方式访问McpToolUtils.getMcpExchange(toolContext).请看这个示例exchange.loggingNotification(...)和exchange.createMessage(...).
资源管理
为服务器向客户端暴露资源提供了标准化方式。
-
静态与动态资源规范
-
可选变更通知
-
资源模板支持
-
同步/异步资源规格之间的自动转换
-
通过春季豆自动资源分配:
@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);
}
即时管理
为服务器提供了一种标准化的方式,以向客户端展示提示模板。
-
变更通知支持
-
模板版本管理
-
同步/异步提示符规格之间的自动转换
-
通过Spring Beans自动提示指定:
@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);
}
完工管理
为服务器提供一种标准化的方式,将完成功能暴露给客户端。
-
支持同步和异步完成规范
-
通过春豆自动注册:
@Bean
public List<McpServerFeatures.SyncCompletionSpecification> myCompletions() {
var completion = new McpServerFeatures.SyncCompletionSpecification(
"code-completion",
"Provides code completion suggestions",
(exchange, request) -> {
// Implementation that returns completion suggestions
return new McpSchema.CompletionResult(List.of(
new McpSchema.Completion("suggestion1", "First suggestion"),
new McpSchema.Completion("suggestion2", "Second suggestion")
));
}
);
return List.of(completion);
}
根变消费者
当根源改变时,支持的客户端列表已更改发送根更更通知。
-
支持监控根变更
-
为被动应用自动转换为异步消费者
-
可选择通过Spring Beans注册
@Bean
public BiConsumer<McpSyncServerExchange, List<McpSchema.Root>> rootsChangeHandler() {
return (exchange, roots) -> {
logger.info("Registering root resources: {}", roots);
};
}
使用示例
标准STDIO服务器配置
# Using spring-ai-starter-mcp-server
spring:
ai:
mcp:
server:
name: stdio-mcp-server
version: 1.0.0
type: SYNC
WebMVC 服务器配置
# Using 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"
sse-message-endpoint: /mcp/messages
capabilities:
tool: true
resource: true
prompt: true
completion: true
WebFlux 服务器配置
# Using spring-ai-starter-mcp-server-webflux
spring:
ai:
mcp:
server:
name: webflux-mcp-server
version: 1.0.0
type: ASYNC # Recommended for reactive applications
instructions: "This reactive server provides weather information tools and resources"
sse-message-endpoint: /mcp/messages
capabilities:
tool: true
resource: true
prompt: true
completion: true
创建带有MCP服务器的Spring Boot应用程序
@Service
public class WeatherService {
@Tool(description = "Get weather information by city name")
public String getWeather(String cityName) {
// Implementation
}
}
@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工具。 你可以让多个豆子产生 ToolCallback。自动配置会合并它们。
应用示例
-
天气服务器(WebFlux)——春季 AI MCP 服务器启动Starters,支持 WebFlux 传输。
-
天气服务器(STDIO)——带有STDIO传输功能的春季AIMCP服务器启动Starters。
-
Weather Server 手动配置——Spring AI MCP Server Boot Starter,不使用自动配置,而是使用 Java SDK 手动配置服务器。