real-browser-mcp-server 1.0.10 → 1.1.2

package/README.md

@@ -35,7 +35,7 @@ npx patchright install chromium
 
 * **Undetected Browser Engine**: Powered by **Patchright Chromium**, bypassing modern fingerprinting checks (does not expose automation indicators or Webdriver/BiDi flags).
 * **Integrated Ad & Tracker Blocker**: Utilizes `@ghostery/adblocker-playwright` with asynchronous pre-compiled filter caching to `adblocker.bin`, blocking ads and speed-bumps completely offline.
-* **Human-like Interactions**: Integrates **ghost-cursor-patchright** (Bézier curves) to transparently simulate human mouse movements, velocity, and natural hover-before-click behaviors.
+* **Human-like Interactions**: Integrates **ghost-cursor-patchright** (Bézier curves) to transparently simulate human mouse movements, velocity, and natural hover-before-click behaviors. Features **Physics-based Smooth Scrolling** (`page.realScroll`) utilizing real mouse-wheel events and Cubic Ease-Out deceleration to perfectly mimic manual trackpad/mouse flicks, bypassing advanced behavioral detectors.
 * **Turnstile Auto-Solver**: Seamlessly detects and bypasses Cloudflare Turnstile widgets.
 * **Anti-Race Condition Guards**: Robust state-guards ensure popup blockers, shims, and adblockers attach exactly once per page, preventing context destruction.
 
@@ -158,7 +158,7 @@ The server exposes 22 highly optimized tools categorized into functional units:
 | `click` | Human-like click using AI healing, ghost cursor, and iframe support. | `selector` (string), `hoverFirst` (boolean) |
 | `type` | Type text with human speed variation, smart clearing, and iframe support. | `selector` (string), `text` (string) |
 | `solve_captcha` | Auto-solve CAPTCHAs (Turnstile, reCAPTCHA, hCaptcha, OCR). | `selector` (string) |
-| `random_scroll` | Simulated human scrolling with natural patterns and lazy-load triggers. | `direction` (string), `amount` (number) |
+| `random_scroll` | Simulated human scrolling with natural patterns and lazy-load triggers. | `direction` (string), `amount` (number), `smooth` (boolean) |
 | `press_key` | Press keyboard keys with modifier key support (Ctrl/Shift/Alt). | `key` (string), `modifiers` (array) |
 | `execute_js` | Run custom asynchronous/synchronous JavaScript inside a page or iframe. | `code` (string), `iframeIndex` (number) |
 
@@ -213,6 +213,11 @@ Both the CommonJS and ES Module test suites execute and pass successfully under
 | **CommonJS (`cjs_test`)** | Fingerprint JS Bot Detector | ✅ Passed |
 | **CommonJS (`cjs_test`)** | Recaptcha V3 Score | ✅ Passed |
 | **CommonJS (`cjs_test`)** | Pixelscan Fingerprint Check | ✅ Passed |
+| **CommonJS (`cjs_test`)** | Human-like Move & Click | ✅ Passed |
+| **CommonJS (`cjs_test`)** | Human-like Typing | ✅ Passed |
+| **CommonJS (`cjs_test`)** | Human-like Scrolling | ✅ Passed |
+| **CommonJS (`cjs_test`)** | Form Automation Demonstration | ✅ Passed |
+| **CommonJS (`cjs_test`)** | Content Strategy Demonstration | ✅ Passed |
 | **ES Module (`esm_test`)** | DrissionPage Detector | ✅ Passed |
 | **ES Module (`esm_test`)** | Sannysoft WebDriver Detector | ✅ Passed |
 | **ES Module (`esm_test`)** | Cloudflare WAF | ✅ Passed |
@@ -220,6 +225,11 @@ Both the CommonJS and ES Module test suites execute and pass successfully under
 | **ES Module (`esm_test`)** | Fingerprint JS Bot Detector | ✅ Passed |
 | **ES Module (`esm_test`)** | Recaptcha V3 Score | ✅ Passed |
 | **ES Module (`esm_test`)** | Pixelscan Fingerprint Check | ✅ Passed |
+| **ES Module (`esm_test`)** | Human-like Move & Click | ✅ Passed |
+| **ES Module (`esm_test`)** | Human-like Typing | ✅ Passed |
+| **ES Module (`esm_test`)** | Human-like Scrolling | ✅ Passed |
+| **ES Module (`esm_test`)** | Form Automation Demonstration | ✅ Passed |
+| **ES Module (`esm_test`)** | Content Strategy Demonstration | ✅ Passed |
 
 ---
 
@@ -244,6 +254,9 @@ const { connect } = require('real-browser-mcp-server');
   // Real mouse movement and click
   await page.realClick('#my-button');
   
