金大哥 - ghost-bridge-mcp MCP 详情

article

README

🚀 幽灵桥 (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 扩展

打开 Chrome 浏览器，导航到 chrome://extensions。
点击右上角的 开发者模式 开关。
点击 加载已解压的扩展程序。
选择目录：~/.ghost-bridge/extension。

💡 提示：运行 ghost-bridge extension --open 可直接打开该目录。

3. 连接并执行命令

点击浏览器工具栏中的 幽灵桥（Ghost Bridge） 幽灵图标。
点击连接，等待状态变为 ✅ 已开启。
打开 Claude 桌面应用或 Claude CLI。所有工具现已准备就绪！

✨ 主要特性

🔌 零配置连接 — 无需使用 --remote-debugging-port，通过扩展程序直接捕获 Chrome 的原生 DevTools 协议。
🔍 无源码映射调试 — 切片代码片段、执行字符串搜索并分析覆盖率，直接在压缩后的生产代码中定位 bug。
🌐 深度网络分析 — 全面捕获请求/响应，支持多维过滤和响应体检查。
📸 视觉与结构感知 — 全页或裁剪的高保真截图，同时提取结构数据（标题、链接、表单、按钮）。
🎯 DOM 物理操作 — 使 AI 能够通过 CDP 级别的物理模拟进行点击、输入和表单提交操作，完全兼容复杂的单页应用（React/Vue/Angular/Svelte）。
📊 性能诊断 — 获取详细的引擎指标：JS 堆、布局重计算、网页关键指标（TTFB/FCP/LCP）和资源加载速度。
🔄 多客户端管理 — 内置单例管理器，可自动协调多个共享单个 Chrome 传输的 MCP 客户端。

🛠️ 工具库

🔍 核心调试

| 工具 | 功能 | |------|------------| | get_server_info | 获取服务器实例状态、WebSocket 端口和客户端角色。 | | get_last_error | 汇总最近的异常、控制台错误和失败的网络请求，并映射定位信息。 | | get_script_source | 获取原始脚本定义，支持 URL 片段过滤、特定行定位和代码美化。 | | coverage_snapshot | 触发快速覆盖率跟踪（默认 1.5 秒），识别页面上最活跃的脚本。 | | find_by_string | 在页面脚本源中搜索关键字，返回 200 字符的上下文窗口。 | | symbolic_hints | 收集上下文线索：资源列表、全局变量键、本地存储模式和用户代理字符串。 | | eval_script | 在页面上下文中执行原始 JavaScript 表达式。（谨慎使用） |

🌍 网络智能

| 工具 | 功能 | |------|------------| | list_network_requests | 列出捕获的网络流量，支持按 URL、方法、状态码或资源类型过滤。 | | get_network_detail | 深入查看特定请求的头部、时间信息和可选的响应体提取。 | | clear_network_requests | 清除当前的网络捕获缓冲区。 |

📸 页面感知

| 工具 | 功能 | |------|------------| | capture_screenshot | 捕获视口或模拟全页滚动截图。 | | get_page_content | 提取原始文本、清理后的 HTML 或结构化的可操作数据表示。 |

🎯 交互式自动化（DOM）

| 工具 | 功能 | |------|------------| | get_interactive_snapshot | 扫描可见的交互式元素，返回简洁的映射 [e1, e2...]，可穿透打开的 Shadow DOM。 | | dispatch_action | 针对目标元素引用（例如 e1）调度物理 UI 操作（点击、填充、按键、悬停）。 |

示例代理工作流程：

AI：get_interactive_snapshot ➝ [{ref:"e1", tag:"input", placeholder:"Search..."}, {ref:"e2", tag:"button", text:"Login"}]
AI：dispatch_action({ref: "e1", action: "fill", value: "hello"})
AI：dispatch_action({ref: "e2", action: "click"})
AI：capture_screenshot 以验证状态变化。

📊 性能分析

| 工具 | 功能 | |------|------------| | perf_metrics | 收集分层性能数据（引擎指标、网页关键指标和资源加载摘要）。 |

⚙️ 配置

| 设置 | 默认值 | 描述 | |---------|---------|-------------| | 基础端口 | 33333 | WebSocket 端口，若被占用会自动递增。 | | 令牌 | 每月 UUID | 本地 WebSocket 认证令牌，每月 1 日自动轮换。 | | 自动分离 | false | 保持调试器连接，以主动缓冲不可见的异常和网络调用。 |

环境变量：

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

ghost-bridge-mcp