brave-real-browser-mcp-server 2.36.0 → 2.37.1

package/README.md

@@ -14,7 +14,9 @@ A production-ready MCP (Model Context Protocol) server that combines Puppeteer w
 
 | Feature | Description |
 |---------|-------------|
-| MCP Server | Model Context Protocol compatible server |
+| **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 |
@@ -25,6 +27,7 @@ A production-ready MCP (Model Context Protocol) server that combines Puppeteer w
 | Auto-Install | Brave auto-installs if missing |
 | TypeScript Support | Full type definitions included |
 | ESM + CJS | Dual module support |
+| **Multi-language** | English & Hindi language support |
 | **Auto-Update** | Daily automatic dependency updates |
 | **Auto-Publish** | Automatic NPM publishing on updates |
 | **Monorepo** | npm workspaces with linked packages |
@@ -127,6 +130,209 @@ AI: [Calls file_downloader with url="..."] -> Downloaded to ./downloads/image.pn
 
 ---
 
+## LSP Server (Language Server Protocol)
+
+This package also includes a full-featured **LSP Server** for IDE code intelligence when writing browser automation scripts.
+
+### Quick Start LSP Server
+
+```bash
+# Start the LSP server
+npm run lsp
+```
+
+### LSP Capabilities
+
+| Feature | Description |
+|---------|-------------|
+| **Autocomplete** | Tool names, parameters, and enum values |
+| **Hover** | Full documentation on hover |
+| **Diagnostics** | Error & warning detection (missing browser_init, etc.) |
+| **Snippets** | Code templates for common workflows |
+| **Refactoring** | Quick fixes (add browser_init, try-catch, etc.) |
+| **Simulation** | Workflow simulation in IDE |
+| **Multi-language** | English & Hindi support |
+
+### VS Code Setup
+
+Create `.vscode/settings.json` in your project:
+
+```json
+{
+  "braveRealBrowser.language": "en",
+  "braveRealBrowser.maxDiagnostics": 100,
+  "braveRealBrowser.enableSnippets": true,
+  "braveRealBrowser.enableSimulation": true,
+  "braveRealBrowser.enableRefactoring": true
+}
+```
+
+### Diagnostic Features
+
+The LSP detects common issues:
+
+- 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
+
+When diagnostics are detected, quick fixes are offered:
+
+- Add `browser_init()` at start
+- Add `navigate()` before page tools
+- Add `browser_close()` at end
+- Wrap in try-catch
+- Extract to function
+
+---
+
+## 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
+
+| 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
+{
+  "success": true,
+  "selector": "#new-login-btn",
+  "clicked": true,
+  "_ai": {
+    "enabled": true,
+    "healed": true,
+    "originalSelector": "#old-login-button",
+    "healedSelector": "#new-login-btn",
+    "duration": 245
+  }
+}
+```
+
+### AI Modules
+
+| Module | Description |
+|--------|-------------|
+| `AICore` | Central AI intelligence singleton |
+| `ElementFinder` | Smart element finding with multiple strategies |
+| `SelectorHealer` | Auto-fix broken CSS selectors |
+| `PageAnalyzer` | Page structure analysis |
+| `ActionParser` | Natural language command parsing |
+
+### Programmatic Access
+
+For advanced usage, you can access AI features directly:
+
+```javascript
+const { getAICore, aiEnhancedSelector } = require('./src/mcp/handlers');
+
+// Get AI Core instance
+const ai = getAICore();
+
+// Use AI-enhanced selector finding
+const { element, selector, healed } = await aiEnhancedSelector(page, '#old-selector', 'click');
+```
+
+---
+
+## Unified Architecture
+
+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 + AI integration
+├── lsp/
+│   ├── server.js        # LSP server for IDEs
+│   └── capabilities/    # Autocomplete, hover, diagnostics, etc.
+└── index.js             # Unified entry point
+```
+
+### Unified CLI
+
+```bash
+# List all tools
+node src/index.js --list
+
+# Start MCP server (default)
+node src/index.js mcp
+
+# Start LSP server
+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
 
 ```
@@ -398,9 +604,12 @@ console.log(blocker === sameBlocker); // true
 
 | Command | Description |
 |---------|-------------|
+| `npm start` | Start unified server (MCP by default) |
 | `npm run dev` | Start MCP server |
 | `npm run mcp` | Start MCP server (alias) |
 | `npm run mcp:verbose` | Start MCP server with tool details |
+| `npm run lsp` | Start LSP server for IDE intelligence |
+| `npm run list` | List all 28 tools with categories |
 | `npm install` | Install all dependencies with workspace linking |
 | `npm test` | Run all tests (CJS + ESM) |
 | `npm run cjs_test` | Run CommonJS tests only |

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.36.0",
+  "version": "2.37.1",
   "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",
@@ -28,10 +28,11 @@
   },
   "scripts": {
     "start": "node src/index.js",
-    "dev": "node src/index.js mcp",
+    "dev": "node src/index.js",
     "mcp": "node src/index.js mcp",
     "mcp:verbose": "node src/index.js mcp --verbose",
     "lsp": "node src/index.js lsp",
+    "lsp:tcp": "node src/lsp/server.js --tcp",
     "list": "node src/index.js --list",
     "build": "echo 'Root package uses pre-built lib/ - no build needed'",
     "build:self": "echo 'Root package uses pre-built lib/ - no build needed'",
@@ -70,7 +71,7 @@
   "license": "ISC",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.3",
-    "brave-real-puppeteer-core": "^24.51.0",
+    "brave-real-puppeteer-core": "^24.52.1",
     "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.12.0",
+  "version": "1.13.1",
   "description": "Advanced uBlock Origin management and stealth features for Brave Real Browser",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -63,7 +63,7 @@
     "@types/adm-zip": "^0.5.5",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^20.0.0",
-    "brave-real-puppeteer-core": "^24.51.0",
+    "brave-real-puppeteer-core": "^24.52.1",
     "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.18.0",
+  "version": "1.19.1",
   "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,7 +54,7 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "brave-real-blocker": "^1.12.0",
+    "brave-real-blocker": "^1.13.1",
     "escape-string-regexp": "^4.0.0",
     "is-wsl": "^2.2.0",
     "which": "^4.0.0"

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

@@ -1,6 +1,6 @@
 {
   "name": "brave-real-puppeteer-core",
-  "version": "24.51.0",
+  "version": "24.52.1",
   "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,7 +132,7 @@
     "test-version": "node ./scripts/test-version-management.js"
   },
   "dependencies": {
-    "brave-real-launcher": "^1.18.0",
+    "brave-real-launcher": "^1.19.1",
     "get-east-asian-width": "^1.4.0",
     "yargs": "^18.0.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;