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

package/README.md

@@ -14,7 +14,8 @@ 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 |
 | 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 +26,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 +129,113 @@ 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
+
+---
+
+## Unified Architecture
+
+Both MCP and LSP servers share the same tool definitions:
+
+```
+src/
+├── shared/
+│   └── tools.js         # Single source of truth (28 tools)
+├── mcp/
+│   ├── server.js        # MCP server for AI agents
+│   └── handlers.js      # Tool implementations
+├── 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 +507,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brave-real-browser-mcp-server",
-  "version": "2.36.0",
+  "version": "2.37.0",
   "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.0",
     "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.0",
   "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.0",
     "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.0",
   "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.0",
     "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.0",
   "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.0",
     "get-east-asian-width": "^1.4.0",
     "yargs": "^18.0.0"
   },

package/src/index.js

@@ -3,20 +3,19 @@
  * Brave Real Browser - Unified Entry Point
  * 
  * Usage:
- *   node src/index.js mcp        - Start MCP Server (default)
- *   node src/index.js lsp        - Start LSP Server
- *   node src/index.js --help     - Show help
+ *   node src/index.js             - Start both MCP + LSP together (default)
+ *   node src/index.js mcp         - Start MCP Server only
+ *   node src/index.js lsp         - Start LSP Server only (STDIO)
+ *   node src/index.js --help      - Show help
  * 
  * npm scripts:
- *   npm run dev                  - Start MCP server
- *   npm run mcp                  - Start MCP server
- *   npm run lsp                  - Start LSP server
+ *   npm run dev                   - Start MCP + LSP together
+ *   npm run mcp                   - Start MCP server only
+ *   npm run lsp                   - Start LSP server only
  * 
- * For AI Assistants (MCP):
- *   Claude Desktop, Cursor, Copilot, etc.
- * 
- * For IDEs (LSP):
- *   VS Code, Neovim, Sublime Text, etc.
+ * Architecture:
+ *   MCP Server → STDIO transport (for AI agents: Claude, Cursor, Copilot)
+ *   LSP Server → TCP :7777 (for IDEs: VS Code, Neovim)
  */
 
 const { TOOLS, TOOL_DISPLAY, CATEGORIES } = require('./shared/tools.js');
@@ -45,8 +44,9 @@ ${colors.bright}USAGE:${colors.reset}
   node src/index.js [mode] [options]
 
 ${colors.bright}MODES:${colors.reset}
-  ${colors.green}mcp${colors.reset}           Start MCP Server for AI agents (default)
-  ${colors.green}lsp${colors.reset}           Start LSP Server for IDE intelligence
+  ${colors.green}(default)${colors.reset}     Start both MCP + LSP servers together
+  ${colors.green}mcp${colors.reset}           Start MCP Server only (for AI agents)
+  ${colors.green}lsp${colors.reset}           Start LSP Server only (for IDEs)
 
 ${colors.bright}OPTIONS:${colors.reset}
   ${colors.yellow}--help, -h${colors.reset}    Show this help message
@@ -54,23 +54,25 @@ ${colors.bright}OPTIONS:${colors.reset}
   ${colors.yellow}--list${colors.reset}        List all available tools
 
 ${colors.bright}EXAMPLES:${colors.reset}
-  node src/index.js mcp          # Start MCP server
-  node src/index.js lsp          # Start LSP server
+  node src/index.js              # Start MCP + LSP together
+  node src/index.js mcp          # Start MCP server only
+  node src/index.js lsp          # Start LSP server only
   node src/index.js --list       # List all tools
 
 ${colors.bright}NPM SCRIPTS:${colors.reset}
-  npm run dev                    # Start MCP server
-  npm run mcp                    # Start MCP server
-  npm run lsp                    # Start LSP server
+  npm run dev                    # Start MCP + LSP together
+  npm run mcp                    # Start MCP server only
+  npm run lsp                    # Start LSP server only (STDIO)
+
+${colors.bright}ARCHITECTURE:${colors.reset}
+  ${colors.cyan}MCP Server${colors.reset} → STDIO transport → AI Agents (Claude, Cursor, Copilot)
+  ${colors.cyan}LSP Server${colors.reset} → TCP :7777      → IDEs (VS Code, Neovim)
 
 ${colors.bright}TOOL CATEGORIES (${TOOLS.length} tools):${colors.reset}
 ${Object.entries(CATEGORIES).map(([key, cat]) => {
   const count = TOOLS.filter(t => t.category === key).length;
   return `  ${cat.emoji} ${colors.yellow}${cat.name.padEnd(15)}${colors.reset} ${colors.dim}(${count} tools)${colors.reset}`;
 }).join('\n')}
-
-${colors.dim}MCP: For AI assistants (Claude, Cursor, Copilot)
-LSP: For IDE code intelligence (VS Code, Neovim)${colors.reset}
   `);
 }
 
@@ -88,13 +90,45 @@ function listTools() {
     console.log(`${colors.dim}${'─'.repeat(50)}${colors.reset}`);
     
     for (const tool of tools) {
-      const required = tool.inputSchema?.required || [];
       console.log(`  ${tool.emoji} ${colors.yellow}${tool.name.padEnd(25)}${colors.reset} ${colors.dim}${tool.description.substring(0, 40)}${colors.reset}`);
     }
     console.log('');
   }
 }
 
