Spring AI 实战：MCP 协议原理、Server 与 Client 完整搭建全流程【实战案例】

{
  "name": "get_weather",
  "description": "查询指定城市的当前天气情况，支持选择温度单位。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称，例如 'Beijing' 或 'Shanghai'"
      },
      "unit": {
        "type": "string",
        "description": "温度单位，可选值为 'celsius' 或 'fahrenheit'",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["city"]
  }
}

Weiz-SpringAI-MCP/
├── pom.xml                 父工程（统一版本）
├── Weiz-SpringAI-MCP-Server/   MCP 服务端
└── Weiz-SpringAI-MCP-Client/   MCP 客户端（Agent）

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>Weiz-SpringAI-MCP</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </parent>
    <artifactId>Weiz-SpringAI-MCP-Server</artifactId>
    <name>Weiz-SpringAI-MCP-Server</name>
    <description>MCP Server 提供天气查询和景点推荐工具</description>

    <properties>
        <java.version>17</java.version>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
    </properties>

    <dependencies>
        <!-- Spring Web 依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- MCP Server 依赖 -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

#
spring.application.name=Weiz-SpringAI-MCP-Server
server.port=8081

# MCP Server
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.name=trip-tools-server
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.stio=false
spring.ai.mcp.server.sse-message-endpoint=/mcp/message
spring.ai.mcp.server.sse-endpoint=/mcp/sse

#
logging.level.org.springframework.ai=DEBUG
logging.level.com.example=DEBUG

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>Weiz-SpringAI-MCP</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </parent>

    <artifactId>Weiz-SpringAI-MCP-Client</artifactId>
    <name>Weiz-SpringAI-MCP-Client</name>
    <description>MCP Client 集成 MCP Server 工具到 Agent</description>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- 智谱 AI -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-zhipuai</artifactId>
        </dependency>

        <!-- MCP Client 依赖 -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-mcp-client</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>
</project>

#
spring.application.name=Weiz-SpringAI-MCP-Client
server.port=8080

# AI
spring.ai.zhipuai.api-key=858b5b317ac7449b9e3dc9c75baa8ecf.t3KDMKdKERWDQPed
spring.ai.zhipuai.base-url=https://open.bigmodel.cn/api/paas
spring.ai.zhipuai.chat.options.model=GLM-4-Flash
spring.ai.zhipuai.chat.options.temperature=0.7

# MCP Client HTTP/SSE
spring.ai.mcp.client.sse.connections.trip-tools.url=http://localhost:8081
spring.ai.mcp.client.type=SYNC
#
logging.level.org.springframework.ai=DEBUG
logging.level.com.example=DEBUG

package com.example.weizspringai.mcp;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;

/**
 * 天气查询 MCP 工具
 * 通过 MCP 协议暴露，供 Client 调用
 */
@Component
public class WeatherMcpTool {

    @Tool(description = "获取指定城市的实时天气信息，返回天气状况、温度范围、空气质量、出行建议")
    public String getWeather(
            @ToolParam(description = "城市名称，支持中文，如：北京、上海、广州、成都、西安、杭州") String city
    ) {
        // 模拟天气 API 调用（实际项目替换为真实 API）
        return simulateWeatherApi(city);
    }

    private String simulateWeatherApi(String city) {
        String weatherData;
        if (city.contains("北京")) {
            weatherData = "晴，气温 18-25°C，空气质量优，紫外线较强，建议防晒";
        } else if (city.contains("上海")) {
            weatherData = "多云，气温 20-28°C，空气质量良，有轻微雾霾";
        } else if (city.contains("广州")) {
            weatherData = "小雨，气温 22-26°C，湿度 85%，建议携带雨具";
        } else if (city.contains("成都")) {
            weatherData = "阴天，气温 16-22°C，空气质量良，适合室内外活动";
        } else if (city.contains("西安")) {
            weatherData = "晴朗，气温 15-23°C，空气质量良，适合户外观光";
        } else if (city.contains("杭州")) {
            weatherData = "多云转晴，气温 19-27°C，空气质量优，西湖游览佳日";
        } else {
            weatherData = "晴，气温 20-25°C，空气质量良，适合出行";
        }

        return String.format(
                "{\"city\": \"%s\", \"weather\": \"%s\", \"source\": \"实时天气数据\"}",
                city, weatherData
        );
    }
}

package com.example.weizspringai.mcp;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;

import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

/**
 * 景点推荐 MCP 工具
 * 通过 MCP 协议暴露，供 Client 调用
 */
@Component
public class AttractionMcpTool {

