brave-real-browser-mcp-server 2.37.0 → 2.37.2

package/README.md

@@ -16,6 +16,7 @@ A production-ready MCP (Model Context Protocol) server that combines Puppeteer w
 |---------|-------------|
 | **MCP Server** | Model Context Protocol compatible server with 28 tools |
 | **LSP Server** | Language Server Protocol for IDE code intelligence |
+| **AI Core** | Automatic AI enhancement for all tools (auto-healing, smart retry) |
 | Brave Browser | Uses Brave instead of Chromium for better privacy |
 | 50+ Stealth Features | Passes all major bot detectors |
 | Built-in Ad Blocker | uBlock Origin filters with auto-update |
@@ -152,40 +153,81 @@ npm run lsp
 | **Simulation** | Workflow simulation in IDE |
 | **Multi-language** | English & Hindi support |
 
-### VS Code Setup
+## AI Core (Automatic Enhancement)
+
+All 28 tools are automatically enhanced with AI capabilities. No configuration needed - AI features work transparently.
+
+### How It Works
+
+```
+AI Agent calls any tool (e.g., click, type, find_element)
+                │
+                ▼
+        ┌───────────────────┐
+        │   AI Core Check   │
+        │ (Lazy initialize) │
+        └───────────────────┘
+                │
+                ▼
+        Execute Original Tool
+                │
+        ┌───────┴───────┐
+        │               │
+     Success         Failed (selector not found)
+        │               │
+        ▼               ▼
+   Return result    ┌─────────────────┐
+   with _ai meta    │ AI Auto-Healing │
+                    │ - Find alts     │
+                    │ - Try healed    │
+                    │ - Retry op      │
+                    └─────────────────┘
+                            │
+                            ▼
+                    Return healed result
+```
+
+### AI Features
 
-Create `.vscode/settings.json` in your project:
+| Feature | Description |
+|---------|-------------|
+| **Auto-Healing Selectors** | If a CSS selector fails, AI finds alternative selectors |
+| **Smart Retry** | Failed operations are automatically retried with AI assistance |
+| **Confidence Scoring** | AI provides confidence scores for healed selectors |
+| **Caching** | Healed selectors are cached for performance |
+| **Zero Configuration** | Works out of the box with all 28 tools |
+
+### Example Response with AI Metadata
+
+When AI heals a broken selector:
 
 ```json
 {
-  "braveRealBrowser.language": "en",
-  "braveRealBrowser.maxDiagnostics": 100,
-  "braveRealBrowser.enableSnippets": true,
-  "braveRealBrowser.enableSimulation": true,
-  "braveRealBrowser.enableRefactoring": true
+  "success": true,
+  "selector": "#new-login-btn",
+  "clicked": true,
+  "_ai": {
+    "enabled": true,
+    "healed": true,
+    "originalSelector": "#old-login-button",
+    "healedSelector": "#new-login-btn",
+    "duration": 245
+  }
 }
 ```
+### Programmatic Access
 
-### Diagnostic Features
-
-The LSP detects common issues:
+For advanced usage, you can access AI features directly:
 
-- Missing `browser_init()` before page operations
-- Missing `navigate()` before content extraction
-- Invalid selectors and URLs
-- Missing required parameters
-- Unclosed browser sessions
-- Security issues (eval usage, etc.)
-
-### Quick Fixes
+```javascript
+const { getAICore, aiEnhancedSelector } = require('./src/mcp/handlers');
 
-When diagnostics are detected, quick fixes are offered:
+// Get AI Core instance
+const ai = getAICore();
 
-- Add `browser_init()` at start
-- Add `navigate()` before page tools
-- Add `browser_close()` at end
-- Wrap in try-catch
-- Extract to function
+// Use AI-enhanced selector finding
+const { element, selector, healed } = await aiEnhancedSelector(page, '#old-selector', 'click');
+```
 
 ---
 
@@ -197,9 +239,16 @@ Both MCP and LSP servers share the same tool definitions:
 src/
 ├── shared/
 │   └── tools.js         # Single source of truth (28 tools)
+├── ai/                  # AI Core Module (Auto-enhancement)
+│   ├── index.js         # AI module exports
+│   ├── core.js          # AI Core singleton
+│   ├── element-finder.js# Smart element finding
+│   ├── selector-healer.js# Auto-heal selectors
+│   ├── page-analyzer.js # Page analysis
+│   └── action-parser.js # NL command parsing
 ├── mcp/
 │   ├── server.js        # MCP server for AI agents
