Moonbridge MCP

月亮桥

你的MCP客户刚刚组建了一个团队。

从Claude Code、Cursor或任何MCP客户端生成AI编码代理。以成本的一小部分并行运行10种方法。

uvx moonbridge

快速开始

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

1. 添加到MCP配置 (~/.mcp.json):

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

1. 使用它。 您的MCP客户端现在具有 spawn_agent 和 spawn_agents_parallel 工具。

安全警告（请先阅读）

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

Moonbridge增加了护栏(MOONBRIDGE_ALLOWED_DIRS，环境同种异体，可选 MOONBRIDGE_SANDBOX=1)，但这些并不等同于操作系统级别的遏制。

对于不受信任的提示或共享环境，请在容器或VM中运行Moonbridge 最小权限文件系统和网络访问。

更新中

Moonbridge在启动时检查更新（缓存24小时）。要手动更新，请执行以下操作：

# If using uvx (recommended)
uvx moonbridge --refresh

# If installed as a tool
uv tool upgrade moonbridge

禁用CI/CD自动化的更新检查：

export MOONBRIDGE_SKIP_UPDATE_CHECK=1

何时使用Moonbridge

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

原理

连接流程

1. MCP客户端（Claude Code、Cursor等）通过stdio连接到Moonbridge
2. 客户端通过以下方式发现可用工具 list_tools
3. 客户电话 spawn_agent 或 spawn_agents_parallel

产卵过程

1. Moonbridge验证提示和工作目录
2. 决定使用哪个适配器（Kimi、Codex、OpenCode、Gemini）
3. 适配器使用适当的标志构建CLI命令
4. 在单独的流程组中生成子流程
5. 捕获stdout/stderr，强制超时
6. 返回结构化JSON结果

并行执行

• spawn_agents_parallel 通过以下方式同时运行多达10个代理 asyncio.gather
• 每个代理都是独立的（单独的过程，单独的输出）
• 当最后一个代理完成（或超时）时，所有结果一起返回

MCP Client → stdio → Moonbridge → adapter → CLI subprocess
                                          → CLI subprocess (parallel)
                                          → CLI subprocess (parallel)

工具

示例：平行探索

{
  "agents": [
    {"prompt": "Refactor to React hooks"},
    {"prompt": "Refactor to Zustand"},
    {"prompt": "Refactor to Redux Toolkit"}
  ]
}

三种方法。一个请求。你选择赢家。

工具参数

spawn_agent

spawn_agents_parallel

check_status

list_models

响应格式

所有工具都返回带有以下字段的JSON：

当输出太大时，Moonbridge会截断它并添加 raw.output_limit 元数据 原始尺寸。

配置

环境变量

安全

Moonbridge继承了所选适配器CLI的安全模型。Kimi、Codex、OpenCode和Gemini是 代理CLIs；提示可以触发命令执行、文件访问和网络活动 在流程权限范围内。

1.威胁模型（包括快速注入）

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

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

Moonbridge不会检查即时意图。将提示输入视为可能不受信任。

2.目录限制(MOONBRIDGE_ALLOWED_DIRS)

默认值：代理可以在任何目录中操作。集 MOONBRIDGE_ALLOWED_DIRS 限制：冒号分隔允许的路径。Symlinks已通过以下方式解决 os.path.realpath 在检查之前。严格模式(MOONBRIDGE_STRICT=1)如果未配置有效的允许目录，则在启动时退出。

export MOONBRIDGE_ALLOWED_DIRS="/home/user/projects:/home/user/work"
export MOONBRIDGE_STRICT=1  # require restrictions

3.环境消毒

只有白名单中的环境变量才会传递给生成的代理。每个适配器都定义了自己的满列表(PATH, HOME，加上适配器特定的类似功能 OPENAI_API_KEY 食品法典委员会）。默认情况下，您的shell环境（机密、令牌、SSH密钥）不会被继承。

4.输入验证

验证模型参数以防止标志注入（值以 - 被拒绝）。提示最多为100000个字符，不能为空。

5.过程隔离和沙盒模式

代理在单独的进程组中运行(start_new_session=True).出口处的孤儿清理。沙盒模式可用(MOONBRIDGE_SANDBOX=1)用于运行时复制隔离。

不是操作系统级沙盒。 代理仍然可以读取或写入他们可以访问的任意主机文件。

6.强化部署检查表

• 集 MOONBRIDGE_ALLOWED_DIRS 尽可能小的集合。
• 启用 MOONBRIDGE_STRICT=1 因此，缺失的限制无法关闭。
• 启用 MOONBRIDGE_SANDBOX=1 以避免直接的工作空间突变。
• 在容器/VM中运行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  # complete login flow, or set GEMINI_API_KEY

超时错误

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

对于超长任务，显式重写：

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

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

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

超时最佳实践

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

“MOONBRIDGE_ALLOWED_DIRS未设置”警告

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

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

沙盒模式（运行时复制）

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

export MOONBRIDGE_SANDBOX=1

启用时：

• 代理在临时副本中运行 cwd.
• 默认情况下，主机文件保持不变。
• 包含一个统一的diff+摘要 raw.sandbox.

可选：

export MOONBRIDGE_SANDBOX_KEEP=1       # keep temp dir
export MOONBRIDGE_SANDBOX_MAX_DIFF=200000
export MOONBRIDGE_SANDBOX_MAX_COPY=300000000

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

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

export MOONBRIDGE_STRICT=1

工作目录权限被拒绝

验证目录是否在您的列表中：

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

调试日志

启用详细日志记录：

export MOONBRIDGE_LOG_LEVEL=DEBUG

平台支持

仅限macOS和Linux。不支持Windows。

许可证

MIT。看 LICENSE.