@dynamicu/chromedebug-mcp 2.3.0 → 2.4.0

package/src/index.js

@@ -14,6 +14,7 @@ import {
   registerProcess,
   findActiveSessions
 } from './services/unified-session-manager.js';
+import logger from './utils/logger.js';
 
 /**
  * Main application class that orchestrates all components
@@ -46,13 +47,23 @@ class ChromePilotApp {
       this.processManager = this.chromeService.getProcessManager();
 
       // Initialize Chrome service (starts HTTP server if needed)
+      logger.info('🚀 Starting ChromeDebug MCP services...');
+
       const serviceResult = await this.chromeService.initialize({
         ...finalOptions,
         sessionManager: this.sessionManager
       });
-      
+
       if (serviceResult.httpServer) {
-        console.error(`Chrome service initialized with HTTP server on port ${serviceResult.httpServer.port}`);
+        logger.info(`✅ HTTP Server Started on port ${serviceResult.httpServer.port}`);
+        logger.debug(`   Status: ${serviceResult.httpServer.status}`);
+      } else if (finalOptions.singleServer) {
+        logger.info('ℹ️  HTTP server disabled (--single-server mode)');
+      } else {
+        logger.error('⚠️  HTTP server failed to start - Chrome extension will not be able to connect');
+        if (serviceResult.httpServer?.error) {
+          logger.error(`   Error: ${serviceResult.httpServer.error}`);
+        }
       }
 
       // Create and configure MCP server
@@ -65,7 +76,7 @@ class ChromePilotApp {
         serviceResult
       };
     } catch (error) {
-      console.error('Failed to initialize Chrome Debug:', error);
+      logger.error('Failed to initialize Chrome Debug:', error);
       throw error;
     }
   }
@@ -82,13 +93,13 @@ class ChromePilotApp {
       // Clean up any existing Chrome Debug processes
       const cleanupResult = await this.processManager.cleanupChromePilotProcesses();
       if (cleanupResult.total > 0) {
-        console.error(`Cleaned up ${cleanupResult.killed.length} existing processes`);
+        logger.debug(`Cleaned up ${cleanupResult.killed.length} existing processes`);
       }
 
       // Start the MCP server
       await this.mcpServer.start();
     } catch (error) {
-      console.error('Failed to start Chrome Debug MCP server:', error);
+      logger.error('Failed to start Chrome Debug MCP server:', error);
       process.exit(1);
     }
   }
@@ -147,7 +158,7 @@ class ChromePilotApp {
           if (i + 1 < argv.length) {
             args.sessionId = argv[++i];
           } else {
-            console.error('--session-id requires a value');
+            logger.error('--session-id requires a value');
             process.exit(1);
           }
           break;
@@ -165,7 +176,7 @@ class ChromePilotApp {
           if (arg.startsWith('--session-id=')) {
             args.sessionId = arg.split('=')[1];
           } else if (arg.startsWith('--')) {
-            console.error(`Unknown argument: ${arg}`);
+            logger.error(`Unknown argument: ${arg}`);
             this.showHelp();
             process.exit(1);
           }
@@ -215,20 +226,20 @@ For more information, see the documentation in CLAUDE.md
    * Graceful shutdown
    */
   async shutdown() {
-    console.error('Shutting down Chrome Debug...');
-    
+    logger.info('Shutting down Chrome Debug...');
+
     try {
       if (this.chromeService) {
         await this.chromeService.cleanup();
       }
-      
+
       if (this.processManager) {
         await this.processManager.killAllManagedProcesses();
       }
-      
-      console.error('Chrome Debug shutdown complete');
+
+      logger.info('Chrome Debug shutdown complete');
     } catch (error) {
-      console.error('Error during shutdown:', error);
+      logger.error('Error during shutdown:', error);
     }
   }
 }
