DarwinRelay

MCPエージェント向けネイティブmacOS実行ランタイム:シェル、PTY、バックグラウンドChrome、Accessibilityベースのデスクトップ制御。

DarwinRelayはMCPクライアントを、あなたがすでに使っているMacに接続します。クライアントとmacOSの間に別のモデルループを挟むことなく、構造化されたローカルマシン機能を公開します:無制限のシェル/ファイルシステムアクセス、対話型PTY、長時間実行ジョブ、永続化されたCodex履歴、管理されたバックグラウンドChromeワークスペース、そしてAccessibility、ScreenCaptureKit、Vision、CoreGraphicsによるネイティブデスクトップ制御。

[!CAUTION] DarwinRelayは意図的に強力です。これはサンドボックスではありません。また、ファイルシステムやシェルコマンドの許可リストも実装していません。接続されたクライアントは、ブリッジを実行しているmacOSユーザーの実効権限で動作できます。localhostの範囲を超えて公開する前に、SECURITY.mdをお読みください。

DarwinRelayを選ぶ理由

多くのMCPサーバーは1つの狭いAPIしか公開しません。DarwinRelayは、有用な状態がすでにMac上に存在する開発者向けおよびコンピューター使用ワークフローのためのローカル実行ランタイムとして設計されています:

• シェルとファイル — コマンドの実行、ファイルの検査・変更、パッチの適用、ローカルプロセスの管理。

• 本物のPTY — 対話型シェル、REPL、SSH、sudoプロンプト、TUI、長時間実行ターミナルプログラム。

• ネイティブコンピューター使用 — セマンティックなAXクエリ/アクション、ウィンドウ、ダイアログ、開く/保存パネル、キーボード/マウスのフォールバック、スクリーンショット、OCR、ビジュアル待機。

• バックグラウンドブラウザ自動化 — フォーカスを奪わずにナビゲート、検査、入力、クリックができる専用のChrome拡張機能所有タブプール。

• Codex履歴 — 新しいモデルターンを開始せずに永続化されたCodexスレッドを読み取り。

• リモートMCPトランスポート — ローカルではstdio、またはあなたが管理するトンネルの背後にある認証付きHTTP/OAuthフロントエンド。

• フェイルクローズのライフサイクル — 明示的なフルアクセスロック解除、監査ログ、プロセス回収、シングルトンメニュー所有権、ロールバック対応アプリ更新。

Related MCP server: mcp-server-macos-use

アーキテクチャ

flowchart LR
    A[MCP client] --> B[DarwinRelay bridge]
    B --> C[Shell / filesystem / jobs]
    B --> D[PTY helper]
    B --> E[Codex persisted history]
    B --> F[MacUIHelper]
    F --> G[Accessibility / ScreenCaptureKit / Vision / CGEvent]
    B --> H[Chrome native host]
    H --> I[DarwinRelay Chrome extension]
    I --> J[Background DR tab pool]

ネイティブデスクトップヘルパーは特権デーモンではなく、意図的に短命です。メニューアプリ、MacUIHelper、仮想カーソルは安定したコード署名識別子を使用するため、永続的な署名IDが利用可能な場合、macOSのTCC許可は通常の再ビルド後も維持されます。

要件

• macOS 13以降

• Node.js 18以降(CIではNode.js 22を使用)

• ネイティブデスクトップ制御とメニューアプリ用のXcodeコマンドラインツール/swiftc

• ネイティブコンピューター使用のためのAccessibilityおよびScreen Recording権限

• 管理されたchrome_*バックグラウンドワークスペースが必要な場合のみGoogle Chrome

• HTTPトランスポートをリモートで公開する場合のみcloudflaredまたは別のHTTPSトンネル

• codex_thread_*履歴ツールが必要な場合のみCodex CLI

クイックスタート

リポジトリをクローンし、メニューアプリをビルドします:

git clone https://github.com/dcierra/darwinrelay.git
cd darwinrelay
npm run check
./menubar/build.sh
open /Applications/DarwinRelay.app

アプリがmacOSメニューバーにDRとして表示されます。要求されたデスクトップ権限を付与し、設定済みのHTTP/トンネルパスにはStartを使用します。

ソースのみのローカルMCP使用の場合、ブリッジを直接実行することもできます。フルアクセスは明示的に承認する必要があります:

export DARWINRELAY_FULL_ACCESS_ACK=I_UNDERSTAND_THIS_GRANTS_FULL_ACCESS
node bridge.mjs

