farion1231/cc-switch · error · Error

无法识别的 TOML 格式。请提供单个 MCP 服务器配置，或使用

Error message

无法识别的 TOML 格式。请提供单个 MCP 服务器配置，或使用 [mcp_servers.<id>] 格式

What it means

After parsing, tomlToMcpServer tries three shapes in order: a direct server config (type/command/url/args/env at the top level), a [mcp_servers.<id>] table (first server wins), and the tolerated-but-wrong [mcp.servers.<id>] form. '无法识别的 TOML 格式...' is the terminal throw when none match — the TOML parsed successfully but contains no recognizable MCP server stanzas.

Solutions

  1. Wrap the server under [mcp_servers.<id>] — the recommended format this parser looks for first
  2. Or paste only the server's own keys (command = '...', args = [...]) at the top level
  3. Preview with extractIdFromToml to confirm the parser can see the table before importing

Example fix

# before
cat = "meow"
owner = "dev"

# 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 recognizable =
  Boolean(parsed.type || parsed.command || parsed.url || parsed.args || parsed.env) ||
  Object.keys(parsed.mcp_servers ?? {}).length > 0 ||
  Object.keys((parsed.mcp as Record<string, unknown> | undefined)?.servers ?? {}).length > 0;
if (!recognizable) {
  // show format guidance before calling tomlToMcpServer
}

Try / catch

try {
  const server = tomlToMcpServer(tomlText);
} catch (error) {
  if (error instanceof Error && error.message.includes('无法识别的 TOML 格式')) {
    // guide the user to [mcp_servers.<id>] format
  } else {
    throw error;
  }
}

Prevention

When it happens

Trigger: Pasting a settings file whose server sits under a different table (e.g. [tools.mcp.x]), a document with only unrelated top-level keys, or an [mcp_servers] table that is empty.

Common situations: Copying a whole config.toml from another app that uses a different section name; the real entry commented out so the table is empty; config schema drift between tool versions.

Related errors

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

Appendix: source

Thrown at src/utils/tomlUtils.ts:92

    if (serverIds.length > 0) {
      const firstServer = (parsed.mcp_servers as any)[serverIds[0]];
      return normalizeServerConfig(firstServer);
    }
  }

  // 情况 3: [mcp.servers.<id>] 错误格式（容错解析）
  if (parsed.mcp && typeof parsed.mcp === "object") {
    const mcpObj = parsed.mcp as any;
    if (mcpObj.servers && typeof mcpObj.servers === "object") {
      const serverIds = Object.keys(mcpObj.servers);
      if (serverIds.length > 0) {
        const firstServer = mcpObj.servers[serverIds[0]];
        return normalizeServerConfig(firstServer);
      }
    }
  }

  throw new Error(
    "无法识别的 TOML 格式。请提供单个 MCP 服务器配置，或使用 [mcp_servers.<id>] 格式",
  );
};

/**
 * 规范化服务器配置对象为 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>();

View on GitHub (pinned to 0b5da51016)