+/**
+ * Start both MCP and LSP servers together
+ */
+async function startBothServers() {
+  console.error('');
+  console.error(`${colors.bright}${colors.cyan}╔════════════════════════════════════════════════════════════╗${colors.reset}`);
+  console.error(`${colors.bright}${colors.cyan}║${colors.reset}  ${colors.bright}${colors.magenta}🦁 Brave Real Browser - Unified Server${colors.reset}                  ${colors.cyan}║${colors.reset}`);
+  console.error(`${colors.bright}${colors.cyan}║${colors.reset}  ${colors.dim}MCP (AI Agents) + LSP (IDE Intelligence)${colors.reset}                 ${colors.cyan}║${colors.reset}`);
+  console.error(`${colors.bright}${colors.cyan}╚════════════════════════════════════════════════════════════╝${colors.reset}`);
+  console.error('');
+
+  // Start LSP Server on TCP first (background)
+  console.error(`${colors.bright}${colors.blue}📡 Starting LSP Server...${colors.reset}`);
+  
+  try {
+    const { startTcpServer, LSP_PORT } = require('./lsp/server.js');
+    const { port } = await startTcpServer();
+    console.error(`${colors.bright}${colors.green}✅ LSP Server running on TCP :${port}${colors.reset}`);
+    console.error(`${colors.dim}   IDEs can connect to: 127.0.0.1:${port}${colors.reset}`);
+  } catch (err) {
+    console.error(`${colors.yellow}⚠️  LSP Server failed: ${err.message}${colors.reset}`);
+    console.error(`${colors.dim}   Continuing with MCP only...${colors.reset}`);
+  }
+
+  console.error('');
+  
+  // Start MCP Server on STDIO (foreground)
+  console.error(`${colors.bright}${colors.blue}🚀 Starting MCP Server...${colors.reset}`);
+  
+  // Import and run MCP server
+  require('./mcp/index.js');
+}
+
 /**
  * Main entry point
  */
@@ -104,7 +138,7 @@ async function main() {
   // Parse arguments
   const hasHelp = args.includes('--help') || args.includes('-h');
   const hasList = args.includes('--list');
-  const mode = args.find(a => ['mcp', 'lsp'].includes(a.toLowerCase())) || 'mcp';
+  const mode = args.find(a => ['mcp', 'lsp'].includes(a.toLowerCase()));
   
   if (hasHelp) {
     showHelp();
@@ -116,13 +150,16 @@ async function main() {
     process.exit(0);
   }
   
-  // Start appropriate server
-  if (mode.toLowerCase() === 'lsp') {
-    // Start LSP Server
+  // Start appropriate server(s)
+  if (mode?.toLowerCase() === 'lsp') {
+    // Start LSP Server only (STDIO mode)
     require('./lsp/index.js');
-  } else {
-    // Start MCP Server (default)
+  } else if (mode?.toLowerCase() === 'mcp') {
+    // Start MCP Server only
     require('./mcp/index.js');
+  } else {
+    // Default: Start both servers together
+    await startBothServers();
   }
 }
 
@@ -133,6 +170,7 @@ module.exports = {
   CATEGORIES,
   startMCP: () => require('./mcp/index.js'),
   startLSP: () => require('./lsp/index.js'),
+  startBoth: startBothServers,
 };
 
 // Run if called directly

package/src/lsp/server.js

@@ -1,6 +1,11 @@
 /**
  * Brave Real Browser LSP Server
+ * 
+ * Supports both STDIO and TCP transports:
+ * - STDIO: For direct IDE connections (npm run lsp)
+ * - TCP: For running alongside MCP server (npm run dev)
  */
+const net = require('net');
 const { createConnection, TextDocuments, ProposedFeatures, TextDocumentSyncKind, MarkupKind } = require('vscode-languageserver/node');
 const { TextDocument } = require('vscode-languageserver-textdocument');
 const { TOOLS } = require('../mcp/tools.js');
@@ -12,67 +17,168 @@ const { getRefactorings } = require('./capabilities/refactoring.js');
 const { simulateWorkflow } = require('./capabilities/simulation.js');
 const { getLanguagePack } = require('./utils/i18n.js');
 
-const connection = createConnection(ProposedFeatures.all, process.stdin, process.stdout);
-const documents = new TextDocuments(TextDocument);
-let settings = { language: 'en', maxDiagnostics: 100, enableSnippets: true, enableSimulation: true, enableRefactoring: true };
-
-connection.onInitialize(() => ({
-  capabilities: {
-    textDocumentSync: TextDocumentSyncKind.Incremental,
-    completionProvider: { resolveProvider: true, triggerCharacters: ['.', "'", '"', '(', '{', ' '] },
-    hoverProvider: true,
-    codeActionProvider: true,
-    codeLensProvider: { resolveProvider: true },
-    signatureHelpProvider: { triggerCharacters: ['(', ','] },
-    documentSymbolProvider: true,
-  },
-}));
-
-connection.onDidChangeConfiguration((change) => {
-  if (change.settings?.braveRealBrowser) settings = { ...settings, ...change.settings.braveRealBrowser };
-  documents.all().forEach(validateDocument);
-});
-
-connection.onCompletion((params) => {
-  const doc = documents.get(params.textDocument.uri);
-  return doc ? getCompletions(doc, params.position, TOOLS, getLanguagePack(settings.language), settings) : [];
-});
-
-connection.onCompletionResolve((item) => {
-  const lang = getLanguagePack(settings.language);
-  const tool = TOOLS.find(t => t.name === item.data?.toolName);
-  if (tool && lang.tools[tool.name]) {
-    const tl = lang.tools[tool.name];
-    item.documentation = { kind: MarkupKind.Markdown, value: `### ${tool.emoji} ${tl.label}\n\n${tl.documentation}\n\n**Parameters:**\n${Object.entries(tl.parameters || {}).map(([k, v]) => `- \`${k}\`: ${v}`).join('\n')}` };
+// Default settings
+let settings = { 
+  language: 'en', 
+  maxDiagnostics: 100, 
+  enableSnippets: true, 
+  enableSimulation: true, 
+  enableRefactoring: true 
+};
+
+// LSP port for TCP mode
+const LSP_PORT = process.env.LSP_PORT || 7777;
+
+/**
+ * Setup LSP connection handlers
+ */
+function setupConnection(connection) {
+  const documents = new TextDocuments(TextDocument);
+
+  connection.onInitialize(() => ({
+    capabilities: {
+      textDocumentSync: TextDocumentSyncKind.Incremental,
+      completionProvider: { resolveProvider: true, triggerCharacters: ['.', "'", '"', '(', '{', ' '] },
+      hoverProvider: true,
+      codeActionProvider: true,
+      codeLensProvider: { resolveProvider: true },
+      signatureHelpProvider: { triggerCharacters: ['(', ','] },
+      documentSymbolProvider: true,
+    },
+  }));
+
+  connection.onDidChangeConfiguration((change) => {
+    if (change.settings?.braveRealBrowser) {
+      settings = { ...settings, ...change.settings.braveRealBrowser };
+    }
+    documents.all().forEach((doc) => validateDocument(connection, doc));
+  });
+
+  connection.onCompletion((params) => {
+    const doc = documents.get(params.textDocument.uri);
+    return doc ? getCompletions(doc, params.position, TOOLS, getLanguagePack(settings.language), settings) : [];
+  });
+
+  connection.onCompletionResolve((item) => {
+    const lang = getLanguagePack(settings.language);
+    const tool = TOOLS.find(t => t.name === item.data?.toolName);
+    if (tool && lang.tools[tool.name]) {
+      const tl = lang.tools[tool.name];
+      item.documentation = { 
+        kind: MarkupKind.Markdown, 
+        value: `### ${tool.emoji} ${tl.label}\n\n${tl.documentation}\n\n**Parameters:**\n${Object.entries(tl.parameters || {}).map(([k, v]) => `- \`${k}\`: ${v}`).join('\n')}` 
+      };
+    }
+    return item;
+  });
+
+  connection.onHover((params) => {
+    const doc = documents.get(params.textDocument.uri);
+    return doc ? getHoverInfo(doc, params.position, TOOLS, getLanguagePack(settings.language)) : null;
+  });
+
+  function validateDocument(conn, doc) {
+    conn.sendDiagnostics({ 
+      uri: doc.uri, 
+      diagnostics: getDiagnostics(doc, TOOLS, getLanguagePack(settings.language), settings.maxDiagnostics) 
+    });
   }
