real-browser-mcp-server 1.1.2 → 1.1.4

package/.github/workflows/publish.yml

@@ -82,11 +82,37 @@ jobs:
 
           echo "📈 Selected increment type: $INCREMENT_TYPE"
           
+          # Calculate the new version before bumping
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          echo "📦 Current version: $CURRENT_VERSION"
+          
+          # Calculate expected new version
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+          case "$INCREMENT_TYPE" in
+            major) NEW_VERSION="$((MAJOR + 1)).0.0" ;;
+            minor) NEW_VERSION="$MAJOR.$((MINOR + 1)).0" ;;
+            patch) NEW_VERSION="$MAJOR.$MINOR.$((PATCH + 1))" ;;
+          esac
+          echo "🔮 Expected new version: $NEW_VERSION"
+          
+          # Check if tag already exists locally and remove it
+          if git tag -l "v$NEW_VERSION" | grep -q "v$NEW_VERSION"; then
+            echo "⚠️ Tag v$NEW_VERSION exists locally, removing..."
+            git tag -d "v$NEW_VERSION"
+          fi
+          
+          # Check if tag exists on remote and delete it
+          if git ls-remote --tags origin "v$NEW_VERSION" | grep -q "v$NEW_VERSION"; then
+            echo "⚠️ Tag v$NEW_VERSION exists on remote, deleting..."
+            git push origin --delete "v$NEW_VERSION" || true
+          fi
+          
           # Bump version, commit changes and create tag
           npm version $INCREMENT_TYPE -m "🔖 Release: v%s [skip ci]"
           
-          # Capture new version for subsequent steps
+          # Capture actual new version for subsequent steps
           NEW_VERSION=$(node -p "require('./package.json').version")
+          echo "✅ New version: $NEW_VERSION"
           echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
           echo "version=v$NEW_VERSION" >> $GITHUB_OUTPUT
 

package/README.md