-│   └── handlers.js      # Tool implementations
+│   └── handlers.js      # Tool implementations + AI integration
 ├── lsp/
 │   ├── server.js        # LSP server for IDEs
 │   └── capabilities/    # Autocomplete, hover, diagnostics, etc.
@@ -221,21 +270,6 @@ node src/index.js lsp
 # Show help
 node src/index.js --help
 ```
-
-### Tool Categories
-
-| Category | Tools | Description |
-|----------|-------|-------------|
-| **Browser** | 3 | Browser lifecycle (init, close, cookies) |
-| **Navigation** | 1 | Page navigation |
-| **Interaction** | 8 | User actions (click, type, scroll, etc.) |
-| **Extraction** | 10 | Content scraping (HTML, JSON, links, etc.) |
-| **Network** | 3 | Network operations (recorder, download, trace) |
-| **Analysis** | 1 | Page analysis (SEO, performance, etc.) |
-| **Utility** | 2 | Helpers (wait, progress tracker) |
-
----
-
 ## Monorepo Ecosystem
 
 ```
@@ -302,53 +336,6 @@ All packages published to NPM automatically
 ```bash
 npm install brave-real-browser-mcp-server
 ```
-
-For Linux (required for headless mode):
-```bash
-sudo apt-get install xvfb
-```
-
----
-
-## Quick Start
-
-### CommonJS
-
-```javascript
-const { connect } = require('brave-real-browser-mcp-server');
-
-(async () => {
-  const { browser, page, blocker } = await connect({
-    headless: false,
-    turnstile: true,  // Auto-solve Cloudflare
-  });
-
-  await page.goto('https://example.com');
-
-  // Human-like click with ghost-cursor
-  await page.realClick('#button');
-
-  await browser.close();
-})();
-```
-
-### ESM
-
-```javascript
-import { connect } from 'brave-real-browser-mcp-server';
-
-const { browser, page, blocker } = await connect({
-  headless: false,
-  turnstile: true,
-});
-
-await page.goto('https://example.com');
-await page.realClick('#button');
-await browser.close();
-```
-
----
-
 ## Connect Options
 
 | Option | Type | Default | Description |
