mcpbrowser 0.3.33 → 0.3.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.33",
+  "version": "0.3.35",
   "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 } from '../core/plugin-loader.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -332,7 +333,8 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
           "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"
+          "Use MCPBrowser's close_tab when finished",
+          ...(html ? getPluginNextSteps(currentUrl, html) : [])
         ]
       : [
           "Use MCPBrowser's get_current_html to see updated page state",

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 } from '../core/plugin-loader.js';
 
 // Shared execution defaults for script actions
 export const EXECUTION_TIMEOUT_DEFAULT_MS = 30_000;
@@ -225,7 +226,8 @@ export async function executeJavascript({ url, script, timeoutMs = EXECUTION_TIM
     nextSteps: [
       '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'
+      serialization.truncated ? 'Narrow your selector or reduce returned fields to avoid truncation' : 'Proceed with the returned data',
+      ...getPluginNextSteps(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 } from '../core/plugin-loader.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -224,7 +225,8 @@ async function doFetchPage({ url, browser, removeUnnecessaryHTML, postLoadWait }
         "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"
+        "Use MCPBrowser's close_tab when finished to free browser resources",
+        ...getPluginNextSteps(page.url(), processedHtml)
       ]
     );
   } catch (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 } from '../core/plugin-loader.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -160,7 +161,8 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
         "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"
