mcpbrowser 0.3.35 → 0.3.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.35",
+  "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,7 +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 } from '../core/plugin-loader.js';
+import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -38,7 +38,7 @@ import { getPluginNextSteps } from '../core/plugin-loader.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;
@@ -48,6 +48,7 @@ export class ClickWithFallbackResponse extends MCPResponse {
     this.currentUrl = currentUrl;
     this.html = html;
     this.message = message;
+    this.recommendedPlugins = recommendedPlugins;
   }
 
   _getAdditionalFields() {
@@ -59,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
     };
   }
 
@@ -329,12 +331,12 @@ 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",
           "Use MCPBrowser's take_screenshot if page has popups or visual content that's hard to parse from HTML",
-          "Use MCPBrowser's close_tab when finished",
-          ...(html ? getPluginNextSteps(currentUrl, html) : [])
+          "Use MCPBrowser's close_tab when finished"
         ]
       : [
           "Use MCPBrowser's get_current_html to see updated page state",
@@ -354,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,7 +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 } from '../core/plugin-loader.js';
+import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
 
 // Shared execution defaults for script actions
 export const EXECUTION_TIMEOUT_DEFAULT_MS = 30_000;
@@ -22,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;
@@ -32,6 +32,7 @@ export class ExecuteJavascriptResponse extends MCPResponse {
     this.urlChanged = urlChanged;
     this.currentUrl = currentUrl;
     this.error = error;
+    this.recommendedPlugins = recommendedPlugins;
   }
 
   _getAdditionalFields() {
@@ -42,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
     };
   }
 
@@ -224,11 +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',
-      ...getPluginNextSteps(currentUrl, '')
-    ]
+      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,7 +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 } from '../core/plugin-loader.js';
+import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -26,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') {
@@ -39,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
     };
   }
 
@@ -221,13 +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",
-        ...getPluginNextSteps(page.url(), processedHtml)
-      ]
+        "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,7 +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 } from '../core/plugin-loader.js';
+import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -24,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') {
@@ -37,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
     };
   }
 
@@ -158,12 +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",
-        ...getPluginNextSteps(currentUrl, 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/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/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'
+        ]
+  );
+}