@@ -256,18 +267,18 @@ async function main() {
     // Log session information if verbose
     if (args.verbose) {
       const sessionInfo = getSessionInfo();
-      console.log('Session Information:');
-      console.log(`  Session ID: ${sessionInfo.sessionId}`);
-      console.log(`  PID: ${sessionInfo.pid}`);
-      console.log(`  Port: ${sessionInfo.port}`);
-      console.log(`  Session File: ${sessionInfo.sessionFile}`);
+      logger.debug('Session Information:');
+      logger.debug(`  Session ID: ${sessionInfo.sessionId}`);
+      logger.debug(`  PID: ${sessionInfo.pid}`);
+      logger.debug(`  Port: ${sessionInfo.port}`);
+      logger.debug(`  Session File: ${sessionInfo.sessionFile}`);
 
       // Show other active sessions
       const activeSessions = await findActiveSessions();
       if (activeSessions.length > 1) {
-        console.log(`  Other active sessions: ${activeSessions.length - 1}`);
+        logger.debug(`  Other active sessions: ${activeSessions.length - 1}`);
         activeSessions.filter(s => s.sessionId !== sessionInfo.sessionId).forEach(session => {
-          console.log(`    - ${session.sessionId} (PID: ${session.pid}, Port: ${session.port})`);
+          logger.debug(`    - ${session.sessionId} (PID: ${session.pid}, Port: ${session.port})`);
         });
       }
     }
@@ -277,19 +288,19 @@ async function main() {
 
     await app.start();
   } catch (error) {
-    console.error('Fatal error starting Chrome Debug:', error);
+    logger.error('Fatal error starting Chrome Debug:', error);
     process.exit(1);
   }
 }
 
 // Handle graceful shutdown
 process.on('SIGINT', async () => {
-  console.error('Received SIGINT, shutting down gracefully...');
+  logger.info('Received SIGINT, shutting down gracefully...');
   process.exit(0);
 });
 
 process.on('SIGTERM', async () => {
-  console.error('Received SIGTERM, shutting down gracefully...');
+  logger.info('Received SIGTERM, shutting down gracefully...');
   process.exit(0);
 });
 
@@ -299,7 +310,7 @@ export { ChromePilotApp };
 // Run if this is the main module
 if (import.meta.url === `file://${process.argv[1]}`) {
   main().catch((error) => {
-    console.error('Unhandled error:', error);
+    logger.error('Unhandled error:', error);
     process.exit(1);
   });
 }

package/src/middleware/auth.js

@@ -4,6 +4,7 @@ import { v4 as uuidv4 } from 'uuid';
 import path from 'path';
 import fs from 'fs';
 import { fileURLToPath } from 'url';
+import logger from '../utils/logger.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -26,7 +27,7 @@ try {
     apiKeys = JSON.parse(fs.readFileSync(API_KEYS_FILE, 'utf8'));
   }
 } catch (error) {
-  console.error('Error loading API keys:', error);
+  logger.error('Error loading API keys:', error);
   apiKeys = [];
 }
 
@@ -35,7 +36,7 @@ function saveApiKeys() {
   try {
     fs.writeFileSync(API_KEYS_FILE, JSON.stringify(apiKeys, null, 2));
   } catch (error) {
-    console.error('Error saving API keys:', error);
+    logger.error('Error saving API keys:', error);
   }
 }
 
