简介
spring ai alibaba是java的ai agent框架，本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理，不仅指导agent的开发，更可以改造框架，增加新特性
系列内容：
系列(一) 架构 完成
系列(二) 调用
I 工具
II-1 MCP MCP能力，工具，资源，Prompts，sampling，。。。；springboot自动配置；
-2 分布式 MCP
-3 MCP security
III skills 完成
系列(六) RAG
I 知识库，文档读取，分块；嵌入，向量store
检索，增强生成，模块化
II 混合检索，融合重排
系列(三) 模型
I 模型模型，chat模型; chat client，提示词，消息，结构化输出
II advisor组件；chat记忆，会话管理
系列(四) graph 图结构，节点和边；StateGraph，CompiledGraph；图执行
系列(五) I agent，ReactAgent；另外FlowAgain，A2A agent放在MAS
II 钩子和拦截器；上下文工程
系列(七) MAS
I FlowAgent，sub agent，agent tool；handoffs模式，toolcalling模式；
II A2A，分布式agent；agent集群，AP2AP
III 集成agentscope-java，agentic模式，消息hub
系列(八) 模型评估和观测
系列(九) agent管理平台(admin) agent发布，列表，提示词管理，会话管理，skill管理，MCP服务管理；评估；观测
其他 多模态
本文分析外部调用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为例
SpringAiSyncToolProvider 构建tool能力规格的对象，从ServerMcpAnnotatedBeans的beansByAnnotation获取带标注@MCPTool的bean，通过反射获取数据，构建tool能力规格对象 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的能力