@bsbofmusic/agent-browser-mcp-opencode 0.1.1 → 1.0.0

package/src/tools/actions/find.js

@@ -0,0 +1,107 @@
+import { execSync } from 'child_process';
+
+export const findTool = {
+  name: 'browser_find',
+  description: 'Find element by semantic locator (role, text, label, placeholder, alt, title, testid). Then optionally perform an action.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      type: {
+        type: 'string',
+        description: 'Locator type: role, text, label, placeholder, alt, title, testid, first, last, nth',
+        enum: ['role', 'text', 'label', 'placeholder', 'alt', 'title', 'testid', 'first', 'last', 'nth'],
+      },
+      value: {
+        type: 'string',
+        description: 'Value to search for (text content, role name, label, etc.)',
+      },
+      action: {
+        type: 'string',
+        description: 'Action to perform: click, fill, type, hover, focus, check, uncheck, text',
+        enum: ['click', 'fill', 'type', 'hover', 'focus', 'check', 'uncheck', 'text'],
+      },
+      actionValue: {
+        type: 'string',
+        description: 'Value for fill/type actions',
+      },
+      exact: {
+        type: 'boolean',
+        description: 'Require exact text match',
+        default: false,
+      },
+      name: {
+        type: 'string',
+        description: 'Filter by accessible name (for role locator)',
+      },
+      nth: {
+        type: 'number',
+        description: 'For nth locator: index number',
+      },
+    },
+    required: ['type', 'value'],
+  },
+};
+
+export async function findToolHandler(args) {
+  const { type, value, action, actionValue, exact = false, name, nth } = args;
+  const logs = [];
+  const startTime = Date.now();
+  
+  logs.push(`[${new Date().toISOString()}] browser_find: type=${type}, value=${value}`);
+  
+  try {
+    let command = `find ${type} "${value}"`;
+    
+    if (exact) command += ' --exact';
+    if (name) command += ` --name "${name}"`;
+    if (nth !== undefined) command += ` ${nth}`;
+    
+    if (action) {
+      command += ` ${action}`;
+      if (actionValue) command += ` "${actionValue}"`;
+    }
+    
+    const stdout = execSync(`agent-browser ${command} --json`, {
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+    
+    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, raw: stdout };
+    }
+    
+    return {
+      ok: true,
+      logs,
+      stdout,
+      output: parsed,
+      locator: { type, value, action },
+      duration: elapsed,
+    };
+  } catch (error) {
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    
+    const nextSteps = [
+      'Run browser_snapshot to see available elements',
+      'Verify locator type and value are correct',
+      'Try different locator: role, text, label',
+    ];
+    
+    return {
+      ok: false,
+      logs,
+      stderr: error.stderr || '',
+      error: error.message,
+      locator: { type, value, action },
+      duration: elapsed,
+      nextSteps,
+    };
+  }
+}

package/src/tools/actions/getText.js

