Spring AI MCP 客户端详解
概述
Model Context Protocol (MCP) 是一种标准化协议，用于使 AI 模型以结构化的方式与外部工具和资源进行交互。它充当 AI 模型与外部系统（如数据库、API 和文件系统）之间的桥梁，支持多种传输机制，以适应不同环境。
Spring AI 通过专用的 Boot Starters 和 MCP Java Annotations 集成 MCP，使 Spring 开发者能够构建消费 MCP 服务器的 AI 应用程序，并创建暴露 Spring 基于服务的 MCP 服务器。MCP 架构采用三层设计：
- 客户端/服务器层：包括管理客户端操作和服务器连接的
McpClient，以及处理服务器端协议操作的McpServer。 - 会话层：通过
McpSession、McpClientSession和McpServerSession管理通信。 - 传输层：通过
McpTransport处理消息传输和序列化，支持如 STDIO、HTTP/SSE 和 Streamable-HTTP 等传输方式。
MCP Java SDK 提供了协议的 Java 实现，支持同步和异步通信模式。
设置
要使用 Spring AI 中的 MCP 客户端，请按照以下步骤设置：
- 使用 Spring Initializer 初始化带有 MCP 支持的 AI 应用程序。
- 在
pom.xml中添加相应的 Spring Boot starter 依赖：
spring-ai-starter-mcp-client：提供 STDIO、基于 Servlet 的 Streamable-HTTP、无状态 Streamable-HTTP 和 SSE 支持。spring-ai-starter-mcp-client-webflux：提供基于 WebFlux 的 Streamable-HTTP、无状态 Streamable-HTTP 和 SSE 传输（适用于响应式应用）。
例如，添加 Anthropic 模型和 MCP 客户端的依赖：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-anthropic</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>使用 Spring AI BOM 管理版本：
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>1.0.1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>配置
配置通过 Spring Boot 属性文件（如 application.yaml）管理。支持两种主要传输类型：stdio 和 SSE。
示例配置
- Brave Search MCP 客户端 (stdio)：
spring:
ai:
mcp:
client:
stdio:
connections:
brave-search:
command: npx
args:
- "-y"
- "@modelcontextprotocol/server-brave-search"
env:
BRAVE_API_KEY: ${BRAVE_API_KEY}- Filesystem MCP 客户端 (stdio)：
spring:
ai:
mcp:
client:
stdio:
connections:
filesystem:
command: npx
args:
- "-y"
- "@modelcontextprotocol/server-filesystem"
- "./"- 自定义 MCP 服务器客户端 (SSE)：
spring:
ai:
mcp:
client:
sse:
connections:
author-tools-server:
url: http://localhost:8081启动时，Spring AI 会建立与 MCP 服务器的一对一连接，并创建一个 SyncMcpToolCallbackProvider Bean 来暴露所有可用工具。
此外，配置 API 密钥和模型：
spring:
ai:
anthropic:
api-key: ${ANTHROPIC_API_KEY}
chat:
options:
model: claude-opus-4-20250514使用
MCP 客户端 (McpClient) 负责：
- 建立和管理与 MCP 服务器的连接。
- 处理协议版本协商以确保兼容性。
- 执行能力协商以确定可用功能。
- 管理消息传输和 JSON-RPC 通信。
- 支持工具发现和执行。
- 启用资源访问和管理。
- 促进提示系统交互。
它支持根管理、采样支持以及同步/异步操作。
在 Spring AI 中，使用 MCP 客户端构建聊天机器人时：
- 创建
ChatClientBean：
@Bean
ChatClient chatClient(ChatModel chatModel, SyncMcpToolCallbackProvider toolCallbackProvider) {
return ChatClient.builder(chatModel)
.defaultToolCallbacks(toolCallbackProvider.getToolCallbacks())
.build();
}- 实现聊天服务：
String chat(String question) {
return chatClient.prompt()
.user(question)
.call()
.content();
}- 通过 REST 端点暴露：
@PostMapping("/chat")
ResponseEntity<ChatResponse> chat(@RequestBody ChatRequest chatRequest) {
String answer = chatbotService.chat(chatRequest.question());
return ResponseEntity.ok(new ChatResponse(answer));
}
record ChatRequest(String question) {}
record ChatResponse(String answer) {}示例
1. Web 搜索
使用 Brave Search 工具发送问题：
http POST :8080/chat question="How much was Elon Musk's initial offer to buy OpenAI in 2025?"响应将包括搜索结果和来源。
2. 文件系统操作
http POST :8080/chat question="Create a text file named 'mcp-demo.txt' with content 'This is awesome!'."确认文件创建。
3. 自定义工具调用
假设有一个自定义服务器暴露作者工具：
http POST :8080/chat question="Who wrote the article 'Testing CORS in Spring Boot?' on Baeldung, and how can I contact them?"返回作者姓名和电子邮件。
关键特性
- 传输灵活性：支持 STDIO、HTTP/SSE、Streamable-HTTP 和无状态 Streamable-HTTP。
- 双向集成：允许 Spring 开发者参与 MCP 生态系统的客户端和服务器端。
- 注解支持：通过 MCP Annotations 模块，使用如
@McpLogging、@McpSampling、@McpElicitation和@McpProgress等注解进行声明式编程。 - 自动发现：支持注解扫描，并可配置包包含/排除。
- Spring Boot 集成：通过 MCP Boot Starters 简化设置。
最佳实践
- 使用 Spring Initializer 引导项目以支持 MCP。
- 根据传输需求选择合适的 starter（例如，响应式应用使用
spring-ai-starter-mcp-client-webflux）。 - 利用 MCP Annotations 减少样板代码，提高客户端实现的维护性。
- 在客户端-服务器交互中通过协议版本和能力协商确保兼容性。
- 使用结构化日志和通知实现稳健的客户端-服务器通信。
