mcpbrowser 0.3.35 → 0.3.37

package/src/cli/registry.js

@@ -0,0 +1,256 @@
+/**
+ * cli/registry.js — Single source of truth for all CLI commands.
+ *
+ * To add a new CLI command:
+ *   1. Import the MCP TOOL definition and action function
+ *   2. Add an entry to CLI_REGISTRY below
+ *   3. Done — help, routing, flag mapping, coercion all auto-update
+ */
+
+import { writeFileSync } from 'fs';
+
+import { fetchPage, FETCH_WEBPAGE_TOOL } from '../actions/fetch-page.js';
+import { clickElement, CLICK_ELEMENT_TOOL } from '../actions/click-element.js';
+import { typeText, TYPE_TEXT_TOOL } from '../actions/type-text.js';
+import { executeJavascript, EXECUTE_JAVASCRIPT_TOOL } from '../actions/execute-javascript.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 { navigateHistory, NAVIGATE_HISTORY_TOOL } from '../actions/navigate-history.js';
+import { closeTab, CLOSE_TAB_TOOL } from '../actions/close-tab.js';
+
+import { htmlToText, getStructured, getPrimaryText } from './utils.js';
+
+// ---------------------------------------------------------------------------
+// Factory for back/forward (deduplicated)
+// ---------------------------------------------------------------------------
+
+function makeHistoryCommand(direction) {
+  return {
+    cmd: direction,
+    tool: NAVIGATE_HISTORY_TOOL,
+    action: navigateHistory,
+    requiresFetch: true,
+    flagMap: { raw: '_raw' },
+    flagDefaults: {},
+    buildParams: (url, flags) => ({
+      url,
+      direction,
+      returnHtml: true,
+      removeUnnecessaryHTML: !flags.raw,
+    }),
+    formatOutput: (mcp, flags) => {
+      const s = getStructured(mcp);
+      const out = {};
+      if (s.previousUrl || s.currentUrl) {
+        out.stderr = `${s.previousUrl || '?'} → ${s.currentUrl || '?'}`;
+      }
+      if (s.html) out.stdout = flags.raw ? s.html : htmlToText(s.html);
+      return out;
+    },
+    examples: [`mcpbrowser ${direction} https://example.com`],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI_REGISTRY
+// ---------------------------------------------------------------------------
+
+export const CLI_REGISTRY = [
+  {
+    cmd: 'fetch',
+    tool: FETCH_WEBPAGE_TOOL,
+    action: fetchPage,
+    requiresFetch: false,
+    flagMap: { wait: 'postLoadWait', raw: '_raw' },
+    flagDefaults: {},
+    buildParams: (url, flags) => ({
+      url,
+      browser: flags.browser || '',
+      removeUnnecessaryHTML: !flags.raw,
+      postLoadWait: flags.wait ? Number(flags.wait) : 0
+    }),
+    formatOutput: (mcp, flags) => {
+      const html = getStructured(mcp).html || getPrimaryText(mcp);
+      return { stdout: flags.raw ? html : htmlToText(html) };
+    },
+    examples: [
+      'mcpbrowser fetch https://eng.ms/docs/my-page',
+      'mcpbrowser fetch https://portal.azure.com --browser edge --wait 5000',
+      'mcpbrowser fetch https://github.com --raw',
+    ],
+    cliNote: '--raw    Output full HTML instead of extracted text',
+  },
+
+  {
+    cmd: 'screenshot',
+    tool: TAKE_SCREENSHOT_TOOL,
+    action: takeScreenshot,
+    requiresFetch: true,
+    autoFetch: true, // screenshot auto-fetches the page first
+    flagMap: { 'full-page': 'fullPage' },
+    buildParams: (url, flags) => ({
+      url,
+      fullPage: !!flags['full-page']
+    }),
+    formatOutput: (mcp, flags) => {
+      const base64 = getStructured(mcp).screenshotBase64;
+      if (!base64) return { error: 'No screenshot data returned' };
+      const outFile = flags.output || 'screenshot.png';
+      writeFileSync(outFile, Buffer.from(base64, 'base64'));
+      return { stderr: `Screenshot saved to ${outFile}` };
+    },
+    examples: [
+      'mcpbrowser screenshot https://example.com --output page.png',
+      'mcpbrowser screenshot https://dashboard.corp.com --full-page',
+    ],
+    cliNote: '--output <path>    File path to save (default: screenshot.png)',
+  },
+
+  {
+    cmd: 'click',
+    tool: CLICK_ELEMENT_TOOL,
+    action: clickElement,
+    requiresFetch: true,
+    flagMap: {},
+    buildParams: (url, flags) => ({
+      url,
+      selector: flags.selector || undefined,
+      text: flags.text || undefined,
+      returnHtml: flags.returnHtml !== 'false',
+      removeUnnecessaryHTML: true,
+      postClickWait: flags.postClickWait ? Number(flags.postClickWait) : 1000,
+    }),
+    validate: (flags) => {
+      if (!flags.selector && !flags.text) return '--selector or --text is required for click';
+    },
+    formatOutput: (mcp) => {
+      const html = getStructured(mcp).html;
+      return { stdout: html ? htmlToText(html) : getPrimaryText(mcp) };
+    },
+    examples: [
+      'mcpbrowser click https://example.com --selector "#login-btn"',
+      'mcpbrowser click https://example.com --text "Sign In"',
+    ],
+  },
+
+  {
+    cmd: 'type',
+    tool: TYPE_TEXT_TOOL,
+    action: typeText,
+    requiresFetch: true,
+    flagMap: {},
+    buildParams: (url, flags) => ({
+      url,
+      fields: [{ selector: flags.selector, text: flags.text }],
+      returnHtml: false
+    }),
+    validate: (flags) => {
+      if (!flags.selector || !flags.text) return '--selector and --text are required for type';
+    },
+    formatOutput: (mcp) => ({ stdout: getPrimaryText(mcp) }),
+    examples: [
+      'mcpbrowser type https://example.com --selector "#search" --text "query"',
+      'mcpbrowser type https://login.com --selector "input[name=email]" --text "user@corp.com"',
+    ],
+    cliNote: 'CLI shorthand: --selector + --text fills a single field',
+  },
+
+  {
+    cmd: 'exec',
+    tool: EXECUTE_JAVASCRIPT_TOOL,
+    action: executeJavascript,
+    requiresFetch: true,
+    flagMap: {},
+    buildParams: (url, flags) => ({
+      url,
+      script: flags.script,
+      timeoutMs: flags.timeoutMs ? Number(flags.timeoutMs) : 30000,
+      returnType: flags.returnType || 'json',
+    }),
+    validate: (flags) => {
+      if (!flags.script) return '--script is required for exec';
+    },
+    formatOutput: (mcp) => {
+      const r = getStructured(mcp).result;
+      if (r !== undefined && r !== null) {
+        return { stdout: typeof r === 'string' ? r : JSON.stringify(r, null, 2) };
+      }
+      return { stdout: getPrimaryText(mcp) };
+    },
+    examples: [
+      'mcpbrowser exec https://example.com --script "document.title"',
+      'mcpbrowser exec https://mail.google.com --script "[...document.querySelectorAll(\'.zA\')].map(r=>r.textContent)"',
+    ],
+  },
+
+  {
+    cmd: 'html',
+    tool: GET_CURRENT_HTML_TOOL,
+    action: getCurrentHtml,
+    requiresFetch: true,
+    flagMap: { raw: '_raw' },
+    buildParams: (url, flags) => ({
+      url,
+      removeUnnecessaryHTML: !flags.raw,
+    }),
+    formatOutput: (mcp) => ({ stdout: getStructured(mcp).html || getPrimaryText(mcp) }),
+    examples: [
+      'mcpbrowser html https://example.com',
+      'mcpbrowser html https://example.com --raw',
+    ],
+    cliNote: '--raw    Output raw HTML without cleanup',
+  },
+
+  {
+    cmd: 'scroll',
+    tool: SCROLL_PAGE_TOOL,
+    action: scrollPage,
+    requiresFetch: true,
+    flagMap: {},
+    buildParams: (url, flags) => {
+      const params = { url };
+      if (flags.selector) { params.selector = flags.selector; }
+      else if (flags.x !== undefined || flags.y !== undefined) {
+        if (flags.x !== undefined) params.x = Number(flags.x);
+        if (flags.y !== undefined) params.y = Number(flags.y);
+      } else {
+        params.direction = flags.direction || 'down';
+        if (flags.amount) params.amount = Number(flags.amount);
+      }
+      return params;
+    },
+    formatOutput: (mcp) => {
+      const s = getStructured(mcp);
+      return {
+        stdout: JSON.stringify({
+          scrollX: s.scrollX, scrollY: s.scrollY,
+          pageWidth: s.pageWidth, pageHeight: s.pageHeight,
+          viewportWidth: s.viewportWidth, viewportHeight: s.viewportHeight
+        }, null, 2)
+      };
+    },
+    examples: [
+      'mcpbrowser scroll https://example.com --direction down --amount 1000',
+      'mcpbrowser scroll https://example.com --selector "#footer"',
+      'mcpbrowser scroll https://example.com --x 0 --y 0',
+    ],
+  },
+
+  makeHistoryCommand('back'),
+  makeHistoryCommand('forward'),
+
+  {
+    cmd: 'close',
+    tool: CLOSE_TAB_TOOL,
+    action: closeTab,
+    requiresFetch: false,
+    flagMap: {},
+    buildParams: (url) => ({ url }),
+    formatOutput: (mcp) => ({ stdout: getPrimaryText(mcp) }),
+    examples: ['mcpbrowser close https://example.com'],
+  },
+];
+
+// Lookup map for O(1) command resolution
+export const CMD_MAP = new Map(CLI_REGISTRY.map(entry => [entry.cmd, entry]));

package/src/cli/utils.js

@@ -0,0 +1,39 @@
+/**
+ * cli/utils.js — Shared utilities for CLI output formatting and safe data access.
+ */
+
+/**
+ * Convert HTML to readable terminal text (lossy preview).
+ */
+export function htmlToText(html) {
+  return html
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/p>/gi, '\n\n')
+    .replace(/<\/div>/gi, '\n')
+    .replace(/<\/li>/gi, '\n')
+    .replace(/<\/h[1-6]>/gi, '\n\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ')
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/**
+ * Safely get the primary text content from an MCP result.
+ * Falls back to empty string if content is missing.
+ */
+export function getPrimaryText(mcp) {
+  return mcp?.content?.[0]?.text ?? '';
+}
+
+/**
+ * Safely get structuredContent from an MCP result.
+ * Returns an empty object if missing, so callers can destructure safely.
+ */
+export function getStructured(mcp) {
+  return mcp?.structuredContent ?? {};
+}

package/src/core/plugin-loader.js

@@ -263,14 +263,12 @@ export function detectPlugins(url, html) {
       if (match && match.matched) {
         const confidence = typeof match.confidence === 'number' ? match.confidence : 1.0;
         
-        // Build nextSteps from plugin info
+        // Build nextSteps from plugin info — concise, actionable
         const info = plugin.getInfo();
-        const topActions = (info.actions || []).slice(0, 3);
-        const actionSummary = topActions.map(a => a.name).join(', ');
+        const recommendationText = info.recommendation || info.description || 'Site-specific automation available.';
         
         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`] : [])
+          `Recommended: use "${name}" plugin to ${recommendationText.charAt(0).toLowerCase() + recommendationText.slice(1).replace(/\.$/, '')}. See recommendedPlugins for available actions.`
         ];
         
         results.push({ pluginName: name, confidence, nextSteps });
@@ -301,6 +299,29 @@ export function getPluginNextSteps(url, html) {
   return steps;
 }
 
+/**
+ * Build the recommendedPlugins payload for structuredContent.
+ * Returns full plugin metadata including action catalog with params,
+ * so agents can call actions directly without needing plugin_info.
+ * @param {string} url - Current page URL
+ * @param {string} html - Extracted page HTML
+ * @returns {Array<{ plugin: string, recommendation: string, actions: Array, usage: string }>}
+ */
+export function getRecommendedPlugins(url, html) {
+  const detections = detectPlugins(url, html);
+  return detections.map(d => {
+    const plugin = loadedPlugins.get(d.pluginName);
+    const info = plugin.getInfo();
+    const recommendationText = info.recommendation || info.description || 'Site-specific automation available.';
+    return {
+      plugin: d.pluginName,
+      recommendation: recommendationText,
+      actions: info.actions || [],
+      usage: `plugin_action({ plugin: '${d.pluginName}', action: '<name>', params: {...} })`
+    };
+  });
+}
+
 // ============================================================================
 // ACCESSORS
 // ============================================================================

package/src/mcp-browser.js

@@ -12,6 +12,9 @@ import { fileURLToPath } from 'url';
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 
+// Import CLI mode
+import { isCliMode, runCli } from './cli/index.js';
+
 // Import response classes
 import { ErrorResponse } from './core/responses.js';
 import logger, { attachServer as attachLoggerServer } from './core/logger.js';
@@ -203,6 +206,9 @@ export {
   scrollPage,
   navigateHistory,
   handleAcceptEula,
+  // CLI exports
+  isCliMode,
+  runCli,
   // Plugin system exports
   loadPlugins,
   getLoadedPlugins,
@@ -216,8 +222,20 @@ export {
 // Run the MCP server only if this is the main module (not imported for testing)
 if (import.meta.url === new URL(process.argv[1], 'file://').href || 
     fileURLToPath(import.meta.url) === process.argv[1]) {
-  main().catch((err) => {
-    logger.error(`Server failed: ${err.message}`);
-    process.exit(1);
-  });
+  const argv = process.argv.slice(2);
+  if (isCliMode(argv)) {
+    // CLI mode: run command and exit
+    runCli(argv).then((code) => {
+      process.exit(code);
+    }).catch((err) => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exit(1);
+    });
+  } else {
+    // MCP server mode (default): stdin/stdout JSON-RPC
+    main().catch((err) => {
+      logger.error(`Server failed: ${err.message}`);
+      process.exit(1);
+    });
+  }
 }

package/src/plugins/_example/index.js

@@ -131,6 +131,7 @@ export function getActions() {
  */
 export function getInfo() {
   return {
+    recommendation: "Interact with example.test pages — list items and view item details.",
     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",

package/src/plugins/gcal/actions/check-availability.js

@@ -0,0 +1,185 @@
+/**
+ * check-availability.js — Check whether a time slot is free or busy.
+ *
+ * Tier usage:
+ *   T1: calendarNavigate + buildViewPath to navigate to day view for the date
+ *   T3: extractVisibleEvents for event data extraction
+ *   T4: EVENT_CHIP selector via waitForCalendar
+ */
+
+import { ErrorResponse } from '../../../core/responses.js';
+import logger from '../../../core/logger.js';
+import {
+  checkPrecondition,
+  calendarNavigate,
+  buildViewPath,
+  waitForCalendar,
+  extractVisibleEvents,
+  GCalActionResponse
+} from '../helpers.js';
+import { EVENT_CHIP } from '../selectors.js';
+
+/**
+ * Parse HH:MM time string to total minutes since midnight.
+ * @param {string} timeStr - Time in HH:MM format
+ * @returns {number} Minutes since midnight
+ */
+function timeToMinutes(timeStr) {
+  const [h, m] = timeStr.split(':').map(Number);
+  return h * 60 + m;
+}
+
+/**
+ * Format minutes since midnight back to HH:MM.
+ * @param {number} minutes
+ * @returns {string}
+ */
+function minutesToTime(minutes) {
+  const h = Math.floor(minutes / 60);
+  const m = minutes % 60;
+  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`;
+}
+
+/**
+ * Check availability for a given date and time window.
+ * @param {object} opts
+ * @param {import('puppeteer-core').Page} opts.page
+ * @param {object} opts.params
+ * @param {string} opts.params.date - ISO date to check (required)
+ * @param {string} opts.params.startTime - Window start time in HH:MM (required)
+ * @param {string} opts.params.endTime - Window end time in HH:MM (required)
+ * @returns {Promise<GCalActionResponse|ErrorResponse>}
+ */
+export async function checkAvailability({ page, params }) {
+  // Validate required params
+  if (!params.date) {
+    return new ErrorResponse(
+      'The "date" parameter is required to check availability.',
+      ['Provide a date: check_availability({ date: "2026-04-10", startTime: "09:00", endTime: "17:00" })']
+    );
+  }
+  if (!params.startTime) {
+    return new ErrorResponse(
+      'The "startTime" parameter is required to check availability.',
+      ['Provide a start time: check_availability({ date: "2026-04-10", startTime: "09:00", endTime: "17:00" })']
+    );
+  }
+  if (!params.endTime) {
+    return new ErrorResponse(
+      'The "endTime" parameter is required to check availability.',
+      ['Provide an end time: check_availability({ date: "2026-04-10", startTime: "09:00", endTime: "17:00" })']
+    );
+  }
+
+  // Validate startTime < endTime
+  const windowStart = timeToMinutes(params.startTime);
+  const windowEnd = timeToMinutes(params.endTime);
+  if (windowStart >= windowEnd) {
+    return new ErrorResponse(
+      `startTime (${params.startTime}) must be earlier than endTime (${params.endTime}).`,
+      ['Ensure the start time is before the end time, e.g. startTime: "09:00", endTime: "17:00"']
+    );
+  }
+
+  // Precondition: must be on Google Calendar
+  const pre = await checkPrecondition(page, 'on_calendar');
+  if (!pre.met) {
+    return new ErrorResponse(pre.error, [
+      pre.suggestion || "Use fetch_webpage({ url: 'https://calendar.google.com' }) to open Google Calendar first."
+    ]);
+  }
+
+  // T1: Navigate to the day view for the specified date
+  const path = buildViewPath('day', params.date);
+  await calendarNavigate(page, path);
+  logger.debug(`checkAvailability: navigated to day view for ${params.date}`);
+
+  // Wait for event chips (or empty day)
+  let events = [];
+  try {
+    await waitForCalendar(page, EVENT_CHIP);
+    events = await extractVisibleEvents(page, 100);
+  } catch {
+    // No events — the entire window is free
+    logger.debug('checkAvailability: no events found, entire window is free');
+  }
+
+  // Filter events that overlap with the requested time window
+  const busySlots = [];
+  for (const event of events) {
+    if (event.allDay) {
+      // All-day events occupy the full day but don't block time slots
+      continue;
+    }
+
+    // Parse event times (best-effort from extracted data)
+    if (event.startTime && event.endTime) {
+      const eventStart = timeToMinutes(event.startTime);
+      const eventEnd = timeToMinutes(event.endTime);
+
+      // Check overlap: event overlaps window if event starts before window ends
+      // AND event ends after window starts
+      if (eventStart < windowEnd && eventEnd > windowStart) {
+        busySlots.push({
+          title: event.title,
+          startTime: event.startTime,
+          endTime: event.endTime
+        });
+      }
+    }
+  }
+
+  // Compute free slots within the window
+  const freeSlots = [];
+  // Sort busy slots by start time
+  busySlots.sort((a, b) => timeToMinutes(a.startTime) - timeToMinutes(b.startTime));
+
+  let cursor = windowStart;
+  for (const busy of busySlots) {
+    const busyStart = timeToMinutes(busy.startTime);
+    const busyEnd = timeToMinutes(busy.endTime);
+
+    if (cursor < busyStart) {
+      freeSlots.push({
+        startTime: minutesToTime(cursor),
+        endTime: minutesToTime(Math.min(busyStart, windowEnd)),
+        durationMinutes: Math.min(busyStart, windowEnd) - cursor
+      });
+    }
+    cursor = Math.max(cursor, busyEnd);
+  }
+
+  // Final free slot after all busy periods
+  if (cursor < windowEnd) {
+    freeSlots.push({
+      startTime: minutesToTime(cursor),
+      endTime: minutesToTime(windowEnd),
+      durationMinutes: windowEnd - cursor
+    });
+  }
+
+  const isFree = busySlots.length === 0;
+  const summary = isFree
+    ? `${params.date} from ${params.startTime} to ${params.endTime} is completely free.`
+    : `${params.date} from ${params.startTime} to ${params.endTime} has ${busySlots.length} conflicting event(s) and ${freeSlots.length} free slot(s).`;
+
+  return new GCalActionResponse(
+    {
+      date: params.date,
+      windowStart: params.startTime,
+      windowEnd: params.endTime,
+      isFree,
+      busySlots,
+      freeSlots,
+      conflictCount: busySlots.length
+    },
+    summary,
+    isFree
+      ? [`Use create_event({ date: "${params.date}", startTime: "${params.startTime}" }) to book this slot`]
+      : [
+          'Use create_event to book one of the free slots',
+          'Use check_availability with a different time range to find open slots',
+          'Use list_events to see all events on this date'
+        ]
+  );
+}