openclaw-node-harness 2.0.0

package/skills/fast-browser-use/.clawhub/origin.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "registry": "https://clawhub.ai",
+  "slug": "fast-browser-use",
+  "installedVersion": "1.0.5",
+  "installedAt": 1770236284101
+}

package/skills/fast-browser-use/CODEBUDDY.md

@@ -0,0 +1,142 @@
+# CODEBUDDY.md This file provides guidance to CodeBuddy Code when working with code in this repository.
+
+## Project Overview
+
+`browser-use` is a Rust library for browser automation via Chrome DevTools Protocol (CDP). It provides:
+
+- A browser session manager wrapping `headless_chrome`
+- A tool system for common browser operations (navigate, click, input, extract, etc.)
+- DOM extraction with indexed interactive elements
+- An MCP (Model Context Protocol) server for AI-driven browser automation
+
+## Common Commands
+
+### Building
+
+```bash
+cargo build                    # Build library
+cargo build --bin mcp-server  # Build MCP server binary
+cargo build --release         # Production build
+```
+
+### Testing
+
+```bash
+cargo test                     # Run unit tests only
+cargo test -- --ignored        # Run integration tests (requires Chrome installed)
+cargo test dom_integration     # Run specific test file
+```
+
+### Running
+
+```bash
+cargo run --bin mcp-server              # Run MCP server (headless)
+cargo run --bin mcp-server -- --headed  # Run with visible browser
+```
+
+### Development
+
+```bash
+cargo check        # Fast compile check
+cargo clippy       # Linting
+cargo fmt          # Format code
+```
+
+## Architecture
+
+### Module Structure
+
+The codebase is organized into five main modules:
+
+**1. `browser/` - Browser Management**
+
+- `session.rs`: `BrowserSession` wraps `headless_chrome::Browser` and manages tabs
+- `config.rs`: `LaunchOptions` and `ConnectionOptions` for browser initialization
+- Key APIs: `launch()`, `connect()`, `navigate()`, `extract_dom()`
+
+**2. `dom/` - DOM Extraction & Indexing**
+
+- `tree.rs`: `DomTree` represents page structure with indexed interactive elements
+- `element.rs`: `ElementNode` is a serializable DOM node with visibility/interactivity metadata
+- `extract_dom.js`: JavaScript injected into pages to extract DOM as JSON
+- Flow: JS extraction → JSON → `ElementNode` tree → index interactive elements → `DomTree.selectors`
+
+**3. `tools/` - Browser Automation Tools**
+
+- Each tool is in its own file: `navigate.rs`, `click.rs`, `input.rs`, `extract.rs`, `screenshot.rs`, `evaluate.rs`, `wait.rs`
+- All tools implement the `Tool` trait with type-safe parameter structs (e.g., `ClickParams`, `NavigateParams`)
+- `ToolRegistry` manages tools and executes them with `ToolContext` (contains `BrowserSession` + optional cached `DomTree`)
+- Element selection: tools accept either CSS selectors OR numeric indices (from `DomTree`)
+- **⚠️ IMPORTANT: When adding a new tool, remember to register it in `src/mcp/mod.rs` using the `register_mcp_tools!` macro**
+
+**4. `mcp/` - Model Context Protocol Server**
+
+- `handler.rs`: `BrowserServer` wraps `BrowserSession` in `Arc<Mutex<>>` for thread-safe MCP access
+- `mod.rs`: Uses `register_mcp_tools!` macro to auto-generate MCP tool wrappers from internal tools
+- Runs as stdio-based MCP server via `rmcp` crate
+
+**5. `error.rs` - Error Handling**
+
+- `BrowserError` enum with variants for launch/connection/navigation/DOM/tool failures
+- Converts `anyhow::Error` from `headless_chrome` and `serde_json::Error`
+
+### Key Design Patterns
+
+**Tool System**: The `Tool` trait uses associated types for compile-time parameter validation:
+
+```rust
+trait Tool {
+    type Params: Serialize + Deserialize + JsonSchema;
+    fn execute_typed(&self, params: Self::Params, context: &mut ToolContext) -> Result<ToolResult>;
+}
+```
+
+**DOM Indexing**: Interactive elements get numeric indices for easier LLM targeting:
+
+- Extract DOM → Traverse tree → Detect interactive elements (buttons, links, inputs)
+- Assign indices only to visible + interactive elements
+- Tools can use `{"index": 5}` instead of complex CSS selectors
+
+**Dual Element Selection**: Tools accept both:
+
+- CSS selector: `{"selector": "#submit-btn"}`
+- Numeric index: `{"index": 5}` (requires DOM extraction first)
+
+**MCP Integration**: The `register_mcp_tools!` macro automatically wraps internal tools:
+
+- Takes tool type + MCP name + description
+- Generates async function that locks session, calls tool, converts result
+- All registered in `tool_router` for `rmcp` dispatcher
+
+### Testing Approach
+
+- Unit tests in each module for struct/enum behavior
+- Integration tests in `tests/` require Chrome (`#[ignore]` attribute)
+- Run ignored tests with: `cargo test -- --ignored`
+- Tests use `data:` URLs to avoid network dependencies
+
+## Important Implementation Notes
+
+- The MCP server runs in a single-threaded Tokio runtime (`#[tokio::main(flavor = "current_thread")]`)
+- `BrowserSession` holds a `headless_chrome::Browser` and manages one active tab at a time
+- DOM extraction executes JavaScript in the browser and parses the returned JSON
+- All tools work on the active tab; use `switch_tab()` to change context
+- Element indices are only valid for the specific DOM extraction they came from
+- Re-extracting the DOM rebuilds the selector list on `DomTree` and reassigns all indices
+- **When writing JavaScript to be executed in the browser, always use `JSON.stringify()` to ensure the result is returned properly** - this prevents issues with complex objects and ensures consistent serialization
+
+## Crate Dependencies
+
+- `headless_chrome`: CDP client for Chrome/Chromium automation
+- `rmcp`: Model Context Protocol (MCP) server framework
+- `serde`/`serde_json`: JSON serialization for params and DOM
+- `schemars`: JSON Schema generation for tool parameters
+- `thiserror`: Ergonomic error definitions
+- `tokio` (optional): Async runtime for MCP server
+- `clap` (optional): CLI arg parsing for MCP server binary
+
+## File Locations
+
+- MCP server binary: `src/bin/mcp_server.rs`
+- DOM extraction script: `src/dom/extract_dom.js` (embedded via `include_str!`)
+- Integration tests: `tests/dom_integration.rs`

