mcpbrowser 0.3.57 → 0.3.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.57",
+  "version": "0.3.59",
   "mcpName": "io.github.cherchyk/mcpbrowser",
   "type": "module",
   "description": "MCP browser server — loads and interacts with web pages using the user's Chromium-based browser with full JavaScript execution. Handles authentication, SSO, and anti-bot protection automatically via the user's existing browser session.",

package/src/actions/click-element.js

@@ -25,11 +25,12 @@
  */
 
 import { getBrowser, getValidatedPage } from '../core/browser.js';
-import { extractAndProcessHtml, waitForPageReady } from '../core/page.js';
+import { extractAndProcessHtml, waitForPageReady, getLargeHtmlHints } 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';
+import { scanScrollableAreas } from './scroll-page.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -39,7 +40,7 @@ import { scanPageForms } from './detect-forms.js';
  * 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 = [], formData = null }) {
+  constructor({ status, fallbackUsed = false, nativeAttempt, fallbackAttempt, postClickWait, currentUrl, html = null, message, nextSteps = [], recommendedPlugins = [], formData = null, scrollableAreas = [] }) {
     super(nextSteps);
     this.status = status;
     this.fallbackUsed = fallbackUsed;
@@ -53,6 +54,7 @@ export class ClickWithFallbackResponse extends MCPResponse {
     this.forms = formData?.forms || [];
     this.orphanedFields = formData?.orphanedFields || [];
     this.totalFieldCount = formData?.totalFieldCount || 0;
+    this.scrollableAreas = scrollableAreas;
   }
 
   _getAdditionalFields() {
@@ -68,7 +70,8 @@ export class ClickWithFallbackResponse extends MCPResponse {
       recommendedPlugins: this.recommendedPlugins,
       forms: this.forms,
       orphanedFields: this.orphanedFields,
-      totalFieldCount: this.totalFieldCount
+      totalFieldCount: this.totalFieldCount,
+      scrollableAreas: this.scrollableAreas
     };
   }
 
@@ -99,6 +102,7 @@ export const CLICK_ELEMENT_TOOL = {
       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 },
+      htmlSelector: { type: "string", description: "CSS selector to extract a specific DOM subtree from the post-click page instead of the full page. Use on heavy SPAs (e.g., ADO, Jira) to reduce response size. Only used when returnHtml is true. Example: '.activity-feed', '[role=\"main\"]'." },
       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"],
@@ -114,16 +118,16 @@ export const CLICK_ELEMENT_TOOL = {
         properties: {
           status: { type: "string", enum: ["success", "timeout", "error"] },
           durationMs: { type: "number" },
-          error: { type: ["string", "null"] }
+          error: { type: "string" }
         },
         required: ["status", "durationMs"]
       },
       fallbackAttempt: {
-        type: ["object", "null"],
+        type: "object",
         properties: {
           status: { type: "string", enum: ["success", "timeout", "error"] },
           durationMs: { type: "number" },
-          error: { type: ["string", "null"] }
+          error: { type: "string" }
         },
         required: ["status", "durationMs"],
         description: "Present when fallbackUsed is true"
@@ -140,7 +144,7 @@ export const CLICK_ELEMENT_TOOL = {
       currentUrl: { type: "string", description: "URL after click" },
       message: { type: "string", description: "Status message" },
       html: { 
-        type: ["string", "null"], 
+        type: "string", 
         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)" },
@@ -155,6 +159,21 @@ export const CLICK_ELEMENT_TOOL = {
         type: "array",
         items: { type: "object" },
         description: "Detected site-specific plugins available for this domain"
+      },
+      scrollableAreas: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            selector: { type: "string" },
+            scrollHeight: { type: "number" },
+            clientHeight: { type: "number" },
+            scrollTop: { type: "number" },
+            hiddenPixels: { type: "number" },
+            description: { type: "string" }
+          }
+        },
+        description: "Scrollable containers on the page. Pass a selector to browser_scroll_page's 'container' parameter to scroll within a specific area."
       }
     },
     required: ["status", "fallbackUsed", "nativeAttempt", "currentUrl", "message", "html", "nextSteps"],
@@ -199,7 +218,7 @@ export const CLICK_ELEMENT_TOOL = {
  *   returnHtml: false 
  * });
  */
-export async function clickElement({ url, selector, text, waitForElementTimeout = 30000, returnHtml = true, removeUnnecessaryHTML = true, postClickWait = 1000, detectForms = false }) {
+export async function clickElement({ url, selector, text, waitForElementTimeout = 30000, returnHtml = true, removeUnnecessaryHTML = true, htmlSelector = null, postClickWait = 1000, detectForms = false }) {
   logger.info(`browser_click_element called: ${selector || `text="${text}"`}`);
   
   if (!url) {
@@ -290,7 +309,7 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
         'The element could not be located on the page. It may be hidden, dynamically loaded, or the selector/text may be incorrect.',
         [
           "Use MCPBrowser's browser_get_current_html to verify page content",
-          "Use MCPBrowser's browser_take_screenshot to see the visual layout if HTML is unclear",
+          "Use MCPBrowser's browser_take_screenshot with fullPage=true to see the full visual layout if HTML is unclear",
           "Try a different selector or text",
           "Check if the element is visible on the page"
         ]
@@ -344,7 +363,7 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
     }
 
     const currentUrl = page.url();
-    const html = finalStatus === 'success' && returnHtml ? await extractAndProcessHtml(page, removeUnnecessaryHTML) : null;
+    const html = finalStatus === 'success' && returnHtml ? await extractAndProcessHtml(page, removeUnnecessaryHTML, htmlSelector) : null;
 
     // Scan for forms when requested and returning HTML (lightweight, ~50-100ms)
     let formData = null;
@@ -356,6 +375,16 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       }
     }
 
