@iflow-mcp/shaun0927-openchrome 1.7.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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

@@ -0,0 +1,387 @@
+<p align="center">
+  <img src="assets/mascot.png?v=4" alt="OpenChrome Raptor" width="180">
+</p>
+
+<h1 align="center">OpenChrome</h1>
+
+<p align="center">
+  <b>Smart. Fast. Parallel.</b><br>
+  Browser automation MCP server that uses your real Chrome.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/openchrome-mcp"><img src="https://img.shields.io/npm/v/openchrome-mcp" alt="npm"></a>
+  <a href="https://github.com/shaun0927/openchrome/releases/latest"><img src="https://img.shields.io/github/v/release/shaun0927/openchrome" alt="Latest Release"></a>
+  <a href="https://github.com/shaun0927/openchrome/releases/latest"><img src="https://img.shields.io/github/release-date/shaun0927/openchrome" alt="Release Date"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT"></a>
+</p>
+
+<p align="center">
+  <img src="assets/demo.svg" alt="Traditional vs OpenChrome" width="100%">
+</p>
+
+<p align="center">
+  <img src="assets/chart-tokens.svg" alt="Token Efficiency: OpenChrome vs Playwright" width="100%">
+</p>
+
+---
+
+## What is OpenChrome?
+
+Imagine **20+ parallel Playwright sessions** — but already logged in to everything, invisible to bot detection, and sharing one Chrome process at 300MB. That's OpenChrome.
+
+Search across 20 sites simultaneously. Crawl authenticated dashboards in seconds. Debug production UIs with real user sessions. Connect to [OpenClaw](https://github.com/openclaw/openclaw) and give your AI agent browser superpowers across Telegram, Discord, or any chat platform.
+
+```
+You: oc compare "AirPods Pro" prices across Amazon, eBay, Walmart,
+     Best Buy, Target, Costco, B&H, Newegg — find the lowest
+
+AI:  [8 parallel workers, all sites simultaneously]
+     Best Buy:  $179 ← lowest (sale)
+     Amazon:    $189
+     Costco:    $194 (members)
+     ...
+     Time: 2.8s | All prices from live pages, already logged in.
+```
+
+| | Traditional | OpenChrome |
+|---|:---:|:---:|
+| **5-site task** | ~250s (login each) | **~3s** (parallel) |
+| **Memory** | ~2.5 GB (5 browsers) | **~300 MB** (1 Chrome) |
+| **Auth** | Every time | **Never** |
+| **Bot detection** | Flagged | **Invisible** |
+
+---
+
+## Guided, Not Guessing
+
+The bottleneck in browser automation isn't the browser — it's the **LLM thinking between each step**. Every tool call costs 5–15 seconds of inference time. When an AI agent guesses wrong, it doesn't just fail — it spends another 10 seconds thinking about why, then another 10 seconds trying something else.
+
+```
+Playwright agent checking prices on 5 sites:
+
+  Site 1:  launch browser           3s
+           navigate                  2s
+           ⚡ bot detection          LLM thinks... 12s → retry with UA
+           ⚡ CAPTCHA                LLM thinks... 10s → stuck, skip
+           navigate to login         2s
+           ⚡ no session             LLM thinks... 12s → fill credentials
+           2FA prompt               LLM thinks... 10s → stuck
+           ...
+           finally reaches product   after ~20 LLM calls, ~4 minutes
+
+  × 5 sites, sequential  =  ~100 LLM calls,  ~20 minutes,  ~$2.00
+
+  Actual work: 5 calls.  Wasted on wandering: 95 calls.
+```
+
+OpenChrome eliminates this entirely — your Chrome is already logged in, and the hint engine corrects mistakes before they cascade:
+
+```
+OpenChrome agent checking prices on 5 sites:
+
+  All 5 sites in parallel:
+    navigate (already authenticated)     1s
+    read prices                          2s
+    ⚡ stale ref on one site
+      └─ Hint: "Use read_page for fresh refs"    ← no guessing
+    read_page → done                     1s
+
+  = ~20 LLM calls,  ~15 seconds,  ~$0.40
+```
+
+The hint engine watches every tool call across 6 layers — error recovery, composite suggestions, repetition detection, sequence detection, learned patterns, and success guidance. When it sees the same error→recovery pattern 3+ times, it promotes it to a permanent rule across sessions.
+
+| | Playwright | OpenChrome | Savings |
+|---|---|---|---|
+| **LLM calls** | ~100 | ~20 | **80% fewer** |
+| **Wall time** | ~20 min | ~15 sec | **80x faster** |
+| **Token cost** | ~$2.00 | ~$0.40 | **5x cheaper** |
+| **Wasted calls** | ~95% | ~0% | |
+
+---
+
+## Quick Start
+
+```bash
+npx openchrome-mcp setup
+```
+
+One command. Configures MCP server + auto-approves tool permissions.
+Restart Claude Code, then say `oc`.
+
+<details>
+<summary>Manual config</summary>
+
+**Claude Code:**
+```bash
+claude mcp add openchrome -- npx -y openchrome-mcp@latest serve --auto-launch
+```
+
+**VS Code / Copilot** (`.vscode/mcp.json`):
+```json
+{
+  "servers": {
+    "openchrome": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "openchrome-mcp@latest", "serve", "--auto-launch"]
+    }
+  }
+}
+```
+
+**Cursor / Windsurf / Other MCP clients:**
+```json
+{
+  "mcpServers": {
+    "openchrome": {
+      "command": "npx",
+      "args": ["-y", "openchrome-mcp@latest", "serve", "--auto-launch"]
+    }
+  }
+}
+```
+
+</details>
+
+---
+
+## Examples
+
+**Parallel monitoring:**
+```
+oc screenshot AWS billing, GCP console, Stripe, and Datadog — all at once
+→ 4 workers, 3.1s, already authenticated everywhere
+```
+
+**Multi-account:**
+```
+oc check orders on personal and business Amazon accounts simultaneously
+→ 2 workers, isolated sessions, same site different accounts
+```
+
+**Competitive intelligence:**
+```
+oc compare prices for "AirPods Pro" across Amazon, eBay, Walmart, Best Buy
+→ 4 workers, 4 sites, 2.4s, works past bot detection
+```
+
+---
+
+## 45 Tools
+
+| Category | Tools |
+|----------|-------|
+| **Navigate & Interact** | `navigate`, `interact`, `fill_form`, `find`, `computer` |
+| **Read & Extract** | `read_page`, `page_content`, `javascript_tool`, `selector_query`, `xpath_query` |
+| **Environment** | `emulate_device`, `geolocation`, `user_agent`, `network` |
+| **Storage & Debug** | `cookies`, `storage`, `console_capture`, `performance_metrics`, `request_intercept` |
+| **Parallel Workflows** | `workflow_init`, `workflow_collect`, `worker_create`, `batch_execute` |
+| **Memory** | `memory_record`, `memory_query`, `memory_validate` |
+
+<details>
+<summary>Full tool list (45)</summary>
+
+`navigate` `interact` `computer` `read_page` `find` `form_input` `fill_form` `javascript_tool` `page_reload` `page_content` `page_pdf` `wait_for` `user_agent` `geolocation` `emulate_device` `network` `selector_query` `xpath_query` `cookies` `storage` `console_capture` `performance_metrics` `request_intercept` `drag_drop` `file_upload` `http_auth` `worker_create` `worker_list` `worker_update` `worker_complete` `worker_delete` `tabs_create` `tabs_context` `tabs_close` `workflow_init` `workflow_status` `workflow_collect` `workflow_collect_partial` `workflow_cleanup` `execute_plan` `batch_execute` `lightweight_scroll` `memory_record` `memory_query` `memory_validate` `oc_stop`
+
+</details>
+
+---
+
+## CLI
+
+```bash
+oc setup                    # Auto-configure
+oc serve --auto-launch      # Start server
+oc serve --headless-shell   # Headless mode
+oc doctor                   # Diagnose issues
+```
+
+---
+
+## Cross-Platform
+
+| Platform | Status |
+|----------|--------|
+| **macOS** | Full support |
+| **Windows** | Full support (taskkill process cleanup) |
+| **Linux** | Full support (Snap paths, `CHROME_PATH` env, `--no-sandbox` for CI) |
+
+---
+
+## DOM Mode (Token Efficient)
+
+`read_page` supports three output modes:
+
+| Mode | Output | Tokens | Use Case |
+|------|--------|--------|----------|
+| `ax` (default) | Accessibility tree with `ref_N` IDs | Baseline | Screen readers, semantic analysis |
+| `dom` | Compact DOM with `backendNodeId` | **~5-10x fewer** | Click, fill, extract — most tasks |
+| `css` | CSS diagnostic info (variables, computed styles, framework detection) | Minimal | Debugging styles, Tailwind detection |
+
+**DOM mode example:**
+```
+read_page tabId="tab1" mode="dom"
+
+[page_stats] url: https://example.com | title: Example | scroll: 0,0 | viewport: 1920x1080
+
+[142]<input type="search" placeholder="Search..." aria-label="Search"/> ★
+[156]<button type="submit"/>Search ★
+[289]<a href="/home"/>Home ★
+[352]<h1/>Welcome to Example
+```
+
+DOM mode outputs `[backendNodeId]` as stable identifiers — they persist for the lifetime of the DOM node, unlike `ref_N` IDs which are cleared on each AX-mode `read_page` call.
+
+---
+
+## Stable Selectors
+
+Action tools that accept a `ref` parameter (`form_input`, `computer`, etc.) support three identifier formats:
+
+| Format | Example | Source |
+|--------|---------|--------|
+| `ref_N` | `ref_5` | From `read_page` AX mode (ephemeral) |
+| Raw integer | `142` | From `read_page` DOM mode (stable) |
+| `node_N` | `node_142` | Explicit prefix form (stable) |
+
+**Backward compatible** — existing `ref_N` workflows work unchanged. DOM mode's `backendNodeId` eliminates "ref not found" errors caused by stale references.
+
+---
+
+## Session Persistence
+
+Headless mode (`--headless-shell`) doesn't persist cookies across restarts. Enable storage state persistence to maintain authenticated sessions:
+
+```bash
+oc serve --persist-storage                         # Enable persistence
+oc serve --persist-storage --storage-dir ./state    # Custom directory
+```
+
+Cookies and localStorage are saved atomically every 30 seconds and restored on session creation.
+
+---
+
+## Anti-Bot & Turnstile Support
+
+OpenChrome includes built-in defenses against Cloudflare Turnstile and similar anti-bot systems, with additional stealth navigation planned for a future release. See [Turnstile Guide](docs/turnstile-guide.md) for details.
+
+---
+
+## Benchmarks
+
+Measure token efficiency and parallel performance:
+
+```bash
+npm run benchmark                                    # Stub mode: AX vs DOM token efficiency (interactive)
+npm run benchmark:ci                                 # Stub mode: AX vs DOM with JSON + regression detection
+npm run benchmark -- --mode real                     # Real mode: actual MCP server (requires Chrome)
+npx ts-node tests/benchmark/run-parallel.ts          # Stub mode: all parallel benchmark categories
+npx ts-node tests/benchmark/run-parallel.ts --mode real --category batch-js --runs 1  # Real mode
+npx ts-node tests/benchmark/run-parallel.ts --mode real --category realworld --runs 1  # Real-world benchmarks
+```
+
+By default, benchmarks run in **stub mode** — measuring protocol correctness and tool-call counts with mock responses. Use `--mode real` to spawn an actual MCP server subprocess and measure real performance (requires Chrome to be available).
+
+**Parallel benchmark categories:**
+
+| Category | What It Measures |
+|----------|-----------------|
+| Multi-step interaction | Form fill + click sequences across N parallel pages |
+| Batch JS execution | N × `javascript_tool` vs 1 × `batch_execute` |
+| Compiled plan execution | Sequential agent tool calls vs single `execute_plan` |
+| Streaming collection | Blocking vs `workflow_collect_partial` |
+| Init overhead | Sequential `tabs_create` vs batch `workflow_init` |
+| Fault tolerance | Circuit breaker recovery speed |
+| Scalability curve | Speedup efficiency at 1–50x concurrency |
+| **Real-world** | Multi-site crawl, heavy JS, pipeline, scalability with public websites (`httpbin.org`, `jsonplaceholder`, `example.com`) — NOT included in `all`, requires network |
+
+---
+
+## Server / Headless Deployment
+
+OpenChrome works on servers and in CI/CD pipelines without Chrome login. All 45 tools function with unauthenticated Chrome — navigation, scraping, screenshots, form filling, and parallel workflows all work in clean sessions.
+
+### Quick start
+
+```bash
+# Single flag for optimal server defaults
+openchrome serve --server-mode
+```
+
+`--server-mode` automatically sets:
+- Auto-launches Chrome in headless mode
+- Skips cookie bridge scanning (~5s faster per page creation)
+- Optimal defaults for server environments
+
+### What works without login
+
+| Category | Tools |
+|----------|-------|
+| **Navigation & scraping** | `navigate`, `read_page`, `page_content`, `javascript_tool` |
+| **Interaction** | `interact`, `fill_form`, `drag_drop`, `file_upload` |
+| **Parallel workflows** | `workflow_init` with multiple workers, `batch_execute` |
+| **Screenshots & PDF** | `computer(screenshot)`, `page_pdf` |
+| **Network & performance** | `request_intercept`, `performance_metrics`, `console_capture` |
+
+### Important: MCP client required
+
+OpenChrome is an MCP server — it responds to tool calls, not standalone scripts. Server-side usage requires an MCP client (e.g., Claude API, Claude Code, or a custom MCP client) to drive it:
+
+```
+MCP Client (LLM) → stdio → OpenChrome (--server-mode) → Chrome
+```
+
+For standalone scraping scripts without an LLM, use Playwright or Puppeteer directly.
+
+### Docker
+
+A production-ready `Dockerfile` is included in the repository:
+
+```bash
+docker build -t openchrome .
+docker run openchrome
+```
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `CHROME_PATH` | Path to Chrome/Chromium binary (used by launcher) |
+| `CHROME_BINARY` | Path to Chrome binary (used by `--chrome-binary` CLI flag) |
+| `CHROME_USER_DATA_DIR` | Custom profile directory |
+| `CI` | Detected automatically; adds `--no-sandbox` |
+| `DOCKER` | Detected automatically; adds `--no-sandbox` |
+
+### Individual flags
+
+For fine-grained control, use individual flags instead of `--server-mode`:
+
+```bash
+openchrome serve \
+  --auto-launch \
+  --headless-shell \
+  --port 9222
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--auto-launch` | `false` | Auto-launch Chrome if not running |
+| `--headless-shell` | `false` | Use chrome-headless-shell binary |
+| `--visible` | `false` | Show Chrome window (disables headless) |
+| `--server-mode` | `false` | Compound flag for server deployment |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/shaun0927/openchrome.git
+cd openchrome
+npm install && npm run build && npm test
+```
+
+## License
+
+MIT

package/assets/chart-tokens.svg

@@ -0,0 +1,42 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 480" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif">
+  <defs>
+    <linearGradient id="bg2" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#f8fafc"/>
+      <stop offset="100%" stop-color="#f1f5f9"/>
+    </linearGradient>
+  </defs>
+  <rect width="880" height="480" fill="url(#bg2)" rx="16"/>
+
+  <!-- Title -->
+  <text x="440" y="38" text-anchor="middle" font-size="22" font-weight="700" fill="#0f172a">Simple Task Token Efficiency</text>
+  <text x="440" y="62" text-anchor="middle" font-size="13" fill="#94a3b8">Tokens the LLM must process per Twitter profile (lower is better)</text>
+
+  <!-- Row 1: Playwright + LLM — 178,102 tok/profile -->
+  <text x="48" y="108" font-size="13" font-weight="600" fill="#475569">Playwright + LLM</text>
+  <text x="48" y="124" font-size="11" fill="#94a3b8">(raw HTML to LLM)</text>
+  <rect x="200" y="96" width="580" height="36" fill="#6366f1" opacity="0.85" rx="6"/>
+  <text x="770" y="120" text-anchor="end" font-size="14" font-weight="700" fill="#fff">178,102 tok/profile</text>
+  <text x="200" y="152" font-size="11" fill="#94a3b8">Total for 20 profiles: 3,562,038 tokens</text>
+
+  <!-- Row 2: OpenChrome — 11,641 tok/profile -->
+  <text x="48" y="198" font-size="13" font-weight="600" fill="#ea580c">OpenChrome</text>
+  <text x="48" y="214" font-size="11" fill="#94a3b8">(compact DOM)</text>
+  <rect x="200" y="186" width="38" height="36" fill="#f97316" opacity="0.9" rx="6"/>
+  <text x="248" y="210" font-size="14" font-weight="700" fill="#1e293b">11,641 tok/profile</text>
+  <text x="200" y="242" font-size="11" fill="#94a3b8">Total for 20 profiles: 232,813 tokens</text>
+
+  <!-- Row 3: Playwright standalone — 290 tok/profile -->
+  <text x="48" y="288" font-size="13" font-weight="600" fill="#475569">Playwright standalone</text>
+  <text x="48" y="304" font-size="11" fill="#94a3b8">(no per-page LLM)</text>
+  <rect x="200" y="276" width="3" height="36" fill="#10b981" opacity="0.9" rx="1"/>
+  <text x="214" y="300" font-size="14" font-weight="700" fill="#1e293b">290 tok/profile</text>
+  <text x="200" y="332" font-size="11" fill="#94a3b8">Total for 20 profiles: 5,800 tokens</text>
+
+  <!-- Savings callout box -->
+  <rect x="160" y="368" width="560" height="50" fill="#fff7ed" stroke="#f97316" stroke-width="1.5" rx="10"/>
+  <text x="440" y="390" text-anchor="middle" font-size="15" font-weight="700" fill="#ea580c">OpenChrome saves 93.5% tokens vs Playwright + LLM</text>
+  <text x="440" y="409" text-anchor="middle" font-size="12" fill="#b45309">15.3x compression — compact DOM strips CSS, scripts, and hidden elements</text>
+
+  <!-- Footer -->
+  <text x="440" y="455" text-anchor="middle" font-size="11" fill="#94a3b8">Token estimate: 1 token ≈ 4 characters | Compression ratio calibrated from actual read_page measurements</text>
+</svg>