mcpbrowser 0.3.58 → 0.3.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.58",
+  "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"],
@@ -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

@@ -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

@@ -114,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 {
@@ -159,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 }) => {
@@ -188,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 {
@@ -210,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
     };
   }
 
@@ -110,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"],
@@ -247,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()}`);
     
@@ -260,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/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: {
@@ -124,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"],
@@ -139,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" },
@@ -163,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'
@@ -171,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");
@@ -223,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) {
@@ -250,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 = {
@@ -273,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
@@ -285,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,
@@ -306,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/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 [];
+}