remote-bridge

RemoteBridge 🌉

AI エージェントがリモートサーバーに確実にアクセスできるようにする、安全で設定可能な MCP ツールです。

RemoteBridge は、AI を活用したリモートワークフロー向けの Rust 製 CLI および MCP サーバーです。rsync でローカルコードを同期し、SSH 経由でリモートコマンドを実行し、ログと診断情報を収集して環境を比較します。そして、これらすべてを AI が直接使えるコンパクトなツールセットとして提供します。

Claude Code、Cursor、Windsurf、Codex、またはその他の MCP 対応ツール上の AI エージェントに、シェルプロンプトだけでなく、実際の運用コンテキストを把握したうえでリモートマシンを操作させたい場合にご利用ください。

サーバーの設定をモデルに推測させる代わりに、RemoteBridge は設定済みの運用インターフェースを提供します。

RemoteBridge が AI の理解を支援すること

AI がリモートマシン上でデバッグやデプロイを行うには、「このコマンドを実行する」以上の情報が必要です。

次のような情報を理解する必要があります。

• アプリがどこにデプロイされているか
• サービスをどのように再起動するか
• どのログファイルが重要か
• どのランタイムがインストールされているか
• サービスが正常に動作しているか
• どのポートがリッスンしているか
• ディスクやメモリの負荷が関係しているか
• ステージング環境と本番環境にどのような違いがあるか
• どのコマンドが許可されているか、または危険か

RemoteBridge は、こうした繰り返し参照するサーバー情報を remotebridge.yaml に保存し、役立つワークフローを MCP ツールとして提供します。

これにより、AI はリモートサーバーを、単にコマンドを実行する場所としてではなく、理解できるシステムとして扱えるようになります。

実際に解決する問題

構造化されたツールレイヤーがない場合、AI によるリモート作業は通常、ノイズの多い一連のシェル操作になります。

• 適切なホストを見つける
• デプロイ先のパスを見つける
• ランタイムを調べる
• 再起動コマンドを見つける
• ログを見つける
• 出力を大量に表示する
• コンテキストを取り戻すために追加で質問する

RemoteBridge は、これらを意図が明確で、より適切なデフォルト値を備えた、再利用可能な少数の操作にまとめます。

AI は次のツールを呼び出せます。

• sync_to_remote
• deploy
• preflight_check
• fetch_logs
• diagnose_failure
• compare_targets

これらのツールは、単にリモートシステム上でコマンドを実行するのではなく、AI がリモートシステムを調査し、推論できるよう支援することを目的としています。

たとえば、diagnose_failure は次の情報を収集できます。

• ランタイム情報
• サービスマネージャーの状態
• 最近のログ
• リスナー
• ディスクの状態
• メモリの状態
• 考えられる障害の兆候

これらをひとつの簡潔な応答にまとめます。

SSH を直接使う場合について

AI ツールから SSH を直接使う方法が便利なのは、次のような場合です。

• 完全に対話型のシェルが必要な場合。
• 実行するコマンドがすでに正確にわかっている場合。
• 一度限りの即席の調査をしたい場合。
• 緊急のコマンドを一度だけ実行し、生のターミナル動作を確認したい場合。

次のような場合は、RemoteBridge がより適しています。

• AI がワークフローを進める場合。
• 同じサーバー情報を何度も調べ直している場合。
• デプロイ、再起動、診断、ログの各ワークフローを繰り返し実行できるようにしたい場合。
• 破壊的なコマンドに対するガードレールが必要な場合。
• シェルの実行内容をすべて表示するのではなく、簡潔な回答が欲しい場合。
• 「ステージング環境と本番環境を比較する」といった設定を考慮した操作が必要な場合。

RemoteBridge が実際に異なる点

RemoteBridge の優位性は、SSH を隠すことではありません。インフラに関する繰り返しの推論を、安定して再利用できるツールの動作に変えることです。

SSH を直接使う場合との具体的な違いは次のとおりです。

