mcpbrowser 0.3.8 → 0.3.10

package/README.md

@@ -1,4 +1,4 @@
-# MCPBrowser (MCP Browser)
+# ✅ MCPBrowser (MCP Browser)
 
 [![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/cherchyk.mcpbrowser.svg)](https://marketplace.visualstudio.com/items?itemName=cherchyk.mcpbrowser)
 [![npm version](https://img.shields.io/npm/v/mcpbrowser.svg)](https://www.npmjs.com/package/mcpbrowser)
@@ -270,6 +270,28 @@ Environment variables for advanced setup:
 | `CHROME_USER_DATA_DIR` | Browser profile directory | `%LOCALAPPDATA%/ChromeAuthProfile` |
 | `CHROME_REMOTE_DEBUG_PORT` | DevTools port | `9222` |
 
+## Observability & Logging
+
+MCPBrowser logs all operations to help you understand what's happening:
+
+```
+[MCPBrowser] fetch_webpage called: url=https://example.com
+[MCPBrowser] Tab created: example.com
+[MCPBrowser] Navigating to: https://example.com
+[MCPBrowser] Navigation complete: https://example.com (1234ms)
+[MCPBrowser] SPA detected: React, minimal content (0 chars)
+[MCPBrowser] SPA content ready
+[MCPBrowser] fetch_webpage completed: https://example.com
+```
+
+**Error messages are marked with ❌:**
+```
+[MCPBrowser] ❌ fetch_webpage failed: net::ERR_NAME_NOT_RESOLVED
+[MCPBrowser] ❌ No open page found for example.com
+```
+
+Logs go to `stderr` so they don't interfere with MCP protocol on `stdout`.
+
 ## Troubleshooting
 
 **Browser doesn't open?**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "mcpName": "io.github.cherchyk/mcpbrowser",
   "type": "module",
   "description": "MCP browser server - fetch web pages using real Chrome/Edge browser. Handles authentication, SSO, CAPTCHAs, and anti-bot protection. Browser automation for AI assistants.",

package/src/actions/click-element.js

@@ -27,6 +27,7 @@
 import { getBrowser, domainPages } from '../core/browser.js';
 import { extractAndProcessHtml, waitForPageStability } from '../core/page.js';
 import { MCPResponse, ErrorResponse } from '../core/responses.js';
+import logger from '../core/logger.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -153,6 +154,8 @@ export const CLICK_ELEMENT_TOOL = {
  * });
  */
 export async function clickElement({ url, selector, text, waitForElementTimeout = 30000, returnHtml = true, removeUnnecessaryHTML = true, postClickWait = 1000 }) {
+  logger.info(`click_element called: ${selector || `text="${text}"`}`);
+  
   if (!url) {
     throw new Error("url parameter is required");
   }
@@ -172,6 +175,7 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
   let page = domainPages.get(hostname);
   
   if (!page || page.isClosed()) {
+    logger.error(`No open page found for ${hostname}`);
     return new ErrorResponse(
       `No open page found for ${hostname}. Please fetch the page first using fetch_webpage.`,
       [
@@ -232,11 +236,13 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
     // await page.evaluate(el => el.scrollIntoView({ behavior: 'smooth', block: 'center' }), elementHandle);
     // await new Promise(r => setTimeout(r, 300)); // Brief delay after scroll
     
+    logger.info(`Clicking: ${selector || `text="${text}"`}`);
     await elementHandle.click();
     
     if (returnHtml) {
       // Wait for page to stabilize (handles both navigation and SPA content updates)
       // This ensures content is fully loaded before returning, just like fetch_webpage does
+      logger.info('Waiting for page stability...');
       await waitForPageStability(page);
       
       // Wait for SPAs to render dynamic content after click
@@ -247,6 +253,8 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       const currentUrl = page.url();
       const html = await extractAndProcessHtml(page, removeUnnecessaryHTML);
       
+      logger.info(`click_element completed: ${selector || `text="${text}"`}`);
+      
       return new ClickElementSuccessResponse(
         currentUrl,
         selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`,
@@ -260,6 +268,7 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       );
     } else {
       // Wait for page to stabilize even for fast clicks (ensures JS has finished)
+      logger.info('Waiting for page stability (fast mode)...');
       await waitForPageStability(page);
       
       // Wait for SPAs to render dynamic content after click
@@ -269,6 +278,8 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       
       const currentUrl = page.url();
       
+      logger.info(`click_element completed: ${selector || `text="${text}"`}`);
+      
       return new ClickElementSuccessResponse(
         currentUrl,
         selector ? `Clicked element: ${selector}` : `Clicked element with text: "${text}"`,
@@ -281,6 +292,7 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       );
     }
   } catch (err) {
+    logger.error(`click_element failed: ${err.message}`);
     return new ErrorResponse(
       `Failed to click element: ${err.message}`,
       [

package/src/actions/close-tab.js

@@ -4,6 +4,7 @@
 
 import { domainPages } from '../core/browser.js';
 import { MCPResponse, ErrorResponse } from '../core/responses.js';
+import logger from '../core/logger.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -95,6 +96,9 @@ export const CLOSE_TAB_TOOL = {
  * @returns {Promise<object>} Result indicating success or failure
  */
 export async function closeTab({ url }) {
+  const startTime = Date.now();
+  logger.info(`close_tab called: url=${url}`);
+  
   try {
     // Validate URL
     if (!url || typeof url !== 'string') {
@@ -171,7 +175,7 @@ export async function closeTab({ url }) {
     // Remove from domain pool
     domainPages.delete(hostname);
     
-    console.error(`[MCPBrowser] Closed tab for hostname: ${hostname}`);
+    logger.info(`close_tab completed: closed tab for ${hostname}`);
     
     return new CloseTabSuccessResponse(
       `Successfully closed tab for ${hostname}`,
@@ -182,7 +186,7 @@ export async function closeTab({ url }) {
     );
     
   } catch (error) {
-    console.error(`[MCPBrowser] Error closing tab:`, error);
+    logger.error(`close_tab failed: ${error.message}`);
     return new ErrorResponse(
       error.message,
       [

package/src/actions/fetch-page.js

@@ -7,6 +7,7 @@ import { getBrowser, domainPages } from '../core/browser.js';
 import { getOrCreatePage, queueRequest, navigateToUrl, waitForPageReady, extractAndProcessHtml, waitForPageStability } from '../core/page.js';
 import { detectRedirectType, waitForAutoAuth, waitForManualAuth } from '../core/auth.js';
 import { MCPResponse, ErrorResponse } from '../core/responses.js';
+import logger from '../core/logger.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -113,12 +114,15 @@ export const FETCH_WEBPAGE_TOOL = {
  * @returns {Promise<Object>} Result object with success status, URL, HTML content, or error details
  */
 export async function fetchPage({ url, browser = '', removeUnnecessaryHTML = true, postLoadWait = 0 }) {
+  logger.info(`fetch_webpage called: url=${url}`);
+  
   // Handle missing URL with environment variable fallback
   if (!url) {
     const fallbackUrl = process.env.DEFAULT_FETCH_URL || process.env.MCP_DEFAULT_FETCH_URL;
     if (fallbackUrl) {
       url = fallbackUrl;
     } else {
+      logger.error("Missing url parameter");
       return new ErrorResponse(
         "Missing url parameter and no DEFAULT_FETCH_URL/MCP_DEFAULT_FETCH_URL configured",
         ["Set DEFAULT_FETCH_URL or MCP_DEFAULT_FETCH_URL environment variable", "Provide url parameter in the request"]
@@ -131,6 +135,7 @@ export async function fetchPage({ url, browser = '', removeUnnecessaryHTML = tru
   try {
     hostname = new URL(url).hostname;
   } catch {
+    logger.error(`Invalid URL: ${url}`);
     return new ErrorResponse(`Invalid URL: ${url}`, []);
   }
 
@@ -170,7 +175,7 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
     const redirectInfo = detectRedirectType(url, hostname, currentUrl, currentHostname);
     
     if (redirectInfo.type === 'requested_auth') {
-      console.error(`[MCPBrowser] User requested auth page directly, returning content`);
+      logger.info('User requested auth page directly, returning content');
       // Update domain mapping if needed
       if (redirectInfo.currentHostname !== hostname) {
         domainPages.delete(hostname);
@@ -178,13 +183,13 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
         hostname = redirectInfo.currentHostname;
       }
     } else if (redirectInfo.type === 'permanent') {
-      console.error(`[MCPBrowser] Permanent redirect detected: ${hostname} → ${redirectInfo.currentHostname}`);
+      logger.info(`Redirect: ${hostname} → ${redirectInfo.currentHostname}`);
       
       // Check if we already have a tab for the redirected hostname
       // (can happen after reconnect - we mapped mail.google.com but not gmail.com)
       const existingPage = domainPages.get(redirectInfo.currentHostname);
       if (existingPage && existingPage !== page && !existingPage.isClosed()) {
-        console.error(`[MCPBrowser] Found existing tab for ${redirectInfo.currentHostname}, reusing it`);
+        logger.info(`Found existing tab for ${redirectInfo.currentHostname}, reusing it`);
         // Close the new tab we just opened, use the existing one
         await page.close().catch(() => {});
         domainPages.delete(hostname);
@@ -192,20 +197,20 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
         // Map original hostname to existing page
         domainPages.set(hostname, existingPage);
       } else {
-        console.error(`[MCPBrowser] Mapping both hostnames to same tab for future reuse`);
         // Map both original and final hostname to the same page
         domainPages.set(hostname, page);
         domainPages.set(redirectInfo.currentHostname, page);
       }
       hostname = redirectInfo.currentHostname;
     } else if (redirectInfo.type === 'auth') {
-      console.error(`[MCPBrowser] Authentication flow detected (${redirectInfo.flowType})`);
-      console.error(`[MCPBrowser] Current location: ${redirectInfo.currentUrl}`);
+      logger.info(`Authentication required: ${redirectInfo.flowType}`);
+      logger.info(`Auth URL: ${redirectInfo.currentUrl}`);
       
       // Try auto-auth first (check if existing session works)
       const autoAuthResult = await waitForAutoAuth(page);
       
       if (autoAuthResult.success) {
+        logger.info(`Auto-auth successful, now at: ${page.url()}`);
         // Update hostname to where we landed
         if (autoAuthResult.hostname !== hostname) {
           domainPages.delete(hostname);
@@ -217,6 +222,7 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
         const manualAuthResult = await waitForManualAuth(page, authCompletionTimeout);
         
         if (!manualAuthResult.success) {
+          logger.error(`Authentication failed: ${manualAuthResult.error}`);
           return new ErrorResponse(
             manualAuthResult.error,
             [
@@ -233,6 +239,7 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
           domainPages.set(manualAuthResult.hostname, page);
           hostname = manualAuthResult.hostname;
         }
+        logger.info(`Authentication successful, now at: ${page.url()}`);
       }
       
       // Wait for page stability after auth
@@ -241,13 +248,15 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
     
     // Additional wait if requested (for pages that need extra time)
     if (postLoadWait > 0) {
-      console.error(`[MCPBrowser] Waiting ${postLoadWait}ms (postLoadWait)...`);
+      logger.info(`Waiting ${postLoadWait}ms (postLoadWait)...`);
       await new Promise(resolve => setTimeout(resolve, postLoadWait));
     }
     
     // Extract and process HTML
     const processedHtml = await extractAndProcessHtml(page, removeUnnecessaryHTML);
     
+    logger.info(`fetch_webpage completed: ${page.url()}`);
+    
     return new FetchPageSuccessResponse(
       page.url(),
       processedHtml,
@@ -259,6 +268,7 @@ async function doFetchPage({ url, hostname, browser, removeUnnecessaryHTML, post
       ]
     );
   } catch (err) {
+    logger.error(`fetch_webpage failed: ${err.message || String(err)}`);
     return new ErrorResponse(
       err.message || String(err),
       [

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

@@ -5,6 +5,7 @@
 import { getBrowser, domainPages } from '../core/browser.js';
 import { extractAndProcessHtml } from '../core/page.js';
 import { MCPResponse, ErrorResponse } from '../core/responses.js';
+import logger from '../core/logger.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -98,6 +99,9 @@ export const GET_CURRENT_HTML_TOOL = {
  * @returns {Promise<Object>} Result object with current HTML
  */
 export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
+  const startTime = Date.now();
+  logger.info(`get_current_html called: url=${url}`);
+  
   if (!url) {
     throw new Error("url parameter is required");
   }
@@ -113,6 +117,7 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
   let page = domainPages.get(hostname);
   
   if (!page || page.isClosed()) {
+    logger.error(`get_current_html: No open page found for ${hostname}`);
     return new ErrorResponse(
       `No open page found for ${hostname}. Please fetch the page first using fetch_webpage.`,
       [
@@ -125,6 +130,8 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
     const currentUrl = page.url();
     const html = await extractAndProcessHtml(page, removeUnnecessaryHTML);
     
+    logger.info(`get_current_html completed: got HTML from ${currentUrl}`);
+    
     return new GetCurrentHtmlSuccessResponse(
       currentUrl,
       html,
@@ -135,6 +142,7 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
       ]
     );
   } catch (err) {
+    logger.error(`get_current_html failed: ${err.message}`);
     return new ErrorResponse(
       `Failed to get HTML: ${err.message}`,
       [

package/src/actions/type-text.js

@@ -5,6 +5,7 @@
 import { getBrowser, domainPages } from '../core/browser.js';
 import { extractAndProcessHtml, waitForPageStability } from '../core/page.js';
 import { MCPResponse, ErrorResponse } from '../core/responses.js';
+import logger from '../core/logger.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -121,6 +122,9 @@ export const TYPE_TEXT_TOOL = {
  * @returns {Promise<Object>} Result object with success status and details
  */
 export async function typeText({ url, selector, text, clear = true, typeDelay = 50, waitForElementTimeout = 30000, returnHtml = true, removeUnnecessaryHTML = true, postTypeWait = 1000 }) {
+  const startTime = Date.now();
+  logger.info(`type_text called: selector=${selector}, url=${url}`);
+  
   if (!url) {
     throw new Error("url parameter is required");
   }
@@ -144,6 +148,7 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
   let page = domainPages.get(hostname);
   
   if (!page || page.isClosed()) {
+    logger.error(`type_text: No open page found for ${hostname}`);
     return new ErrorResponse(
       `No open page found for ${hostname}. Please fetch the page first using fetch_webpage_protected.`,
       [
@@ -160,10 +165,12 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
       await page.keyboard.press('Backspace');
     }
     
+    logger.info(`Typing into: ${selector}`);
     await page.type(selector, String(text), { delay: typeDelay });
     
     if (returnHtml) {
       // Wait for page to stabilize (handles form validation, autocomplete, etc.)
+      logger.info('Waiting for page stability after typing...');
       await waitForPageStability(page);
       
       // Wait for SPAs to render dynamic content after typing
@@ -174,6 +181,8 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
       const currentUrl = page.url();
       const html = await extractAndProcessHtml(page, removeUnnecessaryHTML);
       
+      logger.info(`type_text completed: typed into ${selector}`);
+      
       return new TypeTextSuccessResponse(
         currentUrl,
         `Typed text into: ${selector}`,
@@ -187,6 +196,7 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
       );
     } else {
       // Wait for page to stabilize even without returning HTML
+      logger.info('Waiting for page stability after typing (fast mode)...');
       await waitForPageStability(page);
       
       // Wait for SPAs to render dynamic content after typing
@@ -196,6 +206,8 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
       
       const currentUrl = page.url();
       
+      logger.info(`type_text completed: typed into ${selector} (no HTML)`);
+      
       return new TypeTextSuccessResponse(
         currentUrl,
         `Typed text into: ${selector}`,
@@ -208,6 +220,7 @@ export async function typeText({ url, selector, text, clear = true, typeDelay =
       );
     }
   } catch (err) {
+    logger.error(`type_text failed: ${err.message}`);
     return new ErrorResponse(
       `Failed to type text: ${err.message}`,
       [

package/src/browsers/ChromiumBrowser.js

@@ -10,6 +10,7 @@ import { existsSync } from "fs";
 import os from "os";
 import path from "path";
 import { spawn } from "child_process";
+import logger from '../core/logger.js';
 
 /**
  * Base class for all Chromium-based browsers
@@ -115,7 +116,7 @@ export class ChromiumBrowser extends BaseBrowser {
         '--no-default-browser-check'
       ];
 
-      console.error(`[MCPBrowser] Launching ${this.config.name} with remote debugging on port ${this.config.port}...`);
+      logger.info(`Launching ${this.config.name} with remote debugging on port ${this.config.port}...`);
       
       const child = spawn(execPath, args, {
         detached: true,
@@ -129,7 +130,7 @@ export class ChromiumBrowser extends BaseBrowser {
       
       while (Date.now() - startTime < maxWaitTime) {
         if (await this.devtoolsAvailable()) {
-          console.error(`[MCPBrowser] ${this.config.name} is ready on port ${this.config.port}`);
+          logger.info(`Connected to ${this.config.name} on port ${this.config.port}`);
           return;
         }
         await new Promise(resolve => setTimeout(resolve, 500));

package/src/core/auth.js

@@ -3,6 +3,7 @@
  */
 
 import { getBaseDomain } from '../utils.js';
+import logger from './logger.js';
 
 // ============================================================================
 // AUTH URL DETECTION
@@ -123,7 +124,7 @@ export function detectRedirectType(url, hostname, currentUrl, currentHostname) {
  * @returns {Promise<Object>} Object with success status and final hostname
  */
 export async function waitForAutoAuth(page, timeoutMs = DEFAULT_AUTO_AUTH_TIMEOUT) {
-  console.error(`[MCPBrowser] Checking for auto-authentication (${timeoutMs / 1000} sec)...`);
+  logger.info(`Checking for auto-authentication (${timeoutMs}ms timeout)...`);
   
   const deadline = Date.now() + timeoutMs;
   
@@ -135,7 +136,7 @@ export async function waitForAutoAuth(page, timeoutMs = DEFAULT_AUTO_AUTH_TIMEOU
       // Browser handles redirects - we just need to detect when auth flow ends
       if (!isLikelyAuthUrl(checkUrl)) {
         const checkHostname = new URL(checkUrl).hostname;
-        console.error(`[MCPBrowser] Auto-authentication successful! Now at: ${checkUrl}`);
+        logger.info(`Auto-authentication successful: ${checkUrl}`);
         return { success: true, hostname: checkHostname };
       }
       
@@ -241,12 +242,11 @@ export async function waitForManualAuth(page, timeoutMs = DEFAULT_MANUAL_AUTH_TI
   
   // Log login page detection
   if (isLoginPage && shouldExtendTimeout) {
-    console.error(`[MCPBrowser] 🔐 LOGIN PAGE DETECTED!`);
-    console.error(`[MCPBrowser] Indicators found: ${loginDetection.indicators.join(', ')}`);
-    console.error(`[MCPBrowser] Extended wait time to ${effectiveTimeoutMinutes} minutes for user authentication`);
+    logger.info(`Login page detected: ${page.url()} (${loginDetection.indicators.join(', ')})`);
+    logger.info(`Extended wait time to ${effectiveTimeoutMinutes} minutes for user authentication`);
   }
   
-  console.error(`[MCPBrowser] Auto-authentication did not complete. Waiting for user...`);
+  logger.info(`Waiting for manual authentication (${effectiveTimeoutMinutes} min timeout, loginPage=${isLoginPage})...`);
   
   // Send initial waiting notification
   if (onStatusChange) {
@@ -262,8 +262,6 @@ export async function waitForManualAuth(page, timeoutMs = DEFAULT_MANUAL_AUTH_TI
     });
   }
   
-  console.error(`[MCPBrowser] Waiting for user to complete authentication (${effectiveTimeoutMinutes} min timeout)...`);
-  
   const deadline = Date.now() + effectiveTimeout;
   let lastStatusUpdate = Date.now();
   
@@ -274,7 +272,7 @@ export async function waitForManualAuth(page, timeoutMs = DEFAULT_MANUAL_AUTH_TI
       // Auth complete when we leave the auth page
       if (!isLikelyAuthUrl(checkUrl)) {
         const checkHostname = new URL(checkUrl).hostname;
-        console.error(`[MCPBrowser] ✅ Authentication completed! Now at: ${checkUrl}`);
+        logger.info(`Manual authentication successful: ${checkUrl}`);
         
         if (onStatusChange) {
           onStatusChange({

package/src/core/browser.js

@@ -6,6 +6,7 @@
 import { ChromeBrowser } from '../browsers/chrome.js';
 import { EdgeBrowser } from '../browsers/edge.js';
 import os from 'os';
+import logger from './logger.js';
 
 // Browser state
 export let cachedBrowser = null;
@@ -29,13 +30,13 @@ async function detectDefaultBrowser() {
   
   for (const browser of browsers) {
     if (await browser.isAvailable()) {
-      console.error(`[MCPBrowser] Auto-detected ${browser.getType()} as default browser`);
+      logger.info(`Auto-detected ${browser.getType()} as default browser`);
       return browser.getType();
     }
   }
   
   // Fallback to Chrome
-  console.error('[MCPBrowser] No browser detected, defaulting to Chrome');
+  logger.info('No browser detected, defaulting to Chrome');
   return 'chrome';
 }
 
@@ -88,7 +89,7 @@ export async function GetBrowser(type = '') {
 export async function rebuildDomainPagesMap(browser) {
   try {
     const pages = await browser.pages();
-    console.error(`[MCPBrowser] Reconnected to browser with ${pages.length} existing tabs`);
+    logger.info(`Reconnected to browser with ${pages.length} existing tabs`);
     
     for (const page of pages) {
       try {
@@ -105,7 +106,7 @@ export async function rebuildDomainPagesMap(browser) {
         const hostname = new URL(pageUrl).hostname;
         if (hostname && !domainPages.has(hostname)) {
           domainPages.set(hostname, page);
-          console.error(`[MCPBrowser] Mapped existing tab for domain: ${hostname} (${pageUrl})`);
+          logger.info(`Tab mapped: ${hostname}`);
         }
       } catch (err) {
         // Skip pages that are inaccessible or have invalid URLs
@@ -114,10 +115,10 @@ export async function rebuildDomainPagesMap(browser) {
     }
     
     if (domainPages.size > 0) {
-      console.error(`[MCPBrowser] Restored ${domainPages.size} domain-to-tab mappings`);
+      logger.info(`Restored ${domainPages.size} domain-to-tab mappings`);
     }
   } catch (err) {
-    console.error(`[MCPBrowser] Warning: Could not rebuild domain pages map: ${err.message}`);
+    logger.info(`Could not rebuild domain pages map: ${err.message}`);
   }
 }
 

package/src/core/logger.js

@@ -0,0 +1,26 @@
+/**
+ * Logger - Simple logging for MCPBrowser
+ * 
+ * All output goes to stderr so it doesn't interfere with MCP protocol on stdout.
+ */
+
+const PREFIX = '[MCPBrowser]';
+
+/**
+ * Log an info message
+ * @param {string} message - The message to log
+ */
+function info(message) {
+  console.error(`${PREFIX} ${message}`);
+}
+
+/**
+ * Log an error message
+ * @param {string} message - The message to log
+ */
+function error(message) {
+  console.error(`${PREFIX} ❌ ${message}`);
+}
+
+export const logger = { info, error };
+export default logger;

package/src/core/page.js

@@ -7,6 +7,7 @@
 
 import { domainPages } from './browser.js';
 import { cleanHtml, enrichHtml } from './html.js';
+import logger from './logger.js';
 
 // ============================================================================
 // SIMPLE REQUEST QUEUE (No Locks)
@@ -42,7 +43,7 @@ async function processQueue() {
     const queueLength = requestQueue.length;
     
     if (queueLength > 0) {
-      console.error(`[MCPBrowser] Processing request (${queueLength} more in queue)`);
+      logger.info(`Queue: ${queueLength} requests waiting`);
     }
     
     try {
@@ -78,7 +79,7 @@ export async function getOrCreatePage(browser, hostname, reuseLastKeptPage = tru
     if (!existingPage.isClosed()) {
       page = existingPage;
       await page.bringToFront().catch(() => {});
-      console.error(`[MCPBrowser] Reusing existing tab for domain: ${hostname}`);
+      logger.info(`Tab reused: ${hostname}`);
     } else {
       // Page was closed externally, remove from map
       domainPages.delete(hostname);
@@ -110,7 +111,7 @@ export async function getOrCreatePage(browser, hostname, reuseLastKeptPage = tru
     }
     // Add new page to domain map
     domainPages.set(hostname, page);
-    console.error(`[MCPBrowser] Created new tab for domain: ${hostname}`);
+    logger.info(`Tab created: ${hostname}`);
   }
   
   return page;
@@ -196,7 +197,7 @@ export async function isItSPA(page) {
  * @returns {Promise<void>}
  */
 export async function navigateToUrl(page, url, waitUntil, timeout) {
-  console.error(`[MCPBrowser] Navigating to: ${url}`);
+  logger.info(`Navigating to: ${url}`);
   
   const startTime = Date.now();
   
@@ -204,10 +205,10 @@ export async function navigateToUrl(page, url, waitUntil, timeout) {
     await page.goto(url, { waitUntil, timeout });
     
     const loadTime = Date.now() - startTime;
-    console.error(`[MCPBrowser] Navigation completed in ${loadTime}ms: ${page.url()}`);
+    logger.info(`Navigation complete: ${page.url()} (${loadTime}ms)`);
   } catch (error) {
     const elapsed = Date.now() - startTime;
-    console.error(`[MCPBrowser] Navigation error after ${elapsed}ms: ${error.message}`);
+    logger.error(`Navigation failed: ${error.message} after ${elapsed}ms`);
     throw error;
   }
 }
@@ -222,8 +223,7 @@ export async function waitForPageReady(page) {
   const spaCheck = await isItSPA(page);
   
   if (spaCheck.isSPA) {
-    console.error(`[MCPBrowser] 🔄 SPA detected: ${spaCheck.indicators.join(', ')}`);
-    console.error(`[MCPBrowser] Waiting for JavaScript to render content...`);
+    logger.info(`SPA detected: ${spaCheck.indicators.join(', ')}`);
     
     // Wait for SPA to render
     await new Promise(resolve => setTimeout(resolve, 3000));
@@ -234,7 +234,7 @@ export async function waitForPageReady(page) {
     } catch {
       // OK if timeout - SPA might have websockets or long-polling
     }
-    console.error(`[MCPBrowser] SPA content ready`);
+    logger.info('SPA content ready');
   } else {
     // For non-SPAs, just wait briefly for any pending network requests
     try {
@@ -252,17 +252,17 @@ export async function waitForPageReady(page) {
  * @returns {Promise<void>}
  */
 export async function waitForPageStability(page) {
-  console.error(`[MCPBrowser] Waiting for page to stabilize...`);
+  logger.info('Waiting for page stability (network idle)...');
   
   // Give time for any triggered actions to complete
   await new Promise(resolve => setTimeout(resolve, 2000));
   
   try {
     await page.waitForNetworkIdle({ timeout: 5000 });
-    console.error(`[MCPBrowser] Page stabilized`);
+    logger.info('Page stabilized');
   } catch {
     // Ignore timeout - page may have long-polling or websockets
-    console.error(`[MCPBrowser] Network still active, continuing anyway`);
+    logger.info('Network still active, continuing anyway');
   }
 }
 

package/src/mcp-browser.js

@@ -14,6 +14,7 @@ import { dirname, join } from 'path';
 
 // Import response classes
 import { ErrorResponse } from './core/responses.js';
+import logger from './core/logger.js';
 
 // Import core functionality
 import { fetchPage, FETCH_WEBPAGE_TOOL } from './actions/fetch-page.js';
@@ -91,6 +92,7 @@ async function main() {
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  logger.info(`MCPBrowser server v${packageJson.version} started`);
 }
 
 // Export for testing
@@ -123,7 +125,7 @@ export {
 if (import.meta.url === new URL(process.argv[1], 'file://').href || 
     fileURLToPath(import.meta.url) === process.argv[1]) {
   main().catch((err) => {
-    console.error(err);
+    logger.error(`Server failed: ${err.message}`);
     process.exit(1);
   });
 }