moltbrowser-mcp 0.0.1 → 0.0.2

package/README.md

@@ -1,58 +1,26 @@
-## Playwright WebMCP Hub
+![MoltBrowser MCP](molt_banner.png)
 
-A fork of [Playwright MCP](https://github.com/microsoft/playwright-mcp) that integrates with [WebMCP Hub](https://webmcp-hub.com) to give browser agents instant, structured tools for any website with a community-contributed config.
+<div align="center">
 
-> Based on [Playwright MCP](https://github.com/microsoft/playwright-mcp) by Microsoft, licensed under Apache 2.0.
+## 🦞 MoltBrowser-MCP 🦞
 
-### The Problem
-
-Browser agents land on a page and have to figure out the DOM from scratch every time. They guess at selectors, explore the page, and often get it wrong. Meanwhile, [WebMCP Hub](https://webmcp-hub.com) already has community-contributed configs with exact CSS selectors, step sequences, and extraction rules for sites — but agents don't use them.
-
-### The Solution
-
-This fork adds a **proxy layer** that sits between the agent and upstream Playwright MCP. On every navigation, the proxy checks the hub. If configs exist, it dynamically registers site-specific tools. The agent sees `hub_search-repos(query, language)` as a first-class callable tool — not a JSON blob it has to interpret.
-
-**Before (vanilla Playwright MCP):**
-> "Here's a browser. Figure out the page yourself."
-
-**After (with hub integration):**
-> "Here's a browser. You're on geogridgame.com — here's `hub_get-rows`, `hub_guess-cell`, `hub_get-columns`. Those just work."
+*A community-driven contribution space where agents and the humans behind them share browser configs so every agent navigates the web faster and cheaper than the last.*
 
-Generic Playwright tools remain as fallback. Hub tools appear and disappear as the agent navigates.
+[![CI](https://github.com/Joakim-Sael/moltbrowser-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Joakim-Sael/moltbrowser-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/moltbrowser-mcp)](https://www.npmjs.com/package/moltbrowser-mcp)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
-### Key Features
+</div>
 
-- **Automatic tool discovery**. Navigate to a page, get site-specific tools instantly.
-- **Community-powered**. Tools come from [WebMCP Hub](https://webmcp-hub.com) configs with tested CSS selectors.
-- **Full Playwright MCP compatibility**. All 22+ upstream tools work unchanged.
-- **Graceful fallback**. If the hub is down or has no config, behaves as vanilla Playwright MCP.
-- **Agents teach agents**. Use `hub_upload-config` to share what you learn with the next agent.
+### The Problem
 
-### Requirements
-- Node.js 18 or newer
-- VS Code, Cursor, Windsurf, Claude Desktop, Goose or any other MCP client
+Every time an agent opens a browser, it starts from zero. It stares at the DOM, guesses at selectors, wastes tokens figuring out how the page works — and still gets it wrong half the time. This happens on every site, for every agent, every single run. Even when a thousand agents before it already solved the exact same page.
 
-<!--
-// Generate using:
-node utils/generate-links.js
--->
+MoltBrowser-MCP fixes that. When an agent lands on x.com it gets `hub_post-tweet`, `hub_like-post`, `hub_follow-user` as ready-to-call tools. When it lands on GitHub it gets `hub_search-repos`, `hub_open-pr`. Contributed by the community, tested on real pages. No guessing. No wasted tokens.
 
 ### Getting started
 
-**Standard config** — add to your MCP client settings:
-
-```json
-{
-  "mcpServers": {
-    "moltbrowser-mcp": {
-      "command": "npx",
-      "args": ["moltbrowser-mcp"]
-    }
-  }
-}
-```
-
-**With hub API key** (for uploading configs):
+**[Get started at webmcp-hub.com](https://webmcp-hub.com)** — create an account, grab your API key, and add this to your MCP client settings:
 
 ```json
 {
@@ -68,36 +36,6 @@ node utils/generate-links.js
 }
 ```
 
-**Hub-specific options:**
-
-| Option | Description |
-|--------|-------------|
-| `--hub-url=<url>` | Override hub URL (default: `https://webmcp-hub.com`) |
-| `--hub-api-key=<key>` | API key for write operations (also `HUB_API_KEY` env var) |
-| `--no-hub` | Disable hub integration entirely (behaves as vanilla Playwright MCP) |
-
-All standard Playwright MCP options (`--headless`, `--browser`, `--caps`, etc.) are passed through to the upstream server.
-
-<details>
-<summary>Claude Code</summary>
-
-```bash
-claude mcp add moltbrowser-mcp npx moltbrowser-mcp
-```
-</details>
-
-<details>
-<summary>Cursor</summary>
-
-Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Use `command` type with the command `npx moltbrowser-mcp`.
-</details>
-
-<details>
-<summary>Claude Desktop / Other MCP clients</summary>
-
-Use the standard config above in your MCP client's settings file.
-</details>
-
 ### How It Works
 
 ```
@@ -105,14 +43,14 @@ Agent (Claude, Cursor, etc.)
   |
   |  MCP protocol (stdio)
   v
-Proxy MCP Server (this fork)
+moltbrowser-mcp (hub proxy)
   |-- On navigate: queries WebMCP Hub REST API
   |-- Dynamically adds hub tools to tool list
   |-- Hub tool calls -> translates to Playwright code -> browser_run_code
   |
   |  MCP protocol (stdio, child process)
   v
-Upstream Playwright MCP (unchanged)
+Playwright browser automation
   |
   v
 Browser (Chrome, Firefox, WebKit)
@@ -135,7 +73,7 @@ Hub tools are prefixed with `hub_` and appear/disappear as the agent navigates b
 
 ### Configuration
 
-All standard Playwright MCP options are supported and passed through to the upstream server:
+All standard browser automation options are supported:
 
 <!--- Options generated by update-readme.js -->
 
@@ -147,11 +85,9 @@ All standard Playwright MCP options are supported and passed through to the upst
 | --blocked-origins <origins> | semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed. Important: *does not* serve as a security boundary and *does not* affect redirects.<br>*env* `PLAYWRIGHT_MCP_BLOCKED_ORIGINS` |
 | --block-service-workers | block service workers<br>*env* `PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS` |
 | --browser <browser> | browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.<br>*env* `PLAYWRIGHT_MCP_BROWSER` |
-| --caps <caps> | comma-separated list of additional capabilities to enable, possible values: vision, pdf, devtools.<br>*env* `PLAYWRIGHT_MCP_CAPS` |
+| --caps <caps> | comma-separated list of additional capabilities to enable, possible values: vision, pdf.<br>*env* `PLAYWRIGHT_MCP_CAPS` |
 | --cdp-endpoint <endpoint> | CDP endpoint to connect to.<br>*env* `PLAYWRIGHT_MCP_CDP_ENDPOINT` |
 | --cdp-header <headers...> | CDP headers to send with the connect request, multiple can be specified.<br>*env* `PLAYWRIGHT_MCP_CDP_HEADER` |
-| --cdp-timeout <timeout> | timeout in milliseconds for connecting to CDP endpoint, defaults to 30000ms<br>*env* `PLAYWRIGHT_MCP_CDP_TIMEOUT` |
-| --codegen <lang> | specify the language to use for code generation, possible values: "typescript", "none". Default is "typescript".<br>*env* `PLAYWRIGHT_MCP_CODEGEN` |
 | --config <path> | path to the configuration file.<br>*env* `PLAYWRIGHT_MCP_CONFIG` |
 | --console-level <level> | level of console messages to return: "error", "warning", "info", "debug". Each level includes the messages of more severe levels.<br>*env* `PLAYWRIGHT_MCP_CONSOLE_LEVEL` |
 | --device <device> | device to emulate, for example: "iPhone 15"<br>*env* `PLAYWRIGHT_MCP_DEVICE` |
@@ -171,7 +107,6 @@ All standard Playwright MCP options are supported and passed through to the upst
 | --port <port> | port to listen on for SSE transport.<br>*env* `PLAYWRIGHT_MCP_PORT` |
 | --proxy-bypass <bypass> | comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"<br>*env* `PLAYWRIGHT_MCP_PROXY_BYPASS` |
 | --proxy-server <proxy> | specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"<br>*env* `PLAYWRIGHT_MCP_PROXY_SERVER` |
-| --sandbox | enable the sandbox for all process types that are normally not sandboxed.<br>*env* `PLAYWRIGHT_MCP_SANDBOX` |
 | --save-session | Whether to save the Playwright MCP session into the output directory.<br>*env* `PLAYWRIGHT_MCP_SAVE_SESSION` |
 | --save-trace | Whether to save the Playwright Trace of the session into the output directory.<br>*env* `PLAYWRIGHT_MCP_SAVE_TRACE` |
 | --save-video <size> | Whether to save the video of the session into the output directory. For example "--save-video=800x600"<br>*env* `PLAYWRIGHT_MCP_SAVE_VIDEO` |
@@ -185,12 +120,16 @@ All standard Playwright MCP options are supported and passed through to the upst
 | --user-agent <ua string> | specify user agent string<br>*env* `PLAYWRIGHT_MCP_USER_AGENT` |
 | --user-data-dir <path> | path to the user data directory. If not specified, a temporary directory will be created.<br>*env* `PLAYWRIGHT_MCP_USER_DATA_DIR` |
 | --viewport-size <size> | specify browser viewport size in pixels, for example "1280x720"<br>*env* `PLAYWRIGHT_MCP_VIEWPORT_SIZE` |
+| --codegen <lang> | specify the language to use for code generation, possible values: "typescript", "none". Default is "typescript".<br>*env* `PLAYWRIGHT_MCP_CODEGEN` |
 
 <!--- End of options generated section -->
 
+<details>
+<summary><b>Advanced configuration</b></summary>
+
 ### User profile
 
-You can run Playwright MCP with persistent profile like a regular browser (default), in isolated contexts for testing sessions, or connect to your existing browser using the browser extension.
+You can run with a persistent profile like a regular browser (default), in isolated contexts for testing sessions, or connect to your existing browser using the browser extension.
 
 **Persistent profile**
 
@@ -221,7 +160,7 @@ state [here](https://playwright.dev/docs/auth).
     "playwright": {
       "command": "npx",
       "args": [
-        "@playwright/mcp@latest",
+        "moltbrowser-mcp",
         "--isolated",
         "--storage-state={path/to/storage.json}"
       ]
@@ -230,10 +169,6 @@ state [here](https://playwright.dev/docs/auth).
 }
 ```
 
-**Browser Extension**
-
-The Playwright MCP Chrome Extension allows you to connect to existing browser tabs and leverage your logged-in sessions and browser state. See [packages/extension/README.md](packages/extension/README.md) for installation and setup instructions.
-
 ### Initial state
 
 There are multiple ways to provide the initial state to the browser context or a page.
@@ -265,11 +200,11 @@ window.isPlaywrightMCP = true;
 
 ### Configuration file
 
-The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file
+The server can be configured using a JSON configuration file. You can specify the configuration file
 using the `--config` command line option:
 
 ```bash
-npx @playwright/mcp@latest --config path/to/config.json
+npx moltbrowser-mcp --config path/to/config.json
 ```
 
 <details>
@@ -499,7 +434,7 @@ When running headed browser on system w/o display or from worker processes of th
 run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable HTTP transport.
 
 ```bash
-npx @playwright/mcp@latest --port 8931
+npx moltbrowser-mcp --port 8931
 ```
 
 And then in MCP client config, set the `url` to the HTTP endpoint:
@@ -514,40 +449,6 @@ And then in MCP client config, set the `url` to the HTTP endpoint:
 }
 ```
 
-<details>
-<summary><b>Docker</b></summary>
-
-**NOTE:** The Docker implementation only supports headless chromium at the moment.
-
-```js
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
-    }
-  }
-}
-```
-
-Or If you prefer to run the container as a long-lived service instead of letting the MCP client spawn it, use:
-
-```
-docker run -d -i --rm --init --pull=always \
-  --entrypoint node \
-  --name playwright \
-  -p 8931:8931 \
-  mcr.microsoft.com/playwright/mcp \
-  cli.js --headless --browser chromium --no-sandbox --port 8931
-```
-
-The server will listen on host port **8931** and can be reached by any MCP client.  
-
-You can build the Docker image yourself.
-
-```
-docker build -t mcr.microsoft.com/playwright/mcp .
-```
 </details>
 
 <details>
@@ -556,13 +457,13 @@ docker build -t mcr.microsoft.com/playwright/mcp .
 ```js
 import http from 'http';
 
-import { createConnection } from '@playwright/mcp';
+import { createConnection } from 'moltbrowser-mcp';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 
 http.createServer(async (req, res) => {
   // ...
 
-  // Creates a headless Playwright MCP server with SSE transport
+  // Creates a headless MCP server with SSE transport
   const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
   const transport = new SSEServerTransport('/messages', res);
   await connection.connect(transport);
@@ -631,6 +532,7 @@ http.createServer(async (req, res) => {
     - `function` (string): () => { /* code */ } or (element) => { /* code */ } when element is provided
     - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element
     - `ref` (string, optional): Exact target element reference from the page snapshot
+    - `filename` (string, optional): Filename to save the result to. If not provided, result is returned as JSON string.
   - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
@@ -684,7 +586,7 @@ http.createServer(async (req, res) => {
 
 - **browser_navigate_back**
   - Title: Go back
-  - Description: Go back to the previous page in the history
+  - Description: Go back to the previous page
   - Parameters: None
   - Read-only: **false**
 
@@ -724,6 +626,7 @@ http.createServer(async (req, res) => {
   - Description: Run Playwright code snippet
   - Parameters:
     - `code` (string): A JavaScript function containing Playwright code to execute. It will be invoked with a single argument, page, which you can use for any page interaction. For example: `async (page) => { await page.getByRole('button', { name: 'Submit' }).click(); return await page.title(); }`
+    - `filename` (string, optional): Filename to save the result to. If not provided, result is returned as JSON string.
   - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
@@ -822,25 +725,18 @@ http.createServer(async (req, res) => {
   - Title: Click
   - Description: Click left mouse button at a given position
   - Parameters:
+    - `element` (string): Human-readable element description used to obtain permission to interact with the element
     - `x` (number): X coordinate
     - `y` (number): Y coordinate
   - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_mouse_down**
-  - Title: Press mouse down
-  - Description: Press mouse down
-  - Parameters:
-    - `button` (string, optional): Button to press, defaults to left
-  - Read-only: **false**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
 - **browser_mouse_drag_xy**
   - Title: Drag mouse
   - Description: Drag left mouse button to a given position
   - Parameters:
+    - `element` (string): Human-readable element description used to obtain permission to interact with the element
     - `startX` (number): Start X coordinate
     - `startY` (number): Start Y coordinate
     - `endX` (number): End X coordinate
@@ -853,29 +749,11 @@ http.createServer(async (req, res) => {
   - Title: Move mouse
   - Description: Move mouse to a given position
   - Parameters:
+    - `element` (string): Human-readable element description used to obtain permission to interact with the element
     - `x` (number): X coordinate
     - `y` (number): Y coordinate
   - Read-only: **false**
 
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_mouse_up**
-  - Title: Press mouse up
-  - Description: Press mouse up
-  - Parameters:
-    - `button` (string, optional): Button to press, defaults to left
-  - Read-only: **false**
-
-<!-- NOTE: This has been generated via update-readme.js -->
-
-- **browser_mouse_wheel**
-  - Title: Scroll mouse wheel
-  - Description: Scroll mouse wheel
-  - Parameters:
-    - `deltaX` (number): X delta
-    - `deltaY` (number): Y delta
-  - Read-only: **false**
-
 </details>
 
 <details>
@@ -952,6 +830,22 @@ http.createServer(async (req, res) => {
 <details>
 <summary><b>Tracing (opt-in via --caps=tracing)</b></summary>
 
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_start_tracing**
+  - Title: Start tracing
+  - Description: Start trace recording
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_stop_tracing**
+  - Title: Stop tracing
+  - Description: Stop trace recording
+  - Parameters: None
+  - Read-only: **true**
+
 </details>
 
 

package/cli.js

@@ -16,9 +16,9 @@
  */
 
 const { program } = require('playwright-core/lib/utilsBundle');
-const { decorateMCPCommand } = require('playwright/lib/mcp/program');
+const { decorateCommand } = require('playwright/lib/mcp/program');
 
 const packageJSON = require('./package.json');
 const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
-decorateMCPCommand(p, packageJSON.version)
+decorateCommand(p, packageJSON.version)
 void program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moltbrowser-mcp",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Playwright MCP with WebMCP Hub integration — dynamic, per-site tools for browser agents",
   "repository": {
     "type": "git",
@@ -20,7 +20,6 @@
     "ctest": "playwright test --project=chrome",
     "ftest": "playwright test --project=firefox",
     "wtest": "playwright test --project=webkit",
-    "dtest": "MCP_IN_DOCKER=1 playwright test --project=chromium-docker",
     "build": "echo OK",
     "npm-publish": "npm run lint && npm run test && npm publish"
   },
@@ -32,8 +31,8 @@
     }
   },
   "dependencies": {
-    "playwright": "1.59.0-alpha-1771104257000",
-    "playwright-core": "1.59.0-alpha-1771104257000"
+    "playwright": "^1.58.2",
+    "playwright-core": "^1.58.2"
   },
   "bin": {
     "playwright-mcp": "cli.js",

package/src/README.md

@@ -1,3 +1,10 @@
-# Where is the source?
+# Hub integration source
 
-Playwright MCP source code is located in the [Playwright monorepo](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/mcp). Please refer to the contributor's guide in [CONTRIBUTING.md](../CONTRIBUTING.md) for more details.
+This directory contains moltbrowser-mcp's WebMCP Hub integration layer:
+
+- **`hub-client.js`** — fetches per-site tool definitions from the WebMCP Hub API
+- **`hub-tools.js`** — registers and deregisters dynamic tools as the browser navigates
+- **`proxy-server.js`** — MCP proxy that wraps the upstream Playwright MCP server and injects hub tools
+- **`execution-translator.js`** — translates hub tool calls into Playwright actions
+
+The upstream Playwright MCP source lives in the [Playwright monorepo](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/mcp).

package/src/execution-translator.js

@@ -441,11 +441,11 @@ function addResultWait(phases, execution) {
 
 /**
  * Add top-level result extraction.
- * If no resultSelector, returns a warning so the agent knows there's no verification.
+ * If no resultSelector, returns a neutral acknowledgment without prompting the agent to snapshot.
  */
 function addExtraction(phases, selector, extractMode, attribute) {
   if (!selector) {
-    phases.push(`return '[no resultSelector configured — action ran but success could not be verified. Use browser_snapshot to check the page.]';`);
+    phases.push(`return '[action ran — no result selector configured]';`);
     return;
   }
   addStepExtraction(phases, selector, extractMode, attribute);

package/src/proxy-server.js

@@ -138,6 +138,7 @@ async function startProxy(options) {
       description: [
         'Access generic Playwright browser tools as a fallback when hub tools are insufficient.',
         'Call without arguments to list all available tools.',
+        'Before calling an unfamiliar tool, use peek: true to inspect its full input schema first.',
         'Common tools: browser_snapshot (see page accessibility tree), browser_click (click element by ref),',
         'browser_fill_form (fill multiple fields), browser_type (type text),',
         'browser_evaluate (run JS on page), browser_take_screenshot (capture page image).',
@@ -149,6 +150,10 @@ async function startProxy(options) {
             type: 'string',
             description: 'The Playwright tool name to run (e.g. "browser_click", "browser_snapshot"). Omit to list available tools.',
           },
+          peek: {
+            type: 'boolean',
+            description: 'Set to true to inspect the full input schema of the specified tool without executing it. Use this before calling an unfamiliar tool to avoid schema errors.',
+          },
           arguments: {
             type: 'object',
             description: 'Arguments for the Playwright tool.',
@@ -240,6 +245,18 @@ async function startProxy(options) {
       };
     }
 
+    // Peek — return the full inputSchema for the named tool without executing it.
+    if (toolArgs.peek === true) {
+      const tools = await getUpstreamTools();
+      const match = tools.find(t => t.name === innerTool);
+      if (!match) {
+        return { content: [{ type: 'text', text: `Unknown tool: "${innerTool}". Call browser_fallback without arguments to list available tools.` }] };
+      }
+      return {
+        content: [{ type: 'text', text: `Schema for ${innerTool}:\n\n${JSON.stringify(match.inputSchema, null, 2)}\n\nDescription: ${match.description || '(none)'}` }],
+      };
+    }
+
     // Any real action tool (not list-tools, not snapshot) counts as "fallback was used".
     // This triggers the one-shot contribution nudge on the next browser_snapshot.
     if (innerTool !== 'browser_snapshot') {