mcpbrowser 0.3.48 → 0.3.49

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.48",
+  "version": "0.3.49",
   "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.",
+  "description": "MCP browser server — load and interact with any web page using a real Chrome/Edge/Brave browser with full JavaScript execution. Handles login flows, authentication, SSO, CAPTCHAs, and anti-bot protection. Use whenever a real browser is needed to load a page, especially when JavaScript rendering or user login is required.",
   "main": "src/mcp-browser.js",
   "bin": {
     "mcpbrowser": "src/mcp-browser.js"
@@ -38,7 +38,10 @@
     "claude",
     "ai-assistant",
     "cdp",
-    "devtools"
+    "devtools",
+    "javascript-rendering",
+    "login",
+    "interactive"
   ],
   "author": "cherchyk",
   "license": "MIT",

package/src/actions/click-element.js

@@ -88,7 +88,7 @@ export class ClickWithFallbackResponse extends MCPResponse {
 export const CLICK_ELEMENT_TOOL = {
   name: "browser_click_element",
   title: "Click Element",
-  description: "**BROWSER INTERACTION** - Clicks elements on browser-loaded pages. Use this for navigation (clicking links/buttons), form submission, and any user interaction that requires clicking.\n\nWorks with any clickable element including buttons, links, or elements with onclick handlers. Can target by CSS selector or text content. Waits for page stability and returns updated HTML by default.\n\n**PREREQUISITE**: Page MUST be loaded with browser_fetch_webpage first. This tool operates on an already-loaded page in the browser.",
+  description: "Click buttons, links, or any element on a browser-loaded page. Use when: you need to navigate a website, submit a form, press a button, follow a link, or interact with any clickable UI element. Targets by CSS selector or visible text. Returns updated page HTML after click. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
   inputSchema: {
     type: "object",
     properties: {

package/src/actions/close-tab.js

@@ -59,7 +59,7 @@ export class CloseTabSuccessResponse extends MCPResponse {
 export const CLOSE_TAB_TOOL = {
   name: "browser_close_tab",
   title: "Close Tab",
-  description: "**BROWSER MANAGEMENT** - Closes the browser tab for the given URL's hostname. This removes the page from the tab pool and forces a fresh session on the next visit to that hostname. Useful for memory management or when you need to clear session state. Note: Uses exact hostname match (www.example.com and example.com are treated as different tabs).",
+  description: "Close a browser tab to free resources. Use when: you are done with a page and want to release memory, or need to reset session state for a hostname. Uses exact hostname match.",
   inputSchema: {
     type: "object",
     properties: {

package/src/actions/detect-forms.js

@@ -74,7 +74,7 @@ export class DetectFormsResponse extends MCPResponse {
 export const DETECT_FORMS_TOOL = {
   name: "browser_detect_forms",
   title: "Detect Forms",
-  description: "**AUTO FORM DISCOVERY** - Scans the current page and returns structured JSON of all forms: fields (name, type, required, placeholder, current value, validation constraints), submit buttons, and orphaned inputs not inside any <form> (common in SPAs). Use this BEFORE filling forms to understand what fields exist and how to interact with them.\n\n**PREREQUISITE**: Page MUST be loaded with browser_fetch_webpage first.",
+  description: "Scan a browser-loaded page and return all forms as structured JSON — fields, types, validation rules, submit buttons, and orphaned inputs. Use when: you need to understand a form before filling it, discover what fields exist on a page, or map form structure for automation. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
   inputSchema: {
     type: "object",
     properties: {

package/src/actions/execute-javascript.js

@@ -59,7 +59,7 @@ export class ExecuteJavascriptResponse extends MCPResponse {
 export const EXECUTE_JAVASCRIPT_TOOL = {
   name: 'browser_execute_javascript',
   title: 'Execute JavaScript',
-  description: '**BROWSER INTERACTION** - Executes a JavaScript snippet in the active page and returns the result with metadata (execution time, truncation, navigation detection). Use for structured extraction or UI actions that are unreliable via protocol clicks.',
+  description: 'Run JavaScript on a browser-loaded page and get the result. Use when: you need to extract structured data from a page, manipulate the DOM, read page state, run custom queries on page content, or perform UI actions that CSS selectors cannot reach. Returns the script result as JSON, text, or void. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.',
   inputSchema: {
     type: 'object',
     properties: {

package/src/actions/fetch-page.js

@@ -74,7 +74,7 @@ export class FetchPageSuccessResponse extends MCPResponse {
 export const FETCH_WEBPAGE_TOOL = {
   name: "browser_fetch_webpage",
   title: "Fetch Web Page",
-  description: "Fetches web pages using Chrome/Edge browser with full JavaScript rendering and authentication support. **REQUIRED for corporate/enterprise sites, any page requiring login/SSO, anti-bot/CAPTCHA pages, and JavaScript-heavy applications.** Use this as the DEFAULT for all webpage fetching - it handles simple HTML pages too. Opens browser for user authentication when needed. Never use generic HTTP fetch for pages that might require authentication.",
+  description: "Load any URL and return its content using a real browser with full JavaScript execution. Use when: user shares a URL, you need to read a webpage, fetch content from a link, open a page, check a website, load a GitHub PR/issue, read documentation, or access any HTTP/HTTPS resource. Handles JavaScript rendering, login/SSO, CAPTCHA, and anti-bot protection automatically. Works on all sites including those behind authentication. Prefer this over generic HTTP fetch — it always works, even on authenticated or JS-heavy pages that require proper JavaScript execution or user login.",
   inputSchema: {
     type: "object",
     properties: {

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

@@ -72,7 +72,7 @@ export class GetCurrentHtmlSuccessResponse extends MCPResponse {
 export const GET_CURRENT_HTML_TOOL = {
   name: "browser_get_current_html",
   title: "Get Current HTML",
-  description: "**BROWSER STATE EXTRACTION** - Retrieves current HTML from an already-loaded page WITHOUT navigating/reloading. Use this to check page state after interactions (click, type) or to re-examine the current page. Much faster than browser_fetch_webpage since it only extracts HTML from the current page state.\n\n**PREREQUISITE**: Page MUST be loaded with browser_fetch_webpage first. This tool reads from an already-loaded page in the browser.",
+  description: "Re-read HTML from an already-loaded page without reloading it. Use when: you need to check page state after a click or form fill, re-extract content from the current page, or get updated HTML after dynamic changes. Much faster than browser_fetch_webpage since it skips navigation. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
   inputSchema: {
     type: "object",
     properties: {

package/src/actions/navigate-history.js

@@ -71,7 +71,7 @@ export class NavigateHistorySuccessResponse extends MCPResponse {
 export const NAVIGATE_HISTORY_TOOL = {
   name: "browser_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 browser_fetch_webpage first. This tool navigates the history of an existing browser tab.",
+  description: "Go back or forward in browser history. Use when: you clicked a link and need to return to the previous page, or want to go forward after going back. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
   inputSchema: {
     type: "object",
     properties: {

package/src/actions/plugin-action.js

@@ -38,17 +38,17 @@ export class PluginActionSuccessResponse extends MCPResponse {
 export const PLUGIN_ACTION_TOOL = {
   name: "browser_plugin_action",
   title: "Plugin Action",
-  description: "Execute a site-specific plugin action. Use browser_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.",
+  description: "Execute a site-specific plugin action. Call browser_plugin_info first to discover available plugins and their actions.",
   inputSchema: {
     type: "object",
     properties: {
       plugin: {
         type: "string",
-        description: "Plugin name (e.g., 'gmail', 'outlook', 'powerbi')"
+        description: "Plugin name (use browser_plugin_info to list available plugins)"
       },
       action: {
         type: "string",
-        description: "Action name within the plugin (e.g., 'list_emails', 'extract_grid')"
+        description: "Action name within the plugin (use browser_plugin_info to discover available actions)"
       },
       params: {
         type: "object",

package/src/actions/plugin-info.js

@@ -55,7 +55,7 @@ export class PluginActionDetailResponse extends MCPResponse {
 export const PLUGIN_INFO_TOOL = {
   name: "browser_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 browser_plugin_action. You can also call with no arguments to list all loaded plugins.",
+  description: "List available site-specific plugins and their actions. Use when: browser_fetch_webpage suggests a plugin in nextSteps, or you want to check what optimized actions are available for the current site. Call with no arguments to list all plugins, or with a plugin name for details.",
   inputSchema: {
     type: "object",
     properties: {

package/src/actions/scroll-page.js

@@ -94,7 +94,7 @@ export class ScrollPageSuccessResponse extends MCPResponse {
 export const SCROLL_PAGE_TOOL = {
   name: "browser_scroll_page",
   title: "Scroll Page",
-  description: "**PAGE NAVIGATION** - Scrolls within an already-loaded page. Use before browser_take_screenshot to capture different parts of the page, or to bring elements into view before interaction.\n\n**PREREQUISITE**: Page MUST be loaded with browser_fetch_webpage first.\n\n**SCROLL MODES**:\n- By direction: Scroll up/down/left/right by pixel amount\n- To element: Scroll until a specific element is visible\n- To position: Scroll to absolute coordinates",
+  description: "Scroll within a browser-loaded page. Use when: you need to see more content below the fold, bring an element into view before clicking, scroll to a specific section, or navigate long pages. Supports scroll by direction, to a CSS selector, or to absolute coordinates. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
   inputSchema: {
     type: "object",
     properties: {

package/src/actions/take-screenshot.js

@@ -89,7 +89,7 @@ export class TakeScreenshotSuccessResponse extends MCPResponse {
 export const TAKE_SCREENSHOT_TOOL = {
   name: "browser_take_screenshot",
   title: "Take Screenshot",
-  description: "**VISUAL CAPTURE** - Takes a screenshot of an already-loaded page for visual analysis. Useful when HTML parsing is insufficient or you need to see visual layout, images, charts, or rendered content. Returns a PNG image.\n\n**PREREQUISITE**: Page MUST be loaded with browser_fetch_webpage first. This tool captures the current visual state of the page.",
+  description: "Capture a screenshot of a browser-loaded page as PNG. Use when: you need to see what a page looks like, analyze visual layout, view charts/images/graphs, debug UI issues, or when HTML alone is insufficient to understand the page content. Returns base64-encoded PNG. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
   inputSchema: {
     type: "object",
     properties: {

package/src/actions/type-text.js

@@ -66,7 +66,7 @@ export class TypeTextSuccessResponse extends MCPResponse {
 export const TYPE_TEXT_TOOL = {
   name: "browser_type_text",
   title: "Type Text",
-  description: "**BROWSER INTERACTION** - Types text into multiple input fields on browser-loaded pages in a single call. Use this for filling forms, entering search queries, or any text input on the page.\n\nWorks with input fields, textareas, and other editable elements. Supports filling multiple fields at once for efficient form filling.\n\n**PREREQUISITE**: Page MUST be loaded with browser_fetch_webpage first. This tool operates on an already-loaded page in the browser.",
+  description: "Type text into input fields on a browser-loaded page. Use when: you need to fill a form, enter a search query, type into a text box, or input data into any editable field. Supports filling multiple fields in a single call. PREREQUISITE: Page must be loaded with browser_fetch_webpage first.",
   inputSchema: {
     type: "object",
     properties: {

package/src/mcp-browser.js

@@ -61,15 +61,30 @@ async function main() {
   const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
   
   const server = new Server(
-    { name: "MCP Browser", version: packageJson.version },
+    { name: "MCPBrowser", version: packageJson.version },
     { capabilities: { tools: {}, logging: {} } }
   );
 
   // Wire server to logger so logs flow to agent via notifications/message.
   attachLoggerServer(server);
 
+  // Load plugins before assembling tools so we only expose plugin tools when plugins are enabled
+  const pluginCount = await loadPlugins();
+  if (pluginCount > 0) {
+    logger.info(`${pluginCount} plugin(s) loaded and ready`);
+  }
+
   // Assemble tools from action imports
-  // ACCEPT_EULA_TOOL must be first - it's required before using other tools
+  // Only include plugin tools when plugins are actually enabled, with descriptions referencing loaded plugin names
+  const pluginTools = [];
+  if (pluginCount > 0) {
+    const pluginNames = [...getLoadedPlugins().keys()];
+    const nameList = pluginNames.join(', ');
+    pluginTools.push(
+      { ...PLUGIN_INFO_TOOL, description: `${PLUGIN_INFO_TOOL.description} Enabled plugins: ${nameList}.` },
+      { ...PLUGIN_ACTION_TOOL, description: `${PLUGIN_ACTION_TOOL.description} Enabled plugins: ${nameList}.` }
+    );
+  }
   const tools = [
     // ACCEPT_EULA_TOOL,
     FETCH_WEBPAGE_TOOL,
@@ -82,8 +97,7 @@ async function main() {
     SCROLL_PAGE_TOOL,
     NAVIGATE_HISTORY_TOOL,
     DETECT_FORMS_TOOL,
-    PLUGIN_INFO_TOOL,
-    PLUGIN_ACTION_TOOL
+    ...pluginTools
   ];
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
@@ -182,13 +196,6 @@ 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`);
 }