mcpbrowser 0.3.19 → 0.3.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.19",
+  "version": "0.3.20",
   "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/accept-eula.js

@@ -0,0 +1,188 @@
+/**
+ * accept-eula.js - Accept the End User License Agreement
+ * This tool must be called before any other MCPBrowser tools can be used.
+ */
+
+import { MCPResponse } from '../core/responses.js';
+import { acceptEula, isEulaAccepted, EULA_URL } from '../core/eula.js';
+import logger from '../core/logger.js';
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+// ============================================================================
+// EULA CHECK HELPER
+// ============================================================================
+
+/**
+ * Check if EULA acceptance is required before executing a tool.
+ * @param {string} toolName - The name of the tool being called
+ * @returns {Object|null} MCP-formatted response if EULA not accepted, null if OK to proceed
+ */
+export function requireEulaAcceptance(toolName) {
+  if (isEulaAccepted()) {
+    return null;
+  }
+  
+  logger.info(`Tool ${toolName} requested - EULA acceptance required`);
+  return new EulaPendingResponse(
+    EULA_URL,
+    [],
+    toolName
+  ).toMcpFormat();
+}
+
+// ============================================================================
+// RESPONSE CLASSES
+// ============================================================================
+
+/**
+ * Response when EULA needs to be accepted (shown before acceptance)
+ */
+export class EulaPendingResponse extends MCPResponse {
+  /**
+   * @param {string} eulaUrl - URL to the EULA
+   * @param {string[]} nextSteps - Suggested next actions
+   * @param {string} [attemptedAction] - The tool the user tried to use (optional)
+   */
+  constructor(eulaUrl, nextSteps, attemptedAction = null) {
+    super(nextSteps);
+    
+    if (typeof eulaUrl !== 'string') {
+      throw new TypeError('eulaUrl must be a string');
+    }
+    
+    this.eulaUrl = eulaUrl;
+    this.accepted = false;
+    this.attemptedAction = attemptedAction;
+    this.requiresUserConfirmation = true;
+  }
+
+  _getAdditionalFields() {
+    return {
+      accepted: this.accepted,
+      eulaUrl: this.eulaUrl,
+      requiresUserConfirmation: this.requiresUserConfirmation,
+      ...(this.attemptedAction && { attemptedAction: this.attemptedAction })
+    };
+  }
+
+  getTextSummary() {
+    return `STOP - EXPLICIT USER CONFIRMATION REQUIRED !!!
+
+Use ask questions tool to show a Yes/No options asking the user: "Do you accept the MCPBrowser EULA at ${this.eulaUrl}?"
+
+DO NOT call accept_eula until the user explicitly selects "Yes".
+If the user selects "No" or does not respond, DO NOT proceed.
+
+When calling accept_eula, you MUST set userExplicitlyConfirmed=true ONLY if user said Yes.`;
+  }
+}
+
+/**
+ * Response for successful EULA acceptance
+ */
+export class EulaAcceptedResponse extends MCPResponse {
+  /**
+   * @param {string} eulaUrl - URL to the EULA that was accepted
+   * @param {string[]} nextSteps - Suggested next actions
+   */
+  constructor(eulaUrl, nextSteps) {
+    super(nextSteps);
+    
+    if (typeof eulaUrl !== 'string') {
+      throw new TypeError('eulaUrl must be a string');
+    }
+    
+    this.eulaUrl = eulaUrl;
+    this.accepted = true;
+  }
+
+  _getAdditionalFields() {
+    return {
+      accepted: this.accepted,
+      eulaUrl: this.eulaUrl
+    };
+  }
+
+  getTextSummary() {
+    return `EULA accepted (${this.eulaUrl}). You now have full access to MCPBrowser tools.`;
+  }
+}
+
+// ============================================================================
+// TOOL DEFINITION
+// ============================================================================
+
+/**
+ * @type {Tool}
+ */
+export const ACCEPT_EULA_TOOL = {
+  name: "accept_eula",
+  description: "CRITICAL: You MUST ask the user 'Do you accept the MCPBrowser EULA?' and wait for their explicit 'Yes' response BEFORE calling this tool. Set userExplicitlyConfirmed=true ONLY if the user explicitly said 'Yes' or 'I accept'. If the user has not responded or said 'No', DO NOT call this tool. Calling this tool without user consent violates the EULA terms.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      userExplicitlyConfirmed: {
+        type: "boolean",
+        description: "REQUIRED: Must be true. Set to true ONLY if the user explicitly said 'Yes' or 'I accept' to the EULA prompt. Never set to true without explicit user confirmation."
+      }
+    },
+    required: ["userExplicitlyConfirmed"]
+  }
+};
+
+// ============================================================================
+// TOOL IMPLEMENTATION
+// ============================================================================
+
+/**
+ * Handle EULA acceptance
+ * @param {Object} args - Tool arguments
+ * @param {boolean} args.userExplicitlyConfirmed - Whether user explicitly confirmed acceptance
+ * @returns {Promise<MCPResponse>} Response indicating EULA status
+ */
+export async function handleAcceptEula(args) {
+  const { userExplicitlyConfirmed } = args;
+  
+  logger.debug(`accept_eula called with userExplicitlyConfirmed: ${userExplicitlyConfirmed}`);
+  
+  // If already accepted and calling again, just confirm
+  if (isEulaAccepted()) {
+    logger.info('EULA already accepted');
+    return new EulaAcceptedResponse(
+      EULA_URL,
+      [
+        'Use fetch_webpage to navigate to a URL',
+        'Use get_current_html to see the current page content'
+      ]
+    );
+  }
+  
+  // CRITICAL: Validate user explicitly confirmed
+  if (userExplicitlyConfirmed !== true) {
+    logger.warn('accept_eula called without userExplicitlyConfirmed=true - rejecting');
+    return new EulaPendingResponse(
+      EULA_URL,
+      [
+        'Ask the user: "Do you accept the MCPBrowser EULA?"',
+        'Wait for explicit "Yes" response',
+        'Then call accept_eula with userExplicitlyConfirmed=true'
+      ]
+    );
+  }
+  
+  // Accept the EULA
+  acceptEula(EULA_URL);
+  logger.info('EULA accepted with explicit user confirmation');
+  
+  return new EulaAcceptedResponse(
+    EULA_URL,
+    [
+      'Use fetch_webpage to navigate to a URL',
+      'Use click_element to interact with page elements',
+      'Use type_text to enter text into forms'
+    ]
+  );
+}

