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 文件。