デフォルトのランタイム状態は以下に置かれます:

~/Library/Application Support/DarwinRelay
~/Library/Logs/DarwinRelay

DARWINRELAY_DATA_DIR、DARWINRELAY_LOG_DIR、DARWINRELAY_SHELL、DARWINRELAY_AUDIT_MODEなどの環境変数を使用して、開発/テストインスタンスを分離できます。

AIおよびコーディングエージェント向け

このリポジトリには意図的にエージェント向けドキュメントが含まれています。リポジトリをCodex、Claude、ChatGPT、または他のコーディングエージェントに渡す場合は、まず**AGENTS.md**を参照させてください。このファイルには、リポジトリマップ、不変条件、開発コマンド、テストの期待事項、署名/ブラウザのルール、リリース制約が記載されています。

ソースを変更するのではなく、インストール済みのDarwinRelayランタイムを操作するエージェントの場合は、**docs/AGENT_OPERATIONS.mdを使用してください。完全なツールファミリーマップ、推奨される判断順序、一般的な障害状態、安全なランタイムワークフローが含まれています。docs/ARCHITECTURE.md**は、より深い推論のためのコンポーネント/データフローと信頼境界を説明しています。

ネイティブデスクトップ制御

DarwinRelayはセマンティックなAccessibility操作を優先し、ビジュアル/生入力はフォールバックとして使用します。中核となる機能は次のとおりです:

• ui_observe、ui_tree、ui_ax_query、ui_ax_at

• 古い参照検出付きのフィンガープリントAX参照

• ui_action、ui_wait_for、ui_assert

• ui_app_*、ui_window_*、ダイアログ、ファイルパネル

• ScreenCaptureKitスクリーンショットとVision OCR

• macOSがサポートする場合のバックグラウンドPIDターゲット入力(セマンティック検証と制限付きフォアグラウンドフォールバック付き)

• 決定的なマルチステップネイティブバースト用のui_sequence

• 物理ポインターを動かさないクリックスルー仮想AIカーソル

制御モデルと制限事項についてはdocs/DESKTOP_CONTROL.mdを参照してください。

バックグラウンドChromeワークスペース

DarwinRelayは、解凍されたChrome拡張機能とNative Messagingを使用します。公開拡張機能のIDは安定しています。期待される拡張機能IDは次のとおりです:

pfhahlehpahegefejooendokpkklgmgd

インストーラーは、デフォルトでサインアウトしたDarwinRelayという名前のローカルChromeプロファイルを作成または再利用します。これにより、エージェントのブラウジング状態が日常のGoogleプロファイルから分離されます:

# Recommended/default: dedicated local profile named DarwinRelay
./scripts/install-background-chrome.sh

# Explicit alternatives only when you want them
./scripts/install-background-chrome.sh --profile 'Some Existing Profile'
./scripts/install-background-chrome.sh --use-current-profile

デフォルトのプロファイルは、他のプロファイルのブラウジングデータを削除または変更せずに作成されます。DarwinRelayプロファイルがまだ存在しない場合は、インストーラーを実行する前にChromeを一度終了してください。ChromeがLocal Stateを同時に書き換えるのを防ぐためです。プロファイルが存在した後は、Chromeを開いたまま通常の再インストールを実行できます。DarwinRelayのアンインストールは、ブラウザプロファイルの内容がユーザーデータであるため、意図的にそのプロファイルを残します。

次に、選択したプロファイル内でのみ、chrome://extensionsを開き、デベロッパーモードを有効にして、Load unpackedを選択し、このリポジトリのchrome-extension/ディレクトリを選択します。この1回限りのセットアップ手順では、インストーラーに--openを渡すことができます。

拡張機能は、DRという名前のChromeネイティブタブグループを所有します。通常のchrome_open呼び出しは、任意のフォアグラウンドタブを作成する代わりに、事前作成されたアイドルタブをリースします。chrome_closeはワークスペースタブをプールに戻します。

ブラウザセキュリティモデル

緩和された承認がデフォルトです。設定されたchrome_*ワークスペースを通じた通常のHTTP/HTTPS作業には、サイトごとのターミナル許可は必要ありません。メニューアプリでStrict approvalsを有効にすると、スコープ付きURL許可と1回限りのアプリスコープネイティブ変更承認が復元されます。