+  // Real human-like smooth scrolling (60FPS Cubic Ease-Out physics)
+  await page.realScroll(400); // scrolls down 400px smoothly
+  
   await browser.close();
 })();
 ```
@@ -259,6 +272,10 @@ const { browser, page } = await connect({
 
 await page.goto('https://example.com');
 await page.realClick('#my-button');
+
+// Real human-like smooth scrolling (60FPS Cubic Ease-Out physics)
+await page.realScroll(400); // scrolls down 400px smoothly
+
 await browser.close();
 ```
 

package/lib/cjs/index.js

@@ -66,8 +66,23 @@ 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 setupRealPage(browser, page) {
@@ -85,6 +100,29 @@ function setupRealPage(browser, page) {
     });
   }
 
+  // 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 (_) {}
+    }
+  };
+
   // Ghost Cursor integration - Bézier curve human-like mouse movement
   try {
     const cursor = createCursor(page);
@@ -123,6 +161,7 @@ function setupRealPage(browser, page) {
   }
 
   return page;
+
 }
 
 function getBraveExecutablePath() {

package/lib/esm/index.mjs

@@ -71,8 +71,23 @@ 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 setupRealPage(browser, page) {
@@ -90,6 +105,29 @@ function setupRealPage(browser, page) {
     });
   }
 
+  // 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 (_) {}
+    }
+  };
+
   // Ghost Cursor integration - Bézier curve human-like mouse movement
   try {
     const cursor = createCursor(page);
@@ -128,6 +166,7 @@ function setupRealPage(browser, page) {
   }
 
   return page;
+
 }
 
 function getBraveExecutablePath() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "real-browser-mcp-server",
-  "version": "1.0.10",
+  "version": "1.1.2",
   "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

