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 许可证。