简介

    spring ai alibaba是java的ai agent框架，本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理，不仅指导agent的开发，更可以改造框架，增加新特性

系列内容：

系列(一) 架构  完成
系列(二) I 模型 model模型 完成
         chat模型，消息，提示词，结构化输出，记忆
         chat client，advisor组件  
         II 提示词工程@nacos
系列(三) 调用 
     I 工具  完成 
     II MCP
       1 MCP MCP能力，工具，资源，Prompts，sampling，。。。；springboot自动配置  完成
       2 分布式 MCP 完成
       3 MCP security, oauth2
     III skills  完成
系列(四) RAG  完成
     I 知识库，文档读取，分块；嵌入，向量store 
     II 检索，增强生成，模块化；混合检索，融合重排
系列(五) graph  完成
        I StateGraph,图结构
          推理框架  graph映射: ReAct，relection，CoT，Plan-And-Execute 
        II 图编译 CompiledGraph，扁平化图结构，邻接表结构 完成
        III 图执行，响应式流执行，检查点，回溯/回放，中断和恢复，容错
系列(六) agent及组件 完成
系列(七) MAS 完成
    I MAS模式 flow模式 编排器-子智能体，智能体团队；数据交接
    II 分布式MAS，远程通讯，负载均衡，注册发现，容错
系列(八) 观测 完成 
    I 观测组件(micrometer-observation), langfuse
    II spring ai观测，观测组件，ChatClient，ChatModel
系列(九) 评估 
    I spring ai 评估组件 本地测试
    II spring ai alibaba admin，数据集构建、线上链路数据复用，试验，评估器
    III langfuse评估
系列(十) 沙箱  完成

本文分析外部调用II-1 MCP，另外，II-2 分布式MCP，II-3 MCP security 

based spring ai aliba ba v1.1.2.2，spring ai v1.1.2，MCP sdk 0.17.0

关键词

缩写

spring ai 缩写sa

spring ai alibaba  本文缩写saa

参考资料

https://java2ai.com/docs/overview  spring ai alibaba官网文档

https://docs.spring.io/spring-ai/reference/index.html  spring ai官方文档

组件视图

上图是saa原理源码分析场景视图，每个包对应着saa/sa组件或特性，是本文分析的目录

model  大模型调用装，模型包括Chat，嵌入，audio，image等类型，其中chat模型包括，chat client，advisor组件，提示词，记忆等；

agent/graph  agent和图紧密相关，可以认为agent是一种既定的”图”形，开发人员可以使用graph低层api直接构建graph，也可以使用agent获得既定的图形，简化和加快agent的开发

外部调用(calling)  调用可能是agent发展演变最快的部分，最初的工具，到mcp，最近的CLI，skills

RAG  检索增强生成

MAS  多个agent协同工作，每个agent有独立职能

studio 简易的agent管理工具，嵌入到agent，带有agent面板，列表agent；提供chat界面，用于调试agent

admin 管理台， agent的发布，列表，管理，执行；提示词工程，评估和数据集，观测

外部调用

       如果说agent是一个人，大模型是大脑，调用是手脚，执行动作干实事。调用在不断发展演变中，目前已有工具，MCP，skills，CLI等多种方式

MCP-sdk  MCP的实现，包括连接管理，会话和传输协议，能力(资源，工具等)，本文不分析MCP原理源码，重点放在sa/saa集成MCP，saa分布式MCP

MCP介绍

本节介绍MCP

上图sa文档MCP的描述，3个关键词，MCP是ai model调用工具和资源的标准协议 ，MCP是ai model与外部交互的桥梁

MCP能力(Capabilities)

MCP规范定义MCP的能力，Tools是主要能力，其他能力有client侧，有server侧的

server侧：

Tools，定义可执行的函数，是目标本身，让 AI 做事情（如，查天气、发邮件、写文件）。