• サーバーのパスは remotebridge.yaml で一度設定すれば、毎回の呼び出しで再利用されます。
• 再起動コマンドは一度設定すれば、何度も探したり入力し直したりする必要がありません。
• ログファイルは一度設定すれば、モデルが探し回る必要がありません。
• モデルは deploy、diagnose_failure、compare_targets を、意図に沿った操作として呼び出せます。
• モデルに大量のログではなく必要な情報を届けるため、出力は意図的に制限されています。
• 危険なコマンドは、確認を求めたり、ブロックしたり、許可リストに登録したりできます。
• ローカルコードの変更とリモートでの実行を、分断された二つの手順ではなく、ひとつのワークフローとして扱えます。

このため、AI エージェントが技術的にはすでにリモートアクセスに対応している場合でも、RemoteBridge は通常、AI エージェント内でシェルを直接使うよりも便利です。

実際にトークンを節約できる理由

RemoteBridge は、モデルとサーバー間の価値の低い会話を減らすときに役立ちます。

具体的には、次のような方法でトークンを節約します。

• run_remote_command は stdout と stderr を合算し、共通の行数上限で切り詰めるため、モデルは出力全体ではなく重要な末尾を受け取ります。
• preflight_check は、AI が複数のシェルコマンドを個別に実行する代わりに、1 回のリモート呼び出しで OS とランタイムの情報を収集します。
• fetch_logs は、AI がログの保存場所を何度も尋ねたり、各ファイルを手動で tail したりする代わりに、設定済みのログファイルを 1 つの構造化レスポンスで取得します。
• diagnose_failure は、サービスの状態、リスナー、ディスク、メモリ、ランタイム情報、直近のログを一度に収集し、原因として考えられるものを要約します。
• compare_targets は、「staging に SSH で接続し、prod に SSH で接続し、両方を調べ、頭の中で差分を比較する」作業を、意図に沿った 1 回のツール呼び出しにまとめます。
• deploy と restart_service を使えば、AI が毎回 cd /path && ... のようなシェルコマンドのつなぎ合わせを言い直す必要がありません。
• remote_path、restart_cmd、logs、allowed_commands、blocked_patterns などの設定値は一度保存すれば、すべての呼び出しで再利用されます。

重要なのは、単に「SSH コマンドが減る」ということだけではありません。次のような効果もあります。

• 同じインフラ情報についての推論の繰り返しが減る
• モデルが読み取る出力が減る
• ノイズの多いシェルトランスクリプトが原因の追加プロンプトが減る

AI にシェルを自由に使わせるより優れている理由

生の SSH は AI に大きな権限を与えますが、構造はほとんどありません。

RemoteBridge は次の機能を追加します。

• 設定の認識：対象ホスト、デプロイ先のパス、再起動コマンド、ログのパスを remotebridge.yaml に保存します。
• 運用上のセマンティクス：deploy、diagnose_failure、compare_targets などのツールは、単なるシェル構文ではなく、意図を表します。
• より安全なデフォルト設定：危険なコマンドには確認を必須にしたり、完全にブロックしたり、許可リストに登録されたプレフィックスのみに制限したりできます。
• より適切な出力制御：MCP のインターフェースは、すべてをそのまま出力するのではなく、圧縮された有用な出力を返します。
• ローカルとリモートの連携：ローカルファイルのリモートサーバーへの同期が別途手動で行う手順ではなく、同じワークフローに組み込まれています。

最後の点は重要です。リモートシェルだけでは、ローカルでコミットされていないコードを確認できません。RemoteBridge なら、AI がローカルで変更した内容を正確に同期し、それに依存するリモート側の手順を実行できます。

主な価値

RemoteBridge は、シェルとして SSH を上回ろうとしているわけではありません。

AI エージェントに、次の手順よりも優れた抽象化を提供することを目指しています。

1. ホストを推測する
2. パスを推測する
3. サービスマネージャーを推測する
4. ログを推測する
5. 出力を過剰に表示する
6. もう一度試す

Rust で構築した理由

RemoteBridge は Node.js や Python でも実装できました。この記事で紹介するツールの用途に関係する実用的な理由から、Rust を選びました。

Rust が適している理由は次のとおりです。

