基于Spring AI Alibaba实现MCP-Stdio的全栈解析与实践指南

一、MCP协议核心原理

1.1 MCP架构设计理念

Model Context Protocol（模型上下文协议）是一种面向AI服务编排的通信协议，其核心设计目标在于：

1. 服务解耦：分离模型服务与业务逻辑
2. 动态扩展：支持运行时服务发现与加载
3. 协议中立：兼容多种传输协议（HTTP/STDIO/WebSocket）
4. 上下文感知：维护多轮对话的会话状态

协议架构示意图：

MCP协议

客户端

路由网关

模型服务1

模型服务2

工具服务

大模型推理

向量检索

外部API集成

1.2 协议核心组件

组件	功能描述	实现示例
Service Registry	服务注册与发现	Spring Cloud ServiceRegistry
Protocol Adapter	协议转换层	STDIO/HTTP适配器
Context Manager	会话上下文管理	Redis会话存储
Tool Executor	外部工具执行引擎	MethodToolCallbackProvider

二、服务端实现解析

2.1 服务启动入口

@SpringBootApplication
public class McpServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

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

关键配置解析：

• @SpringBootApplication：启用自动配置与组件扫描
• ToolCallbackProvider：注册工具方法到MCP上下文
• MethodToolCallbackProvider：基于反射的工具方法发现机制

2.2 天气服务实现

2.2.1 数据模型定义

@JsonIgnoreProperties(ignoreUnknown = true)
public record WeatherData(
    @JsonProperty("latitude") Double latitude,
    @JsonProperty("current") CurrentWeather current,
    @JsonProperty("daily") DailyForecast daily) {

    public record CurrentWeather(
        @JsonProperty("temperature_2m") Double temperature,
        @JsonProperty("weather_code") Integer weatherCode) {}
    
    public record DailyForecast(
        @JsonProperty("time") List<String> dates,
        @JsonProperty("temperature_2m_max") List<Double> maxTemps) {}
}

模型设计特点：

• 使用Java Record简化DTO定义
• @JsonIgnoreProperties增强反序列化容错
• 嵌套结构反映API响应格式

2.2.2 工具方法注册

@Tool(description = "获取指定经纬度的天气预报")
public String getWeatherForecastByLocation(
    @ToolParam(description = "纬度") double latitude,
    @ToolParam(description = "经度") double longitude) {
    
    // 调用OpenMeteo API
    WeatherData data = restClient.get()
        .uri("/forecast?latitude={lat}&...", latitude, longitude)
        .retrieve()
        .body(WeatherData.class);
    
    // 构建格式化响应
    return buildWeatherReport(data);
}

注解解析：

• @Tool：声明方法为可调用工具
• @ToolParam：定义参数元数据
• 方法返回String将作为大模型的上下文输入

2.3 配置优化实践

application.yml关键配置：

spring:
  main:
    web-application-type: none # 禁用Web容器
    banner-mode: off # 关闭启动Banner
  ai:
    mcp:
      server:
        name: weather-service
        stdio: true # 启用STDIO通信

配置说明：

• 禁用Web容器以降低资源消耗
• 关闭Banner保证STDIO输出纯净
• 命名服务便于客户端发现

三、客户端实现解析

3.1 客户端启动配置

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Bean
    CommandLineRunner queryRunner(ChatClient.Builder builder) {
        return args -> {
            ChatClient client = builder.build();
            String response = client.prompt("北京的天气如何？").call().content();
            System.out.println(response);
        };
    }
}

执行流程：

1. 初始化Spring上下文
2. 构建ChatClient实例
3. 发送自然语言查询
4. 打印模型响应

3.2 服务发现机制

mcp-servers-config.json配置：

{
  "mcpServers": {
    "weather": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/server.jar"
      ]
    }
  }
}

配置要点：

• 定义服务启动命令
• 支持环境变量注入
• 允许多服务并行注册

3.3 通信协议处理

STDIO通信流程：

客户端 服务端 启动子进程 写入JSON请求 返回JSON响应 持续交互 loop [保持连接] 客户端 服务端

协议特点：

• 基于标准输入输出的双向通信
• 使用换行符分隔消息
• JSON格式编码数据

四、核心功能实现

4.1 天气数据获取

API请求构造示例：

String uri = UriComponentsBuilder.fromPath("/forecast")
    .queryParam("latitude", latitude)
    .queryParam("longitude", longitude)
    .queryParam("current", "temperature_2m,weather_code")
    .queryParam("daily", "temperature_2m_max")
    .queryParam("timezone", "auto")
    .build()
    .toUriString();

参数说明：

• 经纬度精确到小数点后4位
• 选择需要的天气要素
• 自动时区识别

4.2 数据格式化处理

天气报告生成逻辑：

private String buildWeatherReport(WeatherData data) {
    StringBuilder sb = new StringBuilder();
    sb.append("当前天气：\n")
      .append(String.format("温度：%.1f°C\n", data.current().temperature()))
      .append(String.format("天气状况：%s\n", parseWeatherCode(data.current().weatherCode())));
    
    sb.append("\n未来三天预报：\n");
    for (int i = 0; i < 3; i++) {
        sb.append(String.format("%s：最高%.1f°C\n", 
            formatDate(data.daily().dates().get(i)),
            data.daily().maxTemps().get(i)));
    }
    return sb.toString();
}

格式化要点：

• 数值精度控制
• 天气代码转自然语言
• 日期本地化处理

4.3 异常处理机制

try {
    return restClient.get()
        .uri(/* ... */)
        .retrieve()
        .body(WeatherData.class);
} catch (RestClientException e) {
    log.error("API请求失败", e);
    return generateFallbackData(latitude, longitude);
}

private WeatherData generateFallbackData(double lat, double lon) {
    // 生成模拟数据
    return new WeatherData(lat, lon, 
        new CurrentWeather(25.5, 0),
        new DailyForecast(List.of("2024-01-01"), List.of(26.0)));
}

容错策略：

• 异常捕获与日志记录
• 降级数据生成
• 客户端超时控制

五、高级功能扩展

5.1 多服务协同

服务编排示例：

@Tool(description = "综合天气分析")
public String analyzeWeather(String location) {
    // 调用地理编码服务
    Coordinate coord = geoService.geocode(location);
    
    // 获取实时天气
    String current = weatherService.getCurrentWeather(coord);
    
    // 获取空气质量
    String aqi = airQualityService.getAqiReport(coord);
    
    // 生成分析报告
    return analysisModel.analyze(current, aqi);
}

协同流程：

1. 地址解析为经纬度
2. 并行获取多源数据
3. 综合数据分析
4. 生成最终报告

5.2 性能优化策略

5.2.1 缓存机制

@Cacheable(value = "weather", key = "#lat + ',' + #lon")
public WeatherData getWeather(double lat, double lon) {
    // API调用
}

缓存配置：

• 使用Redis分布式缓存
• 设置10分钟过期时间
• 定义缓存雪崩保护

5.2.2 批量请求处理

@Tool(description = "批量获取天气")
public Map<String, String> batchGetWeather(List<Coordinate> coords) {
    return coords.parallelStream()
        .collect(Collectors.toMap(
            c -> c.toString(),
            c -> getWeather(c.lat(), c.lon())
        );
}

优化点：

• 并行流处理
• 连接池优化
• 请求合并