weboperator-mcp 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem KK
+
+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,51 @@
+# weboperator-mcp
+
+MCP server that hands your **live Chrome tab** to any agent client — Claude Desktop, Cursor, Hermes, OpenClaw, OpenHands. Speaks MCP over stdio.
+
+It drives the browser you are already signed into, so your sessions, cookies, and extensions come along. Nothing is launched headless and nothing leaves the machine.
+
+## Tools
+
+`browser_snapshot` · `browser_navigate` · `browser_click` · `browser_type` · `browser_press` · `browser_scroll` · `browser_screenshot` · `browser_extract` · `browser_solve_captcha` · `weboperator_execute_goal`
+
+`browser_snapshot` returns an accessibility tree with numbered interactive elements; the action tools take those numbers, so an agent never guesses at CSS selectors.
+
+## Install
+
+The server talks to Chrome through the [WebOperator extension](https://github.com/KazKozDev/WebOperator) and a Native Messaging host, so install the extension first, then register the host:
+
+```bash
+npx -p weboperator-mcp weboperator-bridge-install
+```
+
+Then point your client at the server:
+
+```json
+{
+  "mcpServers": {
+    "weboperator": {
+      "command": "npx",
+      "args": ["-y", "weboperator-mcp"]
+    }
+  }
+}
+```
+
+Reload the extension in `chrome://extensions` after registering the host.
+
+## Configuration
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `WEBOPERATOR_BRIDGE_PORT` | `8765` | Port of the local bridge HTTP API |
+| `WEBOPERATOR_BRIDGE_HOST` | `127.0.0.1` | Bridge bind address |
+| `WEBOPERATOR_AGENT_SOCKET` | `/tmp/weboperator-bridge.sock` | Unix socket the bridge listens on |
+| `WEBOPERATOR_API_TOKEN` | _(unset)_ | Shared token, required when unauthenticated bridge access is disabled |
+
+macOS and Linux. Chrome, Chromium, Brave, Edge, and Arc are all registered by the installer.
+
+## Security
+
+Page content is treated as data, never as instructions — the extension's prompt-injection fixtures live in [`evals/fixtures/`](https://github.com/KazKozDev/WebOperator/tree/main/evals/fixtures). `browser_solve_captcha` pauses for you rather than defeating a challenge, and login flows stop for a human instead of typing credentials.
+
+MIT © Artem KK · [full documentation](https://github.com/KazKozDev/WebOperator)

package/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: weboperator
+description: "Control and automate the live browser (Brave, Chrome) via the WebOperator MCP server. Navigate websites, search, click, type, scroll, take screenshots, extract data, or run autonomous goals directly in the user's active browser."
+version: 1.4.0
+author: WebOperator
+license: MIT
+platforms: [macos, linux, windows]
+metadata:
+  hermes:
+    tags: [Browser-Automation, WebOperator, MCP, Chrome, Brave, Web-Navigation, Live-Browser]
+---
+
+# WebOperator Browser Automation Skill
+
+WebOperator connects Hermes directly to the user's live browser (Brave Browser, Google Chrome) via MCP.
+
+> [!IMPORTANT]
+> When the user asks to open a site, search in the browser, scroll, click, or mentions "вебоператор" / "WebOperator", **ALWAYS** use the `mcp__weboperator__*` tools.
+> **DO NOT** use Firecrawl or built-in `web_search`/`web_extract` when the user refers to WebOperator or wants browser automation.
+
+---
+
+## Available MCP Tools
+
+All tools are prefixed with `mcp__weboperator__`:
+
+### 1. `mcp__weboperator__browser_navigate`
+Navigate the active tab to a specific URL.
+```json
+{
+  "url": "https://www.google.com"
+}
+```
+
+### 2. `mcp__weboperator__browser_snapshot`
+Capture the interactive accessibility tree with numbered element IDs (`@1`, `@2`, etc.) from the active tab.
+```json
+{}
+```
+
+### 3. `mcp__weboperator__browser_click`
+Click an interactive element by its index from `browser_snapshot` or CSS selector.
+```json
+{
+  "index": 2
+}
+```
+
+### 4. `mcp__weboperator__browser_type`
+Type text into an input field.
+```json
+{
+  "index": 1,
+  "text": "auriculares baratos",
+  "clear": true
+}
+```
+
+### 5. `mcp__weboperator__browser_press`
+Press a keyboard key (e.g. Enter, Tab, Escape).
+```json
+{
+  "key": "Enter"
+}
+```
+
+### 6. `mcp__weboperator__browser_scroll`
+Scroll the active webpage up or down.
+```json
+{
+  "direction": "down",
+  "amount": 500
+}
+```
+
+### 7. `mcp__weboperator__browser_screenshot`
+Capture a visual PNG screenshot of the active browser viewport.
+```json
+{}
+```
+
+### 8. `mcp__weboperator__browser_extract`
+Extract structured text content or answers from the active page.
+```json
+{
+  "instruction": "Extract list of top 5 products with prices"
+}
+```
+
+### 9. `mcp__weboperator__browser_solve_captcha`
+Attempt to detect and automatically pass or click Cloudflare Turnstile, reCAPTCHA, or hCaptcha verification challenges on the active page.
+```json
+{
+  "type": "auto"
+}
+```
+
+### 10. `mcp__weboperator__weboperator_execute_goal`
+Run a high-level autonomous goal in the browser end-to-end using WebOperator's planner.
+```json
+{
+  "goal": "Find headphones under 30 euros on amazon.es and summarize top 3 options",
+  "timeoutMs": 120000
+}
+```
+
+---
+
+## Typical Workflow
+
+1. **Open a site**: Call `mcp__weboperator__browser_navigate` with `url`.
+2. **Inspect page**: Call `mcp__weboperator__browser_snapshot` to see element numbers and text.
+3. **Interact**: Call `mcp__weboperator__browser_type` or `mcp__weboperator__browser_click` using the element indices.
+4. **Scroll / Read**: Call `mcp__weboperator__browser_scroll` or `mcp__weboperator__browser_extract`.
+5. **Or run autonomous goal**: Call `mcp__weboperator__weboperator_execute_goal` with the full prompt.

package/agent-client.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// WebOperator framed JSON client for agents.
+const net = require('net');
+const { randomUUID } = require('crypto');
+
+const socketPath = process.env.WEBOPERATOR_AGENT_SOCKET || '/tmp/weboperator-bridge.sock';
+const token = process.env.WEBOPERATOR_API_TOKEN || '';
+const input = process.argv[2] ? JSON.parse(process.argv[2]) : { type: 'bridge.health' };
+const message = {
+  id: input.id || randomUUID(),
+  type: input.type || 'bridge.health',
+  payload: input.payload || {},
+  timeoutMs: input.timeoutMs,
+  ...(token ? { token } : {}),
+};
+
+let buffer = Buffer.alloc(0);
+let nextFrameLength = null;
+const socket = net.createConnection(socketPath, () => sendFrame(socket, message));
+
+socket.on('data', (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+  readFrames();
+});
+socket.on('error', (err) => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+
+function readFrames() {
+  while (true) {
+    if (nextFrameLength === null) {
+      if (buffer.length < 4) return;
+      nextFrameLength = buffer.readUInt32LE(0);
+      buffer = buffer.slice(4);
+    }
+    if (buffer.length < nextFrameLength) return;
+    const payload = buffer.slice(0, nextFrameLength).toString('utf8');
+    buffer = buffer.slice(nextFrameLength);
+    nextFrameLength = null;
+    const msg = JSON.parse(payload);
+    if (msg.kind === 'event') {
+      console.error(JSON.stringify(msg));
+      continue;
+    }
+    console.log(JSON.stringify(msg, null, 2));
+    socket.end();
+  }
+}
+
+function sendFrame(sock, obj) {
+  const body = Buffer.from(JSON.stringify(obj), 'utf8');
+  const header = Buffer.alloc(4);
+  header.writeUInt32LE(body.length, 0);
+  sock.write(Buffer.concat([header, body]));
+}