• 起動が速い単一のネイティブバイナリを生成できるため、CLI や stdio を使う MCP での利用に適しています。
• 実行時に Python ランタイムや、より大きな JS ランタイムスタックをユーザーが管理する必要がありません。
• ssh、rsync、ログのストリーミング、MCP stdio の処理など、プロセスと I/O を多用するツールに適しています。
• エラー処理とデータフローについてコンパイル時に強い保証が得られるため、デプロイやリモート実行のツールにとって重要です。
• ツール呼び出しを繰り返す場合でも、パフォーマンスが予測しやすく、オーバーヘッドが小さい傾向があります。

このプロジェクトでは、具体的に次のようなメリットがあります。

• MCP クライアントがサーバーを起動する際の起動時間が短縮されます。
• すぐにインストールして使いたい CLI のパッケージングが簡単になります。
• ssh や rsync などのシステムツールをラップするのに適したネイティブバイナリを利用できます。
• 大規模なスクリプトランタイムスタックと比べて、ランタイム依存関係に関するリスク範囲が小さくなります。

Node.js や Python でも実現は可能でしたが、AI クライアントとリモートインフラの間を信頼性の高いシステムブリッジとしてつなぐツールには、Rust のほうが適しています。

特徴

特徴	重要な理由
Rsync による同期	すべてを再アップロードせずに、ローカルのコードをサーバーへプッシュできます
SSH 多重化	同期やコマンドの呼び出しを繰り返す際に、OpenSSH の制御接続を再利用します
構造化された MCP ツール	毎回シェル文字列を組み立てる代わりに、AI が意味に基づくアクションを実行できます
出力の切り詰め	コマンドの応答を、モデルのコンテキストで有用な範囲に収めます
事前チェック	実行時の情報を一度に取得します
デプロイパイプライン	同期 → 再起動 → 失敗ログの取得という流れを、1 つの操作として実行します
失敗の診断	サービスの状態、実行時情報、リスナー、ディスク、メモリ、ログをコンパクトなサマリーにまとめます
ターゲットの比較	環境間の設定の差異と実行時の差異を明らかにします
安全ゲート	確認、厳格なブロック、許可リストにより、破壊的なミスを減らします
監査ログ	実際に実行された内容と終了時の状態を記録します
監視モード	編集とテストのループ中、リモートターゲットとの同期を維持します
ターゲットごとの SSH 設定	環境ごとにホスト、ユーザー、パス、ポート、キーを設定できます

実践例

RemoteBridge を使わずに、デプロイの不具合を調査する AI は、たいてい次のように作業します。

1. SSH で接続します。
2. pwd の実行を指示します。
3. ls の実行を指示します。
4. アプリのパスを探します。
5. サービスの再起動方法を推測します。
6. ログの取得を指示します。
7. 必要以上に大量の出力を取得します。
8. 出力にノイズが多いため、追加の質問をします。

RemoteBridge を使えば、同じ依頼を次のように行えます。

あなた：「ステージング環境へのデプロイが失敗しています。原因を調査してください。」

AI は diagnose_failure を呼び出し、次の情報を取得できます。

• ターゲットの識別情報
• 推定されたサービスマネージャー
• サービスの健全性
• 実行時のバージョン
• ディスクまたはメモリの逼迫状況を示す情報
• 関連するログの抜粋
• 考えられる原因
• 次の手順の提案

これは、複数回にわたるシェルのやり取りよりも、コンテキストをはるかに効果的に活用できます。

クイックスタート

1. インストール

前提条件：Rust、rsync、ssh が PATH から利用できること。

npm install -g remote-bridge-cli

2. MCP サーバーを AI ツールに追加する

claude mcp add remote-bridge --scope user -- remote-bridge mcp

その他のツールについては、以下の MCP サポートを参照してください。

3. プロジェクト設定を初期化する

remote-bridge init --name my-app -H your-server.com --user ubuntu --path /var/www/app

これにより remotebridge.yaml が作成され、AI ワークフローで共有する唯一の信頼できる情報源になります。

設定例

