ModelContextProtocol TypeScript SDK 中环境变量 PATH 缺失问题的分析与解决方案

问题背景

在使用 ModelContextProtocol TypeScript SDK 的 StdioTransport 时，开发者可能会遇到一个常见但容易被忽视的问题：当通过 StdioTransport 启动本地 Node.js 子进程时，如果自定义了环境变量但没有包含 PATH 变量，会导致子进程无法正常启动。

问题现象

开发者在使用 StdioTransport 配置如下时会出现问题：

{
  command: "node",
  args: ["./mcp-server-browserbase/stagehand/dist/index.js"],
  env: {
    BROWSERBASE_PROJECT_ID: process.env.BROWSERBASE_PROJECT_ID,
    BROWSERBASE_API_KEY: process.env.BROWSERBASE_API_KEY,
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  },
}

而正确的做法应该是：

{
  command: "node",
  args: ["./mcp-server-browserbase/stagehand/dist/index.js"],
  env: {
    BROWSERBASE_PROJECT_ID: process.env.BROWSERBASE_PROJECT_ID,
    BROWSERBASE_API_KEY: process.env.BROWSERBASE_API_KEY,
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
    PATH: process.env.PATH as string,
  },
}

技术原理

这个问题源于 Node.js 子进程的创建机制。当开发者显式指定 env 对象时，Node.js 会完全使用这个对象作为新进程的环境变量，而不会自动继承父进程的任何环境变量。PATH 环境变量对于系统查找可执行文件（如 node）至关重要，如果缺失会导致 ENOENT 错误。

SDK 设计考量

ModelContextProtocol TypeScript SDK 的设计团队特意没有自动包含 PATH 变量，这是出于以下考虑：

1. 灵活性：允许开发者完全控制子进程的环境变量
2. 安全性：避免意外泄露父进程的环境变量
3. 一致性：确保环境变量的行为可预测

解决方案

开发者有以下几种方式解决这个问题：

方案一：手动添加 PATH 变量

{
  env: {
    ...yourVars,
    PATH: process.env.PATH
  }
}

方案二：使用 SDK 提供的工具函数

SDK 提供了 getDefaultEnvironment() 函数，可以获取包含 PATH 等基本环境变量的默认设置：

import { getDefaultEnvironment } from 'modelcontextprotocol';

{
  env: {
    ...getDefaultEnvironment(),
    ...yourCustomVars
  }
}

方案三：合并环境变量

对于从 JSON 配置读取环境变量的情况，可以这样处理：

const configEnv = JSON.parse(configFile);
const finalEnv = {
  ...getDefaultEnvironment(),
  ...configEnv
};

最佳实践建议

1. 始终确保 PATH 变量存在于子进程环境变量中
2. 对于需要完全自定义环境变量的场景，至少包含 PATH 变量
3. 考虑使用 getDefaultEnvironment() 作为基础环境配置
4. 在测试环境中验证子进程的环境变量设置

总结

理解 Node.js 子进程环境变量的继承机制对于正确使用 ModelContextProtocol TypeScript SDK 的 StdioTransport 功能至关重要。通过合理处理 PATH 变量，可以避免常见的子进程启动失败问题，同时保持环境变量配置的灵活性和安全性。