real-browser-mcp-server 1.0.6 → 1.0.8

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 : false;
+
   // 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 : false;
+
+  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 : false;
+
   // 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 : false;
+
+  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.8",
   "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/ai/core.js

@@ -90,9 +90,13 @@ class AICore {
       if (element) {
         if (humanLike) {
           try {
-            const { createCursor } = require('ghost-cursor-patchright');
-            const cursor = createCursor(page);
-            await cursor.click(selector);
+            if (page.realClick) {
+              await page.realClick(selector);
+            } else {
+              const { createCursor } = require('ghost-cursor-patchright');
+              const cursor = await createCursor(page);
+              await cursor.click(selector);
+            }
           } catch {
             await element.click();
           }

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) {
@@ -2002,9 +2005,13 @@ const handlers = {
 
       // Click submit button with human-like behavior
       try {
-        const { createCursor } = require('ghost-cursor-patchright');
-        const cursor = createCursor(page);
-        await cursor.click(submitSelector);
+        if (page.realClick) {
+          await page.realClick(submitSelector);
+        } else {
+          const { createCursor } = require('ghost-cursor-patchright');
+          const cursor = await createCursor(page);
+          await cursor.click(submitSelector);
+        }
       } catch (e) {
         await page.click(submitSelector);
       }
@@ -4766,13 +4773,18 @@ const handlers = {
                 }
               }
             }, identity, String(value));
-          } else {
             // Smart Type
-            const { createCursor } = require('ghost-cursor-patchright');
-            const cursor = createCursor(page);
-
-            // Click center of element
-            await cursor.click(identity);
+            if (page.realClick) {
+              await page.realClick(identity);
+            } else {
+              try {
+                const { createCursor } = require('ghost-cursor-patchright');
+                const cursor = await createCursor(page);
+                await cursor.click(identity);
+              } catch (e) {
+                await page.click(identity);
+              }
+            }
 
             // Clear existing
             await page.evaluate(s => document.querySelector(s).value = '', identity);
@@ -4835,9 +4847,17 @@ const handlers = {
       });
 
       if (submitSelector) {
-        const { createCursor } = require('ghost-cursor-patchright');
-        const cursor = createCursor(page);
-        await cursor.click(submitSelector);
+        if (page.realClick) {
+          await page.realClick(submitSelector);
+        } else {
+          try {
+            const { createCursor } = require('ghost-cursor-patchright');
+            const cursor = await createCursor(page);
+            await cursor.click(submitSelector);
+          } catch (e) {
+            await page.click(submitSelector);
+          }
+        }
 
         try {
           await page.waitForNavigation({ timeout: 5000, waitUntil: 'domcontentloaded' });

package/test/cjs/test.js

@@ -4,7 +4,7 @@ const { connect } = require('../../lib/cjs/index.js');
 
 const realBrowserOption = {
     turnstile: true,
-    headless: true,
+    headless: false,
     customConfig: {}
 }
 
@@ -32,7 +32,9 @@ test.after(async () => {
 
 test('DrissionPage Detector', async () => {
     await page.goto("https://web.archive.org/web/20240913054632/https://drissionpage.pages.dev/", { timeout: 60000 });
+    await page.waitForSelector("#detector", { timeout: 20000 });
     await page.realClick("#detector")
+    await page.waitForSelector("#isBot span", { timeout: 20000 });
     let result = await page.evaluate(() => { return document.querySelector('#isBot span').textContent.includes("not") ? true : false })
     assert.strictEqual(result, true, "DrissionPage Detector test failed!")
 })

package/test/esm/test.mjs

@@ -4,7 +4,7 @@ import { connect } from '../../lib/esm/index.mjs';
 
 const realBrowserOption = {
     turnstile: true,
-    headless: true,
+    headless: false,
     customConfig: {}
 }
 
@@ -32,7 +32,9 @@ test.after(async () => {
 
 test('DrissionPage Detector', async () => {
     await page.goto("https://web.archive.org/web/20240913054632/https://drissionpage.pages.dev/", { timeout: 70000 });
+    await page.waitForSelector("#detector", { timeout: 20000 });
     await page.realClick("#detector")
+    await page.waitForSelector("#isBot span", { timeout: 20000 });
     let result = await page.evaluate(() => { return document.querySelector('#isBot span').textContent.includes("not") ? true : false })
     assert.strictEqual(result, true, "DrissionPage Detector test failed!")
 })

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 {