シェル/AppleScript/JXAによる直接のChrome自動化はブリッジによってブロックされたままなので、通常のWeb作業は管理されたバックグラウンドパスに留まります。ブラウザ/OSのセキュリティサーフェスが本当にそれを必要とする場合、別のネイティブui_*サーフェスはフォアグラウンドChrome UIと対話できます。

オプションの生のBrowser Harness/CDPアダプターがDARWINRELAY_ADVANCED_BROWSER=1の背後に存在します。これはデフォルトで無効であり、任意のCDPはURLスコープに健全に還元できないため、Strict approvalsではフェイルクローズします。

HTTP / OAuthトランスポート

mcp-http.mjsはループバックにバインドし、静的ベアラートークンと、リモートMCPクライアントが使用するOAuth 2.1フローを備えたMCP HTTPトランスポートをサポートします。CloudflareなどのトンネルがループバックサービスをHTTPSで公開できます。

最小限のローカルフロントエンドは次のようになります:

mkdir -p "$HOME/Library/Application Support/DarwinRelay"
openssl rand -hex 32 > "$HOME/Library/Application Support/DarwinRelay/http-token"
chmod 600 "$HOME/Library/Application Support/DarwinRelay/http-token"

export DARWINRELAY_HTTP_TOKEN_FILE="$HOME/Library/Application Support/DarwinRelay/http-token"
node mcp-http.mjs

SECURITY.mdのリモートアクセス脅威モデルを読まずにHTTPエンドポイントを公開しないでください。このフロントエンドが受け入れる資格情報は、最終的にはデスクトップユーザーとしてのローカルコード実行を許可します。

リポジトリには、そのトランスポートを好むユーザーのために、元のプロジェクトから継承したOpenAI Secure MCP Tunnelインストーラーも保持されています。DEPLOY.mdを参照してください。

開発

npm run check
npm run test:core
npm run test:desktop
npm run test:lifecycle
# or all groups
npm test

公開CIは、1つの不透明なtestジョブではなく、意図的に個別のチェックを公開しています:

• 静的チェック — 構文/ネイティブビルド検証と全履歴gitleaksスキャン

• コアおよびプロトコルテスト — MCP、HTTP/OAuth、PTY、フェデレーション、ブラウザ、敵対的テスト

• デスクトップ制御テスト — 決定的なデスクトッププロトコルテストとネイティブフィクスチャコンパイル

• インストールおよびライフサイクルテスト — インストーラー、自動起動、シングルトン所有権、ロールバック、アンインストール動作

実際の可変AppKit E2Eは、TCC権限を持つログイン済みMacが必要なため、使い捨てのGitHubホストGUIセッションでは信頼できるものとして扱われません。メンテナーはローカルで次のコマンドで実行できます:

DARWINRELAY_RUN_NATIVE_DESKTOP_E2E=1 node tests/desktop-control-native.mjs

プルリクエストを開く前にCONTRIBUTING.mdを参照してください。

セキュリティ

重要な境界は単純です:DarwinRelayは、それを実行するmacOSアカウントの権限を持ちます。 ロック解除ファイル、Strict approvals、監査メタデータ、OAuth、バックグラウンドブラウザルーティング、プロセス回収などのセキュリティ機能は、偶発的またはリモートでの悪用を減らします。これらは、任意のシェルアクセスをサンドボックスに変えるものではありません。

セキュリティレポートは、公開issueではなく、GitHubのプライベート脆弱性報告を使用してください。SECURITY.mdを参照してください。

プロジェクトの系譜

DarwinRelayは独立してメンテナンスされており、Alexander Rådahl BenzによるMac Developer Bridgeから大幅に分岐しています。継承されたアップストリーム履歴は意図的に保存されており、元のMIT著作権表示はLICENSEに残っています。正確な系譜と帰属ポリシーについてはUPSTREAM.mdを参照してください。

公開のdcierra/darwinrelayリポジトリが正規の開発ソースです。以前のプライベートリポジトリは、インストール済みの0.5.xランタイムが移行されるまでの一時的なレガシー本番/ロールバック系譜としてのみ保持されています。これは2番目のアクティブな開発ブランチではありません。コミット履歴のマッピングと将来のワークフローについてはdocs/DEVELOPMENT_MODEL.mdを参照してください。

DarwinRelayはOpenAI、Apple、Google、Cloudflare、またはアップストリームメンテナーとは提携しておらず、その承認も受けていません。

ライセンス

MIT。LICENSEとUPSTREAM.mdを参照してください。