Resources，提供可读取的数据 ，Tool的“原材料”或“背景知识”。 执行Tool前，通过Resource了解当前状态、配置、文档或待处理的数据。

Prompts， 提供预定义的提示词模板，教AI正确使用Tool。避免 AI 自己乱编调用方式，提供最佳实践和上下文示例。

Completion，自动补全能力，允许服务器为 Prompts 和 Resources 的参数提供实时的、上下文感知的输入建议

client侧：  

Elicitation，大模型反向询问client，获取用户信息

Roots， client告诉server “用户的工作目录在哪”，方面后续server获取client的文件数据

Sampling， 允许Tool在执行过程中请求AI生成内容，让Tool 拥有“内省”或“补全”能力。一个复杂的Tool执行中，需要 AI 进行推理、总结或决策时，可以通过Sampling临时“借用”客户端的 LLM 来完成。

Notifications，变更通知能力，client和server变更互相实时通知

总结：

MCP以Tools为中心，其他的能力为完成工具调用设置，要么是给大模型工具使用的资料(Resources,Prompts)，告诉大模型工具怎样使用，要么server工具调用中向client询问信息(Sampling，Elicitation)

与skills对比，skills让大模型做好任务，MCP让大模型用好工具，两者可以互替

MCP工具

MCP工具，sa使用ToolCallback/ToolCallbackProvider组件封装，后续以工具管理和调用，共享工具调用的运行环境

 

上图MCP工具类图

SyncMcpToolCallbackProvider 接收McpSyncClient集为参数，遍历McpSyncClient集，每个McpSyncClient可带多个MCP工具(MCP.Tool类)，每个MCP.Tool封装为SyncMcpToolCallback

SyncMcpToolCallback  ToolCallback实例，工具调用类，引用McpSyncClient调用MCP .Tool

McpClient.SyncSpec  SyncSpec是McpClient的builder，可设置多种事件消费者，监听能力的变更其中有Tool变更

ApplicationListener/McpToolsChangedEvent  SyncMcpToolCallbackProvider实现Tool变更监听，使用spring的事件机制，监听MCP工具的变更，即上节的Notifications能力，重刷一遍McpSyncClient集合，构建新的SyncMcpToolCallback

下面分析MCP集成，springboot自动配置，

构建SyncMcpToolCallbackProvider/SyncMcpToolCallback

MCP集成

     本节分析sa的MCP集成，spring boot自动配置，分java配置和注解配置两部分，其中，java配置构建ToolCallback，注解配置负责MCP能力构建，client侧的McpSampling, McpElicitation, McpProgress等，server侧的McpTool, McpResource, McpPrompt, McpComplete等

MCP client

本节分析MCP client，MCP client运行在AI应用，与MCP sesrver，调用MCP server工具和能力

java配置

上图自动配置Java配置类图，为了展示清晰，Transport有只展示Streamable，只展示同步

McpToolCallbackAutoConfiguration  自动配置的C位，自动配置最终目标是构建SyncMcpToolCallbackProvider，

SyncMcpToolCallbackProvider    给ai应用提供McpToolCallback，依赖

                                                         McpClientAutoConfiguration 构建的McpSyncClient

McpClientAutoConfiguration  负责构建McpSyncClient，依赖McpTransport，通讯传输实现；McpSyncClientConfigurer给用户定制McpSyncClient的组件

McpAsyncClientConfigure/McpSyncClientCustomizer  使用SyncSpec定制McpSyncClient，上一节介绍的设置MCP工具变更事件消费者就是这个组件完成

StreamableHttpHttpClientTransportAutoConfiguration  负责构建McpTransport，使用配置属性(Properties)

注解配置

McpSyncClient的能力是由注解配置负责

上图MCP client注解配置类图

McpClientAnnotationScannerAutoConfiguration  注解自动配置类，职责实例化

                                                                     ClientMcpSyncHandlersRegistry

