Ghost Bridge MCP

🚀 幽靈橋 (Ghost Bridge)

零重啟的 Chrome AI 副駕駛，顛覆你的工作流程。讓 AI 無縫接管你正在使用的瀏覽器，無需啟動新的 Chrome 實例，即可實現即時調試、可視化觀察和交互式操作。

🚀 快速開始

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. 點擊 連接，等待狀態變為 ✅ 已開啟。
3. 打開 Claude 桌面應用或 Claude CLI。所有工具現已準備就緒！

✨ 主要特性

• 🔌 零配置連接 — 無需使用 --remote-debugging-port，通過擴展程序直接捕獲 Chrome 的原生 DevTools 協議。
• 🔍 無源碼映射調試 — 切片代碼片段、執行字符串搜索並分析覆蓋率，直接在壓縮後的生產代碼中定位 bug。
• 🌐 深度網絡分析 — 全面捕獲請求/響應，支持多維過濾和響應體檢查。
• 📸 視覺與結構感知 — 全頁或裁剪的高保真截圖，同時提取結構數據（標題、鏈接、表單、按鈕）。
• 🎯 DOM 物理操作 — 使 AI 能夠通過 CDP 級別的物理模擬進行點擊、輸入和表單提交操作，完全兼容複雜的單頁應用（React/Vue/Angular/Svelte）。
• 📊 性能診斷 — 獲取詳細的引擎指標：JS 堆、佈局重計算、網頁關鍵指標（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 通過標準 I/O 流啟動，協調 WebSocket 連接。
• Chrome 擴展（MV3）：利用 chrome.debugger API，使用離屏文檔防止 WebSocket 休眠。
• 單例設計：如果多個代理啟動服務器，第一個將成為主橋，後續實例將透明地作為客戶端鏈接。

⚠️ 已知限制

• 服務工作線程暫停：MV3 後臺工作線程可能會暫停。我們已經構建了強大的自動重連邏輯，但長時間不活動可能需要重新切換。
• DevTools 衝突：如果手動在目標標籤頁打開 Chrome DevTools（F12），chrome.debugger.attach 可能會被拒絕。
• 美化開銷：美化大型單行捆綁包的成本較高，服務器將自動截斷過大的腳本。
• 跨源 OOPIF：深度嵌入嚴格跨源 Iframe 中的元素和錯誤可能會避開主調試器鉤子，需要進一步的多目標連接邏輯。

🤝 貢獻

歡迎貢獻代碼、提出問題和請求新功能！查看我們的 貢獻指南，開始構建工具或改進橋樑。

📄 許可證

本項目採用 MIT 許可證。