mcpbrowser 0.3.33 → 0.3.35

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.
   }
 }
 

package/src/core/plugin-loader.js

@@ -0,0 +1,323 @@
+/**
+ * plugin-loader.js — Core plugin infrastructure for MCPBrowser.
+ * Reads the plugin registry, validates manifests, dynamically loads plugins,
+ * and provides detection/accessor functions for dispatch tools.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import logger from './logger.js';
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** Current plugin interface version. Plugins must match this exactly. */
+export const CURRENT_INTERFACE_VERSION = 1;
+
+/** @type {Map<string, object>} Loaded plugin instances keyed by name */
+const loadedPlugins = new Map();
+
+// ============================================================================
+// REGISTRY
+// ============================================================================
+
+/**
+ * Resolve the path to plugins.json relative to this module's package root.
+ * @returns {string} Absolute path to plugins.json
+ */
+function getRegistryPath() {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  return join(__dirname, '../plugins.json');
+}
+
+/**
+ * Resolve the path to the plugins/ directory.
+ * @returns {string} Absolute path to plugins/
+ */
+function getPluginsDir() {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  return join(__dirname, '../plugins');
+}
+
+/**
+ * Read and parse the plugin registry file.
+ * @returns {{ enabled: string[] }} Registry data with enabled plugin names
+ */
+export function readRegistry() {
+  const registryPath = getRegistryPath();
+  
+  if (!existsSync(registryPath)) {
+    logger.debug('plugins.json not found — no plugins to load');
+    return { enabled: [] };
+  }
+
+  try {
+    const raw = readFileSync(registryPath, 'utf-8');
+    const data = JSON.parse(raw);
+    
+    if (!data || !Array.isArray(data.enabled)) {
+      logger.warn('plugins.json: "enabled" must be an array — no plugins loaded');
+      return { enabled: [] };
+    }
+    
+    return { enabled: data.enabled.filter(name => typeof name === 'string' && name.length > 0) };
+  } catch (err) {
+    logger.warn(`plugins.json: failed to parse — ${err.message}`);
+    return { enabled: [] };
+  }
+}
+
+// ============================================================================
+// VALIDATION
+// ============================================================================
+
+/**
+ * Validate a plugin manifest against required fields and interface version.
+ * @param {object} manifest - Plugin manifest object
+ * @param {string} folderName - Expected folder name for the plugin
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export function validateManifest(manifest, folderName) {
+  if (!manifest || typeof manifest !== 'object') {
+    return { valid: false, reason: 'manifest is missing or not an object' };
+  }
+
+  const required = ['name', 'version', 'description', 'interfaceVersion', 'urlPatterns'];
+  for (const field of required) {
+    if (manifest[field] === undefined || manifest[field] === null || manifest[field] === '') {
+      return { valid: false, reason: `missing required field: ${field}` };
+    }
+  }
+
+  if (typeof manifest.name !== 'string') {
+    return { valid: false, reason: 'name must be a string' };
+  }
+  if (typeof manifest.version !== 'string') {
+    return { valid: false, reason: 'version must be a string' };
+  }
+  if (typeof manifest.description !== 'string') {
+    return { valid: false, reason: 'description must be a string' };
+  }
+  if (typeof manifest.interfaceVersion !== 'number' || !Number.isInteger(manifest.interfaceVersion)) {
+    return { valid: false, reason: 'interfaceVersion must be an integer' };
+  }
+  if (!Array.isArray(manifest.urlPatterns) || manifest.urlPatterns.length === 0) {
+    return { valid: false, reason: 'urlPatterns must be a non-empty array' };
+  }
+
+  if (manifest.name !== folderName) {
+    return { valid: false, reason: `manifest name "${manifest.name}" does not match folder name "${folderName}"` };
+  }
+
+  if (manifest.interfaceVersion !== CURRENT_INTERFACE_VERSION) {
+    return { valid: false, reason: `interfaceVersion ${manifest.interfaceVersion} is not compatible (expected ${CURRENT_INTERFACE_VERSION})` };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate that a plugin module has all required exports.
+ * @param {object} mod - Imported module namespace
+ * @param {string} pluginName - Plugin name for logging
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+function validateExports(mod, pluginName) {
+  if (typeof mod.matchesPage !== 'function') {
+    return { valid: false, reason: 'missing required export: matchesPage (function)' };
+  }
+  if (typeof mod.getActions !== 'function') {
+    return { valid: false, reason: 'missing required export: getActions (function)' };
+  }
+  if (typeof mod.getInfo !== 'function') {
+    return { valid: false, reason: 'missing required export: getInfo (function)' };
+  }
+  
+  // Validate getActions returns non-empty array with required fields
+  try {
+    const actions = mod.getActions();
+    if (!Array.isArray(actions) || actions.length === 0) {
+      return { valid: false, reason: 'getActions() must return a non-empty array' };
+    }
+    
+    const actionNames = new Set();
+    for (const action of actions) {
+      if (!action.name || !action.description || !Array.isArray(action.params) || typeof action.execute !== 'function') {
+        return { valid: false, reason: `action "${action.name || '?'}" is missing required fields (name, description, params, execute)` };
+      }
+      if (actionNames.has(action.name)) {
+        return { valid: false, reason: `duplicate action name "${action.name}" — action names must be unique within a plugin` };
+      }
+      actionNames.add(action.name);
+    }
+  } catch (err) {
+    return { valid: false, reason: `getActions() threw: ${err.message}` };
+  }
+
+  return { valid: true };
+}
+
+// ============================================================================
+// LOADING
+// ============================================================================
+
+/**
+ * Load all enabled plugins from the registry.
+ * Reads plugins.json, dynamically imports each plugin, validates manifest
+ * and exports, and stores valid plugins in the loaded map.
+ * @returns {Promise<number>} Number of successfully loaded plugins
+ */
+export async function loadPlugins() {
+  loadedPlugins.clear();
+  
+  const registry = readRegistry();
+  if (registry.enabled.length === 0) {
+    logger.debug('No plugins enabled in registry');
+    return 0;
+  }
+
+  const pluginsDir = getPluginsDir();
+  
+  // Check for duplicate names in registry
+  const seen = new Set();
+  const uniqueEnabled = [];
+  for (const name of registry.enabled) {
+    if (seen.has(name)) {
+      logger.warn(`Plugin "${name}" is listed multiple times in registry — skipping duplicate`);
+      continue;
+    }
+    seen.add(name);
+    uniqueEnabled.push(name);
+  }
+
+  for (const pluginName of uniqueEnabled) {
+    const pluginDir = join(pluginsDir, pluginName);
+    const entryPoint = join(pluginDir, 'index.js');
+
+    if (!existsSync(entryPoint)) {
+      logger.warn(`Plugin "${pluginName}": entry point not found at ${entryPoint} — skipping`);
+      continue;
+    }
+
+    try {
+      const moduleUrl = pathToFileURL(resolve(entryPoint)).href;
+      const mod = await import(moduleUrl);
+
+      // Validate manifest
+      const manifestCheck = validateManifest(mod.manifest, pluginName);
+      if (!manifestCheck.valid) {
+        logger.warn(`Plugin "${pluginName}": invalid manifest — ${manifestCheck.reason} — skipping`);
+        continue;
+      }
+
+      // Validate exports
+      const exportsCheck = validateExports(mod, pluginName);
+      if (!exportsCheck.valid) {
+        logger.warn(`Plugin "${pluginName}": invalid exports — ${exportsCheck.reason} — skipping`);
+        continue;
+      }
+
+      // Store the loaded plugin
+      loadedPlugins.set(pluginName, {
+        manifest: mod.manifest,
+        matchesPage: mod.matchesPage,
+        getActions: mod.getActions,
+        getInfo: mod.getInfo
+      });
+
+      logger.info(`Plugin "${pluginName}" v${mod.manifest.version} loaded (${mod.getActions().length} actions)`);
+    } catch (err) {
+      logger.warn(`Plugin "${pluginName}": failed to load — ${err.message} — skipping`);
+    }
+  }
+
+  logger.info(`Plugin loader: ${loadedPlugins.size} plugin(s) loaded`);
+  return loadedPlugins.size;
+}
+
+// ============================================================================
+// DETECTION
+// ============================================================================
+
+/**
+ * Detect which loaded plugins match the given page URL and HTML.
+ * URL patterns are checked first (fast path), then DOM patterns if defined.
+ * @param {string} url - Current page URL
+ * @param {string} html - Extracted page HTML
+ * @returns {Array<{ pluginName: string, confidence: number, nextSteps: string[] }>}
+ */
+export function detectPlugins(url, html) {
+  if (loadedPlugins.size === 0) return [];
+  
+  const results = [];
+  
+  for (const [name, plugin] of loadedPlugins) {
+    try {
+      const match = plugin.matchesPage(url, html);
+      if (match && match.matched) {
+        const confidence = typeof match.confidence === 'number' ? match.confidence : 1.0;
+        
+        // Build nextSteps from plugin info
+        const info = plugin.getInfo();
+        const topActions = (info.actions || []).slice(0, 3);
+        const actionSummary = topActions.map(a => a.name).join(', ');
+        
+        const nextSteps = [
+          `Plugin "${name}" detected — use plugin_info({ plugin: '${name}' }) to see all available actions`,
+          ...(actionSummary ? [`Top actions: ${actionSummary}. Use plugin_action({ plugin: '${name}', action: '<name>' }) to execute`] : [])
+        ];
+        
+        results.push({ pluginName: name, confidence, nextSteps });
+      }
+    } catch (err) {
+      // Detection must not throw — skip this plugin silently
+      logger.debug(`Plugin "${name}" detection error: ${err.message}`);
+    }
+  }
+  
+  // Sort by confidence descending
+  results.sort((a, b) => b.confidence - a.confidence);
+  return results;
+}
+
+/**
+ * Convert detection results into a flat nextSteps string array for response augmentation.
+ * @param {string} url - Current page URL
+ * @param {string} html - Extracted page HTML
+ * @returns {string[]} Array of nextSteps strings from matching plugins
+ */
+export function getPluginNextSteps(url, html) {
+  const detections = detectPlugins(url, html);
+  const steps = [];
+  for (const d of detections) {
+    steps.push(...d.nextSteps);
+  }
+  return steps;
+}
+
+// ============================================================================
+// ACCESSORS
+// ============================================================================
+
+/**
+ * Get the map of all loaded plugins.
+ * @returns {Map<string, object>}
+ */
+export function getLoadedPlugins() {
+  return loadedPlugins;
+}
+
+/**
+ * Get a specific loaded plugin by name.
+ * @param {string} name - Plugin name
+ * @returns {object|undefined} Plugin instance or undefined
+ */
+export function getPlugin(name) {
+  return loadedPlugins.get(name);
+}