package/skills/fast-browser-use/Cargo.toml

@@ -0,0 +1,77 @@
+[[bin]]
+name = "mcp-server"
+path = "src/bin/mcp_server.rs"
+required-features = ["mcp-server"]
+
+[[bin]]
+name = "fast-browser-use"
+path = "src/bin/cli.rs"
+required-features = ["cli"]
+
+[package]
+name = "browser-use"
+version = "0.1.0"
+edition = "2024"
+authors = ["rknoche"]
+description = "A lightweight Rust library for browser automation via Chrome DevTools Protocol (CDP), featuring a built-in Model Context Protocol (MCP) server for AI-driven browser automation"
+license = "MIT"
+repository = "https://github.com/rknoche6/fast-browser-use"
+readme = "README.md"
+keywords = ["browser", "automation", "cdp", "devtools", "mcp"]
+categories = ["web-programming", "development-tools"]
+
+[features]
+default = ["mcp-handler", "cli"]
+mcp-handler = ["rmcp/macros", "rmcp/server"]
+mcp-server = [
+    "mcp-handler",
+    "rmcp/transport-io",
+    "rmcp/transport-sse-server",
+    "rmcp/transport-streamable-http-server",
+    "tokio",
+    "clap",
+    "axum",
+    "tokio-util",
+    "env_logger",
+]
+cli = [
+    "clap",
+    "tokio",
+    "env_logger",
+    "rand",
+]
+
+[dependencies]
+headless_chrome = "1.0.18"
+rmcp = "0.8"
+thiserror = "2.0"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+anyhow = "1.0"
+indexmap = { version = "2.0", features = ["serde"] }
+schemars = "1.1"
+async-trait = "0.1"
+tokio = { version = "1", features = [
+    "rt",
+    "rt-multi-thread",
+    "macros",
+    "sync",
+    "net",
+    "signal",
+    "io-std",
+    "fs",
+], optional = true }
+clap = { version = "4.5", features = ["derive"], optional = true }
+axum = { version = "0.8", optional = true }
+tokio-util = { version = "0.7", optional = true }
+log = "0.4"
+env_logger = { version = "0.11", optional = true }
+html2md = "0.2"
+rand = { version = "0.8", optional = true }
+image = "0.24"
+imageproc = "0.23"
+rusttype = "0.9"
+base64 = "0.21"
+
+[dev-dependencies]
+urlencoding = "2.1"

