mcpbrowser 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "mcpName": "io.github.cherchyk/mcpbrowser",
   "type": "module",
   "description": "MCP browser server - fetch web pages using real Chrome/Edge browser. Handles authentication, SSO, CAPTCHAs, and anti-bot protection. Browser automation for AI assistants.",
@@ -12,7 +12,7 @@
     "mcp": "node src/mcp-browser.js",
     "test": "node tests/run-all.js",
     "test:unit": "node tests/run-unit.js",
-    "test:ci": "node tests/run-unit.js"
+    "test:descriptions": "node tests/tool-selection/run-tool-selection-tests.js"
   },
   "keywords": [
     "mcp",

package/src/actions/click-element.js

@@ -1,5 +1,5 @@
 /**
- * click.js - Click element action
+ * click-element.js - Click element action
  * 
  * This function handles two distinct use cases:
  * 
@@ -26,6 +26,105 @@
 
 import { getBrowser, domainPages } from '../core/browser.js';
 import { extractAndProcessHtml, waitForPageStability } from '../core/page.js';
+import { MCPResponse, ErrorResponse } from '../core/responses.js';
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+// ============================================================================
+// RESPONSE CLASS
+// ============================================================================
+
+/**
+ * Response for successful click_element operations
+ */
+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) {
+    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.currentUrl = currentUrl;
+    this.message = message;
+    this.html = html;
+  }
+
+  _getAdditionalFields() {
+    return {
+      currentUrl: this.currentUrl,
+      message: this.message,
+      html: this.html
+    };
+  }
+
+  getTextSummary() {
+    return this.message || "Element clicked successfully";
+  }
+}
+
+// ============================================================================
+// TOOL DEFINITION
+// ============================================================================
+
+/**
+ * @type {Tool}
+ */
+export const CLICK_ELEMENT_TOOL = {
+  name: "click_element",
+  title: "Click Element",
+  description: "**BROWSER INTERACTION** - Clicks elements on browser-loaded pages. Use this for navigation (clicking links/buttons), form submission, and any user interaction that requires clicking.\n\nWorks with any clickable element including buttons, links, or elements with onclick handlers. Can target by CSS selector or text content. Waits for page stability and returns updated HTML by default.\n\n**PREREQUISITE**: Page MUST be loaded with fetch_webpage first. This tool operates on an already-loaded page in the browser.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "The URL of the page (must match a previously fetched page)" },
+      selector: { type: "string", description: "CSS selector for the element to click (e.g., '#submit-btn', '.login-button')" },
+      text: { type: "string", description: "Text content to search for if selector is not provided (e.g., 'Sign In', 'Submit')" },
+      waitForElementTimeout: { type: "number", description: "Maximum time to wait for element in milliseconds", default: 1000 },
+      returnHtml: { type: "boolean", description: "Whether to wait for stability and return HTML after clicking. Set to false for fast form interactions (checkboxes, radio buttons).", default: true },
+      removeUnnecessaryHTML: { type: "boolean", description: "Remove Unnecessary HTML for size reduction by 90%. Only used when returnHtml is true.", default: true },
+      postClickWait: { type: "number", description: "Milliseconds to wait after click for SPAs to render dynamic content.", default: 1000 }
+    },
+    required: ["url"],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      currentUrl: { type: "string", description: "URL after click" },
+      message: { type: "string", description: "Success message" },
+      html: { 
+        type: ["string", "null"], 
+        description: "Page HTML if returnHtml was true, null otherwise" 
+      },
+      nextSteps: { 
+        type: "array", 
+        items: { type: "string" },
+        description: "Suggested next actions"
+      }
+    },
+    required: ["currentUrl", "message", "html", "nextSteps"],
+    additionalProperties: false
+  }
+};
+
+// ============================================================================
+// ACTION FUNCTION
+// ============================================================================
 
 /**
  * Click on an element on the page
@@ -73,10 +172,12 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
   let page = domainPages.get(hostname);
   
   if (!page || page.isClosed()) {
-    return {
-      success: false,
-      error: `No open page found for ${hostname}. Please fetch the page first using fetch_webpage.`
-    };
+    return new ErrorResponse(
+      `No open page found for ${hostname}. Please fetch the page first using fetch_webpage.`,
+      [
+        "Use fetch_webpage to load the page first"
+      ]
+    );
   }
 
   try {
@@ -113,10 +214,14 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
     }
 
     if (!elementHandle || !elementHandle.asElement()) {
-      return {
-        success: false,
-        error: selector ? `Element not found: ${selector}` : `Element with text "${text}" not found`
-      };
+      return new ErrorResponse(
+        selector ? `Element not found: ${selector}` : `Element with text "${text}" not found`,
+        [
+          "Use get_current_html to verify page content",
+          "Try a different selector or text",
+          "Check if the element is visible on the page"
+        ]
+      );
     }
 
     // Scroll element into view and click
@@ -142,13 +247,17 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       const currentUrl = page.url();
       const html = await extractAndProcessHtml(page, removeUnnecessaryHTML);
       
-      return {
-        success: true,
-        message: selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`,
+      return new ClickElementSuccessResponse(
         currentUrl,
+        selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`,
         html,
-        clicked: selector || `text:"${text}"`
-      };
+        [
+          "Use click_element again to navigate further",
+          "Use type_text to fill forms if needed",
+          "Use get_current_html to refresh page state",
+          "Use close_tab when finished"
+        ]
+      );
     } else {
       // Wait for page to stabilize even for fast clicks (ensures JS has finished)
       await waitForPageStability(page);
@@ -160,17 +269,25 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       
       const currentUrl = page.url();
       
-      return {
-        success: true,
-        message: selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`,
+      return new ClickElementSuccessResponse(
         currentUrl,
-        clicked: selector || `text:"${text}"`
-      };
+        selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`,
+        null,
+        [
+          "Use get_current_html to see updated page state",
+          "Use click_element or type_text for more interactions",
+          "Use close_tab when finished"
+        ]
+      );
     }
   } catch (err) {
-    return {
-      success: false,
-      error: `Failed to click element: ${err.message}`
-    };
+    return new ErrorResponse(
+      `Failed to click element: ${err.message}`,
+      [
+        "Use get_current_html to check current page state",
+        "Verify the selector or text is correct",
+        "Try fetch_webpage to reload if page is stale"
+      ]
+    );
   }
 }

package/src/actions/close-tab.js

@@ -1,8 +1,91 @@
 /**
- * Close a tab for a specific domain
+ * close-tab.js - Close a tab for a specific domain
  */
 
 import { domainPages } from '../core/browser.js';