+    // Scan for scrollable areas when returning HTML (lightweight, ~20-50ms)
+    let scrollableAreas = [];
+    if (finalStatus === 'success' && returnHtml) {
+      try {
+        scrollableAreas = await scanScrollableAreas(page);
+      } catch (err) {
+        logger.debug(`Scrollable area scan failed (non-fatal): ${err.message}`);
+      }
+    }
+
     const baseMessage = selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`;
     const message = finalStatus === 'success'
       ? baseMessage
@@ -365,16 +394,17 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
 
     const nextSteps = returnHtml
       ? [
+          ...(html ? getLargeHtmlHints(html, htmlSelector) : []),
           ...(html ? getPluginNextSteps(currentUrl, html) : []),
           "Use MCPBrowser's browser_click_element again to navigate further",
           "Use MCPBrowser's browser_type_text to fill forms if needed",
           "Use MCPBrowser's browser_get_current_html to refresh page state",
-          "Use MCPBrowser's browser_take_screenshot if page has popups or visual content that's hard to parse from HTML",
+          "Use MCPBrowser's browser_take_screenshot with fullPage=true if page has popups or visual content that's hard to parse from HTML",
           "Use MCPBrowser's browser_close_tab when finished"
         ]
       : [
           "Use MCPBrowser's browser_get_current_html to see updated page state",
-          "Use MCPBrowser's browser_take_screenshot if the page has popups, modals, or visual content",
+          "Use MCPBrowser's browser_take_screenshot with fullPage=true if the page has popups, modals, or visual content",
           "Use MCPBrowser's browser_click_element or MCPBrowser's browser_type_text for more interactions",
           "Use MCPBrowser's browser_close_tab when finished"
         ];
@@ -392,7 +422,8 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       message,
       nextSteps,
       recommendedPlugins: html ? getRecommendedPlugins(currentUrl, html) : [],
-      formData
+      formData,
+      scrollableAreas
     });
   } catch (err) {
     logger.error(`browser_click_element failed: ${err.message}`);
@@ -401,7 +432,7 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       'The element was found but could not be clicked. It may be covered by another element, not interactable, or the page may have changed.',
       [
         "Use MCPBrowser's browser_get_current_html to check current page state",
-        "Use MCPBrowser's browser_take_screenshot to see what's visually blocking the element",
+        "Use MCPBrowser's browser_take_screenshot with fullPage=true to see what's visually blocking the element",
         "Verify the selector or text is correct",
         "Try MCPBrowser's browser_fetch_webpage to reload if page is stale"
       ]

package/src/actions/detect-forms.js

@@ -123,7 +123,7 @@ export const DETECT_FORMS_TOOL = {
               }
             },
             submitButton: {
-              type: ["object", "null"],
+              type: "object",
               properties: {
                 selector: { type: "string" },
                 text: { type: "string" },
@@ -502,7 +502,7 @@ function buildNextSteps(forms, orphanedFields) {
     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_take_screenshot with fullPage=true 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

@@ -36,8 +36,13 @@ export class ExecuteJavascriptResponse extends MCPResponse {
   }
 
   _getAdditionalFields() {
+    // outputSchema declares result as type: 'string' (serialized).
+    // Ensure non-string values (numbers, objects, arrays) are stringified.
+    const serializedResult = this.result == null ? null
+      : typeof this.result === 'string' ? this.result
+      : JSON.stringify(this.result);
     return {
-      result: this.result,
+      result: serializedResult,
       type: this.type,
       executionTimeMs: this.executionTimeMs,
       truncated: this.truncated,
@@ -74,14 +79,14 @@ export const EXECUTE_JAVASCRIPT_TOOL = {
   outputSchema: {
     type: 'object',
     properties: {
-      result: { description: 'Serialized result of the script', nullable: true },
+      result: { type: 'string', description: 'Serialized result of the script', nullable: true },
       type: { type: 'string', description: 'Type of the returned result' },
       executionTimeMs: { type: 'number', description: 'Script execution duration' },
       truncated: { type: 'boolean', description: 'True if result was capped to size limit' },
       urlChanged: { type: 'boolean', description: 'True if page URL changed during execution' },
       currentUrl: { type: 'string', description: 'URL after execution' },
       nextSteps: { type: 'array', items: { type: 'string' } },
-      error: { type: ['object', 'null'], description: 'Error object when script throws or times out' },
+      error: { type: 'object', description: 'Error object when script throws or times out' },
       recommendedPlugins: {
         type: 'array',
         items: { type: 'object' },
@@ -109,11 +114,14 @@ function buildErrorResponse(message, reason, nextSteps) {
   return new InformationalResponse(message, reason, nextSteps);
 }
 
+const VALID_RETURN_TYPES = new Set(['json', 'text', 'void']);
+
 export async function executeJavascript({ url, script, timeoutMs = EXECUTION_TIMEOUT_DEFAULT_MS, returnType = 'json' }) {
   logger.info(`browser_execute_javascript called: ${url}`);
 
   if (!url) throw new Error('url parameter is required');
   if (!script || typeof script !== 'string' || !script.trim()) throw new Error('script parameter is required');
+  if (!VALID_RETURN_TYPES.has(returnType)) throw new Error(`Invalid returnType: '${returnType}'. Must be one of: json, text, void`);
 
   let hostname;
   try {
@@ -154,7 +162,15 @@ export async function executeJavascript({ url, script, timeoutMs = EXECUTION_TIM
   }
 
   const effectiveTimeout = clampTimeout(timeoutMs);
-  const beforeUrl = page.url();
+
+  // Capture beforeUrl via evaluate for consistency with post-exec currentUrl check
+  let beforeUrl;
+  try {
+    beforeUrl = await page.evaluate(() => location.href);
+  } catch {
+    beforeUrl = page.url();
+  }
+
   const start = Date.now();
 
   const evalPromise = page.evaluate(async ({ userScript, mode }) => {
@@ -183,14 +199,17 @@ export async function executeJavascript({ url, script, timeoutMs = EXECUTION_TIM
   }, { userScript: script, mode: returnType });
 
   let evalResult;
+  let timeoutTimer;
   try {
     evalResult = await Promise.race([
       evalPromise,
-      new Promise((_, reject) => setTimeout(() => reject(new Error(`Execution timed out after ${effectiveTimeout}ms`)), effectiveTimeout))
+      new Promise((_, reject) => {
+        timeoutTimer = setTimeout(() => reject(new Error(`Execution timed out after ${effectiveTimeout}ms`)), effectiveTimeout);
+      })
     ]);
   } catch (err) {
     const executionTimeMs = Date.now() - start;
-    let currentUrl = page.url();
+    let currentUrl = beforeUrl;
     try {
       currentUrl = await page.evaluate(() => location.href);
     } catch {
@@ -205,21 +224,23 @@ export async function executeJavascript({ url, script, timeoutMs = EXECUTION_TIM
       currentUrl,
       error: { name: 'TimeoutError', message: err.message }
     });
+  } finally {
+    clearTimeout(timeoutTimer);
   }
 
   const executionTimeMs = Date.now() - start;
-  let currentUrl = page.url();
+  let currentUrl = beforeUrl;
   try {
     currentUrl = await page.evaluate(() => location.href);
   } catch {
-    // If we can't read location (e.g., cross-origin), fall back to page.url()
+    // If we can't read location (e.g., cross-origin), fall back to beforeUrl
   }
   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) {
+  // Our inner wrapper always returns { value, type } or { error }, never undefined.
+  if (evalResult === undefined) {
     return new ExecuteJavascriptResponse({
       result: null,
       type: 'undefined',

package/src/actions/fetch-page.js

@@ -4,12 +4,13 @@
  */
 
 import { getBrowser, domainPages } from '../core/browser.js';
-import { getOrCreatePage, queueRequest, navigateToUrl, waitForPageReady, extractAndProcessHtml } from '../core/page.js';
+import { getOrCreatePage, queueRequest, navigateToUrl, waitForPageReady, extractAndProcessHtml, getLargeHtmlHints } from '../core/page.js';
 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';
+import { scanScrollableAreas } from './scroll-page.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -30,7 +31,7 @@ export class FetchPageSuccessResponse extends MCPResponse {
    * @param {Array} [recommendedPlugins] - Detected plugin metadata
    * @param {Object} [formData] - Detected forms data
    */
-  constructor(currentUrl, html, nextSteps, recommendedPlugins = [], formData = null) {
+  constructor(currentUrl, html, nextSteps, recommendedPlugins = [], formData = null, scrollableAreas = []) {
     super(nextSteps);
     
     if (typeof currentUrl !== 'string') {
@@ -46,6 +47,7 @@ export class FetchPageSuccessResponse extends MCPResponse {
     this.forms = formData?.forms || [];
     this.orphanedFields = formData?.orphanedFields || [];
     this.totalFieldCount = formData?.totalFieldCount || 0;
+    this.scrollableAreas = scrollableAreas;
   }
 
   _getAdditionalFields() {
@@ -55,7 +57,8 @@ export class FetchPageSuccessResponse extends MCPResponse {
       recommendedPlugins: this.recommendedPlugins,
       forms: this.forms,
       orphanedFields: this.orphanedFields,
-      totalFieldCount: this.totalFieldCount
+      totalFieldCount: this.totalFieldCount,
+      scrollableAreas: this.scrollableAreas
     };
   }
 
@@ -81,8 +84,9 @@ export const FETCH_WEBPAGE_TOOL = {
       url: { type: "string", description: "The URL to fetch" },
       browser: { 
         type: "string", 
-        description: "Browser to use: 'chrome' or 'edge'. Leave empty for auto-detection. Uses CDP to connect to the user's existing browser session.",
-        enum: ["", "chrome", "edge"]
+        enum: ["chrome", "edge", "brave"],
+        description: "Browser to use. Uses CDP to connect to the user's existing browser session.",
+        default: "chrome"
       },
       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." },
@@ -109,6 +113,21 @@ export const FETCH_WEBPAGE_TOOL = {
         type: "array",
         items: { type: "object" },
         description: "Detected site-specific plugins available for this domain"
+      },
+      scrollableAreas: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            selector: { type: "string" },
+            scrollHeight: { type: "number" },
+            clientHeight: { type: "number" },
+            scrollTop: { type: "number" },
+            hiddenPixels: { type: "number" },
+            description: { type: "string" }
+          }
+        },
+        description: "Scrollable containers on the page. Pass a selector to browser_scroll_page's 'container' parameter to scroll within a specific area."
       }
     },
     required: ["currentUrl", "html", "nextSteps"],
@@ -246,6 +265,14 @@ async function doFetchPage({ url, browser, removeUnnecessaryHTML, selector, post
         logger.debug(`Form scan failed (non-fatal): ${err.message}`);
       }
     }
+
+    // Scan for scrollable areas (lightweight, ~20-50ms)
+    let scrollableAreas = [];
+    try {
+      scrollableAreas = await scanScrollableAreas(page);
+    } catch (err) {
+      logger.debug(`Scrollable area scan failed (non-fatal): ${err.message}`);
+    }
     
     logger.info(`browser_fetch_webpage completed: ${page.url()}`);
     
@@ -259,15 +286,17 @@ async function doFetchPage({ url, browser, removeUnnecessaryHTML, selector, post
       page.url(),
       processedHtml,
       [
+        ...getLargeHtmlHints(processedHtml, selector),
         ...getPluginNextSteps(page.url(), processedHtml),
         "Use MCPBrowser's browser_click_element to interact with buttons/links on the page",
         "Use MCPBrowser's browser_type_text to fill in form fields",
         "Use MCPBrowser's browser_get_current_html to re-check page state after interactions",
-        "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_take_screenshot with fullPage=true to capture the entire page visually (charts, images, complex layouts)",
         "Use MCPBrowser's browser_close_tab when finished to free browser resources"
       ],
       getRecommendedPlugins(page.url(), processedHtml),
-      formData
+      formData,
+      scrollableAreas
     );
   } catch (err) {
     logger.error(`browser_fetch_webpage failed: ${err.message || String(err)}`);

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

@@ -3,11 +3,12 @@
  */
 
 import { getBrowser, getValidatedPage } from '../core/browser.js';
-import { extractAndProcessHtml } from '../core/page.js';
+import { extractAndProcessHtml, getLargeHtmlHints } 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';
+import { scanScrollableAreas } from './scroll-page.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -28,7 +29,7 @@ export class GetCurrentHtmlSuccessResponse extends MCPResponse {
    * @param {Array} [recommendedPlugins] - Detected plugin metadata
    * @param {Object} [formData] - Detected forms data
    */
-  constructor(currentUrl, html, nextSteps, recommendedPlugins = [], formData = null) {
+  constructor(currentUrl, html, nextSteps, recommendedPlugins = [], formData = null, scrollableAreas = []) {
     super(nextSteps);
     
     if (typeof currentUrl !== 'string') {
@@ -44,6 +45,7 @@ export class GetCurrentHtmlSuccessResponse extends MCPResponse {
     this.forms = formData?.forms || [];
     this.orphanedFields = formData?.orphanedFields || [];
     this.totalFieldCount = formData?.totalFieldCount || 0;
+    this.scrollableAreas = scrollableAreas;
   }
 
   _getAdditionalFields() {
@@ -53,7 +55,8 @@ export class GetCurrentHtmlSuccessResponse extends MCPResponse {
       recommendedPlugins: this.recommendedPlugins,
       forms: this.forms,
       orphanedFields: this.orphanedFields,
-      totalFieldCount: this.totalFieldCount
+      totalFieldCount: this.totalFieldCount,
+      scrollableAreas: this.scrollableAreas
     };
   }
 
@@ -101,6 +104,21 @@ export const GET_CURRENT_HTML_TOOL = {
         type: "array",
         items: { type: "object" },
         description: "Detected site-specific plugins available for this domain"
+      },
+      scrollableAreas: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            selector: { type: "string" },
+            scrollHeight: { type: "number" },
+            clientHeight: { type: "number" },
+            scrollTop: { type: "number" },
+            hiddenPixels: { type: "number" },
+            description: { type: "string" }
+          }
+        },
+        description: "Scrollable containers on the page. Pass a selector to browser_scroll_page's 'container' parameter to scroll within a specific area."
       }
     },
     required: ["currentUrl", "html", "nextSteps"],
@@ -189,6 +207,14 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true, select
         logger.debug(`Form scan failed (non-fatal): ${err.message}`);
       }
     }
+
+    // Scan for scrollable areas (lightweight, ~20-50ms)
+    let scrollableAreas = [];
+    try {
+      scrollableAreas = await scanScrollableAreas(page);
+    } catch (err) {
+      logger.debug(`Scrollable area scan failed (non-fatal): ${err.message}`);
+    }
     
     // Detect empty/near-empty HTML extraction (e.g., CSP blocking page.evaluate)
     if (!html || html.trim().length < 100) {
@@ -197,7 +223,7 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true, select
         `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_take_screenshot with fullPage=true 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"