@@ -0,0 +1,70 @@
+import { execSync } from 'child_process';
+
+export const getTextTool = {
+  name: 'browser_get_text',
+  description: 'Get text content from an element. Use ref from snapshot or CSS selector.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      selector: {
+        type: 'string',
+        description: 'Element selector (e.g., @e1, #title, h1)',
+      },
+    },
+    required: ['selector'],
+  },
+};
+
+export async function getTextToolHandler(args) {
+  const { selector } = args;
+  const logs = [];
+  const startTime = Date.now();
+  
+  logs.push(`[${new Date().toISOString()}] browser_get_text: ${selector}`);
+  
+  try {
+    const command = `get text "${selector}"`;
+    
+    const stdout = execSync(`agent-browser ${command} --json`, {
+      encoding: 'utf8',
+      timeout: 10000,
+    });
+    
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Completed in ${elapsed}ms`);
+    
+    let parsed;
+    try {
+      parsed = JSON.parse(stdout);
+    } catch {
+      parsed = { text: stdout.trim() };
+    }
+    
+    return {
+      ok: true,
+      logs,
+      stdout,
+      output: parsed,
+      selector,
+      duration: elapsed,
+    };
+  } catch (error) {
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    
+    const nextSteps = [
+      'Run browser_snapshot first to get element refs',
+      'Verify selector is correct',
+    ];
+    
+    return {
+      ok: false,
+      logs,
+      stderr: error.stderr || '',
+      error: error.message,
+      selector,
+      duration: elapsed,
+      nextSteps,
+    };
+  }
+}

package/src/tools/actions/open.js

@@ -0,0 +1,96 @@
+import { execSync } from 'child_process';
+
+export const openTool = {
+  name: 'browser_open',
+  description: 'Navigate to a URL. Opens a browser and navigates to the specified URL.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: {
+        type: 'string',
+        description: 'The URL to navigate to (e.g., https://example.com)',
+      },
+      timeout: {
+        type: 'number',
+        description: 'Timeout in milliseconds',
+        default: 30000,
+      },
+      newTab: {
+        type: 'boolean',
+        description: 'Open in a new tab instead of current tab',
+        default: false,
+      },
+      session: {
+        type: 'string',
+        description: 'Session name for isolated browser state',
+      },
+      profile: {
+        type: 'string',
+        description: 'Profile directory for persistent browser state',
+      },
+    },
+    required: ['url'],
+  },
+};
+
+export async function openToolHandler(args) {
+  const { url, timeout = 30000, newTab = false, session, profile } = args;
+  const logs = [];
+  const startTime = Date.now();
+  
+  logs.push(`[${new Date().toISOString()}] browser_open: ${url}`);
+  
+  try {
+    let command = `open ${newTab ? '--new-tab ' : ''}"${url}"`;
+    
+    if (session) {
+      command = `open ${newTab ? '--new-tab ' : ''}--session ${session} "${url}"`;
+    } else if (profile) {
+      command = `open ${newTab ? '--new-tab ' : ''}--profile "${profile}" "${url}"`;
+    }
+    
+    const stdout = execSync(`agent-browser ${command} --json`, {
+      encoding: 'utf8',
+      timeout,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+    
+    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, raw: stdout };
+    }
+    
+    return {
+      ok: true,
+      logs,
+      stdout,
+      output: parsed,
+      url,
+      duration: elapsed,
+    };
+  } catch (error) {
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    
+    const nextSteps = [
+      'Check if URL is valid and accessible',
+      'Run: browser_ensure to install browser',
+      'Run: browser_doctor to diagnose issues',
+    ];
+    
+    return {
+      ok: false,
+      logs,
+      stderr: error.stderr || '',
+      error: error.message,
+      url,
+      duration: elapsed,
+      nextSteps,
+    };
+  }
+}

package/src/tools/actions/screenshot.js

@@ -0,0 +1,81 @@
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+export const screenshotTool = {
+  name: 'browser_screenshot',
+  description: 'Take a screenshot of the current page. Optionally saves to a file and can include annotated labels.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Path to save screenshot (optional, defaults to temp file)',
+      },
+      fullPage: {
+        type: 'boolean',
+        description: 'Capture full scrollable page',
+        default: false,
+      },
+      annotate: {
+        type: 'boolean',
+        description: 'Add numbered labels to interactive elements',
+        default: false,
+      },
+    },
+  },
+};
+
+export async function screenshotToolHandler(args) {
+  const { path: savePath, fullPage = false, annotate = false } = args;
+  const logs = [];
+  const startTime = Date.now();
+  
+  logs.push(`[${new Date().toISOString()}] browser_screenshot called`);
+  
+  try {
+    let command = 'screenshot';
+    if (savePath) command += ` "${savePath}"`;
+    if (fullPage) command += ' --full';
+    if (annotate) command += ' --annotate';
+    
+    const stdout = execSync(`agent-browser ${command}`, {
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+    
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Completed in ${elapsed}ms`);
+    
+    const outputPath = savePath || stdout.trim().split('\n').find(l => l.includes('saved to'));
+    
+    return {
+      ok: true,
+      logs,
+      stdout,
+      outputPath: outputPath || null,
+      fullPage,
+      annotate,
+      duration: elapsed,
+    };
+  } catch (error) {
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    
+    const nextSteps = [
+      'Run browser_open first to navigate to a page',
+      'Check if browser is open: browser_tab',
+      'Verify screenshot path is writable',
+    ];
+    
+    return {
+      ok: false,
+      logs,
+      stderr: error.stderr || '',
+      error: error.message,
+      duration: elapsed,
+      nextSteps,
+    };
+  }
+}