project_name: "my-app"
targets:
  staging:
    host: "13.234.xx.xx"
    user: "ubuntu"
    remote_path: "/var/www/html/app"
    port: 22
    ssh_key: "~/.ssh/id_rsa"
    restart_cmd: "pm2 restart app"
    logs:
      - "/var/www/html/app/logs/error.log"
      - "/var/log/nginx/error.log"
    require_confirmation: false
    exclude:
      - "node_modules/"
      - "*.log"
    blocked_patterns:
      - "rm -rf"
      - "drop table"
    allowed_commands:
      - "npm"
      - "pm2"
    audit_log: "~/.remote-bridge-staging.log"
  production:
    host: "prod.example.com"
    user: "ubuntu"
    remote_path: "/opt/app"
    ssh_key: "~/keys/prod.pem"
    restart_cmd: "systemctl restart myapp"
    logs:
      - "/opt/app/logs/error.log"
    require_confirmation: true

remotebridge.yaml が重要な理由

このファイルがあるため、MCP ツールは生の SSH よりも便利です。

AI がその都度調べ直す必要のない情報を保存します。

• アプリの配置場所
• 再起動方法
• 重要なログ
• 安全に実行できるコマンド
• より厳格な確認が必要な環境

こうした情報を一度記述しておけば、以降のツール呼び出しはすべて、より簡潔で低コストになります。

CLI コマンド

コマンド	説明
init	新しい remotebridge.yaml を作成します
sync	ローカルファイルをリモートサーバーに同期します
sync --dry-run	サーバーに変更を加えずに rsync の変更内容をプレビューします
run <cmd>	リモートコマンドを 1 つ実行します
preflight	リモートの OS と実行時バージョンを収集します
logs	設定済みのログの最新分を取得します
logs --follow	設定済みのログをリアルタイムでストリーミングします
restart	設定済みのサービスを再起動します
deploy	同期と再起動を行い、再起動が失敗した場合は原因調査に役立つ情報を取得します
watch	ローカルファイルを監視し、変更時に自動で同期します
apply	AI の出力から Markdown を解析し、ファイルの変更とシェルコマンドを適用します

AI CLI との連携

RemoteBridge はパイプでの連携にも対応しています。

Claude Code

claude "Fix the database connection in src/db.ts and restart the app" --non-interactive \
  | remote-bridge apply --target staging

Gemini CLI

gemini "Add rate limiting to the Express API" \
  | remote-bridge apply --target staging

Aider

aider --message "Refactor the login logic" --apply \
  | remote-bridge apply --target staging

MCP サポート

RemoteBridge はネイティブの MCP サーバーです。MCP 互換の AI IDE であれば、どれでも利用できます。

利用可能な MCP ツール

ツール	実用上の価値
sync_to_remote	同じ AI セッションからローカルのコードをサーバーにプッシュします
run_remote_command	出力を制限してリモートのシェルコマンドを実行します
preflight_check	実行時の情報を簡潔なレスポンスで取得します
fetch_logs	パスを再確認せずに、設定済みのログを取得します
restart_service	設定済みの再起動コマンドを安全に再利用します
deploy	標準的なリモートデプロイの流れを1つのアクションとして実行します
diagnose_failure	生のシェルデバッグを垂れ流す代わりに、障害の状況を収集して要約します
compare_targets	設定と実行時の情報の両方を使って環境を比較します

これらのツールで、AI は生の SSH より優れた作業を行えます

diagnose_failure は最もわかりやすい例です。

生の SSH を使うエージェントは、次のことを判断する必要があります。

• どのサービスマネージャーが存在するか
• その状態をどう確認するか
• どのログを読むか
• 何行を末尾から取得するか
• ディスク、メモリ、ポートの状態が関係する可能性があるか
• どの行が有用な情報で、どの行がノイズか

diagnose_failure は、この調査を1つの操作にまとめています。

compare_targets もその一例です。SSH では一度に1台のサーバーしか調査できません。このツールは、次の項目を比較します。

• ホスト／パス／設定の違い
• 確認ポリシーのずれ
• サービスマネージャーの違い
• 実行環境のバージョンの違い
• 概要レベルの互換性リスク

