Spring Boot MCP（stdio）工具实现的注意事项（踩坑总结）
随着 MCP（Model Context Protocol）的普及，越来越多的人开始使用Spring Boot + MCP来给 AI 工具（如TRAE、Claude Desktop）扩展能力。
但stdio 模式的 MCP和我们熟悉的 Web Spring Boot完全不是一回事，稍不注意就会出现：
- Tool 调用返回
null - MCP Client 报 JSON 解析错误
- 工具列表加载失败
- 中文参数直接乱码
本文结合真实踩坑经验，总结Spring Boot 实现 MCP（stdio）工具时的关键注意事项。
一、首先要明确：stdio MCP ≠ Web 服务
MCP（stdio）本质是什么？
- MCP Client（如 TRAE）启动你的程序
- 通过stdin / stdout与之通信
- stdout 是协议通道，不是控制台
👉 你必须把 Spring Boot 当成：
一个“命令行工具程序”，而不是 HTTP 服务
二、必须关闭 Web 能力（否则必翻车）
正确配置
spring:main:web-application-type:none如果不关：
- Tomcat 会启动
- 控制台输出大量日志
- stdout 被污染
- MCP 直接无法解析
三、stdout 只能输出 MCP JSON（这是第一铁律）
常见 stdout 污染来源
| 来源 | 是否致命 |
|---|---|
| Spring Boot Banner | ✅ |
| log.info / log.debug | ✅ |
| System.out.println | ✅ |
| MyBatis SQL 日志 | ✅ |
| 数据库连接池启动日志 | ✅ |
错误表现
Unexpected token '�' not valid JSON Unexpected non-whitespace character after JSON必须做的事情
1️⃣ 关闭 Banner
spring:main:banner-mode:off2️⃣ 关闭所有 stdout 日志
logging:level:root:OFF3️⃣ 提供 logback-spring.xml（推荐）
建议只输出MCP的日志其他日志写入到文件里：
<configuration><propertyname="LOG_FILE"value="logs/mcp-server.log"/><appendername="FILE"class="ch.qos.logback.core.FileAppender"><file>${LOG_FILE}</file><encoder><pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern></encoder></appender><rootlevel="INFO"><appender-refref="FILE"/></root><loggername="org.springframework.ai.mcp"level="DEBUG"/><!-- 关闭 Spring Boot 自带的启动 INFO --><loggername="org.springframework.boot.StartupInfoLogger"level="OFF"/><loggername="org.springframework.boot.autoconfigure.logging"level="OFF"/></configuration>或者直接：
<configuration><rootlevel="OFF"/></configuration>MCP stdio 模式下，宁可没有日志，也不要 stdout 日志
四、Windows 下一定要强制 UTF-8（否则中文必炸）
典型错误
"��ѯˮ����Ϣ��时间�?"这是GBK 输出 + UTF-8 解析的经典乱码。
正确做法（TRAE 启动参数）
{"command":"java","args":["-Dfile.encoding=UTF-8","-Dspring.output.ansi.enabled=NEVER","-jar","xxx.jar"]}📌这一步不做，中文参数 100% 出问题
五、Tool 能调用 ≠ Spring 容器正常
一个非常迷惑人的现象是：
- Tool 能被 TRAE 识别
- 简单 Tool（时间、字符串）正常
- 一查数据库就返回
null
常见原因
- 没有指定 profile
- 数据源指向了“空库”
- Mapper 没被扫描
- Service 实际上是
null
建议
spring:profiles:active:dev或在启动参数中显式指定：
--spring.profiles.active=dev六、MCP Tool 返回值要“简单、干净”
不推荐的返回方式
@ToolpublicReservoirInfogetReservoirInfo(Stringname)问题可能来自：
- 懒加载代理
- 循环引用
- Jackson 序列化失败
- LocalDateTime / BigDecimal
推荐做法（最佳实践）
@ToolpublicMap<String,Object>getReservoirInfo(Stringname){ReservoirInfoinfo=service.findByName(name);if(info==null){returnnull;}Map<String,Object>result=newHashMap<>();result.put("name",info.getName());result.put("code",info.getCode());result.put("location",info.getLocation());returnresult;}👉MCP Tool = 接口协议，不是领域模型暴露
七、严禁在 Tool 中使用 System.out
错误示例（非常常见）
System.out.println("查询水库信息："+name);后果
- stdout 被污染
- MCP JSON 被截断
- Client 报解析错误
📌stdio MCP 下，System.out = 自杀按钮
八、最小可用 MCP（stdio）配置模板
application.yml（推荐基线）
spring:main:web-application-type:none# 设置为非Web应用类型banner-mode:off# 关闭 Spring Boot 启动横幅ai:mcp:server:enabled:truename:demo-aiversion:1.0.0stdio:truelogging:level:root:OFF九、MCP stdio 的五条“生存铁律”
- stdout 只能输出 MCP JSON
- 禁止 Banner
- 禁止 stdout 日志
- 强制 UTF-8
- Tool 返回值尽量简单
只要违反一条，问题一定以 JSON 解析错误的形式出现
十、总结
Spring Boot 实现 MCP（stdio）工具时，最大的误区在于：
用 Web Spring Boot 的思维，去写一个“协议型命令行程序”
一旦你真正把它当成：
- 没有控制台
- 没有日志
- stdout 只服务协议
👉 MCP 就会变得非常稳定、非常可靠。
