ghost-bridge 0.4.0 → 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 <Author>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,156 +1,183 @@
-# Ghost Bridge
+# 👻 Ghost Bridge
 
-> 无侵入 Chrome AI 副驾 —— 通过 MCP 让 AI 无缝接管你正在使用的浏览器，实时调试、观察页面、操控交互，无需启动新浏览器实例。
+[![npm version](https://img.shields.io/npm/v/ghost-bridge.svg?style=flat-square)](https://www.npmjs.com/package/ghost-bridge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-## ✨ 特性
+> **Zero-restart Chrome AI Copilot** — Subvert your workflow. Allow AI to seamlessly take over the browser you're already using, enabling real-time debugging, visual observation, and interactive manipulation without launching a new Chrome instance.
 
-- 🔌 **零配置附加** — 不依赖 `--remote-debugging-port`，通过 Chrome 扩展直接获取 CDP
-- 🔍 **无 sourcemap 调试** — 片段截取、字符串搜索、覆盖率分析，在压缩代码中定位问题
-- 🌐 **网络请求分析** — 完整记录请求/响应，支持多维度过滤和响应体查看
-- 📸 **页面截图与内容提取** — 视觉分析 + 结构化数据提取
-- 🎯 **DOM 交互操控** — AI 可直接点击按钮、填写表单、按键提交，使用 CDP 物理级模拟，兼容 React/Vue/Angular
-- 📊 **性能诊断** — JS 堆内存、DOM 规模、Layout 开销、Web Vitals、资源加载分析
-- 🔄 **多实例支持** — 自动单例管理，多个 MCP 客户端共享同一 Chrome 连接
+---
 
-## 快速开始
+## ✨ Why Ghost Bridge?
 
-### 1. 安装与初始化
+- 🔌 **Zero-Config Attach** — Bypasses the need for `--remote-debugging-port`. Captures Chrome's native DevTools Protocol directly via an extension.
+- 🔍 **No-Sourcemap Debugging** — Slice code fragments, perform string searches, and analyze coverage to pinpoint bugs straight in minified production code.
+- 🌐 **Deep Network Analysis** — Comprehensive capture of requests/responses with multi-dimensional filtering and response body inspection.
+- 📸 **Visual & Structural Perception** — Full-page or clipped high-fidelity screenshots paired with structural data extraction (titles, links, forms, buttons).
+- 🎯 **DOM Physical Manipulation** — Empowers AI to click, type, and form-submit with CDP-level physical simulation. Fully compatible with complex SPAs (React/Vue/Angular/Svelte).
+- 📊 **Performance Diagnostics** — Get granular engine metrics: JS Heap, Layout recalculations, Web Vitals (TTFB/FCP/LCP), and resource loading speeds.
+- 🔄 **Multi-Client Mastery** — Built-in singleton manager automatically coordinates multiple MCP clients sharing a single Chrome transport.
 
-```bash
-# 全局安装
-npm install -g ghost-bridge
-
-# 自动配置 Claude MCP 并准备扩展
-ghost-bridge init
-```
-
-### 2. 加载 Chrome 扩展
-
-1. 打开 Chrome，访问 `chrome://extensions`
-2. 开启右上角的 **开发者模式**
-3. 点击 **加载已解压的扩展程序**
-4. 选择目录：`~/.ghost-bridge/extension`
-
-> 💡 运行 `ghost-bridge extension --open` 可直接打开该目录
-
-### 3. 连接并使用
-
-1. 点击浏览器工具栏中的 Ghost Bridge 图标
-2. 点击 **连接**，等待状态变为 ✅ 已连接
-3. 打开 Claude Desktop 或 Claude CLI，即可使用所有调试工具
-
-## CLI 命令
-
-| 命令 | 说明 |
-|------|------|
-| `ghost-bridge init` | 配置 MCP 并复制扩展文件 |
-| `ghost-bridge status` | 检查配置状态 |
-| `ghost-bridge extension` | 显示扩展安装路径（`--open` 打开目录） |
-| `ghost-bridge start` | 手动启动 MCP 服务（通常不需要） |
-
-## 工具一览
-
-### 🔍 基础调试
-
-| 工具 | 说明 |
-|------|------|
-| `get_server_info` | 获取服务器状态（端口、连接状态、角色） |
-| `get_last_error` | 汇总最近的异常 / console 错误 / 网络报错，附行列与脚本标识 |
-| `get_script_source` | 抓取目标脚本源码，支持按 URL 片段筛选、指定行列定位、beautify |
-| `coverage_snapshot` | 启动执行覆盖率采集（默认 1.5s），返回最活跃的脚本列表 |
-| `find_by_string` | 在页面脚本源码中按关键词搜索，返回 200 字符上下文窗口 |
-| `symbolic_hints` | 采集资源列表、全局变量 key、localStorage key、UA 与 URL |
-| `eval_script` | 在页面执行 JS 表达式（谨慎使用） |
-
-### � 网络请求分析
+---
 
-| 工具 | 说明 |
-|------|------|
-| `list_network_requests` | 列出捕获的网络请求，支持按 URL / 方法 / 状态 / 资源类型过滤 |
-| `get_network_detail` | 获取单个请求的详细信息（请求头、响应头、timing），可选获取响应体 |
-| `clear_network_requests` | 清空已捕获的网络请求记录 |
+## 🚀 Quick Start
 
-### 📸 页面内容
+### 1. Install & Initialize
 
-| 工具 | 说明 |
-|------|------|
-| `capture_screenshot` | 截取页面截图（支持完整长截图、指定区域、JPEG/PNG 格式） |
-| `get_page_content` | 提取页面内容：纯文本 / HTML / 结构化数据（标题、链接、按钮、表单） |
-
-### 🎯 页面交互（DOM 操作）
-
-| 工具 | 说明 |
-|------|------|
-| `get_interactive_snapshot` | 扫描页面所有可见可交互元素，返回带 ref 短标识（e1, e2...）的精简列表，支持 Shadow DOM 穿透 |
-| `dispatch_action` | 对目标元素执行动作（click / fill / press / scroll / select / hover / focus），使用 CDP 物理级模拟 |
-
-**交互工作流示例：**
+```bash
+# Install globally
+npm install -g ghost-bridge
 
+# Auto-configure MCP (Claude Code, Codex, Cursor, Antigravity) and prepare the extension directory
+ghost-bridge init
 ```
-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"})
-   → 在搜索框中输入 "hello"
+> `ghost-bridge init` currently writes:
+> - Claude Code: `~/.claude/settings.json` or legacy `~/.claude.json`
+> - Codex: `~/.codex/config.toml`
+> - Cursor: `~/.cursor/mcp.json`
+> - Antigravity: `~/.gemini/antigravity/mcp.json`
+>
+> **Note on other MCP clients (Windsurf, Roo, others):** 
+> `ghost-bridge init` attempts to auto-configure supported clients. If your client isn't auto-detected, add one of the following snippets to the appropriate MCP configuration file:
+>
+> JSON-style MCP configs (`mcp.json`, Claude JSON config, Cursor):
+> ```json
+> {
+>   "mcpServers": {
+>     "ghost-bridge": {
+>       "command": "/absolute/path/to/node",
+>       "args": ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
+>     }
+>   }
+> }
+> ```
+>
+> Codex TOML config (`~/.codex/config.toml`):
+> ```toml
+> [mcp_servers.ghost-bridge]
+> type = "stdio"
+> command = "/absolute/path/to/node"
+> args = ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
+> ```
+
+### 2. Load the Chrome Extension
+
+1. Open Chrome and navigate to `chrome://extensions`
+2. Toggle **Developer mode** in the top right corner.
+3. Click **Load unpacked**
+4. Select the directory: `~/.ghost-bridge/extension`
+
+> 💡 *Tip: Run `ghost-bridge extension --open` to reveal the directory directly.*
+
+### 3. Connect & Command
+
+1. Click the **Ghost Bridge** ghost icon in your browser toolbar.
+2. Click **Connect** and wait for the status to turn to ✅ **ON**.
+3. Open Claude Desktop or your Claude CLI. All tools are now primed and ready!
+
+**Prompting tips:**
+- You usually do not need to say "please use ghost-bridge". Direct requests like `分析当前页面`、`看看这个网站的 DOM 结构`、`帮我检查这个页面为什么布局错了`、`帮我点击登录按钮并提交表单` should be enough.
+- `inspect_page` is the default entry tool for generic page analysis.
+- For visual/UI issues, the model should prefer `capture_screenshot`.
+- For text/DOM extraction, the model should prefer `get_page_content`.
+- For page actions, the model should start with `get_interactive_snapshot` and then call `dispatch_action`.
+
+---
+
+## 🛠️ Tool Arsenal
+
+### 🔍 Core Debugging
+
+| Tool | Capability |
+|------|------------|
+| `inspect_page` | Best default entry for page analysis. Returns metadata, structured content, and an interactive-elements overview. |
+| `get_server_info` | Retrieves server instance status, WebSocket ports, and client roles. |
+| `get_last_error` | Aggregates recent exceptions, console errors, and failed network requests with mapped locators. |
+| `get_script_source` | Pulls raw script definitions. Supports URL-fragment filtering, specific line targeting, and beautification. |
+| `coverage_snapshot` | Triggers a quick coverage trace (1.5s default) to identify the most active scripts on the page. |
+| `find_by_string` | Scans page script sources for keywords, returning a 200-character context window. |
+| `symbolic_hints` | Gathers context clues: Resource lists, Global Variable keys, LocalStorage schema, and UA strings. |
+| `eval_script` | Executes raw JavaScript expressions in the page context. *(Use with caution)* |
+
+### 🌍 Network Intelligence
+
+| Tool | Capability |
+|------|------------|
+| `list_network_requests` | Lists captured network traffic. Supports filtering by URL, Method, Status Code, or Resource Type. |
+| `get_network_detail` | Dives deep into a specific request's Headers, Timing, and optional Response Body extraction. |
+| `clear_network_requests` | Wipes the current network capture buffer. |
+
+### 📸 Page Perception
+
+| Tool | Capability |
+|------|------------|
+| `capture_screenshot` | Captures the viewport or emulates full-page scrolling screenshots. |
+| `get_page_content` | Extracts raw text, sanitized HTML, or structured actionable data representations. |
+
+### 🎯 Interactive Automation (DOM)
+
+| Tool | Capability |
+|------|------------|
+| `get_interactive_snapshot` | Scans for visible interactive elements, returning a concise map `[e1, e2...]`. Pierces open Shadow DOMs. |
+| `dispatch_action` | Dispatches physical UI actions (click, fill, press, hover) against targeted element references (e.g., `e1`). |
+
+**Example Agent Workflow:**
+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` to verify state changes.
+
+### 📊 Performance Profiling
+
+| Tool | Capability |
+|------|------------|
+| `perf_metrics` | Collects layered performance data (Engine Metrics, Web Vitals, and Resource Load Summaries). |
+
+---
+
+## ⚙️ Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| **Base Port** | `33333` | WS port. Auto-increments if occupied. |
+| **Token** | *Monthly UUID* | Local WS auth token, auto-rotates on the 1st of every month. |
+| **Auto Detach** | `false` | Keeps debugger attached to actively buffer invisible exceptions and network calls. |
+
+**Environment Variables:**
+- `GHOST_BRIDGE_PORT` — Override base port.
+- `GHOST_BRIDGE_TOKEN` — Override connection token.
+
+---
+
+## 🏗️ Architecture
 
-3. AI 调用 dispatch_action({ref: "e2", action: "click"})
-   → 点击 Login 按钮
-
-4. AI 调用 capture_screenshot 验证操作结果
+```mermaid
+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]
 ```
 
-### 📊 性能分析
-
-| 工具 | 说明 |
-|------|------|
-| `perf_metrics` | 获取页面性能指标，包含三层数据：|
+- **MCP Server**: Spawned by Claude via standard I/O streams. Orchestrates WS connections.
+- **Chrome Extension (MV3)**: Taps into `chrome.debugger` API. Utilizes an Offscreen Document to prevent WS hibernation.
+- **Singleton Design**: If multiple agents spawn servers, the first becomes the master bridge while subsequent instances chain transparently as clients.
 
-**`perf_metrics` 返回的数据：**
+---
 
-- **引擎级指标** — JS 堆内存（使用量/总量/占比）、DOM 节点数、事件监听器数、Layout 重排次数与耗时、脚本执行时间
-- **Web Vitals** — Navigation Timing 各阶段（DNS / TTFB / DOM Interactive / Load）、FP、FCP、Long Tasks 统计
-- **资源加载摘要** — 按类型分组统计（count / size / avgDuration）、最慢资源识别
+## ⚠️ Known Limitations
 
-## 配置
-
-| 项目 | 默认值 | 说明 |
-|------|--------|------|
-| 端口 | `33333` | WebSocket 服务端口，自动递增寻找可用端口 |
-| Token | 当月自动生成 | 本机 WS 校验，基于当月 1 号时间戳 |
-| 自动 Detach | `false` | 保持附加，便于持续捕获异常和网络请求 |
-
-环境变量：
-
-- `GHOST_BRIDGE_PORT` — 自定义基础端口
-- `GHOST_BRIDGE_TOKEN` — 自定义 token
-
-## 架构
-
-```
-┌──────────────┐     stdio      ┌──────────────┐    WebSocket    ┌──────────────┐
-│  Claude CLI  │ ◄────────────► │  MCP Server  │ ◄──────────────►│Chrome Extension│
-│  / Desktop   │                │ (server.js)  │                 │(background.js)│
-└──────────────┘                └──────────────┘                 └──────┬───────┘
-                                                                       │ CDP
-                                                                 ┌─────▼──────┐
-                                                                 │  浏览器页面  │
-                                                                 └────────────┘
-```
+- **Service Workers Suspending**: MV3 background workers may suspend. We've built robust auto-reconnection logic, but prolonged inactivity might require re-toggling.
+- **DevTools Conflict**: If you manually open Chrome DevTools (F12) on the target tab, `chrome.debugger.attach` may be rejected.
+- **Beautify Overhead**: Beautifying massive single-line bundles is expensive; the server will auto-truncate overly large scripts.
+- **Cross-Origin OOPIF**: Elements and errors deeply embedded in strict Cross-Origin Iframes might evade the primary debugger hook without further multi-target attach logic.
 
-- **MCP Server** — 通过 stdio 被 Claude 拉起，与扩展通过 WebSocket 通信
-- **Chrome Extension (MV3)** — 使用 `chrome.debugger` API 附加页面，Offscreen Document 维持 WebSocket 长连接
-- **单例模式** — 多个 MCP 客户端自动协调，首个实例为主服务，后续实例作为客户端连接
+---
 
-## 已知限制
+## 🤝 Contributing
 
-- 扩展 Service Worker 可能被挂起，已内置重连策略；若长时间无流量需重新唤醒
-- 若目标页面已打开 DevTools，`chrome.debugger.attach` 可能失败，请关闭后重试
-- 大体积单行 bundle beautify 可能耗时，服务端对超长源码会截取片段
-- 跨月时 token 会自动更新，扩展和服务端需在同月内启动
-- DOM 交互：SPA 路由变化后 ref 标识会失效，需重新调用 `get_interactive_snapshot`
-- DOM 交互：跨域 iframe 内的元素暂不支持细粒度操作
-- DOM 交互：Shadow DOM 内的元素可以被扫描到，但部分封闭模式的 Shadow Root 可能无法穿透
+Contributions, issues, and feature requests are welcome! 
+Check out our [Contributing Guide](CONTRIBUTING.md) to get started building tools or improving the bridge.
 
-## License
+## 📄 License
 
-MIT
+This project is [MIT](LICENSE) licensed.