|
此版本仍在开发中,尚未被视为稳定版。如需最新的快照版本,请使用 Spring AI 1.1.3! |
MCP Server Boot Starters
模型上下文协议 (MCP) 服务器 是通过标准化协议接口向 AI 应用程序暴露特定能力的程序。 每个服务器为特定领域提供专注的功能。
Spring AI MCP Server Boot Starters 为在 Spring Boot 应用程序中设置 MCP 服务器 提供了自动配置功能。 它们实现了 MCP 服务器能力与 Spring Boot 自动配置系统的无缝集成。
MCP Server Boot Starters 提供:
-
MCP 服务器组件的自动配置,包括工具、资源和提示词
-
支持不同的 MCP 协议版本,包括 STDIO、SSE、Streamable-HTTP 和无状态服务器。
-
支持同步和异步操作模式
-
多种传输层选项
-
灵活的工具、资源和提示规范
-
更改通知功能
-
基于注解的服务器开发,具备自动 Bean 扫描和注册功能
MCP 服务器Starters
MCP 服务器支持多种协议和传输机制。
请使用专用的 starter 并配置正确的 spring.ai.mcp.server.protocol 属性来设置您的服务器:
Web MVC
服务器类型 |
依赖 |
<property> </property> |
|
|
|
|
|
|
|
|
服务器能力
根据服务器和传输类型的不同,MCP 服务器可以支持各种功能,例如:
-
工具 - 允许服务器暴露可由语言模型调用的工具
-
资源 - 提供了一种标准化的方式,供服务器向客户端暴露资源
-
提示词 - 为服务器向客户端暴露提示词模板提供了一种标准化方式
-
实用工具/补全 - 为服务器提供一种标准化的方式,以便为提示和资源 URI 提供参数自动补全建议
-
实用工具/日志记录 - 为服务器向客户端发送结构化日志消息提供了一种标准化方式
-
工具/进度 - 通过通知消息为长时间运行的操作提供可选的进度跟踪
-
实用工具/Ping - 服务器报告其状态的可选健康检查机制
所有功能默认启用。禁用某项功能将阻止服务器向客户端注册和暴露相应的特性。
服务器协议
MCP 提供多种协议类型,包括:
-
标准输入输出 - 进程内(例如,服务器在宿主应用程序内部运行)协议。通信通过标准输入和标准输出进行。要启用
STDIO,请设置spring.ai.mcp.server.stdio=true。 -
SSE - 用于实时更新的服务端发送事件协议。服务器作为独立进程运行,可处理多个客户端连接。
-
可流式传输的 HTTP - 可流式传输的 HTTP 传输 允许 MCP 服务器作为独立进程运行,能够使用 HTTP POST 和 GET 请求处理多个客户端连接,并支持可选的服务器发送事件 (SSE) 流式传输以发送多条服务器消息。它取代了 SSE 传输。要启用
STREAMABLE协议,请设置spring.ai.mcp.server.protocol=STREAMABLE。 -
无状态 - 无状态 MCP 服务器专为简化部署而设计,不在请求之间维护会话状态。 它们非常适合微服务架构和云原生部署。要启用
STATELESS协议,请设置spring.ai.mcp.server.protocol=STATELESS。
同步/异步服务器 API 选项
MCP Server API 支持命令式(即同步)和响应式(例如异步)编程模型。
-
同步服务器 - 使用
McpSyncServer实现的默认服务器类型。 它专为应用程序中简单的请求 - 响应模式而设计。 要启用此服务器类型,请在配置中设置spring.ai.mcp.server.type=SYNC。 激活后,它将自动处理同步工具规范的配置。
注意:SYNC 服务器仅注册同步的 MCP 注解方法。异步方法将被忽略。
-
异步服务器 - 异步服务器实现使用
McpAsyncServer并针对非阻塞操作进行了优化。 要启用此服务器类型,请使用spring.ai.mcp.server.type=ASYNC配置您的应用程序。 此服务器类型会自动设置带有内置 Project Reactor 支持的异步工具规范。
注意:ASYNC 服务器仅注册带有异步 MCP 注解的方法。同步方法将被忽略。
MCP 服务器注解
MCP Server Boot Starters 为基于注解的服务器开发提供了全面支持,使您能够使用声明式的 Java 注解来创建 MCP 服务器,而无需手动配置。
关键注解
-
@McpTool - 将方法标记为 MCP 工具,并自动生成 JSON 架构
-
@McpResource - 通过 URI 模板提供对资源的访问
-
@McpPrompt - 为 AI 交互生成提示消息
-
@McpComplete - 为提示词提供自动补全功能
特殊参数
注解系统支持 特殊参数类型,以提供额外的上下文:
-
McpMeta- 从 MCP 请求访问元数据 -
@McpProgressToken- 接收长时间运行操作的进度Tokens -
McpSyncServerExchange/McpAsyncServerExchange- 用于高级操作的完整服务器上下文 -
McpTransportContext- 用于无状态操作的轻量级上下文 -
CallToolRequest- 支持灵活工具的动态模式
简单示例
@Component
public class CalculatorTools {
@McpTool(name = "add", description = "Add two numbers together")
public int add(
@McpToolParam(description = "First number", required = true) int a,
@McpToolParam(description = "Second number", required = true) int b) {
return a + b;
}
@McpResource(uri = "config://{key}", name = "Configuration")
public String getConfig(String key) {
return configData.get(key);
}
}
向 McpTransportContext 添加数据
默认情况下,McpTransportContext 为空(McpTransportContext.EMPTY)。
这是设计使然,旨在保持 MCP 服务器与传输方式无关。
如果您的工具需要特定于传输的元数据(例如,HTTP 头、远程主机等),
请在您的传输提供者上配置一个 TransportContextExtractor。
@Bean
public WebMvcStreamableServerTransportProvider transport(ObjectMapper objectMapper) {
return WebMvcStreamableServerTransportProvider.builder()
.contextExtractor(serverRequest -> {
String authorization = serverRequest.headers().firstHeader("Authorization");
return McpTransportContext.create(Map.of("authorization", authorization));
})
.build();
}
配置完成后,在您的工具中通过 McpSyncRequestContext(或 McpAsyncRequestContext)访问上下文。
@McpTool
public String accessProtectedResource(McpSyncRequestContext requestContext) {
McpTransportContext context = requestContext.transportContext();
String authorization = (String) context.get("authorization");
return "Successfully accessed protected resource.";
}
示例应用
-
天气服务器 (SSE WebFlux) - 带有 WebFlux 传输的 Spring AI MCP Server Boot Starter
-
天气服务器 (STDIO) - 带有 STDIO 传输的 Spring AI MCP 服务器 Boot Starter
-
天气服务器手动配置 - Spring AI MCP 服务器 Boot Starter,不使用自动配置,而是使用 Java SDK 手动配置服务器
-
可流式传输的 HTTP WebFlux/WebMVC 示例 - 待办事项
-
无状态 WebFlux/WebMVC 示例 - 待办事项