real-browser-mcp-server 1.0.6 → 1.0.7

package/README.md

@@ -11,6 +11,26 @@ This server is **100% compatible with all major AI IDEs** (Cursor, VS Code, Clin
 
 ---
 
+## ⚙️ Installation & Setup
+
+To install and run the server locally, clone the repository, install NPM dependencies, and configure the undetected browser binary using **Patchright**:
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/codeiva4u/Real-Browser-Mcp-Server.git
+
+# 2. Navigate to the project directory
+cd Real-Browser-Mcp-Server
+
+# 3. Install dependencies
+npm install
+
+# 4. Install Chromium-Driver for Patchright (Undetected Browser binary)
+npx patchright install chromium
+```
+
+---
+
 ## 🚀 Key Evasion & Stealth Features
 
 * **Undetected Browser Engine**: Powered by **Patchright Chromium**, bypassing modern fingerprinting checks (does not expose automation indicators or Webdriver/BiDi flags).

package/lib/cjs/index.js

@@ -70,10 +70,13 @@ function getDefaultHeadless() {
   return envHeadless === 'true';
 }
 
-function setupRealPage(browser, page) {
+function setupRealPage(browser, page, options = {}) {
   if (page._setupApplied) return page;
   page._setupApplied = true;
 
+  const headless = options.headless !== undefined ? options.headless : getDefaultHeadless();
+  const showCursor = options.showCursor !== undefined ? options.showCursor : !headless;
+
   // Enable ad blocker
   if (adBlockerInstance) {
     adBlockerInstance.enableBlockingInPage(page).catch(() => {});
@@ -87,11 +90,13 @@ function setupRealPage(browser, page) {
 
   // Ghost Cursor integration - Bézier curve human-like mouse movement
   try {
-    const cursor = createCursor(page);
+    // 5th parameter controls visual cursor (installMouseHelper under the hood)
+    const cursorPromise = createCursor(page, undefined, false, {}, showCursor);
     page.realCursor = {
       move: async (selector, options = {}) => {
         try {
-          await cursor.actions.move(selector, options);
+          const cursor = await cursorPromise;
+          await cursor.move(selector, options);
         } catch (e) {
           // Fallback to native hover if ghost-cursor fails
           try { await page.hover(selector); } catch (_) {}
@@ -100,7 +105,8 @@ function setupRealPage(browser, page) {
     };
     page.realClick = async (selector, options = {}) => {
       try {
-        await cursor.actions.click({ target: selector, ...options });
+        const cursor = await cursorPromise;
+        await cursor.click(selector, options);
       } catch (e) {
         // Fallback to native click if ghost-cursor fails
         await page.click(selector, options);
@@ -228,6 +234,7 @@ async function connect({
   proxy = {},
   turnstile = false,
   executablePath = undefined,
+  visualCursor = undefined,
 } = {}) {
   let playwrightProxy = undefined;
   if (proxy && proxy.host && proxy.port) {
@@ -328,7 +335,9 @@ async function connect({
 
   await applyUserAgentOverride(page, modifiedUa, userAgentMetadata);
 
-  setupRealPage(browser, page);
+  const showCursor = visualCursor !== undefined ? visualCursor : !headless;
+
+  setupRealPage(browser, page, { headless, showCursor });
 
   page = await pageController({
     browser,
@@ -339,7 +348,7 @@ async function connect({
 
   context.on('page', async (newPage) => {
     await applyUserAgentOverride(newPage, modifiedUa, userAgentMetadata);
-    setupRealPage(browser, newPage);
+    setupRealPage(browser, newPage, { headless, showCursor });
     await pageController({
       browser,
       page: newPage,

package/lib/esm/index.mjs

@@ -75,10 +75,13 @@ function getDefaultHeadless() {
   return envHeadless === 'true';
 }
 
-function setupRealPage(browser, page) {
+function setupRealPage(browser, page, options = {}) {
   if (page._setupApplied) return page;
   page._setupApplied = true;
 
+  const headless = options.headless !== undefined ? options.headless : getDefaultHeadless();
+  const showCursor = options.showCursor !== undefined ? options.showCursor : !headless;
+
   // Enable ad blocker
   if (adBlockerInstance) {
     adBlockerInstance.enableBlockingInPage(page).catch(() => {});
@@ -92,11 +95,13 @@ function setupRealPage(browser, page) {
 
   // Ghost Cursor integration - Bézier curve human-like mouse movement
   try {
-    const cursor = createCursor(page);
+    // 5th parameter controls visual cursor (installMouseHelper under the hood)
+    const cursorPromise = createCursor(page, undefined, false, {}, showCursor);
     page.realCursor = {
       move: async (selector, options = {}) => {
         try {
-          await cursor.actions.move(selector, options);
+          const cursor = await cursorPromise;
+          await cursor.move(selector, options);
         } catch (e) {
           // Fallback to native hover if ghost-cursor fails
           try { await page.hover(selector); } catch (_) {}
@@ -105,7 +110,8 @@ function setupRealPage(browser, page) {
     };
     page.realClick = async (selector, options = {}) => {
       try {
-        await cursor.actions.click({ target: selector, ...options });
+        const cursor = await cursorPromise;
+        await cursor.click(selector, options);
       } catch (e) {
         // Fallback to native click if ghost-cursor fails
         await page.click(selector, options);
@@ -232,6 +238,7 @@ export async function connect({
   proxy = {},
   turnstile = false,
   executablePath = undefined,
+  visualCursor = undefined,
 } = {}) {
   let playwrightProxy = undefined;
   if (proxy && proxy.host && proxy.port) {
@@ -332,7 +339,9 @@ export async function connect({
 
   await applyUserAgentOverride(page, modifiedUa, userAgentMetadata);
 
-  setupRealPage(browser, page);
+  const showCursor = visualCursor !== undefined ? visualCursor : !headless;
+
+  setupRealPage(browser, page, { headless, showCursor });
 
   page = await pageController({
     browser,
@@ -343,7 +352,7 @@ export async function connect({
 
   context.on('page', async (newPage) => {
     await applyUserAgentOverride(newPage, modifiedUa, userAgentMetadata);
-    setupRealPage(browser, newPage);
+    setupRealPage(browser, newPage, { headless, showCursor });
     await pageController({
       browser,
       page: newPage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "real-browser-mcp-server",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "MCP Server for Real Browser - Patchright (undetected Playwright fork) with Stealth Mode, Ad Blocker, and Turnstile Auto-Solver for undetectable web automation.",
   "main": "lib/cjs/index.js",
   "module": "lib/esm/index.mjs",

package/src/mcp/handlers.js

@@ -1239,20 +1239,23 @@ const handlers = {
             notifyProgress('click', 'progress', 'Used force click (JS)');
           } else if (humanLike) {
             try {
-              const { createCursor } = require('ghost-cursor-patchright');
-              const cursor = createCursor(page);
-
               if (context !== page) {
                 const element = await context.$(selector);
                 if (element) {
                   const box = await element.boundingBox();
                   if (box) {
-                    await cursor.moveTo({ x: box.x + box.width / 2, y: box.y + box.height / 2 });
+                    if (page.realCursor) {
+                      await page.realCursor.move({ x: box.x + box.width / 2, y: box.y + box.height / 2 });
+                    }
                     await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2, { clickCount, delay });
                   }
                 }
               } else {
-                await cursor.click(selector);
+                if (page.realClick) {
+                  await page.realClick(selector);
+                } else {
+                  await context.click(selector, { clickCount, delay });
+                }
               }
               notifyProgress('click', 'progress', 'Used human-like cursor movement');
             } catch (e) {

package/typings.d.ts

@@ -31,6 +31,8 @@ declare module "real-browser-mcp-server" {
 		enableBlocker?: boolean;
 		/** Blocker configuration options */
 		blockerOptions?: BlockerOptions;
+		/** Enable visual cursor arrow overlay (defaults to true in headed/visible mode, false in headless mode) */
+		visualCursor?: boolean;
 	}
 
 	interface ProxyOptions {