@@ -134,17 +135,17 @@ function verifyJWT(token) {
 // Authentication middleware
 export function authenticate(req, res, next) {
   // Debug logging for authentication flow
-  console.log(`[AUTH-DEBUG] ${new Date().toISOString()} - ${req.method} ${req.originalUrl}`);
-  console.log(`[AUTH-DEBUG] Client IP: ${req.ip}`);
-  console.log(`[AUTH-DEBUG] X-Forwarded-For: ${req.headers['x-forwarded-for'] || 'none'}`);
-  console.log(`[AUTH-DEBUG] User-Agent: ${req.headers['user-agent'] || 'none'}`);
-  console.log(`[AUTH-DEBUG] Authorization header present: ${!!req.headers.authorization}`);
-  console.log(`[AUTH-DEBUG] X-API-Key header present: ${!!req.headers['x-api-key']}`);
-  console.log(`[AUTH-DEBUG] X-Service-Token header present: ${!!req.headers['x-service-token']}`);
-  
+  logger.debug(`[AUTH-DEBUG] ${new Date().toISOString()} - ${req.method} ${req.originalUrl}`);
+  logger.debug(`[AUTH-DEBUG] Client IP: ${req.ip}`);
+  logger.debug(`[AUTH-DEBUG] X-Forwarded-For: ${req.headers['x-forwarded-for'] || 'none'}`);
+  logger.debug(`[AUTH-DEBUG] User-Agent: ${req.headers['user-agent'] || 'none'}`);
+  logger.debug(`[AUTH-DEBUG] Authorization header present: ${!!req.headers.authorization}`);
+  logger.debug(`[AUTH-DEBUG] X-API-Key header present: ${!!req.headers['x-api-key']}`);
+  logger.debug(`[AUTH-DEBUG] X-Service-Token header present: ${!!req.headers['x-service-token']}`);
+
   // Allow localhost requests from Chrome extension
   const isLocalhost = req.ip === '::1' || req.ip === '127.0.0.1' || req.ip === '::ffff:127.0.0.1';
-  console.log(`[AUTH-DEBUG] Is localhost: ${isLocalhost}`);
+  logger.debug(`[AUTH-DEBUG] Is localhost: ${isLocalhost}`);
   
   if (isLocalhost) {
     // Set a synthetic user for localhost requests with explicit permissions
@@ -162,7 +163,7 @@ export function authenticate(req, res, next) {
         PERMISSIONS.FRAME_WRITE
       ]
     };
-    console.log(`[AUTH-DEBUG] ✅ Localhost bypass granted for user:`, req.user);
+    logger.debug(`[AUTH-DEBUG] ✅ Localhost bypass granted for user:`, req.user);
     return next();
   }
 
@@ -208,7 +209,7 @@ export function authenticate(req, res, next) {
   }
   
   if (!user) {
-    console.log(`[AUTH-DEBUG] ❌ Authentication failed - no valid credentials found`);
+    logger.debug(`[AUTH-DEBUG] ❌ Authentication failed - no valid credentials found`);
     return res.status(401).json({
       error: 'Authentication required',
       message: 'Please provide a valid API key, Bearer token, or service token',
@@ -219,8 +220,8 @@ export function authenticate(req, res, next) {
       }
     });
   }
-  
-  console.log(`[AUTH-DEBUG] ✅ Authentication successful for user:`, {
+
+  logger.debug(`[AUTH-DEBUG] ✅ Authentication successful for user:`, {
     id: user.id,
     name: user.name,
     role: user.role,
@@ -316,11 +317,11 @@ export function deleteApiKey(keyId) {
 // Initialize with default admin key if no keys exist
 if (apiKeys.length === 0) {
   const defaultAdmin = generateApiKey('Default Admin', ROLES.ADMIN);
-  console.log('=== Chrome Debug Security Initialization ===');
-  console.log('Generated default admin API key:');
-  console.log(`API Key: ${defaultAdmin.apiKey}`);
-  console.log('Please save this key securely and create additional keys as needed.');
-  console.log('============================================');
+  logger.info('=== Chrome Debug Security Initialization ===');
+  logger.info('Generated default admin API key:');
+  logger.info(`API Key: ${defaultAdmin.apiKey}`);
+  logger.info('Please save this key securely and create additional keys as needed.');
+  logger.info('============================================');
 }
 
 // Generate MCP service token
@@ -333,7 +334,7 @@ export function generateServiceToken() {
 function validateServiceToken(token) {
   const expectedToken = process.env.MCP_SERVICE_TOKEN;
   if (!expectedToken) {
-    console.warn('MCP_SERVICE_TOKEN not set. Service authentication disabled.');
+    logger.warn('MCP_SERVICE_TOKEN not set. Service authentication disabled.');
     return false;
   }
   return token === expectedToken;
@@ -344,23 +345,23 @@ function initializeMcpServiceToken() {
   if (!process.env.MCP_SERVICE_TOKEN) {
     const serviceToken = generateServiceToken();
     process.env.MCP_SERVICE_TOKEN = serviceToken;
-    console.log('=== ChromeDebug MCP Service Token ===');
-    console.log(`Generated MCP service token: ${serviceToken}`);
-    console.log('This token allows MCP clients to access recordings.');
-    console.log('======================================');
-    
+    logger.info('=== ChromeDebug MCP Service Token ===');
+    logger.info(`Generated MCP service token: ${serviceToken}`);
+    logger.info('This token allows MCP clients to access recordings.');
+    logger.info('======================================');
+
     // Optionally save to .env file for persistence
     try {
       const envPath = path.join(__dirname, '../../.env');
       const envContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8') : '';
-      
+
       if (!envContent.includes('MCP_SERVICE_TOKEN=')) {
         const newEnvContent = envContent + (envContent.endsWith('\n') ? '' : '\n') + `MCP_SERVICE_TOKEN=${serviceToken}\n`;
         fs.writeFileSync(envPath, newEnvContent);
-        console.log('MCP service token saved to .env file');
+        logger.info('MCP service token saved to .env file');
       }
     } catch (error) {
-      console.log('Could not save MCP service token to .env file:', error.message);
+      logger.debug('Could not save MCP service token to .env file:', error.message);
     }
   }
 }

package/src/port-discovery.js

@@ -12,6 +12,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import logger from './utils/logger.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -31,9 +32,9 @@ export function writePortFile(port) {
 
   try {
     fs.writeFileSync(portFilePath, port.toString());
-    console.log(`Port ${port} written to ${portFilePath}`);
+    logger.debug(`Port ${port} written to ${portFilePath}`);
   } catch (error) {
-    console.error('Failed to write port file:', error);
+    logger.error('Failed to write port file:', error);
   }
 }
 
@@ -52,7 +53,7 @@ export function readPortFile() {
       }
     }
   } catch (error) {
-    console.error('Failed to read port file:', error);
+    logger.error('Failed to read port file:', error);
   }
 
   return null;
@@ -67,10 +68,10 @@ export function removePortFile() {
   try {
     if (fs.existsSync(portFilePath)) {
       fs.unlinkSync(portFilePath);
-      console.log(`Removed port file: ${portFilePath}`);
+      logger.debug(`Removed port file: ${portFilePath}`);
     }
   } catch (error) {
-    console.error('Failed to remove port file:', error);
+    logger.error('Failed to remove port file:', error);
   }
 }
 
@@ -114,7 +115,7 @@ export async function discoverServer(preferredPorts = [3000, 3001, 3002, 3028],
       if (response.ok) {
         const data = await response.json();
         if (data.status === 'online') {
-          console.log(`Discovered ChromeDebug server on port ${port}`);
+          logger.debug(`Discovered ChromeDebug server on port ${port}`);
           return port;
         }
       }

package/src/services/failover-manager.js

@@ -14,6 +14,7 @@
  */
 
 import { EventEmitter } from 'events';
+import logger from '../utils/logger.js';
 
 export class FailoverManager extends EventEmitter {
   constructor(options = {}) {
@@ -51,7 +52,7 @@ export class FailoverManager extends EventEmitter {
     this.healthCheckTimer = null;
     this.recoveryTimer = null;
 
-    console.log('[FailoverManager] Initialized with failover management');
+    logger.debug('[FailoverManager] Initialized with failover management');
   }
 
   /**
@@ -65,9 +66,9 @@ export class FailoverManager extends EventEmitter {
       this.startHealthMonitoring();
 
       this.initialized = true;
-      console.log('[FailoverManager] Initialized successfully');
+      logger.debug('[FailoverManager] Initialized successfully');
     } catch (error) {
-      console.error('[FailoverManager] Initialization failed:', error);
+      logger.error('[FailoverManager] Initialization failed:', error);
       throw error;
     }
   }
@@ -111,7 +112,7 @@ export class FailoverManager extends EventEmitter {
       this.daemonHealthy = false;
       this.lastDaemonCheck = new Date();
 
-      console.warn(`[FailoverManager] Daemon health check failed: ${error.message}`);
+      logger.warn(`[FailoverManager] Daemon health check failed: ${error.message}`);
       return false;
     }
   }
@@ -145,7 +146,7 @@ export class FailoverManager extends EventEmitter {
   async shouldUseFallback(operation = 'unknown') {
     // Always use fallback if daemon is known to be unhealthy
     if (!this.daemonHealthy) {
-      console.log(`[FailoverManager] Using fallback for ${operation}: daemon is unhealthy`);
+      logger.debug(`[FailoverManager] Using fallback for ${operation}: daemon is unhealthy`);
       return true;
     }
 
@@ -153,14 +154,14 @@ export class FailoverManager extends EventEmitter {
     if (this.metrics.lastFailureTime) {
       const timeSinceFailure = Date.now() - this.metrics.lastFailureTime;
       if (timeSinceFailure < this.config.fallbackCooldownMs) {
-        console.log(`[FailoverManager] Using fallback for ${operation}: in cooldown period`);
+        logger.debug(`[FailoverManager] Using fallback for ${operation}: in cooldown period`);
         return true;
       }
     }
 
     // Check if we've had too many consecutive failures
     if (this.metrics.consecutiveFailures >= this.config.maxConsecutiveFailures) {
-      console.log(`[FailoverManager] Using fallback for ${operation}: too many consecutive failures`);
+      logger.debug(`[FailoverManager] Using fallback for ${operation}: too many consecutive failures`);
       return true;
     }
 
@@ -170,7 +171,7 @@ export class FailoverManager extends EventEmitter {
       // Perform a quick health check before critical operations
       const isHealthy = await this.checkDaemonHealth();
       if (!isHealthy) {
-        console.log(`[FailoverManager] Using fallback for critical ${operation}: health check failed`);
+        logger.debug(`[FailoverManager] Using fallback for critical ${operation}: health check failed`);
         return true;
       }
     }
@@ -222,7 +223,7 @@ export class FailoverManager extends EventEmitter {
     this.fallbackActive = true;
     this.metrics.totalFallbacks++;
 
-    console.warn('[FailoverManager] Triggering fallback to individual browsers');
+    logger.warn('[FailoverManager] Triggering fallback to individual browsers');
 
     // Start recovery monitoring
     this.startRecoveryMonitoring();
@@ -247,7 +248,7 @@ export class FailoverManager extends EventEmitter {
       }
     }, this.config.healthCheckIntervalMs);
 
-    console.log('[FailoverManager] Started daemon health monitoring');
+    logger.debug('[FailoverManager] Started daemon health monitoring');
   }
 
   /**
@@ -264,7 +265,7 @@ export class FailoverManager extends EventEmitter {
       }
     }, this.config.recoveryCheckIntervalMs);
 
-    console.log('[FailoverManager] Started recovery monitoring');
+    logger.debug('[FailoverManager] Started recovery monitoring');
   }
 
   /**
@@ -276,7 +277,7 @@ export class FailoverManager extends EventEmitter {
     this.recoveryInProgress = true;
 
     try {
-      console.log('[FailoverManager] Checking for daemon recovery...');
+      logger.debug('[FailoverManager] Checking for daemon recovery...');
 
       // Perform multiple health checks to ensure stability
       const healthChecks = [];
@@ -289,13 +290,13 @@ export class FailoverManager extends EventEmitter {
       const allHealthy = results.every(result => result === true);
 
       if (allHealthy) {
-        console.log('[FailoverManager] Daemon has recovered, disabling fallback');
+        logger.debug('[FailoverManager] Daemon has recovered, disabling fallback');
         this.recoveredFromFallback();
       } else {
-        console.log('[FailoverManager] Daemon still unhealthy, continuing fallback');
+        logger.debug('[FailoverManager] Daemon still unhealthy, continuing fallback');
       }
     } catch (error) {
-      console.warn('[FailoverManager] Error during recovery check:', error);
+      logger.warn('[FailoverManager] Error during recovery check:', error);
     } finally {
       this.recoveryInProgress = false;
     }
@@ -354,7 +355,7 @@ export class FailoverManager extends EventEmitter {
       this.recoveryTimer = null;
     }
 
-    console.log('[FailoverManager] Failover state reset');
+    logger.debug('[FailoverManager] Failover state reset');
     this.emit('state-reset');
   }
 
@@ -391,7 +392,7 @@ export class FailoverManager extends EventEmitter {
    * Cleanup method for graceful shutdown
    */
   async cleanup() {
-    console.log('[FailoverManager] Cleaning up...');
+    logger.debug('[FailoverManager] Cleaning up...');
 
     // Stop all timers
     if (this.healthCheckTimer) {
@@ -407,6 +408,6 @@ export class FailoverManager extends EventEmitter {
     // Remove all listeners
     this.removeAllListeners();
 
-    console.log('[FailoverManager] Cleanup completed');
+    logger.debug('[FailoverManager] Cleanup completed');
   }
 }

package/src/services/project-manager.js

@@ -15,6 +15,7 @@
 import { promises as fs, existsSync as fsExistsSync } from 'fs';
 import path from 'path';
 import os from 'os';
+import logger from '../utils/logger.js';
 
 export class ProjectManager {
   constructor() {
@@ -34,7 +35,7 @@ export class ProjectManager {
       const projectRoot = this.findProjectRoot(resolvedPath);
       
       if (!projectRoot) {
-        console.log('[ProjectManager] No valid project detected from:', resolvedPath);
+        logger.debug('[ProjectManager] No valid project detected from:', resolvedPath);
         return null;
       }
 
@@ -48,12 +49,12 @@ export class ProjectManager {
         hasMarkers: markers
       };
 
-      console.log(`[ProjectManager] Detected ${projectType} project at: ${projectRoot}`);
-      console.log(`[ProjectManager] Project markers found: ${markers.join(', ')}`);
-      
+      logger.debug(`[ProjectManager] Detected ${projectType} project at: ${projectRoot}`);
+      logger.debug(`[ProjectManager] Project markers found: ${markers.join(', ')}`);
+
       return this.projectInfo;
     } catch (error) {
-      console.warn('[ProjectManager] Error during project detection:', error.message);
+      logger.warn('[ProjectManager] Error during project detection:', error.message);
       return null;
     }
   }
@@ -220,7 +221,7 @@ export class ProjectManager {
       logsDir: path.join(projectDir, '.chromedebug', 'logs')
     };
 
-    console.log(`[ProjectManager] Initializing project structure in: ${this.projectStructure.baseDir}`);
+    logger.debug(`[ProjectManager] Initializing project structure in: ${this.projectStructure.baseDir}`);
 
     try {
       // Create all necessary directories
@@ -235,12 +236,12 @@ export class ProjectManager {
         await this.updateGitignore(projectDir);
       }
 
-      console.log('[ProjectManager] Project structure initialized successfully');
-      console.log('[ProjectManager] Structure:', this.projectStructure);
-      
+      logger.debug('[ProjectManager] Project structure initialized successfully');
+      logger.debug('[ProjectManager] Structure:', this.projectStructure);
+
       this.initialized = true;
     } catch (error) {
-      console.error('[ProjectManager] Failed to initialize project structure:', error);
+      logger.error('[ProjectManager] Failed to initialize project structure:', error);
       throw new Error(`Project structure initialization failed: ${error.message}`);
     }
   }
@@ -272,11 +273,11 @@ export class ProjectManager {
         
         if (hasEntry) {
           needsUpdate = false;
-          console.log('[ProjectManager] .chromedebug already in .gitignore');
+          logger.debug('[ProjectManager] .chromedebug already in .gitignore');
         }
       } catch (error) {
         // .gitignore doesn't exist, will create it
-        console.log('[ProjectManager] Creating new .gitignore file');
+        logger.debug('[ProjectManager] Creating new .gitignore file');
       }
 
       if (needsUpdate) {
@@ -290,14 +291,14 @@ export class ProjectManager {
 # Chrome Debug project-local data
 ${chromePilotEntry}
 `;
-        
+
         gitignoreContent += chromePilotSection;
 
         await fs.writeFile(gitignorePath, gitignoreContent, 'utf8');
-        console.log('[ProjectManager] Added .chromedebug to .gitignore');
+        logger.debug('[ProjectManager] Added .chromedebug to .gitignore');
       }
     } catch (error) {
-      console.warn('[ProjectManager] Warning: Could not update .gitignore:', error.message);
+      logger.warn('[ProjectManager] Warning: Could not update .gitignore:', error.message);
       // Don't fail initialization if .gitignore update fails
     }
   }

package/src/utils/logger.js

@@ -0,0 +1,63 @@
+/**
+ * Logger utility for ChromeDebug MCP
+ *
+ * Logging Levels:
+ * - ERROR: Critical errors, always shown
+ * - WARN: Warnings and fallback scenarios, always shown
+ * - INFO: Important events (startup, connections), shown in development/debug mode
+ * - DEBUG: Verbose traces, shown only with DEBUG=true
+ *
+ * Usage:
+ *   import logger from './utils/logger.js';
+ *   logger.error('Connection failed:', error);
+ *   logger.warn('Falling back to default port');
+ *   logger.info('Server started on port', port);
+ *   logger.debug('Query executed:', sql);
+ *
+ * Environment Variables:
+ *   NODE_ENV=development - Shows INFO level and above
+ *   DEBUG=true or DEBUG=1 - Shows DEBUG level (all logs)
+ */
+
+const isDevelopment = process.env.NODE_ENV === 'development';
+const isDebug = process.env.DEBUG === 'true' || process.env.DEBUG === '1';
+
+/**
+ * Logger with level-based filtering
+ * All output goes to stderr to keep stdout clean for MCP JSON-RPC protocol
+ */
+const logger = {
+  /**
+   * Log critical errors - always shown
+   */
+  error: (...args) => {
+    console.error('[ERROR]', ...args);
+  },
+
+  /**
+   * Log warnings and fallback scenarios - always shown
+   */
+  warn: (...args) => {
+    console.error('[WARN]', ...args);
+  },
+
+  /**
+   * Log important events - shown in development or debug mode
+   */
+  info: (...args) => {
+    if (isDevelopment || isDebug) {
+      console.error('[INFO]', ...args);
+    }
+  },
+
+  /**
+   * Log verbose traces - shown only with DEBUG=true
+   */
+  debug: (...args) => {
+    if (isDebug) {
+      console.error('[DEBUG]', ...args);
+    }
+  }
+};
+
+export default logger;