当前位置：首页 > news >正文

Spring AI MCP

news 来源：原创 2025/6/12 17:29:29

MCP 是一种开放协议，它对应用程序向大语言模型（LLMs）提供上下文信息的方式进行了标准化。可以把 MCP 想象成人工智能应用程序的 USB-C 接口。就像 USB-C 为将设备连接到各种外围设备和配件提供了一种标准化方式一样，MCP 将人工智能模型连接到不同的数据源和工具提供了一种标准化方式。
MCP 可在 LLM 之上构建智能体和复杂的工作流。LLM 通常需要与数据和工具集成，而 MCP 可提供：

在 LLM 提供商和供应商之间切换的灵活性。
不断扩充的预构建集成列表，大语言模型可以直接接入其中；
保护基础设施内数据的最佳实践

MCP Java SDK 提供模型上下文协议的 Java 实现，通过同步和异步通信模式实现与 AI 模型和工具的标准化交互。
Spring AI MCP通过 Spring Boot 集成扩展了 MCP Java SDK，同时提供了客户端和服务器启动器。使用 Spring Initializer 通过 MCP 支持引导您的 AI 应用程序。

架构

MCP架构

MCP 的核心遵循客户端-服务器架构，其中主机应用程序可以连接到多个服务器：
在这里插入图片描述

MCP 主机：通过 MCP 访问数据的 Claude Desktop、IDE 或 AI 工具等程序
MCP 客户端：与服务器保持 1：1 连接的协议客户端
MCP 服务器：轻量级程序，每个程序都通过标准化的模型上下文协议公开特定功能
本地数据源：MCP 服务器可以安全访问的计算机文件、数据库和服务
远程服务：MCP 服务器可以连接到的互联网（例如，通过 API）提供的外部系统

MCP Java SDK 架构

Java MCP 实现遵循三层架构：
在这里插入图片描述

客户端/服务器层：McpClient 处理客户端作，而 McpServer 管理服务器端协议作。两者都使用 McpSession 进行通信管理。
会话层（McpSession）：通过 DefaultMcpSession 实现管理通信模式和状态。
传输层（McpTransport）：处理 JSON-RPC 消息序列化和反序列化，并支持多种传输实现。

MCP 客户端

在这里插入图片描述

MCP 客户端是模型上下文协议（MCP）架构中的关键组件，负责建立和管理与 MCP 服务器的连接。它实现协议的客户端，处理：

协议版本协商，确保与服务器兼容
用于确定可用功能的功能协商
消息传输和 JSON-RPC 通信
工具发现和执行
资源访问和管理
提示系统交互
可选功能：
- 根管理
- 采样支持
同步和异步作
交通方式：
- 基于 Stdio 的传输，用于基于进程的通信
- 基于 Java HttpClient 的 SSE 客户端传输
- 用于反应式 HTTP 流的 WebFlux SSE 客户端传输

MCP 服务器

在这里插入图片描述

MCP 服务器是模型上下文协议（MCP）架构中的基础组件，用于向客户端提供工具、资源和功能。它实现了协议的服务器端，负责：

服务器端协议作实现
- 工具曝光和发现
- 使用基于 URI 的访问进行资源管理
- 及时的模板配置和处理
- 与客户的能力协商
- 结构化日志记录和通知
并发客户端连接管理
同步和异步 API 支持
Transport 实现：
- 基于 Stdio 的传输，用于基于进程的通信
- 基于 Servlet 的 SSE 服务器传输
- 用于反应式 HTTP 流的 WebFlux SSE 服务器传输
- 用于基于 servlet 的 HTTP 流的 WebMVC SSE 服务器传输

MCP 集成

Spring AI 通过以下 Spring Boot 启动器提供 MCP 集成：
客户端启动器

spring-ai-starter-mcp-client- Core starter 提供 STDIO 和基于 HTTP 的 SSE 支持
spring-ai-starter-mcp-client-webflux- 基于 WebFlux 的 SSE 传输实现
服务器启动器
spring-ai-starter-mcp-server- 支持 STDIO 传输的核心服务器
spring-ai-starter-mcp-server-webmvc- 基于 Spring MVC 的 SSE 传输实现
spring-ai-starter-mcp-server-webflux- 基于 WebFlux 的 SSE 传输实现

客户端启动器

MCP Client Boot Starter 提供：

管理多个客户端实例
自动客户端初始化（如果启用）
支持多个命名传输
与 Spring AI 的工具执行框架集成
适当的生命周期管理，在应用程序上下文关闭时自动清理资源
通过定制器创建可定制的客户端

标准 MCP 客户端
标准启动器通过（进程内）和/或（远程）传输同时连接到一个或多个 MCP 服务器。 SSE 连接使用基于 HttpClient 的传输实现。与 MCP 服务器的每次连接都会创建一个新的 MCP 客户端实例。可以选择 MCP 客户端之一（注意：不能混合使用同步客户端和异步客户端）。对于生产部署，建议将基于 WebFlux 的 SSE 连接与 .STDIOSSESYNCASYNCspring-ai-starter-mcp-client-webflux

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

WebFlux 客户端
WebFlux 启动器提供与标准启动器类似的功能，但使用基于 WebFlux 的 SSE 传输实现。

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
</dependency>

配置属性

通用属性
通用属性的前缀为：spring.ai.mcp.client

属性	描述	默认值
enabled	启用/禁用 MCP 客户端	true
name	MCP 客户端实例的名称（用于兼容性检查）	spring-ai-mcp-client
version	MCP 客户端实例的版本	1.0.0
initialized	是否在创建时初始化客户端	true
request-timeout	MCP 客户端请求的超时持续时间	20s
type	客户端类型（SYNC 或 ASYNC）。所有客户端都必须是 sync 或 async;不支持混合	SYNC
root-change-notification	为所有客户端启用/禁用 root 更改通知	true
toolcallback.enabled	启用/禁用 MCP 工具回调与 Spring AI 的工具执行框架的集成	true