package/src/tools/actions/snapshot.js

@@ -0,0 +1,94 @@
+import { execSync } from 'child_process';
+
+export const snapshotTool = {
+  name: 'browser_snapshot',
+  description: 'Get the accessibility tree of the current page with element refs. This is the recommended way for AI agents to interact with pages - use refs from snapshot to click, fill, etc.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      interactive: {
+        type: 'boolean',
+        description: 'Only show interactive elements (buttons, inputs, links)',
+        default: false,
+      },
+      compact: {
+        type: 'boolean',
+        description: 'Remove empty structural elements',
+        default: false,
+      },
+      depth: {
+        type: 'number',
+        description: 'Limit tree depth',
+      },
+      selector: {
+        type: 'string',
+        description: 'Scope to CSS selector',
+      },
+      cursor: {
+        type: 'boolean',
+        description: 'Include cursor-interactive elements',
+        default: false,
+      },
+    },
+  },
+};
+
+export async function snapshotToolHandler(args) {
+  const { interactive = false, compact = false, depth, selector, cursor = false } = args;
+  const logs = [];
+  const startTime = Date.now();
+  
+  logs.push(`[${new Date().toISOString()}] browser_snapshot called`);
+  
+  try {
+    let command = 'snapshot --json';
+    
+    if (interactive) command += ' -i';
+    if (compact) command += ' -c';
+    if (cursor) command += ' -C';
+    if (depth) command += ` -d ${depth}`;
+    if (selector) command += ` -s "${selector}"`;
+    
+    const stdout = execSync(`agent-browser ${command}`, {
+      encoding: 'utf8',
+      timeout: 30000,
+      maxBuffer: 50 * 1024 * 1024,
+    });
+    
+    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, raw: stdout };
+    }
+    
+    return {
+      ok: true,
+      logs,
+      stdout,
+      output: parsed,
+      duration: elapsed,
+    };
+  } catch (error) {
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    
+    const nextSteps = [
+      'Run browser_open first to navigate to a page',
+      'Check if browser is open: browser_tab',
+      'Run: browser_doctor to diagnose issues',
+    ];
+    
+    return {
+      ok: false,
+      logs,
+      stderr: error.stderr || '',
+      error: error.message,
+      duration: elapsed,
+      nextSteps,
+    };
+  }
+}

package/src/tools/actions/tab.js