@@ -80,14 +80,17 @@ Add the server entry to your global MCP settings file (typically found at `%APPD
 {
   "mcpServers": {
     "real-browser-mcp-server": {
-      "command": "node",
+      "type": "stdio",
+      "command": "C:/Program Files/nodejs/node.exe",
       "args": [
         "c:/Users/Admin/Desktop/Software/Real-Browser-Mcp-Server/src/index.js"
       ],
       "env": {
         "HEADLESS": "false"
       },
-      "disabled": false
+      "disabled": false,
+      "autoApprove": [],
+      "timeout": 120
     }
   }
 }
@@ -136,9 +139,9 @@ Configure the server in your `opencode.jsonc` or standard MCP settings configura
 
 ---
 
-## 🌐 Complete MCP Tool Reference (22 Tools)
+## 🌐 Complete MCP Tool Reference (25 Tools)
 
-The server exposes 22 highly optimized tools categorized into functional units:
+The server exposes 25 highly optimized tools categorized into functional units:
 
 ### 🌐 Browser & Session
 | Tool Name | Description | Parameters |
@@ -182,6 +185,17 @@ The server exposes 22 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 |
+|:---|:---|:---|
+| `see_page` | Lets the AI **visually SEE** the page like human eyes: returns the actual screenshot image to the agent **plus** a "visual map" of every visible interactive element (button/link/input) with its on-screen position, text label, and a click-ready selector. Use it to look before deciding where to click/type. | `fullPage` (boolean), `format` (png/jpeg), `includeElements` (boolean), `maxElements` (number) |
+
 ---
 
 ## 📈 Evasion Performance & Test Coverage
@@ -291,11 +305,12 @@ 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 22 tools with emojis and categories. |
+| `npm run list` | Clean list of all 25 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. |
 | `npm run esm_test` | Run ECMAScript Module test scripts. |
+| `npm run mcp_test` | Fast, network-independent MCP smoke test (handshake + tool registry validation). |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "real-browser-mcp-server",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "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",
@@ -27,7 +27,8 @@
     "list": "node src/index.js --list",
     "test": "npm run cjs_test && npm run esm_test",
     "esm_test": "node ./test/esm/test.mjs",
-    "cjs_test": "node ./test/cjs/test.js"
+    "cjs_test": "node ./test/cjs/test.js",
+    "mcp_test": "node ./test/mcp/smoke-test.js"
   },
   "keywords": [
     "mcp-server",

package/src/ai/core.js

@@ -242,7 +242,8 @@ class AICore {
         return await this.smartType(page, action.target, action.text, { humanLike });
       
       case 'navigate':
-        await page.goto(action.url, { waitUntil: 'networkidle2' });
+        // Playwright/Patchright waitUntil: load|domcontentloaded|networkidle|commit
+        await page.goto(action.url, { waitUntil: 'networkidle' });
         return { success: true, url: action.url };
       
       case 'scroll':

package/src/ai/page-analyzer.js

@@ -1,13 +1,3 @@
-/**
- * AI Page Analyzer - Understand page structure and content
- * 
- * Analyzes page to identify:
- * - Interactive elements (buttons, links, inputs)
- * - Forms and form fields
- * - Navigation structure
- * - Main content areas
- * - Media elements
- */
 
 class PageAnalyzer {
   constructor() {
@@ -274,8 +264,9 @@ class PageAnalyzer {
 
     // Add screenshot if requested
     if (includeScreenshot) {
-      const screenshot = await page.screenshot({ encoding: 'base64', type: 'jpeg', quality: 50 });
-      analysis.screenshot = screenshot;
+      // Playwright/Patchright returns a Buffer; convert to base64 ourselves
+      const buf = await page.screenshot({ type: 'jpeg', quality: 50 });
+      analysis.screenshot = Buffer.from(buf).toString('base64');
     }
 
     return analysis;

package/src/mcp/handlers.js

@@ -1,13 +1,3 @@
-/**
- * Brave Real Browser MCP Server - Tool Handlers
- * 
- * Implementation of all 23 browser automation tools (optimized from 28)
- * 
- * Environment Variables:
- *   HEADLESS=true   - Run browser in headless mode
- *   HEADLESS=false  - Run browser in GUI mode (visible)
- */
-
 const path = require('path');
 const fs = require('fs');
 const crypto = require('crypto');
@@ -106,6 +96,16 @@ function requireBrowser() {
   return { browser: browserInstance, page: pageInstance };
 }
 
+/**
+ * Validate the waitUntil value for Playwright/Patchright.
+ * Only these states are supported: load | domcontentloaded | networkidle | commit.
+ * Any unsupported value safely falls back to 'networkidle'.
+ */
+function resolveWaitUntil(value) {
+  const allowed = ['load', 'domcontentloaded', 'networkidle', 'commit'];
+  return allowed.includes(value) ? value : 'networkidle';
+}
+
 /**
  * DECODER UTILITIES - URL, Base64, AES Decryption
  */
@@ -636,7 +636,7 @@ const handlers = {
       };
     });
 
-    const pid = browserInstance.process()?.pid;
+    const pid = (typeof browserInstance.process === 'function') ? browserInstance.process()?.pid : null;
 
     notifyProgress('browser_init', 'completed', `Browser started (PID: ${pid})`, {
       headless,
@@ -656,7 +656,9 @@ const handlers = {
   // 2. Navigate (ENHANCED - handles context destroyed errors, retries)
   async navigate(params) {
     const { page } = requireBrowser();
-    const { url, waitUntil = 'networkidle2', timeout = 30000, retries = 2 } = params;
+    let { url, waitUntil = 'networkidle', timeout = 30000, retries = 2 } = params;
+    // Playwright/Patchright wait states: load | domcontentloaded | networkidle | commit
+    waitUntil = resolveWaitUntil(waitUntil);
 
     notifyProgress('navigate', 'started', `Navigating to: ${url}`);
 
@@ -766,7 +768,7 @@ const handlers = {
       const url = rawHttpUrl || page.url();
       notifyProgress('get_content', 'in_progress', `Fetching raw HTTP (no JS) from: ${url}`);
       try {
-        const cookies = await page.cookies(url);
+        const cookies = await page.context().cookies(url);
         const cookieStr = cookies.map(c => `${c.name}=${c.value}`).join('; ');
         const response = await fetch(url, {
           headers: {
@@ -797,7 +799,59 @@ const handlers = {
 
     let content;
 
-    if (selector) {
+    // === markdown: real HTML→Markdown conversion (no external deps) ===
+    if (format === 'markdown') {
+      if (selector) {
+        const exists = await page.$(selector);
+        if (!exists) {
+          notifyProgress('get_content', 'error', `Element not found: ${selector}`);
+          return { success: false, error: `Element not found: ${selector}` };
+        }
+      }
+      content = await page.evaluate((sel) => {
+        const root = sel ? document.querySelector(sel) : document.body;
+        if (!root) return '';
+        const skip = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'IFRAME', 'SVG', 'CANVAS']);
+        const inline = (node) => {
+          let out = '';
+          node.childNodes.forEach(c => {
+            if (c.nodeType === 3) { out += c.textContent.replace(/\s+/g, ' '); return; }
+            if (c.nodeType !== 1 || skip.has(c.tagName)) return;
+            const t = c.tagName;
+            if (t === 'A') { const h = c.getAttribute('href') || ''; const x = inline(c).trim(); out += h ? `[${x}](${h})` : x; }
+            else if (t === 'STRONG' || t === 'B') out += `**${inline(c).trim()}**`;
+            else if (t === 'EM' || t === 'I') out += `*${inline(c).trim()}*`;
+            else if (t === 'CODE') out += '`' + c.textContent.trim() + '`';
+            else if (t === 'IMG') { const a = c.getAttribute('alt') || ''; const s = c.getAttribute('src') || ''; if (s) out += `![${a}](${s})`; }
+            else if (t === 'BR') out += '\n';
+            else out += inline(c);
+          });
+          return out;
+        };
+        const lines = [];
+        const walk = (node) => {
+          node.childNodes.forEach(c => {
+            if (c.nodeType === 3) { const x = c.textContent.trim(); if (x) lines.push(x); return; }
+            if (c.nodeType !== 1 || skip.has(c.tagName)) return;
+            const t = c.tagName;
+            if (/^H[1-6]$/.test(t)) lines.push('\n' + '#'.repeat(+t[1]) + ' ' + inline(c).trim() + '\n');
+            else if (t === 'P') { const x = inline(c).trim(); if (x) lines.push(x + '\n'); }
+            else if (t === 'UL' || t === 'OL') {
+              let i = 1;
+              c.querySelectorAll(':scope > li').forEach(li => lines.push((t === 'OL' ? (i++) + '. ' : '- ') + inline(li).trim()));
+              lines.push('');
+            }
+            else if (t === 'BLOCKQUOTE') lines.push('> ' + inline(c).trim() + '\n');
+            else if (t === 'PRE') lines.push('```\n' + c.textContent.trim() + '\n```\n');
+            else if (t === 'HR') lines.push('\n---\n');
+            else if (['A', 'STRONG', 'B', 'EM', 'I', 'CODE', 'IMG', 'SPAN', 'LABEL'].includes(t)) { const x = inline(c).trim(); if (x) lines.push(x); }
+            else walk(c);
+          });
+        };
+        walk(root);
+        return lines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+      }, selector || null);
+    } else if (selector) {
       const element = await page.$(selector);
       if (!element) {
         notifyProgress('get_content', 'error', `Element not found: ${selector}`);
@@ -812,11 +866,6 @@ const handlers = {
     } else {
       if (format === 'html') {
         content = await page.content();
-      } else if (format === 'markdown') {
-        content = await page.evaluate(() => {
-          const body = document.body.innerText;
-          return body;
-        });
       } else {
         content = await page.evaluate(() => document.body.innerText);
       }
@@ -847,7 +896,7 @@ const handlers = {
         await page.waitForNavigation({ timeout });
         break;
       case 'networkidle':
-        await page.waitForNetworkIdle({ timeout });
+        await page.waitForLoadState('networkidle', { timeout });
         break;
       case 'timeout':
       default:
@@ -1404,7 +1453,9 @@ const handlers = {
         notifyProgress('browser_close', 'progress', 'Browser closed gracefully');
       } catch (e) {
         if (force) {
-          browserInstance.process()?.kill('SIGKILL');
+          if (typeof browserInstance.process === 'function') {
+            browserInstance.process()?.kill('SIGKILL');
+          }
           notifyProgress('browser_close', 'progress', 'Browser force killed');
         }
       }
@@ -1640,12 +1691,12 @@ const handlers = {
           try {
             const captchaEl = await targetFrame.$(detectedCaptchaSelector);
             if (captchaEl) {
-              captchaImageBase64 = await captchaEl.screenshot({ encoding: 'base64' });
+              captchaImageBase64 = (await captchaEl.screenshot()).toString('base64');
             }
           } catch(e) {}
 
           // Take full context screenshot for host LLM fallback
-          const screenshotBase64 = await targetHandle.screenshot({ encoding: 'base64' });
+          const screenshotBase64 = (await targetHandle.screenshot()).toString('base64');
 
           // ═══════════════════════════════════════════════════════════
           // STEP A: Server-Side Vision API (if aiMode enabled)
@@ -2104,7 +2155,7 @@ const handlers = {
         }
       }
     } else if (xpath) {
-      const handles = await page.$x(xpath);
+      const handles = await page.$$(`xpath=${xpath}`);
       elements = await Promise.all(handles.map(h => h.evaluate(el => ({
         tag: el.tagName,
         text: el.textContent?.substring(0, 100)
@@ -2198,7 +2249,7 @@ const handlers = {
     page.on('framenavigated', frameNavigatedHandler);
 
     try {
-      await page.goto(url, { waitUntil: 'networkidle2', timeout });
+      await page.goto(url, { waitUntil: 'networkidle', timeout });
 
       // If followJS is enabled, wait a bit and check for meta refreshes and JS redirects
       if (followJS) {
@@ -2938,29 +2989,51 @@ const handlers = {
 
     notifyProgress('cookie_manager', 'started', `Cookie action: ${action}`);
 
+    // Playwright/Patchright: cookies are managed via the BrowserContext, not the page
+    const context = page.context();
+
     switch (action) {
-      case 'get':
-        const cookies = await page.cookies();
+      case 'get': {
+        const cookies = await context.cookies();
         notifyProgress('cookie_manager', 'completed', `Retrieved ${cookies.length} cookies`);
         return { success: true, cookies: name ? cookies.filter(c => c.name === name) : cookies };
+      }
 
-      case 'set':
-        await page.setCookie({ name, value, domain: domain || new URL(page.url()).hostname, expires });
+      case 'set': {
+        await context.addCookies([{
+          name,
+          value,
+          domain: domain || new URL(page.url()).hostname,
+          path: '/',
+          ...(expires ? { expires } : {})
+        }]);
         notifyProgress('cookie_manager', 'completed', `Cookie set: ${name}`);
         return { success: true, message: `Cookie ${name} set` };
+      }
 
-      case 'delete':
-        const toDelete = await page.cookies();
-        const filtered = name ? toDelete.filter(c => c.name === name) : toDelete;
-        await page.deleteCookie(...filtered);
-        notifyProgress('cookie_manager', 'completed', `Deleted ${filtered.length} cookie(s)`);
-        return { success: true, message: `Deleted ${filtered.length} cookie(s)` };
+      case 'delete': {
+        // Playwright has no per-cookie delete: clear all, then re-add the ones we keep
+        const toDelete = await context.cookies();
+        const remaining = name ? toDelete.filter(c => c.name !== name) : [];
+        const removedCount = toDelete.length - remaining.length;
+        await context.clearCookies();
+        if (remaining.length) {
+          await context.addCookies(remaining.map(c => ({
+            name: c.name, value: c.value, domain: c.domain, path: c.path,
+            ...(c.expires && c.expires > 0 ? { expires: c.expires } : {}),
+            httpOnly: c.httpOnly, secure: c.secure, sameSite: c.sameSite
+          })));
+        }
+        notifyProgress('cookie_manager', 'completed', `Deleted ${removedCount} cookie(s)`);
+        return { success: true, message: `Deleted ${removedCount} cookie(s)` };
+      }
 
-      case 'clear':
-        const allCookies = await page.cookies();
-        await page.deleteCookie(...allCookies);
+      case 'clear': {
+        const allCookies = await context.cookies();
+        await context.clearCookies();
         notifyProgress('cookie_manager', 'completed', `Cleared ${allCookies.length} cookies`);
         return { success: true, message: `Cleared ${allCookies.length} cookies` };
+      }
     }
 
     return { success: false, error: 'Invalid action' };
@@ -2977,8 +3050,8 @@ const handlers = {
       fs.mkdirSync(directory, { recursive: true });
     }
 
-    const response = await page.goto(url, { waitUntil: 'networkidle2' });
-    const buffer = await response.buffer();
+    const response = await page.goto(url, { waitUntil: 'networkidle' });
+    const buffer = await response.body();
 
     const outputFilename = filename || path.basename(new URL(url).pathname) || 'download';
     const outputPath = path.join(directory, outputFilename);
@@ -3516,7 +3589,7 @@ const handlers = {
           const inputType = await input.evaluate(el => el.type);
 
           if (tagName === 'select') {
-            await page.select(inputSelector, value);
+            await page.selectOption(inputSelector, value);
           } else if (inputType === 'checkbox' || inputType === 'radio') {
             if (value) await input.click();
           } else {
@@ -3969,8 +4042,8 @@ const handlers = {
             notifyProgress('media_extractor', 'progress', `Processing ${i + 1}/${urls.length}: ${url}`);
 
             // Navigate to URL
-            await page.goto(url, { waitUntil: 'networkidle2', timeout: 30000 });
-            await page.waitForTimeout(2000); // Wait for media to load
+            await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
+            await new Promise(r => setTimeout(r, 2000)); // Wait for media to load
 
             // Extract streams
             const streams = await extractStreamsFromContext(page, 'main');
@@ -4871,6 +4944,241 @@ const handlers = {
       filledFields,
       message: `Form filled: ${filledFields.join(', ')}`
     };
+  },
+
+  // 23. Screenshot - capture viewport / full page / element (returns image to AI)
+  async screenshot(params = {}) {
+    const { page } = requireBrowser();
+    const {
+      fullPage = false,
+      selector,
+      format = 'png',
+      quality,
+      path: savePath,
+      returnBase64 = true,
+      omitBackground = false
+    } = params;
+
+    notifyProgress('screenshot', 'started',
+      `Capturing ${selector ? 'element' : (fullPage ? 'full page' : 'viewport')} screenshot`);
+
+    const opts = { type: format, fullPage: selector ? false : fullPage };
+    if (format === 'jpeg' && typeof quality === 'number') opts.quality = quality;
+    if (format === 'png' && omitBackground) opts.omitBackground = true;
+
+    let buffer;
+    if (selector) {
+      const element = await page.$(selector);
+      if (!element) {
+        notifyProgress('screenshot', 'error', `Element not found: ${selector}`);
+        return { success: false, error: `Element not found: ${selector}` };
+      }
+      buffer = await element.screenshot(opts);
+    } else {
+      buffer = await page.screenshot(opts);
+    }
+
+    let savedTo = null;
+    if (savePath) {
+      const dir = path.dirname(savePath);
+      if (dir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(savePath, buffer);
+      savedTo = savePath;
+    }
+
+    notifyProgress('screenshot', 'completed',
+      `Screenshot captured (${buffer.length} bytes)${savedTo ? ' → ' + savedTo : ''}`);
+
+    const meta = { success: true, format, bytes: buffer.length, savedTo, url: page.url() };
+
+    if (returnBase64) {
+      const base64 = Buffer.from(buffer).toString('base64');
+      // mcpContent is returned directly to the AI agent (image + text summary)
+      meta.mcpContent = [
+        { type: 'image', data: base64, mimeType: format === 'jpeg' ? 'image/jpeg' : 'image/png' },
+        { type: 'text', text: JSON.stringify({ success: true, format, bytes: buffer.length, savedTo, url: page.url() }, null, 2) }
+      ];
+    }
+
+    return meta;
+  },
+
+  // 24. Save as PDF - Chromium print-to-PDF (headless mode only)
+  async save_as_pdf(params = {}) {
+    const { page } = requireBrowser();
+    const {
+      path: savePath = './downloads/page.pdf',
+      format = 'A4',
+      landscape = false,
+      printBackground = true
+    } = params;
+
+    notifyProgress('save_as_pdf', 'started', `Saving page as PDF: ${savePath}`);
+
+    const dir = path.dirname(savePath);
+    if (dir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    try {
+      await page.pdf({ path: savePath, format, landscape, printBackground });
+    } catch (e) {
+      notifyProgress('save_as_pdf', 'error', e.message);
+      return {
+        success: false,
+        error: `PDF generation failed (page.pdf() works only in headless mode): ${e.message}`
+      };
+    }
+
+    const stats = fs.existsSync(savePath) ? fs.statSync(savePath) : null;
+    notifyProgress('save_as_pdf', 'completed', `PDF saved: ${savePath}`);
+
+    return {
+      success: true,
+      savedTo: savePath,
+      bytes: stats ? stats.size : null,
+      url: page.url()
+    };
+  },
+
+  // 25. See Page (AI Vision — "eyes": screenshot + visual map of interactive elements)
+  async see_page(params = {}) {
+    const { page } = requireBrowser();
+    const {
+      fullPage = false,
+      format = 'jpeg',
+      quality = 70,
+      includeElements = true,
+      maxElements = 60,
+      path: savePath
+    } = params;
+
+    notifyProgress('see_page', 'started', `👁️ Looking at the page (${fullPage ? 'full page' : 'viewport'})...`);
+
+    // 1. Capture what the page looks like (the "eyes")
+    const shotOpts = { type: format, fullPage };
+    if (format === 'jpeg' && typeof quality === 'number') shotOpts.quality = quality;
+
+    let buffer;
+    try {
+      buffer = await page.screenshot(shotOpts);
+    } catch (e) {
+      return { success: false, error: `Vision capture failed: ${e.message}` };
+    }
+
+    // 2. Build a "visual map" of visible interactive elements (what a human can act on)
+    let elements = [];
+    let pageInfo = {};
+    if (includeElements) {
+      const data = await page.evaluate((maxEls) => {
+        const out = [];
+        const seen = new Set();
+        const sel = 'a[href], button, input, select, textarea, [role="button"], [role="link"], [onclick], [tabindex]';
+        const nodes = document.querySelectorAll(sel);
+
+        const cssPath = (el) => {
+          if (el.id) return `#${CSS.escape(el.id)}`;
+          if (el.name) return `${el.tagName.toLowerCase()}[name="${el.name}"]`;
+          const parts = [];
+          let node = el;
+          while (node && node.nodeType === 1 && parts.length < 4) {
+            let part = node.tagName.toLowerCase();
+            if (node.classList.length) {
+              const cls = Array.from(node.classList).slice(0, 2).map(c => '.' + CSS.escape(c)).join('');
+              part += cls;
+            }
+            const parent = node.parentElement;
+            if (parent) {
+              const sibs = Array.from(parent.children).filter(c => c.tagName === node.tagName);
+              if (sibs.length > 1) part += `:nth-of-type(${sibs.indexOf(node) + 1})`;
+            }
+            parts.unshift(part);
+            node = node.parentElement;
+          }
+          return parts.join(' > ');
+        };
+
+        for (const el of nodes) {
+          if (out.length >= maxEls) break;
+          const rect = el.getBoundingClientRect();
+          // Only elements actually visible on screen
+          if (rect.width < 2 || rect.height < 2) continue;
+          const style = window.getComputedStyle(el);
+          if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') continue;
+          if (rect.bottom < 0 || rect.right < 0 || rect.top > window.innerHeight || rect.left > window.innerWidth) {
+            // outside current viewport — skip (we report what is seen)
+            continue;
+          }
+
+          const tag = el.tagName.toLowerCase();
+          let label = (el.innerText || el.value || el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.getAttribute('title') || el.getAttribute('alt') || '').trim().replace(/\s+/g, ' ').slice(0, 80);
+          let kind = tag;
+          if (tag === 'a') kind = 'link';
+          else if (tag === 'button' || el.getAttribute('role') === 'button') kind = 'button';
+          else if (tag === 'input') kind = `input:${el.type || 'text'}`;
+          else if (tag === 'select') kind = 'select';
+          else if (tag === 'textarea') kind = 'textarea';
+
+          const selector = cssPath(el);
+          if (seen.has(selector + '|' + label)) continue;
+          seen.add(selector + '|' + label);
+
+          out.push({
+            kind,
+            text: label,
+            selector,
+            href: tag === 'a' ? el.href : undefined,
+            box: { x: Math.round(rect.x), y: Math.round(rect.y), w: Math.round(rect.width), h: Math.round(rect.height) }
+          });
+        }
+
+        return {
+          elements: out,
+          info: {
+            title: document.title,
+            url: location.href,
+            viewport: { width: window.innerWidth, height: window.innerHeight },
+            scrollY: Math.round(window.scrollY),
+            scrollHeight: document.body ? document.body.scrollHeight : 0
+          }
+        };
+      }, maxElements).catch(() => ({ elements: [], info: {} }));
+
+      elements = data.elements || [];
+      pageInfo = data.info || {};
+    }
+
+    // 3. Optionally save the image too
+    let savedTo = null;
+    if (savePath) {
+      const dir = path.dirname(savePath);
+      if (dir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(savePath, buffer);
+      savedTo = savePath;
+    }
+
+    notifyProgress('see_page', 'completed',
+      `👁️ Saw the page: ${elements.length} interactive elements visible${savedTo ? ' (saved ' + savedTo + ')' : ''}`);
+
+    const base64 = Buffer.from(buffer).toString('base64');
+    const summary = {
+      success: true,
+      url: pageInfo.url || page.url(),
+      title: pageInfo.title,
+      viewport: pageInfo.viewport,
+      scroll: { y: pageInfo.scrollY, pageHeight: pageInfo.scrollHeight },
+      visibleInteractiveElements: elements.length,
+      elements,
+      savedTo
+    };
+
+    // Return BOTH the actual image (so the AI literally "sees" it) and the visual map text
+    return {
+      success: true,
+      mcpContent: [
+        { type: 'image', data: base64, mimeType: format === 'jpeg' ? 'image/jpeg' : 'image/png' },
+        { type: 'text', text: JSON.stringify(summary, null, 2) }
+      ],
+      ...summary
+    };
   }
 };
 