@@ -403,104 +390,6 @@ const { browser, page } = await connect({
 });
 ```
 
-### Custom Brave Path
-
-```javascript
-const { browser, page } = await connect({
-  customConfig: {
-    bravePath: 'C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe',
-    userDataDir: './my-profile'
-  }
-});
-```
-
-### Disable Blocker
-
-```javascript
-const { browser, page } = await connect({
-  enableBlocker: false,  // Disable all blocking
-});
-```
-
-### Custom Blocker Options
-
-```javascript
-const { browser, page, blocker } = await connect({
-  blockerOptions: {
-    enableAdBlocking: true,
-    enableStealth: true,
-    enableCosmeticFiltering: true,
-    enableRedirectBlocking: true,
-    enableScriptlets: true,
-    customFiltersPath: './my-filters.txt',
-    enableFilterAutoUpdate: true,
-  }
-});
-```
-
-### Real Cursor (Ghost-Cursor)
-
-Built-in ghost-cursor for human-like mouse movements:
-
-```javascript
-const { browser, page } = await connect();
-
-// Human-like click
-await page.realClick('#submit-button');
-
-// Full cursor control
-await page.realCursor.move('#element');
-await page.realCursor.click('#button');
-```
-
-### Turnstile Auto-Solver
-
-Automatically solves Cloudflare Turnstile challenges:
-
-```javascript
-const { browser, page } = await connect({
-  turnstile: true
-});
-
-await page.goto('https://site-with-turnstile.com');
-// Turnstile is automatically solved!
-```
-
-### Puppeteer-Extra Plugins
-
-```javascript
-const clickAndWait = require('puppeteer-extra-plugin-click-and-wait')();
-
-const { browser, page } = await connect({
-  plugins: [clickAndWait]
-});
-```
-
-### Singleton Blocker Usage
-
-The blocker is a singleton - only one instance is created and shared:
-
-```javascript
-// From brave-real-blocker package
-import { 
-  getBraveBlockerSingleton, 
-  initBraveBlockerSingleton,
-  isBraveBlockerInitialized 
-} from 'brave-real-blocker/singleton';
-
-// Initialize once at startup
-const blocker = await initBraveBlockerSingleton({
-  enableAdBlocking: true,
-  enableStealth: true,
-});
-
-// Get the same instance anywhere else
-const sameBlocker = getBraveBlockerSingleton();
-console.log(blocker === sameBlocker); // true
-```
-
----
-
 ## Commands
 
 ### Root Level

package/data/.gitkeep

@@ -0,0 +1,2 @@
+# This folder stores learned patterns for self-healing
+# Files are auto-generated and should not be committed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brave-real-browser-mcp-server",
-  "version": "2.37.0",
+  "version": "2.37.2",
   "description": "MCP Server for Brave Real Browser - Puppeteer with Brave Browser, Stealth Mode, Ad Blocker, and Turnstile Auto-Solver for undetectable web automation.",
   "main": "lib/cjs/index.js",
   "module": "lib/esm/index.mjs",
@@ -71,7 +71,7 @@
   "license": "ISC",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.3",
-    "brave-real-puppeteer-core": "^24.52.0",
+    "brave-real-puppeteer-core": "^24.52.2",
     "ghost-cursor": "^1.4.2",
     "puppeteer-extra": "^3.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",

package/packages/brave-real-blocker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brave-real-blocker",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "description": "Advanced uBlock Origin management and stealth features for Brave Real Browser",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -53,17 +53,18 @@
   },
   "homepage": "https://github.com/codeiva4u/Brave-Real-Browser/tree/main/packages/brave-real-blocker",
   "dependencies": {
-    "@cliqz/adblocker-puppeteer": "^1.23.8",
+    "@cliqz/adblocker-puppeteer": "^1.34.0",
+    "@ghostery/adblocker-puppeteer": "^2.13.4",
     "adm-zip": "^0.5.10",
     "cross-fetch": "^4.1.0",
-    "fs-extra": "^11.2.0",
+    "fs-extra": "^11.3.3",
     "got": "^13.0.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.5",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^20.0.0",
-    "brave-real-puppeteer-core": "^24.52.0",
+    "brave-real-puppeteer-core": "^24.52.2",
     "mocha": "^10.4.0",
     "puppeteer-core": "^24.35.0",
     "sinon": "^17.0.1",

package/packages/brave-real-launcher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brave-real-launcher",
-  "version": "1.19.0",
+  "version": "1.19.2",
   "description": "Launch Brave Browser with ease from node. Based on chrome-launcher with Brave-specific support.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -54,10 +54,10 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "brave-real-blocker": "^1.13.0",
-    "escape-string-regexp": "^4.0.0",
-    "is-wsl": "^2.2.0",
-    "which": "^4.0.0"
+    "brave-real-blocker": "^1.13.2",
+    "escape-string-regexp": "^5.0.0",
+    "is-wsl": "^3.1.0",
+    "which": "^6.0.0"
   },
   "types": "./dist/index.d.ts",
   "repository": {

package/packages/brave-real-puppeteer-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brave-real-puppeteer-core",
-  "version": "24.52.0",
+  "version": "24.52.2",
   "description": "🦁 Brave Real-World Optimized Puppeteer & Playwright Core with 1-5ms ultra-fast timing, 50+ professional stealth features, intelligent browser auto-detection, and 100% bot detection bypass. Features cross-platform Brave browser integration, comprehensive anti-detection, and breakthrough performance improvements.",
   "keywords": [
     "automation",
@@ -132,13 +132,13 @@
     "test-version": "node ./scripts/test-version-management.js"
   },
   "dependencies": {
-    "brave-real-launcher": "^1.19.0",
+    "brave-real-launcher": "^1.19.2",
     "get-east-asian-width": "^1.4.0",
     "yargs": "^18.0.0"
   },
   "optionalDependencies": {
-    "playwright-core": "^1.57.0",
-    "puppeteer-core": "^24.34.0"
+    "playwright-core": "^1.58.1",
+    "puppeteer-core": "^24.36.1"
   },
   "devDependencies": {
     "test": "^3.3.0"

package/src/ai/action-parser.js

@@ -0,0 +1,274 @@
+/**
+ * AI Action Parser - Parse natural language commands into actions
+ * 
+ * Converts commands like:
+ * - "click the login button" -> { type: 'click', target: 'login button' }
+ * - "type hello in the search box" -> { type: 'type', target: 'search box', text: 'hello' }
+ * - "scroll down" -> { type: 'scroll', direction: 'down' }
+ */
+
+class ActionParser {
+  constructor() {
+    // Action patterns
+    this.actionPatterns = [
+      // Click patterns
+      {
+        pattern: /^(click|tap|press|hit|select)\s+(?:on\s+)?(?:the\s+)?(.+)/i,
+        type: 'click',
+        extract: (match) => ({ target: match[2].trim() })
+      },
+      // Type patterns
+      {
+        pattern: /^(type|enter|write|input)\s+["']?([^"']+)["']?\s+(?:in|into|in the|into the)\s+(.+)/i,
+        type: 'type',
+        extract: (match) => ({ text: match[2].trim(), target: match[3].trim() })
+      },
+      {
+        pattern: /^(type|enter|write|input)\s+(.+)\s+(?:in|into)\s+["']?([^"']+)["']?/i,
+        type: 'type',
+        extract: (match) => ({ target: match[2].trim(), text: match[3].trim() })
+      },
+      {
+        pattern: /^(fill|fill in|complete)\s+(?:the\s+)?(.+)\s+(?:with|as)\s+["']?([^"']+)["']?/i,
+        type: 'type',
+        extract: (match) => ({ target: match[2].trim(), text: match[3].trim() })
+      },
+      // Navigate patterns
+      {
+        pattern: /^(go to|navigate to|open|visit)\s+(.+)/i,
+        type: 'navigate',
+        extract: (match) => {
+          let url = match[2].trim();
+          if (!url.startsWith('http')) {
+            url = 'https://' + url;
+          }
+          return { url };
+        }
+      },
+      // Scroll patterns
+      {
+        pattern: /^scroll\s+(up|down|left|right)(?:\s+(\d+)\s*(?:px|pixels)?)?/i,
+        type: 'scroll',
+        extract: (match) => ({ 
+          direction: match[1].toLowerCase(), 
+          amount: parseInt(match[2]) || 300 
+        })
+      },
+      {
+        pattern: /^scroll\s+to\s+(?:the\s+)?(top|bottom|footer|header)/i,
+        type: 'scroll',
+        extract: (match) => {
+          const target = match[1].toLowerCase();
+          return {
+            direction: target === 'top' || target === 'header' ? 'up' : 'down',
+            amount: 10000,
+            scrollTo: target
+          };
+        }
+      },
+      // Wait patterns
+      {
+        pattern: /^wait\s+(?:for\s+)?(\d+)\s*(?:ms|milliseconds?|s|seconds?)?/i,
+        type: 'wait',
+        extract: (match) => {
+          let duration = parseInt(match[1]);
+          const unit = match[0].toLowerCase();
+          if (unit.includes('s') && !unit.includes('ms')) {
+            duration *= 1000;
+          }
+          return { duration };
+        }
+      },
+      {
+        pattern: /^wait\s+(?:for\s+)?(?:the\s+)?(.+?)(?:\s+to\s+(?:appear|load|show))?$/i,
+        type: 'waitFor',
+        extract: (match) => ({ target: match[1].trim() })
+      },
+      // Find/Search patterns
+      {
+        pattern: /^(find|search|look for|locate)\s+(?:the\s+)?(.+)/i,
+        type: 'find',
+        extract: (match) => ({ query: match[2].trim() })
+      },
+      // Hover patterns
+      {
+        pattern: /^(hover|mouse over|move to)\s+(?:the\s+)?(.+)/i,
+        type: 'hover',
+        extract: (match) => ({ target: match[2].trim() })
+      },
+      // Clear patterns
+      {
+        pattern: /^(clear|empty|delete)\s+(?:the\s+)?(.+)/i,
+        type: 'clear',
+        extract: (match) => ({ target: match[2].trim() })
+      },
+      // Submit patterns
+      {
+        pattern: /^submit\s+(?:the\s+)?(?:form)?(.*)$/i,
+        type: 'submit',
+        extract: (match) => ({ target: match[1].trim() || 'form' })
+      },
+      // Screenshot patterns
+      {
+        pattern: /^(take|capture)\s+(?:a\s+)?screenshot/i,
+        type: 'screenshot',
+        extract: () => ({})
+      },
+      // Go back/forward patterns
+      {
+        pattern: /^go\s+(back|forward)/i,
+        type: 'navigation',
+        extract: (match) => ({ direction: match[1].toLowerCase() })
+      },
+      // Refresh patterns
+      {
+        pattern: /^(refresh|reload)\s*(?:the\s+)?(?:page)?/i,
+        type: 'refresh',
+        extract: () => ({})
+      }
+    ];
+
+    // Context variable patterns (for substitution)
+    this.variablePattern = /\{(\w+)\}/g;
+  }
+
+  /**
+   * Parse a natural language command
+   */
+  async parse(command, context = {}) {
+    // Substitute context variables
+    let processedCommand = command.replace(this.variablePattern, (match, varName) => {
+      return context[varName] !== undefined ? context[varName] : match;
+    });
+
+    // Trim and normalize
+    processedCommand = processedCommand.trim();
+
+    // Try each pattern
+    for (const pattern of this.actionPatterns) {
+      const match = processedCommand.match(pattern.pattern);
+      if (match) {
+        const extracted = pattern.extract(match);
+        return {
+          type: pattern.type,
+          ...extracted,
+          originalCommand: command,
+          confidence: 0.9
+        };
+      }
+    }
+
+    // Fallback: Try to guess action from keywords
+    const fallback = this.guessFallback(processedCommand);
+    if (fallback) {
+      return {
+        ...fallback,
+        originalCommand: command,
+        confidence: 0.5
+      };
+    }
+
+    // Could not parse
+    return {
+      type: 'unknown',
+      originalCommand: command,
+      confidence: 0,
+      error: 'Could not understand command'
+    };
+  }
+
+  /**
+   * Try to guess action from keywords
+   */
+  guessFallback(command) {
+    const lower = command.toLowerCase();
+
+    // Check for action keywords
+    if (lower.includes('button') || lower.includes('link') || lower.includes('click')) {
+      return { type: 'click', target: command };
+    }
+
+    if (lower.includes('type') || lower.includes('enter') || lower.includes('input')) {
+      return { type: 'find', query: command, suggestedAction: 'type' };
+    }
+
+    if (lower.includes('search') || lower.includes('find') || lower.includes('look')) {
+      return { type: 'find', query: command };
+    }
+
+    if (lower.includes('scroll')) {
+      return { type: 'scroll', direction: 'down', amount: 300 };
+    }
+
+    // Default to find
+    return { type: 'find', query: command };
+  }
+
+  /**
+   * Parse multiple commands (separated by 'then', 'and', or newlines)
+   */
+  async parseMultiple(commands, context = {}) {
+    // Split by separators
+    const parts = commands.split(/\s+(?:then|and)\s+|\n|;/i).filter(p => p.trim());
+    
+    const results = [];
+    for (const part of parts) {
+      const parsed = await this.parse(part.trim(), context);
+      results.push(parsed);
+    }
+
+    return results;
+  }
+
+  /**
+   * Get suggestions for incomplete commands
+   */
+  getSuggestions(partialCommand) {
+    const lower = partialCommand.toLowerCase();
+    const suggestions = [];
+
+    if (lower.startsWith('click')) {
+      suggestions.push(
+        'click the login button',
+        'click the submit button',
+        'click the link',
+        'click the menu'
+      );
+    } else if (lower.startsWith('type')) {
+      suggestions.push(
+        'type "text" in the search box',
+        'type "username" in the login field',
+        'type "hello" in the input'
+      );
+    } else if (lower.startsWith('go')) {
+      suggestions.push(
+        'go to google.com',
+        'go back',
+        'go forward'
+      );
+    } else if (lower.startsWith('scroll')) {
+      suggestions.push(
+        'scroll down',
+        'scroll up',
+        'scroll to the bottom',
+        'scroll to the top'
+      );
+    } else if (lower.startsWith('wait')) {
+      suggestions.push(
+        'wait 2 seconds',
+        'wait for the button to appear',
+        'wait 500ms'
+      );
+    } else if (lower.startsWith('find')) {
+      suggestions.push(
+        'find the login button',
+        'find the search input',
+        'find all links'
+      );
+    }
+
+    return suggestions;
+  }
+}
+
+module.exports = ActionParser;