ClientMcpSyncHandlersRegistry  扫描spring管理的类型，找出带MCP标注的bean，使用了spring两个机制：

        --BeanFactoryPostProcessor  扫描受spring管理的类(带Service注解)，构建两个属性对象，allAnnotatedBeans，所有带有MCP注解的bean的名称；capabilitiesPerClient，保存每个client拥有的能力，MCP client用它列举能力

         --SmartInitializingSingleton   分析allAnnotatedBeans的MCP注解，使用反射技术封装MCP能力处理器

McpClientAutoConfiguration/McpSyncClient  上节java配置分析过，其中McpSyncClient能力设置是注解配置负责，从ClientMcpSyncHandlersRegistry获取

总结：client侧的自动配置目标是构建SyncMcpToolCallbackProvider，java配置负责，该类提供调用MCP工具的组件McpToolCallback，McpToolCallback依赖McpSyncClient，也是java配置负责，注解配置负责McpSyncClient能力handler

MCP server

上节分析MCP client侧自动配置，server侧“套路”类似，server侧的配置最终目的是构建Mcp Server，java配置负责，而注解配置负责初始化Mcp Server的能力

上图 MCP server的自动配置图1，负责构建McpSyncServer

McpServerAutoConfiguration  负责构建McpSyncServer，依赖各种能力Specification

McpSyncServer  负责通讯，处理能力请求

能力Specification  可以理解为药方，照单配药，构建能力需要的属性都在里面，McpSyncServer用来构建能力对象

ServerMcpAnnotatedBeans 这对象在这里只是new了，里面装着以注解类型分组的bean，用来构建能力Specification，下面分析

能力Specification怎么来的，下面继续分析

上图 MCP server的自动配置图2，负责构建各种能力Specification

McpServerSpecificationFactoryAutoConfiguration  能力Specification构建在这个自动配置

SyncMcpAnnotationProviders 该对象的定义了各种能力Specification的实例方法（@Bean），以tool能力规格实例方法toolSpecs为例，有两条线：

     1. SpringAiSyncToolProvider  构建tool能力规格的对象，从ServerMcpAnnotatedBeans的beansByAnnotation获取带标注@MCPTool的bean，通过反射获取数据，构建tool能力规格对象 SyncToolSpecification

       2. ToolCallbackConverterAutoConfiguration 收集ToolCallback和ToolCallbackProvider，转换为SyncToolSpecification

 最后，看看ServerMcpAnnotatedBeans的beansByAnnotation是怎么获得的

上图 MCP server的自动配置图3，负责beansByAnnotation的获取

McpServerAnnotationScannerAutoConfiguration  负责注解扫描，设定了扫描的注解

ServerAnnotatedMethodBeanPostProcessor  利用spring的机制BeanPostProcessor，该机制开发者在 Spring 容器实例化 Bean 之后、初始化方法（如 @PostConstruct、afterPropertiesSet、自定义 init-method）调用之前和之后，对 Bean 进行自定义的增强处理，ServerAnnotatedMethodBeanPostProcessor使用了调用后的机制点

AnnotatedMethodDiscovery  扫描BeanPostProcessor送过来的bean，获取bean所有目标注解

ServerMcpAnnotatedBeans  AnnotatedMethodDiscovery扫描回来的注解(集)，送个ServerMcpAnnotatedBeans，按注解类型分组bean，得到：

Map<Class<? extends Annotation>, List<Object>> beansByAnnotation，这个也是第二步用来构建能力规格的

web server

MCP server不是web服务，如 tomcat，web服务负责接收和处理web请求，因此，MCP 服务需要引用web服务，本节以webmvc为例分析一下MCP server与web服务的关联

上图是MCP server和web服务集成

MCP server应用引入spring-ai-starter-mcp-server-webmvc，引入tomcat

RouterFunctionMapping/AbstractHandlerMapping  spring-mvc负责路由请求的组件，get/post请求交给WebMvcStreamableServerTransportProvider构建的RouterFunction，最终调用McpSyncServer的能力