Moonbridge

🚀 Moonbridge

Moonbridge 让你的 MCP 客户端拥有了一个团队。你可以从 Claude Code、Cursor 或任何 MCP 客户端中生成 AI 编码代理，以较低的成本并行运行 10 种方案。

uvx moonbridge

🚀 快速开始

1. 至少安装一个受支持的 CLI：

2. 添加到 MCP 配置文件（~/.mcp.json）：

{
    "mcpServers": {
        "moonbridge": {
            "type": "stdio",
            "command": "uvx",
            "args": ["moonbridge"]
        }
    }
}

3. 开始使用。你的 MCP 客户端现在拥有 spawn_agent 和 spawn_agents_parallel 工具。

⚠️ 安全警告（请先阅读）

Moonbridge 会执行代理式 CLI（Kimi/Codex/OpenCode/Gemini）。恶意或粗心的提示可能会导致代理运行 shell 命令、读取可访问的文件或通过网络调用泄露数据。

Moonbridge 添加了防护措施（MOONBRIDGE_ALLOWED_DIRS、环境白名单、可选的 MOONBRIDGE_SANDBOX=1），但这些并不等同于操作系统级别的隔离。

对于不可信的提示或共享环境，请在具有最小权限的文件系统和网络访问权限的容器或虚拟机中运行 Moonbridge。

🔄 更新

Moonbridge 在启动时会检查更新（缓存 24 小时）。若要手动更新：

# 若使用 uvx（推荐）
uvx moonbridge --refresh

# 若作为工具安装
uv tool upgrade moonbridge

若要在 CI/自动化中禁用更新检查：

export MOONBRIDGE_SKIP_UPDATE_CHECK=1

💡 何时使用 Moonbridge

最适合：受益于并行执行或大量任务的场景。

🔍 工作原理

连接流程

1. MCP 客户端（Claude Code、Cursor 等）通过标准输入输出连接到 Moonbridge。
2. 客户端通过 list_tools 发现可用工具。
3. 客户端调用 spawn_agent 或 spawn_agents_parallel。

生成过程

1. Moonbridge 验证提示和工作目录。
2. 确定要使用的适配器（Kimi、Codex、OpenCode、Gemini）。
3. 适配器使用适当的标志构建 CLI 命令。
4. 在单独的进程组中生成子进程。
5. 捕获标准输出/标准错误，强制执行超时。
6. 返回结构化的 JSON 结果。

并行执行

• spawn_agents_parallel 通过 asyncio.gather 并发运行最多 10 个代理。
• 每个代理是独立的（单独的进程、单独的输出）。
• 当最后一个代理完成（或超时）时，所有结果一起返回。

MCP 客户端 → 标准输入输出 → Moonbridge → 适配器 → CLI 子进程
                                          → CLI 子进程（并行）
                                          → CLI 子进程（并行）

💻 工具

示例：并行探索

{
    "agents": [
        {"prompt": "重构为 React hooks"},
        {"prompt": "重构为 Zustand"},
        {"prompt": "重构为 Redux Toolkit"}
    ]
}

三种方案，一次请求，你选择最佳方案。

工具参数

spawn_agent

spawn_agents_parallel

check_status

list_models

📄 响应格式

所有工具返回的 JSON 包含以下字段：

当输出太大时，Moonbridge 会截断输出并添加 raw.output_limit 元数据，包含原始大小。

⚙️ 配置

环境变量

🔒 安全

Moonbridge 继承了所选适配器 CLI 的安全模型。Kimi、Codex、OpenCode 和 Gemini 是代理式 CLI；提示可以触发命令执行、文件访问和网络活动，这些活动受进程权限的限制。

1. 威胁模型（包括提示注入）

如果攻击者能够影响通过 MCP 发送的提示输入，他们可以尝试让代理：

• 读取敏感文件（例如 ~/.ssh 或 .env）。
• 运行破坏性的 shell 命令。
• 通过网络泄露数据。

Moonbridge 不会检查提示意图。请将提示输入视为潜在的不可信输入。

2. 目录限制（MOONBRIDGE_ALLOWED_DIRS）

默认情况下，代理可以在任何目录中操作。设置 MOONBRIDGE_ALLOWED_DIRS 以进行限制：以冒号分隔的允许路径。在检查之前，符号链接会通过 os.path.realpath 解析。严格模式（MOONBRIDGE_STRICT=1）在启动时如果没有配置有效的允许目录则会退出。