package/skills/fast-browser-use/README.md

@@ -0,0 +1,62 @@
+Any contribution is very much welcome!
+Skill published in clawhub https://www.clawhub.ai/rknoche6/fast-browser-use
+
+# browser-use
+
+A lightweight Rust library for browser automation via Chrome DevTools Protocol (CDP).
+
+## ✨ Highlights
+
+- **Zero Node.js dependency** - Pure Rust implementation directly controlling browsers via CDP
+- **Lightweight & Fast** - No heavy runtime, minimal overhead
+- **MCP Integration** - Built-in Model Context Protocol server for AI-driven automation
+- **Simple API** - Easy-to-use tools for common browser operations
+
+## Installation
+
+```bash
+cargo add browser-use
+```
+
+## Styling
+
+```bash
+cargo +nightly fmt
+```
+
+## Quick Start
+
+```rust
+use browser_use::browser::BrowserSession;
+
+// Launch browser and navigate
+let session = BrowserSession::launch(Default::default())?;
+session.navigate("https://example.com", None)?;
+
+// Extract DOM with indexed interactive elements
+let dom = session.extract_dom()?;
+```
+
+## MCP Server
+
+Run the built-in MCP server for AI-driven automation:
+
+```bash
+# Headless mode
+cargo run --bin mcp-server
+
+# Visible browser
+cargo run --bin mcp-server -- --headed
+```
+
+## Features
+
+- Navigate, click, input, screenshot, extract content
+- DOM extraction with indexed interactive elements
+- CSS selector or numeric index-based element targeting
+- Thread-safe browser session management
+
+## Requirements
+
+- Rust 1.70+
+- Chrome or Chromium installed