SSH でこれができないわけではありません。ただ、AI が行うにはコストがかかり、繰り返しも必要です。

リクエストの例

MCP 対応 IDE では、次のように指示できます。

• 「現在のプロジェクトをステージングに同期して。」
• 「ローカルの最新の変更をステージングにデプロイして。」
• 「本番環境にインストールされている実行環境を確認して。」
• 「デプロイ後にアプリが失敗しました。ステージングを診断して。」
• 「ステージングと本番環境を比較して、実行環境のずれがバグの原因になり得るか教えて。」
• 「本番環境のログの末尾100行を表示して。」

MCP の設定例

Claude Desktop

ファイル：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "remote-bridge": {
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

Cursor

ファイル：~/.cursor/mcp.json または .cursor/mcp.json

{
  "mcpServers": {
    "remote-bridge": {
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

VS Code / Cline / Continue / Copilot 対応の MCP クライアント

{
  "servers": {
    "remote-bridge": {
      "type": "stdio",
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

Codex CLI

ファイル：~/.codex/config.json

{
  "mcpServers": {
    "remote-bridge": {
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

またはインラインで指定します。

codex --mcp-server "remote-bridge mcp" "Diagnose the staging deploy failure"

汎用 MCP パターン

{
  "command": "remote-bridge",
  "args": ["mcp"],
  "transport": "stdio"
}

SSH 認証

RemoteBridge は既存の SSH 設定を使用します。

1. キーをサーバーにコピーします。

   ssh-copy-id -i ~/.ssh/id_rsa.pub [email protected]
   

2. または、設定でキーとポートを指定します。

   targets:
     staging:
       host: "13.234.xx.xx"
       user: "ubuntu"
       port: 2222
       ssh_key: "~/keys/staging.pem"
   

3. または、~/.ssh/config のエイリアスを使用します。

   Host staging-server
       HostName 13.234.xx.xx
       User ubuntu
       IdentityFile ~/keys/my-key.pem
       Port 22
   

   次に、エイリアスを host に指定します。

   targets:
     staging:
       host: "staging-server"
       user: "ubuntu"
   

安全性モデル

RemoteBridge は AI による実行を想定して設計されているため、安全性は必須です。

確認ゲート

sudo、rm、drop、delete、shutdown、reboot、killall、curl | bash などのリスクのあるパターンを含むコマンドは、実行前に確認が必要です。

ハードブロック

blocked_patterns に含まれるものは、常に拒否されます。

targets:
  production:
    blocked_patterns:
      - "rm -rf"
      - "drop table"
      - "truncate"

許可リスト

allowed_commands が設定されている場合、一致するプレフィックスを持つコマンドのみ許可されます。

targets:
  production:
    allowed_commands:
      - "npm"
      - "pm2"
      - "systemctl restart myapp"

監査ログ

すべてのコマンドは自動的に記録されます。

[1742660591] host=your-server.com path=/var/www/app exit=0 cmd=npm install
[1742660612] host=your-server.com path=/var/www/app exit=-2 cmd=rm -rf /var/data

終了コード：

• 0+ 実際のプロセス終了コード
• -1 ユーザーによってスキップ
• -2 ハードブロック
• -3 許可リストに未登録

その他の保護機能

• require_confirmation: true を設定すると、機密性の高い対象へのすべてのコマンドで確認を必須にできます。
• sync --dry-run を実行すると、同期前に変更内容をプレビューできます。
• RemoteBridge はパスワードを保存しません。
• remotebridge.yaml にシークレットを保存する必要はありません。
• MCP の出力には上限があるため、ノイズの多いコマンドを1つ実行してもモデルのコンテキストがあふれません。

正直なトレードオフ

生のターミナルが必要なら、SSH を使ってください。

再確認やシェル用の接着コード、ノイズの多い出力にトークンを繰り返し浪費せず、AI にリモートインフラを確実に扱わせたいなら、RemoteBridge を使ってください。

それが RemoteBridge の価値です。

貢献

貢献や問題の報告は、GitHub の Issues で歓迎しています。

ライセンス

MIT ライセンス。