farion1231/cc-switch · error · Error

stdio 类型的 MCP 服务器必须包含 command 字段

Error message

stdio 类型的 MCP 服务器必须包含 command 字段

What it means

For type stdio — which is also the default when the type key is omitted — normalizeServerConfig requires a command field that is a non-empty string ('stdio 类型的 MCP 服务器必须包含 command 字段'). stdio servers launch a local process, so without command there is nothing to execute. The check runs before args/env and unknown-field copying.

Solutions

  1. Add command = "<executable>" to the stdio server block
  2. If the server is actually remote, set type = "http" or "sse" and provide url instead
  3. Check spelling and case — the parser only accepts a lowercase command key

Example fix

# before
[mcp_servers.fetch]
type = "stdio"
args = ["mcp-server-fetch"]

# after
[mcp_servers.fetch]
type = "stdio"
command = "uvx"
args = ["mcp-server-fetch"]
Defensive patterns

Strategy: validation

Validate before calling

const parsed = parseToml(normalizeTomlText(tomlText));
const first = firstServerOf(parsed);
const type = (first?.type as string) || 'stdio';
if (type === 'stdio' && (typeof first?.command !== 'string' || !first.command)) {
  // show "stdio server needs a command" before importing
}

Try / catch

try {
  const server = tomlToMcpServer(tomlText);
} catch (error) {
  if (error instanceof Error && error.message.includes('必须包含 command 字段')) {
    // highlight the command field guidance
  } else {
    throw error;
  }
}

Prevention

When it happens

Trigger: Pasting a block like 'type = "stdio"' with only args/env, or where command is missing, empty, or a non-string (number/table).

Common situations: A remote-style (url-based) config pasted while type still says stdio; the executable landed in args when the command line was split wrongly; key typos like cmd or Command.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of farion1231/cc-switch@0b5da51016 (2026-08-20). Data as JSON: /api/errors/ae6b52a0e15a1a55. Report an issue: GitHub.

Appendix: source

Thrown at src/utils/tomlUtils.ts:113

};

/**
 * 规范化服务器配置对象为 McpServer 格式
 * 保留所有字段（包括扩展字段如 timeout_ms）
 */
function normalizeServerConfig(config: any): McpServerSpec {
  if (!config || typeof config !== "object") {
    throw new Error("服务器配置必须是对象");
  }

  const type = (config.type as string) || "stdio";

  // 已知字段列表（用于后续排除）
  const knownFields = new Set<string>();

  if (type === "stdio") {
    if (!config.command || typeof config.command !== "string") {
      throw new Error("stdio 类型的 MCP 服务器必须包含 command 字段");
    }

    const server: McpServerSpec = {
      type: "stdio",
      command: config.command,
    };
    knownFields.add("type");
    knownFields.add("command");

    // 可选字段
    if (config.args && Array.isArray(config.args)) {
      server.args = config.args.map((arg: any) => String(arg));
      knownFields.add("args");
    }
    if (config.env && typeof config.env === "object") {
      const env: Record<string, string> = {};
      for (const [k, v] of Object.entries(config.env)) {
        env[k] = String(v);

View on GitHub (pinned to 0b5da51016)