mcpbrowser 0.3.32 → 0.3.34

package/README.md

@@ -31,6 +31,7 @@ Example workflow for AI assistant to use MCPBrowser
   - [npm Package](#option-4-npm-package)
 - [MCP Tools](#mcp-tools)
   - [fetch_webpage](#fetch_webpage)
+  - [execute_javascript](#execute_javascript)
   - [click_element](#click_element)
   - [type_text](#type_text)
   - [get_current_html](#get_current_html)
@@ -165,6 +166,33 @@ Fetches web pages using your Chrome/Edge browser. Handles authentication, CAPTCH
 
 ---
 
+### `execute_javascript`
+
+Executes a JavaScript snippet in the active page context and returns the result with metadata (execution time, truncation flag, URL-change flag). Use this for structured extraction (e.g., inbox rows) or JS-driven UI actions that are unreliable via protocol clicks.
+
+**⚠️ Note:** Page must be already loaded via `fetch_webpage` first.
+
+**Parameters:**
+- `url` (string, required) - The URL of the page (must match a previously fetched page)
+- `script` (string, required) - JavaScript source to execute in the page context
+- `timeoutMs` (number, optional, default: `30000`, max: `60000`) - Execution timeout
+- `returnType` (string, optional, default: `json`) - `json` | `text` | `void`
+
+**Returns:** Serialized result (`outerHTML` for DOM nodes), `type`, `executionTimeMs`, `truncated`, `urlChanged`, `currentUrl`, and structured `error` when the script throws or times out.
+
+**Example:**
+```json
+{
+  "action": "execute_javascript",
+  "url": "https://mail.google.com/",
+  "script": "[...document.querySelectorAll('tr.zA')].slice(0,5).map((row,i)=>({index:i+1,sender:row.querySelector('.zF,.yP')?.textContent,subject:row.querySelector('.bog')?.textContent}))",
+  "timeoutMs": 30000,
+  "returnType": "json"
+}
+```
+
+---
+
 ### `click_element`
 
 Clicks on any clickable element (buttons, links, divs with onclick handlers, etc.). Can target by CSS selector or visible text content. Automatically scrolls element into view and waits for page stability after clicking.
@@ -195,6 +223,8 @@ Clicks on any clickable element (buttons, links, divs with onclick handlers, etc
 { url: "https://example.com", text: "Load More", postClickWait: 2000 }
 ```
 
+**Fallback behavior:** If the native click times out after locating the element, MCPBrowser automatically retries with a JavaScript-based click and returns `fallbackUsed`, `nativeAttempt`, and `fallbackAttempt` metadata. If both attempts fail, the response lists both errors so you can choose another strategy.
+
 ---
 
 ### `type_text`

package/package.json

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

package/src/actions/click-element.js

@@ -33,48 +33,38 @@ import logger from '../core/logger.js';
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
  */
 
-// ============================================================================
-// RESPONSE CLASS
-// ============================================================================
-
 /**
- * Response for successful click_element operations
+ * Structured response for click_element with JS fallback metadata
  */
-export class ClickElementSuccessResponse extends MCPResponse {
-  /**
-   * @param {string} currentUrl - URL after click
-   * @param {string} message - Success message
-   * @param {string|null} html - Page HTML if returnHtml was true
-   * @param {string[]} nextSteps - Suggested next actions
-   */
-  constructor(currentUrl, message, html, nextSteps) {
+export class ClickWithFallbackResponse extends MCPResponse {
+  constructor({ status, fallbackUsed = false, nativeAttempt, fallbackAttempt, postClickWait, currentUrl, html = null, message, nextSteps = [] }) {
     super(nextSteps);
-    
-    if (typeof currentUrl !== 'string') {
-      throw new TypeError('currentUrl must be a string');
-    }
-    if (typeof message !== 'string') {
-      throw new TypeError('message must be a string');
-    }
-    if (html !== null && typeof html !== 'string') {
-      throw new TypeError('html must be a string or null');
-    }
-    
+    this.status = status;
+    this.fallbackUsed = fallbackUsed;
+    this.nativeAttempt = nativeAttempt;
+    this.fallbackAttempt = fallbackAttempt;
+    this.postClickWait = postClickWait;
     this.currentUrl = currentUrl;
-    this.message = message;
     this.html = html;
+    this.message = message;
   }
 
   _getAdditionalFields() {
     return {
+      status: this.status,
+      fallbackUsed: this.fallbackUsed,
+      nativeAttempt: this.nativeAttempt,
+      fallbackAttempt: this.fallbackAttempt,
+      postClickWait: this.postClickWait,
       currentUrl: this.currentUrl,
-      message: this.message,
-      html: this.html
+      html: this.html,
+      message: this.message
     };
   }
 
   getTextSummary() {
-    return this.message || "Element clicked successfully";
+    const base = this.message || 'Click completed';
+    return this.fallbackUsed ? `${base} (JS fallback used)` : base;
   }
 }
 
@@ -106,8 +96,38 @@ export const CLICK_ELEMENT_TOOL = {
   outputSchema: {
     type: "object",
     properties: {
+      status: { type: "string", enum: ["success", "failed"], description: "Overall click status after native and fallback attempts" },
+      fallbackUsed: { type: "boolean", description: "True when native click timed out and JS fallback ran" },
+      nativeAttempt: { 
+        type: "object",
+        properties: {
+          status: { type: "string", enum: ["success", "timeout", "error"] },
+          durationMs: { type: "number" },
+          error: { type: ["string", "null"] }
+        },
+        required: ["status", "durationMs"]
+      },
+      fallbackAttempt: {
+        type: ["object", "null"],
+        properties: {
+          status: { type: "string", enum: ["success", "timeout", "error"] },
+          durationMs: { type: "number" },
+          error: { type: ["string", "null"] }
+        },
+        required: ["status", "durationMs"],
+        description: "Present when fallbackUsed is true"
+      },
+      postClickWait: {
+        type: "object",
+        properties: {
+          applied: { type: "boolean" },
+          waitedMs: { type: "number" }
+        },
+        required: ["applied", "waitedMs"],
+        description: "Post-click wait metadata"
+      },
       currentUrl: { type: "string", description: "URL after click" },
-      message: { type: "string", description: "Success message" },
+      message: { type: "string", description: "Status message" },
       html: { 
         type: ["string", "null"], 
         description: "Page HTML if returnHtml was true, null otherwise" 
@@ -118,7 +138,7 @@ export const CLICK_ELEMENT_TOOL = {
         description: "Suggested next actions"
       }
     },
-    required: ["currentUrl", "message", "html", "nextSteps"],
+    required: ["status", "fallbackUsed", "nativeAttempt", "currentUrl", "message", "html", "nextSteps"],
     additionalProperties: false
   }
 };
@@ -252,28 +272,60 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
     }
 
     // Scroll element into view and click
-    // For automation, use instant scroll instead of smooth animation to avoid delays
     await page.evaluate(el => el.scrollIntoView({ behavior: 'auto', block: 'center' }), elementHandle);
-    // original:
-    // Smooth scroll (commented out for performance):
-    // await page.evaluate(el => el.scrollIntoView({ behavior: 'smooth', block: 'center' }), elementHandle);
-    // await new Promise(r => setTimeout(r, 300)); // Brief delay after scroll
-    
+
+    const attemptClick = async (label, fn, timeoutMs) => {
+      const start = Date.now();
+      let timeoutId;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+      });
+
+      try {
+        await Promise.race([fn(), timeoutPromise]);
+        return { status: 'success', durationMs: Date.now() - start };
+      } catch (error) {
+        const status = /timeout|timed.out/i.test(error?.message || '') ? 'timeout' : 'error';
+        return { status, durationMs: Date.now() - start, error: error?.message || 'Unknown error' };
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    };
+
+    const clickTimeout = Math.min(Math.max(waitForElementTimeout, 500), 60000);
     logger.debug(`Clicking: ${selector || `text="${text}"`}`);
-    await elementHandle.click();
-    
-    // Wait for page to stabilize (handles both navigation and SPA content updates)
-    logger.debug(`Waiting for page to be ready${returnHtml ? '' : ' (fast mode)'}...`);
-    await waitForPageReady(page, { afterInteraction: true });
-    
-    // Wait for SPAs to render dynamic content after click
-    if (postClickWait > 0) {
-      await new Promise(resolve => setTimeout(resolve, postClickWait));
+    const nativeAttempt = await attemptClick('native click', () => elementHandle.click(), clickTimeout);
+
+    let fallbackUsed = false;
+    let fallbackAttempt = null;
+
+    if (nativeAttempt.status === 'timeout') {
+      fallbackUsed = true;
+      fallbackAttempt = await attemptClick('fallback click', () => page.evaluate(el => el.click(), elementHandle), clickTimeout);
     }
-    
+
+    const finalStatus = nativeAttempt.status === 'success' || (fallbackAttempt && fallbackAttempt.status === 'success')
+      ? 'success'
+      : 'failed';
+
+    if (finalStatus === 'success') {
+      logger.debug(`Waiting for page to be ready${returnHtml ? '' : ' (fast mode)'}...`);
+      await waitForPageReady(page, { afterInteraction: true });
+
+      if (postClickWait > 0) {
+        await new Promise(resolve => setTimeout(resolve, postClickWait));
+      }
+    }
+
     const currentUrl = page.url();
-    const clickMessage = selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`;
-    const html = returnHtml ? await extractAndProcessHtml(page, removeUnnecessaryHTML) : null;
+    const html = finalStatus === 'success' && returnHtml ? await extractAndProcessHtml(page, removeUnnecessaryHTML) : null;
+    const baseMessage = selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`;
+    const message = finalStatus === 'success'
+      ? baseMessage
+      : fallbackUsed
+        ? `Click failed after fallback. Native: ${nativeAttempt.error || nativeAttempt.status}. Fallback: ${fallbackAttempt?.error || fallbackAttempt?.status}`
+        : `Click failed. Native: ${nativeAttempt.error || nativeAttempt.status}`;
+
     const nextSteps = returnHtml
       ? [
           "Use MCPBrowser's click_element again to navigate further",
@@ -288,10 +340,20 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
           "Use MCPBrowser's click_element or MCPBrowser's type_text for more interactions",
           "Use MCPBrowser's close_tab when finished"
         ];
-    
-    logger.info(`click_element completed: ${selector || `text="${text}"`}`);
-    
-    return new ClickElementSuccessResponse(currentUrl, clickMessage, html, nextSteps);
+
+    logger.info(`click_element completed: ${selector || `text="${text}"`}${fallbackUsed ? ' (fallback used)' : ''}`);
+
+    return new ClickWithFallbackResponse({
+      status: finalStatus,
+      fallbackUsed,
+      nativeAttempt,
+      fallbackAttempt,
+      postClickWait: { applied: finalStatus === 'success', waitedMs: finalStatus === 'success' ? postClickWait : 0 },
+      currentUrl,
+      html,
+      message,
+      nextSteps
+    });
   } catch (err) {
     logger.error(`click_element failed: ${err.message}`);
     return new InformationalResponse(

package/src/actions/execute-javascript.js

@@ -0,0 +1,244 @@
+/**
+ * execute-javascript.js - Run arbitrary JavaScript in the current page context
+ */
+
+import { getBrowser, getValidatedPage } from '../core/browser.js';
+import { waitForPageReady } from '../core/page.js';
+import { MCPResponse, InformationalResponse } from '../core/responses.js';
+import logger from '../core/logger.js';
+import { serializeExecutionResult } from '../utils.js';
+
+// Shared execution defaults for script actions
+export const EXECUTION_TIMEOUT_DEFAULT_MS = 30_000;
+export const EXECUTION_TIMEOUT_MAX_MS = 60_000;
+export const EXECUTION_RESULT_MAX_BYTES = 100_000;
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+/**
+ * Structured response for execute_javascript action
+ */
+export class ExecuteJavascriptResponse extends MCPResponse {
+  constructor({ result, type, executionTimeMs, truncated = false, urlChanged = false, currentUrl = '', error = null, nextSteps = [] }) {
+    super(nextSteps);
+
+    this.result = result;
+    this.type = type;
+    this.executionTimeMs = executionTimeMs;
+    this.truncated = truncated;
+    this.urlChanged = urlChanged;
+    this.currentUrl = currentUrl;
+    this.error = error;
+  }
+
+  _getAdditionalFields() {
+    return {
+      result: this.result,
+      type: this.type,
+      executionTimeMs: this.executionTimeMs,
+      truncated: this.truncated,
+      urlChanged: this.urlChanged,
+      currentUrl: this.currentUrl,
+      error: this.error || undefined
+    };
+  }
+
+  getTextSummary() {
+    const outcome = this.error ? `Script error: ${this.error.message || 'Unknown error'}` : 'Script executed';
+    const timing = typeof this.executionTimeMs === 'number' ? ` in ${this.executionTimeMs}ms` : '';
+    const nav = this.urlChanged ? ' (navigation detected)' : '';
+    return `${outcome}${timing}${nav}`;
+  }
+}
+
+export const EXECUTE_JAVASCRIPT_TOOL = {
+  name: 'execute_javascript',
+  title: 'Execute JavaScript',
+  description: '**BROWSER INTERACTION** - Executes a JavaScript snippet in the active page and returns the result with metadata (execution time, truncation, navigation detection). Use for structured extraction or UI actions that are unreliable via protocol clicks.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: 'The URL of the page (must match a previously fetched page)' },
+      script: { type: 'string', description: 'JavaScript source code to execute in page context' },
+      timeoutMs: { type: 'number', description: 'Maximum execution time in milliseconds', default: EXECUTION_TIMEOUT_DEFAULT_MS },
+      returnType: { type: 'string', description: "How to interpret the result: 'json' | 'text' | 'void'", enum: ['json', 'text', 'void'], default: 'json' }
+    },
+    required: ['url', 'script'],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      result: { 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' }
+    },
+    required: ['type', 'executionTimeMs', 'truncated', 'urlChanged', 'currentUrl', 'nextSteps'],
+    additionalProperties: false
+  }
+};
+
+function clampTimeout(timeoutMs) {
+  const numeric = typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) ? timeoutMs : EXECUTION_TIMEOUT_DEFAULT_MS;
+  return Math.min(Math.max(numeric, 1), EXECUTION_TIMEOUT_MAX_MS);
+}
+
+function buildErrorResponse(message, reason, nextSteps) {
+  return new InformationalResponse(message, reason, nextSteps);
+}
+
+export async function executeJavascript({ url, script, timeoutMs = EXECUTION_TIMEOUT_DEFAULT_MS, returnType = 'json' }) {
+  logger.info(`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');
+
+  let hostname;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  try {
+    await getBrowser();
+  } catch (err) {
+    logger.error(`execute_javascript: Failed to connect to browser: ${err.message}`);
+    return buildErrorResponse(
+      `Browser connection failed: ${err.message}`,
+      'The browser must be running with remote debugging enabled.',
+      [
+        'Ensure the browser is installed and running',
+        'Check that remote debugging is enabled (--remote-debugging-port)',
+        'Try restarting the MCP server'
+      ]
+    );
+  }
+
+  const { page, error: pageError } = await getValidatedPage(hostname);
+  if (!page) {
+    const isConnectionLost = pageError && pageError.includes('connection');
+    logger.debug(`execute_javascript: ${pageError || 'No page found for ' + hostname}`);
+    return buildErrorResponse(
+      isConnectionLost ? `Page connection lost for ${hostname}` : `No open page found for ${hostname}`,
+      isConnectionLost
+        ? 'The browser tab was closed or the connection was lost. The page needs to be reloaded.'
+        : 'The page must be loaded before you can run scripts on it.',
+      [
+        "Use MCPBrowser's fetch_webpage tool to load the page first",
+        "Then retry MCPBrowser's execute_javascript with the same URL"
+      ]
+    );
+  }
+
+  const effectiveTimeout = clampTimeout(timeoutMs);
+  const beforeUrl = page.url();
+  const start = Date.now();
+
+  const evalPromise = page.evaluate(async ({ userScript, mode }) => {
+    const wrap = async () => {
+      const fn = new Function(`return (async () => { ${userScript} })();`);
+      return await fn();
+    };
+
+    try {
+      const value = await wrap();
+      const isDom = typeof Element !== 'undefined' && value instanceof Element;
+      if (mode === 'void') {
+        return { value: null, type: 'void' };
+      }
+      if (mode === 'text') {
+        return { value: String(value), type: 'string' };
+      }
+      if (isDom) {
+        return { value: value.outerHTML, type: 'dom-html' };
+      }
+      const valueType = Array.isArray(value) ? 'array' : (value === null ? 'null' : typeof value);
+      return { value, type: valueType };
+    } catch (error) {
+      return { error: { name: error?.name || 'Error', message: error?.message || 'Script error', stack: error?.stack || '' } };
+    }
+  }, { userScript: script, mode: returnType });
+
+  let evalResult;
+  try {
+    evalResult = await Promise.race([
+      evalPromise,
+      new Promise((_, reject) => setTimeout(() => reject(new Error(`Execution timed out after ${effectiveTimeout}ms`)), effectiveTimeout))
+    ]);
+  } catch (err) {
+    const executionTimeMs = Date.now() - start;
+    let currentUrl = page.url();
+    try {
+      currentUrl = await page.evaluate(() => location.href);
+    } catch {
+      // ignore evaluation failures when the page is gone
+    }
+    return new ExecuteJavascriptResponse({
+      result: null,
+      type: 'error',
+      executionTimeMs,
+      truncated: false,
+      urlChanged: currentUrl !== beforeUrl,
+      currentUrl,
+      error: { name: 'TimeoutError', message: err.message }
+    });
+  }
+
+  const executionTimeMs = Date.now() - start;
+  let currentUrl = page.url();
+  try {
+    currentUrl = await page.evaluate(() => location.href);
+  } catch {
+    // If we can't read location (e.g., cross-origin), fall back to page.url()
+  }
+  const urlChanged = currentUrl !== beforeUrl;
+
+  if (evalResult?.error) {
+    return new ExecuteJavascriptResponse({
+      result: null,
+      type: 'error',
+      executionTimeMs,
+      truncated: false,
+      urlChanged,
+      currentUrl,
+      error: evalResult.error
+    });
+  }
+
+  const serialization = serializeExecutionResult(evalResult?.value, { maxBytes: EXECUTION_RESULT_MAX_BYTES });
+
+  return new ExecuteJavascriptResponse({
+    result: serialization.result,
+    type: evalResult?.type || serialization.type,
+    executionTimeMs,
+    truncated: serialization.truncated,
+    urlChanged,
+    currentUrl,
+    nextSteps: [
+      'Use click_element or type_text for follow-up actions',
+      'Inspect urlChanged to decide if navigation occurred',
+      serialization.truncated ? 'Narrow your selector or reduce returned fields to avoid truncation' : 'Proceed with the returned data'
+    ]
+  });
+}
+
+export async function executeJavascriptWithReady(params) {
+  const response = await executeJavascript(params);
+  try {
+    if (!response.error) {
+      const { page } = await getValidatedPage(new URL(params.url).hostname);
+      if (page) await waitForPageReady(page, { afterInteraction: true });
+    }
+  } catch (err) {
+    logger.debug(`execute_javascript post-wait skipped: ${err.message}`);
+  }
+  return response;
+}

package/src/actions/navigate-history.js

@@ -0,0 +1,248 @@
+/**
+ * navigate-history.js - Browser back/forward navigation
+ * Navigates browser history on an already-loaded page.
+ */
+
+import { getBrowser, getValidatedPage, domainPages } from '../core/browser.js';
+import { extractAndProcessHtml, waitForPageReady } from '../core/page.js';
+import { MCPResponse, InformationalResponse } from '../core/responses.js';
+import logger from '../core/logger.js';
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+// ============================================================================
+// RESPONSE CLASS
+// ============================================================================
+
+/**
+ * Response for successful navigate_history operations
+ */
+export class NavigateHistorySuccessResponse extends MCPResponse {
+  /**
+   * @param {string} direction - Navigation direction (back or forward)
+   * @param {string} previousUrl - URL before navigation
+   * @param {string} currentUrl - URL after navigation
+   * @param {string|null} html - Page HTML content (null if returnHtml=false)
+   * @param {string[]} nextSteps - Suggested next actions
+   */
+  constructor(direction, previousUrl, currentUrl, html, nextSteps) {
+    super(nextSteps);
+
+    if (typeof direction !== 'string') {
+      throw new TypeError('direction must be a string');
+    }
+    if (typeof previousUrl !== 'string') {
+      throw new TypeError('previousUrl must be a string');
+    }
+    if (typeof currentUrl !== 'string') {
+      throw new TypeError('currentUrl must be a string');
+    }
+    if (html !== null && typeof html !== 'string') {
+      throw new TypeError('html must be a string or null');
+    }
+
+    this.direction = direction;
+    this.previousUrl = previousUrl;
+    this.currentUrl = currentUrl;
+    this.html = html;
+  }
+
+  _getAdditionalFields() {
+    return {
+      direction: this.direction,
+      previousUrl: this.previousUrl,
+      currentUrl: this.currentUrl,
+      html: this.html
+    };
+  }
+
+  getTextSummary() {
+    return `Navigated ${this.direction}: ${this.previousUrl} → ${this.currentUrl}`;
+  }
+}
+
+// ============================================================================
+// TOOL DEFINITION
+// ============================================================================
+
+/** @type {Tool} */
+export const NAVIGATE_HISTORY_TOOL = {
+  name: "navigate_history",
+  title: "Navigate Back/Forward",
+  description: "**BROWSER HISTORY NAVIGATION** - Navigate back or forward in browser history on an already-loaded page. Use after clicking links to return to the previous page, or to go forward after going back.\n\n**PREREQUISITE**: Page MUST be loaded with fetch_webpage first. This tool navigates the history of an existing browser tab.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "URL of the already-loaded page (identifies which tab to navigate)" },
+      direction: {
+        type: "string",
+        enum: ["back", "forward"],
+        description: "Navigation direction: 'back' to go to previous page, 'forward' to go to next page",
+        default: "back"
+      },
+      returnHtml: { type: "boolean", description: "Return page HTML after navigation", default: true },
+      removeUnnecessaryHTML: { type: "boolean", description: "Remove unnecessary HTML elements (scripts, styles, etc.) for size reduction.", default: true }
+    },
+    required: ["url"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      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)" },
+      nextSteps: {
+        type: "array",
+        items: { type: "string" },
+        description: "Suggested next actions"
+      }
+    },
+    required: ["direction", "previousUrl", "currentUrl", "nextSteps"],
+    additionalProperties: false
+  },
+  annotations: {
+    title: "Navigate Back/Forward",
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true
+  }
+};
+
+// ============================================================================
+// ACTION FUNCTION
+// ============================================================================
+
+/**
+ * Navigate browser history (back/forward) on an already-loaded page
+ * @param {Object} params - Parameters
+ * @param {string} params.url - URL of the already-loaded page
+ * @param {string} [params.direction='back'] - Navigation direction
+ * @param {boolean} [params.returnHtml=true] - Return page HTML after navigation
+ * @param {boolean} [params.removeUnnecessaryHTML=true] - Clean HTML
+ * @returns {Promise<MCPResponse>} Navigation result
+ */
+export async function navigateHistory({ url, direction = 'back', returnHtml = true, removeUnnecessaryHTML = true }) {
+  logger.info(`navigate_history called: url=${url}, direction=${direction}`);
+
+  if (!url) {
+    throw new Error("url parameter is required");
+  }
+
+  let hostname;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  // Ensure browser connection
+  try {
+    await getBrowser();
+  } catch (err) {
+    logger.error(`navigate_history: Failed to connect to browser: ${err.message}`);
+    return new InformationalResponse(
+      `Browser connection failed: ${err.message}`,
+      'The browser must be running with remote debugging enabled.',
+      [
+        'Ensure the browser is installed and running',
+        'Check that remote debugging is enabled (--remote-debugging-port)',
+        'Try restarting the MCP server'
+      ]
+    );
+  }
+
+  // Validate page exists and is usable
+  const { page, error: pageError } = await getValidatedPage(hostname);
+
+  if (!page) {
+    const isConnectionLost = pageError && pageError.includes('connection');
+    logger.debug(`navigate_history: ${pageError || 'No page found for ' + hostname}`);
+    return new InformationalResponse(
+      isConnectionLost ? `Page connection lost for ${hostname}` : `No open page found for ${hostname}`,
+      isConnectionLost
+        ? 'The browser tab was closed or the connection was lost. The page needs to be reloaded.'
+        : 'The page must be loaded before you can navigate its history.',
+      [
+        "Use MCPBrowser's fetch_webpage tool to load the page first",
+        "Then retry MCPBrowser's navigate_history with the same URL"
+      ]
+    );
+  }
+
+  try {
+    const previousUrl = page.url();
+
+    // Navigate history
+    let response;
+    if (direction === 'forward') {
+      response = await page.goForward({ waitUntil: 'domcontentloaded', timeout: 30000 });
+    } else {
+      response = await page.goBack({ waitUntil: 'domcontentloaded', timeout: 30000 });
+    }
+
+    // goBack/goForward return null if there's no history entry
+    if (response === null) {
+      logger.info(`navigate_history: No ${direction} history entry available`);
+      return new InformationalResponse(
+        `No ${direction} history entry available`,
+        `The page has no ${direction} history to navigate to. This means you're already at the ${direction === 'back' ? 'first' : 'last'} page in the browsing history for this tab.`,
+        [
+          direction === 'back'
+            ? "Use MCPBrowser's fetch_webpage to navigate to a different URL"
+            : "Use MCPBrowser's navigate_history with direction='back' to go back instead",
+          "Use MCPBrowser's get_current_html to check the current page content"
+        ]
+      );
+    }
+
+    const currentUrl = page.url();
+
+    // Update domainPages if hostname changed after navigation
+    try {
+      const newHostname = new URL(currentUrl).hostname;
+      if (newHostname !== hostname) {
+        domainPages.delete(hostname);
+        domainPages.set(newHostname, page);
+        logger.info(`navigate_history: Updated domainPages mapping: ${hostname} → ${newHostname}`);
+      }
+    } catch {
+      // If URL parsing fails, keep existing mapping
+    }
+
+    // Extract HTML if requested
+    let html = null;
+    if (returnHtml) {
+      await waitForPageReady(page);
+      html = await extractAndProcessHtml(page, removeUnnecessaryHTML);
+    }
+
+    logger.info(`navigate_history completed: ${direction} from ${previousUrl} to ${currentUrl}`);
+
+    return new NavigateHistorySuccessResponse(
+      direction,
+      previousUrl,
+      currentUrl,
+      html,
+      [
+        "Use MCPBrowser's navigate_history to go back or forward again",
+        "Use MCPBrowser's click_element to interact with elements on the page",
+        "Use MCPBrowser's get_current_html to re-read the page content",
+        "Use MCPBrowser's fetch_webpage to navigate to a new URL"
+      ]
+    );
+  } catch (err) {
+    logger.error(`navigate_history failed: ${err.message}`);
+    return new InformationalResponse(
+      `Navigation ${direction} failed: ${err.message}`,
+      'The browser could not navigate. The page may have been closed or the connection was lost.',
+      [
+        "Try MCPBrowser's fetch_webpage to reload the page",
+        "Use MCPBrowser's close_tab and start fresh if needed"
+      ]
+    );
+  }
+}

package/src/mcp-browser.js

@@ -27,6 +27,8 @@ import { closeTab, CLOSE_TAB_TOOL } from './actions/close-tab.js';
 import { getCurrentHtml, GET_CURRENT_HTML_TOOL } from './actions/get-current-html.js';
 import { takeScreenshot, TAKE_SCREENSHOT_TOOL } from './actions/take-screenshot.js';
 import { scrollPage, SCROLL_PAGE_TOOL } from './actions/scroll-page.js';
+import { executeJavascript, EXECUTE_JAVASCRIPT_TOOL } from './actions/execute-javascript.js';
+import { navigateHistory, NAVIGATE_HISTORY_TOOL } from './actions/navigate-history.js';
 
 // Import functions for testing exports
 import { getBrowser, closeBrowser } from './core/browser.js';
@@ -60,12 +62,14 @@ async function main() {
   const tools = [
     // ACCEPT_EULA_TOOL,
     FETCH_WEBPAGE_TOOL,
+    EXECUTE_JAVASCRIPT_TOOL,
     CLICK_ELEMENT_TOOL,
     TYPE_TEXT_TOOL,
     CLOSE_TAB_TOOL,
     GET_CURRENT_HTML_TOOL,
     TAKE_SCREENSHOT_TOOL,
-    SCROLL_PAGE_TOOL
+    SCROLL_PAGE_TOOL,
+    NAVIGATE_HISTORY_TOOL
   ];
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
@@ -91,6 +95,10 @@ async function main() {
         case "fetch_webpage":
           result = await fetchPage(safeArgs);
           break;
+
+        case "execute_javascript":
+          result = await executeJavascript(safeArgs);
+          break;
           
         case "click_element":
           result = await clickElement(safeArgs);
@@ -115,6 +123,10 @@ async function main() {
         case "scroll_page":
           result = await scrollPage(safeArgs);
           break;
+
+        case "navigate_history":
+          result = await navigateHistory(safeArgs);
+          break;
           
         default:
           throw new Error(`Unknown tool: ${name}`);
@@ -158,12 +170,14 @@ export {
   extractAndProcessHtml,
   getBaseDomain,
   isLikelyAuthUrl,
+  executeJavascript,
   clickElement,
   typeText,
   closeTab,
   getCurrentHtml,
   takeScreenshot,
   scrollPage,
+  navigateHistory,
   handleAcceptEula
 };
 

package/src/utils.js

@@ -72,6 +72,71 @@ export function truncate(str, max) {
   return str.length > max ? `${str.slice(0, max)}... [truncated]` : str;
 }
 
+function byteLength(str) {
+  return new TextEncoder().encode(str).length;
+}
+
+function safeStringify(value) {
+  const seen = new WeakSet();
+  return JSON.stringify(value, (key, val) => {
+    if (typeof val === 'function' || typeof val === 'symbol') return undefined;
+    if (typeof val === 'bigint') return val.toString();
+    if (val && typeof val === 'object') {
+      if (seen.has(val)) return '[Circular]';
+      seen.add(val);
+    }
+    return val;
+  });
+}
+
+/**
+ * Serialize a JS value for MCP responses with size and safety guards.
+ * Returns JSON-safe payload, detected type, and truncation flag.
+ * @param {any} value
+ * @param {object} options
+ * @param {number} [options.maxBytes=100000]
+ * @returns {{ result: any, type: string, truncated: boolean }}
+ */
+export function serializeExecutionResult(value, { maxBytes = 100_000 } = {}) {
+  let type = Array.isArray(value) ? 'array' : (value === null ? 'null' : typeof value);
+  let jsonString;
+
+  if (type === 'string') {
+    jsonString = String(value);
+  } else {
+    try {
+      jsonString = safeStringify(value);
+    } catch (err) {
+      jsonString = String(value);
+      type = 'string';
+    }
+  }
+
+  let truncated = false;
+  if (byteLength(jsonString) > maxBytes) {
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    const sliced = encoder.encode(jsonString).slice(0, maxBytes);
+    jsonString = `${decoder.decode(sliced)}...[truncated]`;
+    truncated = true;
+    type = 'string';
+  }
+
+  let parsed = value;
+  if (type === 'object' || type === 'array' || type === 'null') {
+    try {
+      parsed = JSON.parse(jsonString);
+    } catch {
+      parsed = jsonString;
+      type = 'string';
+    }
+  } else if (type === 'string') {
+    parsed = jsonString;
+  }
+
+  return { result: parsed, type, truncated };
+}
+
 /**
  * Extract base domain from hostname (e.g., "mail.google.com" → "google.com")
  * @param {string} hostname - The hostname to parse