Ghost Bridge MCP

🚀 👻 Ghost Bridge

ゼロ再起動のChrome AIコパイロット。作業フローを革新します。新しいChromeインスタンスを起動することなく、AIが既に使用しているブラウザをシームレスに引き継ぎ、リアルタイムのデバッグ、視覚的な観察、インタラクティブな操作を可能にします。

🚀 クイックスタート

1. インストールと初期化

# グローバルにインストール
npm install -g ghost-bridge

# MCP (Claude Code, Antigravity, Codex) を自動設定し、拡張機能ディレクトリを準備
ghost-bridge init

他のMCPクライアント (Cursor, Windsurf, Roo) に関する注意： ghost-bridge init はサポートされているクライアントを自動設定しようとします。クライアントが自動検出されない場合は、クライアントのMCP設定ファイル (例: mcp.json) に以下を追加してください。

{
  "mcpServers": {
    "ghost-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
    }
  }
}

2. Chrome拡張機能の読み込み

1. Chromeを開き、chrome://extensions に移動します。
2. 右上隅の 開発者モード をオンにします。
3. パッケージ化されていない拡張機能を読み込む をクリックします。
4. ディレクトリ ~/.ghost-bridge/extension を選択します。

💡 ヒント: ghost-bridge extension --open を実行すると、ディレクトリを直接開くことができます。

3. 接続とコマンド実行

1. ブラウザのツールバーにある Ghost Bridge の幽霊アイコンをクリックします。
2. 接続 をクリックし、ステータスが ✅ ON に変わるのを待ちます。
3. Claude DesktopまたはClaude CLIを開きます。すべてのツールが準備完了です！

✨ 主な機能

• 🔌 ゼロコンフィグ接続 — --remote-debugging-port を必要とせず、拡張機能を通じてChromeのネイティブDevToolsプロトコルを直接キャプチャします。
• 🔍 ソースマップなしのデバッグ — コード断片を切り出し、文字列検索を行い、カバレッジを分析して、圧縮された本番コード内のバグを直接特定します。
• 🌐 深いネットワーク分析 — リクエスト/レスポンスを包括的にキャプチャし、多次元フィルタリングとレスポンスボディの検査を行います。
• 📸 視覚的および構造的知覚 — 全ページまたはクリッピングされた高忠実度のスクリーンショットを撮影し、構造データ (タイトル、リンク、フォーム、ボタン) を抽出します。
• 🎯 DOMの物理操作 — AIにCDPレベルの物理シミュレーションでクリック、入力、フォーム送信を行わせることができます。複雑なSPA (React/Vue/Angular/Svelte) と完全に互換性があります。
• 📊 パフォーマンス診断 — 詳細なエンジンメトリックを取得します: JSヒープ、レイアウト再計算、Web Vitals (TTFB/FCP/LCP)、およびリソースの読み込み速度。
• 🔄 マルチクライアント管理 — 組み込みのシングルトンマネージャが自動的に、単一のChromeトランスポートを共有する複数のMCPクライアントを調整します。

🛠️ ツール群

🔍 コアデバッグ

🌍 ネットワークインテリジェンス

📸 ページ知覚

🎯 インタラクティブオートメーション (DOM)

エージェントのワークフロー例：

1. AI: get_interactive_snapshot ➝ [{ref:"e1", tag:"input", placeholder:"Search..."}, {ref:"e2", tag:"button", text:"Login"}]
2. AI: dispatch_action({ref: "e1", action: "fill", value: "hello"})
3. AI: dispatch_action({ref: "e2", action: "click"})
4. AI: capture_screenshot で状態の変化を確認する。

📊 パフォーマンスプロファイリング

⚙️ 設定

環境変数：

• GHOST_BRIDGE_PORT — ベースポートを上書きします。
• GHOST_BRIDGE_TOKEN — 接続トークンを上書きします。

🏗️ アーキテクチャ

graph LR
    A[Claude CLI/Desktop] <-->|stdio| B(MCP Server\nserver.js)
    B <-->|WebSocket| C(Chrome Extension\nbackground.js)
    C <-->|CDP| D[Browser Tab\nTarget Context]

• MCPサーバー：Claudeによって標準入出力ストリームを介して起動されます。WS接続を調整します。
• Chrome拡張機能 (MV3)：chrome.debugger APIを利用します。オフスクリーンドキュメントを使用してWSの休止を防止します。
• シングルトン設計：複数のエージェントがサーバーを起動する場合、最初のサーバーがマスターブリッジになり、それ以降のインスタンスはクライアントとして透過的にチェーンされます。

⚠️ 既知の制限事項

• サービスワーカーの一時停止：MV3のバックグラウンドワーカーが一時停止することがあります。強力な自動再接続ロジックを組み込んでいますが、長時間の非アクティビティの場合は再切り替えが必要になることがあります。
• DevToolsの競合：ターゲットタブで手動でChrome DevTools (F12) を開くと、chrome.debugger.attach が拒否されることがあります。
• 整形のオーバーヘッド：巨大な単一行のバンドルを整形するのはコストがかかります。サーバーは過度に大きなスクリプトを自動的に切り捨てます。
• クロスオリジンOOPIF：厳格なクロスオリジンIframeに深く埋め込まれた要素やエラーは、さらなるマルチターゲットアタッチロジックなしでは、主なデバッガーフックから逃れることがあります。

🤝 コントリビューション

コントリビューション、問題の報告、および機能リクエストは大歓迎です！ ツールの開発やブリッジの改善を始めるには、コントリビューションガイド をご確認ください。

📄 ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。