+        "Use MCPBrowser's close_tab to free resources when done",
+        ...getPluginNextSteps(currentUrl, html)
       ]
     );
   } catch (err) {

package/src/actions/navigate-history.js

@@ -0,0 +1,248 @@
+/**
+ * navigate-history.js - Browser back/forward navigation
+ * Navigates browser history on an already-loaded page.
+ */
+
+import { getBrowser, getValidatedPage, domainPages } from '../core/browser.js';
+import { extractAndProcessHtml, waitForPageReady } from '../core/page.js';
+import { MCPResponse, InformationalResponse } from '../core/responses.js';
+import logger from '../core/logger.js';
+
+/**
+ * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
+ */
+
+// ============================================================================
+// RESPONSE CLASS
+// ============================================================================
+
+/**
+ * Response for successful navigate_history operations
+ */
+export class NavigateHistorySuccessResponse extends MCPResponse {
+  /**
+   * @param {string} direction - Navigation direction (back or forward)
+   * @param {string} previousUrl - URL before navigation
+   * @param {string} currentUrl - URL after navigation
+   * @param {string|null} html - Page HTML content (null if returnHtml=false)
+   * @param {string[]} nextSteps - Suggested next actions
+   */
+  constructor(direction, previousUrl, currentUrl, html, nextSteps) {
+    super(nextSteps);
+
+    if (typeof direction !== 'string') {
+      throw new TypeError('direction must be a string');
+    }
+    if (typeof previousUrl !== 'string') {
+      throw new TypeError('previousUrl must be a string');
+    }
+    if (typeof currentUrl !== 'string') {
+      throw new TypeError('currentUrl must be a string');
+    }
+    if (html !== null && typeof html !== 'string') {
+      throw new TypeError('html must be a string or null');
+    }
+
+    this.direction = direction;
+    this.previousUrl = previousUrl;
+    this.currentUrl = currentUrl;
+    this.html = html;
+  }
+
+  _getAdditionalFields() {
+    return {
+      direction: this.direction,
+      previousUrl: this.previousUrl,
+      currentUrl: this.currentUrl,
+      html: this.html
+    };
+  }
+
+  getTextSummary() {
+    return `Navigated ${this.direction}: ${this.previousUrl} → ${this.currentUrl}`;
+  }
+}
+
+// ============================================================================
+// TOOL DEFINITION
+// ============================================================================
+
+/** @type {Tool} */
+export const NAVIGATE_HISTORY_TOOL = {
+  name: "navigate_history",
+  title: "Navigate Back/Forward",
+  description: "**BROWSER HISTORY NAVIGATION** - Navigate back or forward in browser history on an already-loaded page. Use after clicking links to return to the previous page, or to go forward after going back.\n\n**PREREQUISITE**: Page MUST be loaded with fetch_webpage first. This tool navigates the history of an existing browser tab.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "URL of the already-loaded page (identifies which tab to navigate)" },
+      direction: {
+        type: "string",
+        enum: ["back", "forward"],
+        description: "Navigation direction: 'back' to go to previous page, 'forward' to go to next page",
+        default: "back"
+      },
+      returnHtml: { type: "boolean", description: "Return page HTML after navigation", default: true },
+      removeUnnecessaryHTML: { type: "boolean", description: "Remove unnecessary HTML elements (scripts, styles, etc.) for size reduction.", default: true }
+    },
+    required: ["url"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      direction: { type: "string", enum: ["back", "forward"], description: "Navigation direction used" },
+      previousUrl: { type: "string", description: "URL before navigation" },
+      currentUrl: { type: "string", description: "URL after navigation" },
+      html: { type: ["string", "null"], description: "Page HTML content after navigation (null if returnHtml=false)" },
+      nextSteps: {
+        type: "array",
+        items: { type: "string" },
+        description: "Suggested next actions"
+      }
+    },
+    required: ["direction", "previousUrl", "currentUrl", "nextSteps"],
+    additionalProperties: false
+  },
+  annotations: {
+    title: "Navigate Back/Forward",
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true
+  }
+};
+
+// ============================================================================
+// ACTION FUNCTION
+// ============================================================================
+
+/**
+ * Navigate browser history (back/forward) on an already-loaded page
+ * @param {Object} params - Parameters
+ * @param {string} params.url - URL of the already-loaded page
+ * @param {string} [params.direction='back'] - Navigation direction
+ * @param {boolean} [params.returnHtml=true] - Return page HTML after navigation
+ * @param {boolean} [params.removeUnnecessaryHTML=true] - Clean HTML
+ * @returns {Promise<MCPResponse>} Navigation result
+ */
+export async function navigateHistory({ url, direction = 'back', returnHtml = true, removeUnnecessaryHTML = true }) {
+  logger.info(`navigate_history called: url=${url}, direction=${direction}`);
+
+  if (!url) {
+    throw new Error("url parameter is required");
+  }
+
+  let hostname;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  // Ensure browser connection
+  try {
+    await getBrowser();
+  } catch (err) {
+    logger.error(`navigate_history: Failed to connect to browser: ${err.message}`);
+    return new InformationalResponse(
+      `Browser connection failed: ${err.message}`,
+      'The browser must be running with remote debugging enabled.',
+      [
+        'Ensure the browser is installed and running',
+        'Check that remote debugging is enabled (--remote-debugging-port)',
+        'Try restarting the MCP server'
+      ]
+    );
+  }
+
+  // Validate page exists and is usable
+  const { page, error: pageError } = await getValidatedPage(hostname);
+
+  if (!page) {
+    const isConnectionLost = pageError && pageError.includes('connection');
+    logger.debug(`navigate_history: ${pageError || 'No page found for ' + hostname}`);
+    return new InformationalResponse(
+      isConnectionLost ? `Page connection lost for ${hostname}` : `No open page found for ${hostname}`,
+      isConnectionLost
+        ? 'The browser tab was closed or the connection was lost. The page needs to be reloaded.'
+        : 'The page must be loaded before you can navigate its history.',
+      [
+        "Use MCPBrowser's fetch_webpage tool to load the page first",
+        "Then retry MCPBrowser's navigate_history with the same URL"
+      ]
+    );
+  }
+
+  try {
+    const previousUrl = page.url();
+
+    // Navigate history
+    let response;
+    if (direction === 'forward') {
+      response = await page.goForward({ waitUntil: 'domcontentloaded', timeout: 30000 });
+    } else {
+      response = await page.goBack({ waitUntil: 'domcontentloaded', timeout: 30000 });
+    }
+
+    // goBack/goForward return null if there's no history entry
+    if (response === null) {
+      logger.info(`navigate_history: No ${direction} history entry available`);
+      return new InformationalResponse(
+        `No ${direction} history entry available`,
+        `The page has no ${direction} history to navigate to. This means you're already at the ${direction === 'back' ? 'first' : 'last'} page in the browsing history for this tab.`,
+        [
+          direction === 'back'
+            ? "Use MCPBrowser's fetch_webpage to navigate to a different URL"
+            : "Use MCPBrowser's navigate_history with direction='back' to go back instead",
+          "Use MCPBrowser's get_current_html to check the current page content"
+        ]
+      );
+    }
+
+    const currentUrl = page.url();
+
+    // Update domainPages if hostname changed after navigation
+    try {
+      const newHostname = new URL(currentUrl).hostname;
+      if (newHostname !== hostname) {
+        domainPages.delete(hostname);
+        domainPages.set(newHostname, page);
+        logger.info(`navigate_history: Updated domainPages mapping: ${hostname} → ${newHostname}`);
+      }
+    } catch {
+      // If URL parsing fails, keep existing mapping
+    }
+
+    // Extract HTML if requested
+    let html = null;
+    if (returnHtml) {
+      await waitForPageReady(page);
+      html = await extractAndProcessHtml(page, removeUnnecessaryHTML);
+    }
+
+    logger.info(`navigate_history completed: ${direction} from ${previousUrl} to ${currentUrl}`);
+
+    return new NavigateHistorySuccessResponse(
+      direction,
+      previousUrl,
+      currentUrl,
+      html,
+      [
+        "Use MCPBrowser's navigate_history to go back or forward again",
+        "Use MCPBrowser's click_element to interact with elements on the page",
+        "Use MCPBrowser's get_current_html to re-read the page content",
+        "Use MCPBrowser's fetch_webpage to navigate to a new URL"
+      ]
+    );
+  } catch (err) {
+    logger.error(`navigate_history failed: ${err.message}`);
+    return new InformationalResponse(
+      `Navigation ${direction} failed: ${err.message}`,
+      'The browser could not navigate. The page may have been closed or the connection was lost.',
+      [
+        "Try MCPBrowser's fetch_webpage to reload the page",
+        "Use MCPBrowser's close_tab and start fresh if needed"
+      ]
+    );
+  }
+}

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);
+}