mcpbrowser 0.3.18 → 0.3.19

package/README.md

@@ -7,7 +7,7 @@
 
 > ⚠️ **Security Notice:** MCPBrowser extracts webpage content and provides it to your AI agent (e.g., GitHub Copilot, Claude), which then sends it to the LLM provider it uses (e.g., Anthropic, OpenAI, GitHub) for processing. Make sure you trust both your agent and the LLM provider — especially when accessing pages with sensitive or private data.
 
-**MCPBrowser is an MCP browser server that gives AI assistants the ability to browse web pages using a real Chrome or Edge browser.** This browser-based MCP server fetches any web page — especially those protected by authentication, CAPTCHAs, anti-bot protection, or requiring JavaScript rendering. Uses your real Chrome/Edge browser for web automation so you can log in normally, then automatically extracts content. Works with corporate SSO, login forms, Cloudflare, and JavaScript-heavy sites (SPAs, dashboards).
+**MCPBrowser is an MCP browser server that gives AI assistants the ability to browse web pages using a real Chrome, Edge, or Brave browser.** This browser-based MCP server fetches any web page — especially those protected by authentication, CAPTCHAs, anti-bot protection, or requiring JavaScript rendering. Uses your real browser for web automation so you can log in normally, then automatically extracts content. Works with corporate SSO, login forms, Cloudflare, and JavaScript-heavy sites (SPAs, dashboards).
 
 This is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server using [stdio transport](https://modelcontextprotocol.io/docs/concepts/transports#stdio). Your AI assistant uses this web browser MCP server when standard HTTP requests fail — pages requiring authentication, CAPTCHA protection, or heavy JavaScript (SPAs). Once connected, the browser MCP server can navigate through websites, interact with elements, and send HTML back to the AI assistant. This gives your AI the ability to browse the web just like you do.
 
@@ -15,10 +15,9 @@ Example workflow for AI assistant to use MCPBrowser
 
 ```
 1. fetch_webpage    → Load the login page
-2. type_text        → Enter username
-3. type_text        → Enter password
-4. click_element    → Click "Sign In"
-5. get_current_html → Extract the content after login
+2. type_text        → Enter username and password (multiple fields at once)
+3. click_element    → Click "Sign In"
+4. get_current_html → Extract the content after login
 ```
 
 
@@ -35,6 +34,7 @@ Example workflow for AI assistant to use MCPBrowser
   - [click_element](#click_element)
   - [type_text](#type_text)
   - [get_current_html](#get_current_html)
+  - [scroll_page](#scroll_page)
   - [take_screenshot](#take_screenshot)
   - [close_tab](#close_tab)
 - [Configuration](#configuration-optional)
@@ -43,7 +43,7 @@ Example workflow for AI assistant to use MCPBrowser
 
 ## Requirements
 
-- Chrome or Edge browser
+- Chrome, Edge, or Brave browser
 - [Node.js 18+](https://nodejs.org/) (includes npm)
 
 > **Note:** Node.js must be installed on your system. The VS Code extension and npm package both require Node.js to run the MCP server. Download from [nodejs.org](https://nodejs.org/) if not already installed.
@@ -54,8 +54,9 @@ Example workflow for AI assistant to use MCPBrowser
 |---|----------|------------|
 | 1 | [VS Code Extension](#option-1-vs-code-extension) | One Click |
 | 2 | [Claude Code](#option-2-claude-code) | One Command |
-| 3 | [Claude Desktop](#option-3-claude-desktop) | Manual |
-| 4 | [npm Package](#option-4-npm-package) | Manual |
+| 3 | [OpenClaw](#option-3-openclaw) | One Command |
+| 4 | [Claude Desktop](#option-4-claude-desktop) | Manual |
+| 5 | [npm Package](#option-5-npm-package) | Manual |
 
 ### Option 1: VS Code Extension
 
@@ -85,7 +86,22 @@ mcpbrowser: npx -y mcpbrowser@latest - ✓ Connected
 That's it! Ask Claude to fetch any protected page:
 > "Fetch https://portal.azure.com using mcpbrowser"
 
-### Option 3: Claude Desktop
+### Option 3: OpenClaw
+
+[OpenClaw](https://openclaw.ai/) is a personal AI assistant that runs on your devices. Add MCPBrowser to give it browser automation capabilities:
+
+```bash
+openclaw mcp add mcpbrowser -- npx -y mcpbrowser@latest
+```
+
+Verify it's working:
+```bash
+openclaw mcp list
+```
+
+Now OpenClaw can browse authenticated pages, fill forms, and interact with web apps using your existing browser sessions.
+
+### Option 4: Claude Desktop
 
 Add to your config file:
 
@@ -105,7 +121,7 @@ Add to your config file:
 
 Restart Claude Desktop after saving.
 
-### Option 4: npm Package
+### Option 5: npm Package
 
 For VS Code (GitHub Copilot) manual setup, add to your `mcp.json`:
 
@@ -183,36 +199,55 @@ Clicks on any clickable element (buttons, links, divs with onclick handlers, etc
 
 ### `type_text`
 
-Types text into an input field, textarea, or other editable element. Simulates human-like typing with configurable delay between keystrokes. Automatically clears existing text by default.
+Types text into one or more input fields in a single call. Supports filling entire forms at once for efficient automation. Automatically clears existing text by default.
 
 **⚠️ Note:** Page must be already loaded via `fetch_webpage` first.
 
 **Parameters:**
 - `url` (string, required) - The URL of the page (must match a previously fetched page)
-- `selector` (string, required) - CSS selector for the input element (e.g., `#username`, `input[name="email"]`)
-- `text` (string, required) - Text to type into the field
-- `clear` (boolean, optional, default: `true`) - Whether to clear existing text first
-- `typeDelay` (number, optional, default: `50`) - Delay between keystrokes in milliseconds (simulates human typing)
+- `fields` (array, required) - Array of fields to fill. Each field object contains:
+  - `selector` (string, required) - CSS selector for the input element (e.g., `#username`, `input[name="email"]`)
+  - `text` (string, required) - Text to type into the field
+  - `clear` (boolean, optional, default: `true`) - Whether to clear existing text first
+  - `waitForElementTimeout` (number, optional, default: `5000`) - Maximum time to wait for element in milliseconds
 - `returnHtml` (boolean, optional, default: `true`) - Whether to wait for stability and return HTML after typing
 - `removeUnnecessaryHTML` (boolean, optional, default: `true`) - Remove unnecessary HTML for size reduction. Only used when `returnHtml` is `true`
 - `postTypeWait` (number, optional, default: `1000`) - Milliseconds to wait after typing for SPAs to render dynamic content
-- `waitForElementTimeout` (number, optional, default: `5000`) - Maximum time to wait for element in milliseconds
 
 **Examples:**
 ```javascript
-// Basic text input
-{ url: "https://example.com", selector: "#email", text: "user@example.com" }
-
-// Append text without clearing
-{ url: "https://example.com", selector: "#search", text: " advanced", clear: false }
+// Fill multiple fields at once (login form)
+{ 
+  url: "https://example.com/login", 
+  fields: [
+    { selector: "#username", text: "john@example.com" },
+    { selector: "#password", text: "secretpass123" }
+  ]
+}
 
-// Fast typing without human simulation
-{ url: "https://example.com", selector: "#username", text: "john", typeDelay: 0 }
+// Single field input
+{ url: "https://example.com", fields: [{ selector: "#search", text: "query" }] }
 
-// Type without waiting for HTML return (faster)
-{ url: "https://example.com", selector: "#field", text: "value", returnHtml: false }
+// Append text without clearing
+{ url: "https://example.com", fields: [{ selector: "#notes", text: " additional text", clear: false }] }
+
+// Fast form fill without HTML return
+{ 
+  url: "https://example.com/signup", 
+  fields: [
+    { selector: "#firstName", text: "John" },
+    { selector: "#lastName", text: "Doe" },
+    { selector: "#email", text: "john@example.com" }
+  ],
+  returnHtml: false 
+}
 ```
 
+**Error handling:** If a field fails, the response indicates:
+- Which field number failed (e.g., "Failed on field 2 of 3")
+- Which fields were successfully filled
+- Clear guidance to NOT re-type already filled fields
+
 ---
 
 ### `get_current_html`
@@ -240,6 +275,46 @@ Gets the current HTML from an already-loaded page **WITHOUT** navigating or relo
 
 ---
 
+### `scroll_page`
+
+Scrolls within an already-loaded page. Use before `take_screenshot` to capture different parts of the page, or to bring elements into view before interaction. Supports multiple scroll modes:
+
+- **By direction**: Scroll up/down/left/right by pixel amount
+- **To element**: Scroll until a specific element is visible
+- **To position**: Scroll to absolute coordinates
+
+**⚠️ Note:** Page must be already loaded via `fetch_webpage` first.
+
+**Parameters:**
+- `url` (string, required) - The URL of the page (must match a previously fetched page)
+- `direction` (string, optional) - Direction to scroll: `up`, `down`, `left`, `right`. Use with `amount`.
+- `amount` (number, optional, default: `500`) - Pixels to scroll in the specified direction (~half a viewport)
+- `selector` (string, optional) - CSS selector of element to scroll into view. Ignores direction/amount.
+- `x` (number, optional) - Absolute horizontal scroll position. Use with `y`.
+- `y` (number, optional) - Absolute vertical scroll position. Use with `x`.
+
+**Examples:**
+```javascript
+// Scroll down by 500px (default)
+{ url: "https://example.com", direction: "down" }
+
+// Scroll down by 1000px
+{ url: "https://example.com", direction: "down", amount: 1000 }
+
+// Scroll an element into view
+{ url: "https://example.com", selector: "#footer" }
+
+// Scroll to specific position
+{ url: "https://example.com", x: 0, y: 2000 }
+
+// Scroll to top of page
+{ url: "https://example.com", x: 0, y: 0 }
+```
+
+**Returns:** Current scroll position, page dimensions, and viewport size — useful for understanding where you are on the page.
+
+---
+
 ### `take_screenshot`
 
 Takes a screenshot of an already-loaded page for visual analysis. **Useful when HTML parsing is insufficient** — for example, pages with charts, images, complex layouts, popups, or visual content that's hard to understand from HTML alone. Returns a PNG image.
@@ -328,7 +403,7 @@ Logs go to `stderr` so they don't interfere with MCP protocol on `stdout`.
 ## Troubleshooting
 
 **Browser doesn't open?**
-- Make sure Chrome or Edge is installed
+- Make sure Chrome, Edge, or Brave is installed
 - Try setting `CHROME_PATH` explicitly
 
 **Can't connect to browser?**

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.18",
+  "version": "0.3.19",
   "mcpName": "io.github.cherchyk/mcpbrowser",
   "type": "module",
-  "description": "MCP browser server - fetch web pages using real Chrome/Edge browser. Handles authentication, SSO, CAPTCHAs, and anti-bot protection. Browser automation for AI assistants.",
+  "description": "MCP browser server - fetch web pages using real Chrome/Edge/Brave browser. Handles authentication, SSO, CAPTCHAs, and anti-bot protection. Browser automation for AI assistants.",
   "main": "src/mcp-browser.js",
   "bin": {
     "mcpbrowser": "src/mcp-browser.js"

package/src/actions/click-element.js

@@ -178,9 +178,9 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
     logger.error(`click_element: Failed to connect to browser: ${err.message}`);
     return new InformationalResponse(
       `Browser connection failed: ${err.message}`,
-      'Could not connect to Chrome or Edge browser. The browser must be running with remote debugging enabled.',
+      'The browser must be running with remote debugging enabled.',
       [
-        'Ensure Chrome or Edge browser is installed and running',
+        'Ensure the browser is installed and running',
         'Check that remote debugging is enabled (--remote-debugging-port)',
         'Try restarting the MCP server'
       ]

package/src/actions/fetch-page.js

@@ -6,7 +6,7 @@
 import { getBrowser, domainPages } from '../core/browser.js';
 import { getOrCreatePage, queueRequest, navigateToUrl, waitForPageReady, extractAndProcessHtml, waitForPageStability } from '../core/page.js';
 import { detectRedirectType, waitForAutoAuth, waitForManualAuth } from '../core/auth.js';
-import { MCPResponse, ErrorResponse, HttpStatusResponse } from '../core/responses.js';
+import { MCPResponse, ErrorResponse, HttpStatusResponse, InformationalResponse } from '../core/responses.js';
 import logger from '../core/logger.js';
 
 /**
@@ -156,7 +156,22 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
   const authCompletionTimeout = 600000;
   const reuseLastKeptPage = true;
 
-  const browserInstance = await getBrowser(browser);
+  // Ensure browser connection
+  let browserInstance;
+  try {
+    browserInstance = await getBrowser(browser);
+  } catch (err) {
+    logger.error(`fetch_webpage: Failed to connect to browser: ${err.message}`);
+    return new InformationalResponse(
+      `Browser connection failed: ${err.message}`,
+      'The browser must be running with remote debugging enabled.',
+      [
+        'Ensure the browser is installed and running',
+        'Check that remote debugging is enabled (--remote-debugging-port)',
+        'Try restarting the MCP server'
+      ]
+    );
+  }
   
   try {
     // Get or create page for this domain (simple - no locks needed)

package/src/actions/get-current-html.js

@@ -120,9 +120,9 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
     logger.error(`get_current_html: Failed to connect to browser: ${err.message}`);
     return new InformationalResponse(
       `Browser connection failed: ${err.message}`,
-      'Could not connect to Chrome or Edge browser. The browser must be running with remote debugging enabled.',
+      'The browser must be running with remote debugging enabled.',
       [
-        'Ensure Chrome or Edge browser is installed and running',
+        'Ensure the browser is installed and running',
         'Check that remote debugging is enabled (--remote-debugging-port)',
         'Try restarting the MCP server'
       ]

package/src/actions/scroll-page.js

@@ -186,9 +186,9 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
     logger.error(`scroll_page: Failed to connect to browser: ${err.message}`);
     return new InformationalResponse(
       `Browser connection failed: ${err.message}`,
-      'Could not connect to Chrome or Edge browser. The browser must be running with remote debugging enabled.',
+      'The browser must be running with remote debugging enabled.',
       [
-        'Ensure Chrome or Edge browser is installed and running',
+        'Ensure the browser is installed and running',
         'Check that remote debugging is enabled (--remote-debugging-port)',
         'Try restarting the MCP server'
       ]

package/src/actions/take-screenshot.js

@@ -149,9 +149,9 @@ export async function takeScreenshot({ url, fullPage = false }) {
     logger.error(`take_screenshot: Failed to connect to browser: ${err.message}`);
     return new InformationalResponse(
       `Browser connection failed: ${err.message}`,
-      'Could not connect to Chrome or Edge browser. The browser must be running with remote debugging enabled.',
+      'The browser must be running with remote debugging enabled.',
       [
-        'Ensure Chrome or Edge browser is installed and running',
+        'Ensure the browser is installed and running',
         'Check that remote debugging is enabled (--remote-debugging-port)',
         'Try restarting the MCP server'
       ]

package/src/actions/type-text.js

@@ -66,21 +66,32 @@ export class TypeTextSuccessResponse extends MCPResponse {
 export const TYPE_TEXT_TOOL = {
   name: "type_text",
   title: "Type Text",
-  description: "**BROWSER INTERACTION** - Types text into input fields on browser-loaded pages. Use this for filling forms, entering search queries, or any text input on the page.\n\nWorks with input fields, textareas, and other editable elements.\n\n**PREREQUISITE**: Page MUST be loaded with fetch_webpage first. This tool operates on an already-loaded page in the browser.",
+  description: "**BROWSER INTERACTION** - Types text into multiple input fields on browser-loaded pages in a single call. Use this for filling forms, entering search queries, or any text input on the page.\n\nWorks with input fields, textareas, and other editable elements. Supports filling multiple fields at once for efficient form filling.\n\n**PREREQUISITE**: Page MUST be loaded with fetch_webpage first. This tool operates on an already-loaded page in the browser.",
   inputSchema: {
     type: "object",
     properties: {
       url: { type: "string", description: "The URL of the page (must match a previously fetched page)" },
-      selector: { type: "string", description: "CSS selector for the input element (e.g., '#username', 'input[name=\"email\"]')" },
-      text: { type: "string", description: "Text to type into the field" },
-      clear: { type: "boolean", description: "Whether to clear existing text first", default: true },
-      typeDelay: { type: "number", description: "Delay between keystrokes in milliseconds (simulates human typing)", default: 50 },
-      waitForElementTimeout: { type: "number", description: "Maximum time to wait for element in milliseconds", default: 5000 },
+      fields: {
+        type: "array",
+        description: "Array of fields to fill. Each field specifies a selector and text to type.",
+        items: {
+          type: "object",
+          properties: {
+            selector: { type: "string", description: "CSS selector for the input element (e.g., '#username', 'input[name=\"email\"]')" },
+            text: { type: "string", description: "Text to type into the field" },
+            clear: { type: "boolean", description: "Whether to clear existing text first", default: true },
+            waitForElementTimeout: { type: "number", description: "Maximum time to wait for element in milliseconds", default: 5000 }
+          },
+          required: ["selector", "text"],
+          additionalProperties: false
+        },
+        minItems: 1
+      },
       returnHtml: { type: "boolean", description: "Whether to wait for stability and return HTML after typing.", default: true },
       removeUnnecessaryHTML: { type: "boolean", description: "Remove Unnecessary HTML for size reduction by 90%. Only used when returnHtml is true.", default: true },
       postTypeWait: { type: "number", description: "Milliseconds to wait after typing for SPAs to render dynamic content.", default: 1000 }
     },
-    required: ["url", "selector", "text"],
+    required: ["url", "fields"],
     additionalProperties: false
   },
   outputSchema: {
@@ -103,38 +114,48 @@ export const TYPE_TEXT_TOOL = {
   }
 };
 
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Hardcoded delay between keystrokes in milliseconds */
+const TYPE_DELAY_MS = 10;
+
 // ============================================================================
 // ACTION FUNCTION
 // ============================================================================
 
 /**
- * Type text into an input field
+ * Type text into multiple input fields
  * @param {Object} params - Type parameters
  * @param {string} params.url - The URL of the page to interact with
- * @param {string} params.selector - CSS selector for the input element
- * @param {string} params.text - Text to type
- * @param {boolean} [params.clear=true] - Whether to clear existing text first
- * @param {number} [params.typeDelay=50] - Delay between keystrokes in milliseconds
- * @param {number} [params.waitForElementTimeout=30000] - Maximum time to wait for element
+ * @param {Array<{selector: string, text: string, clear?: boolean, waitForElementTimeout?: number}>} params.fields - Array of fields to fill
  * @param {boolean} [params.returnHtml=true] - Whether to wait for stability and return HTML
  * @param {boolean} [params.removeUnnecessaryHTML=true] - Whether to clean HTML (only if returnHtml is true)
  * @param {number} [params.postTypeWait=1000] - Milliseconds to wait after typing for SPAs to render dynamic content
  * @returns {Promise<Object>} Result object with success status and details
  */
-export async function typeText({ url, selector, text, clear = true, typeDelay = 50, waitForElementTimeout = 30000, returnHtml = true, removeUnnecessaryHTML = true, postTypeWait = 1000 }) {
+export async function typeText({ url, fields, returnHtml = true, removeUnnecessaryHTML = true, postTypeWait = 1000 }) {
   const startTime = Date.now();
-  logger.info(`type_text called: selector=${selector}, url=${url}`);
+  logger.info(`type_text called: ${fields?.length || 0} fields, url=${url}`);
   
   if (!url) {
     throw new Error("url parameter is required");
   }
   
-  if (!selector) {
-    throw new Error("selector parameter is required");
+  if (!fields || !Array.isArray(fields) || fields.length === 0) {
+    throw new Error("fields parameter is required and must be a non-empty array");
   }
   
-  if (text === undefined || text === null) {
-    throw new Error("text parameter is required");
+  // Validate each field
+  for (let i = 0; i < fields.length; i++) {
+    const field = fields[i];
+    if (!field.selector) {
+      throw new Error(`fields[${i}].selector is required`);
+    }
+    if (field.text === undefined || field.text === null) {
+      throw new Error(`fields[${i}].text is required`);
+    }
   }
 
   let hostname;
@@ -151,9 +172,9 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
     logger.error(`type_text: Failed to connect to browser: ${err.message}`);
     return new InformationalResponse(
       `Browser connection failed: ${err.message}`,
-      'Could not connect to Chrome or Edge browser. The browser must be running with remote debugging enabled.',
+      'The browser must be running with remote debugging enabled.',
       [
-        'Ensure Chrome or Edge browser is installed and running',
+        'Ensure the browser is installed and running',
         'Check that remote debugging is enabled (--remote-debugging-port)',
         'Try restarting the MCP server'
       ]
@@ -178,16 +199,32 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
     );
   }
 
+  const filledSelectors = [];
+  let currentFieldIndex = 0;
+  let currentSelector = null;
+  
   try {
-    await page.waitForSelector(selector, { timeout: waitForElementTimeout, visible: true });
-    
-    if (clear) {
-      await page.click(selector, { clickCount: 3 }); // Select all text
-      await page.keyboard.press('Backspace');
+    // Type into each field sequentially
+    for (const field of fields) {
+      const { selector, text, clear = true, waitForElementTimeout = 5000 } = field;
+      currentSelector = selector;
+      
+      await page.waitForSelector(selector, { timeout: waitForElementTimeout, visible: true });
+      
+      if (clear) {
+        await page.click(selector, { clickCount: 3 }); // Select all text
+        await page.keyboard.press('Backspace');
+      }
+      
+      logger.info(`Typing into: ${selector}`);
+      await page.type(selector, String(text), { delay: TYPE_DELAY_MS });
+      filledSelectors.push(selector);
+      currentFieldIndex++;
     }
     
-    logger.info(`Typing into: ${selector}`);
-    await page.type(selector, String(text), { delay: typeDelay });
+    const fieldsSummary = filledSelectors.length === 1 
+      ? filledSelectors[0] 
+      : `${filledSelectors.length} fields (${filledSelectors.join(', ')})`;
     
     if (returnHtml) {
       // Wait for page to stabilize (handles form validation, autocomplete, etc.)
@@ -202,11 +239,11 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
       const currentUrl = page.url();
       const html = await extractAndProcessHtml(page, removeUnnecessaryHTML);
       
-      logger.info(`type_text completed: typed into ${selector}`);
+      logger.info(`type_text completed: typed into ${fieldsSummary}`);
       
       return new TypeTextSuccessResponse(
         currentUrl,
-        `Typed text into: ${selector}`,
+        `Typed text into: ${fieldsSummary}`,
         html,
         [
           "Use MCPBrowser's type_text to fill additional fields",
@@ -228,11 +265,11 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
       
       const currentUrl = page.url();
       
-      logger.info(`type_text completed: typed into ${selector} (no HTML)`);
+      logger.info(`type_text completed: typed into ${fieldsSummary} (no HTML)`);
       
       return new TypeTextSuccessResponse(
         currentUrl,
-        `Typed text into: ${selector}`,
+        `Typed text into: ${fieldsSummary}`,
         null,
         [
           "Use MCPBrowser's get_current_html to see updated page state",
@@ -243,16 +280,63 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
       );
     }
   } catch (err) {
-    logger.error(`type_text failed: ${err.message}`);
-    return new InformationalResponse(
-      `Failed to type text: ${err.message}`,
-      'The input field was found but text could not be entered. It may be disabled, read-only, or covered by another element.',
-      [
+    // Build informative error message for agent
+    const totalFields = fields.length;
+    const failedFieldNum = currentFieldIndex + 1;
+    const errorMsg = err.message;
+    
+    // Determine error type for better guidance
+    const isNotFound = errorMsg.includes('Waiting for selector') || errorMsg.includes('failed: Waiting failed');
+    const isNotVisible = errorMsg.includes('not visible') || errorMsg.includes('hidden');
+    const isDetached = errorMsg.includes('detached') || errorMsg.includes('Node is detached');
+    
+    let reason;
+    let nextSteps;
+    
+    if (isNotFound) {
+      reason = `Selector not found: "${currentSelector}". The element may not exist on the page or have a different selector.`;
+      nextSteps = [
+        "Use MCPBrowser's get_current_html to find the correct selector",
+        "Use MCPBrowser's take_screenshot to visually inspect the form",
+        "Check for typos in the selector or try a simpler selector (e.g., 'input[type=\"text\"]')",
+        "The element may load dynamically - try increasing waitForElementTimeout"
+      ];
+    } else if (isNotVisible) {
+      reason = `Element "${currentSelector}" exists but is not visible. It may be hidden, collapsed, or off-screen.`;
+      nextSteps = [
+        "Use MCPBrowser's take_screenshot to see the page state",
+        "Use MCPBrowser's click_element to expand/show the form section first",
+        "Use MCPBrowser's scroll_page to bring the element into view"
+      ];
+    } else if (isDetached) {
+      reason = `Element "${currentSelector}" was removed from the page during interaction. The page may have reloaded or updated.`;
+      nextSteps = [
+        "Use MCPBrowser's get_current_html to check current page state",
+        "Retry the type_text call - the page may have stabilized"
+      ];
+    } else {
+      reason = `Failed to interact with "${currentSelector}": ${errorMsg}`;
+      nextSteps = [
         "Use MCPBrowser's get_current_html to verify page state",
         "Use MCPBrowser's take_screenshot to see what's on the page visually",
-        "Check if the selector is correct",
-        "Verify the input field is visible and enabled"
-      ]
+        "The element may be disabled or read-only"
+      ];
+    }
+    
+    // Build progress summary
+    let progressInfo;
+    if (filledSelectors.length === 0) {
+      progressInfo = `Failed on field 1 of ${totalFields}. No fields were filled.`;
+    } else {
+      progressInfo = `Failed on field ${failedFieldNum} of ${totalFields}. Successfully filled ${filledSelectors.length} field(s): ${filledSelectors.join(', ')}. Do NOT re-type these fields.`;
+    }
+    
+    logger.error(`type_text failed on field ${failedFieldNum}/${totalFields} (${currentSelector}): ${errorMsg}`);
+    
+    return new InformationalResponse(
+      `${progressInfo}`,
+      reason,
+      nextSteps
     );
   }
 }

package/src/browsers/brave.js

@@ -0,0 +1,66 @@
+/**
+ * Brave browser implementation for MCPBrowser
+ * Brave is Chromium-based and uses the same CDP protocol as Chrome
+ */
+
+import { ChromiumBrowser } from './ChromiumBrowser.js';
+import os from "os";
+
+/**
+ * Get platform-specific default paths where Brave browser is typically installed.
+ * @returns {string[]} Array of possible Brave executable paths for the current platform
+ */
+function getDefaultBravePaths() {
+  const platform = os.platform();
+  
+  if (platform === "win32") {
+    return [
+      "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe",
+      "C:/Program Files (x86)/BraveSoftware/Brave-Browser/Application/brave.exe",
+      `${os.homedir()}/AppData/Local/BraveSoftware/Brave-Browser/Application/brave.exe`,
+    ];
+  } else if (platform === "darwin") {
+    return [
+      "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    ];
+  } else {
+    return [
+      "/usr/bin/brave",
+      "/usr/bin/brave-browser",
+      "/usr/bin/brave-browser-stable",
+      "/opt/brave.com/brave/brave-browser",
+      "/snap/bin/brave",
+    ];
+  }
+}
+
+/**
+ * Brave browser class implementation
+ * Extends ChromiumBrowser with Brave-specific configuration
+ */
+export class BraveBrowser extends ChromiumBrowser {
+  constructor() {
+    const config = {
+      name: 'Brave',
+      host: process.env.BRAVE_REMOTE_DEBUG_HOST || "127.0.0.1",
+      port: Number(process.env.BRAVE_REMOTE_DEBUG_PORT || 9224),
+      wsEndpoint: process.env.BRAVE_WS_ENDPOINT,
+      executablePath: process.env.BRAVE_PATH,
+      defaultPaths: getDefaultBravePaths(),
+      userDataDirName: 'BraveDebug'
+    };
+    super(config);
+  }
+}
+
+// Legacy exports for backward compatibility
+export async function connectBrave() {
+  const brave = new BraveBrowser();
+  return await brave.connect();
+}
+
+export async function disconnectBrave(browser) {
+  if (browser && browser.isConnected()) {
+    await browser.disconnect();
+  }
+}

package/src/core/browser.js

@@ -5,6 +5,7 @@
 
 import { ChromeBrowser } from '../browsers/chrome.js';
 import { EdgeBrowser } from '../browsers/edge.js';
+import { BraveBrowser } from '../browsers/brave.js';
 import os from 'os';
 import logger from './logger.js';
 
@@ -17,15 +18,16 @@ const browserInstances = new Map();
 
 /**
  * Detect the default browser on the system
- * @returns {Promise<string>} Browser type (chrome, edge)
+ * @returns {Promise<string>} Browser type (chrome, edge, brave)
  */
 async function detectDefaultBrowser() {
   const platform = os.platform();
   
-  // Priority order: Chrome > Edge
+  // Priority order: Chrome > Edge > Brave
   const browsers = [
     new ChromeBrowser(),
-    new EdgeBrowser()
+    new EdgeBrowser(),
+    new BraveBrowser()
   ];
   
   for (const browser of browsers) {
@@ -67,10 +69,13 @@ export async function GetBrowser(type = '') {
     case 'edge':
       browser = new EdgeBrowser();
       break;
+    case 'brave':
+      browser = new BraveBrowser();
+      break;
     default:
       throw new Error(
         `Unsupported browser type: ${type}. ` +
-        `Supported: chrome, edge. ` +
+        `Supported: chrome, edge, brave. ` +
         `Leave empty for auto-detection.`
       );
   }

package/src/mcp-browser.js

@@ -106,7 +106,7 @@ async function main() {
       // Return a proper error response instead of throwing
       return new ErrorResponse(
         `${name} failed: ${error.message}`,
-        ['Check browser is installed', 'Try specifying browser parameter explicitly (chrome or edge)', 'Check MCP server logs for details']
+        ['Check browser is installed', 'Try specifying browser parameter explicitly (chrome, edge, or brave)', 'Check MCP server logs for details']
       ).toMcpFormat();
     }