mcpbrowser 0.3.45 → 0.3.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.45",
+  "version": "0.3.47",
   "mcpName": "io.github.cherchyk/mcpbrowser",
   "type": "module",
   "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.",

package/src/actions/click-element.js

@@ -29,6 +29,7 @@ import { extractAndProcessHtml, waitForPageReady } from '../core/page.js';
 import { MCPResponse, InformationalResponse } from '../core/responses.js';
 import logger from '../core/logger.js';
 import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
+import { scanPageForms } from './detect-forms.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -38,7 +39,7 @@ import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader
  * Structured response for browser_click_element with JS fallback metadata
  */
 export class ClickWithFallbackResponse extends MCPResponse {
-  constructor({ status, fallbackUsed = false, nativeAttempt, fallbackAttempt, postClickWait, currentUrl, html = null, message, nextSteps = [], recommendedPlugins = [] }) {
+  constructor({ status, fallbackUsed = false, nativeAttempt, fallbackAttempt, postClickWait, currentUrl, html = null, message, nextSteps = [], recommendedPlugins = [], formData = null }) {
     super(nextSteps);
     this.status = status;
     this.fallbackUsed = fallbackUsed;
@@ -49,6 +50,9 @@ export class ClickWithFallbackResponse extends MCPResponse {
     this.html = html;
     this.message = message;
     this.recommendedPlugins = recommendedPlugins;
+    this.forms = formData?.forms || [];
+    this.orphanedFields = formData?.orphanedFields || [];
+    this.totalFieldCount = formData?.totalFieldCount || 0;
   }
 
   _getAdditionalFields() {
@@ -61,7 +65,10 @@ export class ClickWithFallbackResponse extends MCPResponse {
       currentUrl: this.currentUrl,
       html: this.html,
       message: this.message,
-      recommendedPlugins: this.recommendedPlugins
+      recommendedPlugins: this.recommendedPlugins,
+      forms: this.forms,
+      orphanedFields: this.orphanedFields,
+      totalFieldCount: this.totalFieldCount
     };
   }
 
@@ -91,7 +98,8 @@ export const CLICK_ELEMENT_TOOL = {
       waitForElementTimeout: { type: "number", description: "Maximum time to wait for element in milliseconds", default: 1000 },
       returnHtml: { type: "boolean", description: "Whether to wait for stability and return HTML after clicking. Set to false for fast form interactions (checkboxes, radio buttons).", default: true },
       removeUnnecessaryHTML: { type: "boolean", description: "Remove Unnecessary HTML for size reduction by 90%. Only used when returnHtml is true.", default: true },
-      postClickWait: { type: "number", description: "Milliseconds to wait after click for SPAs to render dynamic content.", default: 1000 }
+      postClickWait: { type: "number", description: "Milliseconds to wait after click for SPAs to render dynamic content.", default: 1000 },
+      detectForms: { type: "boolean", description: "Scan page for forms after click and return structured form data (fields, selectors, submit buttons, orphaned inputs). Only applies when returnHtml=true. Set to true when you need to fill or interact with forms after clicking.", default: false }
     },
     required: ["url"],
     additionalProperties: false,
@@ -135,6 +143,9 @@ export const CLICK_ELEMENT_TOOL = {
         type: ["string", "null"], 
         description: "Page HTML if returnHtml was true, null otherwise" 
       },
+      forms: { type: "array", items: { type: "object" }, description: "Detected forms with fields, selectors, and metadata (when returnHtml is true)" },
+      orphanedFields: { type: "array", items: { type: "object" }, description: "Input/select/textarea elements not inside any <form> (when returnHtml is true)" },
+      totalFieldCount: { type: "number", description: "Total number of form fields found on the page" },
       nextSteps: { 
         type: "array", 
         items: { type: "string" },
@@ -181,7 +192,7 @@ export const CLICK_ELEMENT_TOOL = {
  *   returnHtml: false 
  * });
  */
-export async function clickElement({ url, selector, text, waitForElementTimeout = 30000, returnHtml = true, removeUnnecessaryHTML = true, postClickWait = 1000 }) {
+export async function clickElement({ url, selector, text, waitForElementTimeout = 30000, returnHtml = true, removeUnnecessaryHTML = true, postClickWait = 1000, detectForms = false }) {
   logger.info(`browser_click_element called: ${selector || `text="${text}"`}`);
   
   if (!url) {
@@ -327,6 +338,17 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
 
     const currentUrl = page.url();
     const html = finalStatus === 'success' && returnHtml ? await extractAndProcessHtml(page, removeUnnecessaryHTML) : null;
+
+    // Scan for forms when requested and returning HTML (lightweight, ~50-100ms)
+    let formData = null;
+    if (detectForms && finalStatus === 'success' && returnHtml) {
+      try {
+        formData = await scanPageForms(page);
+      } catch (err) {
+        logger.debug(`Form scan failed (non-fatal): ${err.message}`);
+      }
+    }
+
     const baseMessage = selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`;
     const message = finalStatus === 'success'
       ? baseMessage
@@ -362,7 +384,8 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       html,
       message,
       nextSteps,
-      recommendedPlugins: html ? getRecommendedPlugins(currentUrl, html) : []
+      recommendedPlugins: html ? getRecommendedPlugins(currentUrl, html) : [],
+      formData
     });
   } catch (err) {
     logger.error(`browser_click_element failed: ${err.message}`);

package/src/actions/detect-forms.js

@@ -0,0 +1,502 @@
+/**
+ * detect-forms.js - Auto Form Discovery
+ * Scans the current page and returns structured JSON of all forms,
+ * their fields, submit buttons, and orphaned inputs (common in SPAs).
+ */
+
+import { getBrowser, getValidatedPage } from '../core/browser.js';
+import { MCPResponse, InformationalResponse } from '../core/responses.js';
+import logger from '../core/logger.js';
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+// ============================================================================
+// RESPONSE CLASS
+// ============================================================================
+
+/**
+ * Response for successful detect_forms operations
+ */
+export class DetectFormsResponse extends MCPResponse {
+  /**
+   * @param {Object} params
+   * @param {Array} params.forms - Array of form objects
+   * @param {Array} params.orphanedFields - Fields not inside any <form>
+   * @param {number} params.totalFieldCount - Total number of fields found
+   * @param {string} params.summary - Human-readable summary
+   * @param {string[]} params.nextSteps - Suggested next actions
+   */
+  constructor({ forms, orphanedFields, totalFieldCount, summary, nextSteps = [] }) {
+    super(nextSteps);
+
+    if (!Array.isArray(forms)) {
+      throw new TypeError('forms must be an array');
+    }
+    if (!Array.isArray(orphanedFields)) {
+      throw new TypeError('orphanedFields must be an array');
+    }
+    if (typeof totalFieldCount !== 'number') {
+      throw new TypeError('totalFieldCount must be a number');
+    }
+    if (typeof summary !== 'string') {
+      throw new TypeError('summary must be a string');
+    }
+
+    this.forms = forms;
+    this.orphanedFields = orphanedFields;
+    this.totalFieldCount = totalFieldCount;
+    this.summary = summary;
+  }
+
+  _getAdditionalFields() {
+    return {
+      forms: this.forms,
+      orphanedFields: this.orphanedFields,
+      totalFieldCount: this.totalFieldCount,
+      summary: this.summary
+    };
+  }
+
+  getTextSummary() {
+    return this.summary;
+  }
+}
+
+// ============================================================================
+// TOOL DEFINITION
+// ============================================================================
+
+/**
+ * @type {Tool}
+ */
+export const DETECT_FORMS_TOOL = {
+  name: "browser_detect_forms",
+  title: "Detect Forms",
+  description: "**AUTO FORM DISCOVERY** - Scans the current page and returns structured JSON of all forms: fields (name, type, required, placeholder, current value, validation constraints), submit buttons, and orphaned inputs not inside any <form> (common in SPAs). Use this BEFORE filling forms to understand what fields exist and how to interact with them.\n\n**PREREQUISITE**: Page MUST be loaded with browser_fetch_webpage first.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "URL of the already-loaded page" },
+      includeHidden: { type: "boolean", default: false, description: "Include hidden fields (type=hidden). Useful for understanding form state." }
+    },
+    required: ["url"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      forms: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            formSelector: { type: "string" },
+            action: { type: "string" },
+            method: { type: "string" },
+            formType: { type: "string" },
+            fields: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  selector: { type: "string" },
+                  name: { type: "string" },
+                  id: { type: "string" },
+                  tag: { type: "string" },
+                  type: { type: "string" },
+                  required: { type: "boolean" },
+                  placeholder: { type: "string" },
+                  currentValue: { type: "string" },
+                  label: { type: "string" },
+                  validation: {
+                    type: "object",
+                    properties: {
+                      min: { type: "string" },
+                      max: { type: "string" },
+                      pattern: { type: "string" },
+                      maxLength: { type: "number" }
+                    }
+                  }
+                }
+              }
+            },
+            submitButton: {
+              type: ["object", "null"],
+              properties: {
+                selector: { type: "string" },
+                text: { type: "string" },
+                type: { type: "string" }
+              }
+            }
+          }
+        },
+        description: "Array of detected forms with fields and metadata"
+      },
+      orphanedFields: {
+        type: "array",
+        items: { type: "object" },
+        description: "Input/select/textarea elements not inside any <form>"
+      },
+      totalFieldCount: { type: "number", description: "Total number of fields found" },
+      summary: { type: "string", description: "Human-readable summary of detected forms" },
+      nextSteps: {
+        type: "array",
+        items: { type: "string" },
+        description: "Suggested next actions"
+      }
+    },
+    required: ["forms", "orphanedFields", "totalFieldCount", "summary", "nextSteps"],
+    additionalProperties: false
+  }
+};
+
+// ============================================================================
+// PAGE EVALUATION FUNCTION
+// ============================================================================
+
+/**
+ * Runs inside the browser context via page.evaluate().
+ * Scans all forms and orphaned fields, resolves labels, classifies form types.
+ * @param {boolean} includeHidden - Whether to include hidden fields
+ * @returns {Object} Raw form data
+ */
+function buildScanFunction() {
+  return (includeHidden) => {
+    /**
+     * Build a CSS selector for an element
+     */
+    function buildSelector(el) {
+      if (el.id) return `#${CSS.escape(el.id)}`;
+      if (el.name) {
+        const tag = el.tagName.toLowerCase();
+        const sel = `${tag}[name="${CSS.escape(el.name)}"]`;
+        if (document.querySelectorAll(sel).length === 1) return sel;
+      }
+      // Fallback: nth-of-type relative to parent
+      const parent = el.parentElement;
+      if (!parent) return el.tagName.toLowerCase();
+      const tag = el.tagName.toLowerCase();
+      const siblings = Array.from(parent.children).filter(c => c.tagName === el.tagName);
+      if (siblings.length === 1) return `${buildSelector(parent)} > ${tag}`;
+      const idx = siblings.indexOf(el) + 1;
+      return `${buildSelector(parent)} > ${tag}:nth-of-type(${idx})`;
+    }
+
+    /**
+     * Resolve label text for a field element
+     * Priority: <label for> → parent <label> → aria-label → aria-labelledby → placeholder
+     */
+    function resolveLabel(el) {
+      // 1. Explicit <label for="id">
+      if (el.id) {
+        const label = document.querySelector(`label[for="${CSS.escape(el.id)}"]`);
+        if (label) return label.textContent.trim();
+      }
+      // 2. Parent <label> wrapping the input
+      const parentLabel = el.closest('label');
+      if (parentLabel) {
+        // Get text content excluding the input itself
+        const clone = parentLabel.cloneNode(true);
+        clone.querySelectorAll('input, select, textarea').forEach(c => c.remove());
+        const text = clone.textContent.trim();
+        if (text) return text;
+      }
+      // 3. aria-label
+      const ariaLabel = el.getAttribute('aria-label');
+      if (ariaLabel) return ariaLabel.trim();
+      // 4. aria-labelledby
+      const ariaLabelledBy = el.getAttribute('aria-labelledby');
+      if (ariaLabelledBy) {
+        const refEl = document.getElementById(ariaLabelledBy);
+        if (refEl) return refEl.textContent.trim();
+      }
+      // 5. placeholder
+      const placeholder = el.getAttribute('placeholder');
+      if (placeholder) return placeholder.trim();
+      return '';
+    }
+
+    /**
+     * Extract field info from an input/select/textarea element
+     */
+    function extractField(el) {
+      const tag = el.tagName.toLowerCase();
+      const type = el.getAttribute('type') || (tag === 'select' ? 'select' : tag === 'textarea' ? 'textarea' : 'text');
+      return {
+        selector: buildSelector(el),
+        name: el.name || '',
+        id: el.id || '',
+        tag,
+        type,
+        required: el.required || el.getAttribute('aria-required') === 'true',
+        placeholder: el.getAttribute('placeholder') || '',
+        currentValue: el.value || '',
+        label: resolveLabel(el),
+        validation: {
+          min: el.getAttribute('min') || '',
+          max: el.getAttribute('max') || '',
+          pattern: el.getAttribute('pattern') || '',
+          maxLength: el.maxLength >= 0 ? el.maxLength : null
+        }
+      };
+    }
+
+    /**
+     * Find the submit button for a form
+     */
+    function findSubmitButton(form) {
+      // Explicit submit button
+      const submit = form.querySelector('button[type="submit"], input[type="submit"]');
+      if (submit) {
+        return {
+          selector: buildSelector(submit),
+          text: (submit.textContent || submit.value || '').trim(),
+          type: submit.getAttribute('type') || 'submit'
+        };
+      }
+      // Fallback: first <button> without type (default is submit)
+      const btn = form.querySelector('button:not([type])');
+      if (btn) {
+        return {
+          selector: buildSelector(btn),
+          text: btn.textContent.trim(),
+          type: 'submit'
+        };
+      }
+      return null;
+    }
+
+    /**
+     * Classify form type via heuristics
+     */
+    function classifyForm(fields, form) {
+      const visibleFields = fields.filter(f => f.type !== 'hidden');
+      const hasPassword = visibleFields.some(f => f.type === 'password');
+      const hasEmail = visibleFields.some(f => f.type === 'email' || f.name.includes('email') || f.id.includes('email'));
+      const hasTextarea = visibleFields.some(f => f.tag === 'textarea');
+      const hasSearch = visibleFields.some(f => f.type === 'search');
+
+      // Check for credit card patterns
+      const cardPatterns = /card|cc[-_]?num|cvv|cvc|expir|ccv/i;
+      const hasCardFields = visibleFields.some(f =>
+        cardPatterns.test(f.name) || cardPatterns.test(f.id) || cardPatterns.test(f.label)
+      );
+
+      if (hasCardFields) return 'checkout';
+      if (hasPassword && visibleFields.length <= 3) return 'login';
+      if (hasPassword && hasEmail && visibleFields.length > 3) return 'registration';
+      if (hasSearch) return 'search';
+      if (hasTextarea && hasEmail && !hasPassword) return 'contact';
+
+      // Check form action/class for search hints
+      const formAction = (form.getAttribute('action') || '').toLowerCase();
+      const formClass = (form.getAttribute('class') || '').toLowerCase();
+      const formRole = (form.getAttribute('role') || '').toLowerCase();
+      if (formRole === 'search' || formAction.includes('search') || formClass.includes('search')) return 'search';
+
+      // Single text input with submit = likely search
+      if (visibleFields.length === 1 && (visibleFields[0].type === 'text' || visibleFields[0].type === 'search')) return 'search';
+
+      return 'other';
+    }
+
+    const fieldSelector = 'input, select, textarea';
+    const forms = [];
+
+    // Process each <form> element
+    document.querySelectorAll('form').forEach((form, index) => {
+      const fieldElements = Array.from(form.querySelectorAll(fieldSelector));
+      let fields = fieldElements.map(extractField);
+
+      // Filter hidden fields unless includeHidden
+      if (!includeHidden) {
+        fields = fields.filter(f => f.type !== 'hidden');
+      }
+
+      forms.push({
+        formSelector: buildSelector(form),
+        action: form.getAttribute('action') || '',
+        method: (form.getAttribute('method') || 'GET').toUpperCase(),
+        formType: classifyForm(fields, form),
+        fields,
+        submitButton: findSubmitButton(form)
+      });
+    });
+
+    // Collect orphaned fields (not inside any <form>)
+    const allFields = Array.from(document.querySelectorAll(fieldSelector));
+    let orphanedFields = allFields
+      .filter(el => !el.closest('form'))
+      .map(extractField);
+
+    if (!includeHidden) {
+      orphanedFields = orphanedFields.filter(f => f.type !== 'hidden');
+    }
+
+    const totalFieldCount = forms.reduce((sum, f) => sum + f.fields.length, 0) + orphanedFields.length;
+
+    return { forms, orphanedFields, totalFieldCount };
+  };
+}
+
+// ============================================================================
+// SHARED SCAN FUNCTION (used by fetch-page, get-current-html, click-element)
+// ============================================================================
+
+/**
+ * Scan a page for forms and return structured data.
+ * Lightweight (~50-100ms) - safe to call on every page load.
+ * @param {Object} page - Puppeteer page object
+ * @param {boolean} [includeHidden=false] - Whether to include hidden fields
+ * @returns {Promise<{forms: Array, orphanedFields: Array, totalFieldCount: number}>}
+ */
+export async function scanPageForms(page, includeHidden = false) {
+  const scanFn = buildScanFunction();
+  return await page.evaluate(scanFn, includeHidden);
+}
+
+// ============================================================================
+// ACTION FUNCTION
+// ============================================================================
+
+/**
+ * Detect all forms on the current page
+ * @param {Object} params - Parameters
+ * @param {string} params.url - The URL of the page to scan
+ * @param {boolean} [params.includeHidden=false] - Whether to include hidden fields
+ * @returns {Promise<DetectFormsResponse|InformationalResponse>}
+ */
+export async function detectForms({ url, includeHidden = false }) {
+  logger.info(`browser_detect_forms called: url=${url}, includeHidden=${includeHidden}`);
+
+  if (!url) {
+    throw new Error("url parameter is required");
+  }
+
+  let hostname;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  // Ensure browser connection
+  try {
+    await getBrowser();
+  } catch (err) {
+    logger.error(`browser_detect_forms: 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'
+      ]
+    );
+  }
+
+  // Validate page exists and is usable
+  const { page, error: pageError } = await getValidatedPage(hostname);
+
+  if (!page) {
+    const isConnectionLost = pageError && pageError.includes('connection');
+    logger.debug(`browser_detect_forms: ${pageError || 'No page found for ' + hostname}`);
+    return new InformationalResponse(
+      isConnectionLost ? `Page connection lost for ${hostname}` : `No open page found for ${hostname}`,
+      isConnectionLost
+        ? 'The browser tab was closed or the connection was lost. The page needs to be reloaded.'
+        : 'The page must be loaded before you can detect forms',
+      [
+        "Use MCPBrowser's browser_fetch_webpage tool to load the page first",
+        "Then retry MCPBrowser's browser_detect_forms with the same URL"
+      ]
+    );
+  }
+
+  try {
+    const raw = await scanPageForms(page, includeHidden);
+
+    // Build summary
+    const summary = buildSummary(raw.forms, raw.orphanedFields, raw.totalFieldCount);
+
+    logger.info(`browser_detect_forms completed: ${summary}`);
+
+    // Build next steps based on discovered forms
+    const nextSteps = buildNextSteps(raw.forms, raw.orphanedFields);
+
+    return new DetectFormsResponse({
+      forms: raw.forms,
+      orphanedFields: raw.orphanedFields,
+      totalFieldCount: raw.totalFieldCount,
+      summary,
+      nextSteps
+    });
+  } catch (err) {
+    logger.error(`browser_detect_forms failed: ${err.message}`);
+    return new InformationalResponse(
+      `Failed to detect forms: ${err.message}`,
+      'Could not scan the page for forms. The page may have navigated away or the connection was lost.',
+      [
+        "Try MCPBrowser's browser_fetch_webpage to reload the page",
+        "Use MCPBrowser's browser_close_tab and start fresh if needed"
+      ]
+    );
+  }
+}
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+/**
+ * Build a human-readable summary of detected forms
+ */
+function buildSummary(forms, orphanedFields, totalFieldCount) {
+  if (forms.length === 0 && orphanedFields.length === 0) {
+    return 'No forms or input fields found on this page';
+  }
+
+  const parts = [];
+  if (forms.length > 0) {
+    const formDescriptions = forms.map(f => {
+      const fieldCount = f.fields.length;
+      return `1 ${f.formType} form (${fieldCount} field${fieldCount !== 1 ? 's' : ''})`;
+    });
+    parts.push(formDescriptions.join(', '));
+  }
+  if (orphanedFields.length > 0) {
+    parts.push(`${orphanedFields.length} orphaned field${orphanedFields.length !== 1 ? 's' : ''} (not in any form)`);
+  }
+
+  return `Found ${forms.length} form${forms.length !== 1 ? 's' : ''}: ${parts.join('; ')}. Total fields: ${totalFieldCount}`;
+}
+
+/**
+ * Build contextual next steps based on what was found
+ */
+function buildNextSteps(forms, orphanedFields) {
+  const steps = [];
+
+  if (forms.length > 0) {
+    const primaryForm = forms[0];
+    if (primaryForm.fields.length > 0) {
+      const firstField = primaryForm.fields[0];
+      steps.push(`Use MCPBrowser's browser_type_text to fill form fields (e.g., selector: '${firstField.selector}')`);
+    }
+    if (primaryForm.submitButton) {
+      steps.push(`Use MCPBrowser's browser_click_element to submit the form (selector: '${primaryForm.submitButton.selector}')`);
+    }
+  }
+
+  if (orphanedFields.length > 0) {
+    steps.push("Use MCPBrowser's browser_type_text for orphaned fields (SPA inputs not inside a <form>)");
+  }
+
+  steps.push("Use MCPBrowser's browser_take_screenshot if form layout is unclear from the data");
+  steps.push("Use MCPBrowser's browser_get_current_html to see full page HTML");
+
+  return steps;
+}

package/src/actions/execute-javascript.js

@@ -209,6 +209,24 @@ export async function executeJavascript({ url, script, timeoutMs = EXECUTION_TIM
   }
   const urlChanged = currentUrl !== beforeUrl;
 
+  // Detect CSP block or silent evaluation failure:
+  // When page.evaluate() is blocked by CSP, Puppeteer returns undefined (not an error).
+  // Distinguish this from a script that intentionally returns nothing.
+  if (evalResult === undefined || evalResult === null) {
+    return new ExecuteJavascriptResponse({
+      result: null,
+      type: 'undefined',
+      executionTimeMs,
+      truncated: false,
+      urlChanged,
+      currentUrl,
+      error: {
+        name: 'EvaluationEmpty',
+        message: 'Script evaluation returned no result. Possible causes: page Content Security Policy (CSP) blocked evaluation, the script has no return value, or the page context is sandboxed. Try browser_take_screenshot to verify the page is loaded, or use a simpler expression like "document.title" to test page accessibility.'
+      }
+    });
+  }
+
   if (evalResult?.error) {
     return new ExecuteJavascriptResponse({
       result: null,

package/src/actions/fetch-page.js

@@ -9,6 +9,7 @@ import { isLikelyAuthUrl, waitForAuth } from '../core/auth.js';
 import { MCPResponse, ErrorResponse, HttpStatusResponse, InformationalResponse } from '../core/responses.js';
 import logger from '../core/logger.js';
 import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
+import { scanPageForms } from './detect-forms.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -27,8 +28,9 @@ export class FetchPageSuccessResponse extends MCPResponse {
    * @param {string} html - Page HTML content
    * @param {string[]} nextSteps - Suggested next actions
    * @param {Array} [recommendedPlugins] - Detected plugin metadata
+   * @param {Object} [formData] - Detected forms data
    */
-  constructor(currentUrl, html, nextSteps, recommendedPlugins = []) {
+  constructor(currentUrl, html, nextSteps, recommendedPlugins = [], formData = null) {
     super(nextSteps);
     
     if (typeof currentUrl !== 'string') {
@@ -41,13 +43,19 @@ export class FetchPageSuccessResponse extends MCPResponse {
     this.currentUrl = currentUrl;
     this.html = html;
     this.recommendedPlugins = recommendedPlugins;
+    this.forms = formData?.forms || [];
+    this.orphanedFields = formData?.orphanedFields || [];
+    this.totalFieldCount = formData?.totalFieldCount || 0;
   }
 
   _getAdditionalFields() {
     return {
       currentUrl: this.currentUrl,
       html: this.html,
-      recommendedPlugins: this.recommendedPlugins
+      recommendedPlugins: this.recommendedPlugins,
+      forms: this.forms,
+      orphanedFields: this.orphanedFields,
+      totalFieldCount: this.totalFieldCount
     };
   }
 
@@ -77,7 +85,9 @@ export const FETCH_WEBPAGE_TOOL = {
         enum: ["", "chrome", "edge"]
       },
       removeUnnecessaryHTML: { type: "boolean", description: "Remove Unnecessary HTML for size reduction by 90%.", default: true },
-      postLoadWait: { type: "number", description: "Additional milliseconds to wait after page load before extracting HTML. Use for pages that need extra time to render. Default: 0 (no extra wait, SPA detection handles most cases automatically).", default: 0 }
+      selector: { type: "string", description: "CSS selector to extract a specific DOM subtree instead of the full page. Use to scope extraction and reduce response size (e.g., 'main', '[role=\"main\"]', 'body > div:first-child'). If no elements match, falls back to full page with a note." },
+      postLoadWait: { type: "number", description: "Additional milliseconds to wait after page load before extracting HTML. Use for pages that need extra time to render. Default: 0 (no extra wait, SPA detection handles most cases automatically).", default: 0 },
+      detectForms: { type: "boolean", description: "Scan page for forms and return structured form data (fields, selectors, submit buttons, orphaned inputs). Set to true when you need to fill or interact with forms.", default: false }
     },
     required: ["url"],
     additionalProperties: false
@@ -87,6 +97,9 @@ export const FETCH_WEBPAGE_TOOL = {
     properties: {
       currentUrl: { type: "string", description: "Final URL after any redirects" },
       html: { type: "string", description: "Page HTML content" },
+      forms: { type: "array", items: { type: "object" }, description: "Detected forms with fields, selectors, and metadata" },
+      orphanedFields: { type: "array", items: { type: "object" }, description: "Input/select/textarea elements not inside any <form>" },
+      totalFieldCount: { type: "number", description: "Total number of form fields found on the page" },
       nextSteps: { 
         type: "array", 
         items: { type: "string" },
@@ -122,7 +135,7 @@ export const FETCH_WEBPAGE_TOOL = {
  * @param {number} [params.postLoadWait=0] - Additional milliseconds to wait after page load before extracting HTML
  * @returns {Promise<Object>} Result object with success status, URL, HTML content, or error details
  */
-export async function fetchPage({ url, browser = '', removeUnnecessaryHTML = true, postLoadWait = 0 }) {
+export async function fetchPage({ url, browser = '', removeUnnecessaryHTML = true, selector = null, postLoadWait = 0, detectForms = false }) {
   logger.info(`browser_fetch_webpage called: url=${url}`);
   
   // Handle missing URL with environment variable fallback
@@ -150,7 +163,7 @@ export async function fetchPage({ url, browser = '', removeUnnecessaryHTML = tru
 
   // Queue this request - processed sequentially, one at a time
   return queueRequest(async () => {
-    return await doFetchPage({ url, browser, removeUnnecessaryHTML, postLoadWait });
+    return await doFetchPage({ url, browser, removeUnnecessaryHTML, selector, postLoadWait, detectForms });
   });
 }
 
@@ -158,7 +171,7 @@ export async function fetchPage({ url, browser = '', removeUnnecessaryHTML = tru
  * Internal function that does the actual page fetching.
  * Called by the queue processor - only one runs at a time.
  */
-async function doFetchPage({ url, browser, removeUnnecessaryHTML, postLoadWait }) {
+async function doFetchPage({ url, browser, removeUnnecessaryHTML, selector, postLoadWait, detectForms }) {
   const originalHostname = new URL(url).hostname;
 
   // Ensure browser connection
@@ -215,7 +228,17 @@ async function doFetchPage({ url, browser, removeUnnecessaryHTML, postLoadWait }
     }
     
     // Extract and process HTML
-    const processedHtml = await extractAndProcessHtml(page, removeUnnecessaryHTML);
+    const processedHtml = await extractAndProcessHtml(page, removeUnnecessaryHTML, selector);
+    
+    // Scan for forms when requested (lightweight, ~50-100ms)
+    let formData = null;
+    if (detectForms) {
+      try {
+        formData = await scanPageForms(page);
+      } catch (err) {
+        logger.debug(`Form scan failed (non-fatal): ${err.message}`);
+      }
+    }
     
     logger.info(`browser_fetch_webpage completed: ${page.url()}`);
     
@@ -236,7 +259,8 @@ async function doFetchPage({ url, browser, removeUnnecessaryHTML, postLoadWait }
         "Use MCPBrowser's browser_take_screenshot if page has charts, images, or complex visual layout that's hard to understand from HTML",
         "Use MCPBrowser's browser_close_tab when finished to free browser resources"
       ],
-      getRecommendedPlugins(page.url(), processedHtml)
+      getRecommendedPlugins(page.url(), processedHtml),
+      formData
     );
   } catch (err) {
     logger.error(`browser_fetch_webpage failed: ${err.message || String(err)}`);

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

@@ -7,6 +7,7 @@ import { extractAndProcessHtml } from '../core/page.js';
 import { MCPResponse, InformationalResponse } from '../core/responses.js';
 import logger from '../core/logger.js';
 import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
+import { scanPageForms } from './detect-forms.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -25,8 +26,9 @@ export class GetCurrentHtmlSuccessResponse extends MCPResponse {
    * @param {string} html - Page HTML content
    * @param {string[]} nextSteps - Suggested next actions
    * @param {Array} [recommendedPlugins] - Detected plugin metadata
+   * @param {Object} [formData] - Detected forms data
    */
-  constructor(currentUrl, html, nextSteps, recommendedPlugins = []) {
+  constructor(currentUrl, html, nextSteps, recommendedPlugins = [], formData = null) {
     super(nextSteps);
     
     if (typeof currentUrl !== 'string') {
@@ -39,13 +41,19 @@ export class GetCurrentHtmlSuccessResponse extends MCPResponse {
     this.currentUrl = currentUrl;
     this.html = html;
     this.recommendedPlugins = recommendedPlugins;
+    this.forms = formData?.forms || [];
+    this.orphanedFields = formData?.orphanedFields || [];
+    this.totalFieldCount = formData?.totalFieldCount || 0;
   }
 
   _getAdditionalFields() {
     return {
       currentUrl: this.currentUrl,
       html: this.html,
-      recommendedPlugins: this.recommendedPlugins
+      recommendedPlugins: this.recommendedPlugins,
+      forms: this.forms,
+      orphanedFields: this.orphanedFields,
+      totalFieldCount: this.totalFieldCount
     };
   }
 
@@ -69,7 +77,9 @@ export const GET_CURRENT_HTML_TOOL = {
     type: "object",
     properties: {
       url: { type: "string", description: "The URL of the page (must match a previously fetched page)" },
-      removeUnnecessaryHTML: { type: "boolean", description: "Remove Unnecessary HTML for size reduction by 90%.", default: true }
+      removeUnnecessaryHTML: { type: "boolean", description: "Remove Unnecessary HTML for size reduction by 90%.", default: true },
+      selector: { type: "string", description: "CSS selector to extract a specific DOM subtree instead of the full page. Use to scope extraction and reduce response size (e.g., 'main', '[role=\"main\"]', 'body > div:first-child'). If no elements match, falls back to full page with a note." },
+      detectForms: { type: "boolean", description: "Scan page for forms and return structured form data (fields, selectors, submit buttons, orphaned inputs). Set to true when you need to fill or interact with forms.", default: false }
     },
     required: ["url"],
     additionalProperties: false
@@ -79,6 +89,9 @@ export const GET_CURRENT_HTML_TOOL = {
     properties: {
       currentUrl: { type: "string", description: "Current page URL" },
       html: { type: "string", description: "Page HTML content" },
+      forms: { type: "array", items: { type: "object" }, description: "Detected forms with fields, selectors, and metadata" },
+      orphanedFields: { type: "array", items: { type: "object" }, description: "Input/select/textarea elements not inside any <form>" },
+      totalFieldCount: { type: "number", description: "Total number of form fields found on the page" },
       nextSteps: { 
         type: "array", 
         items: { type: "string" },
@@ -107,9 +120,9 @@ export const GET_CURRENT_HTML_TOOL = {
  * @param {boolean} [params.removeUnnecessaryHTML=true] - Whether to clean HTML
  * @returns {Promise<Object>} Result object with current HTML
  */
-export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
+export async function getCurrentHtml({ url, removeUnnecessaryHTML = true, selector = null, detectForms = false }) {
   const startTime = Date.now();
-  logger.info(`browser_get_current_html called: url=${url}`);
+  logger.info(`browser_get_current_html called: url=${url}${selector ? ` selector=${selector}` : ''}`);
   
   if (!url) {
     throw new Error("url parameter is required");
@@ -158,7 +171,32 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
 
   try {
     const currentUrl = page.url();
-    const html = await extractAndProcessHtml(page, removeUnnecessaryHTML);
+    const html = await extractAndProcessHtml(page, removeUnnecessaryHTML, selector);
+    
+    // Scan for forms when requested (lightweight, ~50-100ms)
+    let formData = null;
+    if (detectForms) {
+      try {
+        formData = await scanPageForms(page);
+      } catch (err) {
+        logger.debug(`Form scan failed (non-fatal): ${err.message}`);
+      }
+    }
+    
+    // Detect empty/near-empty HTML extraction (e.g., CSP blocking page.evaluate)
+    if (!html || html.trim().length < 100) {
+      logger.warn(`browser_get_current_html: HTML extraction returned empty/minimal content from ${currentUrl} (${html ? html.trim().length : 0} chars)`);
+      return new InformationalResponse(
+        `HTML extraction returned empty content from ${currentUrl}`,
+        'The page may be blocking evaluation via Content Security Policy (CSP), the page has not fully rendered, or the page uses a sandboxed context that prevents DOM reading.',
+        [
+          "Use MCPBrowser's browser_take_screenshot to verify the page is visually loaded",
+          "Use MCPBrowser's browser_execute_javascript with a simple script like 'document.title' to test page accessibility",
+          "Try MCPBrowser's browser_fetch_webpage to reload the page",
+          "Wait and retry — the page may still be rendering"
+        ]
+      );
+    }
     
     logger.info(`browser_get_current_html completed: got HTML from ${currentUrl}`);
     
@@ -172,7 +210,8 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
         "Use MCPBrowser's browser_take_screenshot if page layout or visual content is hard to understand from HTML",
         "Use MCPBrowser's browser_close_tab to free resources when done"
       ],
-      getRecommendedPlugins(currentUrl, html)
+      getRecommendedPlugins(currentUrl, html),
+      formData
     );
   } catch (err) {
     logger.error(`browser_get_current_html failed: ${err.message}`);

package/src/core/html.js

@@ -70,8 +70,9 @@ export function cleanHtml(html) {
   // Remove event handler attributes (onclick, onload, etc.)
   cleaned = cleaned.replace(/\s+on[a-z]+\s*=\s*["'][^"']*["']/gi, '');
   
-  // Remove role attributes
-  cleaned = cleaned.replace(/\s+role=["'][^"']*["']/gi, '');
+  // Keep role attributes — they're semantically valuable for LLM understanding
+  // and enable stable selectors like [role="main"], [role="navigation"]
+  // cleaned = cleaned.replace(/\s+role=["'][^"']*["']/gi, '');
   
   // Remove aria-* attributes
   cleaned = cleaned.replace(/\s+aria-[a-z0-9-]+=["'][^"']*["']/gi, '');

package/src/core/page.js

@@ -475,23 +475,52 @@ async function waitForNavigationToSettle(page) {
  * settle and retries once.
  * @param {Page} page - The Puppeteer page instance
  * @param {boolean} removeUnnecessaryHTML - Whether to clean the HTML
+ * @param {string|null} [selector=null] - CSS selector to extract a DOM subtree instead of full page
  * @returns {Promise<string>} The processed HTML
  */
-export async function extractAndProcessHtml(page, removeUnnecessaryHTML) {
+export async function extractAndProcessHtml(page, removeUnnecessaryHTML, selector = null) {
   let html;
+
+  const extractFn = selector
+    ? (sel) => {
+        const els = document.querySelectorAll(sel);
+        if (!els.length) return null;
+        return Array.from(els).map(el => el.outerHTML).join('\n');
+      }
+    : () => document.documentElement?.outerHTML || "";
+
+  const extractArg = selector || undefined;
+
   try {
-    html = await page.evaluate(() => document.documentElement?.outerHTML || "");
+    html = await page.evaluate(extractFn, extractArg);
   } catch (err) {
     if (isNavigationError(err)) {
       logger.debug('Late navigation during HTML extraction, waiting for settle...');
       await waitForNavigationToSettle(page);
       // Re-run page readiness — the new page may be a SPA that needs rendering time
       await waitForPageReady(page);
-      html = await page.evaluate(() => document.documentElement?.outerHTML || "");
+      html = await page.evaluate(extractFn, extractArg);
     } else {
       throw err;
     }
   }
+
+  // If selector matched nothing, fall back to full page with a note
+  if (selector && html === null) {
+    logger.debug(`Selector "${selector}" matched no elements, falling back to full page`);
+    try {
+      html = await page.evaluate(() => document.documentElement?.outerHTML || "");
+    } catch (err) {
+      if (isNavigationError(err)) {
+        await waitForNavigationToSettle(page);
+        await waitForPageReady(page);
+        html = await page.evaluate(() => document.documentElement?.outerHTML || "");
+      } else {
+        throw err;
+      }
+    }
+    html = `<!-- selector "${selector}" matched no elements; returning full page -->\n` + html;
+  }
   
   let processedHtml;
   if (removeUnnecessaryHTML) {
@@ -501,5 +530,12 @@ export async function extractAndProcessHtml(page, removeUnnecessaryHTML) {
     processedHtml = enrichHtml(html, page.url());
   }
   
+  // Warn when response is very large — the agent should use the selector parameter
+  // to scope extraction to a DOM subtree instead of fetching the entire page.
+  const htmlByteLength = new TextEncoder().encode(processedHtml).length;
+  if (htmlByteLength > 500_000) {
+    logger.warn(`Large HTML response (${(htmlByteLength / 1024).toFixed(0)}KB). Consider using the "selector" parameter to extract a specific DOM subtree instead of the full page.`);
+  }
+  
   return processedHtml;
 }

package/src/mcp-browser.js

@@ -32,6 +32,7 @@ import { takeScreenshot, TAKE_SCREENSHOT_TOOL } from './actions/take-screenshot.
 import { scrollPage, SCROLL_PAGE_TOOL } from './actions/scroll-page.js';
 import { executeJavascript, EXECUTE_JAVASCRIPT_TOOL } from './actions/execute-javascript.js';
 import { navigateHistory, NAVIGATE_HISTORY_TOOL } from './actions/navigate-history.js';
+import { detectForms, DETECT_FORMS_TOOL } from './actions/detect-forms.js';
 
 // Import plugin dispatch tools
 import { pluginAction, PLUGIN_ACTION_TOOL } from './actions/plugin-action.js';
@@ -80,6 +81,7 @@ async function main() {
     TAKE_SCREENSHOT_TOOL,
     SCROLL_PAGE_TOOL,
     NAVIGATE_HISTORY_TOOL,
+    DETECT_FORMS_TOOL,
     PLUGIN_INFO_TOOL,
     PLUGIN_ACTION_TOOL
   ];
@@ -146,6 +148,10 @@ async function main() {
           result = await navigateHistory(safeArgs);
           break;
 
+        case "browser_detect_forms":
+          result = await detectForms(safeArgs);
+          break;
+
         case "browser_plugin_info":
           result = pluginInfo(safeArgs);
           break;
@@ -213,6 +219,7 @@ export {
   takeScreenshot,
   scrollPage,
   navigateHistory,
+  detectForms,
   handleAcceptEula,
   // CLI exports
   isCliMode,