package/src/mcp-browser.js

@@ -28,6 +28,11 @@ import { getCurrentHtml, GET_CURRENT_HTML_TOOL } from './actions/get-current-htm
 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 plugin dispatch tools
+import { pluginAction, PLUGIN_ACTION_TOOL } from './actions/plugin-action.js';
+import { pluginInfo, PLUGIN_INFO_TOOL } from './actions/plugin-info.js';
 
 // Import functions for testing exports
 import { getBrowser, closeBrowser } from './core/browser.js';
@@ -36,6 +41,9 @@ import { isLikelyAuthUrl, waitForAuth, pollUntilAuthDone, detectLoginPage } from
 import { cleanHtml, enrichHtml, prepareHtml } from './core/html.js';
 import { getBaseDomain } from './utils.js';
 
+// Import plugin system
+import { loadPlugins, getLoadedPlugins, getPlugin, detectPlugins, getPluginNextSteps } from './core/plugin-loader.js';
+
 /**
  * Main entry point for the MCP server.
  * Sets up the Model Context Protocol server with all available tools,
@@ -67,7 +75,10 @@ async function main() {
     CLOSE_TAB_TOOL,
     GET_CURRENT_HTML_TOOL,
     TAKE_SCREENSHOT_TOOL,
-    SCROLL_PAGE_TOOL
+    SCROLL_PAGE_TOOL,
+    NAVIGATE_HISTORY_TOOL,
+    PLUGIN_INFO_TOOL,
+    PLUGIN_ACTION_TOOL
   ];
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
@@ -121,6 +132,18 @@ async function main() {
         case "scroll_page":
           result = await scrollPage(safeArgs);
           break;
+
+        case "navigate_history":
+          result = await navigateHistory(safeArgs);
+          break;
+
+        case "plugin_info":
+          result = pluginInfo(safeArgs);
+          break;
+
+        case "plugin_action":
+          result = await pluginAction(safeArgs);
+          break;
           
         default:
           throw new Error(`Unknown tool: ${name}`);
@@ -142,6 +165,13 @@ async function main() {
   });
 
   const transport = new StdioServerTransport();
+  
+  // Load plugins before starting the server
+  const pluginCount = await loadPlugins();
+  if (pluginCount > 0) {
+    logger.info(`${pluginCount} plugin(s) loaded and ready`);
+  }
+  
   await server.connect(transport);
   logger.info(`MCPBrowser server v${packageJson.version} started`);
 }
@@ -171,7 +201,16 @@ export {
   getCurrentHtml,
   takeScreenshot,
   scrollPage,
-  handleAcceptEula
+  navigateHistory,
+  handleAcceptEula,
+  // Plugin system exports
+  loadPlugins,
+  getLoadedPlugins,
+  getPlugin,
+  detectPlugins,
+  getPluginNextSteps,
+  pluginAction,
+  pluginInfo
 };
 
 // Run the MCP server only if this is the main module (not imported for testing)

package/src/plugins/_example/index.js

@@ -0,0 +1,139 @@
+/**
+ * _example plugin — Stub plugin for testing and documentation.
+ * Implements the full plugin interface contract (interfaceVersion 1).
+ * Matches pages on "example.test" domain for unit/integration testing.
+ */
+
+import { MCPResponse } from '../../core/responses.js';
+
+// ============================================================================
+// MANIFEST
+// ============================================================================
+
+export const manifest = {
+  name: "_example",
+  version: "1.0.0",
+  description: "Example stub plugin for testing the MCPBrowser plugin system",
+  interfaceVersion: 1,
+  urlPatterns: ["example.test"],
+  domPatterns: [".example-plugin-marker"]
+};
+
+// ============================================================================
+// DETECTION
+// ============================================================================
+
+/**
+ * Detect whether this plugin is applicable for the given page.
+ * @param {string} url - Current page URL
+ * @param {string} html - Extracted page HTML
+ * @returns {{ matched: boolean, confidence?: number }}
+ */
+export function matchesPage(url, html) {
+  try {
+    // Fast URL check first
+    if (url && url.includes("example.test")) {
+      return { matched: true, confidence: 1.0 };
+    }
+    // DOM fallback check
+    if (html && html.includes("example-plugin-marker")) {
+      return { matched: true, confidence: 0.8 };
+    }
+    return { matched: false };
+  } catch {
+    return { matched: false };
+  }
+}
+
+// ============================================================================
+// ACTIONS
+// ============================================================================
+
+class ExampleActionResponse extends MCPResponse {
+  constructor(data, nextSteps) {
+    super(nextSteps);
+    this.data = data;
+  }
+  _getAdditionalFields() { return { data: this.data }; }
+  getTextSummary() { return `Example action returned ${Array.isArray(this.data) ? this.data.length : 0} items`; }
+}
+
+/**
+ * Return the complete list of actions this plugin provides.
+ * @returns {import('../../specs/002-site-plugins/data-model.md').ActionDescriptor[]}
+ */
+export function getActions() {
+  return [
+    {
+      name: "list_items",
+      description: "List items from the example page",
+      params: [
+        { name: "limit", type: "number", description: "Maximum number of items to return", required: false, default: 10 }
+      ],
+      execute: async ({ page, params }) => {
+        const limit = params?.limit ?? 10;
+        const items = await page.evaluate((lim) => {
+          const rows = document.querySelectorAll('.item-row');
+          return Array.from(rows).slice(0, lim).map(row => ({
+            title: row.querySelector('.title')?.textContent?.trim() || 'Untitled',
+            date: row.querySelector('.date')?.textContent?.trim() || ''
+          }));
+        }, limit);
+
+        return new ExampleActionResponse(items, [
+          "Call plugin_action with action 'get_item_detail' to read a specific item"
+        ]);
+      }
+    },
+    {
+      name: "get_item_detail",
+      description: "Get details for a specific item by ID",
+      params: [
+        { name: "itemId", type: "string", description: "Item identifier", required: true }
+      ],
+      execute: async ({ page, params }) => {
+        if (!params?.itemId) {
+          throw new Error("itemId parameter is required");
+        }
+        const detail = await page.evaluate((id) => {
+          const el = document.querySelector(`[data-id="${id}"]`);
+          if (!el) return null;
+          return {
+            id,
+            title: el.querySelector('.title')?.textContent?.trim() || '',
+            body: el.querySelector('.body')?.textContent?.trim() || ''
+          };
+        }, params.itemId);
+
+        if (!detail) {
+          const { ErrorResponse } = await import('../../src/core/responses.js');
+          return new ErrorResponse(
+            `Item '${params.itemId}' not found on the page`,
+            ["Verify the item ID is correct", "Use list_items to see available items"]
+          );
+        }
+
+        return new ExampleActionResponse(detail, [
+          "Use plugin_action with action 'list_items' to see all items"
+        ]);
+      }
+    }
+  ];
+}
+
+// ============================================================================
+// INFO
+// ============================================================================
+
+/**
+ * Return high-level plugin context for the AI agent.
+ * @returns {import('../../specs/002-site-plugins/data-model.md').PluginInfo}
+ */
+export function getInfo() {
+  return {
+    description: "Example stub plugin for testing MCPBrowser's plugin system. Lists items and retrieves item details from example.test pages.",
+    targetPages: ["Example test page (example.test)"],
+    authFlow: "No authentication required — example.test is a test domain",
+    actions: getActions().map(({ name, description, params }) => ({ name, description, params }))
+  };
+}