-  return item;
-});
 
-connection.onHover((params) => {
-  const doc = documents.get(params.textDocument.uri);
-  return doc ? getHoverInfo(doc, params.position, TOOLS, getLanguagePack(settings.language)) : null;
-});
+  documents.onDidChangeContent((change) => validateDocument(connection, change.document));
+
+  connection.onCodeAction((params) => {
+    const doc = documents.get(params.textDocument.uri);
+    return doc ? getRefactorings(doc, params.range, params.context, TOOLS, getLanguagePack(settings.language)) : [];
+  });
+
+  connection.onCodeLens((params) => {
+    const doc = documents.get(params.textDocument.uri);
+    return doc ? simulateWorkflow(doc, TOOLS, getLanguagePack(settings.language)) : [];
+  });
+
+  connection.onCodeLensResolve((lens) => lens);
 
-function validateDocument(doc) {
-  connection.sendDiagnostics({ uri: doc.uri, diagnostics: getDiagnostics(doc, TOOLS, getLanguagePack(settings.language), settings.maxDiagnostics) });
+  connection.onRequest('braveRealBrowser/snippets', (params) => 
+    getSnippets(params?.category, TOOLS, getLanguagePack(settings.language))
+  );
+
+  documents.listen(connection);
+  connection.listen();
+  
+  return connection;
 }
 
-documents.onDidChangeContent((change) => validateDocument(change.document));
+/**
+ * Start LSP server in STDIO mode
+ */
+function startStdioServer() {
+  const connection = createConnection(ProposedFeatures.all, process.stdin, process.stdout);
+  setupConnection(connection);
+  console.error('🦁 Brave Real Browser LSP Server started (STDIO)');
+  return connection;
+}
 
-connection.onCodeAction((params) => {
-  const doc = documents.get(params.textDocument.uri);
-  return doc ? getRefactorings(doc, params.range, params.context, TOOLS, getLanguagePack(settings.language)) : [];
-});
+/**
+ * Start LSP server in TCP mode
+ */
+function startTcpServer(port = LSP_PORT) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer((socket) => {
+      console.error(`🔌 LSP client connected from ${socket.remoteAddress}`);
+      
+      const connection = createConnection(ProposedFeatures.all, socket, socket);
+      setupConnection(connection);
+      
+      socket.on('close', () => {
+        console.error('🔌 LSP client disconnected');
+      });
+    });
 
-connection.onCodeLens((params) => {
-  const doc = documents.get(params.textDocument.uri);
-  return doc ? simulateWorkflow(doc, TOOLS, getLanguagePack(settings.language)) : [];
-});
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        console.error(`⚠️  LSP port ${port} already in use, trying ${port + 1}...`);
+        server.close();
+        startTcpServer(port + 1).then(resolve).catch(reject);
+      } else {
+        reject(err);
+      }
+    });
 