package/src/actions/click-element.js

@@ -192,7 +192,7 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
   
   if (!page) {
     const isConnectionLost = pageError && pageError.includes('connection');
-    logger.info(`click_element: ${pageError || 'No page found for ' + hostname}`);
+    logger.debug(`click_element: ${pageError || 'No page found for ' + hostname}`);
     return new InformationalResponse(
       isConnectionLost ? `Page connection lost for ${hostname}` : `No open page found for ${hostname}`,
       isConnectionLost 
@@ -259,13 +259,13 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
     // await page.evaluate(el => el.scrollIntoView({ behavior: 'smooth', block: 'center' }), elementHandle);
     // await new Promise(r => setTimeout(r, 300)); // Brief delay after scroll
     
-    logger.info(`Clicking: ${selector || `text="${text}"`}`);
+    logger.debug(`Clicking: ${selector || `text="${text}"`}`);
     await elementHandle.click();
     
     if (returnHtml) {
       // Wait for page to stabilize (handles both navigation and SPA content updates)
       // This ensures content is fully loaded before returning, just like fetch_webpage does
-      logger.info('Waiting for page stability...');
+      logger.debug('Waiting for page stability...');
       await waitForPageStability(page);
       
       // Wait for SPAs to render dynamic content after click
@@ -292,7 +292,7 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       );
     } else {
       // Wait for page to stabilize even for fast clicks (ensures JS has finished)
-      logger.info('Waiting for page stability (fast mode)...');
+      logger.debug('Waiting for page stability (fast mode)...');
       await waitForPageStability(page);
       
       // Wait for SPAs to render dynamic content after click

package/src/actions/fetch-page.js

@@ -190,7 +190,7 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
     const redirectInfo = detectRedirectType(url, hostname, currentUrl, currentHostname);
     
     if (redirectInfo.type === 'requested_auth') {
-      logger.info('User requested auth page directly, returning content');
+      logger.debug('User requested auth page directly, returning content');
       // Update domain mapping if needed
       if (redirectInfo.currentHostname !== hostname) {
         domainPages.delete(hostname);
@@ -198,13 +198,13 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
         hostname = redirectInfo.currentHostname;
       }
     } else if (redirectInfo.type === 'permanent') {
-      logger.info(`Redirect: ${hostname} → ${redirectInfo.currentHostname}`);
+      logger.debug(`Redirect: ${hostname} → ${redirectInfo.currentHostname}`);
       
       // Check if we already have a tab for the redirected hostname
       // (can happen after reconnect - we mapped mail.google.com but not gmail.com)
       const existingPage = domainPages.get(redirectInfo.currentHostname);
       if (existingPage && existingPage !== page && !existingPage.isClosed()) {
-        logger.info(`Found existing tab for ${redirectInfo.currentHostname}, reusing it`);
+        logger.debug(`Found existing tab for ${redirectInfo.currentHostname}, reusing it`);
         // Close the new tab we just opened, use the existing one
         await page.close().catch(() => {});
         domainPages.delete(hostname);
@@ -263,7 +263,7 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
     
     // Additional wait if requested (for pages that need extra time)
     if (postLoadWait > 0) {
-      logger.info(`Waiting ${postLoadWait}ms (postLoadWait)...`);
+      logger.debug(`Waiting ${postLoadWait}ms (postLoadWait)...`);
       await new Promise(resolve => setTimeout(resolve, postLoadWait));
     }
     
@@ -274,7 +274,7 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
     
     // Check for non-2xx HTTP status codes - return informational response (not red error)
     if (statusCode && (statusCode >= 400 && statusCode < 600)) {
-      logger.info(`HTTP ${statusCode} ${statusText} - returning as informational response`);
+      logger.debug(`HTTP ${statusCode} ${statusText} - returning as informational response`);
       return new HttpStatusResponse(
         page.url(),
         statusCode,

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

@@ -134,7 +134,7 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
   
   if (!page) {
     const isConnectionLost = pageError && pageError.includes('connection');
-    logger.info(`get_current_html: ${pageError || 'No page found for ' + hostname}`);
+    logger.debug(`get_current_html: ${pageError || 'No page found for ' + hostname}`);
     return new InformationalResponse(
       isConnectionLost ? `Page connection lost for ${hostname}` : `No open page found for ${hostname}`,
       isConnectionLost 

package/src/actions/scroll-page.js

@@ -200,7 +200,7 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
   
   if (!page) {
     const isConnectionLost = pageError && pageError.includes('connection');
-    logger.info(`scroll_page: ${pageError || 'No page found for ' + hostname}`);
+    logger.debug(`scroll_page: ${pageError || 'No page found for ' + hostname}`);
     return new InformationalResponse(
       isConnectionLost ? `Page connection lost for ${hostname}` : `No open page found for ${hostname}`,
       isConnectionLost 
@@ -219,7 +219,7 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
     // Determine scroll mode and execute
     if (selector) {
       // Scroll to element mode
-      logger.info(`scroll_page: Scrolling to element: ${selector}`);
+      logger.debug(`scroll_page: Scrolling to element: ${selector}`);
       
       const elementExists = await page.$(selector);
       if (!elementExists) {
@@ -243,7 +243,7 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
       
     } else if (typeof x === 'number' && typeof y === 'number') {
       // Absolute position mode
-      logger.info(`scroll_page: Scrolling to absolute position: (${x}, ${y})`);
+      logger.debug(`scroll_page: Scrolling to absolute position: (${x}, ${y})`);
       
       await page.evaluate(({ scrollX, scrollY }) => {
         window.scrollTo(scrollX, scrollY);
@@ -251,7 +251,7 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
       
     } else if (direction) {
       // Directional scroll mode
-      logger.info(`scroll_page: Scrolling ${direction} by ${amount}px`);
+      logger.debug(`scroll_page: Scrolling ${direction} by ${amount}px`);
       
       const scrollDeltas = {
         up: { x: 0, y: -amount },
@@ -271,7 +271,7 @@ export async function scrollPage({ url, direction, amount = 500, selector, x, y
       
     } else {
       // No scroll parameters provided - just return current position
-      logger.info(`scroll_page: No scroll action specified, returning current position`);
+      logger.debug(`scroll_page: No scroll action specified, returning current position`);
     }
     
     // Small delay to let scroll complete

package/src/actions/take-screenshot.js

@@ -163,7 +163,7 @@ export async function takeScreenshot({ url, fullPage = false }) {
   
   if (!page) {
     const isConnectionLost = pageError && pageError.includes('connection');
-    logger.info(`take_screenshot: ${pageError || 'No page found for ' + hostname}`);
+    logger.debug(`take_screenshot: ${pageError || 'No page found for ' + hostname}`);
     return new InformationalResponse(
       isConnectionLost ? `Page connection lost for ${hostname}` : `No open page found for ${hostname}`,
       isConnectionLost 

package/src/actions/type-text.js

@@ -186,7 +186,7 @@ export async function typeText({ url, fields, returnHtml = true, removeUnnecessa
   
   if (!page) {
     const isConnectionLost = pageError && pageError.includes('connection');
-    logger.info(`type_text: ${pageError || 'No page found for ' + hostname}`);
+    logger.debug(`type_text: ${pageError || 'No page found for ' + hostname}`);
     return new InformationalResponse(
       isConnectionLost ? `Page connection lost for ${hostname}` : `No open page found for ${hostname}`,
       isConnectionLost 
@@ -216,7 +216,7 @@ export async function typeText({ url, fields, returnHtml = true, removeUnnecessa
         await page.keyboard.press('Backspace');
       }
       
-      logger.info(`Typing into: ${selector}`);
+      logger.debug(`Typing into: ${selector}`);
       await page.type(selector, String(text), { delay: TYPE_DELAY_MS });
       filledSelectors.push(selector);
       currentFieldIndex++;
@@ -228,7 +228,7 @@ export async function typeText({ url, fields, returnHtml = true, removeUnnecessa
     
     if (returnHtml) {
       // Wait for page to stabilize (handles form validation, autocomplete, etc.)
-      logger.info('Waiting for page stability after typing...');
+      logger.debug('Waiting for page stability after typing...');
       await waitForPageStability(page);
       
       // Wait for SPAs to render dynamic content after typing
@@ -255,7 +255,7 @@ export async function typeText({ url, fields, returnHtml = true, removeUnnecessa
       );
     } else {
       // Wait for page to stabilize even without returning HTML
-      logger.info('Waiting for page stability after typing (fast mode)...');
+      logger.debug('Waiting for page stability after typing (fast mode)...');
       await waitForPageStability(page);
       
       // Wait for SPAs to render dynamic content after typing

package/src/core/eula.js

@@ -0,0 +1,120 @@
+/**
+ * EULA (End User License Agreement) Management
+ * Tracks whether the user has accepted the EULA.
+ * EULA acceptance is persisted to disk and remembered across sessions.
+ */
+
+import logger from './logger.js';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// EULA URL - where the full license agreement can be found
+export const EULA_URL = 'https://github.com/cherchyk/MCPBrowser/blob/main/EULA.md';
+
+// Config directory and file paths
+const CONFIG_DIR = join(homedir(), '.mcpbrowser');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+// In-memory cache of EULA acceptance status
+let eulaAccepted = null;
+
+/**
+ * Load config from disk
+ * @returns {Object} Config object
+ */
+function loadConfig() {
+  try {
+    if (existsSync(CONFIG_FILE)) {
+      const data = readFileSync(CONFIG_FILE, 'utf-8');
+      return JSON.parse(data);
+    }
+  } catch (error) {
+    logger.warn(`Failed to load config: ${error.message}`);
+  }
+  return {};
+}
+
+/**
+ * Save config to disk
+ * @param {Object} config - Config object to save
+ */
+function saveConfig(config) {
+  try {
+    if (!existsSync(CONFIG_DIR)) {
+      mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf-8');
+    logger.info(`Config saved to ${CONFIG_FILE}`);
+  } catch (error) {
+    logger.error(`Failed to save config: ${error.message}`);
+  }
+}
+
+/**
+ * Initialize EULA status from persisted config
+ */
+function initEulaStatus() {
+  if (eulaAccepted === null) {
+    const config = loadConfig();
+    eulaAccepted = config.eulaAccepted === true;
+    if (eulaAccepted) {
+      logger.info('EULA previously accepted, loaded from config');
+    }
+  }
+}
+
+/**
+ * Check if the EULA has been accepted
+ * @returns {boolean} True if EULA has been accepted
+ */
+export function isEulaAccepted() {
+  initEulaStatus();
+  return eulaAccepted;
+}
+
+/**
+ * Accept the EULA (persisted across sessions)
+ * @param {string} eulaUrl - The EULA URL being accepted
+ */
+export function acceptEula(eulaUrl) {
+  eulaAccepted = true;
+  const config = loadConfig();
+  config.eulaAccepted = true;
+  config.eulaAcceptedAt = new Date().toISOString();
+  config.eulaUrl = eulaUrl;
+  saveConfig(config);
+  logger.info(`EULA accepted and persisted (${eulaUrl})`);
+}
+
+/**
+ * Reset EULA acceptance (clears both memory and persisted state)
+ * @param {boolean} [persistReset=true] - Whether to also clear the persisted config
+ */
+export function resetEula(persistReset = true) {
+  eulaAccepted = false;
+  if (persistReset) {
+    const config = loadConfig();
+    delete config.eulaAccepted;
+    delete config.eulaAcceptedAt;
+    delete config.eulaUrl;
+    saveConfig(config);
+    logger.debug('EULA acceptance reset (memory and disk)');
+  } else {
+    logger.debug('EULA acceptance reset (memory only)');
+  }
+}
+
+/**
+ * Get EULA status summary
+ * @returns {{ accepted: boolean, acceptedAt: string|null, eulaUrl: string }} Current EULA status
+ */
+export function getEulaStatus() {
+  initEulaStatus();
+  const config = loadConfig();
+  return {
+    accepted: eulaAccepted,
+    acceptedAt: config.eulaAcceptedAt || null,
+    eulaUrl: EULA_URL
+  };
+}

package/src/core/logger.js

@@ -14,6 +14,14 @@ function info(message) {
   console.error(`${PREFIX} ${message}`);
 }
 
+/**
+ * Log a warning message
+ * @param {string} message - The message to log
+ */
+function warn(message) {
+  console.error(`${PREFIX} ⚠️ ${message}`);
+}
+
 /**
  * Log an error message
  * @param {string} message - The message to log
@@ -22,5 +30,13 @@ function error(message) {
   console.error(`${PREFIX} ❌ ${message}`);
 }
 
-export const logger = { info, error };
+/**
+ * Log a debug message
+ * @param {string} message - The message to log
+ */
+function debug(message) {
+  console.error(`${PREFIX} 🔍 ${message}`);
+}
+
+export const logger = { info, warn, error, debug };
 export default logger;

package/src/core/page.js

@@ -43,7 +43,7 @@ async function processQueue() {
     const queueLength = requestQueue.length;
     
     if (queueLength > 0) {
-      logger.info(`Queue: ${queueLength} requests waiting`);
+      logger.debug(`Queue: ${queueLength} requests waiting`);
     }
     
     try {
@@ -285,7 +285,7 @@ export async function waitForPageReady(page) {
   const spaCheck = await isItSPA(page);
   
   if (spaCheck.isSPA) {
-    logger.info(`SPA detected: ${spaCheck.indicators.join(', ')}`);
+    logger.debug(`SPA detected: ${spaCheck.indicators.join(', ')}`);
     
     // Wait for SPA to render
     await new Promise(resolve => setTimeout(resolve, 3000));
@@ -296,7 +296,7 @@ export async function waitForPageReady(page) {
     } catch {
       // OK if timeout - SPA might have websockets or long-polling
     }
-    logger.info('SPA content ready');
+    logger.debug('SPA content ready');
   } else {
     // For non-SPAs, just wait briefly for any pending network requests
     try {
@@ -314,17 +314,17 @@ export async function waitForPageReady(page) {
  * @returns {Promise<void>}
  */
 export async function waitForPageStability(page) {
-  logger.info('Waiting for page stability (network idle)...');
+  logger.debug('Waiting for page stability (network idle)...');
   
   // Give time for any triggered actions to complete
   await new Promise(resolve => setTimeout(resolve, 2000));
   
   try {
     await page.waitForNetworkIdle({ timeout: 5000 });
-    logger.info('Page stabilized');
+    logger.debug('Page stabilized');
   } catch {
     // Ignore timeout - page may have long-polling or websockets
-    logger.info('Network still active, continuing anyway');
+    logger.debug('Network still active, continuing anyway');
   }
 }
 

package/src/mcp-browser.js

@@ -16,6 +16,9 @@ import { dirname, join } from 'path';
 import { ErrorResponse } from './core/responses.js';
 import logger from './core/logger.js';
 
+// Import EULA functionality
+import { handleAcceptEula, ACCEPT_EULA_TOOL, requireEulaAcceptance } from './actions/accept-eula.js';
+
 // Import core functionality
 import { fetchPage, FETCH_WEBPAGE_TOOL } from './actions/fetch-page.js';
 import { clickElement, CLICK_ELEMENT_TOOL } from './actions/click-element.js';
@@ -47,7 +50,9 @@ async function main() {
   const server = new Server({ name: "MCP Browser", version: packageJson.version }, { capabilities: { tools: {} } });
 
   // Assemble tools from action imports
+  // ACCEPT_EULA_TOOL must be first - it's required before using other tools
   const tools = [
+    ACCEPT_EULA_TOOL,
     FETCH_WEBPAGE_TOOL,
     CLICK_ELEMENT_TOOL,
     TYPE_TEXT_TOOL,
@@ -66,7 +71,17 @@ async function main() {
     let result;
     
     try {
+      // EULA check - accept_eula is always allowed, other tools require EULA acceptance
+      if (name !== "accept_eula") {
+        const eulaResponse = requireEulaAcceptance(name);
+        if (eulaResponse) return eulaResponse;
+      }
+      
       switch (name) {
+        case "accept_eula":
+          result = await handleAcceptEula(safeArgs);
+          break;
+          
         case "fetch_webpage":
           result = await fetchPage(safeArgs);
           break;
@@ -144,7 +159,8 @@ export {
   closeTab,
   getCurrentHtml,
   takeScreenshot,
-  scrollPage
+  scrollPage,
+  handleAcceptEula
 };
 
 // Run the MCP server only if this is the main module (not imported for testing)