SpringAI与MCP服务通信超时问题解决方案

1. SpringAI框架MCP通信超时问题深度解析

最近在整合高德地图MCP服务到SpringAI项目时，遇到了一个典型的通信超时问题。错误信息显示"Did not observe any item or terminal signal within 20000ms"，这个看似简单的超时提示背后，实际上隐藏着Node.js版本兼容性和配置细节的坑。下面我将完整复盘整个排查过程和技术原理。

1.1 问题现象与环境配置

项目基础环境：

• SpringAI 1.0.0
• springai-alibaba 1.0.0.4
• Node.js 14.x（初始版本）
• JDK 17
• Spring Boot 3.1.5

核心配置采用stdio通信模式，mcpServerConfig.json5关键配置如下：

json复制{
  "mcpServers": {
    "amap-maps": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@amap/amap-maps-mcp-server"],
      "env": {
        "AMAP_MAPS_API_KEY": "your_key_here"
      }
    }
  }
}

application.yaml中对应的配置项：

yaml复制mcp:
  client:
    stdio:
      servers-configuration: classpath:/mcpServerConfig.json5
    toolcallback:
      enabled: true

1.2 第一阶段问题：参数缺失错误

首次运行时控制台报错：

code复制ERROR: You must supply a command.

这个错误看似简单，实则暴露了Node.js命令行参数解析的特性。在Node.js 14环境下，npx命令需要显式指定--npm参数才能正确执行。解决方案是在args数组中追加参数：

json复制"args": ["/c", "npx", "--npm", "-y", "@amap/amap-maps-mcp-server"]