    // 模拟景点数据库（与前文一致）
    private static final Map<String, List<AttractionInfo>> ATTRACTIONS_DB = Map.of(
            "北京", List.of(
                    new AttractionInfo("故宫", "人文", "5.0", "3-4小时", "世界文化遗产，明清皇家宫殿"),
                    new AttractionInfo("长城（八达岭）", "人文", "5.0", "半天", "世界七大奇迹之一"),
                    new AttractionInfo("颐和园", "人文", "4.8", "2-3小时", "皇家园林博物馆"),
                    new AttractionInfo("天坛", "人文", "4.7", "2小时", "明清祭天场所"),
                    new AttractionInfo("北京环球影城", "娱乐", "4.9", "全天", "顶级主题乐园")
            ),
            "上海", List.of(
                    new AttractionInfo("外滩", "人文", "4.9", "1-2小时", "万国建筑博览群"),
                    new AttractionInfo("上海迪士尼", "娱乐", "4.8", "全天", "亚洲顶级迪士尼乐园"),
                    new AttractionInfo("豫园", "人文", "4.6", "2小时", "江南古典园林"),
                    new AttractionInfo("东方明珠", "人文", "4.7", "2小时", "上海地标建筑")
            ),
            "成都", List.of(
                    new AttractionInfo("大熊猫繁育研究基地", "自然", "4.9", "半天", "近距离观赏大熊猫"),
                    new AttractionInfo("宽窄巷子", "人文", "4.7", "2-3小时", "成都历史文化街区"),
                    new AttractionInfo("都江堰", "人文", "4.8", "半天", "世界文化遗产水利工程"),
                    new AttractionInfo("青城山", "自然", "4.7", "全天", "道教名山，天然氧吧")
            ),
            "西安", List.of(
                    new AttractionInfo("兵马俑", "人文", "5.0", "半天", "世界第八大奇迹"),
                    new AttractionInfo("大雁塔", "人文", "4.8", "2小时", "唐代佛教建筑"),
                    new AttractionInfo("古城墙", "人文", "4.7", "2-3小时", "中国现存最完整古城墙"),
                    new AttractionInfo("大唐不夜城", "人文", "4.8", "晚上", "沉浸式唐文化体验")
            ),
            "杭州", List.of(
                    new AttractionInfo("西湖", "自然", "5.0", "半天", "世界文化遗产，人间天堂"),
                    new AttractionInfo("灵隐寺", "人文", "4.7", "2小时", "千年古刹"),
                    new AttractionInfo("宋城", "娱乐", "4.6", "全天", "大型演艺主题公园"),
                    new AttractionInfo("西溪湿地", "自然", "4.5", "半天", "城市湿地公园")
            )
    );

    @Tool(description = "根据城市和景点类型偏好推荐热门景点，返回景点名称、类型、评分、建议游览时长、景点简介")
    public String recommendAttractions(
            @ToolParam(description = "城市名称，如：北京、上海、成都、西安、杭州") String city,
            @ToolParam(description = "景点类型偏好：人文、自然、娱乐；不填则推荐全部类型", required = false) String preference
    ) {
        List<AttractionInfo> attractions = ATTRACTIONS_DB.getOrDefault(city, List.of());

        if (attractions.isEmpty()) {
            return String.format("{\"error\": \"暂无 %s 的景点数据，请尝试其他城市\"}", city);
        }

        if (preference != null && !preference.isEmpty()) {
            attractions = attractions.stream()
                    .filter(a -> a.type.contains(preference) || preference.contains(a.type))
                    .collect(Collectors.toList());
        }

        StringBuilder result = new StringBuilder();
        result.append("{\"city\": \"").append(city).append("\", ");
        if (preference != null && !preference.isEmpty()) {
            result.append("\"preference\": \"").append(preference).append("\", ");
        }
        result.append("\"attractions\": [");

        for (int i = 0; i < attractions.size(); i++) {
            AttractionInfo a = attractions.get(i);
            result.append(String.format(
                    "{\"name\": \"%s\", \"type\": \"%s\", \"rating\": \"%s\", \"duration\": \"%s\", \"intro\": \"%s\"}",
                    a.name, a.type, a.rating, a.duration, a.intro
            ));
            if (i < attractions.size() - 1) {
                result.append(", ");
            }
        }

        result.append("], \"count\": ").append(attractions.size()).append("}");
        return result.toString();
    }

    private static class AttractionInfo {
        String name;
        String type;
        String rating;
        String duration;
        String intro;

        AttractionInfo(String name, String type, String rating, String duration, String intro) {
            this.name = name;
            this.type = type;
            this.rating = rating;
            this.duration = duration;
            this.intro = intro;
        }
    }
}

package com.example.weizspringai.config;

import com.example.weizspringai.mcp.AttractionMcpTool;
import com.example.weizspringai.mcp.WeatherMcpTool;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * MCP Server 配置
 * 自动注册工具到 MCP Server
 */
@Configuration
public class McpServerConfig {

    @Bean
    public ToolCallbackProvider weatherToolProvider(WeatherMcpTool weatherMcpTool) {
        return MethodToolCallbackProvider.builder()
                .toolObjects(weatherMcpTool)
                .build();
    }

    @Bean
    public ToolCallbackProvider attractionToolProvider(AttractionMcpTool attractionMcpTool) {
        return MethodToolCallbackProvider.builder()
                .toolObjects(attractionMcpTool)
                .build();
    }

}