-connection.onCodeLensResolve((lens) => lens);
+    server.listen(port, '127.0.0.1', () => {
+      console.error(`🦁 Brave Real Browser LSP Server started (TCP: 127.0.0.1:${port})`);
+      resolve({ server, port });
+    });
+  });
+}
 
-connection.onRequest('braveRealBrowser/snippets', (params) => getSnippets(params?.category, TOOLS, getLanguagePack(settings.language)));
+/**
+ * Get transport mode from args or environment
+ */
+function getTransportMode() {
+  if (process.argv.includes('--tcp')) return 'tcp';
+  if (process.argv.includes('--stdio')) return 'stdio';
+  if (process.env.LSP_TRANSPORT === 'tcp') return 'tcp';
+  // Default: STDIO for direct invocation, TCP when embedded
+  return process.env.LSP_EMBEDDED === 'true' ? 'tcp' : 'stdio';
+}
 
-documents.listen(connection);
-connection.listen();
-console.error('🦁 Brave Real Browser LSP Server started');
+// Export for programmatic use
+module.exports = { 
+  startStdioServer, 
+  startTcpServer, 
+  setupConnection,
+  LSP_PORT 
+};
+
+// Auto-start if run directly
+if (require.main === module) {
+  const mode = getTransportMode();
+  if (mode === 'tcp') {
+    startTcpServer().catch(err => {
+      console.error('❌ Failed to start LSP TCP server:', err.message);
+      process.exit(1);
+    });
+  } else {
+    startStdioServer();
+  }
+}

package/src/mcp/handlers.js

@@ -2,6 +2,10 @@
  * Brave Real Browser MCP Server - Tool Handlers
  * 
  * Implementation of all 28 browser automation tools
+ * 
+ * Environment Variables:
+ *   HEADLESS=true   - Run browser in headless mode
+ *   HEADLESS=false  - Run browser in GUI mode (visible)
  */
 
 const path = require('path');
@@ -15,6 +19,61 @@ let networkRecords = [];
 let isRecordingNetwork = false;
 let progressTasks = {};
 
+// Progress notification callback (set by server)
+let progressCallback = null;
+
+/**
+ * Set progress callback for real-time notifications
+ */
+function setProgressCallback(callback) {
+  progressCallback = callback;
+}
+
+/**
+ * Send real-time progress notification
+ */
+function notifyProgress(toolName, status, message, data = {}) {
+  const notification = {
+    tool: toolName,
+    status, // 'started' | 'progress' | 'completed' | 'error'
+    message,
+    timestamp: new Date().toISOString(),
+    ...data
+  };
+  
+  // Log to stderr for visibility
+  const emoji = {
+    started: '🚀',
+    progress: '⏳',
+    completed: '✅',
+    error: '❌'
+  }[status] || '📌';
+  
+  console.error(`${emoji} [${toolName}] ${message}`);
+  
+  // Call progress callback if set
+  if (progressCallback) {
+    progressCallback(notification);
+  }
+  
+  return notification;
+}
+
+/**
+ * Get headless setting from environment
+ */
+function getHeadlessFromEnv() {
+  const envHeadless = process.env.HEADLESS;
+  
+  if (envHeadless === undefined || envHeadless === null || envHeadless === '') {
+    return false; // Default: GUI mode
+  }
+  
+  // Parse string to boolean
+  const value = envHeadless.toLowerCase().trim();
+  return value === 'true' || value === '1' || value === 'yes';
+}
+
 /**
  * Get browser and page instances
  */