package/src/plugins/gmail/actions/archive-email.js

@@ -0,0 +1,65 @@
+/**
+ * archive-email.js — Archive an email, removing it from the inbox.
+ *
+ * Tier usage:
+ *   T2: 'e' keyboard shortcut to archive
+ *   T3: selectEmailRow for list view targeting
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  detectView,
+  selectEmailRow,
+  VIEW,
+  GmailActionResponse
+} from '../helpers.js';
+
+/**
+ * Archive an email from thread view or list view.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {number} [opts.params.index] - Email index in list view
+ * @param {string} [opts.params.id] - Email ID in list view
+ * @returns {Promise<GmailActionResponse|ErrorResponse>}
+ */
+export async function archiveEmail({ page, params }) {
+  // Precondition: must be on Gmail
+  const pre = await checkPrecondition(page, 'on_gmail');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://mail.google.com' }) to open Gmail first."
+    ]);
+  }
+
+  const view = await detectView(page);
+
+  if (view === VIEW.THREAD) {
+    // In thread view, archive directly
+    await page.keyboard.press('e');
+    logger.debug('archiveEmail: pressed "e" in thread view');
+  } else if (view === VIEW.EMAIL_LIST || view === VIEW.SEARCH_RESULTS) {
+    // In list view, select the row first
+    const sel = await selectEmailRow(page, { index: params.index, id: params.id });
+    if (!sel.selected) {
+      return new ErrorResponse(sel.error || 'Could not select email to archive.', [
+        'Provide an index or id parameter to target a specific email.'
+      ]);
+    }
+    await page.keyboard.press('e');
+    logger.debug('archiveEmail: selected row and pressed "e"');
+  } else {
+    return new ErrorResponse(
+      'Cannot archive from the current view. Navigate to inbox or open an email first.',
+      ["Use list_emails to view the inbox, or read_email to open a thread."]
+    );
+  }
+
+  return new GmailActionResponse(
+    { archived: true },
+    'Email archived successfully.',
+    ['Use list_emails to return to inbox']
+  );
+}