#
spring.application.name=Weiz-SpringAI-MCP-Client
server.port=8080

# AI
spring.ai.zhipuai.api-key=858b5b317ac7449b9e3dc9c75baa8ecf.t3KDMKdKERWDQPed
spring.ai.zhipuai.base-url=https://open.bigmodel.cn/api/paas
spring.ai.zhipuai.chat.options.model=GLM-4-Flash
spring.ai.zhipuai.chat.options.temperature=0.7

# MCP Client HTTP/SSE
spring.ai.mcp.client.sse.connections.trip-tools.url=http://localhost:8081
spring.ai.mcp.client.type=SYNC
#
logging.level.org.springframework.ai=DEBUG
logging.level.com.example=DEBUG

package com.example.weizspringai.service;

import lombok.RequiredArgsConstructor;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;
import org.springframework.stereotype.Service;

/**
 * 基于 MCP 的智能行程规划 Agent
 * 通过 MCP Client 动态发现并调用 MCP Server 提供的工具
 */
@Service
@RequiredArgsConstructor
public class McpTripAgentService {

    private final ChatClient.Builder chatClientBuilder;
    private final SyncMcpToolCallbackProvider toolCallbackProvider;

    /**
     * 带 MCP 工具调用的行程规划
     * @param demand 用户出行需求
     * @return 结合实时数据的个性化行程规划
     */
    public String planTripWithMcpTools(String demand) {
        // 定义 Agent 行为规则
        String systemPrompt = """
            你是一个具备工具调用能力的智能行程规划 Agent，核心规则如下：

            1. 当用户询问天气时，必须调用 getWeather 工具获取实时天气数据；
            2. 当用户需要景点推荐时，必须调用 recommendAttractions 工具获取景点信息；
            3. 结合天气数据和景点信息，生成完整的行程规划建议；
            4. 行程安排要考虑天气因素（如雨天推荐室内景点）；
            5. 所有实时信息必须通过工具获取，严禁编造数据。

            回复风格：简洁专业，突出实用信息。
            """;

        // 构建 ChatClient 并自动注册 MCP 工具
        ChatClient chatClient = chatClientBuilder
                .defaultSystem(systemPrompt)
                .defaultTools(toolCallbackProvider.getToolCallbacks())
                .build();

        // 调用大模型
        return chatClient.prompt()
                .user(demand)
                .call()
                .content();
    }
}

package com.example.weizspringai.controller;


import com.example.weizspringai.service.McpTripAgentService;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

/**
 * MCP Agent 接口
 */
@RestController
@RequestMapping("/agent/mcp")
@RequiredArgsConstructor
public class McpAgentController {

    private final McpTripAgentService mcptripAgentService;

    /**
     * 带 MCP 工具调用的行程规划接口
     * @param demand 用户出行需求
     * @return 智能行程规划结果
     */
    @GetMapping("/plan")
    public Map<String, String> planTrip(@RequestParam("demand") String demand) {
        String tripPlan = mcptripAgentService.planTripWithMcpTools(demand);
        return Map.of(
                "userDemand", demand,
                "tripPlan", tripPlan,
                "agentType", "基于 MCP 的智能行程规划 Agent"
        );
    }
}

{
  "userDemand": "北京明天天气怎么样？适合出行吗？",
  "agentType": "基于 MCP 的智能行程规划 Agent",
  "tripPlan": "北京明天天气晴朗，气温在18-25°C之间，空气质量优，紫外线较强，建议外出时做好防晒措施。适合出行。"
}

{
  "userDemand": "推荐几个北京的人文景点，最好评分高的",
  "agentType": "基于 MCP 的智能行程规划 Agent",
  "tripPlan": "根据您的要求，我为您推荐了几个北京的人文景点，其中包括故宫、长城（八达岭）、颐和园和天坛。这些景点都是世界文化遗产，具有很高的历史和文化价值。故宫是世界文化遗产，明清皇家宫殿，建议游览时长为3-4小时；长城（八达岭）是世界七大奇迹之一，建议游览时长为半天；颐和园是皇家园林博物馆，建议游览时长为2-3小时；天坛是明清祭天场所，建议游览时长为2小时。您可以根据自己的兴趣和时间进行选择。"
}

{
  "userDemand": "帮我规划北京周末两天游，先看看天气，再推荐几个人文景点，生成完整行程",
  "agentType": "基于 MCP 的智能行程规划 Agent",
  "tripPlan": "北京周末两天游行程规划如下：\n\n第一天：\n- 上午：参观故宫，建议游览3-4小时，了解明清皇家宫殿的历史和文化。\n- 下午：游览长城（八达岭），半天时间足够，感受世界七大奇迹之一的壮丽。\n\n第二天：\n- 上午：游览颐和园，建议游览2-3小时，欣赏皇家园林的美丽风光。\n- 下午：参观天坛，建议游览2小时，了解明清祭天的历史和文化。\n\n请注意，北京天气晴朗，气温18-25°C，紫外线较强，建议外出时做好防晒措施。"
}