SpringAI + MCPServer + MCPClient 快速入門編寫大綱
源代碼地址:https://download.csdn.net/download/user_admin_god/90926893
1. 介紹
本文通過使用免費的智普AI的glm-4-flash模型,設計并實現了一個智能問答系統。在該系統中,我們編寫了一個工具接口,專門處理那些大模型無法解答的復雜問題,并將其集成到MCPServer中。MCPClient的Web端接口能夠智能地判斷何時使用智普AI的glm-4-flash模型,何時調用MCPServer的工具接口,從而確保在大模型無法處理的情況下,系統通過MCP實現高效的協調與問題解決。這一方案不僅提升了AI問答的能力,還能更靈活地應對多樣化的用戶需求。
1.1 目標
本文的主要目標是幫助開發者了解如何結合 SpringAI、MCPServer 和 MCPClient 來創建一個高效的分布式應用程序。通過這個快速入門指南,開發者將能夠:
- 迅速掌握這些組件的基本用法及如何將它們集成到實際項目中;
- 理解各個模塊之間的架構設計和通信流程;
- 學習如何通過SpringAI 提供的人工智能服務來增強應用功能;
- 輕松實現一個客戶端-服務器模型,并使用 SpringAI 實現智能化服務。
1.2 技術棧概述
(一)SpringAI
SpringAI 是一個基于 Spring 框架的人工智能服務構建工具,旨在幫助開發者通過簡單的配置和接口集成AI功能。無論是自然語言處理、圖像識別還是其他類型的智能服務,SpringAI 都提供了一套簡潔的API接口,支持與流行的AI平臺(如OpenAI)無縫對接。開發者可以通過它輕松實現復雜的AI任務。
SpringAI特點:
AI 模型集成與管理
Spring AI 提供對多種 AI 模型的支持,包括聊天模型、文本生成、圖像生成、語音識別與合成等,支持同步和流式 API 選項。
統一的 API 接口
框架提供跨 AI 提供商的可移植 API,支持 OpenAI、Anthropic、Google、Microsoft、ZhiPu等主流平臺,簡化了不同模型間的切換和集成。
向量數據庫支持
Spring AI 支持多種向量數據庫,如 Chroma、Milvus、PostgreSQL/PGVector、Redis、Weaviate 等,提供類似 SQL 的元數據過濾 API,方便進行高效的相似性搜索和數據存儲。
函數調用與工具集成
框架支持模型調用外部函數和工具,允許模型在推理過程中訪問實時數據或執行特定操作,增強了模型的實用性和靈活性。
結構化輸出與 POJO 映射
Spring AI 支持將 AI 模型的輸出映射到 Java POJO(Plain Old Java Object),實現結構化數據處理,方便與其他系統的集成。
提示詞模板與檢索增強生成(RAG)
框架提供提示詞模板功能,支持檢索增強生成(RAG)策略,將外部知識庫與 AI 模型結合,提高生成內容的準確性和相關性。
自動配置與 Spring Boot 集成
Spring AI 與 Spring Boot 無縫集成,支持自動配置和啟動器,使得 AI 功能的集成過程更加簡便和高效。
(二)MCPServer
MCPServer 是一個提供具體功能的服務端程序,類似于一個工具箱,里面包含了各種工具,例如文件讀寫、數據庫查詢、API 調用等。這些工具能夠使大型語言模型(LLMs)以標準化的方式訪問外部服務或數據源。
主要職責:
- 提供工具:Server 定義并實現具體的工具(
Tool
),這些工具構成了 MCP 的核心功能。例如,它可以是天氣查詢接口、數學運算功能、數據分析工具等。 - 處理請求:當 MCP Client 發送請求時,Server 負責解析請求內容,并根據需求執行相應的操作。
- 返回結果:完成操作后,Server 將處理結果返回給 Client。這可能包括從數據庫獲取信息、調用第三方 API,或進行其他數據處理任務。
(三)MCPClient
MCPClient 如同大型語言模型(LLM)的遙控器,負責向 Server 發送指令并接收結果。它的角色是將自然語言指令翻譯成 Server 能理解的請求格式。
主要職責:
- 構建請求:Client 根據用戶輸入或 LLM 的需求,構建符合 MCP 協議的請求。它需要理解用戶的意圖,并將其轉化為 Server 可執行的具體命令。
- 與 Server 通信:一旦構建好請求,Client 會通過網絡與 Server 建立連接并發送請求。通常,這一過程遵循 JSON-RPC 2.0 規范,以確保通信的標準化和一致性。
- 接收響應:在接收到 Server 的響應后,Client 負責解讀這些信息,并將有用的結果反饋給用戶或 LLM。
2. 環境準備
-
3.1 軟件要求
- JDK 21+:建議使用 JDK 21 或更高版本,可以通過華為云鏡像下載鏈接獲取。
- Spring Boot 3:推薦使用 Spring Boot 3.4.5 版本。Spring Boot 是一個非常流行的框架,能夠簡化 Java 后端應用的構建過程,自動配置和快速開發。
- Maven 3.9.2:Maven 是一種強大的構建和項目管理工具,用于依賴管理、構建配置及項目生命周期管理。建議使用 Maven 3.9.2 版本。
- IntelliJ IDEA 2024.3:這款IDE是目前最受開發者青睞的Java開發工具之一,具備強大的代碼編輯與調試功能,能夠極大地提高開發效率。
- MySQL 8.0+:MySQL 是一個開源的關系型數據庫管理系統,8.0 版本具有更高的性能和更強的特性支持。
- Mybatis-Plus 3.5.12:這是 Mybatis 的增強工具,能夠簡化數據庫操作,并提高代碼的可維護性。3.5.12 版本是本項目所推薦的版本。
-
3.2 安裝步驟
- 安裝 Java 開發環境
-
首先,下載并安裝 JDK 21+,確保系統的環境變量已經配置好,例如
JAVA_HOME
和PATH
,這樣 Java 可以在命令行中直接調用。 -
安裝完成后,通過執行以下命令驗證是否成功安裝:
java -version
輸出應該顯示 JDK 的版本信息。
- 配置 Spring Boot 項目
-
使用IntelliJ IDEA打開或創建一個新的 Spring Boot 項目。可以通過以下步驟快速創建 Spring Boot 項目:
- 打開 IntelliJ IDEA,選擇 File -> New Project。
-
在項目類型中選擇 Spring Initializr,并根據項目需求配置相關的參數。
-
完成項目初始化后,選擇正確的 Spring Boot 版本(3.4.5 推薦版本)。
- 添加必要的依賴項
在
pom.xml
文件中添加項目所需的依賴項,主要包括:- spring-boot-starter-web:提供構建 Web 應用的基礎功能,支持 RESTful 風格的 Web 服務。
- spring-retry:用于支持自動重試機制,可以幫助應用在失敗時進行重試,確保應用的高可用性。
- spring-cloud:提供 Spring Cloud 的相關組件,適合微服務架構的開發。
3. 項目創建結構
兩個模塊 mcp-client 和 mcp-server
├─mcp-client
│ ├─src
│ │ └─main
│ │ ├─java
│ │ │ └─com
│ │ │ └─gt
│ │ │ └─demo
│ │ │ └─mcpclient
│ │ │ ├─ai
│ │ │ ├─controller
│ │ │ ├─domain
│ │ │ ├─mapper
│ │ │ ├─service
│ │ │ │ └─impl
│ │ │ └─utils
│ │ └─resources
└─mcp-server├─src│ └─main│ ├─java│ │ └─com│ │ └─gt│ │ └─demo│ │ └─mcpserver│ │ ├─ai│ │ ├─controller│ │ ├─domain│ │ ├─mapper│ │ ├─proxy│ │ ├─service│ │ │ └─impl│ │ └─utils│ └─resources
4. 工程核心代碼
- 4.1 MCPServer Pom依賴
<properties><java.version>21</java.version><maven.compiler.source>21</maven.compiler.source><maven.compiler.target>21</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter</artifactId></dependency><dependency><groupId>cn.hutool</groupId><artifactId>hutool-all</artifactId><version>${hutool-all.version}</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-webflux</artifactId></dependency><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-server-webmvc</artifactId><version>${spring-ai.version}</version></dependency><dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><version>${mysql.version}</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>${lombok.version}</version></dependency><dependency><groupId>com.baomidou</groupId><artifactId>mybatis-plus-spring-boot3-starter</artifactId><version>${mybatis-plus.version}</version></dependency></dependencies>```- 4.2 **MCPServer Properties配置**```properties# 服務名稱spring.application.name=mcp-server# 服務運行使用端口server.port=8081# MySQL數據庫配置spring.datasource.url=jdbc:mysql://localhost:3306/test_admin_123?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8&autoReconnect=true&rewriteBatchedStatements=true&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=truespring.datasource.driverClassName=com.mysql.cj.jdbc.Driverspring.datasource.username=guotongspring.datasource.password=123456spring.datasource.hikari.maximum-pool-size=5# MyBatis# mapper.xml 位置mybatis-plus.mapper-locations=classpath:mapper/*.xml# 實體類位置mybatis-plus.type-aliases-package=com.example.entity# mybatis-plus的sql日志mybatis-plus.configuration.log-impl=org.apache.ibatis.logging.slf4j.Slf4jImpl# 下劃線轉駝峰自動mybatis-plus.configuration.map-underscore-to-camel-case=true# 邏輯刪除mybatis-plus.global-config.db-config.logic-not-delete-value=0mybatis-plus.global-config.db-config.logic-delete-field=isDelmybatis-plus.global-config.db-config.logic-delete-value=2-# thymeleaf 模板引擎-# 禁用緩存-開發的時候spring.thymeleaf.cache=false# sspring.thymeleaf.encoding=utf-8sys.conf.file.path=D:/confwindow.dev.file.path=D:/csp# mcp服務配置spring.ai.mcp.server.name=mcp-serverspring.ai.mcp.server.version=1.0.0spring.ai.mcp.server.description=AI服務spring.ai.mcp.server.type=asyncspring.ai.mcp.server.sse-message-endpoint=/mcp/messages```- 4.3 **MCPServer 模型工具接口**
```java@Component@Slf4jpublic class McpToolService {@Resourceprivate SysUserMapper sysUserMapper;@Tool(description = "根據傳入用戶名稱獲取AiGodLike系統用戶信息接口")public String getAiGodLikeUserInfoByName(@ToolParam(description = "隔壁老郭系統的用戶名稱(mack,jay,hans)") String userName) {log.info("隔壁老郭系統用戶名稱:{}", userName);List<SysUser> sysUserList = sysUserMapper.selectList(Wrappers.lambdaQuery(SysUser.class).like(SysUser::getUserName, userName));log.info("隔壁老郭系統用戶信息:{}", sysUserList);return "隔壁老郭系統用戶-王八蛋" + sysUserList;}}
- 4.4MCPServer 注冊工具接口
/*** @author makejava*/@SpringBootApplication@MapperScan("com.gt.demo.mcpserver.mapper")public class McpServerApplication {public static void main(String[] args) {SpringApplication.run(McpServerApplication.class, args);}@Beanpublic ToolCallbackProvider aiGodLikeUserInfoByNameTools(McpToolService mcpToolService) {return MethodToolCallbackProvider.builder().toolObjects(mcpToolService).build();}}```- 4.5 **MCPClient Pom配置**```xml<dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter</artifactId></dependency><!--糊涂萬能工具箱--><dependency><groupId>cn.hutool</groupId><artifactId>hutool-all</artifactId><version>${hutool-all.version}</version></dependency><!--流式響應式--><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-client-webflux</artifactId><version>${spring-ai.version}</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!--MCP客戶端--><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-client</artifactId><version>${spring-ai.version}</version></dependency><!--智普AI--><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-model-zhipuai</artifactId><version>${spring-ai.version}</version></dependency><!--Mysql數據庫--><dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><version>${mysql.version}</version></dependency><!--lombok--><!----><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>${lombok.version}</version></dependency><!-- https://mvnrepository.com/artifact/org.springframework.retry/spring-retry --><dependency><groupId>org.springframework.retry</groupId><artifactId>spring-retry</artifactId><version>2.0.12</version></dependency><!--mybatis-plus--><!----><dependency><groupId>com.baomidou</groupId><artifactId>mybatis-plus-spring-boot3-starter</artifactId><version>${mybatis-plus.version}</version></dependency></dependencies>
- 4.5 MCPClient application.properties
# 服務名稱
spring.application.name=mcp-client# 服務運行使用端口
server.port=8082# MySQL數據庫配置
spring.datasource.url=jdbc:mysql://localhost:3306/test_admin_123?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8&autoReconnect=true&rewriteBatchedStatements=true&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true
spring.datasource.driverClassName=com.mysql.cj.jdbc.Driver
spring.datasource.username=guotong
spring.datasource.password=123456
spring.datasource.hikari.maximum-pool-size=5# MyBatis# mapper.xml 位置
mybatis-plus.mapper-locations=classpath:mapper/*.xml
# 實體類位置
mybatis-plus.type-aliases-package=com.example.entity
# mybatis-plus的sql日志
mybatis-plus.configuration.log-impl=org.apache.ibatis.logging.slf4j.Slf4jImpl
# 下劃線轉駝峰自動
mybatis-plus.configuration.map-underscore-to-camel-case=true
# 邏輯刪除
mybatis-plus.global-config.db-config.logic-not-delete-value=0
mybatis-plus.global-config.db-config.logic-delete-field=isDel
mybatis-plus.global-config.db-config.logic-delete-value=2# thymeleaf 模板引擎
# 禁用緩存-開發的時候
spring.thymeleaf.cache=false
# s
spring.thymeleaf.encoding=utf-8
sys.conf.file.path=D:/conf
window.dev.file.path=D:/cspspring.ai.mcp.client.enabled=true
spring.ai.mcp.client.name=my-mcp-client
spring.ai.mcp.client.version=1.0.0
spring.ai.mcp.client.request-timeout=30s
spring.ai.mcp.client.type=SYNC
spring.ai.mcp.client.sse.connections.server1.url=http://localhost:8081spring.ai.zhipuai.api-key=0baf0413c6c0c6b0d011ae8489a2c9c0.ejfhVbF6Z653Cy1I
spring.ai.zhipuai.base-url=https://open.bigmodel.cn/api/paas
spring.ai.zhipuai.embedding.options.model=glm-4-flash
spring.ai.zhipuai.chat.options.model=glm-4-flash
spring.ai.zhipuai.chat.options.temperature=0.7
- 4.5 MCPClient 調用AI模型問答
/*** AI---式調用問答*/@RequestMapping(value = "/jsonToSay", method = RequestMethod.GET)public String jsonToSay(@RequestParam String question) {var chatClient = chatClientBuilder.defaultTools(toolCallbackProvider).build();System.out.println("=== 聊天模式已啟動(=====");// 調用 AI 并打印回復String content = chatClient.prompt(question).call().content();System.out.println("\n>>> AI 回復: " + content);return content;}
5. 運行與測試
- 5.1 啟動Spring Boot應用
- 運行MCPServer和MCPClient應用程序。
關鍵會打印:MCPClient 注冊到MCPServer上了
- 運行MCPServer和MCPClient應用程序。
2025-05-28T14:41:46.290+08:00 INFO 1828 — [mcp-server] [nio-8081-exec-5] i.m.server.McpAsyncServer : Client initialize request - Protocol: 2024-11-05, Capabilities: ClientCapabilities[experimental=null, roots=null, sampling=null], Info: Implementation[name=my-mcp-client - server1, version=1.0.0]
- 5.2 測試API調用
- 使用Postman或類似工具向MCPClient發送請求,驗證服務器和AI服務是否正常工作。
- 問一個不會協調去掉MCPServer工具的問題,全都是走大模型完成回答
- 問一個大模型完成回答不了的,滿足MCPServer工具的語義的問題,走MCPServer工具