+import { MCPResponse, ErrorResponse } from '../core/responses.js';
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+// ============================================================================
+// RESPONSE CLASS
+// ============================================================================
+
+/**
+ * Response for successful close_tab operations
+ */
+export class CloseTabSuccessResponse extends MCPResponse {
+  /**
+   * @param {string} message - Success message
+   * @param {string} hostname - Hostname that was closed
+   * @param {string[]} nextSteps - Suggested next actions
+   */
+  constructor(message, hostname, nextSteps) {
+    super(nextSteps);
+    
+    if (typeof message !== 'string') {
+      throw new TypeError('message must be a string');
+    }
+    if (typeof hostname !== 'string') {
+      throw new TypeError('hostname must be a string');
+    }
+    
+    this.message = message;
+    this.hostname = hostname;
+  }
+
+  _getAdditionalFields() {
+    return {
+      message: this.message,
+      hostname: this.hostname
+    };
+  }
+
+  getTextSummary() {
+    return this.message || `Closed tab for: ${this.hostname}`;
+  }
+}
+
+// ============================================================================
+// TOOL DEFINITION
+// ============================================================================
+
+/**
+ * @type {Tool}
+ */
+export const CLOSE_TAB_TOOL = {
+  name: "close_tab",
+  title: "Close Tab",
+  description: "**BROWSER MANAGEMENT** - Closes the browser tab for the given URL's hostname. This removes the page from the tab pool and forces a fresh session on the next visit to that hostname. Useful for memory management or when you need to clear session state. Note: Uses exact hostname match (www.example.com and example.com are treated as different tabs).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "The URL whose hostname tab should be closed" }
+    },
+    required: ["url"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      message: { type: "string", description: "Success message" },
+      hostname: { type: "string", description: "Hostname that was closed" },
+      nextSteps: { 
+        type: "array", 
+        items: { type: "string" },
+        description: "Suggested next actions"
+      }
+    },
+    required: ["message", "hostname", "nextSteps"],
+    additionalProperties: false
+  }
+};
+
+// ============================================================================
+// ACTION FUNCTION
+// ============================================================================
 
 /**
  * Closes the browser tab for the given URL's hostname and removes it from the tab pool.
@@ -15,10 +98,12 @@ export async function closeTab({ url }) {
   try {
     // Validate URL
     if (!url || typeof url !== 'string') {
-      return {
-        success: false,
-        error: 'Invalid or missing URL parameter'
-      };
+      return new ErrorResponse(
+        'Invalid or missing URL parameter',
+        [
+          "Provide a valid URL parameter"
+        ]
+      );
     }
 
     // Extract hostname from URL
@@ -26,10 +111,12 @@ export async function closeTab({ url }) {
     try {
       hostname = new URL(url).hostname;
     } catch {
-      return {
-        success: false,
-        error: 'Invalid URL format'
-      };
+      return new ErrorResponse(
+        'Invalid URL format',
+        [
+          "Provide a valid URL with protocol (e.g., https://example.com)"
+        ]
+      );
     }
     
     // Check if we have a tab for this hostname
@@ -50,12 +137,13 @@ export async function closeTab({ url }) {
       }
       
       if (!foundHostname) {
-        return {
-          success: true,
+        return new CloseTabSuccessResponse(
+          'No open tab found for this hostname',
           hostname,
-          message: 'No open tab found for this hostname',
-          alreadyClosed: true
-        };
+          [
+            "Use fetch_webpage to open a new page if needed"
+          ]
+        );
       }
       
       // Found the page by URL - use that hostname
@@ -68,12 +156,13 @@ export async function closeTab({ url }) {
     // Check if page is already closed
     if (page.isClosed()) {
       domainPages.delete(hostname);
-      return {
-        success: true,
+      return new CloseTabSuccessResponse(
+        'Tab was already closed',
         hostname,
-        message: 'Tab was already closed',
-        alreadyClosed: true
-      };
+        [
+          "Use fetch_webpage to open a new page if needed"
+        ]
+      );
     }
 
     // Close the page
@@ -84,17 +173,22 @@ export async function closeTab({ url }) {
     
     console.error(`[MCPBrowser] Closed tab for hostname: ${hostname}`);
     
-    return {
-      success: true,
+    return new CloseTabSuccessResponse(
+      `Successfully closed tab for ${hostname}`,
       hostname,
-      message: `Successfully closed tab for ${hostname}`
-    };
+      [
+        "Use fetch_webpage to open a new page if needed"
+      ]
+    );
     
   } catch (error) {
     console.error(`[MCPBrowser] Error closing tab:`, error);
-    return {
-      success: false,
-      error: error.message
-    };
+    return new ErrorResponse(
+      error.message,
+      [
+        "Check if the URL is correct",
+        "Verify a page exists for this hostname"
+      ]
+    );
   }
 }

package/src/actions/fetch-page.js

@@ -1,11 +1,96 @@
 /**
- * fetch.js - Main page fetching functionality
+ * fetch-page.js - Main page fetching functionality
  * Handles web page fetching with authentication flows and tab reuse
  */
 
 import { getBrowser, domainPages } from '../core/browser.js';
 import { getOrCreatePage, navigateToUrl, extractAndProcessHtml, waitForPageStability } from '../core/page.js';
 import { detectRedirectType, waitForAutoAuth, waitForManualAuth } from '../core/auth.js';