@@ -68,13 +68,25 @@ function notifyProgress(toolName, status, message, data = {}) {
 function getHeadlessFromEnv() {
   const envHeadless = process.env.HEADLESS;
 
-  if (envHeadless === undefined || envHeadless === null || envHeadless === '') {
-    return false; // Default: GUI mode
+  if (envHeadless !== undefined && envHeadless !== null && envHeadless !== '') {
+    const value = envHeadless.toLowerCase().trim();
+    return value === 'true' || value === '1' || value === 'yes';
   }
 
-  // Parse string to boolean
-  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;
 }
 
 /**
@@ -2049,10 +2061,14 @@ const handlers = {
 
     notifyProgress('random_scroll', 'started', `Scrolling ${scrollDirection} ${scrollAmount}px`);
 
-    await page.evaluate(({ scrollAmount, scrollDirection, smooth }) => {
-      const y = scrollDirection === 'down' ? scrollAmount : -scrollAmount;
-      window.scrollBy({ top: y, behavior: smooth ? 'smooth' : 'auto' });
-    }, { scrollAmount, scrollDirection, smooth });
+    const y = scrollDirection === 'down' ? scrollAmount : -scrollAmount;
+    if (smooth && page.realScroll) {
+      await page.realScroll(y, 600);
+    } else {
+      await page.evaluate(({ y, smooth }) => {
+        window.scrollBy({ top: y, behavior: smooth ? 'smooth' : 'auto' });
+      }, { y, smooth });
+    }
 
     notifyProgress('random_scroll', 'completed', `Scrolled ${scrollDirection} ${scrollAmount}px`, { direction: scrollDirection, amount: scrollAmount });
 

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: {}
 }
 
@@ -30,6 +30,126 @@ test.after(async () => {
     }
 });
 
+test('Human-like Move & Click', async () => {
+    await page.goto("https://www.google.com", { timeout: 40000 });
+    const selector = 'textarea[name="q"], input[name="q"]';
+    await page.realCursor.move(selector);
+    await page.realClick(selector);
+    assert.ok(true);
+})
+
+test('Human-like Typing', async () => {
+    await page.goto("https://www.google.com", { timeout: 40000 });
+    const selector = 'textarea[name="q"], input[name="q"]';
+    await page.realCursor.move(selector);
+    await page.realClick(selector);
+    await page.type(selector, 'Real Browser MCP Server', { delay: 150 });
+    const val = await page.inputValue(selector);
+    assert.strictEqual(val, 'Real Browser MCP Server');
+})
+
+test('Human-like Scrolling', async () => {
+    await page.goto("https://www.google.com/search?q=Real+Browser+MCP+Server", { timeout: 40000, waitUntil: 'domcontentloaded' });
+    await new Promise(r => setTimeout(r, 2000));
+    
+    console.log('📜 Scrolling down smoothly and fast (400px)...');
+    await page.realScroll(400, 500);
+    await new Promise(r => setTimeout(r, 600));
+    
+    console.log('📜 Scrolling down smoothly and fast (300px)...');
+    await page.realScroll(300, 400);
+    await new Promise(r => setTimeout(r, 600));
+    
+    console.log('📜 Scrolling up smoothly and fast (-500px)...');
+    await page.realScroll(-500, 600);
+    await new Promise(r => setTimeout(r, 1000));
+    
+    assert.ok(true);
+})
+
+test('Form Automation Demonstration', async () => {
+  console.log('\n🎬 DEMO: Form Automation');
+  try {
+    await page.goto('https://httpbin.org/forms/post', { timeout: 30000 });
+    console.log('\n4️⃣ Filling out form...');
+    
+    // 1. Customer Name
+    await page.type('input[name="custname"]', 'John Doe', { delay: 100 });
+    console.log('✅ Customer Name filled');
+
+    // 2. Telephone
+    await page.type('input[name="custtel"]', '+1-555-0199', { delay: 100 });
+    console.log('✅ Telephone filled');
+
+    // 3. Email address
+    await page.type('input[name="custemail"]', 'john.doe@example.com', { delay: 100 });
+    console.log('✅ Email field filled');
+
+    // 4. Pizza Size (Radio Button)
+    await page.realClick('input[value="medium"]');
+    console.log('✅ Pizza Size selected (Medium)');
+
+    // 5. Pizza Toppings (Checkboxes)
+    await page.realClick('input[value="bacon"]');
+    await page.realClick('input[value="onion"]');
+    console.log('✅ Toppings selected (Bacon, Onion)');
+
+    // 6. Preferred Delivery Time
+    await page.type('input[name="delivery"]', '13:00', { delay: 100 });
+    console.log('✅ Delivery time filled');
+
+    // 7. Delivery Instructions (Comments)
+    await page.type('textarea[name="comments"]', 'Leave at the front door, please.', { delay: 100 });
+    console.log('✅ Delivery instructions filled');
+
+    // Wait 2 seconds for visual demonstration
+    await new Promise(resolve => setTimeout(resolve, 2000));
+
+    // 8. Submit Order
+    await page.realClick('form button');
+    console.log('✅ Form submitted successfully');
+    
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    console.log('\n🎉 FORM AUTOMATION COMPLETE!');
+  } catch (error) {
+    console.error('❌ Form automation test failed:', error);
+    throw error;
+  }
+})
+
+test('Content Strategy Demonstration', async () => {
+  console.log('\n🎬 DEMO: Content Analysis & Token Management');
+  console.log('👀 Watch browser analyze content from different websites');
+  try {
+    const testSites = [
+      { url: 'https://httpbin.org/html', description: 'Simple HTML page' },
+      { url: 'https://example.com', description: 'Minimal content page' }
+    ];
+
+    for (const [index, site] of testSites.entries()) {
+      console.log(`\n${index + 2}️⃣ Testing ${site.description}: ${site.url}`);
+      await page.goto(site.url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+      await new Promise(resolve => setTimeout(resolve, 2000));
+
+      console.log(`   📄 Getting HTML content...`);
+      const htmlContent = await page.content();
+      console.log(`   ✅ HTML analyzed: ${htmlContent.length} characters`);
+      
+      console.log(`   📝 Getting text content...`);
+      const textContent = await page.evaluate(() => document.body.innerText);
+      console.log(`   ✅ Text analyzed: ${textContent.length} characters`);
+      
+      assert.ok(htmlContent.length > 0);
+      assert.ok(textContent.length > 0);
+      await new Promise(resolve => setTimeout(resolve, 1500));
+    }
+    console.log('\n🎉 CONTENT ANALYSIS COMPLETE!');
+  } catch (error) {
+    console.error('❌ Content strategy test failed:', error);
+    throw error;
+  }
+})
+
 test('DrissionPage Detector', async () => {
     await page.goto("https://web.archive.org/web/20240913054632/https://drissionpage.pages.dev/", { timeout: 60000 });
     await page.realClick("#detector")
@@ -210,3 +330,7 @@ test('Pixelscan Fingerprint Check', async () => {
     assert.strictEqual(result, true, "Pixelscan Fingerprint Check failed! Browser fingerprint is inconsistent or masking was detected.");
 })
 
+
+
+
+

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: {}
 }
 
@@ -30,6 +30,126 @@ test.after(async () => {
     }
 });
 
+test('Human-like Move & Click', async () => {
+    await page.goto("https://www.google.com", { timeout: 40000 });
+    const selector = 'textarea[name="q"], input[name="q"]';
+    await page.realCursor.move(selector);
+    await page.realClick(selector);
+    assert.ok(true);
+})
+
+test('Human-like Typing', async () => {
+    await page.goto("https://www.google.com", { timeout: 40000 });
+    const selector = 'textarea[name="q"], input[name="q"]';
+    await page.realCursor.move(selector);
+    await page.realClick(selector);
+    await page.type(selector, 'Real Browser MCP Server', { delay: 150 });
+    const val = await page.inputValue(selector);
+    assert.strictEqual(val, 'Real Browser MCP Server');
+})
+
+test('Human-like Scrolling', async () => {
+    await page.goto("https://www.google.com/search?q=Real+Browser+MCP+Server", { timeout: 40000, waitUntil: 'domcontentloaded' });
+    await new Promise(r => setTimeout(r, 2000));
+    
+    console.log('📜 Scrolling down smoothly and fast (400px)...');
+    await page.realScroll(400, 500);
+    await new Promise(r => setTimeout(r, 600));
+    
+    console.log('📜 Scrolling down smoothly and fast (300px)...');
+    await page.realScroll(300, 400);
+    await new Promise(r => setTimeout(r, 600));
+    
+    console.log('📜 Scrolling up smoothly and fast (-500px)...');
+    await page.realScroll(-500, 600);
+    await new Promise(r => setTimeout(r, 1000));
+    
+    assert.ok(true);
+})
+
+test('Form Automation Demonstration', async () => {
+  console.log('\n🎬 DEMO: Form Automation');
+  try {
+    await page.goto('https://httpbin.org/forms/post', { timeout: 30000 });
+    console.log('\n4️⃣ Filling out form...');
+    
+    // 1. Customer Name
+    await page.type('input[name="custname"]', 'John Doe', { delay: 100 });
+    console.log('✅ Customer Name filled');
+
+    // 2. Telephone
+    await page.type('input[name="custtel"]', '+1-555-0199', { delay: 100 });
+    console.log('✅ Telephone filled');
+
+    // 3. Email address
+    await page.type('input[name="custemail"]', 'john.doe@example.com', { delay: 100 });
+    console.log('✅ Email field filled');
+
+    // 4. Pizza Size (Radio Button)
+    await page.realClick('input[value="medium"]');
+    console.log('✅ Pizza Size selected (Medium)');
+
+    // 5. Pizza Toppings (Checkboxes)
+    await page.realClick('input[value="bacon"]');
+    await page.realClick('input[value="onion"]');
+    console.log('✅ Toppings selected (Bacon, Onion)');
+
+    // 6. Preferred Delivery Time
+    await page.type('input[name="delivery"]', '13:00', { delay: 100 });
+    console.log('✅ Delivery time filled');
+
+    // 7. Delivery Instructions (Comments)
+    await page.type('textarea[name="comments"]', 'Leave at the front door, please.', { delay: 100 });
+    console.log('✅ Delivery instructions filled');
+
+    // Wait 2 seconds for visual demonstration
+    await new Promise(resolve => setTimeout(resolve, 2000));
+
+    // 8. Submit Order
+    await page.realClick('form button');
+    console.log('✅ Form submitted successfully');
+    
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    console.log('\n🎉 FORM AUTOMATION COMPLETE!');
+  } catch (error) {
+    console.error('❌ Form automation test failed:', error);
+    throw error;
+  }
+})
+
+test('Content Strategy Demonstration', async () => {
+  console.log('\n🎬 DEMO: Content Analysis & Token Management');
+  console.log('👀 Watch browser analyze content from different websites');
+  try {
+    const testSites = [
+      { url: 'https://httpbin.org/html', description: 'Simple HTML page' },
+      { url: 'https://example.com', description: 'Minimal content page' }
+    ];
+
+    for (const [index, site] of testSites.entries()) {
+      console.log(`\n${index + 2}️⃣ Testing ${site.description}: ${site.url}`);
+      await page.goto(site.url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+      await new Promise(resolve => setTimeout(resolve, 2000));
+
+      console.log(`   📄 Getting HTML content...`);
+      const htmlContent = await page.content();
+      console.log(`   ✅ HTML analyzed: ${htmlContent.length} characters`);
+      
+      console.log(`   📝 Getting text content...`);
+      const textContent = await page.evaluate(() => document.body.innerText);
+      console.log(`   ✅ Text analyzed: ${textContent.length} characters`);
+      
+      assert.ok(htmlContent.length > 0);
+      assert.ok(textContent.length > 0);
+      await new Promise(resolve => setTimeout(resolve, 1500));
+    }
+    console.log('\n🎉 CONTENT ANALYSIS COMPLETE!');
+  } catch (error) {
+    console.error('❌ Content strategy test failed:', error);
+    throw error;
+  }
+})
+
 test('DrissionPage Detector', async () => {
     await page.goto("https://web.archive.org/web/20240913054632/https://drissionpage.pages.dev/", { timeout: 70000 });
     await page.realClick("#detector")
@@ -173,3 +293,7 @@ test('Pixelscan Fingerprint Check', async () => {
 
     assert.strictEqual(result, true, "Pixelscan Fingerprint Check failed! Browser fingerprint is inconsistent or masking was detected.");
 })
+
+
+
+