@@ -38,9 +97,17 @@ function requireBrowser() {
 const handlers = {
   // 1. Browser Init
   async browser_init(params = {}) {
+    notifyProgress('browser_init', 'started', 'Initializing browser...');
+    
     const { connect } = require('../../lib/cjs/index.js');
     
-    const { headless = false, proxy = {}, turnstile = false, enableBlocker = true } = params;
+    // Get headless from params OR environment variable
+    const envHeadless = getHeadlessFromEnv();
+    const headless = params.headless !== undefined ? params.headless : envHeadless;
+    
+    const { proxy = {}, turnstile = false, enableBlocker = true } = params;
+    
+    notifyProgress('browser_init', 'progress', `Mode: ${headless ? 'Headless' : 'GUI (Visible)'}`, { headless });
     
     const result = await connect({
       headless,
@@ -53,10 +120,18 @@ const handlers = {
     pageInstance = result.page;
     blockerInstance = result.blocker;
     
+    const pid = browserInstance.process()?.pid;
+    
+    notifyProgress('browser_init', 'completed', `Browser started (PID: ${pid})`, { 
+      headless, 
+      pid,
+      blockerEnabled: enableBlocker 
+    });
+    
     return {
       success: true,
-      message: 'Browser initialized successfully',
-      pid: browserInstance.process()?.pid,
+      message: `Browser initialized in ${headless ? 'headless' : 'GUI'} mode`,
+      pid,
       headless,
       blockerEnabled: enableBlocker
     };
@@ -67,12 +142,18 @@ const handlers = {
     const { page } = requireBrowser();
     const { url, waitUntil = 'networkidle2', timeout = 30000 } = params;
     
+    notifyProgress('navigate', 'started', `Navigating to: ${url}`);
+    
     await page.goto(url, { waitUntil, timeout });
     
+    const title = await page.title();
+    
+    notifyProgress('navigate', 'completed', `Loaded: ${title}`, { url: page.url(), title });
+    
     return {
       success: true,
       url: page.url(),
-      title: await page.title()
+      title
     };
   },
 
@@ -81,11 +162,14 @@ const handlers = {
     const { page } = requireBrowser();
     const { format = 'text', selector } = params;
     
+    notifyProgress('get_content', 'started', `Extracting ${format} content${selector ? ` from ${selector}` : ''}`);
+    
     let content;
     
     if (selector) {
       const element = await page.$(selector);
       if (!element) {
+        notifyProgress('get_content', 'error', `Element not found: ${selector}`);
         return { success: false, error: `Element not found: ${selector}` };
       }
       
@@ -99,7 +183,6 @@ const handlers = {
         content = await page.content();
       } else if (format === 'markdown') {
         content = await page.evaluate(() => {
-          // Simple HTML to Markdown conversion
           const body = document.body.innerText;
           return body;
         });
@@ -108,6 +191,8 @@ const handlers = {
       }
     }
     
+    notifyProgress('get_content', 'completed', `Extracted ${content.length} characters`, { format, length: content.length });
+    
     return {
       success: true,
       content,
@@ -121,6 +206,8 @@ const handlers = {
     const { page } = requireBrowser();
     const { type = 'timeout', value, timeout = 30000 } = params;
     
+    notifyProgress('wait', 'started', `Waiting for ${type}: ${value}`);
+    
     switch (type) {
       case 'selector':
         await page.waitForSelector(value, { timeout });
@@ -136,6 +223,8 @@ const handlers = {
         await new Promise(r => setTimeout(r, parseInt(value) || 1000));
     }
     
+    notifyProgress('wait', 'completed', `Wait completed: ${type}`, { type, value });
+    
     return { success: true, type, value };
   },
 
@@ -144,19 +233,23 @@ const handlers = {
     const { page } = requireBrowser();
     const { selector, humanLike = true, clickCount = 1, delay = 0 } = params;
     
+    notifyProgress('click', 'started', `Clicking: ${selector}`);
+    
     if (humanLike) {
       try {
         const { createCursor } = require('ghost-cursor');
         const cursor = createCursor(page);
         await cursor.click(selector);
+        notifyProgress('click', 'progress', 'Used human-like cursor movement');
       } catch (e) {
-        // Fallback to regular click
         await page.click(selector, { clickCount, delay });
       }
     } else {
       await page.click(selector, { clickCount, delay });
     }
     
+    notifyProgress('click', 'completed', `Clicked: ${selector}`, { selector, humanLike });
+    
     return { success: true, selector, clicked: true };
   },
 
@@ -165,13 +258,18 @@ const handlers = {
     const { page } = requireBrowser();
     const { selector, text, delay = 50, clear = false } = params;
     
+    notifyProgress('type', 'started', `Typing ${text.length} characters into ${selector}`);
+    
     if (clear) {
       await page.click(selector, { clickCount: 3 });
       await page.keyboard.press('Backspace');
+      notifyProgress('type', 'progress', 'Cleared existing text');
     }
     
     await page.type(selector, text, { delay });
     
+    notifyProgress('type', 'completed', `Typed ${text.length} characters`, { selector, textLength: text.length });
+    
     return { success: true, selector, textLength: text.length };
   },
 
@@ -179,12 +277,16 @@ const handlers = {
   async browser_close(params = {}) {
     const { force = false } = params;
     
+    notifyProgress('browser_close', 'started', 'Closing browser...');
+    
     if (browserInstance) {
       try {
         await browserInstance.close();
+        notifyProgress('browser_close', 'progress', 'Browser closed gracefully');
       } catch (e) {
         if (force) {
           browserInstance.process()?.kill('SIGKILL');
+          notifyProgress('browser_close', 'progress', 'Browser force killed');
         }
       }
       browserInstance = null;
@@ -192,6 +294,8 @@ const handlers = {
       blockerInstance = null;
     }
     
+    notifyProgress('browser_close', 'completed', 'Browser closed');
+    
     return { success: true, message: 'Browser closed' };
   },
 
@@ -200,22 +304,32 @@ const handlers = {
     const { page } = requireBrowser();
     const { type = 'auto', timeout = 30000 } = params;
     
-    // Wait for turnstile/captcha to be solved (handled by turnstile option in connect)
+    notifyProgress('solve_captcha', 'started', `Solving ${type} captcha...`);
+    
     const start = Date.now();
+    let attempts = 0;
     
     while (Date.now() - start < timeout) {
+      attempts++;
+      
       const turnstileToken = await page.evaluate(() => {
         const input = document.querySelector('input[name="cf-turnstile-response"]');
         return input ? input.value : null;
       });
       
       if (turnstileToken) {
+        notifyProgress('solve_captcha', 'completed', `Captcha solved after ${attempts} checks`, { type: 'turnstile', attempts });
         return { success: true, type: 'turnstile', solved: true };
       }
       
+      if (attempts % 10 === 0) {
+        notifyProgress('solve_captcha', 'progress', `Still solving... (${attempts} checks)`, { attempts });
+      }
+      
       await new Promise(r => setTimeout(r, 500));
     }
     
+    notifyProgress('solve_captcha', 'error', 'Captcha solving timeout');
     return { success: false, error: 'Captcha solving timeout' };
   },
 
@@ -229,11 +343,15 @@ const handlers = {
       ? (Math.random() > 0.5 ? 'down' : 'up') 
       : direction;
     
+    notifyProgress('random_scroll', 'started', `Scrolling ${scrollDirection} ${scrollAmount}px`);
+    
     await page.evaluate(({ scrollAmount, scrollDirection, smooth }) => {
       const y = scrollDirection === 'down' ? scrollAmount : -scrollAmount;
       window.scrollBy({ top: y, behavior: smooth ? 'smooth' : 'auto' });
     }, { scrollAmount, scrollDirection, smooth });
     
+    notifyProgress('random_scroll', 'completed', `Scrolled ${scrollDirection} ${scrollAmount}px`, { direction: scrollDirection, amount: scrollAmount });
+    
     return { success: true, direction: scrollDirection, amount: scrollAmount };
   },
 
@@ -242,6 +360,8 @@ const handlers = {
     const { page } = requireBrowser();
     const { selector, xpath, text, multiple = false } = params;
     
+    notifyProgress('find_element', 'started', `Finding element: ${selector || xpath || text}`);
+    
     let elements = [];
     
     if (selector) {
@@ -278,6 +398,8 @@ const handlers = {
       );
     }
     
+    notifyProgress('find_element', 'completed', `Found ${elements.length} element(s)`, { found: elements.length });
+    
     return { success: true, found: elements.length, elements };
   },
 
@@ -286,6 +408,8 @@ const handlers = {
     const { page } = requireBrowser();
     const { filename, selector, includeImages = true, includeMeta = true } = params;
     
+    notifyProgress('save_content_as_markdown', 'started', `Saving to: ${filename}`);
+    
     let markdown = '';
     
     if (includeMeta) {
@@ -304,6 +428,8 @@ const handlers = {
     const outputPath = path.resolve(filename);
     fs.writeFileSync(outputPath, markdown);
     
+    notifyProgress('save_content_as_markdown', 'completed', `Saved ${markdown.length} bytes to ${filename}`, { filename: outputPath, size: markdown.length });
+    
     return { success: true, filename: outputPath, size: markdown.length };
   },
 
@@ -312,6 +438,8 @@ const handlers = {
     const { page } = requireBrowser();
     const { url, maxRedirects = 10, includeHeaders = false } = params;
     
+    notifyProgress('redirect_tracer', 'started', `Tracing redirects for: ${url}`);
+    
     const redirects = [];
     
     const responseHandler = response => {
@@ -321,6 +449,7 @@ const handlers = {
           status: response.status(),
           headers: includeHeaders ? response.headers() : undefined
         });
+        notifyProgress('redirect_tracer', 'progress', `Redirect ${redirects.length}: ${response.status()}`, { status: response.status() });
       }
     };
     
@@ -330,6 +459,8 @@ const handlers = {
     
     page.off('response', responseHandler);
     
+    notifyProgress('redirect_tracer', 'completed', `Found ${redirects.length} redirects`, { redirectCount: redirects.length, finalUrl: page.url() });
+    
     return {
       success: true,
       originalUrl: url,
@@ -344,6 +475,8 @@ const handlers = {
     const { page } = requireBrowser();
     const { pattern, flags = 'gi', source = 'html' } = params;
     
+    notifyProgress('search_regex', 'started', `Searching pattern: ${pattern}`);
+    
     let content;
     if (source === 'html') {
       content = await page.content();
@@ -356,6 +489,8 @@ const handlers = {
     const regex = new RegExp(pattern, flags);
     const matches = content.match(regex) || [];
     
+    notifyProgress('search_regex', 'completed', `Found ${matches.length} matches`, { matchCount: matches.length });
+    
     return { success: true, pattern, matchCount: matches.length, matches: matches.slice(0, 100) };
   },
 
@@ -364,6 +499,8 @@ const handlers = {
     const { page } = requireBrowser();
     const { source = 'page', selector, jsonPath } = params;
     
+    notifyProgress('extract_json', 'started', `Extracting JSON from: ${source}`);
+    
     let jsonData = [];
     
     if (source === 'ld+json') {
@@ -384,6 +521,8 @@ const handlers = {
       try { jsonData = [JSON.parse(text)]; } catch {}
     }
     
+    notifyProgress('extract_json', 'completed', `Extracted ${jsonData.length} JSON objects`, { count: jsonData.length });
+    
     return { success: true, source, count: jsonData.length, data: jsonData };
   },
 
@@ -392,6 +531,8 @@ const handlers = {
     const { page } = requireBrowser();
     const { types = ['all'] } = params;
     
+    notifyProgress('scrape_meta_tags', 'started', 'Extracting meta tags...');
+    
     const meta = await page.evaluate(() => {
       const result = { meta: {}, og: {}, twitter: {} };
       
@@ -415,6 +556,9 @@ const handlers = {
       return result;
     });
     
+    const tagCount = Object.keys(meta.meta).length + Object.keys(meta.og).length + Object.keys(meta.twitter).length;
+    notifyProgress('scrape_meta_tags', 'completed', `Extracted ${tagCount} meta tags`, { tagCount });
+    
     return { success: true, ...meta };
   },
 
@@ -423,6 +567,8 @@ const handlers = {
     const { page } = requireBrowser();
     const { key, modifiers = [], count = 1 } = params;
     
+    notifyProgress('press_key', 'started', `Pressing: ${modifiers.length ? modifiers.join('+') + '+' : ''}${key} x${count}`);
+    
     for (let i = 0; i < count; i++) {
       if (modifiers.length > 0) {
         const keyCombo = [...modifiers, key].join('+');
@@ -432,6 +578,8 @@ const handlers = {
       }
     }
     
+    notifyProgress('press_key', 'completed', `Pressed ${key} ${count} time(s)`, { key, modifiers, count });
+    
     return { success: true, key, modifiers, count };
   },
 
@@ -442,16 +590,20 @@ const handlers = {
     switch (action) {
       case 'start':
         progressTasks[taskName] = { progress: 0, startTime: Date.now() };
+        notifyProgress('progress_tracker', 'started', `Task started: ${taskName}`);
         break;
       case 'update':
         if (progressTasks[taskName]) {
           progressTasks[taskName].progress = progress;
+          notifyProgress('progress_tracker', 'progress', `${taskName}: ${progress}%`, { taskName, progress });
         }
         break;
       case 'complete':
         if (progressTasks[taskName]) {
           progressTasks[taskName].progress = 100;
           progressTasks[taskName].endTime = Date.now();
+          const duration = progressTasks[taskName].endTime - progressTasks[taskName].startTime;
+          notifyProgress('progress_tracker', 'completed', `${taskName} completed in ${duration}ms`, { taskName, duration });
         }
         break;
     }
@@ -464,6 +616,8 @@ const handlers = {
     const { page } = requireBrowser();
     const { types = ['all'], detailed = true } = params;
     
+    notifyProgress('deep_analysis', 'started', 'Analyzing page...');
+    
     const analysis = await page.evaluate(() => {
       const result = {
         seo: {
@@ -495,6 +649,8 @@ const handlers = {
       return result;
     });
     
+    notifyProgress('deep_analysis', 'completed', `Analysis complete: ${analysis.performance.domElements} DOM elements`, { domElements: analysis.performance.domElements });
+    
     return { success: true, url: page.url(), analysis };
   },
 
@@ -517,12 +673,15 @@ const handlers = {
             });
           }
         });
+        notifyProgress('network_recorder', 'started', 'Network recording started');
         break;
       case 'stop':
         isRecordingNetwork = false;
+        notifyProgress('network_recorder', 'completed', `Recording stopped: ${networkRecords.length} requests captured`);
         break;
       case 'clear':
         networkRecords = [];
+        notifyProgress('network_recorder', 'completed', 'Network records cleared');
         break;
     }
     
@@ -543,6 +702,8 @@ const handlers = {
     const { page } = requireBrowser();
     const { types = ['all'], selector, includeText = true } = params;
     
+    notifyProgress('link_harvester', 'started', 'Harvesting links...');
+    
     const currentHost = new URL(page.url()).hostname;
     
     let links = await page.$$eval(selector ? `${selector} a` : 'a', (anchors, includeText) => 
@@ -566,6 +727,8 @@ const handlers = {
       });
     }
     
+    notifyProgress('link_harvester', 'completed', `Found ${links.length} links`, { count: links.length });
+    
     return { success: true, count: links.length, links };
   },
 
@@ -574,24 +737,30 @@ const handlers = {
     const { page } = requireBrowser();
     const { action = 'get', name, value, domain, expires } = params;
     
+    notifyProgress('cookie_manager', 'started', `Cookie action: ${action}`);
+    
     switch (action) {
       case 'get':
         const cookies = await page.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 });
+        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 'clear':
         const allCookies = await page.cookies();
         await page.deleteCookie(...allCookies);
+        notifyProgress('cookie_manager', 'completed', `Cleared ${allCookies.length} cookies`);
         return { success: true, message: `Cleared ${allCookies.length} cookies` };
     }
     
@@ -603,12 +772,12 @@ const handlers = {
     const { page } = requireBrowser();
     const { url, filename, directory = './downloads' } = params;
     
-    // Ensure directory exists
+    notifyProgress('file_downloader', 'started', `Downloading: ${url}`);
+    
     if (!fs.existsSync(directory)) {
       fs.mkdirSync(directory, { recursive: true });
     }
     
-    // Use page to download
     const response = await page.goto(url, { waitUntil: 'networkidle2' });
     const buffer = await response.buffer();
     
@@ -617,6 +786,8 @@ const handlers = {
     
     fs.writeFileSync(outputPath, buffer);
     
+    notifyProgress('file_downloader', 'completed', `Downloaded: ${outputFilename} (${buffer.length} bytes)`, { filename: outputPath, size: buffer.length });
+    
     return { success: true, filename: outputPath, size: buffer.length };
   },
 
@@ -625,10 +796,13 @@ const handlers = {
     const { page } = requireBrowser();
     const { action = 'list', selector, index } = params;
     
+    notifyProgress('iframe_handler', 'started', `iFrame action: ${action}`);
+    
     const frames = page.frames();
     
     switch (action) {
       case 'list':
+        notifyProgress('iframe_handler', 'completed', `Found ${frames.length} frames`);
         return {
           success: true,
           count: frames.length,
@@ -641,8 +815,10 @@ const handlers = {
           : frames[index];
         
         if (targetFrame) {
+          notifyProgress('iframe_handler', 'completed', `Switched to frame: ${targetFrame.url()}`);
           return { success: true, switched: true, url: targetFrame.url() };
         }
+        notifyProgress('iframe_handler', 'error', 'Frame not found');
         return { success: false, error: 'Frame not found' };
       
       case 'content':
@@ -652,11 +828,13 @@ const handlers = {
         
         if (frame) {
           const content = await frame.content();
+          notifyProgress('iframe_handler', 'completed', `Got frame content: ${content.length} chars`);
           return { success: true, content };
         }
         return { success: false, error: 'Frame not found' };
       
       case 'exit':
+        notifyProgress('iframe_handler', 'completed', 'Returned to main frame');
         return { success: true, message: 'Returned to main frame' };
     }
     
@@ -668,22 +846,21 @@ const handlers = {
     const { page } = requireBrowser();
     const { types = ['all'], quality = 'best' } = params;
     
+    notifyProgress('stream_extractor', 'started', 'Extracting streams...');
+    
     const streams = await page.evaluate(() => {
       const result = { video: [], audio: [], hls: [], dash: [] };
       
-      // Video elements
       document.querySelectorAll('video source, video').forEach(el => {
         const src = el.src || el.getAttribute('src');
         if (src) result.video.push({ src, type: el.type || 'video' });
       });
       
-      // Audio elements
       document.querySelectorAll('audio source, audio').forEach(el => {
         const src = el.src || el.getAttribute('src');
         if (src) result.audio.push({ src, type: el.type || 'audio' });
       });
       
-      // Find HLS/DASH in scripts
       const scripts = [...document.querySelectorAll('script')].map(s => s.textContent).join('\n');
       const hlsMatches = scripts.match(/https?:\/\/[^\s"']+\.m3u8[^\s"']*/gi) || [];
       const dashMatches = scripts.match(/https?:\/\/[^\s"']+\.mpd[^\s"']*/gi) || [];
@@ -694,6 +871,9 @@ const handlers = {
       return result;
     });
     
+    const totalStreams = streams.video.length + streams.audio.length + streams.hls.length + streams.dash.length;
+    notifyProgress('stream_extractor', 'completed', `Found ${totalStreams} streams`, { totalStreams });
+    
     return { success: true, streams };
   },
 
@@ -702,8 +882,11 @@ const handlers = {
     const { page } = requireBrowser();
     const { selector, waitForJS = true, timeout = 10000 } = params;
     
+    notifyProgress('js_scrape', 'started', `Scraping: ${selector}`);
+    
     if (waitForJS) {
       await page.waitForSelector(selector, { timeout });
+      notifyProgress('js_scrape', 'progress', 'Element found, extracting content...');
     }
     
     const content = await page.$eval(selector, el => ({
@@ -712,6 +895,8 @@ const handlers = {
       attributes: Object.fromEntries([...el.attributes].map(a => [a.name, a.value]))
     }));
     
+    notifyProgress('js_scrape', 'completed', `Scraped ${content.text.length} characters`, { selector });
+    
     return { success: true, selector, content };
   },
 
@@ -720,8 +905,12 @@ const handlers = {
     const { page } = requireBrowser();
     const { code, returnValue = true } = params;
     
+    notifyProgress('execute_js', 'started', 'Executing JavaScript...');
+    
     const result = await page.evaluate(code);
     
+    notifyProgress('execute_js', 'completed', 'JavaScript executed', { hasResult: result !== undefined });
+    
     return { success: true, result: returnValue ? result : undefined };
   },
 
@@ -730,8 +919,9 @@ const handlers = {
     const { page } = requireBrowser();
     const { playerType = 'auto', action = 'info' } = params;
     
+    notifyProgress('player_api_hook', 'started', `Player ${action}: ${playerType}`);
+    
     const playerInfo = await page.evaluate(({ playerType, action }) => {
-      // Try to detect player
       if (window.player || window.videoPlayer || window.jwplayer) {
         const player = window.player || window.videoPlayer || (window.jwplayer && window.jwplayer());
         
@@ -763,7 +953,6 @@ const handlers = {
         }
       }
       
-      // Fallback to HTML5 video
       const video = document.querySelector('video');
       if (video) {
         if (action === 'play') video.play();
@@ -782,6 +971,8 @@ const handlers = {
       return { detected: false };
     }, { playerType, action });
     
+    notifyProgress('player_api_hook', 'completed', playerInfo.detected ? `Player detected: ${playerInfo.type}` : 'No player found', { detected: playerInfo.detected });
+    
     return { success: true, ...playerInfo };
   },
 
@@ -791,6 +982,11 @@ const handlers = {
     const { selector, data, submit = false, humanLike = true } = params;
     
     const formSelector = selector || 'form';
+    const fields = Object.keys(data || {});
+    
+    notifyProgress('form_automator', 'started', `Filling form with ${fields.length} fields`);
+    
+    let filledCount = 0;
     
     for (const [field, value] of Object.entries(data || {})) {
       const inputSelector = `${formSelector} [name="${field}"], ${formSelector} #${field}, ${formSelector} [placeholder*="${field}" i]`;
@@ -813,6 +1009,8 @@ const handlers = {
               await page.type(inputSelector, String(value));
             }
           }
+          filledCount++;
+          notifyProgress('form_automator', 'progress', `Filled: ${field}`, { field, filledCount });
         }
       } catch (e) {
         // Field not found, continue
@@ -821,9 +1019,12 @@ const handlers = {
     
     if (submit) {
       await page.click(`${formSelector} [type="submit"], ${formSelector} button`);
+      notifyProgress('form_automator', 'progress', 'Form submitted');
     }
     
-    return { success: true, formSelector, fieldsProcessed: Object.keys(data || {}).length, submitted: submit };
+    notifyProgress('form_automator', 'completed', `Filled ${filledCount}/${fields.length} fields`, { filledCount, submitted: submit });
+    
+    return { success: true, formSelector, fieldsProcessed: filledCount, submitted: submit };
   }
 };
 
@@ -834,12 +1035,14 @@ async function executeTool(name, params = {}) {
   const handler = handlers[name];
   
   if (!handler) {
+    notifyProgress(name, 'error', `Unknown tool: ${name}`);
     return { success: false, error: `Unknown tool: ${name}` };
   }
   
   try {
     return await handler(params);
   } catch (error) {
+    notifyProgress(name, 'error', error.message);
     return { success: false, error: error.message };
   }
 }
@@ -865,5 +1068,8 @@ module.exports = {
   executeTool,
   cleanup,
   getState,
-  requireBrowser
+  requireBrowser,
+  setProgressCallback,
+  notifyProgress,
+  getHeadlessFromEnv
 };