简介spring ai alibaba是java的ai agent框架本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理不仅指导agent的开发更可以改造框架增加新特性系列内容系列(一) 架构 完成系列(三) 调用I 工具 完成II MCP1 MCP MCP能力工具资源Promptssampling。。。springboot自动配置 完成2 分布式 MCP 注册和发现nacosgateway3 MCP security, oauth2III skills 完成系列(四) RAG 完成I 知识库文档读取分块嵌入向量storeII 检索增强生成模块化混合检索融合重排系列(二) I 模型 model模型 完成chat模型消息提示词结构化输出记忆chat clientadvisor组件系列(五) graph 完成I 图结构节点和边StateGraph外部介入 完成推理框架 graph映射: ReActrelectionCoTPlan-And-ExecuteII 图编译 CompiledGraph扁平化图结构邻接表结构 完成III 图执行响应式流执行检查点回溯/回放中断和恢复容错系列(六) agent及组件 ReactAgentAgentLlmNodeAgentToolNode钩子和拦截器记忆结构化输出 完成系列(七) MAS 完成I MAS模式 flow模式 编排器-子智能体智能体团队数据交接II 分布式MAS远程通讯负载均衡注册发现容错系列(八) 观测I 观测组件(micrometer-observation), langfuse 完成II spring ai观测观测组件ChatClientChatModel 完成III spring ai alibaba观测 图观测系列(九) 评估 I spring ai 评估组件 本地开发测试II spring ai alibaba admin数据集构建、线上链路数据复用试验评估器III langfuse评估系列(十) 沙箱 完成本文分析外部调用II-2 分布式MCPbased spring ai aliba ba v1.1.2.2spring ai v1.1.2MCP sdk 0.17.0外部调用如果说agent是一个人大模型是大脑调用是手脚执行动作干实事。调用在不断发展演变中目前已有工具MCPskillsCLI等多种方式MCP-sdk MCP的实现包括连接管理会话和传输协议能力(资源工具等)本文不分析MCP sdk原理源码重点放在sa/saa集成MCPsaa分布式MCP分布式MCPMCP没有分布式相关的规范得益于java成熟的微服务体系saa实现分布式MCP是水到渠成的事nacos v3原生支持MCP服务注册和发现分布式MCP client 依赖 nacos 的发现能力和变更通知能力实现MCP调用的负载均衡和容错实现动态更新MCP server instances分布式client本节分析分布式MCP clientMCP Client集群化、分布式改造解决单点故障、流量洪峰和配置中心动态感知的问题。上图 分布式mcp client和工具类图整体架构可分为“接口定义 - 多协议实现 - 服务治理”3部分核心接口定义1. DistributedSyncMcpClient分布式客户端接口getServerName获取服务名一般是工具MCP工具名称callTool调用工具、listTools列出工具 工具调用方法getMcpSyncClient获取底层同步客户端分布式核心方法Mcp client列表依据负责算法选择 一实例名称改为selectMcpClient更好init/subscribeinit 从nacos获取服务实例subscribe订阅服务的变更包括服务的上线和下线2. ToolCallbackSpring AI agent工具接口3. NacosMcpSubscriber Nacos 服务订阅接口感知分布式mcp client动态变化实现类SseWebFluxDistributedSyncMcpClientDistributedSyncMcpClient see同步实现处理SSE 协议的通信。它内部维护了一个 McpSyncClient 的列表并依赖 NacosMcpOperationService 进行服务发现和变更更新。StreamWebFluxDistributedSyncMcpClient DistributedSyncMcpClient Streamable同步实现处理Streamable协议的通信。它内部维护了一个 McpSyncClient 的列表并依赖 NacosMcpOperationService 进行服务发现和变更更新。DistributedSyncMcpToolCallback实现了 ToolCallback作为上层Agent应用调用的入口内部持有 DistributedSyncMcpClient将具体的工具调用请求委托给分布式客户端处理NacosMcpOperationService封装了对 Nacos 的读写操作负责具体的服务注册、发现逻辑并实现了 NacosMcpSubscriber 接口来监听变化此类属于common包后面服务注册网关用到。协作流程初始化与订阅 DistributedSyncMcpClient 启动时通过 NacosMcpOperationService 获取Nacos 上的 MCP 服务实例订阅变更。动态路由工具调用请求时DistributedSyncMcpToolCallback 调用 callTool。此时分布式客户端根据某种负载算法从维护的 McpSyncClient 列表中选择一个可用的客户端。负载均衡目前负载均衡算法int currentIndex index.getAndUpdate(index - (index 1) % syncClients.size())。这是一种典型的轮询策略用于在多个同步客户端实例间分发请求。获取McpSyncClient列表下标为currentIndex的实例完成mcp工具调用架构抽象层面的不足当前架构虽然能够正常工作但从软件工程的设计原则尤其是开闭原则和单一职责原则来看DistributedSyncMcpClient及其实现类在抽象层次上存在明显不足主要体现在以下三个方面1. 传输协议与分布式逻辑耦合过紧从类图可以看出SseWebFluxDistributedSyncMcpClient同时承担了“分布式管理”如客户端列表维护、负载均衡和“SSE 协议通信”的具体实现职责。问题若未来需要支持 gRPC、HTTP/2 等其他传输协议就必须创建新的实现类如GrpcDistributedSyncMcpClient并重复编写与服务发现、客户端列表维护、负载均衡等与协议无关的分布式逻辑。理想设计应将“分布式代理逻辑”与“传输协议实现”解耦。DistributedSyncMcpClient应作为纯粹的代理Proxy专注于管理McpSyncClient实例集合与请求路由而不关心底层是 SSE 还是 Streamable 协议。底层的McpSyncClient应由工厂根据协议类型动态创建并注入。2. 负载均衡策略硬编码当前负载均衡采用简单的轮询算法实现代码为(index 1) % syncClients.size()。问题策略硬编码在实现类中缺乏灵活性。理想设计应将负载均衡抽象为独立的策略接口例如LoadBalanceStrategy。DistributedSyncMcpClient持有该接口具体的算法如轮询、随机、加权等可通过构造函数注入或配置文件动态切换。3. 服务发现机制与具体实现绑定服务注册与发现目前强依赖 Nacos通过NacosMcpOperationService。这更多是一种产品策略选择绑定自家生态而非技术限制但目前尚无其他注册中心原生支持 MCP 服务。SseWebFluxDistributedSyncMcpClient与StreamWebFluxDistributedSyncMcpClient的实现代码相似度高达 97%仅在与传输协议相关的少数几处存在差异。总结Spring AI Alibaba 的分布式 MCP Client 已具备核心的路由与通信能力。为了适应未来更复杂的企业级场景建议在以下三个维度进行更深层次的抽象实现传输协议无关性、将负载均衡策略化、以及标准化服务发现机制。最终目标是将“做什么”分布式路由与“怎么做”SSE通信、Nacos发现、轮询算法彻底解耦提升框架的扩展性与可维护性。MCP服务注册上节分析MCP分布式client依赖nacos的发现功能获得MCP sever的实例。MCP server实例信息是MCP注册器负责注册MCP server启动后MCP注册器收集MCP server信息自动注册到nacosMCP注册是MCP server的一部分MCP sever和MCP server实例注册为了描述方便前者称为MCP server类型注册上图 MCP服务和注册类图本节展示Stateless的类图非Stateless版本类似注册包括 3个功能0MCP服务兼容性检查首先查询是否已有相同的MCP服务注册查询的key是服务名版本若已有需要检查兼容性上图是兼容检查的代码展示检查的项目1注册MCP服务类型主要从McpStatelessAsyncServer配置抓取信息构建McpServerBasicInfoMCP服务的信息包括服务名称版本描述协议(SSE, STREAMABLE)contextPathMcpToolSpecificationMCP工具(集合)的spec属性包括名称描述输入schemaMcpEndpointSpec最后调用NacosMcpOperationService的createMcpServer注册MCP服务类型有一点需要考虑注册服务类型在MCP启动时多个MCP服务同时启动可能出现碰撞第一个注册后后面的会失败NacosStatelessMcpRegister提供容错机制但比较简单一没有采用随机延时防碰撞机制二nacos异常是通用的NacosException实际情况出现注册不上的可能性比较大2注册MCP服务实例注册实例在onApplicationEventApplicationListener接口的方法接收参数目的是过滤掉”management” web server获取正确的端口management是spring boot actuator观测服务但如果还有其他web serverMCP服务实例注册信息有3个与微服务注册一样服务名称分组名称Instance 实例对象3订阅变更MCP服务的订阅与分布式client的订阅一致关注不同后者关注实例的上下行前者关注工具规格的变更自动配置示例本节结合saa的mcp-exampls/mcp-nacos-example实例分析自动配置观测运行自动配置本节解释示例的自动配置得益于springboot的自动配置默认即可用示例很简单本节剖开内部搞清楚示例究竟做了些什么mcp client本节解释分布式mcp client应用端mcp client被agent工具包装使用与工具是一致上图 分布式mcp client和工具类图NacosMcpAutoConfiguration负责构建NacosMcpOperationService该服务负责nacos的读写订阅用于MCP服务类型MCP服务实例注册订阅MCP 工具变更NacosMcpToolCallbackAutoConfiguration负责构建DistributedSyncMcpToolCallbackProvider依赖NacosMcpStreamableClientAutoConfiguration构建的DistributedSyncMcpClient集DistributedSyncMcpToolCallbackProvider是ToolCallbackProvider实现提供agent工具TooCallback集合注意上图只展示Streamable协议sync client还有see协议async client有了上面的自动配置分布式mcp client应用只需注入ToolCallbackProvider取出TooCallback后续调用agent工具般调用mcp工具mcp服务分布式mcp服务应用与mcp client应用相反读取agent工具信息构建为MCP工具上图 分布式mcp server构建和注册/订阅其中右边部分mcp server分析过mcp server构建agent工具转换为mcp tool spec详细可参考mcp server那部分NacosStatelessMcpRegisterAutoConfiguration构建注册器依赖McpServerAutoConfiguration构建的Mcp server注意上图展示了Statelesssync server还有有状态和异步server有了自动配置加持mcp server示例只需简单声明ToolCallbackProvider即可运行示例2.1) 运行mcp服务上图 mcp server stateless/async的自动配置的断点收集agent工具转换为mcp tool spec上图 服务类型注册nacos原生支持mcp服务注册AI注册中心/MCP管理上图 mcp服务实例运行两个一样的mcp服务组成集群2.2) 运行mcp client上图 分布式mcp client获取两个mcp服务实例DistributedAsyncMcpToolCallbackProvider封装分布式mcp client提供agent工具NEXTmcp gateway