Spring AI中模型上下文交互的协议探索

文章标题：

Spring AI中模型上下文交互协议的探究

文章内容：

文章目录

• • MCP客户端启动器
  • • 启动器
  • • 标准MCP客户端
    • WebFlux MCP客户端
  • 配置属性
  • • 通用属性
    • STDIO传输属性
    • SSE传输属性
  • 功能特性
  • • 同步/异步客户端类型
    • 客户端定制化
    • 同步客户端定制化示例
    • 传输支持
    • 与Spring AI集成
  • 使用示例
  • 示例应用
  • MCP服务器启动器
  • • 启动器
  • • 标准MCP服务器
    • WebMVC服务器传输
    • WebFlux服务器传输
  • 配置属性
  • 同步/异步服务器类型
  • 传输选项
  • 功能与能力
  • • 工具（Tools）
    • 资源管理（Resources）
    • 提示词管理（Prompts）
    • 根变更监听（Root Change Consumers）
  • 使用示例
  • • 标准STDIO服务器配置
    • WebMVC服务器配置
    • WebFlux服务器配置
    • 创建含MCP服务器的Spring Boot应用
  • MCP工具集
  • • • 工具回调适配器（Tool Callback Adapter）
    • 工具回调提供者（Tool Callback Providers）
    • McpToolUtils工具类
    • 原生镜像支持

模型上下文协议（MCP）是一种标准化的协议，它允许人工智能模型以结构化的方式与外部工具及资源开展交互。该协议支持多种传输机制，从而在不同环境中提供灵活的应用方式。
MCP Java SDK
MCP Java SDK提供了模型上下文协议的Java实现，借助同步与异步通信模式，支持与人工智能模型及工具进行标准化交互。
Java版本的MCP实现遵循三层架构：

• 客户端/服务器层（Client/Server Layer）：McpClient负责处理客户端相关操作，而McpServer则管理服务端的协议操作，二者均通过McpSession来进行通信管理。
• 会话层（McpSession）：通过DefaultMcpSession的具体实现，对通信模式以及状态进行管理。
• 传输层（McpTransport）：负责JSON-RPC消息的序列化与反序列化，并且支持多种传输协议的实现，例如HTTP、SSE等。

MCP客户端

MCP客户端是MCP架构中的关键组件，负责与MCP服务器建立并维护连接。该客户端实现了协议的客户端部分，具体处理以下功能：

1. 协议版本协商 ：保证与服务器的兼容性；
2. 能力协商 ：确定可用的功能，比如工具支持的范围等；
3. 消息传输与JSON-RPC通信 ：实现结构化数据的交互；
4. 工具发现与执行 ：动态识别并调用外部工具；
5. 资源访问与管理 ：协调模型与外部数据源的交互；
6. 提示系统交互 ：支持与模型提示（Prompt）系统的集成。

可选功能 ：

• 根管理（Roots Management）
• 采样支持（例如模型输出概率控制）
• 同步与异步操作模式

传输选项 ：

• 基于标准输入/输出的传输（适用于进程间通信）；
• 基于Java HttpClient的SSE客户端传输（支持事件流）；
• 基于WebFlux的SSE客户端传输（用于响应式HTTP流处理）。
  

MCP服务器

MCP服务器是MCP架构中的基础组件，为客户端提供工具、资源以及能力支持。该服务器实现了协议的服务端部分，核心职责包含：

1. 服务端协议操作实现 ：处理协议交互的逻辑；
2. 工具暴露与发现 ：通过标准化接口提供可调用的外部工具，例如函数/API等；
3. 基于URI的资源管理 ：支持文件、数据库等本地资源的安全访问；
4. 提示模板提供与处理 ：管理预定义的Prompt模板并动态注入上下文；
5. 能力协商 ：与客户端协商支持的功能范围，例如同步/异步模式等；
6. 结构化日志与通知 ：记录操作日志并推送状态变更事件；
7. 多客户端并发管理 ：支持高并发连接与会话隔离；
8. 同步与异步API支持 ：适配不同场景的调用需求。

传输实现 ：

• 基于标准输入/输出的传输（适用于进程间通信）；
• 基于Servlet的SSE服务端传输（支持事件流HTTP响应）；
• 基于WebFlux的响应式SSE传输（用于异步HTTP流式处理）；
• 基于WebMVC的Servlet SSE传输（兼容传统HTTP流式交互）

若要了解底层MCP客户端/服务器API的详细实现指南，可参考MCP Java SDK文档。若想通过Spring Boot简化配置，可使用下述介绍的MCP Boot启动器。

Spring AI MCP集成
Spring AI通过以下Spring Boot启动器提供MCP集成支持：

客户端启动器

• spring-ai-mcp-client-spring-boot-starter ：核心启动器，提供基于标准输入/输出（STDIO）和HTTP的SSE传输支持；
• spring-ai-mcp-client-webflux-spring-boot-starter ：基于WebFlux的响应式SSE传输实现。

服务端启动器

• spring-ai-mcp-server-spring-boot-starter ：核心服务端启动器，支持STDIO传输；
• spring-ai-mcp-server-webmvc-spring-boot-starter ：基于Spring MVC的SSE传输实现（兼容传统Servlet环境）；
• spring-ai-mcp-server-webflux-spring-boot-starter ：基于WebFlux的响应式SSE传输实现（支持异步流式处理）\n

MCP客户端启动器

Spring AI MCP（模型上下文协议）客户端启动器为Spring Boot应用程序中的MCP客户端功能提供自动配置支持，包含同步和异步客户端的实现，并且支持多种传输选项。
MCP客户端启动器具备以下功能 ：

1. 多客户端实例管理 ：支持同时维护多个客户端实例以适配不同场景；
2. 自动客户端初始化 （若启用）：通过Spring Boot自动装配机制加载默认配置；
3. 多种命名传输支持 ：允许通过名称区分STDIO、HTTP或WebFlux等传输协议；
4. 与Spring AI工具执行框架集成 ：无缝衔接工具调用与Prompt处理流程；
5. 完善的生命周期管理 ：应用上下文关闭时自动清理会话与资源；
6. 通过自定义器实现客户端可定制性 ：允许通过McpClientCustomizer接口扩展配置逻辑

启动器

标准MCP客户端

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

标准启动器通过STDIO（进程内）和/或SSE（远程）传输协议同时连接到一个或多个MCP服务器。其中SSE连接采用基于HttpClient的传输实现。每建立一个到MCP服务器的连接，即会创建一个新的MCP客户端实例。开发者可选择使用同步（SYNC）或异步（ASYNC）模式的MCP客户端（注意：同一应用中不可混合使用同步与异步客户端）。对于生产环境部署，建议采用基于WebFlux的SSE连接，并搭配spring-
ai-mcp-client-webflux-spring-boot-starter 启动器以实现响应式流式处理。

WebFlux MCP客户端

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

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

配置属性

通用属性

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

STDIO传输属性

标准输入/输出（Stdio