Spring AI MCP stdio npx not found

本地 IDE 裡配好的 MCP server，搬到 Spring Boot 就起不來，報 exec: "npx": executable file not found in $PATH。根因是子進程的 PATH 不等於你交互式 shell 的 PATH，Node 的安裝目錄沒進去；Windows 上 npx 其實是 npx.cmd 批處理，ProcessBuilder 不能直接執行，得用 cmd /c 包一層。

Issue & Env（案發現場與環境）

• 業務場景：用 stdio 方式接 MCP server，比如官方的 filesystem。在本地 IDE（Qoder、Claude Desktop 這類）裡配好能用，搬到 Spring Boot 應用裡，啟動就失敗。
• 環境：Spring AI 1.1.x，spring-ai-starter-mcp-client（或 ...-webflux 版），stdio transport。Node.js 沒裝，或者裝了但不在 JVM 進程的 PATH 裡。

StackTrace（堆疊日誌）

最常見的一條報錯原文：

java.lang.RuntimeException: failed to start command: exec: "npx": executable file not found in $PATH

Windows 上換了個說法：

'npx.cmd' is not recognized as an internal or external command, operable program or batch file.

這兩條文案來自 MCP 客戶端與宿主，Qoder 和阿里雲 Lingma 的 FAQ 都原樣收錄了。如果失敗是從 Java 側 ProcessBuilder 冒出來的，形態通常是這樣（這是 ProcessBuilder 的通用輸出，不是 Spring AI 獨有）：

java.io.IOException: Cannot run program "npx": error=2, No such file or directory
    at java.lang.ProcessBuilder.start(ProcessBuilder.java:1048)

Reproduce（復現程式碼）

設定裡 command 直接寫 npx：

spring:
  ai:
    mcp:
      client:
        stdio:
          connections:
            filesystem:
              command: npx
              args:
                - -y
                - "@modelcontextprotocol/server-filesystem"
                - /Users/username/Desktop

同一串命令在終端手敲能跑，應用一啟動就失敗。差別不在命令，在“誰去執行它”。

Root Cause（根因分析）

PATH 不是同一份

子進程繼承的是啟動它的 JVM 進程的 PATH，跟你登錄後交互式 shell 的 PATH 是兩回事。終端啟動 shell 時會讀 .zshrc、.bash_profile，nvm、Homebrew 這些工具往 PATH 里加目錄，就在這一步。IDE 的 Run 面板、系統服務、容器裡的 JVM 往往不讀這些 rc 文件，拿到的 PATH 更精簡，自然找不到 npx。

直接 exec，沒有 shell 兜底

StdioClientTransport 用 ProcessBuilder 直接拉起 command 指定的可執行文件，中間沒有 shell。命令不會被 shell 再展開一遍，rc 文件裡追加的 PATH 也不生效。終端能跑、IDE 能跑，不代表 Java 進程能跑。

Windows：npx 不是可執行文件

Windows 上 npx、npm、node 都是批處理（.cmd）。ProcessBuilder 只能執行原生 .exe，或者交給 cmd.exe 執行的系統命令，批處理它直接執行不了。Spring AI 官方文檔專門寫了這一條：Windows 上要用 cmd.exe /c 把批處理命令包起來。

The Fix（解決方案）

1. command 換成絕對路徑

最穩的是寫絕對路徑，繞開 PATH 查找：

spring:
  ai:
    mcp:
      client:
        stdio:
          connections:
            filesystem:
              command: /usr/local/bin/npx
              args:
                - -y
                - "@modelcontextprotocol/server-filesystem"
                - /Users/username/Desktop

先用 which npx（Windows 用 where npx）拿到真實路徑再填。用 nvm 的話路徑裡帶 Node 版本號，升級 Node 後要跟著改。

2. Windows 用 cmd /c 包一層

spring:
  ai:
    mcp:
      client:
        stdio:
          connections:
            filesystem:
              command: cmd
              args:
                - /c
                - npx
                - -y
                - "@modelcontextprotocol/server-filesystem"
                - C:\\Users\\username\\Desktop

官方文檔的示例用 cmd.exe，和 cmd 等價。

3. 運行時先備好

• Node.js 18 及以上（自帶 npm 8 及以上）。版本低於這個線，容易出各種問題。
• Python 系的 MCP server 走 uv / uvx，也要先裝好。

4. 配好先用命令行驗證

把 command 和 args 拼成一行，在終端原樣跑一遍：

npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop

能起來，說明命令本身沒問題，剩下就是 Java 進程的 PATH 和 Windows 批處理兩件事。

References（參考來源）

• MCP Client Boot Starter（含 Windows STDIO 設定）— Spring AI 官方文檔spring-docs
• MCP Common Issues：npx/uvx 環境缺失 — Qoder 文檔qoder-docs
• MCP 常見問題說明 — 阿里雲 Lingma FAQaliyun-docs