@@ -4950,7 +5258,7 @@ async function aiEnhancedSelector(page, selector, operation, options = {}) {
  * AI Features automatically applied:
  * - Auto-healing: If selector fails, AI tries to find alternatives
  * - Smart retry: Failed operations are retried with AI assistance
- * - All 28 tools benefit from AI without any changes
+ * - All tools benefit from AI without any changes
  */
 async function executeTool(name, params = {}) {
   const handler = handlers[name];
@@ -5063,7 +5371,9 @@ async function cleanup() {
     try {
       await browserInstance.close();
     } catch (e) {
-      browserInstance.process()?.kill('SIGKILL');
+      if (typeof browserInstance.process === 'function') {
+        browserInstance.process()?.kill('SIGKILL');
+      }
     }
     browserInstance = null;
     pageInstance = null;

package/src/mcp/server.js

@@ -1,14 +1,3 @@
-/**
- * Brave Real Browser MCP Server
- * 
- * Model Context Protocol Server with STDIO Transport
- * Supports: Claude, Cursor, Copilot, and other MCP-compatible AI assistants
- */
-
-// CRITICAL: Redirect ALL console.log to STDERR before ANY imports
-// MCP uses STDIO transport — STDOUT must contain ONLY JSON-RPC messages.
-// Any console.log from this code or ANY dependency (playwright, blocker, etc.)
-// will corrupt the JSON-RPC stream and cause parsing errors.
 const _originalConsoleLog = console.log;
 console.log = function (...args) {
   console.error(...args);
@@ -26,6 +15,14 @@ const {
 const { TOOLS } = require('./tools.js');
 const { executeTool, cleanup } = require('./handlers.js');
 
+// Single source of truth: read version from package.json (avoids version drift)
+let PKG_VERSION = '0.0.0';
+try {
+  PKG_VERSION = require('../../package.json').version || PKG_VERSION;
+} catch (e) {
+  console.error('⚠️  Could not read version from package.json:', e.message);
+}
+
 /**
  * Create and configure MCP Server
  */
@@ -33,7 +30,7 @@ function createServer() {
   const server = new Server(
     {
       name: 'real-browser-mcp-server',
-      version: '2.48.36',
+      version: PKG_VERSION,
     },
     {
       capabilities: {

package/src/shared/tools.js

@@ -1,21 +1,3 @@
-/**
- * Brave Real Browser MCP Server - Shared Tool Definitions
- * 
- * OPTIMIZED: 22 tools (merged from 28)
- * 
- * Merges Applied:
- * - iframe_handler + stream_extractor + player_api_hook → media_extractor
- * - get_content + js_scrape → get_content (enhanced)
- * - search_regex + extract_json + scrape_meta_tags → extract_data
- * - solve_captcha + form_automator → solve_captcha (enhanced)
- * 
- * New Features:
- * - URL/Base64/AES Decoders built into media_extractor
- * - AI Auto-Healing Selectors
- * - Smart Retry Mechanisms
- * - Batch Operations
- */
-
 const TOOLS = [
   // 1. Browser Init
   {
@@ -59,7 +41,7 @@ const TOOLS = [
       type: 'object',
       properties: {
         url: { type: 'string' },
-        waitUntil: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle0', 'networkidle2'], default: 'networkidle2' },
+        waitUntil: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle', 'commit'], default: 'networkidle' },
         timeout: { type: 'number', default: 30000 },
         retries: { type: 'number', default: 3, description: 'Auto-retry on failures' },
         smartWait: { type: 'boolean', default: true, description: 'AI-powered smart waiting' }
@@ -575,6 +557,71 @@ const TOOLS = [
       },
       required: ['code']
     }
+  },
+
+  // 23. Screenshot
+  {
+    name: 'screenshot',
+    emoji: '📸',
+    description: 'Capture a screenshot of the viewport, the full scrollable page, or a specific element. Returns the image directly to the AI agent (base64) and can optionally save it to a file. EFFICIENCY RULE: PREFER a single FULL-PAGE screenshot (set fullPage: true) so the entire page is captured in one shot, then complete ALL related work for that page from this single capture (read, click, type, extract). Take a SECOND screenshot ONLY IF the work genuinely cannot be finished from the first one, OR after the page actually changes (navigation, modal/popup, or new dynamic content loads). Do NOT take repeated screenshots of the SAME unchanged page.',
+    descriptionHindi: 'स्क्रीनशॉट लेना — viewport, पूरा पेज, या किसी element का। Image सीधे AI को मिलती है + file में save हो सकती है। नियम: पहले पूरे पेज का full-page (लॉन्ग) स्क्रीनशॉट लें (fullPage: true) ताकि पूरा पेज एक ही बार में दिख जाए, फिर उसी एक image से उस पेज का सारा काम (पढ़ना, क्लिक, टाइप, data निकालना) एक साथ complete करें। दूसरा स्क्रीनशॉट सिर्फ़ तभी लें जब पहले वाले से काम पूरा न हो पाए, या पेज सच में बदल जाए (navigation, modal/popup, या नया dynamic content)। बिना बदलाव के उसी पेज का बार-बार स्क्रीनशॉट न लें।',
+    category: 'capture',
+    requiresBrowser: true,
+    requiresPage: true,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fullPage: { type: 'boolean', default: false, description: 'Capture the full scrollable page' },
+        selector: { type: 'string', description: 'CSS selector to screenshot a specific element only' },
+        format: { type: 'string', enum: ['png', 'jpeg'], default: 'png' },
+        quality: { type: 'number', description: 'JPEG quality 0-100 (jpeg only)' },
+        path: { type: 'string', description: 'Optional file path to save the screenshot' },
+        returnBase64: { type: 'boolean', default: true, description: 'Return image to AI as base64 (MCP image content)' },
+        omitBackground: { type: 'boolean', default: false, description: 'Transparent background (png only)' }
+      }
+    }
+  },
+
+  // 24. Save as PDF
+  {
+    name: 'save_as_pdf',
+    emoji: '📑',
+    description: 'Save the current page as a PDF file using Chromium print-to-PDF. Note: works only in headless mode.',
+    descriptionHindi: 'पेज को PDF में सेव करना (Chromium print-to-PDF)। ध्यान: सिर्फ़ headless mode में काम करता है।',
+    category: 'capture',
+    requiresBrowser: true,
+    requiresPage: true,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', default: './downloads/page.pdf', description: 'File path to save the PDF' },
+        format: { type: 'string', default: 'A4', description: 'Paper format: A4, Letter, Legal, etc.' },
+        landscape: { type: 'boolean', default: false },
+        printBackground: { type: 'boolean', default: true, description: 'Include background graphics' }
+      }
+    }
+  },
+
+  // 25. See Page (AI Vision — "eyes")
+  {
+    name: 'see_page',
+    emoji: '👁️',
+    description: 'AI VISION ("eyes"): Visually SEE the current page exactly like a human does. Captures a screenshot and returns the actual image to the AI agent so it can visually understand the layout, AND returns a "visual map" of all visible interactive elements (buttons, links, inputs) with their on-screen position (x/y/width/height), text label, and a click-ready selector. Use this to look at a page before deciding where to click/type. EFFICIENCY RULE: PREFER a single FULL-PAGE view (set fullPage: true) so the whole page and all its interactive elements are mapped in one shot, then plan and perform ALL needed actions for that page (read, click, type, extract) from this single view. Call see_page a SECOND time ONLY IF the task genuinely cannot be completed from the first view, OR after the page actually changes — navigation, a modal/popup opens, or new dynamic content loads. Do NOT re-capture the SAME unchanged page repeatedly.',
+    descriptionHindi: 'AI विज़न ("आँखें"): पेज को इंसान की तरह देखना। स्क्रीनशॉट image सीधे AI को भेजता है ताकि वह layout देख सके + सभी दिखने वाले clickable elements का visual map (position + text + selector) देता है। नियम: पहले पूरे पेज का full-page view लें (fullPage: true) ताकि पूरा पेज और उसके सारे elements एक ही बार में map हो जाएँ, फिर उसी एक view से उस पेज के सारे ज़रूरी काम (पढ़ना, क्लिक, टाइप, data निकालना) एक साथ पूरे करें। दूसरी बार see_page सिर्फ़ तभी लें जब पहले view से काम पूरा न हो पाए, या पेज सच में बदल जाए (navigation, modal/popup खुले, या नया dynamic content load हो)। बिना बदलाव के उसी पेज का दोबारा स्क्रीनशॉट न लें।',
+    category: 'vision',
+    requiresBrowser: true,
+    requiresPage: true,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fullPage: { type: 'boolean', default: false, description: 'See the entire scrollable page (true) or just the current viewport (false)' },
+        format: { type: 'string', enum: ['png', 'jpeg'], default: 'jpeg', description: 'Image format (jpeg = smaller, faster for vision)' },
+        quality: { type: 'number', default: 70, description: 'JPEG quality 0-100 (lower = smaller image to the AI)' },
+        includeElements: { type: 'boolean', default: true, description: 'Include the visual map of interactive elements' },
+        maxElements: { type: 'number', default: 60, description: 'Max number of interactive elements to map' },
+        path: { type: 'string', description: 'Optional file path to also save the captured image' }
+      }
+    }
   }
 ];
 
@@ -586,6 +633,8 @@ const CATEGORIES = {
   extraction: { name: 'Extraction', emoji: '📄', description: 'Content extraction and scraping' },
   network: { name: 'Network', emoji: '📡', description: 'Network operations' },
   analysis: { name: 'Analysis', emoji: '🧠', description: 'Page analysis' },
+  capture: { name: 'Capture', emoji: '📸', description: 'Screenshots and PDF capture' },
+  vision: { name: 'Vision', emoji: '👁️', description: 'AI visual perception (sees pages like human eyes)' },
   utility: { name: 'Utility', emoji: '🛠️', description: 'Utility tools' }
 };
 

package/test/mcp/smoke-test.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * MCP Smoke Test — network-independent, fast.
+ *
+ * Spawns the MCP server over STDIO exactly like a real client (Cline/Claude),
+ * performs the JSON-RPC handshake, and verifies:
+ *   1. STDOUT carries ONLY clean JSON-RPC (no banner/log contamination)
+ *   2. `initialize` returns valid serverInfo (name + version from package.json)
+ *   3. `tools/list` returns all expected tools with valid schemas
+ *   4. Tool definitions match src/shared/tools.js (count + names)
+ *   5. Every tool in the registry has a handler implementation
+ *
+ * This does NOT launch a browser, so it runs in milliseconds and in CI.
+ * Exit code 0 = all pass, 1 = failure.
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const assert = require('assert');
+
+const ROOT = path.join(__dirname, '..', '..');
+const SERVER = path.join(ROOT, 'src', 'index.js');
+const { TOOLS } = require(path.join(ROOT, 'src', 'shared', 'tools.js'));
+const { handlers } = require(path.join(ROOT, 'src', 'mcp', 'handlers.js'));
+const PKG = require(path.join(ROOT, 'package.json'));
+
+let passed = 0;
+let failed = 0;
+function check(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2705 ${name}`);
+    passed++;
+  } catch (e) {
+    console.log(`  \u274c ${name}\n     ${e.message}`);
+    failed++;
+  }
+}
+
+function rpc(child, obj) {
+  child.stdin.write(JSON.stringify(obj) + '\n');
+}
+
+async function main() {
+  console.log('\n\ud83e\uddea MCP Smoke Test (no browser)\n');
+
+  // --- Static checks (no spawn needed) ---
+  console.log('Static checks:');
+  check('every registered tool has a handler', () => {
+    const missing = TOOLS.filter(t => typeof handlers[t.name] !== 'function').map(t => t.name);
+    assert.strictEqual(missing.length, 0, `missing handlers: ${missing.join(', ')}`);
+  });
+  check('every tool has name + inputSchema', () => {
+    const bad = TOOLS.filter(t => !t.name || !t.inputSchema || t.inputSchema.type !== 'object');
+    assert.strictEqual(bad.length, 0, `invalid tool defs: ${bad.map(t => t.name).join(', ')}`);
+  });
+  check('no duplicate tool names', () => {
+    const names = TOOLS.map(t => t.name);
+    const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+    assert.strictEqual(dupes.length, 0, `duplicates: ${dupes.join(', ')}`);
+  });
+
+  // --- Live STDIO handshake ---
+  console.log('\nLive STDIO handshake:');
+  const child = spawn('node', [SERVER], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, HEADLESS: 'true' },
+  });
+
+  const responses = {};
+  let stdoutBuf = '';
+  let nonJsonLines = 0;
+
+  child.stdout.on('data', (d) => {
+    stdoutBuf += d.toString();
+    let idx;
+    while ((idx = stdoutBuf.indexOf('\n')) >= 0) {
+      const line = stdoutBuf.slice(0, idx).trim();
+      stdoutBuf = stdoutBuf.slice(idx + 1);
+      if (!line) continue;
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id !== undefined) responses[msg.id] = msg;
+      } catch (e) {
+        nonJsonLines++;
+      }
+    }
+  });
+
+  const wait = (ms) => new Promise(r => setTimeout(r, ms));
+
+  await wait(1200);
+  rpc(child, {
+    jsonrpc: '2.0', id: 1, method: 'initialize',
+    params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'smoke-test', version: '1.0.0' } },
+  });
+  await wait(1200);
+  rpc(child, { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+  await wait(1500);
+
+  child.kill();
+
+  check('STDOUT had zero non-JSON lines (clean JSON-RPC stream)', () => {
+    assert.strictEqual(nonJsonLines, 0, `${nonJsonLines} non-JSON line(s) leaked to STDOUT`);
+  });
+  check('initialize responded', () => {
+    assert.ok(responses[1], 'no response for id=1');
+    assert.ok(responses[1].result, 'initialize has no result');
+  });
+  check('serverInfo.name is correct', () => {
+    assert.strictEqual(responses[1].result.serverInfo.name, 'real-browser-mcp-server');
+  });
+  check('serverInfo.version matches package.json', () => {
+    assert.strictEqual(responses[1].result.serverInfo.version, PKG.version,
+      `server reported ${responses[1].result.serverInfo.version}, package.json is ${PKG.version}`);
+  });
+  check('tools/list responded', () => {
+    assert.ok(responses[2], 'no response for id=2');
+    assert.ok(Array.isArray(responses[2].result.tools), 'tools is not an array');
+  });
+  check(`tools/list returns ${TOOLS.length} tools`, () => {
+    assert.strictEqual(responses[2].result.tools.length, TOOLS.length);
+  });
+  check('tools/list names match registry', () => {
+    const live = responses[2].result.tools.map(t => t.name).sort();
+    const reg = TOOLS.map(t => t.name).sort();
+    assert.deepStrictEqual(live, reg);
+  });
+  check('every live tool has an inputSchema', () => {
+    const bad = responses[2].result.tools.filter(t => !t.inputSchema);
+    assert.strictEqual(bad.length, 0, `missing inputSchema: ${bad.map(t => t.name).join(', ')}`);
+  });
+
+  console.log(`\n\u2139 passed ${passed}, failed ${failed}\n`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+main().catch(e => {
+  console.error('Smoke test crashed:', e);
+  process.exit(1);
+});