@@ -211,14 +237,16 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true, select
       currentUrl,
       html,
       [
+        ...getLargeHtmlHints(html, selector),
         ...getPluginNextSteps(currentUrl, html),
         "Use MCPBrowser's browser_click_element to interact with elements",
         "Use MCPBrowser's browser_type_text to fill forms",
-        "Use MCPBrowser's browser_take_screenshot if page layout or visual content is hard to understand from HTML",
+        "Use MCPBrowser's browser_take_screenshot with fullPage=true 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),
-      formData
+      formData,
+      scrollableAreas
     );
   } catch (err) {
     logger.error(`browser_get_current_html failed: ${err.message}`);

package/src/actions/navigate-history.js

@@ -94,7 +94,7 @@ export const NAVIGATE_HISTORY_TOOL = {
       direction: { type: "string", enum: ["back", "forward"], description: "Navigation direction used" },
       previousUrl: { type: "string", description: "URL before navigation" },
       currentUrl: { type: "string", description: "URL after navigation" },
-      html: { type: ["string", "null"], description: "Page HTML content after navigation (null if returnHtml=false)" },
+      html: { type: "string", description: "Page HTML content after navigation (null if returnHtml=false)" },
       nextSteps: {
         type: "array",
         items: { type: "string" },

package/src/actions/scroll-page.js

@@ -1,6 +1,7 @@
 /**
  * scroll-page.js - Scroll within browser page
- * Scrolls the page in various ways for visibility and screenshot capture
+ * Scrolls the page in various ways for visibility and screenshot capture.
+ * Automatically detects scrollable containers inside SPAs.
  */
 
 import { getBrowser, getValidatedPage } from '../core/browser.js';
@@ -11,6 +12,139 @@ import logger from '../core/logger.js';
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
  */
 
+// ============================================================================
+// SCROLLABLE AREA SCANNER (exported for reuse by fetch-page, click-element, etc.)
+// ============================================================================
+
+/**
+ * Scan a page for scrollable containers and return structured data.
+ * Lightweight (~20-50ms) — safe to call on every page load.
+ *
+ * Returns an array of scrollable areas sorted by visible area (largest first).
+ * Each entry has a CSS selector the agent can pass to browser_scroll_page's
+ * `container` parameter to target that specific area.
+ *
+ * @param {Object} page - Puppeteer page object
+ * @returns {Promise<Array<{selector: string, scrollHeight: number, clientHeight: number, scrollTop: number, hiddenPixels: number, description: string}>>}
+ */
+export async function scanScrollableAreas(page) {
+  return await page.evaluate(() => {
+    const results = [];
+    const minScrollable = 200; // ignore tiny scroll areas (dropdowns, etc.)
+
+    // Check if the window/document itself scrolls
+    const docEl = document.documentElement;
+    const body = document.body;
+    const windowScrollH = Math.max(docEl.scrollHeight, body.scrollHeight);
+    const windowClientH = docEl.clientHeight;
+    const htmlOverflow = getComputedStyle(docEl).overflowY;
+    const bodyOverflow = getComputedStyle(body).overflowY;
+    const windowBlocked = (htmlOverflow === 'hidden' && bodyOverflow === 'hidden');
+
+    if (!windowBlocked && windowScrollH > windowClientH + minScrollable) {
+      results.push({
+        selector: 'window',
+        scrollHeight: windowScrollH,
+        clientHeight: windowClientH,
+        scrollTop: window.scrollY,
+        hiddenPixels: windowScrollH - windowClientH - window.scrollY,
+        description: 'Main page (window scroll)'
+      });
+    }
+
+    // Scan for inner scrollable containers
+    // Check common SPA wrappers + anything with overflow: auto/scroll
+    const seen = new WeakSet();
+    const candidates = document.querySelectorAll(
+      'body > *, body > * > *, [class*="scroll"], [role="main"], [role="region"], ' +
+      '#root > *, #app > *, #__next > *, [class*="content"], [class*="container"], ' +
+      '[class*="panel"], [class*="feed"], [class*="list"], [data-is-scrollable]'
+    );
+
+    for (const el of candidates) {
+      if (seen.has(el)) continue;
+      seen.add(el);
+
+      const overflow = el.scrollHeight - el.clientHeight;
+      if (overflow < minScrollable) continue;
+
+      const style = getComputedStyle(el);
+      if (style.overflowY === 'hidden' || style.overflowY === 'visible') continue;
+      // auto, scroll, overlay are all scrollable
+
+      // Skip elements that are too small to be meaningful content areas
+      if (el.clientWidth < 100 || el.clientHeight < 100) continue;
+
+      // Build a stable selector
+      let selector;
+      if (el.id) {
+        selector = '#' + CSS.escape(el.id);
+      } else if (el.getAttribute('role')) {
+        const role = el.getAttribute('role');
+        const roleEls = document.querySelectorAll(`[role="${role}"]`);
+        if (roleEls.length === 1) {
+          selector = `[role="${role}"]`;
+        }
+      }
+      if (!selector) {
+        // Try class-based selector
+        const classes = Array.from(el.classList).filter(c =>
+          c.includes('scroll') || c.includes('content') || c.includes('main') ||
+          c.includes('panel') || c.includes('feed') || c.includes('list') ||
+          c.includes('container') || c.includes('body') || c.includes('region')
+        );
+        if (classes.length > 0) {
+          const candidate = '.' + CSS.escape(classes[0]);
+          if (document.querySelectorAll(candidate).length === 1) {
+            selector = candidate;
+          }
+        }
+      }
+      if (!selector) {
+        // Use nth-child path as last resort
+        const tag = el.tagName.toLowerCase();
+        const parent = el.parentElement;
+        if (parent) {
+          const siblings = Array.from(parent.children).filter(s => s.tagName === el.tagName);
+          const idx = siblings.indexOf(el) + 1;
+          const parentSel = parent.id ? '#' + CSS.escape(parent.id) : parent.tagName.toLowerCase();
+          selector = `${parentSel} > ${tag}:nth-of-type(${idx})`;
+        } else {
+          selector = tag;
+        }
+      }
+
+      // Build a human-readable description from ARIA, class, or tag
+      let description = el.getAttribute('aria-label') || '';
+      if (!description) {
+        const meaningful = Array.from(el.classList).filter(c =>
+          !c.match(/^(bolt-|flex|ms-|css-|_|sc-)/i)
+        ).slice(0, 2).join(' ');
+        description = meaningful || el.tagName.toLowerCase();
+      }
+
+      results.push({
+        selector,
+        scrollHeight: el.scrollHeight,
+        clientHeight: el.clientHeight,
+        scrollTop: el.scrollTop,
+        hiddenPixels: el.scrollHeight - el.clientHeight - el.scrollTop,
+        description
+      });
+    }
+
+    // Sort by visible area (largest containers first) and deduplicate nested
+    results.sort((a, b) => {
+      if (a.selector === 'window') return -1;
+      if (b.selector === 'window') return 1;
+      return (b.clientHeight * 100 + b.scrollHeight) - (a.clientHeight * 100 + a.scrollHeight);
+    });
+
+    // Cap at 5 most significant scrollable areas
+    return results.slice(0, 5);
+  });
+}
+
 // ============================================================================
 // RESPONSE CLASS
 // ============================================================================
@@ -29,8 +163,9 @@ export class ScrollPageSuccessResponse extends MCPResponse {
    * @param {number} viewportWidth - Viewport width
    * @param {number} viewportHeight - Viewport height
    * @param {string[]} nextSteps - Suggested next actions
+   * @param {Array} [scrollableAreas] - Detected scrollable containers
    */
-  constructor(currentUrl, scrollX, scrollY, pageWidth, pageHeight, viewportWidth, viewportHeight, nextSteps) {
+  constructor(currentUrl, scrollX, scrollY, pageWidth, pageHeight, viewportWidth, viewportHeight, nextSteps, scrollableAreas = []) {
     super(nextSteps);
     
     if (typeof currentUrl !== 'string') {
@@ -62,6 +197,7 @@ export class ScrollPageSuccessResponse extends MCPResponse {
     this.pageHeight = pageHeight;
     this.viewportWidth = viewportWidth;
     this.viewportHeight = viewportHeight;
+    this.scrollableAreas = scrollableAreas;
   }
 
   _getAdditionalFields() {
@@ -72,7 +208,8 @@ export class ScrollPageSuccessResponse extends MCPResponse {
       pageWidth: this.pageWidth,
       pageHeight: this.pageHeight,
       viewportWidth: this.viewportWidth,
-      viewportHeight: this.viewportHeight
+      viewportHeight: this.viewportHeight,
+      scrollableAreas: this.scrollableAreas
     };
   }
 
@@ -94,7 +231,7 @@ export class ScrollPageSuccessResponse extends MCPResponse {
 export const SCROLL_PAGE_TOOL = {
   name: "browser_scroll_page",
   title: "Scroll Page",
-  description: "Scroll within a browser-loaded page. Use when: you need to see more content below the fold, bring an element into view before clicking, scroll to a specific section, or navigate long pages. Supports scroll by direction, to a CSS selector, or to absolute coordinates. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
+  description: "Scroll within a browser-loaded page. Automatically detects scrollable containers inside SPAs (e.g., ADO, Jira, Gmail) where the main content scrolls inside an inner div rather than the window. Use when: you need to see more content below the fold, bring an element into view before clicking, scroll to a specific section, or navigate long pages. Supports scroll by direction, to a CSS selector, or to absolute coordinates. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
   inputSchema: {
     type: "object",
     properties: {
@@ -105,7 +242,8 @@ export const SCROLL_PAGE_TOOL = {
       direction: { 
         type: "string", 
         enum: ["up", "down", "left", "right"],
-        description: "Direction to scroll. Use with 'amount' parameter." 
+        description: "Direction to scroll. Use with 'amount' parameter.",
+        default: "down"
       },
       amount: { 
         type: "number", 
@@ -123,6 +261,10 @@ export const SCROLL_PAGE_TOOL = {
       y: { 
         type: "number", 
         description: "Absolute vertical scroll position. Use with 'x' for precise positioning." 
+      },
+      container: {
+        type: "string",
+        description: "CSS selector of a specific scrollable container to scroll within. Use when the page has multiple scroll areas (e.g., a sidebar + main content). Get available selectors from the scrollableAreas field in fetch/get_current_html/click responses. If omitted, auto-detects the primary scrollable container."
       }
     },
     required: ["url"],
@@ -138,6 +280,21 @@ export const SCROLL_PAGE_TOOL = {
       pageHeight: { type: "number", description: "Total scrollable page height" },
       viewportWidth: { type: "number", description: "Visible viewport width" },
       viewportHeight: { type: "number", description: "Visible viewport height" },
+      scrollableAreas: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            selector: { type: "string", description: "CSS selector to target this container (or 'window' for main page)" },
+            scrollHeight: { type: "number", description: "Total scrollable height in pixels" },
+            clientHeight: { type: "number", description: "Visible height in pixels" },
+            scrollTop: { type: "number", description: "Current scroll position" },
+            hiddenPixels: { type: "number", description: "Pixels of content below current scroll position" },
+            description: { type: "string", description: "Human-readable description of the container" }
+          }
+        },
+        description: "Scrollable containers detected on the page. Pass a selector to the 'container' parameter to scroll within a specific area."
+      },
       nextSteps: { 
         type: "array", 
         items: { type: "string" },
@@ -162,7 +319,9 @@ export const SCROLL_PAGE_TOOL = {
 
 /**
  * Scroll within an already-loaded page
- * Supports directional scrolling, scroll-to-element, and absolute positioning
+ * Supports directional scrolling, scroll-to-element, and absolute positioning.
+ * Automatically detects scrollable containers in SPAs, or accepts an explicit
+ * container selector from the agent.
  * @param {Object} params - Parameters
  * @param {string} params.url - The URL of the page to scroll
  * @param {string} [params.direction] - Direction to scroll: 'up', 'down', 'left', 'right'
@@ -170,10 +329,11 @@ export const SCROLL_PAGE_TOOL = {
  * @param {string} [params.selector] - CSS selector to scroll into view
  * @param {number} [params.x] - Absolute x scroll position
  * @param {number} [params.y] - Absolute y scroll position
+ * @param {string} [params.container] - CSS selector of scrollable container to scroll within
  * @returns {Promise<Object>} Result object with scroll position data
  */
-export async function scrollPage({ url, direction, amount = 500, selector, x, y }) {
-  logger.info(`browser_scroll_page called: url=${url}, direction=${direction}, amount=${amount}, selector=${selector}, x=${x}, y=${y}`);
+export async function scrollPage({ url, direction, amount = 500, selector, x, y, container }) {
+  logger.info(`browser_scroll_page called: url=${url}, direction=${direction}, amount=${amount}, selector=${selector}, x=${x}, y=${y}${container ? `, container=${container}` : ''}`);
   
   if (!url) {
     throw new Error("url parameter is required");
@@ -222,6 +382,38 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
 
   try {
     const currentUrl = page.url();
+
+    // Scan all scrollable areas on the page (lightweight, ~20-50ms)
+    const scrollableAreas = await scanScrollableAreas(page);
+    logger.debug(`browser_scroll_page: found ${scrollableAreas.length} scrollable area(s)`);
+
+    // Resolve which container to target:
+    // 1. Explicit container param from agent
+    // 2. Auto-detect: largest non-window scrollable area (if window is blocked)
+    // 3. Fallback: window
+    let containerInfo; // { isWindow: boolean, selector?: string }
+    if (container) {
+      // Agent explicitly specified a container
+      if (container === 'window') {
+        containerInfo = { isWindow: true };
+      } else {
+        containerInfo = { isWindow: false, selector: container };
+      }
+      logger.debug(`browser_scroll_page: using explicit container=${container}`);
+    } else {
+      // Auto-detect: check if window scrolls; if not, pick the largest inner container
+      const windowArea = scrollableAreas.find(a => a.selector === 'window');
+      const innerAreas = scrollableAreas.filter(a => a.selector !== 'window');
+
+      if (windowArea && windowArea.hiddenPixels > 0) {
+        containerInfo = { isWindow: true };
+      } else if (innerAreas.length > 0) {
+        containerInfo = { isWindow: false, selector: innerAreas[0].selector };
+      } else {
+        containerInfo = { isWindow: true };
+      }
+      logger.debug(`browser_scroll_page: auto-detected container=${containerInfo.isWindow ? 'window' : containerInfo.selector}`);
+    }
     
     // Determine scroll mode and execute
     if (selector) {
@@ -249,15 +441,24 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
       }, selector);
       
     } else if (typeof x === 'number' && typeof y === 'number') {
-      // Absolute position mode
+      // Absolute position mode — target the resolved container
       logger.debug(`browser_scroll_page: Scrolling to absolute position: (${x}, ${y})`);
       
-      await page.evaluate(({ scrollX, scrollY }) => {
-        window.scrollTo(scrollX, scrollY);
-      }, { scrollX: x, scrollY: y });
+      await page.evaluate(({ scrollX, scrollY, ctr }) => {
+        if (ctr.isWindow) {
+          window.scrollTo(scrollX, scrollY);
+        } else {
+          const el = document.querySelector(ctr.selector);
+          if (el) {
+            el.scrollTo(scrollX, scrollY);
+          } else {
+            window.scrollTo(scrollX, scrollY);
+          }
+        }
+      }, { scrollX: x, scrollY: y, ctr: containerInfo });
       
     } else if (direction) {
-      // Directional scroll mode
+      // Directional scroll mode — target the resolved container
       logger.debug(`browser_scroll_page: Scrolling ${direction} by ${amount}px`);
       
       const scrollDeltas = {
@@ -272,9 +473,18 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
         throw new Error(`Invalid direction: ${direction}. Must be one of: up, down, left, right`);
       }
       
-      await page.evaluate(({ dx, dy }) => {
-        window.scrollBy(dx, dy);
-      }, { dx: delta.x, dy: delta.y });
+      await page.evaluate(({ dx, dy, ctr }) => {
+        if (ctr.isWindow) {
+          window.scrollBy(dx, dy);
+        } else {
+          const el = document.querySelector(ctr.selector);
+          if (el) {
+            el.scrollBy(dx, dy);
+          } else {
+            window.scrollBy(dx, dy);
+          }
+        }
+      }, { dx: delta.x, dy: delta.y, ctr: containerInfo });
       
     } else {
       // No scroll parameters provided - just return current position
@@ -284,18 +494,48 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
     // Small delay to let scroll complete
     await new Promise(resolve => setTimeout(resolve, 100));
     
-    // Get final scroll position and page dimensions
-    const scrollInfo = await page.evaluate(() => ({
-      scrollX: window.scrollX,
-      scrollY: window.scrollY,
-      pageWidth: document.documentElement.scrollWidth,
-      pageHeight: document.documentElement.scrollHeight,
-      viewportWidth: window.innerWidth,
-      viewportHeight: window.innerHeight
-    }));
+    // Re-scan scrollable areas to get updated positions after scroll
+    const updatedAreas = await scanScrollableAreas(page);
+
+    // Get final scroll position from the targeted container
+    const scrollInfo = await page.evaluate((ctr) => {
+      if (ctr.isWindow) {
+        return {
+          scrollX: window.scrollX,
+          scrollY: window.scrollY,
+          pageWidth: document.documentElement.scrollWidth,
+          pageHeight: document.documentElement.scrollHeight,
+          viewportWidth: window.innerWidth,
+          viewportHeight: window.innerHeight
+        };
+      }
+      const el = document.querySelector(ctr.selector);
+      if (el) {
+        return {
+          scrollX: el.scrollLeft,
+          scrollY: el.scrollTop,
+          pageWidth: el.scrollWidth,
+          pageHeight: el.scrollHeight,
+          viewportWidth: el.clientWidth,
+          viewportHeight: el.clientHeight
+        };
+      }
+      return {
+        scrollX: window.scrollX,
+        scrollY: window.scrollY,
+        pageWidth: document.documentElement.scrollWidth,
+        pageHeight: document.documentElement.scrollHeight,
+        viewportWidth: window.innerWidth,
+        viewportHeight: window.innerHeight
+      };
+    }, containerInfo);
     
-    logger.info(`browser_scroll_page completed: position=(${scrollInfo.scrollX}, ${scrollInfo.scrollY}), page=(${scrollInfo.pageWidth}x${scrollInfo.pageHeight})`);
+    logger.info(`browser_scroll_page completed: position=(${scrollInfo.scrollX}, ${scrollInfo.scrollY}), page=(${scrollInfo.pageWidth}x${scrollInfo.pageHeight})${containerInfo.isWindow ? '' : ` container=${containerInfo.selector}`}`);
     
+    const containerHint = containerInfo.isWindow
+      ? []
+      : [`Scrolled within inner container (${containerInfo.selector}). Use container="${containerInfo.selector}" to keep targeting it.`];
+
     return new ScrollPageSuccessResponse(
       currentUrl,
       scrollInfo.scrollX,
@@ -305,11 +545,13 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
       scrollInfo.viewportWidth,
       scrollInfo.viewportHeight,
       [
-        "Use MCPBrowser's browser_take_screenshot to capture the current view",
+        ...containerHint,
+        "Use MCPBrowser's browser_take_screenshot with fullPage=true to capture the entire page in one shot",
         "Use MCPBrowser's browser_scroll_page again to navigate further",
         "Use MCPBrowser's browser_click_element to interact with visible elements",
         "Use MCPBrowser's browser_get_current_html to get the page content"
-      ]
+      ],
+      updatedAreas
     );
   } catch (err) {
     logger.error(`browser_scroll_page failed: ${err.message}`);

package/src/actions/take-screenshot.js

@@ -89,12 +89,12 @@ export class TakeScreenshotSuccessResponse extends MCPResponse {
 export const TAKE_SCREENSHOT_TOOL = {
   name: "browser_take_screenshot",
   title: "Take Screenshot",
-  description: "Capture a screenshot of a browser-loaded page as PNG. Use when: you need to see what a page looks like, analyze visual layout, view charts/images/graphs, debug UI issues, or when HTML alone is insufficient to understand the page content. Returns base64-encoded PNG. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
+  description: "Capture a screenshot of a browser-loaded page as PNG. Set fullPage=true to capture the entire scrollable page in one shot — this avoids multiple scroll+screenshot cycles. Only use fullPage=false when you specifically need just the current viewport (rare). Use when: you need to see what a page looks like, analyze visual layout, view charts/images/graphs, debug UI issues, or when HTML alone is insufficient. Returns base64-encoded PNG. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
   inputSchema: {
     type: "object",
     properties: {
       url: { type: "string", description: "The URL of the page (must match a previously fetched page)" },
-      fullPage: { type: "boolean", description: "Capture the full scrollable page instead of just the viewport. Default: false (viewport only).", default: false }
+      fullPage: { type: "boolean", description: "RECOMMENDED: set to true to capture the entire scrollable page in one shot instead of just the viewport. Avoids multiple scroll+screenshot cycles. Automatically falls back to viewport if the page is extremely tall.", default: false }
     },
     required: ["url"],
     additionalProperties: false
@@ -135,6 +135,10 @@ export const TAKE_SCREENSHOT_TOOL = {
  * @param {boolean} [params.fullPage=false] - Whether to capture full scrollable page
  * @returns {Promise<Object>} Result object with screenshot data
  */
+
+/** Max page height (px) for safe full-page capture. Beyond this, fall back to viewport to avoid giant payloads. */
+const MAX_FULL_PAGE_HEIGHT = 12000;
+
 export async function takeScreenshot({ url, fullPage = false }) {
   logger.info(`browser_take_screenshot called: url=${url}, fullPage=${fullPage}`);
   
@@ -186,25 +190,45 @@ export async function takeScreenshot({ url, fullPage = false }) {
   try {
     const currentUrl = page.url();
     
+    // Safety cap: if fullPage requested, check page height first
+    let effectiveFullPage = fullPage;
+    let wasClipped = false;
+    if (fullPage) {
+      const pageHeight = await page.evaluate(() => document.documentElement.scrollHeight);
+      if (pageHeight > MAX_FULL_PAGE_HEIGHT) {
+        logger.warn(`browser_take_screenshot: page height ${pageHeight}px exceeds ${MAX_FULL_PAGE_HEIGHT}px cap, falling back to viewport`);
+        effectiveFullPage = false;
+        wasClipped = true;
+      }
+    }
+    
     // Take screenshot as base64
     const screenshotBuffer = await page.screenshot({
       encoding: 'base64',
       type: 'png',
-      fullPage: fullPage
+      fullPage: effectiveFullPage
     });
     
-    logger.info(`browser_take_screenshot completed: captured from ${currentUrl} (fullPage=${fullPage})`);
+    logger.info(`browser_take_screenshot completed: captured from ${currentUrl} (fullPage=${effectiveFullPage}${wasClipped ? ', clipped from full' : ''})`);
+    
+    const nextSteps = [];
+    if (wasClipped) {
+      nextSteps.push(`Page too tall for full-page capture (>${MAX_FULL_PAGE_HEIGHT}px). Viewport screenshot taken instead. Use browser_scroll_page to see more content, then browser_take_screenshot again.`);
+    } else if (!fullPage) {
+      nextSteps.push("Use MCPBrowser's browser_take_screenshot with fullPage=true to capture the entire page in one shot");
+    }
+    nextSteps.push(
+      "Use MCPBrowser's browser_get_current_html if you need the HTML instead",
+      "Use MCPBrowser's browser_click_element to interact with elements",
+      "Use MCPBrowser's browser_type_text to fill forms",
+      "Use MCPBrowser's browser_close_tab to free resources when done"
+    );
     
     return new TakeScreenshotSuccessResponse(
       currentUrl,
       screenshotBuffer,
       'image/png',
-      [
-        "Use MCPBrowser's browser_get_current_html if you need the HTML instead",
-        "Use MCPBrowser's browser_click_element to interact with elements",
-        "Use MCPBrowser's browser_type_text to fill forms",
-        "Use MCPBrowser's browser_close_tab to free resources when done"
-      ]
+      nextSteps
     );
   } catch (err) {
     logger.error(`browser_take_screenshot failed: ${err.message}`);

package/src/actions/type-text.js

@@ -100,7 +100,7 @@ export const TYPE_TEXT_TOOL = {
       currentUrl: { type: "string", description: "URL after typing" },
       message: { type: "string", description: "Success message" },
       html: { 
-        type: ["string", "null"], 
+        type: "string", 
         description: "Page HTML if returnHtml was true, null otherwise" 
       },
       nextSteps: { 

package/src/core/page.js

@@ -539,3 +539,24 @@ export async function extractAndProcessHtml(page, removeUnnecessaryHTML, selecto
   
   return processedHtml;
 }
+
+/**
+ * Returns nextStep hints when the HTML response is large and no selector was used.
+ * Call after extractAndProcessHtml to get agent-visible guidance on using the selector
+ * parameter to scope extraction on heavy SPAs.
+ *
+ * @param {string} html - The processed HTML string
+ * @param {string|null} selector - The selector that was used (null = full page)
+ * @returns {string[]} Array of nextStep hint strings (empty if HTML is small or selector was used)
+ */
+export function getLargeHtmlHints(html, selector) {
+  if (selector) return [];
+  const byteLength = new TextEncoder().encode(html).length;
+  if (byteLength > 200_000) {
+    const sizeKB = (byteLength / 1024).toFixed(0);
+    return [
+      `⚠ Large HTML response (${sizeKB}KB). Use the "selector" parameter (e.g., selector: '[role="main"]', 'main', '.content') to extract only the relevant DOM subtree and reduce response size.`
+    ];
+  }
+  return [];
+}

package/src/mcp-browser.js

@@ -71,6 +71,17 @@ async function main() {
     }
   );
 
+  // Capture the negotiated MCP protocol version so the ListTools handler can
+  // strip fields that older clients cannot parse (outputSchema, annotations,
+  // title were added in MCP protocol 2025-03-26).
+  let negotiatedProtocolVersion = null;
+  const _origOnInitialize = server._oninitialize.bind(server);
+  server._oninitialize = async function(request) {
+    const result = await _origOnInitialize(request);
+    negotiatedProtocolVersion = result.protocolVersion;
+    return result;
+  };
+
   // Wire server to logger so logs flow to agent via notifications/message.
   attachLoggerServer(server);
 
@@ -106,7 +117,16 @@ async function main() {
     ...pluginTools
   ];
 
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    // outputSchema, annotations, and title require MCP protocol 2025-03-26+.
+    // Strip them for clients that negotiated an older version (e.g. Antigravity/Gemini).
+    if (!negotiatedProtocolVersion || negotiatedProtocolVersion < '2025-03-26') {
+      return {
+        tools: tools.map(({ outputSchema, annotations, title, ...core }) => core)
+      };
+    }
+    return { tools };
+  });
 
   // --- Prompts handlers ---
   server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));