Stealth browser automation for AI agents over MCP and the Chrome DevTools Protocol: navigation, network hooks, DOM extraction, and pixel-accurate UI cloning.
Python ai-agent-toolsai-toolsanthropicanti-bot-bypassautomation-toolsbrowser-automationchrome-devtoolsclaude-mcpcloudflare-bypassdeveloper-toolsfastmcpmcp-servermodel-context-protocolnetwork-interceptionnodriverpythonstealth-browserundetectable-browserweb-automationweb-scraping
fix(logging): suppress stderr noise unless debug is enabled
Vibhek Sonica885ff4597b
diff --git a/src/browser_manager.py b/src/browser_manager.pyindex 112f78a..c465af2 100644--- a/src/browser_manager.py+++ b/src/browser_manager.py@@ -193,7 +193,11 @@ class BrowserManager:width=options.viewport_width,height=options.viewport_height)- print(f"[DEBUG] Set viewport to {options.viewport_width}x{options.viewport_height}", file=sys.stderr)+ debug_logger.log_info(+ "browser_manager",+ "spawn_browser",+ f"Set viewport to {options.viewport_width}x{options.viewport_height}",+ )applied_timezone_id = await self._apply_timezone_override(tab=tab,diff --git a/src/debug_logger.py b/src/debug_logger.pyindex efe24ce..ae0f668 100644--- a/src/debug_logger.py+++ b/src/debug_logger.py@@ -39,6 +39,21 @@ class DebugLogger:self._lock_acquired_time = 0self._seen_errors: set = set()+ def _emit_stderr(self, message: str, force: bool = False):+ """+ Emit a debug line to stderr only when logging is enabled unless forced.++ Args:+ message (str): Message to emit.+ force (bool): Whether to emit regardless of current debug state.+ """+ if not force and not self._enabled:+ return+ try:+ print(message, file=sys.stderr)+ except Exception:+ pass+def log_error(self, component: str, method: str, error: Exception, context: Optional[Dict[str, Any]] = None):"""Log an error with full context.@@ -72,7 +87,7 @@ class DebugLogger:}self._errors.append(error_entry)self._stats[f'{component}.{method}.errors'] += 1- print(f"[DEBUG ERROR] {component}.{method}: {error}", file=sys.stderr)+ self._emit_stderr(f"[DEBUG ERROR] {component}.{method}: {error}")def log_warning(self, component: str, method: str, message: str, context: Optional[Dict[str, Any]] = None):"""@@ -97,7 +112,7 @@ class DebugLogger:}self._warnings.append(warning_entry)self._stats[f'{component}.{method}.warnings'] += 1- print(f"[DEBUG WARN] {component}.{method}: {message}", file=sys.stderr)+ self._emit_stderr(f"[DEBUG WARN] {component}.{method}: {message}")def log_info(self, component: str, method: str, message: str, data: Optional[Any] = None):"""@@ -122,9 +137,9 @@ class DebugLogger:}self._info.append(info_entry)self._stats[f'{component}.{method}.calls'] += 1- print(f"[DEBUG INFO] {component}.{method}: {message}", file=sys.stderr)+ self._emit_stderr(f"[DEBUG INFO] {component}.{method}: {message}")if data:- print(f" Data: {data}", file=sys.stderr)+ self._emit_stderr(f" Data: {data}")def get_debug_view(self) -> Dict[str, Any]:"""@@ -243,13 +258,13 @@ class DebugLogger:self._warnings.clear()self._info.clear()self._stats.clear()- print("[DEBUG] Debug logs cleared", file=sys.stderr)+ self._emit_stderr("[DEBUG] Debug logs cleared")finally:self._lock.release()else:- print("[DEBUG] Failed to clear logs - timeout acquiring lock", file=sys.stderr)+ self._emit_stderr("[DEBUG] Failed to clear logs - timeout acquiring lock")except Exception as e:- print(f"[DEBUG] Error clearing logs: {e}", file=sys.stderr)+ self._emit_stderr(f"[DEBUG] Error clearing logs: {e}")def clear_debug_view_safe(self):"""@@ -262,7 +277,7 @@ class DebugLogger:self._warnings = []self._info = []self._stats = defaultdict(int)- print("[DEBUG] Debug logs force-cleared (lock bypass)", file=sys.stderr)+ self._emit_stderr("[DEBUG] Debug logs force-cleared (lock bypass)")def enable(self):"""@@ -272,7 +287,7 @@ class DebugLogger:self._enabled (bool): Set to True."""self._enabled = True- print("[DEBUG] Debug logging enabled", file=sys.stderr)+ self._emit_stderr("[DEBUG] Debug logging enabled", force=True)def disable(self):"""@@ -281,8 +296,8 @@ class DebugLogger:Variables:self._enabled (bool): Set to False."""+ self._emit_stderr("[DEBUG] Debug logging disabled")self._enabled = False- print("[DEBUG] Debug logging disabled", file=sys.stderr)def get_lock_status(self) -> Dict[str, Any]:"""Get current lock status for debugging."""@@ -328,18 +343,18 @@ class DebugLogger:"""import timetry:- print(f"[DEBUG] export_debug_logs attempting lock acquisition...", file=sys.stderr)+ self._emit_stderr("[DEBUG] export_debug_logs attempting lock acquisition...")current_status = self.get_lock_status()- print(f"[DEBUG] Current lock status: {current_status}", file=sys.stderr)+ self._emit_stderr(f"[DEBUG] Current lock status: {current_status}")acquired = self._lock.acquire(timeout=5.0)if not acquired:- print("[DEBUG] Lock timeout - falling back to lock-free export", file=sys.stderr)+ self._emit_stderr("[DEBUG] Lock timeout - falling back to lock-free export")return self._export_lockfree(filepath, max_errors, max_warnings, max_info, format)self._lock_owner = "export_debug_logs"self._lock_acquired_time = time.time()- print("[DEBUG] Lock acquired by export_debug_logs", file=sys.stderr)+ self._emit_stderr("[DEBUG] Lock acquired by export_debug_logs")try:debug_data = self.get_debug_view_paginated(@@ -351,9 +366,9 @@ class DebugLogger:self._lock_owner = "none"self._lock_acquired_time = 0self._lock.release()- print("[DEBUG] Lock released by export_debug_logs", file=sys.stderr)+ self._emit_stderr("[DEBUG] Lock released by export_debug_logs")except Exception as e:- print(f"[DEBUG] Exception in export: {e}", file=sys.stderr)+ self._emit_stderr(f"[DEBUG] Exception in export: {e}")return self._export_lockfree(filepath, max_errors, max_warnings, max_info, format)if format == "auto":@@ -427,10 +442,12 @@ class DebugLogger:pickle.dump(debug_data, f, protocol=pickle.HIGHEST_PROTOCOL)file_size = os.path.getsize(filepath)- print(f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "- f"{debug_data['summary']['returned_warnings']} warnings, "- f"{debug_data['summary']['returned_info']} info logs to {filepath} "- f"({file_size} bytes, gzip-pickle format)", file=sys.stderr)+ self._emit_stderr(+ f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "+ f"{debug_data['summary']['returned_warnings']} warnings, "+ f"{debug_data['summary']['returned_info']} info logs to {filepath} "+ f"({file_size} bytes, gzip-pickle format)"+ )return filepathdef _export_pickle(self, debug_data: Dict[str, Any], filepath: str) -> str:@@ -442,10 +459,12 @@ class DebugLogger:pickle.dump(debug_data, f, protocol=pickle.HIGHEST_PROTOCOL)file_size = os.path.getsize(filepath)- print(f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "- f"{debug_data['summary']['returned_warnings']} warnings, "- f"{debug_data['summary']['returned_info']} info logs to {filepath} "- f"({file_size} bytes, pickle format)", file=sys.stderr)+ self._emit_stderr(+ f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "+ f"{debug_data['summary']['returned_warnings']} warnings, "+ f"{debug_data['summary']['returned_info']} info logs to {filepath} "+ f"({file_size} bytes, pickle format)"+ )return filepathdef _export_json(self, debug_data: Dict[str, Any], filepath: str) -> str:@@ -454,11 +473,13 @@ class DebugLogger:json.dump(debug_data, f, separators=(',', ':'), default=str)file_size = os.path.getsize(filepath)- print(f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "- f"{debug_data['summary']['returned_warnings']} warnings, "- f"{debug_data['summary']['returned_info']} info logs to {filepath} "- f"({file_size} bytes, JSON format)", file=sys.stderr)+ self._emit_stderr(+ f"[DEBUG] Exported {debug_data['summary']['returned_errors']} errors, "+ f"{debug_data['summary']['returned_warnings']} warnings, "+ f"{debug_data['summary']['returned_info']} info logs to {filepath} "+ f"({file_size} bytes, JSON format)"+ )return filepath-debug_logger = DebugLogger()\ No newline at end of file+debug_logger = DebugLogger()diff --git a/src/network_interceptor.py b/src/network_interceptor.pyindex 01c9d0f..918d575 100644--- a/src/network_interceptor.py+++ b/src/network_interceptor.py@@ -3,7 +3,6 @@import asyncioimport base64import json-import sysfrom datetime import datetimefrom pathlib import Pathfrom typing import Any, Dict, List, Optional@@ -11,6 +10,7 @@ from typing import Any, Dict, List, Optionalimport nodriver as ucfrom nodriver import Tab+from debug_logger import debug_loggerfrom models import NetworkRequest, NetworkResponse@@ -50,16 +50,31 @@ class NetworkInterceptor:if resource_type.lower() in resource_patterns:url_patterns.extend(resource_patterns[resource_type.lower()])- print(f"[DEBUG] Added URL patterns for {resource_type}: {resource_patterns[resource_type.lower()]}", file=sys.stderr)+ debug_logger.log_info(+ "network_interceptor",+ "setup_interception",+ f"Added URL patterns for {resource_type}",+ resource_patterns[resource_type.lower()],+ )else:# Assume it's already a URL patternurl_patterns.append(resource_type)- print(f"[DEBUG] Added custom URL pattern: {resource_type}", file=sys.stderr)+ debug_logger.log_info(+ "network_interceptor",+ "setup_interception",+ "Added custom URL pattern",+ resource_type,+ )# Use network.set_blocked_ur_ls to block the URL patternsif url_patterns:await tab.send(uc.cdp.network.set_blocked_ur_ls(urls=url_patterns))- print(f"[DEBUG] Blocked {len(url_patterns)} URL patterns: {url_patterns}", file=sys.stderr)+ debug_logger.log_info(+ "network_interceptor",+ "setup_interception",+ f"Blocked {len(url_patterns)} URL patterns",+ url_patterns,+ )tab.add_handler(uc.cdp.network.RequestWillBeSent,@@ -74,7 +89,7 @@ class NetworkInterceptor:if instance_id not in self._instance_requests:self._instance_requests[instance_id] = []except Exception as e:- print(f"[DEBUG] Error in setup_interception: {e}", file=sys.stderr)+ debug_logger.log_error("network_interceptor", "setup_interception", e)raise Exception(f"Failed to setup network interception: {str(e)}")async def _on_request(self, event, instance_id: str):@@ -571,4 +586,4 @@ class NetworkInterceptor:for req_id in self._instance_requests[instance_id]:self._requests.pop(req_id, None)self._responses.pop(req_id, None)- del self._instance_requests[instance_id]\ No newline at end of file+ del self._instance_requests[instance_id]diff --git a/src/server.py b/src/server.pyindex 2b4b6ca..6e99dfc 100644--- a/src/server.py+++ b/src/server.py@@ -51,6 +51,12 @@ def parse_bool_env(name: str, default: bool = False) -> bool:return defaultreturn value.strip().lower() in {"1", "true", "yes", "on", "enabled"}++DEBUG_LOGGING_ENABLED = (+ parse_bool_env("STEALTH_BROWSER_DEBUG", default=False)+ or parse_bool_env("DEBUG", default=False)+)+def is_section_enabled(section: str) -> bool:"""Check if a tool section is enabled."""return section not in DISABLED_SECTIONS@@ -134,6 +140,9 @@ network_interceptor = NetworkInterceptor()dom_handler = DOMHandler()cdp_function_executor = CDPFunctionExecutor()+if DEBUG_LOGGING_ENABLED:+ debug_logger.enable()+@section_tool("browser-management")async def spawn_browser(headless: bool = False,@@ -2783,6 +2792,12 @@ if __name__ == "__main__":help="Enable only core browser management and element interaction (disable everything else)")parser.add_argument("--list-sections", action="store_true",help="List all available tool sections and exit")+ parser.add_argument(+ "--debug",+ action="store_true",+ default=DEBUG_LOGGING_ENABLED,+ help="Enable debug logging to stderr",+ )parser.add_argument("--xpool-safe",action="store_true",@@ -2791,6 +2806,9 @@ if __name__ == "__main__":)args = parser.parse_args()++ if args.debug and not debug_logger._enabled:+ debug_logger.enable()if args.list_sections:print("Available tool sections:")@@ -2845,7 +2863,11 @@ if __name__ == "__main__":apply_disabled_sections()if DISABLED_SECTIONS:- print(f"Disabled tool sections: {', '.join(sorted(DISABLED_SECTIONS))}", file=sys.stderr)+ debug_logger.log_info(+ "server",+ "startup",+ f"Disabled tool sections: {', '.join(sorted(DISABLED_SECTIONS))}",+ )if args.transport == "http":mcp.run(transport="http", host=args.host, port=args.port)