real-browser-mcp-server 1.3.4 → 1.4.0

package/lib/esm/index.mjs

@@ -3,9 +3,9 @@ import { createCursor } from "ghost-cursor-patchright";
 import { PlaywrightBlocker } from "@ghostery/adblocker-playwright";
 import { pageController } from "./module/pageController.mjs";
 import { fileURLToPath } from 'url';
-import Xvfb from "xvfb";
 import * as fs from 'fs';
 import * as path from 'path';
+import { execSync } from 'child_process';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -71,13 +71,28 @@ function loadEnvFile() {
 loadEnvFile();
 
 function getDefaultHeadless() {
-  const envHeadless = (process.env.HEADLESS || '').toLowerCase();
-  return envHeadless === 'true';
+  const envHeadless = process.env.HEADLESS;
+  if (envHeadless !== undefined && envHeadless !== null && envHeadless !== '') {
+    const value = envHeadless.toLowerCase().trim();
+    return value === 'true' || value === '1' || value === 'yes';
+  }
+  // Auto-detect CI environments
+  if (process.env.CI || process.env.GITHUB_ACTIONS || process.env.TRAVIS || process.env.CIRCLECI) {
+    return true;
+  }
+  // Auto-detect headless Linux environments without X11 or Wayland
+  if (process.platform === 'linux') {
+    const hasDisplay = process.env.DISPLAY || process.env.WAYLAND_DISPLAY;
+    if (!hasDisplay) {
+      return true;
+    }
+  }
+  return false;
 }
 
-function applyBrowserShims(browser, page) {
-  if (page._shimsApplied) return page;
-  page._shimsApplied = true;
+function setupRealPage(browser, page) {
+  if (page._setupApplied) return page;
+  page._setupApplied = true;
 
   // Enable ad blocker
   if (adBlockerInstance) {
@@ -90,115 +105,164 @@ function applyBrowserShims(browser, page) {
     });
   }
 
-  // Cookie shims (Compatibility adapter for Playwright context)
-  if (!page.cookies) {
-    page.cookies = async (urls) => {
-      return await page.context().cookies(urls ? (Array.isArray(urls) ? urls : [urls]) : []);
-    };
-  }
-
-  if (!page.setCookie) {
-    page.setCookie = async (...cookies) => {
-      const formatted = cookies.map(c => ({
-        name: c.name,
-        value: c.value,
-        domain: c.domain || new URL(page.url()).hostname,
-        path: c.path || '/',
-        expires: c.expires || undefined,
-        httpOnly: c.httpOnly,
-        secure: c.secure,
-        sameSite: c.sameSite
-      }));
-      await page.context().addCookies(formatted);
-    };
-  }
+  // Human-like smooth scrolling with 60FPS Cubic Ease-Out physics
+  page.realScroll = async (deltaY, duration = 600) => {
+    try {
+      const stepDelay = 15; // ~60 FPS
+      const steps = Math.max(10, Math.floor(duration / stepDelay));
+      const easeOutCubic = (t) => 1 - Math.pow(1 - t, 3);
+      let currentScroll = 0;
+      for (let i = 1; i <= steps; i++) {
+        const t = i / steps;
+        const targetScroll = deltaY * easeOutCubic(t);
+        const diff = targetScroll - currentScroll;
+        await page.mouse.wheel(0, diff);
+        currentScroll = targetScroll;
+        await new Promise(r => setTimeout(r, stepDelay));
+      }
+    } catch (e) {
+      // Fallback to native window scroll in case of wheel errors
+      try {
+        await page.evaluate((y) => window.scrollBy({ top: y, behavior: 'smooth' }), deltaY);
+      } catch (_) {}
+    }
+  };
 
-  if (!page.deleteCookie) {
-    page.deleteCookie = async (...cookies) => {
-      await page.context().clearCookies();
+  // Ghost Cursor integration - Bézier curve human-like mouse movement
+  try {
+    const cursor = createCursor(page);
+    page.realCursor = {
+      move: async (selector, options = {}) => {
+        try {
+          await cursor.actions.move(selector, options);
+        } catch (e) {
+          // Fallback to native hover if ghost-cursor fails
+          try { await page.hover(selector); } catch (_) {}
+        }
+      }
     };
-  }
-
-  // Navigation shims
-  if (!page.waitForNetworkIdle) {
-    page.waitForNetworkIdle = async (options = {}) => {
+    page.realClick = async (selector, options = {}) => {
       try {
-        await page.waitForLoadState('networkidle', { timeout: options.timeout });
+        await cursor.actions.click({ target: selector, ...options });
       } catch (e) {
-        // Ignore networkidle timeouts if they are non-fatal
+        // Fallback to native click if ghost-cursor fails
+        await page.click(selector, options);
       }
     };
+  } catch (e) {
+    // Fallback if ghost-cursor-patchright fails to initialize
+    if (!page.realClick) {
+      page.realClick = async (selector, options) => {
+        await page.click(selector, options);
+      };
+    }
+    if (!page.realCursor) {
+      page.realCursor = {
+        move: async (selector) => {
+          try { await page.hover(selector); } catch (_) {}
+        }
+      };
+    }
   }
 
-  if (!page.evaluateOnNewDocument) {
-    page.evaluateOnNewDocument = async (fn, ...args) => {
-      return await page.addInitScript(fn, ...args);
-    };
+  return page;
+
+}
+
+function getBraveExecutablePath() {
+  if (process.env.BRAVE_PATH && fs.existsSync(process.env.BRAVE_PATH)) {
+    return process.env.BRAVE_PATH;
   }
 
-  // Ghost Cursor integration via ghost-cursor-patchright
-  const cursorPromise = createCursor(page).catch(err => {
-    console.error("Failed to create cursor:", err);
-    return null;
-  });
+  const platform = process.platform;
 
-  page.realCursor = {
-    move: async (selector, options = {}) => {
+  // Try automatic scanning via CLI / registry query
+  if (platform === 'win32') {
+    const regQueries = [
+      'reg query "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\brave.exe" /ve',
+      'reg query "HKEY_CURRENT_USER\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\brave.exe" /ve',
+      'reg query "HKEY_LOCAL_MACHINE\\SOFTWARE\\Clients\\StartMenuInternet\\Brave-Browser\\shell\\open\\command" /ve'
+    ];
+
+    for (const cmd of regQueries) {
       try {
-        const cursor = await cursorPromise;
-        if (cursor) {
-          await cursor.move(selector, options);
-        } else {
-          await page.hover(selector, options);
+        const output = execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+        const match = output.match(/REG_SZ\s+(.*)/);
+        if (match && match[1]) {
+          let p = match[1].trim().replace(/^"|"$/g, '');
+          if (!p.toLowerCase().endsWith('.exe')) {
+            const exeIndex = p.toLowerCase().indexOf('.exe');
+            if (exeIndex !== -1) {
+              p = p.substring(0, exeIndex + 4).replace(/^"|"$/g, '');
+            }
+          }
+          if (fs.existsSync(p)) return p;
         }
-      } catch (e) {
-        // Silently fallback if element is not found
-        try {
-          await page.hover(selector, options);
-        } catch (err) {}
-      }
-    }
-  };
-  page.realClick = async (selector, options = {}) => {
-    try {
-      const cursor = await cursorPromise;
-      if (cursor) {
-        await cursor.click(selector, options);
-      } else {
-        await page.click(selector, options);
-      }
-    } catch (e) {
-      await page.click(selector, options);
+      } catch (e) {}
     }
-  };
 
-  // Mouse wheel shim (Adapter for Playwright positional args)
-  if (page.mouse && page.mouse.wheel) {
-    const originalWheel = page.mouse.wheel.bind(page.mouse);
-    page.mouse.wheel = async (x, y) => {
-      if (typeof x === 'object' && x !== null) {
-        const deltaX = x.deltaX || 0;
-        const deltaY = x.deltaY || 0;
-        return await originalWheel(deltaX, deltaY);
+    try {
+      const output = execSync('where brave.exe', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim().split('\r\n')[0];
+      if (output && fs.existsSync(output)) return output;
+    } catch (e) {}
+  } else if (platform === 'darwin') {
+    try {
+      const output = execSync('mdfind "kMDItemCFBundleIdentifier == \'com.brave.Browser\'"', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim().split('\n')[0];
+      if (output) {
+        const p = path.join(output, 'Contents', 'MacOS', 'Brave Browser');
+        if (fs.existsSync(p)) return p;
       }
-      return await originalWheel(x, y);
-    };
+    } catch (e) {}
+  } else {
+    try {
+      const output = execSync('which brave-browser || which brave', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+      if (output && fs.existsSync(output)) return output;
+    } catch (e) {}
   }
 
-  // Browser shims
-  if (!browser.process) {
-    browser.process = () => ({
-      pid: browser._childProcess?.pid || 1337
-    });
+  // Fallback to hardcoded common paths
+  let paths = [];
+  if (platform === 'win32') {
+    paths = [
+      path.join(process.env.PROGRAMFILES || 'C:\\Program Files', 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'),
+      path.join(process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)', 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'),
+      path.join(process.env.LOCALAPPDATA || '', 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe')
+    ].filter(p => p);
+  } else if (platform === 'darwin') {
+    paths = [
+      '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'
+    ];
+  } else {
+    paths = [
+      '/usr/bin/brave-browser',
+      '/usr/bin/brave',
+      '/usr/bin/brave-browser-stable',
+      '/usr/bin/brave-browser-beta',
+      '/usr/bin/brave-browser-nightly',
+      '/usr/local/bin/brave-browser',
+      '/usr/local/bin/brave'
+    ];
   }
 
-  if (!browser.pages) {
-    browser.pages = async () => {
-      return browser.contexts().flatMap(c => c.pages());
-    };
+  for (const p of paths) {
+    if (p && fs.existsSync(p)) {
+      return p;
+    }
   }
 
-  return page;
+  return null;
+}
+
+async function applyUserAgentOverride(page, userAgent, userAgentMetadata) {
+  try {
+    const client = await page.context().newCDPSession(page);
+    await client.send('Emulation.setUserAgentOverride', {
+      userAgent: userAgent,
+      userAgentMetadata: userAgentMetadata
+    });
+  } catch (e) {
+    // Ignore errors
+  }
 }
 
 export async function connect({
@@ -206,21 +270,8 @@ export async function connect({
   headless = getDefaultHeadless(),
   proxy = {},
   turnstile = false,
-  disableXvfb = false,
+  executablePath = undefined,
 } = {}) {
-  let xvfbInstance = null;
-  if (process.platform === 'linux' && !process.env.DISPLAY && !disableXvfb) {
-    try {
-      xvfbInstance = new Xvfb({
-        silent: true,
-        xvfb_args: ['-screen', '0', '1280x1024x24', '-ac']
-      });
-      xvfbInstance.startSync();
-    } catch (err) {
-      console.error('[xvfb] Failed to start Xvfb server automatically:', err.message);
-    }
-  }
-
   let playwrightProxy = undefined;
   if (proxy && proxy.host && proxy.port) {
     playwrightProxy = {
@@ -232,91 +283,82 @@ export async function connect({
     }
   }
 
+  // 1. Launch a temporary browser to retrieve the native user agent and properties
+  const tempBrowser = await chromium.launch({
+    headless: true,
+    args: ['--no-sandbox', '--disable-setuid-sandbox'],
+    ...(executablePath ? { executablePath } : {}),
+  });
+  const tempContext = await tempBrowser.newContext();
+  const tempPage = await tempContext.newPage();
+  let nativeUa = '';
+  let isBrave = false;
+  try {
+    nativeUa = await tempPage.evaluate(() => navigator.userAgent);
+    isBrave = await tempPage.evaluate(() => typeof navigator.brave !== 'undefined');
+  } catch (e) {
+    nativeUa = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/148.0.0.0 Safari/537.36';
+    isBrave = executablePath && executablePath.toLowerCase().includes('brave');
+  }
+  await tempBrowser.close();
+
+  let modifiedUa = nativeUa.replace(/HeadlessChrome\//g, 'Chrome/');
+  const chromeVersionMatch = modifiedUa.match(/Chrome\/([\d.]+)/);
+  const chromeVersion = chromeVersionMatch ? chromeVersionMatch[1] : '148.0.0.0';
+  const majorVersion = chromeVersion.split('.')[0];
+
+  const brands = [
+    { brand: 'Chromium', version: majorVersion },
+    { brand: 'Not/A)Brand', version: '99' }
+  ];
+  if (isBrave) {
+    brands.unshift({ brand: 'Brave', version: majorVersion });
+  } else {
+    brands.unshift({ brand: 'Google Chrome', version: majorVersion });
+  }
+
+  let platformName = 'Windows';
+  if (nativeUa.includes('Macintosh') || nativeUa.includes('Mac OS X')) {
+    platformName = 'macOS';
+  } else if (nativeUa.includes('Linux')) {
+    platformName = 'Linux';
+  }
+
+  const userAgentMetadata = {
+    brands: brands,
+    mobile: false,
+    platform: platformName,
+    platformVersion: platformName === 'macOS' ? '14.0.0' : platformName === 'Linux' ? '6.0.0' : '10.0.0',
+    architecture: 'x86',
+    model: '',
+    bitness: '64',
+    wow64: false
+  };
+
   const chromiumArgs = [
+    `--user-agent=${modifiedUa}`,
     '--disable-blink-features=AutomationControlled',
     '--no-sandbox',
     '--disable-setuid-sandbox',
-    '--window-size=1920,1080',
     ...args
   ];
 
-  if (headless) {
-    chromiumArgs.push(
-      '--headless=new',
-      '--disable-gpu',
-      '--hide-scrollbars',
-      '--mute-audio'
-    );
-  }
-
-function getBravePath() {
-  if (process.platform === 'win32') {
-    const paths = [
-      "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
-      "C:\\Program Files (x86)\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
-      path.join(process.env.LOCALAPPDATA || '', 'BraveSoftware\\Brave-Browser\\Application\\brave.exe'),
-      path.join(process.env.PROGRAMFILES || '', 'BraveSoftware\\Brave-Browser\\Application\\brave.exe'),
-      path.join(process.env['PROGRAMFILES(X86)'] || '', 'BraveSoftware\\Brave-Browser\\Application\\brave.exe')
-    ];
-    for (const p of paths) {
-      if (p && fs.existsSync(p)) return p;
-    }
-  } else if (process.platform === 'darwin') {
-    const paths = [
-      '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'
-    ];
-    for (const p of paths) {
-      if (fs.existsSync(p)) return p;
-    }
-  } else if (process.platform === 'linux') {
-    const paths = [
-      '/usr/bin/brave-browser',
-      '/usr/bin/brave'
-    ];
-    for (const p of paths) {
-      if (fs.existsSync(p)) return p;
+  // If headless is true, we run with headless: false but pass '--headless=new' to args.
+  // This triggers Chromium's modern undetected headless mode instead of Playwright's default old headless shell.
+  let launchHeadless = headless;
+  if (headless === true) {
+    launchHeadless = false;
+    if (!chromiumArgs.includes('--headless=new')) {
+      chromiumArgs.push('--headless=new');
     }
   }
-  return null;
-}
 
-  const bravePath = getBravePath();
-  if (!bravePath) {
-    throw new Error("Brave Browser was not found on this system. Real Browser MCP Server is configured to exclusively use Brave Browser.");
-  }
-
-  let browser;
-  try {
-    browser = await chromium.launch({
-      headless: false, // Prevent Playwright from adding leaky headless shims
-      args: chromiumArgs,
-      proxy: playwrightProxy,
-      executablePath: bravePath
-    });
-    console.error('[Launch] Successfully launched system Brave Browser');
-  } catch (err) {
-    console.error('[Launch] Failed to launch system Brave Browser:', err.message);
-    throw err;
-  }
-
-  if (xvfbInstance) {
-    browser.on('disconnected', () => {
-      try {
-        xvfbInstance.stopSync();
-      } catch (e) {
-        console.error('[xvfb] Failed to stop Xvfb server:', e.message);
-      }
-    });
-    const originalClose = browser.close.bind(browser);
-    browser.close = async () => {
-      await originalClose();
-      try {
-        xvfbInstance.stopSync();
-      } catch (e) {
-        console.error('[xvfb] Failed to stop Xvfb server during close:', e.message);
-      }
-    };
-  }
+  const browser = await chromium.launch({
+    headless: launchHeadless,
+    args: chromiumArgs,
+    proxy: playwrightProxy,
+    ...(executablePath ? { executablePath } : {}),
+  });
 
   // Ensure ad blocker is ready
   await getAdBlocker();
@@ -327,7 +369,9 @@ function getBravePath() {
 
   let page = await context.newPage();
 
-  applyBrowserShims(browser, page);
+  await applyUserAgentOverride(page, modifiedUa, userAgentMetadata);
+
+  setupRealPage(browser, page);
 
   page = await pageController({
     browser,
@@ -337,7 +381,8 @@ function getBravePath() {
   });
 
   context.on('page', async (newPage) => {
-    applyBrowserShims(browser, newPage);
+    await applyUserAgentOverride(newPage, modifiedUa, userAgentMetadata);
+    setupRealPage(browser, newPage);
     await pageController({
       browser,
       page: newPage,

package/lib/esm/module/pageController.mjs

@@ -24,26 +24,29 @@ export async function pageController({ browser, page, proxy, turnstile }) {
 
     // === POPUP AD BLOCKING ===
     const context = page.context();
-    context.on('page', async (newPage) => {
-        try {
-            const opener = await newPage.opener();
-            if (opener) {
-                const url = newPage.url();
-                const isAdPopup = url === 'about:blank' ||
-                    url.includes('ad') ||
-                    url.includes('pop') ||
-                    url.includes('click') ||
-                    url.includes('redirect') ||
-                    url.includes('track');
-                if (isAdPopup) {
-                    await newPage.close().catch(() => { });
-                    console.error('[popup-blocker] Blocked popup ad:', url.substring(0, 50));
+    if (!context._popupBlockerApplied) {
+        context._popupBlockerApplied = true;
+        context.on('page', async (newPage) => {
+            try {
+                const opener = await newPage.opener();
+                if (opener) {
+                    const url = newPage.url();
+                    const isAdPopup = url === 'about:blank' ||
+                        url.includes('ad') ||
+                        url.includes('pop') ||
+                        url.includes('click') ||
+                        url.includes('redirect') ||
+                        url.includes('track');
+                    if (isAdPopup) {
+                        await newPage.close().catch(() => { });
+                        console.error('[popup-blocker] Blocked popup ad:', url.substring(0, 50));
+                    }
                 }
+            } catch (e) {
+                // Ignore errors
             }
-        } catch (e) {
-            // Ignore errors
-        }
-    });
+        });
+    }
 
     // NOTE: JS stealth overrides are commented out because Patchright natively handles automation hiding.
     // Manual JS overrides trigger Pixelscan fingerprint masking detectors.

package/lib/esm/module/turnstile.mjs

@@ -2,6 +2,13 @@ export const checkTurnstile = async ({ page }) => {
     try {
         const elements = await page.locator('[name="cf-turnstile-response"]').all();
         if (elements.length <= 0) {
+            const isChallenge = await page.evaluate(() => {
+                return document.title.includes('Just a moment') || 
+                       document.querySelector('#challenge-stage') !== null ||
+                       document.querySelector('.cf-turnstile') !== null;
+            });
+            if (!isChallenge) return false;
+
             const coordinates = await page.evaluate(() => {
                 let coordinates = [];
                 document.querySelectorAll('div').forEach(item => {

package/package.json

@@ -1,35 +1,41 @@
 {
   "name": "real-browser-mcp-server",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "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",
+  "main": "dist/lib/cjs/index.js",
   "module": "lib/esm/index.mjs",
   "type": "commonjs",
   "exports": {
     ".": {
       "types": "./typings.d.ts",
       "import": "./lib/esm/index.mjs",
-      "require": "./lib/cjs/index.js"
+      "require": "./dist/lib/cjs/index.js"
     }
   },
+  "files": [
+    "dist",
+    "lib/esm",
+    "typings.d.ts"
+  ],
   "typings": "typings.d.ts",
   "engines": {
     "node": ">=18.0.0"
   },
   "bin": {
-    "real-browser-mcp": "./src/index.js"
+    "real-browser-mcp": "./dist/src/index.js"
   },
   "scripts": {
-    "start": "node src/index.js",
-    "dev": "node src/index.js",
-    "mcp": "node src/index.js mcp",
-    "mcp:verbose": "node src/index.js mcp --verbose",
-    "list": "node src/index.js --list",
+    "prepublishOnly": "npm run build",
+    "build": "tsc",
+    "start": "node dist/src/index.js",
+    "dev": "npm run build && node dist/src/index.js",
+    "mcp": "node dist/src/index.js mcp",
+    "mcp:verbose": "node dist/src/index.js mcp --verbose",
+    "list": "node dist/src/index.js --list",
     "test": "npm run cjs_test && npm run esm_test",
-    "esm_test": "node ./test/esm/test.js",
-    "cjs_test": "node ./test/cjs/test.js",
-    "build": "echo 'No build step required for this package.'",
-    "postinstall": "npx patchright install chromium"
+    "esm_test": "node ./test/esm/test.mjs",
+    "cjs_test": "node ./dist/test/cjs/test.js",
+    "mcp_test": "node ./dist/test/mcp/smoke-test.js"
   },
   "keywords": [
     "mcp-server",
@@ -45,8 +51,11 @@
   "dependencies": {
     "@ghostery/adblocker-playwright": "latest",
     "@modelcontextprotocol/sdk": "latest",
-    "patchright": "latest",
-    "ghost-cursor-patchright": "file:../ghost-cursor",
-    "xvfb": "latest"
+    "ghost-cursor-patchright": "^1.0.2",
+    "patchright": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3"
   }
 }

package/typings.d.ts

@@ -24,8 +24,9 @@ declare module "real-browser-mcp-server" {
 		turnstile?: boolean;
 		connectOption?: any;
 		disableXvfb?: boolean;
-		plugins?: any[];
 		ignoreAllFlags?: boolean;
+		/** Path to the browser executable (defaults to auto-detected Brave browser or falls back to Chromium) */
+		executablePath?: string;
 		/** Enable blocker on all pages (default: true) */
 		enableBlocker?: boolean;
 		/** Blocker configuration options */
@@ -77,3 +78,8 @@ declare module "real-browser-mcp-server" {
 		shouldBlock(url: string): boolean;
 	}
 }
+
+declare module "real-browser-mcp-server" {
+	export * from "real-browser-mcp-server";
+}
+