基于Spring AI Alibaba实现MCP-Stdio的全栈解析与实践指南
一、MCP协议核心原理
1.1 MCP架构设计理念
Model Context Protocol（模型上下文协议）是一种面向AI服务编排的通信协议，其核心设计目标在于：
- 服务解耦：分离模型服务与业务逻辑
- 动态扩展：支持运行时服务发现与加载
- 协议中立：兼容多种传输协议（HTTP/STDIO/WebSocket）
- 上下文感知：维护多轮对话的会话状态
协议架构示意图：
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);}@Beanpublic 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 APIWeatherData 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 # 关闭启动Bannerai:mcp:server:name: weather-servicestdio: true # 启用STDIO通信
配置说明：
- 禁用Web容器以降低资源消耗
- 关闭Banner保证STDIO输出纯净
- 命名服务便于客户端发现
三、客户端实现解析
3.1 客户端启动配置
@SpringBootApplication
public class Application {public static void main(String[] args) {SpringApplication.run(Application.class, args);}@BeanCommandLineRunner queryRunner(ChatClient.Builder builder) {return args -> {ChatClient client = builder.build();String response = client.prompt("北京的天气如何？").call().content();System.out.println(response);};}
}
执行流程：
- 初始化Spring上下文
- 构建ChatClient实例
- 发送自然语言查询
- 打印模型响应
3.2 服务发现机制
mcp-servers-config.json配置：
{"mcpServers": {"weather": {"command": "java","args": ["-jar","/path/to/server.jar"]}}
}
配置要点：
- 定义服务启动命令
- 支持环境变量注入
- 允许多服务并行注册
3.3 通信协议处理
STDIO通信流程：
协议特点：
- 基于标准输入输出的双向通信
- 使用换行符分隔消息
- 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);
}
协同流程：
- 地址解析为经纬度
- 并行获取多源数据
- 综合数据分析
- 生成最终报告
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()));
}
优化点：
- 并行流处理
- 连接池优化
- 请求合并