real-browser-mcp-server 1.1.6 → 1.1.8

package/README.md

@@ -139,9 +139,9 @@ Configure the server in your `opencode.jsonc` or standard MCP settings configura
 
 ---
 
-## 🌐 Complete MCP Tool Reference (25 Tools)
+## 🌐 Complete MCP Tool Reference (23 Tools)
 
-The server exposes 25 highly optimized tools categorized into functional units:
+The server exposes 23 highly optimized tools categorized into functional units:
 
 ### 🌐 Browser & Session
 | Tool Name | Description | Parameters |
@@ -185,11 +185,7 @@ The server exposes 25 highly optimized tools categorized into functional units:
 | `wait` | Smart delay with AI prediction or static timeout. | `duration` (number) |
 | `progress_tracker` | Track running automation progress with AI-estimated remaining times. | `step` (string), `percentage` (number) |
 
-### 📸 Capture
-| Tool Name | Description | Parameters |
-|:---|:---|:---|
-| `screenshot` | Capture viewport, full page, or a specific element. Returns the image to the AI agent (base64) and can save to a file. | `fullPage` (boolean), `selector` (string), `format` (png/jpeg), `path` (string) |
-| `save_as_pdf` | Save the current page as a PDF via Chromium print-to-PDF (headless mode only). | `path` (string), `format` (string), `landscape` (boolean) |
+
 
 ### 👁️ AI Vision (Eyes)
 | Tool Name | Description | Parameters |
@@ -305,7 +301,7 @@ Run these scripts from the project root directory:
 | `npm run dev` | Alias to start the MCP server. |
 | `npm run mcp` | Start the MCP server. |
 | `npm run mcp:verbose` | Start the MCP server with verbose logging on `stderr`. |
-| `npm run list` | Clean list of all 25 tools with emojis and categories. |
+| `npm run list` | Clean list of all 23 tools with emojis and categories. |
 | `npm run build` | Validate workspace structure and confirm library status. |
 | `npm test` | Execute the full test suite (CJS & ESM). |
 | `npm run cjs_test` | Run CommonJS test scripts. |

package/dist/lib/cjs/index.js

@@ -0,0 +1,384 @@
+"use strict";
+// @ts-nocheck
+const { chromium } = require("patchright");
+const { createCursor } = require("ghost-cursor-patchright");
+const { PlaywrightBlocker } = require("@ghostery/adblocker-playwright");
+const { pageController } = require("./module/pageController.js");
+const fs = require('fs');
+const path = require('path');
+let adBlockerInstance = null;
+let adBlockerPromise = null;
+function getAdBlocker() {
+    if (!adBlockerPromise) {
+        const cachePath = path.join(__dirname, 'adblocker.bin');
+        adBlockerPromise = PlaywrightBlocker.fromPrebuiltAdsAndTracking(fetch, {
+            path: cachePath,
+            read: fs.promises.readFile,
+            write: fs.promises.writeFile,
+        }).then(blocker => {
+            adBlockerInstance = blocker;
+            return blocker;
+        }).catch(err => {
+            console.error('[adblocker] Failed to initialize adblocker:', err.message);
+            return null;
+        });
+    }
+    return adBlockerPromise;
+}
+function loadEnvFile() {
+    const envPaths = [
+        path.join(process.cwd(), '.env'),
+    ];
+    let currentDir = process.cwd();
+    for (let i = 0; i < 5; i++) {
+        const envPath = path.join(currentDir, '.env');
+        if (fs.existsSync(envPath) && !envPaths.includes(envPath)) {
+            envPaths.push(envPath);
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir)
+            break;
+        currentDir = parentDir;
+    }
+    for (const envPath of envPaths) {
+        try {
+            if (fs.existsSync(envPath)) {
+                const envContent = fs.readFileSync(envPath, 'utf-8');
+                envContent.split('\n').forEach(line => {
+                    const trimmed = line.trim();
+                    if (trimmed && !trimmed.startsWith('#')) {
+                        const [key, ...valueParts] = trimmed.split('=');
+                        const value = valueParts.join('=').replace(/^["']|["']$/g, '');
+                        if (key && !process.env[key]) {
+                            process.env[key] = value;
+                        }
+                    }
+                });
+                break;
+            }
+        }
+        catch (error) {
+            // Silently ignore .env loading errors
+        }
+    }
+}
+loadEnvFile();
+function getDefaultHeadless() {
+    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) {
+    if (page._setupApplied)
+        return page;
+    page._setupApplied = true;
+    // Enable ad blocker
+    if (adBlockerInstance) {
+        adBlockerInstance.enableBlockingInPage(page).catch(() => { });
+    }
+    else {
+        getAdBlocker().then(blocker => {
+            if (blocker) {
+                blocker.enableBlockingInPage(page).catch(() => { });
+            }
+        });
+    }
+    // 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);
+        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 (_) { }
+                }
+            }
+        };
+        page.realClick = async (selector, options = {}) => {
+            try {
+                await cursor.actions.click({ target: selector, ...options });
+            }
+            catch (e) {
+                // 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 (_) { }
+                }
+            };
+        }
+    }
+    return page;
+}
+function getBraveExecutablePath() {
+    if (process.env.BRAVE_PATH && fs.existsSync(process.env.BRAVE_PATH)) {
+        return process.env.BRAVE_PATH;
+    }
+    const platform = process.platform;
+    const { execSync } = require('child_process');
+    // 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 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) { }
+        }
+        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;
+            }
+        }
+        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) { }
+    }
+    // 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'
+        ];
+    }
+    for (const p of paths) {
+        if (p && fs.existsSync(p)) {
+            return p;
+        }
+    }
+    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
+    }
+}
+async function connect({ args = [], headless = getDefaultHeadless(), proxy = {}, turnstile = false, executablePath = undefined, } = {}) {
+    let playwrightProxy = undefined;
+    if (proxy && proxy.host && proxy.port) {
+        playwrightProxy = {
+            server: `${proxy.host}:${proxy.port}`
+        };
+        if (proxy.username && proxy.password) {
+            playwrightProxy.username = proxy.username;
+            playwrightProxy.password = proxy.password;
+        }
+    }
+    // 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',
+        ...args
+    ];
+    // 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');
+        }
+    }
+    const browser = await chromium.launch({
+        headless: launchHeadless,
+        args: chromiumArgs,
+        proxy: playwrightProxy,
+        ...(executablePath ? { executablePath } : {}),
+    });
+    // Ensure ad blocker is ready
+    await getAdBlocker();
+    const context = await browser.newContext({
+        viewport: null,
+    });
+    let page = await context.newPage();
+    await applyUserAgentOverride(page, modifiedUa, userAgentMetadata);
+    setupRealPage(browser, page);
+    page = await pageController({
+        browser,
+        page,
+        proxy,
+        turnstile,
+    });
+    context.on('page', async (newPage) => {
+        await applyUserAgentOverride(newPage, modifiedUa, userAgentMetadata);
+        setupRealPage(browser, newPage);
+        await pageController({
+            browser,
+            page: newPage,
+            proxy,
+            turnstile,
+        });
+    });
+    return {
+        browser,
+        page,
+    };
+}
+module.exports = { connect };

