SpringAI MCP介紹

Spring AI MCP 為模型上下文協議提供 Java 和Spring 框架集成、它使 SpringAI 應用程序能夠通過標準化的接口與不同的數據源和工是進行交互，支持同步和異步通信模式。整體架構如下:

Spring Al 通過以下 Spring Boot 啟動器提供 MCP 集成：

客戶端啟動器

• spring-ai-starter-mcp-client 核心啟動器提供 STDIO 和基于 HTTP 的 SSE 支持。
• spring-ai-starter-mcp-client-webflux 基于WebFlux的SSE流式傳輸實現

服務端啟動器

• spring-ai-starter-mcp-server 核心服務器具有 STDIO 傳輸支持
• spring-ai-starter-mcp-server-webmvc 基于Spring MVC的SSE流式傳輸實現
• spring-ai-starter-mcp-server-webflux 基于WebFlux的SSE流式傳輸實現

基于stdio標準流

MCP 服務端

基于 stdio 的實現是最常見的 MCP客戶端方案，它通過標準輸入輸出流與 MCP 服務器進行通信，這種方式簡單直觀，能夠直接通過進程間通信實現數據交互，避免了額外的網絡通信開銷，特別適用于本地部署的MCP服務器，可以在司一臺機器上啟動 MCP 服務器進程，與客戶端無縫對接。

引入依賴

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
  <version>1.0.0-M6</version>
</dependency>

配置MCP服務端

spring:
  application:
    name: mcp-server
  main:
    web-application-type: none # 必須禁用web應用類型
    banner-mode: off # 禁用banner
  ai:
    mcp:
      server:
        stdio: true # 啟用stdio模式
        name: mcp-server # 服務器名稱
        version: 0.0.1 # 服務器版本

實現MCP工具

@Tool 是 SpingAI MCP框架中用于快速暴露業務能力為AI 工具的核心注解，該注解實現Java方法與MCP協議工具的自動銀蛇，并且可以通過注解的屬性description，有助于人工智能模型根據用戶輸入的信息決定是否調用這些工具，并返回相應的結果.

@Service
public class OpenMeteoService {

    @Tool(description = "根據經緯度獲取天氣預報")
    public String getAirQuality(
        @ToolParameter(description = "緯度，例如：39.9042") String latitude,
        @ToolParameter(description = "經度，例如：116.4074") String longitude) {

        // 模擬數據，實際應用中應調用真實API
        return "當前位置（緯度：" + latitude + "，經度：" + longitude + "）的天氣信息：\n 多云轉陰";
    }
}

這個工具方法主要是用來根據經緯度獲取天氣預報的，這里為了方便演示，寫了模擬數據

注冊MCP工具

最后向 MCP 服務注冊剛剛寫的工具：

    @Bean
    public ToolCallbackProvider serverTools(OpenMeteoService openMeteoService) {
        return MethodToolCallbackProvider.builder().toolObjects(openMeteoService).build();
    }

這段代碼定義了一個 Spring 的 Bean，用于將查詢天氣服務 OpenMeteoService 中所有用 @Tool 注解標記的方法注冊為工具，供 AI 模型調用。

ToolCallbackProvider 是Spring Al 中的一個接口，用于定義工具發現機制，主要負責將那些使用
@Tool 注解標記的方法轉換為工具回調對象，并提供給 ChatClient 或ChatModel 使用，以便 AI 模型能夠在對話過程中調用這些工具。

MCP 客戶端

引入依賴

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

配置MCP服務器

因為服務端是通過 stdio 實現的，需要在 application.yml 中配置MCP服務器的一些參數：

spring:
  ai:
    mcp:
      client:
        stdio:
          # 指定MCP服務器配置文件
          servers-configuration: classpath:/mcp-servers-config.json
  mandatory-file-encoding: UTF-8

其中 mcp-servers-config.json 的配置如下：

{
  "mcpServers": {
    "weatherServer": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
        "/Users/gulihua/Documents/mcp-server/target/mcp-server-0.0.1-SNAPSHOT.jar"
      ],
      "env": {}
    }
  }
}

