mcpbrowser 0.3.46 → 0.3.48

package/README.md

@@ -7,6 +7,10 @@
 
 > ⚠️ **Security Notice:** MCPBrowser extracts webpage content and provides it to your AI agent (e.g., GitHub Copilot, Claude, Kiro, Antigravity), 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.
 
+> 💡 **Why MCPBrowser over Puppeteer/Playwright MCP servers?** Puppeteer and Playwright are browser automation libraries — their MCP servers give agents raw, low-level browser commands. MCPBrowser uses Puppeteer under the hood and was built specifically for AI agents, adding an intelligence layer that handles the hard parts automatically.
+>
+> The agent gets clean HTML (90% smaller), automatic SPA detection (React, Vue, Angular), authentication flow handling (SSO, redirects, multi-step login), form discovery with multi-field filling, structured responses with next-step guidance, domain-based tab reuse, and instant DOM re-extraction without page reloads. Each MCPBrowser tool call replaces 5-8 raw browser automation calls — a typical 4-step workflow in MCPBrowser would take 20+ calls with Puppeteer/Playwright MCP, saving tokens and making the agent significantly faster. [See full comparison below.](#why-mcpbrowser-over-puppeteerplaywright-mcp-servers)
+
 **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.
@@ -20,9 +24,26 @@ Example workflow for AI assistant to use MCPBrowser
 4. browser_get_current_html → Extract the content after login
 ```
 
+## Why MCPBrowser over Puppeteer/Playwright MCP servers?
+
+Puppeteer and Playwright are browser automation libraries — their MCP servers expose low-level browser commands and the agent has to handle SPAs, auth flows, messy HTML, and edge cases on its own. **MCPBrowser was built specifically for AI agents.** It uses Puppeteer under the hood and adds an intelligence layer so the agent can focus on the task instead of fighting the browser.
+
+| | MCPBrowser | Puppeteer/Playwright MCP |
+|---|---|---|
+| **HTML output** | Clean, LLM-optimized (~90% smaller) — strips scripts, styles, SVGs, tracking attrs, converts relative URLs | Raw DOM |
+| **SPA support** | Auto-detects React, Vue, Angular, Svelte, Next.js, Nuxt — applies framework-aware wait strategies | Agent must configure waits manually |
+| **Authentication** | Detects login pages, SSO redirects, multi-step auth — follows redirect chains, two-phase timeouts (5s SSO → 20min manual) | Agent must script each auth step |
+| **Form interaction** | `browser_detect_forms` discovers all fields, labels, constraints; `browser_type_text` fills multiple fields at once | One field at a time, manual selectors |
+| **Response format** | Typed, structured with `nextSteps` guidance — soft vs hard failure distinction with recovery actions | Raw results, generic errors |
+| **Tab management** | Domain-pooled — reuses tabs, survives browser reconnection | New context per request |
+| **DOM re-extraction** | `browser_get_current_html` — instant, no reload (10-50x faster) | Must re-fetch full page |
+| **Plugin system** | Detects known sites by URL/DOM patterns, offers site-specific actions with confidence scoring | N/A |
+| **Built for** | AI agents | Browser test automation |
+| **Agent efficiency** | 1 tool call replaces 5-8 raw browser calls — a 4-step login flow takes 4 calls instead of 20+, saving tokens and round-trips | Each step (navigate, wait, query, type, click) is a separate call |
 
 ## Contents
 
+- [Why MCPBrowser over Puppeteer/Playwright MCP servers?](#why-mcpbrowser-over-puppeteerplaywright-mcp-servers)
 - [Requirements](#requirements)
 - [Installation](#installation)
   - [VS Code Extension](#option-1-vs-code-extension)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.46",
+  "version": "0.3.48",
   "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/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
     };
   }
 
@@ -78,7 +86,8 @@ export const FETCH_WEBPAGE_TOOL = {
       },
       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." },
-      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 }
+      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
@@ -88,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" },
@@ -123,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, selector = null, 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
@@ -151,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, selector, postLoadWait });
+    return await doFetchPage({ url, browser, removeUnnecessaryHTML, selector, postLoadWait, detectForms });
   });
 }
 
@@ -159,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, selector, postLoadWait }) {
+async function doFetchPage({ url, browser, removeUnnecessaryHTML, selector, postLoadWait, detectForms }) {
   const originalHostname = new URL(url).hostname;
 
   // Ensure browser connection
@@ -218,6 +230,16 @@ async function doFetchPage({ url, browser, removeUnnecessaryHTML, selector, post
     // Extract and process HTML
     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()}`);
     
     // Check for non-2xx HTTP status codes
@@ -237,7 +259,8 @@ async function doFetchPage({ url, browser, removeUnnecessaryHTML, selector, post
         "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
     };
   }
 
@@ -70,7 +78,8 @@ export const GET_CURRENT_HTML_TOOL = {
     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 },
-      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." }
+      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
@@ -80,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" },
@@ -108,7 +120,7 @@ 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, selector = null }) {
+export async function getCurrentHtml({ url, removeUnnecessaryHTML = true, selector = null, detectForms = false }) {
   const startTime = Date.now();
   logger.info(`browser_get_current_html called: url=${url}${selector ? ` selector=${selector}` : ''}`);
   
@@ -161,6 +173,16 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true, select
     const currentUrl = page.url();
     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)`);
@@ -188,7 +210,8 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true, select
         "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/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,