@@ -0,0 +1,91 @@
+import { execSync } from 'child_process';
+
+export const tabTool = {
+  name: 'browser_tab',
+  description: 'Manage browser tabs: list, create new, switch, or close tabs.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        description: 'Tab action: list, new, close, or number to switch to',
+        enum: ['list', 'new', 'close'],
+      },
+      index: {
+        type: 'number',
+        description: 'Tab index to switch to (0-based)',
+      },
+      url: {
+        type: 'string',
+        description: 'URL to open in new tab (for action=new)',
+      },
+    },
+  },
+};
+
+export async function tabToolHandler(args) {
+  const { action, index, url } = args;
+  const logs = [];
+  const startTime = Date.now();
+  
+  logs.push(`[${new Date().toISOString()}] browser_tab called: action=${action}, index=${index}`);
+  
+  try {
+    let command = 'tab';
+    
+    if (action === 'list' || action === undefined) {
+      command = 'tab';
+    } else if (action === 'new') {
+      command = 'tab new';
+      if (url) command += ` "${url}"`;
+    } else if (action === 'close') {
+      command = 'tab close';
+    } else if (index !== undefined) {
+      command = `tab ${index}`;
+    }
+    
+    const stdout = execSync(`agent-browser ${command} --json`, {
+      encoding: 'utf8',
+      timeout: 10000,
+    });
+    
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Completed in ${elapsed}ms`);
+    
+    let parsed;
+    try {
+      parsed = JSON.parse(stdout);
+    } catch {
+      parsed = { raw: stdout };
+    }
+    
+    return {
+      ok: true,
+      logs,
+      stdout,
+      output: parsed,
+      action,
+      index,
+      duration: elapsed,
+    };
+  } catch (error) {
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    
+    const nextSteps = [
+      'Run browser_open first to open a browser',
+      'Verify tab index is valid',
+    ];
+    
+    return {
+      ok: false,
+      logs,
+      stderr: error.stderr || '',
+      error: error.message,
+      action,
+      index,
+      duration: elapsed,
+      nextSteps,
+    };
+  }
+}

package/src/tools/actions/wait.js

@@ -0,0 +1,85 @@
+import { execSync } from 'child_process';
+
+export const waitTool = {
+  name: 'browser_wait',
+  description: 'Wait for element, text, URL, or specified time. Useful for waiting for dynamic content to load.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      target: {
+        type: 'string',
+        description: 'What to wait for: selector, --text, --url, or milliseconds',
+      },
+      text: {
+        type: 'string',
+        description: 'Text to wait for (use with --text flag)',
+      },
+      url: {
+        type: 'string',
+        description: 'URL pattern to wait for (use with --url flag)',
+      },
+      loadState: {
+        type: 'string',
+        description: 'Page load state: load, domcontentloaded, networkidle',
+        enum: ['load', 'domcontentloaded', 'networkidle'],
+      },
+      timeout: {
+        type: 'number',
+        description: 'Timeout in milliseconds (default: 30000)',
+        default: 30000,
+      },
+    },
+  },
+};
+
+export async function waitToolHandler(args) {
+  const { target, text, url, loadState, timeout = 30000 } = args;
+  const logs = [];
+  const startTime = Date.now();
+  
+  logs.push(`[${new Date().toISOString()}] browser_wait called`);
+  
+  try {
+    let command = 'wait';
+    
+    if (target && !target.startsWith('--')) {
+      command += ` "${target}"`;
+    }
+    if (text) command += ` --text "${text}"`;
+    if (url) command += ` --url "${url}"`;
+    if (loadState) command += ` --${loadState}`;
+    
+    const stdout = execSync(`agent-browser ${command} --json`, {
+      encoding: 'utf8',
+      timeout,
+    });
+    
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Completed in ${elapsed}ms`);
+    
+    return {
+      ok: true,
+      logs,
+      stdout,
+      duration: elapsed,
+    };
+  } catch (error) {
+    const elapsed = Date.now() - startTime;
+    logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
+    
+    const nextSteps = [
+      'Verify the target element/text/URL exists',
+      'Increase timeout value',
+      'Check page for dynamic content issues',
+    ];
+    
+    return {
+      ok: false,
+      logs,
+      stderr: error.stderr || '',
+      error: error.message,
+      duration: elapsed,
+      nextSteps,
+    };
+  }
+}

package/src/tools/doctor.js

@@ -0,0 +1,42 @@
+import { runDoctor } from '../doctor.js';
+
+export const doctorTool = {
+  name: 'browser_doctor',
+  description: 'Diagnose environment issues and provide actionable nextSteps. Checks network, permissions, dependencies, system libraries, executable, browser, and authentication. Returns categorized issues with fix recommendations.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+};
+
+export async function doctorToolHandler(args = {}) {
+  const logs = [];
+  
+  logs.push(`[${new Date().toISOString()}] browser_doctor called`);
+  
+  const result = await runDoctor();
+  
+  const output = {
+    ok: result.ok,
+    summary: result.summary,
+    issues: result.issues,
+    version: result.versionInfo?.version,
+    latestVersion: result.versionInfo?.latestVersion,
+    hasUpdate: result.updateInfo?.hasUpdate,
+    nextSteps: [],
+  };
+  
+  if (!result.ok) {
+    for (const issue of result.issues) {
+      output.nextSteps.push(...issue.nextSteps);
+    }
+    output.nextSteps = [...new Set(output.nextSteps)];
+  }
+  
+  return {
+    ok: result.ok,
+    logs,
+    stdout: JSON.stringify(output, null, 2),
+    ...output,
+  };
+}