這個配置文件設置了MCP客戶端的基本配置，包括 Java 命令參數，服務端 jar 包的絕對路徑等，上述的 JSON 配置文件也可以直接寫在 apllication.yaml 里，效果是一樣的。

    mcp:
      client:
        stdio:
         connections:
           server1:
             command: java
             args:
               - -Dspring.ai.mcp.server.stdio=true
               - -Dspring.main.web-application-type=none
               - -Dlogging.pattern.console=
               - -jar
               - /Users/gulihua/Documents/mcp-server/target/mcp-server-0.0.1-SNAPSHOT.jar

客戶端我們使用問里巴巴的通義千問模型，所以引入 spring-ai-alibaba-starter 依賴，如果使用的是其他的模型，也可以使用對應的依賴項，比加 openAI 引入 sprine-ai-openai-spring-boot-starter 這個依賴就行了

配置大模型的密鑰等信息：

spring:
  ai:
    dashscope:
      api-key: ${通義千問的key}
      chat:
        options:
          model: qwen-max

初始化聊天客戶端

@Bean
public ChatClient initChatClient(ChatClient.Builder chatClientBuilder,
                                 ToolCallbackProvider mcpTools) {
    return chatClientBuilder
    .defaultTools(mcpTools)
    .build();
}

該代碼定義了一個 spring pean，用于初始化一個AI聊天客戶端，里面有兩個參數，chatcient.Buinider 是 SpnngAI 提供的AI聊天客戶端構建器，用于構建 ChatCient實例，是由 Spring AI 自動注入的，另一個是 ToolCallbackProvider，用于從MCP客服端發現并獲取AI工具。

然后就可以通過這個 chatclient 去調用了：

chatClient.prompt()
.user(request.getContent())
.call()
.content();

基于SSE

MCP服務端

除了基于 stdio 的實現外，Spring Al還提供了基于 Server-Sent vents(SSE)的 MCP客戶端方案。相較于 stdio方式，SSE 更適用于遠程部署的 MCP 服務器，客戶端可以通過標準 HTTP 協議與服務器建立連接，實現單向的實時數據推送。基于 SSE的 MCP 服務器支持被多個客戶端的遠程調用。

引入依賴

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-mcp-server-webflux-spring-boot-starter</artifactId>
  <version>1.0.0-M6</version>
</dependency>

配置MCP服務端

server:
  port: 8090

spring:
  application:
    name: mcp-server
  ai:
    mcp:
      server:
        name: mcp-server # MCP服務器名稱
        version: 0.0.1   # 服務器版本號

除了引入的依賴包不一樣，以及配置文件不同，其他的不需要修改。

MCP 客戶端

引入依賴

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

配置MCP服務器

因為服務端是通過SSE實現的，需要在 application.yml 中配置MCP服務器的URL端口：

spring:
  ai:
    mcp:
      client:
        enabled: true
        name: mcp-client
        version: 1.0.0
        request-timeout: 30s
        type: ASYNC # 類型同步或者異步
        sse:
          connections:
            server1:
              url: http://localhost:8090

和MCP服務端的修改一樣，除了依賴和配置的修改，其他的也不需要調整

注意

除了上面基礎的用法和配置，還應該考慮以下幾個方面:

• 工具設計
  • 每個工具方法應具備明確的功能定義及參數說明。
  • 使用 @Tool 注解提供清晰、完整的工具描述，便于自動生成文檔或展示給前端。
  • 使用 @ToolParameter 注解詳細說明每個參數的用途，提升使用者的理解與正確性。
• 錯誤處理
  • 應全面捕獲并妥善處理可能出現的異常，防止服務崩潰。
  • 返回結構化、具備可讀性的錯誤信息，便于客戶端識別錯誤原因并進行相應處理。
• 性能優化
  • 對于可能耗時的任務，建議使用異步處理機制，避免阻塞主線程，
  • 設置合理的超時時間，防止客戶端長時間等待，提高系統響應性和穩定性。
• 安全性考慮
  • 對涉及敏感資源或關鍵操作的工具方法，應添加嚴格的權限校驗邏輯
  • 禁止在工具方法中執行高風險操作(如執行任意系統命令)，以防止安全洞。
• 部署策略
  • Stdio 模式：適用于嵌入式場景，可作為客戶端的子進程運行，便于集成與資源控制。
  • SSE模式：更適合部署為獨立服務，支持多個客戶端同時訪問，適用于需要持續通信的遠程調用場景。