+import { MCPResponse, ErrorResponse } from '../core/responses.js';
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+// ============================================================================
+// RESPONSE CLASS
+// ============================================================================
+
+/**
+ * Response for successful fetch_webpage operations
+ */
+export class FetchPageSuccessResponse extends MCPResponse {
+  /**
+   * @param {string} currentUrl - Final URL after redirects
+   * @param {string} html - Page HTML content
+   * @param {string[]} nextSteps - Suggested next actions
+   */
+  constructor(currentUrl, html, nextSteps) {
+    super(nextSteps);
+    
+    if (typeof currentUrl !== 'string') {
+      throw new TypeError('currentUrl must be a string');
+    }
+    if (typeof html !== 'string') {
+      throw new TypeError('html must be a string');
+    }
+    
+    this.currentUrl = currentUrl;
+    this.html = html;
+  }
+
+  _getAdditionalFields() {
+    return {
+      currentUrl: this.currentUrl,
+      html: this.html
+    };
+  }
+
+  getTextSummary() {
+    return `Successfully fetched: ${this.currentUrl}`;
+  }
+}
+
+// ============================================================================
+// TOOL DEFINITION
+// ============================================================================
+
+/**
+ * @type {Tool}
+ */
+export const FETCH_WEBPAGE_TOOL = {
+  name: "fetch_webpage",
+  title: "Fetch Web Page",
+  description: "Fetches web pages using Chrome/Edge browser with full JavaScript rendering and authentication support. **REQUIRED for corporate/enterprise sites, any page requiring login/SSO, anti-bot/CAPTCHA pages, and JavaScript-heavy applications.** Use this as the DEFAULT for all webpage fetching - it handles simple HTML pages too. Opens browser for user authentication when needed. Never use generic HTTP fetch for pages that might require authentication.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "The URL to fetch" },
+      removeUnnecessaryHTML: { type: "boolean", description: "Remove Unnecessary HTML for size reduction by 90%.", default: true },
+      postLoadWait: { type: "number", description: "Milliseconds to wait after page load for SPAs to render dynamic content.", default: 1000 }
+    },
+    required: ["url"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      currentUrl: { type: "string", description: "Final URL after any redirects" },
+      html: { type: "string", description: "Page HTML content" },
+      nextSteps: { 
+        type: "array", 
+        items: { type: "string" },
+        description: "Suggested next actions"
+      }
+    },
+    required: ["currentUrl", "html", "nextSteps"],
+    additionalProperties: false
+  }
+};
+
+// ============================================================================
+// ACTION FUNCTION
+// ============================================================================
 
 /**
  * Fetch a web page using Chrome browser, with support for authentication flows and tab reuse.
@@ -19,16 +104,25 @@ import { detectRedirectType, waitForAutoAuth, waitForManualAuth } from '../core/
  * @returns {Promise<Object>} Result object with success status, URL, HTML content, or error details
  */
 export async function fetchPage({ url, removeUnnecessaryHTML = true, postLoadWait = 1000 }) {
+  // Handle missing URL with environment variable fallback
+  if (!url) {
+    const fallbackUrl = process.env.DEFAULT_FETCH_URL || process.env.MCP_DEFAULT_FETCH_URL;
+    if (fallbackUrl) {
+      url = fallbackUrl;
+    } else {
+      return new ErrorResponse(
+        "Missing url parameter and no DEFAULT_FETCH_URL/MCP_DEFAULT_FETCH_URL configured",
+        ["Set DEFAULT_FETCH_URL or MCP_DEFAULT_FETCH_URL environment variable", "Provide url parameter in the request"]
+      );
+    }
+  }
+  
   // Hardcoded smart defaults - use 'domcontentloaded' for fastest loading
   // (waits for HTML parsed, not all resources loaded - much faster for SPAs)
   const waitUntil = "domcontentloaded";
   const navigationTimeout = 30000;
   const authCompletionTimeout = 600000;
   const reuseLastKeptPage = true;
-  
-  if (!url) {
-    throw new Error("url parameter is required");
-  }
 
   // Parse hostname for domain-based tab reuse
   let hostname;
@@ -88,12 +182,14 @@ export async function fetchPage({ url, removeUnnecessaryHTML = true, postLoadWai
         const manualAuthResult = await waitForManualAuth(page, redirectInfo.hostname, redirectInfo.originalBase, authCompletionTimeout);
         
         if (!manualAuthResult.success) {
-          return { 
-            success: false, 
-            error: manualAuthResult.error, 
-            pageKeptOpen: true, 
-            hint: manualAuthResult.hint 
-          };
+          return new ErrorResponse(
+            manualAuthResult.error,
+            [
+              "Complete authentication in the browser window",
+              "Call fetch_webpage again with the same URL to retry",
+              "Use close_tab to reset the session if authentication fails"
+            ]
+          );
         }
         
         // Update hostname if changed
@@ -116,14 +212,25 @@ export async function fetchPage({ url, removeUnnecessaryHTML = true, postLoadWai
     // Extract and process HTML
     const processedHtml = await extractAndProcessHtml(page, removeUnnecessaryHTML);
     
-    return { 
-      success: true, 
-      currentUrl: page.url(),
-      html: processedHtml
-    };
+    return new FetchPageSuccessResponse(
+      page.url(),
+      processedHtml,
+      [
+        "Use click_element to interact with buttons/links on the page",
+        "Use type_text to fill in form fields",
+        "Use get_current_html to re-check page state after interactions",
+        "Use close_tab when finished to free browser resources"
+      ]
+    );
   } catch (err) {
-    const hint = "Tab is left open. Complete sign-in there, then call fetch_webpage again with just the URL.";
-    return { success: false, error: err.message || String(err), pageKeptOpen: true, hint };
+    return new ErrorResponse(
+      err.message || String(err),
+      [
+        "Complete authentication in the browser if prompted",
+        "Call fetch_webpage again with the same URL to retry",
+        "Use close_tab to reset the session if needed"
+      ]
+    );
   } finally {
     // Tab always stays open - domain-aware reuse handles cleanup
   }