标准传输属性
标准 I/O 传输的属性前缀为：spring.ai.mcp.client.stdio

属性	描述	默认值
servers-configuration	包含 JSON 格式的 MCP 服务器配置的资源	-
connections	命名 stdio 连接配置的映射	-
connections.[name].command	要为 MCP 服务器执行的命令	-
connections.[name].args	命令参数列表	-
connections.[name].env	服务器进程的环境变量映射	-

SSE 传输属性
服务器发送事件（SSE）传输的属性前缀为：spring.ai.mcp.client.sse

属性	描述	默认值
connections	命名 SSE 连接配置的映射	-
connections.[name].url	用于与 MCP 服务器进行 SSE 通信的基 URL 端点	-
connections.[name].sse-endpoint	用于连接的 SSE 端点（作为 URL 后缀）	/sse

配置示例：

spring:ai:mcp:client:stdio:root-change-notification: trueconnections:server1:command: /path/to/serverargs:- --port=8080- --mode=productionenv:API_KEY: your-api-keyDEBUG: "true"

自定义客户端

自动配置通过回调接口提供广泛的客户端规范自定义功能。这些定制器允许配置 MCP 客户端行为的各个方面，从请求超时到事件处理和消息处理。

自定义类型
以下自定义选项可用：

请求配置 - 设置自定义请求超时
自定义采样处理程序 - 服务器通过客户端从 LLM 请求 LLM 采样（或）的标准化方式。此流程允许客户端保持对模型访问、选择和权限的控制，同时使服务器能够利用 AI 功能，而无需服务器 API 密钥。completionsgenerations
文件系统（根）访问 - 客户端向服务器公开文件系统的标准化方式。根定义了服务器在文件系统中可以运行的位置的边界，使它们能够了解它们可以访问哪些目录和文件。服务器可以从支持客户端请求根列表，并在该列表更改时接收通知。roots
Event Handlers - 当某个服务器事件发生时通知客户端的处理程序：
- 工具更改通知 - 当可用服务器工具列表发生更改时
- 资源更改通知 - 当可用服务器资源列表发生更改时。
- 提示更改通知 - 当可用服务器列表提示更改时。
日志记录处理程序 - 服务器向客户端发送结构化日志消息的标准化方式。客户端可以通过设置最小日志级别来控制日志记录详细程度

可以为同步（McpSyncClientCustomizer ）客户端或异步（McpAsyncClientCustomizer）客户端实现，具体取决于应用程序的需要。
McpSyncClientCustomizer

@Component
public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {@Overridepublic void customize(String serverConfigurationName, McpClient.SyncSpec spec) {// Customize the request timeout configurationspec.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 samplingCreateMessageResult 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});}
}

McpAsyncClientCustomizer

@Component
public class CustomMcpAsyncClientCustomizer implements McpAsyncClientCustomizer {@Overridepublic void customize(String serverConfigurationName, McpClient.AsyncSpec spec) {// Customize the async client configurationspec.requestTimeout(Duration.ofSeconds(30));}
}

服务器启动器

Spring AI MCP（模型上下文协议）服务器启动器提供了在 Spring Boot 应用程序中设置 MCP 服务器的自动配置。它支持将 MCP 服务器功能与 Spring Boot 的自动配置系统无缝集成。
MCP Server Boot Starter 提供：

自动配置 MCP 服务器组件
支持同步和异步作模式
多个传输层选项
灵活的工具、资源和提示符规范
更改通知功能

标准 MCP 服务器 STDIO

完整的 MCP Server 功能支持服务器传输。

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
</dependency>

适用于命令行和桌面工具
不需要额外的 Web 依赖项

启动器激活自动配置(McpServerAutoConfiguration)，负责：

配置基本 Server 组件
处理工具、资源和提示规范
管理 Server 功能和更改通知
提供同步和异步服务器实现

WebMVC 服务器传输

完整的 MCP 服务器功能支持基于 Spring MVC 的 SSE（服务器发送事件）服务器传输和可选的STDIO传输。

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

Starter 激活McpWebMvcServerAutoConfiguration 和McpServerAutoConfiguration 的 auto-configurations ：

使用 Spring MVC 的基于 HTTP 的传输（WebMvcSseServerTransportProvider)
自动配置的 SSE 终端节点
可选传输（通过设置STDIOspring.ai.mcp.server.stdio=true)
包含和依赖项spring-boot-starter-webmcp-spring-webmvc

WebFlux 服务器传输

完整的 MCP 服务器功能支持基于 Spring WebFlux 的 SSE（Server-Sent Events）服务器传输和可选的STDIO传输。

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

Starter 激活 McpWebFluxServerAutoConfiguration和McpServerAutoConfiguration 的 auto-configurations ：

使用 Spring WebFlux （WebFluxSseServerTransportProvider)
自动配置的反应式 SSE 终端节点
可选传输（通过设置STDIOspring.ai.mcp.server.stdio=true)
包含和依赖项spring-boot-starter-webfluxmcp-spring-webflux

服务器类型

同步服务器 - 使用实现的默认服务器类型。它专为应用程序中的简单请求-响应模式而设计。要启用此服务器类型，请在您的配置中设置。激活后，它会自动处理同步工具规格的配置。McpSyncServerspring.ai.mcp.server.type=SYNC
异步服务器 - 异步服务器实现使用非阻塞作并针对非阻塞作进行了优化。要启用此服务器类型，请使用配置您的应用程序。此服务器类型会自动设置具有内置 Project Reactor 支持的异步工具规范。McpAsyncServerspring.ai.mcp.server.type=ASYNC