package/skills/fast-browser-use/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: fast-browser-use
+displayName: Fastest Browser Use
+emoji: "⚡"
+summary: Rust-powered browser automation that rips through DOMs 10x faster than Puppeteer.
+homepage: https://github.com/rknoche6/fast-browser-use
+primaryEnv: bash
+os:
+  - darwin
+  - linux
+requires:
+  bins:
+    - chrome
+install:
+  - kind: brew
+    formula: rknoche6/tap/fast-browser-use
+  - kind: cargo
+    package: fast-browser-use
+description: "Rust-powered browser automation engine driving Chrome via CDP for fast DOM extraction, scraping, screenshots, and session management. Use for high-performance web scraping, infinite-scroll harvesting, vision-mapped interaction, or site structure analysis."
+triggers:
+  - "scrape this website fast"
+  - "use fast-browser-use to"
+  - "harvest data from this page"
+  - "take a screenshot of this site"
+  - "analyze the site structure"
+negative_triggers:
+  - "browse my local files"
+  - "use agent-browser"
+  - "fetch a single URL and summarize"
+config:
+  requiredEnv:
+    - CHROME_PATH
+  example: |
+    # Standard headless setup
+    export CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+    export BROWSER_HEADLESS="true"
+---
+
+# Fastest Browser Use
+
+A Rust-based browser automation engine that provides a lightweight binary driving Chrome directly via CDP. It is optimized for token-efficient DOM extraction, robust session management, and speed.
+
+![Terminal Demo](https://placehold.co/800x400/1e1e1e/ffffff?text=Terminal+Demo+Coming+Soon)
+
+## 🧪 Recipes for Agents
+
+### 1. Bypass "Bot Detection" via Human Emulation
+Simulate mouse jitter and random delays to scrape protected sites.
+
+```bash
+fast-browser-use navigate --url "https://protected-site.com" \
+  --human-emulation \
+  --wait-for-selector "#content"
+```
+
+### 2. The "Deep Freeze" Snapshot
+Capture the entire DOM state *and* computed styles for perfect reconstruction later.
+
+```bash
+fast-browser-use snapshot --include-styles --output state.json
+```
+
+### 3. Login & Cookie Heist
+Log in manually once, then steal the session for headless automation.
+
+**Step 1: Open non-headless for manual login**
+```bash
+fast-browser-use login --url "https://github.com/login" --save-session ./auth.json
+```
+
+**Step 2: Reuse session later**
+```bash
+fast-browser-use navigate --url "https://github.com/dashboard" --load-session ./auth.json
+```
+
+### 4. 🚜 Infinite Scroll Harvester
+**Extract fresh data from infinite-scroll pages** — perfect for harvesting the latest posts, news, or social feeds.
+
+```bash
+# Harvest headlines from Hacker News (scrolls 3x, waits 800ms between)
+fast-browser-use harvest \
+  --url "https://news.ycombinator.com" \
+  --selector ".titleline a" \
+  --scrolls 3 \
+  --delay 800 \
+  --output headlines.json
+```
+
+**Real output** (59 unique items in ~6 seconds):
+```json
+[
+  "Genode OS is a tool kit for building highly secure special-purpose OS",
+  "Mobile carriers can get your GPS location",
+  "Students using \"humanizer\" programs to beat accusations of cheating with AI",
+  "Finland to end \"uncontrolled human experiment\" with ban on youth social media",
+  ...
+]
+```
+
+Works on any infinite scroll page: Reddit, Twitter, LinkedIn feeds, search results, etc.
+
+### 5. 📸 Quick Screenshot
+Capture any page as PNG:
+
+```bash
+fast-browser-use screenshot \
+  --url "https://example.com" \
+  --output page.png \
+  --full-page  # Optional: capture entire scrollable page
+```
+
+### 6. 🗺️ Sitemap & Page Structure Analyzer
+Discover how a site is organized by parsing sitemaps and analyzing page structure.
+
+```bash
+# Basic sitemap discovery (checks robots.txt + common sitemap URLs)
+fast-browser-use sitemap --url "https://example.com"
+```
+
+```bash
+# Full analysis with page structure (headings, nav, sections)
+fast-browser-use sitemap \
+  --url "https://example.com" \
+  --analyze-structure \
+  --max-pages 10 \
+  --max-sitemaps 5 \
+  --output site-structure.json
+```
+
+**Options:**
+- `--analyze-structure`: Also extract page structure (headings, nav, sections, meta)
+- `--max-pages N`: Limit structure analysis to N pages (default: 5)
+- `--max-sitemaps N`: Limit sitemap parsing to N sitemaps (default: 10, useful for large sites)
+
+**Example output:**
+```json
+{
+  "base_url": "https://example.com",
+  "robots_txt": "User-agent: *\nSitemap: https://example.com/sitemap.xml",
+  "sitemaps": ["https://example.com/sitemap.xml"],
+  "pages": [
+    "https://example.com/about",
+    "https://example.com/products",
+    "https://example.com/contact"
+  ],
+  "page_structures": [
+    {
+      "url": "https://example.com",
+      "title": "Example - Home",
+      "headings": [
+        {"level": 1, "text": "Welcome to Example"},
+        {"level": 2, "text": "Our Services"}
+      ],
+      "nav_links": [
+        {"text": "About", "href": "/about"},
+        {"text": "Products", "href": "/products"}
+      ],
+      "sections": [
+        {"tag": "main", "id": "content", "role": "main"},
+        {"tag": "footer", "id": "footer", "role": null}
+      ],
+      "main_content": {"tag": "main", "id": "content", "word_count": 450},
+      "meta": {
+        "description": "Example company homepage",
+        "canonical": "https://example.com/"
+      }
+    }
+  ]
+}
+```
+
+Use this to understand site architecture before scraping, map navigation flows, or audit SEO structure.
+
+## ⚡ Performance Comparison
+
+| Feature | Fast Browser Use (Rust) | Puppeteer (Node) | Selenium (Java) |
+| :--- | :--- | :--- | :--- |
+| **Startup Time** | **< 50ms** | ~800ms | ~2500ms |
+| **Memory Footprint** | **15 MB** | 100 MB+ | 200 MB+ |
+| **DOM Extract** | **Zero-Copy** | JSON Serialize | Slow Bridge |
+
+## Capabilities & Tools
+
+### Vision & Extraction
+- **vision_map**: Returns a screenshot overlay with numbered bounding boxes for all interactive elements.
+- **snapshot**: Capture the raw HTML snapshot (YAML/Markdown optimized for AI).
+- **screenshot**: Capture a visual image of the page.
+- **extract**: Get structured data from the DOM.
+- **markdown**: Convert the current page content to Markdown.
+- **sitemap**: Analyze site structure via robots.txt, sitemaps, and page semantic analysis.
+
+### Navigation & Lifecycle
+- **navigate**: Visit a specific URL.
+- **go_back** / **go_forward**: Traverse browser history.
+- **wait**: Pause execution or wait for specific conditions.
+- **new_tab**: Open a new browser tab.
+- **switch_tab**: Switch focus to a specific tab.
+- **close_tab**: Close the current or specified tab.
+- **tab_list**: List all open tabs.
+- **close**: Terminate the browser session.
+
+### Interaction
+- **click**: Click elements via CSS selectors or DOM indices.
+- **input**: Type text into fields.
+- **press_key**: Send specific keyboard events.
+- **hover**: Hover over elements.
+- **scroll**: Scroll the viewport.
+- **select**: Choose options in dropdowns.
+
+### State & Debugging
+- **cookies**: Manage session cookies (get/set).
+- **local_storage**: Manage local storage data.
+- **debug**: Access console logs and debug information.
+
+## Usage
+
+This skill is specialized for complex web interactions that require maintaining state (like being logged in), handling dynamic JavaScript content, or managing multiple pages simultaneously. It offers higher performance and control compared to standard fetch-based tools.

package/skills/fast-browser-use/package-lock.json

@@ -0,0 +1,28 @@
+{
+  "name": "fast-browser-use",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "devDependencies": {
+        "prettier": "^3.8.1"
+      }
+    },
+    "node_modules/prettier": {
+      "version": "3.8.1",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.1.tgz",
+      "integrity": "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "prettier": "bin/prettier.cjs"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/prettier/prettier?sponsor=1"
+      }
+    }
+  }
+}

package/skills/fast-browser-use/package.json

@@ -0,0 +1,8 @@
+{
+  "scripts": {
+    "format": "prettier --write ."
+  },
+  "devDependencies": {
+    "prettier": "^3.8.1"
+  }
+}

package/skills/fast-browser-use/rustfmt.toml

@@ -0,0 +1,10 @@
+# Rustfmt configuration for browser-use project
+
+# Import formatting
+imports_indent = "Visual"
+reorder_imports = true
+imports_granularity = "Crate"
+
+# Line formatting
+use_small_heuristics = "Max"
+max_width = 120