Moonbridge

🚀 Moonbridge

あなたのMCPクライアントにチームが加わりました。

Claude Code、Cursor、または任意のMCPクライアントからAIコーディングエージェントを起動します。コストの一部で10のアプローチを並列実行します。

uvx moonbridge

🚀 クイックスタート

1. 少なくとも1つのサポートされるCLIをインストールします。

   アダプター	インストール	認証
   Kimi (デフォルト)	uv tool install --python 3.13 kimi-cli	kimi login
   Codex	npm install -g @openai/codex	OPENAI_API_KEY を設定
   OpenCode	curl -fsSL https://opencode.ai/install | bash	opencode auth login
   Gemini CLI	npm install -g @google/gemini-cli	gemini のログインフローを実行するか、GEMINI_API_KEY を設定

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) を実行します。悪意のあるまたは不注意なプロンプトにより、エージェントがシェルコマンドを実行したり、アクセス可能なファイルを読み取ったり、ネットワーク呼び出しを介してデータを漏洩したりする可能性があります。

Moonbridgeはガードレール (MOONBRIDGE_ALLOWED_DIRS、環境許可リスト、オプションの MOONBRIDGE_SANDBOX=1) を追加しますが、これらはOSレベルの隔離とは同等ではありません。

信頼できないプロンプトや共有環境の場合は、最小限の特権でファイルシステムとネットワークアクセスを持つコンテナまたはVM内でMoonbridgeを実行してください。

🔄 更新

Moonbridgeは起動時に更新を確認します (24時間キャッシュされます)。手動で更新するには:

# uvxを使用している場合 (推奨)
uvx moonbridge --refresh

# ツールとしてインストールされている場合
uv tool upgrade moonbridge

CI/自動化で更新チェックを無効にするには:

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 は asyncio.gather を介して最大10のエージェントを同時に実行します。
• 各エージェントは独立しています (別のプロセス、別の出力)。
• 最後のエージェントが完了するかタイムアウトすると、すべての結果がまとめて返されます。

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

💻 ツール

例: 並列探索

{
  "agents": [
    {"prompt": "React hooksにリファクタリングする"},
    {"prompt": "Zustandにリファクタリングする"},
    {"prompt": "Redux Toolkitにリファクタリングする"}
  ]
}

3つのアプローチ。1つのリクエスト。あなたが勝者を選びます。

ツールのパラメータ

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)
• 破壊的なシェルコマンドを実行する
• ネットワークを介してデータを漏洩する

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 などのアダプター固有のもの)。デフォルトでは、シェル環境 (シークレット、トークン、SSHキー) は継承されません。

4. 入力検証

モデルパラメータは、フラグインジェクションを防止するために検証されます (- で始まる値は拒否されます)。プロンプトは最大100,000文字に制限され、空にすることはできません。

5. プロセス分離とサンドボックスモード

エージェントは別のプロセスグループで実行されます (start_new_session=True)。終了時に孤立したプロセスがクリーンアップされます。サンドボックスモード (MOONBRIDGE_SANDBOX=1) を利用できます。これは実行時にコピーして分離するためのものです。

OSレベルのサンドボックス化ではありません。 エージェントは、アクセス可能な任意のホストファイルを読み書きすることができます。

6. 強化されたデプロイメントチェックリスト

• MOONBRIDGE_ALLOWED_DIRS を可能な限り小さいセットに設定します。
• MOONBRIDGE_STRICT=1 を有効にして、制限がない場合には安全に閉じるようにします。
• MOONBRIDGE_SANDBOX=1 を有効にして、ワークスペースの直接変更を避けます。
• 強力な分離を行うために、コンテナ/VM内でMoonbridgeを実行します。
• 追加の認証制御なしでMoonbridgeを信頼できないクライアントに公開しないでください。

🛠️ トラブルシューティング

"CLI not found"

選択したアダプターの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=1800s、Kimi=600s、OpenCode=1200s、Gemini=1200s。

非常に長いタスクの場合は、明示的に上書きします。

{"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分

⏱️ タイムアウトのベストプラクティス

優先順位の解決: 明示的なパラメータ > アダプターの環境変数 > アダプターのデフォルト > グローバルな環境変数 > 600sのフォールバック

"MOONBRIDGE_ALLOWED_DIRS is not set" 警告

デフォルトでは、Moonbridgeはディレクトリ制限が構成されていない場合、起動時に警告を表示します。これはローカル開発では正常な動作です。共有/本番環境では、許可されたディレクトリを設定します。

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

📦 サンドボックスモード (実行時コピー)

作業ディレクトリの一時コピーでエージェントを実行するには、サンドボックスモードを有効にします。

export MOONBRIDGE_SANDBOX=1

有効にすると:

• エージェントは cwd の一時コピーで実行されます。
• ホストファイルはデフォルトで変更されません。
• 統合差分 + 要約が raw.sandbox に含まれます。

オプション:

export MOONBRIDGE_SANDBOX_KEEP=1       # 一時ディレクトリを保持
export MOONBRIDGE_SANDBOX_MAX_DIFF=200000
export MOONBRIDGE_SANDBOX_MAX_COPY=300000000

制限事項: これはOSレベルの分離ではありません。エージェントは、必要に応じて任意のホストパスを読み書きすることができます。強力な分離にはコンテナ/VMを使用してください。

制限を強制するには (警告ではなく終了する):

export MOONBRIDGE_STRICT=1

作業ディレクトリでのアクセス拒否

ディレクトリが許可リストに含まれていることを確認します。

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

デバッグログ

詳細なログを有効にするには:

export MOONBRIDGE_LOG_LEVEL=DEBUG

🖥️ プラットフォームサポート

macOSとLinuxのみサポートされています。Windowsはサポートされていません。

📄 ライセンス

MITライセンスです。詳細は LICENSE を参照してください。