Content
# 🚀 WebBrain Ultimate Edition (3-In-1)
Welcome to **WebBrain Ultimate Edition (3-In-1)** - a complete and maximally optimized AI Browser Agent solution. This installation package combines 3 important components into a single distribution directory, inherited and developed from high-quality open-source codes of the community.
---
## 📂 Package Structure
```text
3in1/
├── extension/ # Integrated Chrome Extension with Tab Bar & 3 operating interface flows
├── server/ # WebSocket MCP Server (integrated upload_file via CDP, without node_modules)
└── scripts/ # Minimalist Node.js script for automatic local resource loading
```
---
## 🛠️ Quick Installation & Operation Guide
### Step 1: Load Chrome Extension
1. Access the extension management page: `chrome://extensions/` on Google Chrome.
2. Enable **Developer mode** at the top right corner.
3. Click the **Load unpacked** button at the top left corner.
4. Select the directory path: `3in1/extension`
5. Open the WebBrain Sidebar to start using it.
### Step 2: Install & Configure MCP Server for IDEs / AI Agents
The WebBrain server operates on a dual communication mechanism:
- **WebSocket (`ws://localhost:8545`)**: Direct connection and control of the Chrome Extension.
- **STDIO (Standard Input/Output)**: Connection with IDEs and AI Agents (Antigravity, Claude Code, Codex, Cursor, Windsurf, Claude Desktop,...).
#### 1. Install dependencies:
Open the Terminal in the `server` directory and install libraries:
```bash
cd 3in1/server
npm install
```
#### 2. Add MCP Server to IDEs / AI Agents:
* **Antigravity / VS Code / Cursor / Windsurf / Codex / Claude Desktop** (Using JSON configuration file `mcp.json` or `claude_desktop_config.json`):
```json
{
"mcpServers": {
"webbrain": {
"command": "node",
"args": ["C:/path/to/3in1/server/index.js"]
}
}
}
```
*(Replace `C:/path/to/3in1/server/index.js` with the absolute path to the `index.js` file in the `server` directory on your machine).*
* **Claude Code (CLI)**:
Run the command to register the MCP server directly in the Terminal:
```bash
claude mcp add webbrain -- node C:/path/to/3in1/server/index.js
```
> 💡 **Important Note:** When you add the `mcpServers` configuration to the IDE or run the `claude mcp add` command, the IDE / AI Agent will **automatically activate** the MCP Server (`node index.js`) implicitly each time it starts. Therefore, you **DO NOT NEED** to run the `npm start` command manually in the Terminal anymore to avoid port conflict `8545` (`EADDRINUSE`).
* **Manual startup (Only for Dev / Debug without IDE)**:
```bash
cd 3in1/server
npm start
```
*(Only open when testing directly from the terminal without declaring the `mcpServers` file in the IDE).*
#### 3. Check connection:
1. **Browser side:** Go back to the Extension Sidebar ➔ **MCP Server** tab ➔ Status displays 🟢 **CONNECTED** (successful connection to WebSocket port `ws://localhost:8545`).
2. **IDE / Agent side:** The IDE will automatically call `node index.js` via STDIO and recognize the 28 MCP tools of `webbrain` (e.g., `get_accessibility_tree`, `click_ax`, `upload_file`,...).
### Step 3: Operate Shopee Crawler & Download Resources
1. Select the **Shopee Crawler** tab on the Sidebar.
2. Paste the list of Shopee product links to crawl.
3. Enter the Gemini API Key (or OpenAI Endpoint) ➔ Click **Start Crawl**.
4. When completed, export the JSON result file (e.g., `shopee_scraped.json`). Open the terminal and run the command to download all original images/videos:
```bash
node ../scripts/download-media.js "C:/path/to/your/shopee_scraped.json"
```
*CDN images and product introduction videos will be saved automatically in the `3in1/downloads/` directory according to each product name folder.*
---
## 📋 Technical Tool Details by Workflow
The system operates in parallel on 3 independent workflows, providing a set of tools from raw context interaction to deep system intervention:
### 1. AI Browser Agent Workflow (Tab 1 - WebBrain Chat)
Operates as a direct conversational assistant with the current webpage content through recommended actions:
* **Chat with Page:** Analyze context, answer questions based on the displayed text of the active tab.
* **Page Summarization:** Quickly summarize the content of articles, long research documents.
* **Task Planning:** Outline plans and automate basic operations based on natural user prompts.
### 2. Model Context Protocol Workflow (Tab 2 - WebSocket MCP Server)
Publishes **28 system tools** to the WebSocket Server on port `8545` for external agents (like Claude, Gemini, IDE) to connect and control the browser remotely. The tool list includes:
* **Precise DOM Interaction Group (Accessibility Tree):**
* `get_accessibility_tree`: Read the accessibility tree structure of the current page, generating unique and stable `ref_id` identifiers for each element.
* `click_ax`: Click precisely on the DOM element using `ref_id` (avoiding coordinate offset or page scrolling errors).
* `type_ax`: Type text into the input field using `ref_id`.
* `set_field`: Fill in text quickly and optionally press the Enter key (combined click + type).
* `hover`: Move the virtual mouse cursor over the element using `ref_id`.
* `get_selection`: Extract the text being highlighted by the user.
* **Navigation & Network Status Group:**
* `navigate`: Redirect the tab to a specific URL link.
* `new_tab`: Create a new tab and automatically group it into the WebBrain partition.
* `go_back` / `go_forward`: Go back or move forward in the tab history.
* `wait_for_stable`: Wait for the network to calm down and the webpage to finish rendering.
* **Window & Interface Operation Group:**
* `resize_window`: Change the display window size of Chrome.
* `get_window_info`: Get the size information and current tab list.
* `screenshot`: Capture the screenshot of the visible area (Viewport) of the page.
* **File Management & Download Group:**
* `list_downloads`: Search the history of downloaded files.
* `download_files`: Download files from direct URL links through the Chrome download manager.
* `upload_file` *(Special Privilege CDP)*: Use the `chrome.debugger` API attached to CDP to send the `DOM.setFileInputFiles` command to upload local files to the webpage (bypassing the security sandbox).
* **Provisional DOM Operation Group (CSS Selector):**
* `click` / `type_text`: Perform click and type actions based on traditional CSS selectors or index when `ref_id` does not exist.
* `wait_for_element`: Wait until the element matching the CSS Selector appears on the page.
* `get_interactive_elements`: Quickly scan raw interactive elements with index on DOM.
* `extract_data`: Quickly extract structured data like tables or links.
* `read_page` / `read_page_source`: Read raw text displayed or get the entire HTML source code (`outerHTML`).
* **Advanced Execution Group:**
* `execute_js`: Launch and execute an asynchronous JavaScript code block in the context of the page (receiving a `resolve` callback parameter).
### 3. Shopee Crawler Workflow (Tab 3 - Stealth Crawler)
Operates a structured Shopee data crawling system, integrating biological simulation mechanisms to avoid being blocked:
* **Stealth Humanize:** Automatically simulate natural mouse scrolling behavior (Wave scroll) and random mouse movement on the page to bypass bot detection algorithms.
* **AI Data Parsing:** Capture screenshots and send raw text to LLMs (Gemini, DeepSeek) for analysis and return a standard JSON structure with 6 data fields: *Name, Price, Sold, Rating, Brand, Description*.
* **Media Link Extraction:** Run isolated JavaScript code to collect all high-quality CDN image links (`Images`) and product video links (`Video`).
---
## 🌟 Exclusive Improvements in Ultimate Edition
1. **Debounced Glow Border Effect:** When running MCP tasks, the purple gradient border around the tab continuously flashes and automatically maintains. The border only turns off after the system completes the entire task chain and is idle for 8 seconds.
2. **Smart Tab Opening and Grouping:** When clicking to crawl Shopee, a new crawling tab will be created next to the current tab. If the current tab is in a tab group (tabGroup), the crawling tab will be automatically added to the same group to keep the browser organized.
3. **Do Not Close Crawler Tab:** Keep the crawler tab open at the last product page after completion, and change the border light to blue to signal success.
4. **Visual Vietnamese Explanation:** Integrate a concept and usage explanation for the 28 MCP tools directly on the Sidebar interface.
---
## 💖 Acknowledgments & Credits
The **WebBrain Ultimate Edition (3-In-1)** project was developed, customized, and packaged based on the excellent open-source contributions of the community. We would like to express our deep gratitude to:
* **Original WebBrain Project**: Developed by [webbrain-one](https://github.com/webbrain-one/webbrain) - an outstanding Chrome Extension AI Agent platform.
* **WebBrain MCP Fork by author**: Stored and contributed by [nqtruong136/webbrain](https://github.com/nqtruong136/webbrain) - providing the foundation for the first WebSocket MCP Server connection.
*Open-source code is a creative bridge, and we sincerely thank the authors for their contributions!*
