mcpbrowser 0.3.34 → 0.3.36

package/package.json

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

@@ -28,6 +28,7 @@ import { getBrowser, getValidatedPage } from '../core/browser.js';
 import { extractAndProcessHtml, waitForPageReady } 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';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -37,7 +38,7 @@ import logger from '../core/logger.js';
  * Structured response for click_element with JS fallback metadata
  */
 export class ClickWithFallbackResponse extends MCPResponse {
-  constructor({ status, fallbackUsed = false, nativeAttempt, fallbackAttempt, postClickWait, currentUrl, html = null, message, nextSteps = [] }) {
+  constructor({ status, fallbackUsed = false, nativeAttempt, fallbackAttempt, postClickWait, currentUrl, html = null, message, nextSteps = [], recommendedPlugins = [] }) {
     super(nextSteps);
     this.status = status;
     this.fallbackUsed = fallbackUsed;
@@ -47,6 +48,7 @@ export class ClickWithFallbackResponse extends MCPResponse {
     this.currentUrl = currentUrl;
     this.html = html;
     this.message = message;
+    this.recommendedPlugins = recommendedPlugins;
   }
 
   _getAdditionalFields() {
@@ -58,7 +60,8 @@ export class ClickWithFallbackResponse extends MCPResponse {
       postClickWait: this.postClickWait,
       currentUrl: this.currentUrl,
       html: this.html,
-      message: this.message
+      message: this.message,
+      recommendedPlugins: this.recommendedPlugins
     };
   }
 
@@ -328,6 +331,7 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
 
     const nextSteps = returnHtml
       ? [
+          ...(html ? getPluginNextSteps(currentUrl, html) : []),
           "Use MCPBrowser's click_element again to navigate further",
           "Use MCPBrowser's type_text to fill forms if needed",
           "Use MCPBrowser's get_current_html to refresh page state",
@@ -352,7 +356,8 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       currentUrl,
       html,
       message,
-      nextSteps
+      nextSteps,
+      recommendedPlugins: html ? getRecommendedPlugins(currentUrl, html) : []
     });
   } catch (err) {
     logger.error(`click_element failed: ${err.message}`);

package/src/actions/execute-javascript.js

@@ -7,6 +7,7 @@ import { waitForPageReady } from '../core/page.js';
 import { MCPResponse, InformationalResponse } from '../core/responses.js';
 import logger from '../core/logger.js';
 import { serializeExecutionResult } from '../utils.js';
+import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
 
 // Shared execution defaults for script actions
 export const EXECUTION_TIMEOUT_DEFAULT_MS = 30_000;
@@ -21,7 +22,7 @@ export const EXECUTION_RESULT_MAX_BYTES = 100_000;
  * Structured response for execute_javascript action
  */
 export class ExecuteJavascriptResponse extends MCPResponse {
-  constructor({ result, type, executionTimeMs, truncated = false, urlChanged = false, currentUrl = '', error = null, nextSteps = [] }) {
+  constructor({ result, type, executionTimeMs, truncated = false, urlChanged = false, currentUrl = '', error = null, nextSteps = [], recommendedPlugins = [] }) {
     super(nextSteps);
 
     this.result = result;
@@ -31,6 +32,7 @@ export class ExecuteJavascriptResponse extends MCPResponse {
     this.urlChanged = urlChanged;
     this.currentUrl = currentUrl;
     this.error = error;
+    this.recommendedPlugins = recommendedPlugins;
   }
 
   _getAdditionalFields() {
@@ -41,7 +43,8 @@ export class ExecuteJavascriptResponse extends MCPResponse {
       truncated: this.truncated,
       urlChanged: this.urlChanged,
       currentUrl: this.currentUrl,
-      error: this.error || undefined
+      error: this.error || undefined,
+      recommendedPlugins: this.recommendedPlugins
     };
   }
 
@@ -223,10 +226,12 @@ export async function executeJavascript({ url, script, timeoutMs = EXECUTION_TIM
     urlChanged,
     currentUrl,
     nextSteps: [
+      ...getPluginNextSteps(currentUrl, ''),
       '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'
-    ]
+    ],
+    recommendedPlugins: getRecommendedPlugins(currentUrl, '')
   });
 }
 

package/src/actions/fetch-page.js

@@ -8,6 +8,7 @@ import { getOrCreatePage, queueRequest, navigateToUrl, waitForPageReady, extract
 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';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -25,8 +26,9 @@ export class FetchPageSuccessResponse extends MCPResponse {
    * @param {string} currentUrl - Final URL after redirects
    * @param {string} html - Page HTML content
    * @param {string[]} nextSteps - Suggested next actions
+   * @param {Array} [recommendedPlugins] - Detected plugin metadata
    */
-  constructor(currentUrl, html, nextSteps) {
+  constructor(currentUrl, html, nextSteps, recommendedPlugins = []) {
     super(nextSteps);
     
     if (typeof currentUrl !== 'string') {
@@ -38,12 +40,14 @@ export class FetchPageSuccessResponse extends MCPResponse {
     
     this.currentUrl = currentUrl;
     this.html = html;
+    this.recommendedPlugins = recommendedPlugins;
   }
 
   _getAdditionalFields() {
     return {
       currentUrl: this.currentUrl,
-      html: this.html
+      html: this.html,
+      recommendedPlugins: this.recommendedPlugins
     };
   }
 
@@ -220,12 +224,14 @@ async function doFetchPage({ url, browser, removeUnnecessaryHTML, postLoadWait }
       page.url(),
       processedHtml,
       [
+        ...getPluginNextSteps(page.url(), processedHtml),
         "Use MCPBrowser's click_element to interact with buttons/links on the page",
         "Use MCPBrowser's type_text to fill in form fields",
         "Use MCPBrowser's get_current_html to re-check page state after interactions",
         "Use MCPBrowser's take_screenshot if page has charts, images, or complex visual layout that's hard to understand from HTML",
         "Use MCPBrowser's close_tab when finished to free browser resources"
-      ]
+      ],
+      getRecommendedPlugins(page.url(), processedHtml)
     );
   } catch (err) {
     logger.error(`fetch_webpage failed: ${err.message || String(err)}`);

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

@@ -6,6 +6,7 @@ import { getBrowser, getValidatedPage } from '../core/browser.js';
 import { extractAndProcessHtml } 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';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -23,8 +24,9 @@ export class GetCurrentHtmlSuccessResponse extends MCPResponse {
    * @param {string} currentUrl - Current page URL
    * @param {string} html - Page HTML content
    * @param {string[]} nextSteps - Suggested next actions
+   * @param {Array} [recommendedPlugins] - Detected plugin metadata
    */
-  constructor(currentUrl, html, nextSteps) {
+  constructor(currentUrl, html, nextSteps, recommendedPlugins = []) {
     super(nextSteps);
     
     if (typeof currentUrl !== 'string') {
@@ -36,12 +38,14 @@ export class GetCurrentHtmlSuccessResponse extends MCPResponse {
     
     this.currentUrl = currentUrl;
     this.html = html;
+    this.recommendedPlugins = recommendedPlugins;
   }
 
   _getAdditionalFields() {
     return {
       currentUrl: this.currentUrl,
-      html: this.html
+      html: this.html,
+      recommendedPlugins: this.recommendedPlugins
     };
   }
 
@@ -157,11 +161,13 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
       currentUrl,
       html,
       [
+        ...getPluginNextSteps(currentUrl, html),
         "Use MCPBrowser's click_element to interact with elements",
         "Use MCPBrowser's type_text to fill forms",
         "Use MCPBrowser's take_screenshot if page layout or visual content is hard to understand from HTML",
         "Use MCPBrowser's close_tab to free resources when done"
-      ]
+      ],
+      getRecommendedPlugins(currentUrl, html)
     );
   } catch (err) {
     logger.error(`get_current_html failed: ${err.message}`);

package/src/actions/plugin-action.js

@@ -0,0 +1,180 @@
+/**
+ * plugin-action.js — MCP tool that dispatches to a plugin's action.
+ * Looks up the plugin by name, finds the action, provides the browser
+ * page object, and calls the action's execute function.
+ * Part of the plugin dispatch pair (plugin_info + plugin_action).
+ */
+
+import { MCPResponse, ErrorResponse } from '../core/responses.js';
+import { getLoadedPlugins, getPlugin } from '../core/plugin-loader.js';
+import { getBrowser, getValidatedPage } from '../core/browser.js';
+import logger from '../core/logger.js';
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+// ============================================================================
+// RESPONSE CLASS
+// ============================================================================
+
+/** Response wrapping a plugin action's raw result */
+export class PluginActionSuccessResponse extends MCPResponse {
+  constructor(pluginName, actionName, data, nextSteps) {
+    super(nextSteps);
+    this.pluginName = pluginName;
+    this.actionName = actionName;
+    this.data = data;
+  }
+  _getAdditionalFields() { return { pluginName: this.pluginName, actionName: this.actionName, data: this.data }; }
+  getTextSummary() { return `Plugin "${this.pluginName}" action "${this.actionName}" completed`; }
+}
+
+// ============================================================================
+// TOOL DEFINITION
+// ============================================================================
+
+/** @type {Tool} */
+export const PLUGIN_ACTION_TOOL = {
+  name: "plugin_action",
+  title: "Plugin Action",
+  description: "Execute a site-specific plugin action. Use plugin_info first to discover available actions and their parameters. Plugins provide specialized automation for UI-heavy websites like Gmail, Outlook, PowerBI, AWS, and Azure — faster and more reliable than generic DOM interaction.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      plugin: {
+        type: "string",
+        description: "Plugin name (e.g., 'gmail', 'outlook', 'powerbi')"
+      },
+      action: {
+        type: "string",
+        description: "Action name within the plugin (e.g., 'list_emails', 'extract_grid')"
+      },
+      params: {
+        type: "object",
+        description: "Action parameters. Use plugin_info to discover accepted parameters.",
+        additionalProperties: true
+      }
+    },
+    required: ["plugin", "action"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      nextSteps: {
+        type: "array",
+        items: { type: "string" },
+        description: "Suggested next actions"
+      }
+    },
+    required: ["nextSteps"],
+    additionalProperties: true
+  }
+};
+
+// ============================================================================
+// ACTION FUNCTION
+// ============================================================================
+
+/**
+ * Dispatch to a plugin action.
+ * @param {Object} params
+ * @param {string} params.plugin - Plugin name
+ * @param {string} params.action - Action name within the plugin
+ * @param {Object} [params.params] - Action parameters
+ * @returns {Promise<MCPResponse>}
+ */
+export async function pluginAction({ plugin: pluginName, action: actionName, params = {} }) {
+  logger.info(`plugin_action called: plugin=${pluginName} action=${actionName}`);
+
+  const loadedPlugins = getLoadedPlugins();
+
+  // Validate plugin exists
+  const pluginInstance = getPlugin(pluginName);
+  if (!pluginInstance) {
+    const available = [...loadedPlugins.keys()].join(', ') || '(none)';
+    return new ErrorResponse(
+      `Unknown plugin: '${pluginName}'. Available plugins: ${available}`,
+      ["Call plugin_info() to list all loaded plugins"]
+    );
+  }
+
+  // Validate action exists
+  const actions = pluginInstance.getActions();
+  const actionDef = actions.find(a => a.name === actionName);
+  if (!actionDef) {
+    const validActions = actions.map(a => a.name).join(', ');
+    return new ErrorResponse(
+      `Unknown action '${actionName}' for plugin '${pluginName}'. Available actions: ${validActions}`,
+      [`Call plugin_info({ plugin: '${pluginName}' }) to see all available actions and their parameters`]
+    );
+  }
+
+  // Get browser page — check if on correct domain (US5/T032)
+  let page;
+  try {
+    // Try to get a validated page for any of the plugin's URL patterns
+    const browser = await getBrowser();
+    const pages = await browser.pages();
+    
+    // Find a page matching any of the plugin's URL patterns
+    let matchedPage = null;
+    for (const p of pages) {
+      try {
+        const pageUrl = p.url();
+        for (const pattern of pluginInstance.manifest.urlPatterns) {
+          if (pageUrl.includes(pattern)) {
+            matchedPage = p;
+            break;
+          }
+        }
+        if (matchedPage) break;
+      } catch { /* skip closed/errored pages */ }
+    }
+
+    if (!matchedPage) {
+      const targetPatterns = pluginInstance.manifest.urlPatterns.join(', ');
+      return new ErrorResponse(
+        `Plugin '${pluginName}' requires ${targetPatterns} but no matching page is open. Use fetch_webpage to navigate to the correct site first.`,
+        [`Use MCPBrowser's fetch_webpage to navigate to a page matching: ${targetPatterns}`, `Then retry plugin_action`]
+      );
+    }
+    
+    page = matchedPage;
+  } catch (err) {
+    logger.error(`plugin_action: browser error — ${err.message}`);
+    return new ErrorResponse(
+      `Browser connection failed: ${err.message}`,
+      ["Ensure the browser is running with remote debugging enabled", "Retry plugin_action after browser is connected"]
+    );
+  }
+
+  // Execute the action
+  try {
+    const result = await actionDef.execute({ page, params });
+    
+    // If result is already an MCPResponse subclass, return it directly
+    if (result && typeof result.toMcpFormat === 'function') {
+      return result;
+    }
+    
+    // Wrap raw results
+    return new PluginActionSuccessResponse(
+      pluginName,
+      actionName,
+      result,
+      [`Use plugin_info({ plugin: '${pluginName}' }) to see other available actions`]
+    );
+  } catch (err) {
+    logger.error(`plugin_action: "${pluginName}/${actionName}" failed — ${err.message}`);
+    return new ErrorResponse(
+      `Plugin '${pluginName}' action '${actionName}' failed: ${err.message}. The site structure may have changed. You can fall back to generic MCPBrowser tools (click_element, get_current_html).`,
+      [
+        "Check if the page is on the correct site",
+        "Try MCPBrowser's get_current_html to inspect the page state",
+        "Use generic MCPBrowser tools as a fallback"
+      ]
+    );
+  }
+}

package/src/actions/plugin-info.js

@@ -0,0 +1,170 @@
+/**
+ * plugin-info.js — MCP tool that returns information about installed plugins,
+ * their available actions, parameters, and high-level site context.
+ * Part of the plugin dispatch pair (plugin_info + plugin_action).
+ */
+
+import { MCPResponse, ErrorResponse } from '../core/responses.js';
+import { getLoadedPlugins, getPlugin } from '../core/plugin-loader.js';
+import logger from '../core/logger.js';
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+// ============================================================================
+// RESPONSE CLASSES
+// ============================================================================
+
+/** Response listing all loaded plugins */
+export class PluginListResponse extends MCPResponse {
+  constructor(plugins, nextSteps) {
+    super(nextSteps);
+    this.plugins = plugins;
+  }
+  _getAdditionalFields() { return { plugins: this.plugins }; }
+  getTextSummary() { return `${this.plugins.length} plugin(s) loaded`; }
+}
+
+/** Response with plugin detail (action catalog + site context) */
+export class PluginInfoResponse extends MCPResponse {
+  constructor(info, nextSteps) {
+    super(nextSteps);
+    this.pluginInfo = info;
+  }
+  _getAdditionalFields() { return { ...this.pluginInfo }; }
+  getTextSummary() { return `Plugin "${this.pluginInfo.name}": ${this.pluginInfo.actions?.length || 0} action(s)`; }
+}
+
+/** Response with single action detail */
+export class PluginActionDetailResponse extends MCPResponse {
+  constructor(plugin, action, nextSteps) {
+    super(nextSteps);
+    this.plugin = plugin;
+    this.action = action;
+  }
+  _getAdditionalFields() { return { plugin: this.plugin, action: this.action }; }
+  getTextSummary() { return `Action "${this.action.name}" from plugin "${this.plugin}"`; }
+}
+
+// ============================================================================
+// TOOL DEFINITION
+// ============================================================================
+
+/** @type {Tool} */
+export const PLUGIN_INFO_TOOL = {
+  name: "plugin_info",
+  title: "Plugin Info",
+  description: "Get information about an installed site plugin — its available actions, parameters, and site context. Call this after a plugin is detected (recommended in nextSteps) to discover what actions you can perform via plugin_action. You can also call with no arguments to list all loaded plugins.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      plugin: {
+        type: "string",
+        description: "Plugin name to get info for. Omit to list all loaded plugins."
+      },
+      action: {
+        type: "string",
+        description: "Optional. Specific action name to get detailed info for."
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      nextSteps: {
+        type: "array",
+        items: { type: "string" },
+        description: "Suggested next actions"
+      }
+    },
+    required: ["nextSteps"],
+    additionalProperties: true
+  }
+};
+
+// ============================================================================
+// ACTION FUNCTION
+// ============================================================================
+
+/**
+ * Get plugin information — list all plugins, plugin detail, or action detail.
+ * @param {Object} params
+ * @param {string} [params.plugin] - Plugin name (omit to list all)
+ * @param {string} [params.action] - Action name (requires plugin)
+ * @returns {MCPResponse}
+ */
+export function pluginInfo({ plugin, action } = {}) {
+  logger.info(`plugin_info called: plugin=${plugin || '(all)'} action=${action || '(all)'}`);
+
+  const loadedPlugins = getLoadedPlugins();
+
+  // Mode 1: List all plugins
+  if (!plugin) {
+    const plugins = [];
+    for (const [name, p] of loadedPlugins) {
+      plugins.push({
+        name,
+        description: p.manifest.description,
+        actionCount: p.getActions().length
+      });
+    }
+
+    const nextSteps = plugins.length > 0
+      ? plugins.map(p => `Call plugin_info({ plugin: '${p.name}' }) to see ${p.name}'s available actions`)
+      : ["No plugins are currently loaded. Add plugin names to plugins.json and restart the server."];
+
+    return new PluginListResponse(plugins, nextSteps);
+  }
+
+  // Validate plugin exists
+  const pluginInstance = getPlugin(plugin);
+  if (!pluginInstance) {
+    const available = [...loadedPlugins.keys()].join(', ') || '(none)';
+    return new ErrorResponse(
+      `Unknown plugin: '${plugin}'. Available plugins: ${available}`,
+      loadedPlugins.size > 0
+        ? [`Call plugin_info() with no arguments to list all plugins`]
+        : ["No plugins are currently loaded. Add plugin names to plugins.json and restart the server."]
+    );
+  }
+
+  // Mode 3: Single action detail
+  if (action) {
+    const actions = pluginInstance.getActions();
+    const actionDef = actions.find(a => a.name === action);
+    if (!actionDef) {
+      const validActions = actions.map(a => a.name).join(', ');
+      return new ErrorResponse(
+        `Unknown action '${action}' for plugin '${plugin}'. Available actions: ${validActions}`,
+        [`Call plugin_info({ plugin: '${plugin}' }) to see all available actions`]
+      );
+    }
+
+    return new PluginActionDetailResponse(
+      plugin,
+      { name: actionDef.name, description: actionDef.description, params: actionDef.params },
+      [`Call plugin_action({ plugin: '${plugin}', action: '${action}', params: { ... } })`]
+    );
+  }
+
+  // Mode 2: Plugin detail with full action catalog
+  const info = pluginInstance.getInfo();
+  const pluginDetail = {
+    name: plugin,
+    description: info.description,
+    targetPages: info.targetPages,
+    ...(info.authFlow ? { authFlow: info.authFlow } : {}),
+    actions: info.actions || []
+  };
+
+  const nextSteps = [
+    ...(info.actions || []).slice(0, 3).map(a =>
+      `Use plugin_action({ plugin: '${plugin}', action: '${a.name}' }) to ${a.description.toLowerCase()}`
+    ),
+    "Use fetch_webpage to navigate to the target site first if not already there"
+  ];
+
+  return new PluginInfoResponse(pluginDetail, nextSteps);
+}

package/src/core/logger.js

@@ -38,13 +38,9 @@ async function notifyAgent(level, data) {
     // Skip if client requested a higher threshold.
     if (mcpServer.isMessageIgnored?.(level)) return;
     await mcpServer.sendLoggingMessage({ level, logger: 'mcpbrowser', data });
-  } catch (err) {
-    // Fall back to stderr without recursing through logger.
-    try {
-      process.stderr.write(`${PREFIX} logging notification failed: ${err?.message || err}\n`);
-    } catch (_) {
-      /* ignore */
-    }
+  } catch {
+    // Silently drop — this is expected during startup before the MCP
+    // transport handshake completes. Stderr already has the message.
   }
 }