package/{lib → dist/lib}/cjs/module/pageController.js

@@ -1,15 +1,14 @@
+"use strict";
+// @ts-nocheck
 const { checkTurnstile } = require('./turnstile.js');
-
 async function pageController({ browser, page, proxy, turnstile }) {
-    if (page._pageControllerApplied) return page;
+    if (page._pageControllerApplied)
+        return page;
     page._pageControllerApplied = true;
-
     let solveStatus = turnstile;
-
     page.on('close', () => {
         solveStatus = false;
     });
-
     async function turnstileSolver() {
         while (solveStatus) {
             await checkTurnstile({ page }).catch(() => { });
@@ -17,34 +16,35 @@ async function pageController({ browser, page, proxy, turnstile }) {
         }
         return;
     }
-
     if (solveStatus) {
         turnstileSolver();
     }
-
     // === 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.
     /*
@@ -63,8 +63,6 @@ async function pageController({ browser, page, proxy, turnstile }) {
         }
     });
     */
-
     return page;
 }
-
-module.exports = { pageController };
+module.exports = { pageController };

package/{lib → dist/lib}/cjs/module/turnstile.js

@@ -1,7 +1,16 @@
+"use strict";
+// @ts-nocheck
 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 => {
@@ -11,9 +20,9 @@ const checkTurnstile = async ({ page }) => {
                         if (itemCss.margin == "0px" && itemCss.padding == "0px" && itemCoordinates.width > 290 && itemCoordinates.width <= 310 && !item.querySelector('*')) {
                             coordinates.push({ x: itemCoordinates.x, y: item.getBoundingClientRect().y, w: item.getBoundingClientRect().width, h: item.getBoundingClientRect().height });
                         }
-                    } catch (err) { }
+                    }
+                    catch (err) { }
                 });
-
                 if (coordinates.length <= 0) {
                     document.querySelectorAll('div').forEach(item => {
                         try {
@@ -21,28 +30,29 @@ const checkTurnstile = async ({ page }) => {
                             if (itemCoordinates.width > 290 && itemCoordinates.width <= 310 && !item.querySelector('*')) {
                                 coordinates.push({ x: itemCoordinates.x, y: item.getBoundingClientRect().y, w: item.getBoundingClientRect().width, h: item.getBoundingClientRect().height });
                             }
-                        } catch (err) { }
+                        }
+                        catch (err) { }
                     });
                 }
                 return coordinates;
             });
-
             for (const item of coordinates) {
                 try {
                     let x = item.x + 30;
                     let y = item.y + item.h / 2;
                     await page.mouse.click(x, y);
-                } catch (err) { }
+                }
+                catch (err) { }
             }
             return true;
         }
-
         for (const element of elements) {
             try {
                 // Get the parent element bounding box
                 const box = await element.evaluate(el => {
                     const parent = el.parentElement;
-                    if (!parent) return null;
+                    if (!parent)
+                        return null;
                     const rect = parent.getBoundingClientRect();
                     return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
                 });
@@ -51,12 +61,13 @@ const checkTurnstile = async ({ page }) => {
                     let y = box.y + box.height / 2;
                     await page.mouse.click(x, y);
                 }
-            } catch (err) { }
+            }
+            catch (err) { }
         }
         return true;
-    } catch (err) {
+    }
+    catch (err) {
         return false;
     }
-}
-
-module.exports = { checkTurnstile };
+};
+module.exports = { checkTurnstile };