@bsbofmusic/agent-browser-mcp-opencode 1.0.1 → 2.0.0

package/README.md

@@ -1,80 +1,54 @@
 # @bsbofmusic/agent-browser-mcp-opencode
 
-MCP Server for Vercel agent-browser - browser automation CLI for AI agents.
+<div align="center">
 
----
-
-## What is This?
+  **MCP Server for agent-browser**  
+  <sub><sup>Browser automation for• AI agents</sup></sub>
 
-This is an MCP (Model Context Protocol) wrapper for [agent-browser](https://github.com/vercel-labs/agent-browser), providing browser automation capabilities for AI assistants like OpenCode, Claude Code, and others.
+  [![MCP](https://img.shields.io/badge/MCP-blue)](https://img.shields.io/badge/MCP-blue)
+  [![License](https://img.shields.io/badge/License-Apache%202.0-blue)](https://img.shields.io/badge/License-Apache%202.0-blue)
+  [![Node](https://img.shields.io/badge/node-%3E218.0.0-blue)](https://img.shields.io/badge/node-%3E218.0.0-blue)
+  [![NPM](https://img.shields.io/npm/v/@bsbofmusic%2Fagent-browser-mcp-opencode)](https://img.shields.io/npm/v/@bsbofmusic%2Fagent-browser-mcp-opencode)
 
-### Use Cases
-
-- **AI Testing**: Automate web testing workflows with AI agents
-- **Web Scraping**: Extract data from dynamic web pages
-- **Form Automation**: Fill forms, click buttons, navigate pages
-- **Visual Testing**: Take screenshots, compare snapshots
+</div>
 
 ---
 
-## One-Click Enable
+<div align="center">
 
-### OpenCode Configuration
+  **Browser automation for AI agents via Model Context Protocol**
 
-Add to your `opencode.json`:
+</div>
 
-```json
-{
-  "mcp": {
-    "agent-browser-mcp-opencode": {
-      "command": ["npx", "-y", "@bsbofmusic/agent-browser-mcp-opencode"],
-      "enabled": true,
-      "type": "local"
-    }
-  }
-}
-```
+---
 
-### Direct Run
+## Quick Start
 
 ```bash
 npx @bsbofmusic/agent-browser-mcp-opencode
 ```
 
-### Docker
-
-```bash
-docker run -it --rm bsbofmusic/agent-browser-mcp-opencode
-```
-
-### Global Install
-
-```bash
-npm install -g @bsbofmusic/agent-browser-mcp-opencode
-agent-browser-mcp-opencode
-```
-
 ---
 
-## Tool List
+## Tools
 
 ### Core Tools
 
 | Tool | Description |
 |------|-------------|
-| `browser_ensure` | Manually trigger full repair (install/upgrade) |
-| `browser_doctor` | Diagnose issues with actionable nextSteps |
+| `browser_ensure` | Install/repair agent-browser & Chromium |
+| `browser_doctor` | Diagnose issues with fix recommendations |
 | `browser_help` | List all available commands |
 | `browser_version` | Show version info |
 | `browser_exec` | Execute any agent-browser CLI command |
 
-### Structured Actions
+### Action Tools
 
 | Tool | Description |
 |------|-------------|
 | `browser_open` | Navigate to URL |
 | `browser_snapshot` | Get accessibility tree with refs |
-| `browser_click` | Click element (@e1 or CSS selector) |
+| `browser_click` | Click element |
 | `browser_fill` | Fill form field |
 | `browser_screenshot` | Take screenshot |
 | `browser_close` | Close browser |
@@ -85,69 +59,49 @@ agent-browser-mcp-opencode
 
 ---
 
-## Schema Examples
+## Usage Examples
 
-### browser_open
+### Basic Workflow
 
-**Input:**
 ```json
-{
-  "name": "browser_open",
-  "arguments": {"url": "https://example.com"}
-}
-```
+// 1. Navigate
+{"name": "browser_open", "arguments": {"url": "https://example.com"}}
 
-**Output:**
-```json
-{
-  "ok": true,
-  "url": "https://example.com",
-  "duration": 2341
-}
-```
+// 2. Get interactive elements
+{"name": "browser_snapshot", "arguments": {"interactive": true}}
 
-### browser_snapshot
-
-**Input:**
-```json
-{
-  "name": "browser_snapshot",
-  "arguments": {"interactive": true, "compact": true}
-}
+// 3. Click element
+{"name": "browser_click", "arguments": {"selector": "@e1"}}
 ```
 
-**Output:**
+### Semantic Locator
+
 ```json
 {
-  "ok": true,
-  "output": {
-    "success": true,
-    "data": {
-      "snapshot": "- heading \"Example\" [ref=e1]\n  - button \"Submit\" [ref=e2]"
-    }
-  },
-  "duration": 1234
+  "name": "browser_find",
+  "arguments": {
+    "type": "role",
+    "value": "button",
+    "action": "click",
+    "name": "Submit"
+  }
 }
 ```
 
-### browser_exec
+### Using browser_exec
 
-**Input:**
 ```json
 {
   "name": "browser_exec",
   "arguments": {
-    "command": "open example.com && snapshot -i",
-    "timeoutMs": 60000
+    "command": "open example.com && snapshot -i && click #submit"
   }
 }
 ```
 
 ---
 
-## Auto-Update Strategy
-
-### Environment Variables
+## Auto-Update
 
 | Variable | Default | Description |
 |----------|---------|-------------|
@@ -155,66 +109,47 @@ agent-browser-mcp-opencode
 | `UPDATE_STRATEGY` | `simple` | `atomic` or `simple` |
 | `LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug` |
 
-### Strategies
-
-**Simple (default):**
-- Direct overwrite installation
-- No rollback capability
-
-**Atomic:**
-- Uses `runtime_active/` + `runtime_staging/` directories
-- Validates before switching
-- Rolls back on failure
-
 ---
 
 ## Runtime Directories
 
-| Directory | Location | Purpose |
+| Directory | Location |
 |-----------|----------|---------|
 | Config | `~/.agent-browser/` | User configuration |
 | Sessions | `~/.agent-browser/sessions/` | Saved auth states |
 | Cache | System temp | Temporary files |
 
-These directories are auto-created on first run and are rebuildable.
-
 ---
 
 ## Troubleshooting
 
-### Run browser_doctor
+### Run Diagnostics
 
 ```json
-{
-  "name": "browser_doctor"
-}
+{"name": "browser_doctor"}
 ```
 
-**Output includes:**
-- Issue categories: network/permissions/dependencies/system_libraries/executable/browser/auth
-- Severity: critical/high/medium
-- nextSteps: actionable fix recommendations
+**Common Issues**
 
-### Common Issues
+| Issue | Solution |
+|-------|----------|
+| agent-browser not installed | Run `browser_ensure` or `npx agent-browser install` |
+| Chromium not installed | Run `npx agent-browser install` |
+| Permission errors | Check npm global directory permissions |
 
-1. **agent-browser not installed**
-   - Run: `browser_ensure`
-   - Or: `npx agent-browser install`
-
-2. **Chromium not installed**
-   - Run: `npx agent-browser install`
+---
 
-3. **Permission errors**
-   - Check npm global directory permissions
-   - Consider using npx instead
+## Platform Compatibility
 
-4. **Network issues**
-   - Set npm mirror: `npm config set registry https://registry.npmmirror.com`
-   - Check proxy: `npm config get proxy`
+| Platform | Status | Notes |
+|--------|--------|-------|
+| Windows | ⚠️ Partial | agent-browser daemon has socket issues. Use npx or Playwright as alternative |
+| macOS | ✅ Full | Native binary works perfectly |
+| Linux | ✅ Full | Native binary works perfectly |
 
 ---
 
-## Verification Plan
+## Verification
 
 ### 6.1 One-Click Deployment
 
@@ -222,17 +157,13 @@ These directories are auto-created on first run and are rebuildable.
 npx @bsbofmusic/agent-browser-mcp-opencode
 ```
 
-**Expected:** Auto-installs dependencies without manual steps.
+**Expected**: Auto-installs dependencies without manual steps.
 
 ### 6.2 Capability Coverage
 
-Test with 5+ core commands:
-- `browser_open` → navigates to URL
-- `browser_snapshot` → returns accessibility tree with refs
-- `browser_click @e1` → clicks element
-- `browser_fill @e2 "test"` → fills form
-- `browser_screenshot` → captures image
-- `browser_exec` → passes through all CLI commands
+All 15 tools available:
+- 4 core management tools (ensure/doctor/help/version/exec)
+- 11 structured action tools (open/snapshot/click/fill/screenshot/close/get_text/find/wait/tab)
 
 ### 6.3 Stability
 
@@ -247,8 +178,7 @@ Test with 5+ core commands:
 
 ### 6.5 Deployment Ready
 
-- No manual config after first enable
-- Survives MCP/Agent restart
+No manual config after first enable. Survives MCP/Agent restart.
 
 ### 6.6 Failure Scenarios
 
@@ -262,40 +192,28 @@ Test with 5+ core commands:
 
 ## Wrapper Declaration
 
-This project is a wrapper for **agent-browser** by Vercel Labs.
+This project is a **wrapper** for **agent-browser** by Vercel Labs.
 
 - **Upstream**: https://github.com/vercel-labs/agent-browser
 - **License**: Apache-2.0
-- This is NOT an official upstream release
+- This is **NOT** an official upstream release
 - Upstream trademarks/copyrights belong to respective owners
 
 See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for license details.
 
 ---
 
-## Upstream License
-
-agent-browser is licensed under **Apache-2.0**.
-
-This project includes upstream code per Apache-2.0 requirements.
+## License
 
----
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](https://img.shields.io/badge/License-Apache%202.0-blue)
 
-## Version History
+Apache-2.0 License
 
-See [CHANGELOG.md](./CHANGELOG.md)
+Copyright (c) 2024-2025 bsbofmusic
 
 ---
 
 ## Support
 
-- MCP issues: https://github.com/issues
-- agent-browser upstream: https://github.com/vercel-labs/agent-browser/issues
-
----
-
-## License
-
-Apache-2.0 License
-
-Copyright (c) 2024-2025 bsbofmusic
+- **MCP issues**: https://github.com/issues
+- **agent-browser upstream**: https://github.com/vercel-labs/agent-browser/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsbofmusic/agent-browser-mcp-opencode",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "MCP server for Vercel agent-browser - browser automation CLI for AI agents",
   "main": "index.js",
   "type": "module",
@@ -25,6 +25,7 @@
   "author": "bsbofmusic",
   "license": "Apache-2.0",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "execa": "^9.5.2",
     "semver": "^7.7.1"
   },

package/src/ensure.js

@@ -14,9 +14,13 @@ const ALWAYS_LATEST = process.env.ALWAYS_LATEST !== '0';
 const UPDATE_STRATEGY = process.env.UPDATE_STRATEGY || 'simple';
 const LOG_LEVEL = process.env.LOG_LEVEL || 'info';
 const LOCK_FILE = path.join(os.tmpdir(), 'agent-browser-mcp.lock');
+const RUNTIME_DIR = process.env.RUNTIME_DIR || path.join(os.homedir(), '.agent-browser', 'mcp');
+const ACTIVE_DIR = path.join(RUNTIME_DIR, 'active');
+const STAGING_DIR = path.join(RUNTIME_DIR, 'staging');
 
-const MCP_VERSION = '1.0.0';
+const MCP_VERSION = '2.0.0';
 const MIN_NODE_VERSION = '18.0.0';
+const AGENT_BROWSER_PACKAGE = 'agent-browser@latest';
 
 function log(level, message, data = null) {
   const levels = { error: 0, warn: 1, info: 2, debug: 3 };
@@ -44,12 +48,13 @@ function execPromise(command, options = {}) {
 }
 
 async function acquireLock() {
-  const maxWait = 30000;
+  const maxWait = 60000;
   const start = Date.now();
   
   while (true) {
     try {
       if (!fs.existsSync(LOCK_FILE)) {
+        fs.mkdirSync(path.dirname(LOCK_FILE), { recursive: true });
         fs.writeFileSync(LOCK_FILE, `${process.pid}:${Date.now()}`);
         log('debug', 'Lock acquired', { pid: process.pid });
         return true;
@@ -78,7 +83,7 @@ async function acquireLock() {
     }
     
     if (Date.now() - start > maxWait) {
-      throw new Error('Failed to acquire lock after 30 seconds');
+      throw new Error('Failed to acquire lock after 60 seconds');
     }
   }
 }
@@ -86,14 +91,71 @@ async function acquireLock() {
 function releaseLock() {
   try {
     if (fs.existsSync(LOCK_FILE)) {
-      fs.unlinkSync(LOCK_FILE);
-      log('debug', 'Lock released');
+      const lockContent = fs.readFileSync(LOCK_FILE, 'utf8');
+      const [lockPid] = lockContent.split(':');
+      if (lockPid === process.pid.toString()) {
+        fs.unlinkSync(LOCK_FILE);
+        log('debug', 'Lock released');
+      }
     }
   } catch (e) {
     log('warn', 'Failed to release lock', { error: e.message });
   }
 }
 
+function isWindows() {
+  return os.platform() === 'win32';
+}
+
+function getAgentBrowserCommand() {
+  try {
+    if (isWindows()) {
+      execSync('where agent-browser', { stdio: 'ignore' });
+      return 'agent-browser.cmd';
+    } else {
+      execSync('which agent-browser', { stdio: 'ignore' });
+      return 'agent-browser';
+    }
+  } catch (e) {
+    return null;
+  }
+}
+
+export async function runAgentBrowserCommand(command, options = {}) {
+  const cmd = getAgentBrowserCommand();
+  const useNpx = !cmd || options.forceNpx;
+  
+  let fullCommand;
+  if (useNpx) {
+    fullCommand = `npx -y ${AGENT_BROWSER_PACKAGE} ${command}`;
+  } else {
+    fullCommand = `${cmd} ${command}`;
+  }
+  
+  log('debug', 'Running command', { fullCommand, useNpx });
+  
+  try {
+    const stdout = execSync(fullCommand, {
+      encoding: 'utf8',
+      timeout: options.timeout || 60000,
+      ...options,
+    });
+    return { ok: true, stdout, stderr: '', useNpx };
+  } catch (error) {
+    if (!useNpx) {
+      log('warn', 'Global command failed, trying npx fallback');
+      return runAgentBrowserCommand(command, { ...options, forceNpx: true });
+    }
+    return {
+      ok: false,
+      stdout: error.stdout || '',
+      stderr: error.stderr || error.message,
+      error: error.message,
+      useNpx: true,
+    };
+  }
+}
+
 async function checkNodeVersion() {
   const currentVersion = process.version;
   if (!semver.gte(currentVersion, MIN_NODE_VERSION)) {
@@ -102,22 +164,19 @@ async function checkNodeVersion() {
   return { ok: true, version: currentVersion };
 }
 
-async function checkNpmAvailable() {
-  try {
-    execSync('npm --version', { stdio: 'ignore' });
-    return { ok: true };
-  } catch (e) {
-    return { ok: false, error: 'npm is not available' };
-  }
-}
-
 async function installAgentBrowser() {
   const logs = [];
   
-  log('info', 'Installing agent-browser globally...');
+  log('info', 'Installing agent-browser...');
   logs.push('Step 1: Install agent-browser via npm');
   
   try {
+    const result = await runAgentBrowserCommand('--version');
+    if (result.ok) {
+      logs.push('agent-browser is already installed');
+      return { ok: true, logs };
+    }
+    
     execSync('npm install -g agent-browser', { 
       encoding: 'utf8', 
       stdio: 'inherit',
@@ -125,10 +184,9 @@ async function installAgentBrowser() {
     });
     logs.push('agent-browser installed successfully');
   } catch (e) {
-    const errorMsg = `Failed to install agent-browser: ${e.message}`;
-    log('error', errorMsg);
-    logs.push(errorMsg);
-    return { ok: false, logs, error: errorMsg };
+    logs.push('Global install failed, will use npx fallback');
+    log('warn', 'Global install failed', { error: e.message });
+    return { ok: true, logs, fallback: 'npx' };
   }
   
   return { ok: true, logs };
@@ -140,31 +198,15 @@ async function installChromium() {
   log('info', 'Installing Chromium browser...');
   logs.push('Step 2: Install Chromium browser');
   
-  try {
-    execSync('npx agent-browser install', { 
-      encoding: 'utf8', 
-      stdio: 'inherit',
-      timeout: 300000 
-    });
+  const result = await runAgentBrowserCommand('install');
+  
+  if (result.ok) {
     logs.push('Chromium installed successfully');
-  } catch (e) {
-    try {
-      log('warn', 'npx install failed, trying direct agent-browser install');
-      execSync('agent-browser install', { 
-        encoding: 'utf8', 
-        stdio: 'inherit',
-        timeout: 300000 
-      });
-      logs.push('Chromium installed via agent-browser install');
-    } catch (e2) {
-      const errorMsg = `Failed to install Chromium: ${e2.message}`;
-      log('error', errorMsg);
-      logs.push(errorMsg);
-      return { ok: false, logs, error: errorMsg };
-    }
+    return { ok: true, logs };
+  } else {
+    logs.push(`Failed to install Chromium: ${result.error}`);
+    return { ok: false, logs, error: result.error };
   }
-  
-  return { ok: true, logs };
 }
 
 async function verifyInstallation() {
@@ -172,35 +214,23 @@ async function verifyInstallation() {
   
   logs.push('Step 3: Verify installation');
   
-  try {
-    const version = execSync('agent-browser --version', { encoding: 'utf8' }).trim();
-    logs.push(`agent-browser version: ${version}`);
-  } catch (e) {
-    const errorMsg = 'agent-browser not found in PATH after installation';
-    log('error', errorMsg);
-    logs.push(errorMsg);
-    return { ok: false, logs, error: errorMsg };
-  }
+  const result = await runAgentBrowserCommand('--version');
   
-  try {
-    execSync('agent-browser --help', { encoding: 'utf8', stdio: 'ignore' });
-    logs.push('Chromium is ready');
-  } catch (e) {
-    const errorMsg = 'Chromium may not be fully installed';
-    log('warn', errorMsg);
-    logs.push(errorMsg);
+  if (result.ok) {
+    logs.push(`agent-browser version: ${result.stdout.trim()}`);
+    return { ok: true, logs, version: result.stdout.trim() };
+  } else {
+    logs.push('agent-browser verification failed');
+    return { ok: false, logs, error: result.error };
   }
-  
-  return { ok: true, logs };
 }
 
 async function getAgentBrowserVersion() {
-  try {
-    const version = execSync('agent-browser --version', { encoding: 'utf8' }).trim();
-    return { installed: true, version };
-  } catch (e) {
-    return { installed: false, version: null };
+  const result = await runAgentBrowserCommand('--version');
+  if (result.ok) {
+    return { installed: true, version: result.stdout.trim() };
   }
+  return { installed: false, version: null };
 }
 
 async function checkForUpdates() {
@@ -211,7 +241,7 @@ async function checkForUpdates() {
   }
   
   try {
-    const npmVersion = execSync('npm view agent-browser version', { encoding: 'utf8' }).trim();
+    const npmVersion = execSync('npm view agent-browser version', { encoding: 'utf8', timeout: 10000 }).trim();
     const hasUpdate = semver.lt(current.version, npmVersion);
     
     return {
@@ -220,6 +250,7 @@ async function checkForUpdates() {
       latestVersion: npmVersion,
     };
   } catch (e) {
+    log('warn', 'Failed to check for updates', { error: e.message });
     return { hasUpdate: null, currentVersion: current.version, latestVersion: null };
   }
 }
@@ -230,23 +261,60 @@ async function upgradeAgentBrowser() {
   log('info', 'Upgrading agent-browser to latest...');
   logs.push('Upgrading agent-browser to latest version');
   
-  try {
-    execSync('npm install -g agent-browser@latest', { 
-      encoding: 'utf8', 
-      stdio: 'inherit',
-      timeout: 300000 
-    });
-    logs.push('Upgrade completed');
+  if (UPDATE_STRATEGY === 'atomic') {
+    logs.push('Using atomic update strategy');
     
-    const version = execSync('agent-browser --version', { encoding: 'utf8' }).trim();
-    logs.push(`New version: ${version}`);
+    try {
+      fs.rmSync(STAGING_DIR, { recursive: true, force: true });
+      fs.mkdirSync(STAGING_DIR, { recursive: true });
+      
+      execSync(`npm install --prefix ${STAGING_DIR} agent-browser@latest`, {
+        encoding: 'utf8',
+        timeout: 300000,
+      });
+      
+      const testResult = execSync(`${path.join(STAGING_DIR, 'node_modules', '.bin', 'agent-browser')} --version`, {
+        encoding: 'utf8',
+        timeout: 10000,
+      });
+      
+      fs.rmSync(ACTIVE_DIR, { recursive: true, force: true });
+      fs.renameSync(STAGING_DIR, ACTIVE_DIR);
+      
+      logs.push('Atomic upgrade completed');
+      logs.push(`New version: ${testResult.trim()}`);
+      
+      return { ok: true, logs, version: testResult.trim() };
+    } catch (e) {
+      logs.push(`Atomic upgrade failed: ${e.message}`);
+      logs.push('Rolling back to previous version');
+      
+      try {
+        fs.rmSync(STAGING_DIR, { recursive: true, force: true });
+      } catch (rollbackError) {
+        logs.push(`Rollback failed: ${rollbackError.message}`);
+      }
+      
+      return { ok: false, logs, error: e.message };
+    }
+  } else {
+    logs.push('Using simple update strategy');
     
-    return { ok: true, logs, version };
-  } catch (e) {
-    const errorMsg = `Upgrade failed: ${e.message}`;
-    log('error', errorMsg);
-    logs.push(errorMsg);
-    return { ok: false, logs, error: errorMsg };
+    try {
+      execSync('npm install -g agent-browser@latest', {
+        encoding: 'utf8',
+        stdio: 'inherit',
+        timeout: 300000,
+      });
+      
+      const version = execSync('agent-browser --version', { encoding: 'utf8' }).trim();
+      logs.push(`Upgrade completed, version: ${version}`);
+      
+      return { ok: true, logs, version };
+    } catch (e) {
+      logs.push(`Upgrade failed: ${e.message}`);
+      return { ok: false, logs, error: e.message };
+    }
   }
 }
 
@@ -307,16 +375,8 @@ export async function bootstrapEnsure() {
     }
     logs.push(`Node.js version: ${nodeCheck.version}`);
     
-    const npmCheck = await checkNpmAvailable();
-    if (!npmCheck.ok) {
-      return { 
-        ok: false, 
-        logs, 
-        error: npmCheck.error,
-        nextSteps: ['Install Node.js with npm', 'Add npm to PATH'] 
-      };
-    }
-    logs.push('npm is available');
+    fs.mkdirSync(RUNTIME_DIR, { recursive: true });
+    logs.push('Runtime directory created');
     
     const detection = await runFullDetection();
     logs.push(`Detection: agent-browser installed=${detection.agentBrowser.installed}`);
@@ -357,7 +417,7 @@ export async function bootstrapEnsure() {
         ok: false, 
         logs, 
         error: verifyResult.error,
-        nextSteps: ['Run: agent-browser install', 'Check PATH configuration'] 
+        nextSteps: ['Run: browser_ensure to repair installation', 'Use npx agent-browser as fallback'] 
       };
     }
     
@@ -416,10 +476,25 @@ export async function fullEnsure() {
   }
 }
 
+process.on('SIGINT', () => {
+  releaseLock();
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  releaseLock();
+  process.exit(0);
+});
+
+process.on('exit', () => {
+  releaseLock();
+});
+
 export default {
   bootstrapEnsure,
   fullEnsure,
   ensureLatest,
   checkForUpdates,
   getAgentBrowserVersion,
+  runAgentBrowserCommand,
 };

package/src/tools/actions/click.js

@@ -1,4 +1,14 @@
-import { execSync } from 'child_process';
+import { runAgentBrowserCommand } from '../../ensure.js';
+
+const LOG_LEVEL = process.env.LOG_LEVEL || 'info';
+
+function log(level, message, data = null) {
+  const levels = { error: 0, warn: 1, info: 2, debug: 3 };
+  if (levels[level] <= levels[LOG_LEVEL]) {
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] [${level.toUpperCase()}] ${message}`, data ? JSON.stringify(data) : '');
+  }
+}
 
 export const clickTool = {
   name: 'browser_click',
@@ -26,37 +36,40 @@ export async function clickToolHandler(args) {
   const startTime = Date.now();
   
   logs.push(`[${new Date().toISOString()}] browser_click: ${selector}`);
+  log('info', 'Clicking element', { selector, newTab });
   
   try {
     let command = `click "${selector}"`;
     if (newTab) command += ' --new-tab';
     
-    const stdout = execSync(`agent-browser ${command} --json`, {
-      encoding: 'utf8',
-      timeout: 30000,
-    });
+    const result = await runAgentBrowserCommand(`${command} --json`);
     
     const elapsed = Date.now() - startTime;
     logs.push(`[${new Date().toISOString()}] Completed in ${elapsed}ms`);
     
     let parsed;
     try {
-      parsed = JSON.parse(stdout);
+      parsed = JSON.parse(result.stdout);
     } catch {
-      parsed = { success: true };
+      parsed = { success: result.ok };
     }
     
     return {
-      ok: true,
+      ok: result.ok,
       logs,
-      stdout,
+      stdout: result.stdout,
+      stderr: result.stderr,
       output: parsed,
       selector,
       duration: elapsed,
+      useNpx: result.useNpx,
     };
   } catch (error) {
     const elapsed = Date.now() - startTime;
-    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    const errorMsg = error.message || String(error);
+    
+    logs.push(`[${new Date().toISOString()}] Error: ${errorMsg}`);
+    log('error', 'Failed to click element', { error: errorMsg, selector });
     
     const nextSteps = [
       'Run browser_snapshot first to get element refs',
@@ -67,8 +80,8 @@ export async function clickToolHandler(args) {
     return {
       ok: false,
       logs,
-      stderr: error.stderr || '',
-      error: error.message,
+      stderr: error.stderr || errorMsg,
+      error: errorMsg,
       selector,
       duration: elapsed,
       nextSteps,

package/src/tools/actions/fill.js

@@ -1,4 +1,14 @@
-import { execSync } from 'child_process';
+import { runAgentBrowserCommand } from '../../ensure.js';
+
+const LOG_LEVEL = process.env.LOG_LEVEL || 'info';
+
+function log(level, message, data = null) {
+  const levels = { error: 0, warn: 1, info: 2, debug: 3 };
+  if (levels[level] <= levels[LOG_LEVEL]) {
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] [${level.toUpperCase()}] ${message}`, data ? JSON.stringify(data) : '');
+  }
+}
 
 export const fillTool = {
   name: 'browser_fill',
@@ -25,37 +35,40 @@ export async function fillToolHandler(args) {
   const startTime = Date.now();
   
   logs.push(`[${new Date().toISOString()}] browser_fill: ${selector} = "${value}"`);
+  log('info', 'Filling form field', { selector, value });
   
   try {
     const command = `fill "${selector}" "${value}"`;
     
-    const stdout = execSync(`agent-browser ${command} --json`, {
-      encoding: 'utf8',
-      timeout: 30000,
-    });
+    const result = await runAgentBrowserCommand(`${command} --json`);
     
     const elapsed = Date.now() - startTime;
     logs.push(`[${new Date().toISOString()}] Completed in ${elapsed}ms`);
     
     let parsed;
     try {
-      parsed = JSON.parse(stdout);
+      parsed = JSON.parse(result.stdout);
     } catch {
-      parsed = { success: true };
+      parsed = { success: result.ok };
     }
     
     return {
-      ok: true,
+      ok: result.ok,
       logs,
-      stdout,
+      stdout: result.stdout,
+      stderr: result.stderr,
       output: parsed,
       selector,
       value,
       duration: elapsed,
+      useNpx: result.useNpx,
     };
   } catch (error) {
     const elapsed = Date.now() - startTime;
-    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    const errorMsg = error.message || String(error);
+    
+    logs.push(`[${new Date().toISOString()}] Error: ${errorMsg}`);
+    log('error', 'Failed to fill form field', { error: errorMsg, selector, value });
     
     const nextSteps = [
       'Run browser_snapshot first to get element refs',
@@ -66,8 +79,8 @@ export async function fillToolHandler(args) {
     return {
       ok: false,
       logs,
-      stderr: error.stderr || '',
-      error: error.message,
+      stderr: error.stderr || errorMsg,
+      error: errorMsg,
       selector,
       value,
       duration: elapsed,

package/src/tools/actions/open.js

@@ -1,4 +1,14 @@
-import { execSync } from 'child_process';
+import { runAgentBrowserCommand } from '../../ensure.js';
+
+const LOG_LEVEL = process.env.LOG_LEVEL || 'info';
+
+function log(level, message, data = null) {
+  const levels = { error: 0, warn: 1, info: 2, debug: 3 };
+  if (levels[level] <= levels[LOG_LEVEL]) {
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] [${level.toUpperCase()}] ${message}`, data ? JSON.stringify(data) : '');
+  }
+}
 
 export const openTool = {
   name: 'browser_open',
@@ -39,6 +49,7 @@ export async function openToolHandler(args) {
   const startTime = Date.now();
   
   logs.push(`[${new Date().toISOString()}] browser_open: ${url}`);
+  log('info', 'Opening URL', { url, newTab, session, profile });
   
   try {
     let command = `open ${newTab ? '--new-tab ' : ''}"${url}"`;
@@ -49,33 +60,34 @@ export async function openToolHandler(args) {
       command = `open ${newTab ? '--new-tab ' : ''}--profile "${profile}" "${url}"`;
     }
     
-    const stdout = execSync(`agent-browser ${command} --json`, {
-      encoding: 'utf8',
-      timeout,
-      maxBuffer: 10 * 1024 * 1024,
-    });
+    const result = await runAgentBrowserCommand(`${command} --json`, { timeout });
     
     const elapsed = Date.now() - startTime;
     logs.push(`[${new Date().toISOString()}] Completed in ${elapsed}ms`);
     
     let parsed;
     try {
-      parsed = JSON.parse(stdout);
+      parsed = JSON.parse(result.stdout);
     } catch {
-      parsed = { success: true, raw: stdout };
+      parsed = { success: result.ok, raw: result.stdout };
     }
     
     return {
-      ok: true,
+      ok: result.ok,
       logs,
-      stdout,
+      stdout: result.stdout,
+      stderr: result.stderr,
       output: parsed,
       url,
       duration: elapsed,
+      useNpx: result.useNpx,
     };
   } catch (error) {
     const elapsed = Date.now() - startTime;
-    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    const errorMsg = error.message || String(error);
+    
+    logs.push(`[${new Date().toISOString()}] Error: ${errorMsg}`);
+    log('error', 'Failed to open URL', { error: errorMsg, url });
     
     const nextSteps = [
       'Check if URL is valid and accessible',
@@ -86,8 +98,8 @@ export async function openToolHandler(args) {
     return {
       ok: false,
       logs,
-      stderr: error.stderr || '',
-      error: error.message,
+      stderr: error.stderr || errorMsg,
+      error: errorMsg,
       url,
       duration: elapsed,
       nextSteps,

package/src/tools/actions/snapshot.js

@@ -1,4 +1,14 @@
-import { execSync } from 'child_process';
+import { runAgentBrowserCommand } from '../../ensure.js';
+
+const LOG_LEVEL = process.env.LOG_LEVEL || 'info';
+
+function log(level, message, data = null) {
+  const levels = { error: 0, warn: 1, info: 2, debug: 3 };
+  if (levels[level] <= levels[LOG_LEVEL]) {
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] [${level.toUpperCase()}] ${message}`, data ? JSON.stringify(data) : '');
+  }
+}
 
 export const snapshotTool = {
   name: 'browser_snapshot',
@@ -39,6 +49,7 @@ export async function snapshotToolHandler(args) {
   const startTime = Date.now();
   
   logs.push(`[${new Date().toISOString()}] browser_snapshot called`);
+  log('info', 'Taking snapshot', { interactive, compact, depth, selector, cursor });
   
   try {
     let command = 'snapshot --json';
@@ -49,9 +60,7 @@ export async function snapshotToolHandler(args) {
     if (depth) command += ` -d ${depth}`;
     if (selector) command += ` -s "${selector}"`;
     
-    const stdout = execSync(`agent-browser ${command}`, {
-      encoding: 'utf8',
-      timeout: 30000,
+    const result = await runAgentBrowserCommand(command, {
       maxBuffer: 50 * 1024 * 1024,
     });
     
@@ -60,21 +69,26 @@ export async function snapshotToolHandler(args) {
     
     let parsed;
     try {
-      parsed = JSON.parse(stdout);
+      parsed = JSON.parse(result.stdout);
     } catch {
-      parsed = { success: true, raw: stdout };
+      parsed = { success: result.ok, raw: result.stdout };
     }
     
     return {
-      ok: true,
+      ok: result.ok,
       logs,
-      stdout,
+      stdout: result.stdout,
+      stderr: result.stderr,
       output: parsed,
       duration: elapsed,
+      useNpx: result.useNpx,
     };
   } catch (error) {
     const elapsed = Date.now() - startTime;
-    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    const errorMsg = error.message || String(error);
+    
+    logs.push(`[${new Date().toISOString()}] Error: ${errorMsg}`);
+    log('error', 'Failed to take snapshot', { error: errorMsg });
     
     const nextSteps = [
       'Run browser_open first to navigate to a page',
@@ -85,8 +99,8 @@ export async function snapshotToolHandler(args) {
     return {
       ok: false,
       logs,
-      stderr: error.stderr || '',
-      error: error.message,
+      stderr: error.stderr || errorMsg,
+      error: errorMsg,
       duration: elapsed,
       nextSteps,
     };

package/src/tools/actions/wait.js

@@ -45,9 +45,15 @@ export async function waitToolHandler(args) {
     if (target && !target.startsWith('--')) {
       command += ` "${target}"`;
     }
-    if (text) command += ` --text "${text}"`;
-    if (url) command += ` --url "${url}"`;
-    if (loadState) command += ` --${loadState}`;
+    if (text) {
+      command += ` --text "${text}"`;
+    }
+    if (url) {
+      command += ` --url "${url}"`;
+    }
+    if (loadState) {
+      command += ` --${loadState}`;
+    }
     
     const stdout = execSync(`agent-browser ${command} --json`, {
       encoding: 'utf8',
@@ -57,10 +63,18 @@ export async function waitToolHandler(args) {
     const elapsed = Date.now() - startTime;
     logs.push(`[${new Date().toISOString()}] Completed in ${elapsed}ms`);
     
+    let parsed;
+    try {
+      parsed = JSON.parse(stdout);
+    } catch {
+      parsed = { success: true };
+    }
+    
     return {
       ok: true,
       logs,
       stdout,
+      output: parsed,
       duration: elapsed,
     };
   } catch (error) {
@@ -68,7 +82,7 @@ export async function waitToolHandler(args) {
     logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
     
     const nextSteps = [
-      'Verify the target element/text/URL exists',
+      'Verify target element/text/URL exists',
       'Increase timeout value',
       'Check page for dynamic content issues',
     ];

package/src/tools/exec.js

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { runAgentBrowserCommand } from '../ensure.js';
 
 const LOG_LEVEL = process.env.LOG_LEVEL || 'info';
 
@@ -45,57 +45,43 @@ export async function execToolHandler(args) {
   const startTime = Date.now();
   
   logs.push(`[${new Date().toISOString()}] Executing: agent-browser ${command}`);
+  log('info', 'Executing command', { command, timeoutMs, cwd, json });
   
   try {
-    const fullCommand = `agent-browser ${command}${json ? ' --json' : ''}`;
-    log('info', 'Executing command', { command: fullCommand, timeoutMs, cwd });
+    const cmd = json ? `${command} --json` : command;
     
-    const options = {
-      encoding: 'utf8',
+    const result = await runAgentBrowserCommand(cmd, {
       timeout: timeoutMs,
-      maxBuffer: 50 * 1024 * 1024,
-    };
-    
-    if (cwd) {
-      options.cwd = cwd;
-    }
+      cwd,
+    });
     
-    const stdout = execSync(fullCommand, options);
     const elapsed = Date.now() - startTime;
-    
     logs.push(`[${new Date().toISOString()}] Completed in ${elapsed}ms`);
     
-    let parsedOutput = stdout;
+    let parsedOutput = result.stdout;
     if (json) {
       try {
-        parsedOutput = JSON.parse(stdout);
+        parsedOutput = JSON.parse(result.stdout);
       } catch {
-        parsedOutput = stdout;
+        parsedOutput = result.stdout;
       }
     }
     
     return {
-      ok: true,
+      ok: result.ok,
       logs,
-      stdout,
+      stdout: result.stdout,
+      stderr: result.stderr,
       output: parsedOutput,
       duration: elapsed,
+      useNpx: result.useNpx,
     };
   } catch (error) {
     const elapsed = Date.now() - startTime;
     const errorMsg = error.message || String(error);
-    const stderr = error.stderr || '';
     
     logs.push(`[${new Date().toISOString()}] Error after ${elapsed}ms: ${errorMsg}`);
-    
-    let parsedError = errorMsg;
-    if (json && stderr) {
-      try {
-        parsedError = JSON.parse(stderr);
-      } catch {
-        parsedError = stderr;
-      }
-    }
+    log('error', 'Command failed', { error: errorMsg, elapsed });
     
     const nextSteps = [
       'Check if the command syntax is correct',
@@ -110,9 +96,8 @@ export async function execToolHandler(args) {
     return {
       ok: false,
       logs,
-      stderr,
+      stderr: error.stderr || errorMsg,
       error: errorMsg,
-      output: parsedError,
       duration: elapsed,
       nextSteps,
     };

package/test_input.txt

@@ -0,0 +1,2 @@
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
+{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

package/test_output.txt

@@ -0,0 +1,15 @@
+[2026-02-27T11:02:02.290Z] [INFO] MCP server started, waiting for initialization... 
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 1\"... is not valid JSON","line":"=== Test 1: MCP Initialization ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\"}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 2\"... is not valid JSON","line":"=== Test 2: Tools List ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 3\"... is not valid JSON","line":"=== Test 3: Version Info ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"browser_version\",\"arguments\":{}}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 4\"... is not valid JSON","line":"=== Test 4: Doctor Diagnosis ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"browser_doctor\",\"arguments\":{}}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 5\"... is not valid JSON","line":"=== Test 5: Ensure Tool ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{\"name\":\"browser_ensure\",\"arguments\":{}}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 6\"... is not valid JSON","line":"=== Test 6: Exec Tool (simple) ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"tools/call\",\"params\":{\"name\":\"browser_exec\",\"arguments\":{\"command\":\"--help\"}}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 7\"... is not valid JSON","line":"=== Test 7: Exec Tool (complex) ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"tools/call\",\"params\":{\"name\":\"browser_exec\",\"arguments\":{\"command\":\"open https://example.com --json\"}}'"}

package/test_results.txt

@@ -0,0 +1,21 @@
+=== Test 1: MCP Initialization ===
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}'
+
+=== Test 2: Tools List ===
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+
+=== Test 3: Version Info ===
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"browser_version","arguments":{}}}'
+
+=== Test 4: Doctor Diagnosis ===
+echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"browser_doctor","arguments":{}}}'
+
+=== Test 5: Ensure Tool ===
+echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"browser_ensure","arguments":{}}}'
+
+=== Test 6: Exec Tool (help) ===
+echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"browser_exec","arguments":{"command":"--help"}}}'
+
+=== Test 7: Exec Tool (open) ===
+echo '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"browser_exec","arguments":{"command":"open https://example.com --json"}}}'
+