export MOONBRIDGE_ALLOWED_DIRS="/home/user/projects:/home/user/work"
export MOONBRIDGE_STRICT=1  # 要求设置限制

3. 环境清理

只有白名单中的环境变量会传递给生成的代理。每个适配器定义自己的白名单（PATH、HOME，以及适配器特定的变量，如 Codex 的 OPENAI_API_KEY）。默认情况下，你的 shell 环境（秘密、令牌、SSH 密钥）不会被继承。

4. 输入验证

模型参数会进行验证，以防止标志注入（以 - 开头的值会被拒绝）。提示限制为 100,000 个字符，且不能为空。

5. 进程隔离和沙箱模式

代理在单独的进程组中运行（start_new_session=True）。退出时会清理孤儿进程。可用沙箱模式（MOONBRIDGE_SANDBOX=1）进行运行时复制隔离。

注意：这不是操作系统级别的沙箱。代理仍然可以读取或写入它们可以访问的任意主机文件。

6. 强化部署清单

• 将 MOONBRIDGE_ALLOWED_DIRS 设置为尽可能小的集合。
• 启用 MOONBRIDGE_STRICT=1，以便在缺少限制时安全关闭。
• 启用 MOONBRIDGE_SANDBOX=1 以避免直接修改工作区。
• 在容器/虚拟机中运行 Moonbridge 以实现强隔离。
• 在没有额外身份验证控制的情况下，不要将 Moonbridge 暴露给不可信的客户端。

🛠️ 故障排除

"CLI 未找到"

安装你所选适配器的 CLI：

# Kimi
uv tool install --python 3.13 kimi-cli
which kimi

# Codex
npm install -g @openai/codex
which codex

# OpenCode
curl -fsSL https://opencode.ai/install | bash
which opencode

# Gemini
npm install -g @google/gemini-cli
which gemini

"auth_error" 响应

使用你所选的 CLI 进行认证：

# Kimi
kimi login

# Codex
export OPENAI_API_KEY=sk-...

# OpenCode
opencode auth login

# Gemini
gemini  # 完成登录流程，或设置 GEMINI_API_KEY

超时错误

适配器有合理的默认值：Codex = 1800 秒，Kimi = 600 秒，OpenCode = 1200 秒，Gemini = 1200 秒。

对于特别长的任务，显式覆盖超时时间：

{"prompt": "...", "timeout_seconds": 3600}

或者通过环境变量设置每个适配器的默认值：

export MOONBRIDGE_CODEX_TIMEOUT=2400  # 40 分钟
export MOONBRIDGE_KIMI_TIMEOUT=900    # 15 分钟
export MOONBRIDGE_OPENCODE_TIMEOUT=1200  # 20 分钟
export MOONBRIDGE_GEMINI_TIMEOUT=1200  # 20 分钟

⏱️ 超时最佳实践

优先级解析：显式参数 > 适配器环境变量 > 适配器默认值 > 全局环境变量 > 600 秒回退值

"MOONBRIDGE_ALLOWED_DIRS 未设置" 警告

默认情况下，如果没有配置目录限制，Moonbridge 会在启动时发出警告。这在本地开发中是正常的。对于共享/生产环境，请设置允许的目录：

export MOONBRIDGE_ALLOWED_DIRS="/path/to/project:/another/path"

📦 沙箱模式（运行时复制）

启用沙箱模式以在工作目录的临时副本中运行代理：

export MOONBRIDGE_SANDBOX=1

启用后：

• 代理在当前工作目录的临时副本中运行。
• 默认情况下，主机文件保持不变。
• raw.sandbox 中包含统一的差异和摘要。

可选设置：

export MOONBRIDGE_SANDBOX_KEEP=1       # 保留临时目录
export MOONBRIDGE_SANDBOX_MAX_DIFF=200000
export MOONBRIDGE_SANDBOX_MAX_COPY=300000000

限制：这不是操作系统级别的隔离。如果代理选择，它们仍然可以读取/写入任意主机路径。使用容器/虚拟机实现强隔离。

若要强制执行限制（退出而不是警告）：

export MOONBRIDGE_STRICT=1

工作目录权限被拒绝

验证目录是否在你的白名单中：

export MOONBRIDGE_ALLOWED_DIRS="/path/to/project:/another/path"

调试日志

启用详细日志记录：

export MOONBRIDGE_LOG_LEVEL=DEBUG

🖥️ 平台支持

仅支持 macOS 和 Linux，不支持 Windows。

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 文件。