Mcpx CLI

🔌 MCPX

一个配置来管理它们。 只需配置一次MCP服务器，即可自动部署到每个AI CLI。

______________________________________________________________________

😩 问题

每个AI CLI工具都使用 不同的文件格式 用于配置MCP（模型上下文协议）服务器：

如果你使用多个人工智能工具（你可能确实这样做了），你需要 手动维护8个不同的配置文件 具有不同的结构、字段名和怪癖。对于 每一个项目.

______________________________________________________________________

✨ 解决方案

MCPX 维护单个规范配置文件(.mcpx.json)每个项目和 自动生成 您使用的每个AI CLI提供程序的正确配置文件。

.mcpx.json  ──────►  .mcp.json                     (Claude Code)
    │       ──────►  .gemini/settings.json          (Gemini CLI)
    │       ──────►  ~/.kimi/mcp.json               (Kimi CLI)
    │       ──────►  .codex/config.toml             (OpenAI Codex)
    │       ──────►  opencode.json                  (OpenCode)
    │       ──────►  .copilot/mcp-config.json       (Copilot CLI)
    │       ──────►  .vscode/mcp.json               (VS Code)
    └─────  ──────►  .idea/mcp.json                 (IntelliJ IDEA)

______________________________________________________________________

🚀 快速开始

📦 安装

npm install -g mcpx-cli

⚡ 首次设置

导航到项目目录并运行：

mcpx

交互式向导将指导您完成以下操作：

1. 🔍 检测 --自动检测项目中现有的MCP配置
2. 📥 导入 --提供从检测到的配置中导入服务器
3. ➕ 添加服务器 --配置新MCP服务器的交互式向导
4. 🎯 选择提供商 --选择要为哪些AI CLI生成配置
5. ⚙️ 生成 --创建 .mcpx.json 以及所有提供程序配置文件

______________________________________________________________________

📋 命令

🏳️ 全球旗帜

______________________________________________________________________

📐 规范格式

MCPX使用单个 .mcpx.json 文件作为真相的来源：

{
  "version": 1,
  "providers": ["claude-code", "gemini-cli", "openai-codex", "copilot-cli"],
  "servers": {
    "jira": {
      "description": "Jira Atlassian",
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://myorg.atlassian.net",
        "JIRA_USERNAME": "user@example.com",
        "JIRA_API_TOKEN": "your-token"
      }
    },
    "github": {
      "description": "GitHub MCP Server",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-github-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

📝 服务器字段

______________________________________________________________________

🤖 支持的提供商

📁 项目范围内的供应商

这些提供程序生成配置文件 在项目目录中每个项目都有自己的独立配置。

🟣 克劳德代码

🔵 Gemini CLI

🟢 OpenAI Codex

🟠 OpenCode

⚫ GitHub Copilot命令行界面

📌 注： Copilot CLI本身不会自动发现项目级MCP配置。MCPX自动配置shell别名(copilot='copilot --additional-mcp-config @.copilot/mcp-config.json')在你的 .zshrc, .bashrc，或 config.fish 因此，当您运行时，项目配置会自动加载 copilot.

🔷 VS Code

🟧 智能J IDEA

🌍 全球供应商

这些提供商使用 单个全局配置文件 在所有项目中共享。跑步 mcpx sync 用当前项目的服务器覆盖全局文件。

🔴 化学CLI

______________________________________________________________________

🔄 同步和提供程序管理

🔁 同步中

修改后 .mcpx.json （手动或通过命令），重新生成所有提供程序配置：

mcpx sync

🔀 更换供应商

使用交互式向导添加或删除提供程序：

mcpx init
# Select "Alterar providers"

当提供者 移除，MCPX 删除 相应的配置文件。对于全局提供商，旧项目级文件也会被清理。

📥 从现有配置导入

您的人工智能工具中已经配置了MCP服务器吗？导入它们：

mcpx import

MCPX检测现有的项目级配置(.mcp.json, .gemini/settings.json等），并允许您选择要导入的服务器 .mcpx.json.

______________________________________________________________________

🏗️ 建筑

src/
├── cli.ts                    # Commander setup & routing
├── types/
│   ├── canonical.ts          # McpConfigFile, McpServerConfig (Zod schemas)
│   ├── providers.ts          # Provider interface
│   └── common.ts             # CommandContext, SyncResult
├── commands/
│   ├── init.ts               # Interactive wizard
│   ├── add.ts / remove.ts    # Server management
│   ├── list.ts / status.ts   # Display info
│   ├── sync.ts               # Regenerate configs
│   └── import.ts             # Import from providers
├── providers/
│   ├── base.ts               # Provider interface
│   ├── registry.ts           # Provider registry (factory)
│   ├── claude-code.ts        # .mcp.json
│   ├── gemini-cli.ts         # .gemini/settings.json
│   ├── kimi-cli.ts           # ~/.kimi/mcp.json
│   ├── openai-codex.ts       # .codex/config.toml
│   ├── opencode.ts           # opencode.json
│   ├── copilot-cli.ts        # .copilot/mcp-config.json
│   ├── vscode.ts             # .vscode/mcp.json
│   └── intellij.ts           # .idea/mcp.json
├── core/
│   ├── config-store.ts       # .mcpx.json read/write
│   ├── detector.ts           # Detect existing configs
│   └── merger.ts             # Smart sync with merge support
├── wizard/
│   ├── main-wizard.ts        # Main interactive flow
│   ├── server-wizard.ts      # Server creation wizard
│   ├── provider-wizard.ts    # Provider selection
│   └── step-runner.ts        # Step navigation (back support)
└── utils/
    ├── fs.ts                 # File system helpers
    ├── logger.ts             # Logger with colors
    └── validation.ts         # Zod validation

______________________________________________________________________

🧪 测试

# Run all tests
npm test

# Run once (CI)
npm run test:run

# Type checking
npm run typecheck

______________________________________________________________________

🛠️ 技术栈

______________________________________________________________________

📄 许可证

麻省理工学院

______________________________________________________________________

🇧🇷 Leia em Português (pt-BR)