|
获取最新的快照版本,请使用 Spring AI 1.1.3! |
MCP客户端启动Starters
Spring Boot中的MCP模型上下文协议(Model Context Protocol)客户Starters提供自动配置MCP客户端功能的实现。该Starters支持同步和异步客户端实现,并提供多种传输选项。
MCP 客户端Starters提供:
-
多客户端实例管理
-
如果启用,则会自动初始化客户端(Automatic client initialization,如果启用)。
-
支持多个命名传输
-
集成Spring AI的工具执行框架
-
正确的生命周期管理,当应用上下文关闭时,自动清理资源。
-
通过定制器实现客户创建的可定制性
Starters
|
There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the 升级说明以获取更多信息。 |
标准MCP客户端
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>
标准启动程序同时通过STDIO(进程内)和/或SSE(远程)传输连接到一个或多个MCP服务器。
SSE连接使用基于HttpClient的传输实现。
每个与MCP服务器的连接都会创建一个新的MCP客户端实例。
您可以选择使用SYNC或ASYNC个MCP客户端(注意:不能混用同步和异步客户端)。
对于生产部署,我们建议使用基于WebFlux的SSE连接,并搭配spring-ai-starter-mcp-client-webflux。
配置属性
常见属性
常见的属性都以0前缀表示:
| 属性 | 描述 | 默认值 |
|---|---|---|
|
启用/禁用 MCP 客户端 |
|
|
mcpClientName |
|
|
MCP客户端实例的版本号 |
|
|
是否在创建时初始化客户端 |
|
|
MCP客户端请求的超时时间设置。 |
|
|
客户端类型必须是SYNC或ASYNC。所有客户端必须是SYNC或ASYNC,混合使用不被支持。 |
|
|
所有客户端启用或禁用root变更通知 |
|
|
启用或禁用MCP工具回调集成,与Spring AI的工具执行框架结合。 |
|
Spring框架运输属性
标准I/O传输的属性以0前缀:
| 属性 | 描述 | 默认值 |
|---|---|---|
|
包含MCP服务器配置的JSON格式的资源 |
- |
|
命名文件句柄连接配置地图 |
- |
|
用于MCP服务器的执行命令 |
- |
|
命令参数列表 |
- |
|
服务器过程的环境变量地图 |
- |
示例配置:
spring:
ai:
mcp:
client:
stdio:
root-change-notification: true
connections:
server1:
command: /path/to/server
args:
- --port=8080
- --mode=production
env:
API_KEY: your-api-key
DEBUG: "true"
或者,您可以使用外部JSON文件(采用Claude Desktop格式)来配置stdio连接:
spring:
ai:
mcp:
client:
stdio:
servers-configuration: classpath:mcp-servers.json
Claude Desktop 格式如下所示:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/Users/username/Downloads"
]
}
}
}
目前,Claude Desktop 格式仅支持 STDIO 连接类型。
SSE 传输属性
服务器发送事件(SSE)传输的属性以 spring.ai.mcp.client.sse 开头:
| 属性 | 描述 | 默认值 |
|---|---|---|
|
命名的SSE连接配置映射 |
- |
|
与MCP服务器进行SSE通信的基础URL端点 |
- |
|
用于连接的 SSE 端点(作为 URL 后缀) |
|
示例配置:
spring:
ai:
mcp:
client:
sse:
connections:
server1:
url: http://localhost:8080
server2:
url: http://otherserver:8081
sse-endpoint: /custom-sse
特性
同步/异步客户端类型
该Starters支持两种类型的客户端:
-
同步 - 默认客户端类型,适用于具有阻塞操作的传统请求-响应模式。
-
异步 - 适用于具有非阻塞操作的响应式应用程序,通过使用
spring.ai.mcp.client.type=ASYNC进行配置
客户端自定义
自动配置通过回调接口提供了广泛的客户端规格自定义功能。这些自定义器允许您配置MCP客户端行为的各个方面,从请求超时到事件处理和消息处理。
自定义类型
以下自定义选项可用:
-
请求配置 - 设置自定义请求超时
-
自定义采样处理器 - 服务器通过客户端向大语言模型请求采样(
completions或generations)的标准化方式。该流程允许客户端在维持对模型访问、选择和权限控制的同时,使服务器能够利用人工智能能力——且无需服务器API密钥。 -
文件系统(根目录)访问 - 客户端向服务器公开文件系统
roots的标准化方式。 根目录定义了服务器在文件系统中可操作的边界,使其能够了解可以访问哪些目录和文件。 服务器可以向支持的客户端请求根目录列表,并在该列表发生变化时接收通知。 -
事件处理器 - 当特定服务器事件发生时,通知客户端处理器:
-
工具更改通知 - 当可用服务器工具列表发生变化时
-
资源变更通知 - 当可用服务器资源列表发生变化时。
-
提示更改通知 - 当可用服务器提示列表发生变化时。
-
-
日志处理程序 - 服务器向客户端发送结构化日志消息的标准化方式。 客户端可以通过设置最低日志级别来控制日志的详细程度
您可以根据应用程序的需要,为同步客户端实现 McpSyncClientCustomizer,或为异步客户端实现 McpAsyncClientCustomizer。
-
Sync
-
Async
@Component
public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {
@Override
public void customize(String serverConfigurationName, McpClient.SyncSpec spec) {
// Customize the request timeout configuration
spec.requestTimeout(Duration.ofSeconds(30));
// Sets the root URIs that this client can access.
spec.roots(roots);
// Sets a custom sampling handler for processing message creation requests.
spec.sampling((CreateMessageRequest messageRequest) -> {
// Handle sampling
CreateMessageResult result = ...
return result;
});
// Adds a consumer to be notified when the available tools change, such as tools
// being added or removed.
spec.toolsChangeConsumer((List<McpSchema.Tool> tools) -> {
// Handle tools change
});
// Adds a consumer to be notified when the available resources change, such as resources
// being added or removed.
spec.resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {
// Handle resources change
});
// Adds a consumer to be notified when the available prompts change, such as prompts
// being added or removed.
spec.promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {
// Handle prompts change
});
// Adds a consumer to be notified when logging messages are received from the server.
spec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
// Handle log messages
});
}
}
@Component
public class CustomMcpAsyncClientCustomizer implements McpAsyncClientCustomizer {
@Override
public void customize(String serverConfigurationName, McpClient.AsyncSpec spec) {
// Customize the async client configuration
spec.requestTimeout(Duration.ofSeconds(30));
}
}
serverConfigurationName 参数是应用自定义器的服务器配置的名称,也是为其创建 MCP 客户端的名称。
MCP 客户端自动配置会自动检测并应用应用程序上下文中找到的任何自定义器。
使用示例
将适当的Starters依赖项添加到您的项目中,并在 application.properties 或 application.yml 中配置客户端:
spring:
ai:
mcp:
client:
enabled: true
name: my-mcp-client
version: 1.0.0
request-timeout: 30s
type: SYNC # or ASYNC for reactive applications
sse:
connections:
server1:
url: http://localhost:8080
server2:
url: http://otherserver:8081
stdio:
root-change-notification: false
connections:
server1:
command: /path/to/server
args:
- --port=8080
- --mode=production
env:
API_KEY: your-api-key
DEBUG: "true"
MCP 客户端 Bean 将会自动配置并可供注入:
@Autowired
private List<McpSyncClient> mcpSyncClients; // For sync client
// OR
@Autowired
private List<McpAsyncClient> mcpAsyncClients; // For async client
当启用工具回调(默认行为)时,所有MCP客户端注册的MCP工具将作为一个 ToolCallbackProvider 实例提供:
@Autowired
private SyncMcpToolCallbackProvider toolCallbackProvider;
ToolCallback[] toolCallbacks = toolCallbackProvider.getToolCallbacks();
示例应用程序
-
Brave 网络搜索聊天机器人 - 一个使用模型上下文协议与网络搜索服务器交互的聊天机器人。
-
默认MCP客户端Starters - 一个使用默认的
spring-ai-starter-mcp-clientMCP客户端Starters的简单示例。 -
WebFlux MCP 客户端Starters - 一个使用
spring-ai-starter-mcp-client-webfluxMCP 客户端Starters的简单示例。