LCBro

# Remote CDP Server Support ## Overview Support for connecting to remote Chrome DevTools Protocol (CDP) servers via HTTP/HTTPS API has been implemented. This allows getting a list of available browsers and ports from remote servers. ## 🔗 Key Features ### **Remote CDP Servers** - Connection to remote CDP servers via HTTP/HTTPS - Getting list of available browsers and ports - SSL/TLS support for secure connections - Authentication via API keys ### **Flexible Configuration** - Automatic selection between local and remote detection - SSL mode configuration - Custom HTTP headers - Timeouts and retries ### **Security** - HTTPS support for encrypted connections - API keys for authentication - Configurable SSL modes - URL validation ## 📋 Configuration ### config/default.yaml ```yaml browser: engine: cdp cdp: enabled: true host: "localhost" # for local detection port: 9222 # for local detection # Remote CDP server configuration remote: enabled: true # enable remote server support url: "https://cdp.example.com:9222" # remote server URL sslMode: "auto" # SSL mode: auto, enabled, disabled, insecure apiKey: "your-api-key" # API key for authentication (optional) headers: # additional HTTP headers "X-Custom-Header": "value" "User-Agent": "MCP-Browser-Server/1.0" # Detection settings detection: enabled: true ports: [9222, 9223, 9224, 9225, 9226] # for local scanning timeout: 5000 useRemote: true # use remote server instead of local scanning ``` ## 🔧 SSL Modes ### **auto** (default) - Automatically detects SSL based on URL - HTTPS URL → SSL enabled - HTTP URL → SSL disabled ### **enabled** - Forces SSL enablement - All connections must be encrypted ### **disabled** - Forces SSL disablement - All connections without encryption ### **insecure** - Disables SSL certificate verification - Used for self-signed certificates - ⚠️ **Insecure** - only for development ## 🌐 Usage Examples ### 1. **Connection to Remote CDP Server** ```yaml browser: engine: cdp cdp: enabled: true remote: enabled: true url: "https://cdp-server.company.com:9222" sslMode: "enabled" apiKey: "secret-api-key-123" detection: useRemote: true ``` ### 2. **Self-signed Certificate (Development)** ```yaml browser: engine: cdp cdp: enabled: true remote: enabled: true url: "https://localhost:9222" sslMode: "insecure" # disables certificate verification detection: useRemote: true ``` ### 3. **HTTP Connection (Insecure)** ```yaml browser: engine: cdp cdp: enabled: true remote: enabled: true url: "http://internal-cdp-server:9222" sslMode: "disabled" detection: useRemote: true ``` ### 4. **Custom Headers** ```yaml browser: engine: cdp cdp: enabled: true remote: enabled: true url: "https://api.cdp-provider.com/v1" sslMode: "enabled" apiKey: "your-api-key" headers: "X-Client-ID": "mcp-browser-server" "X-Client-Version": "1.0.0" "Accept": "application/json" detection: useRemote: true ``` ## 🔌 Remote CDP Server API ### **Expected Response Format** ```json { "browsers": [ { "id": "browser_9222", "title": "Chrome Browser", "name": "Chrome Browser", "version": "Chrome/120.0.0.0", "userAgent": "Mozilla/5.0...", "url": "https://example.com", "webSocketUrl": "ws://localhost:9222/devtools/browser/...", "wsUrl": "ws://localhost:9222/devtools/browser/...", "description": "Chrome browser on port 9222" } ], "serverVersion": "1.0.0", "serverInfo": "Remote CDP Server v1.0.0" } ``` ### **Endpoints** #### **GET /api/browsers** Returns list of all available browsers. **Headers:** ``` Authorization: Bearer your-api-key X-API-Key: your-api-key Accept: application/json ``` **Response:** ```json { "browsers": [...], "serverVersion": "1.0.0", "serverInfo": "Remote CDP Server" } ``` #### **GET /api/browsers/{id}** Returns details of specific browser. **Response:** ```json { "id": "browser_9222", "title": "Chrome Browser", "webSocketUrl": "ws://localhost:9222/devtools/browser/...", ... } ``` #### **GET /api/info** Returns server information. **Response:** ```json { "name": "Remote CDP Server", "version": "1.0.0", "capabilities": ["browser-detection", "websocket-proxy"], "uptime": 3600 } ``` #### **GET /api/health** Server availability check. **Response:** ```json { "status": "healthy", "timestamp": 1705135815123 } ``` ## 💻 Programmatic Usage ### **RemoteCDPClient** ```typescript import { RemoteCDPClient } from './src/utils/remote-cdp-client.js'; // Create client const client = new RemoteCDPClient(logger, { url: 'https://cdp-server.example.com:9222', sslMode: 'enabled', apiKey: 'your-api-key', headers: { 'X-Client-ID': 'mcp-browser-server' }, timeout: 30000 }); // Get browser list const response = await client.getAvailableBrowsers(); if (response.success) { console.log(`Found ${response.browsers.length} browsers`); response.browsers.forEach(browser => { console.log(`- ${browser.title}: ${browser.webSocketDebuggerUrl}`); }); } // Check server availability const isAvailable = await client.isServerAvailable(); console.log(`Server available: ${isAvailable}`); // Get server information const serverInfo = await client.getServerInfo(); if (serverInfo.success) { console.log(`Server: ${serverInfo.info.name} v${serverInfo.info.version}`); } ``` ### **URL Validation** ```typescript import { RemoteCDPClient } from './src/utils/remote-cdp-client.js'; // Validate URL const validation = RemoteCDPClient.validateURL('https://cdp.example.com:9222'); if (validation.valid) { console.log('URL is valid'); } else { console.error(`Invalid URL: ${validation.error}`); } // Parse URL const parsed = RemoteCDPClient.parseRemoteURL('https://cdp.example.com:9222/api'); console.log(parsed); // { // host: 'cdp.example.com', // port: 9222, // protocol: 'https:', // path: '/api' // } ``` ## 🔍 Logging and Debugging ### **Successful Connection** ```json { "level": "info", "msg": "Detecting browsers from remote CDP server", "url": "https://cdp.example.com:9222" } { "level": "info", "msg": "Retrieved browsers from remote CDP server", "count": 3, "browsers": [ {"id": "browser_9222", "title": "Chrome Browser"}, {"id": "browser_9223", "title": "Edge Browser"} ] } ``` ### **Connection Errors** ```json { "level": "error", "msg": "Failed to fetch browsers from remote CDP server", "url": "https://cdp.example.com:9222", "error": "HTTP 401: Unauthorized" } { "level": "error", "msg": "Remote CDP browser detection failed", "error": "Network timeout after 30000ms" } ``` ### **SSL Warnings** ```json { "level": "warn", "msg": "SSL verification disabled - connections may not be secure", "sslMode": "insecure" } ``` ## 🛡️ Security ### **Recommendations** 1. **Use HTTPS** for production 2. **API keys** for authentication 3. **Validate certificates** (don't use `insecure`) 4. **Restrict access** by IP addresses 5. **Log connections** for audit ### **SSL Configuration** ```yaml # Production (secure) remote: url: "https://cdp.company.com:9222" sslMode: "enabled" apiKey: "secure-api-key" # Development with self-signed certificate remote: url: "https://localhost:9222" sslMode: "insecure" # only for development! # Internal network remote: url: "http://internal-cdp:9222" sslMode: "disabled" # only in trusted network ``` ## 🔧 Integration with Existing System ### **Automatic Switching** ```yaml browser: engine: cdp cdp: enabled: true # Local detection as fallback host: "localhost" ports: [9222, 9223, 9224] # Remote server as primary remote: enabled: true url: "https://primary-cdp.example.com:9222" sslMode: "enabled" detection: useRemote: true # try remote first # If remote unavailable, use local scanning ``` ### **Status Monitoring** ```typescript // Check remote server availability const isRemoteAvailable = await remoteClient.isServerAvailable(); if (!isRemoteAvailable) { // Fallback to local detection const localBrowsers = await detectLocalBrowsers(); return localBrowsers; } ``` ## 📊 Usage Scenario Examples ### **1. Corporate Environment** ```yaml # Company centralized CDP server browser: engine: cdp cdp: enabled: true remote: enabled: true url: "https://cdp.company.com:9222" sslMode: "enabled" apiKey: "corporate-api-key" headers: "X-Department": "QA" "X-Environment": "staging" detection: useRemote: true ``` ### **2. Cloud Infrastructure** ```yaml # CDP server in cloud browser: engine: cdp cdp: enabled: true remote: enabled: true url: "https://cdp.aws.region.com:9222" sslMode: "enabled" apiKey: "${CDP_API_KEY}" # from environment variables detection: useRemote: true ``` ### **3. Local Development** ```yaml # Local CDP server for development browser: engine: cdp cdp: enabled: true remote: enabled: true url: "https://localhost:9222" sslMode: "insecure" # self-signed certificate detection: useRemote: true ``` ## 🚀 Ready for Use Remote CDP server support is fully implemented: - ✅ **HTTP/HTTPS client** for remote servers - ✅ **SSL/TLS support** with various modes - ✅ **Authentication** via API keys - ✅ **URL validation** and error handling - ✅ **Integration** with existing CDP system - ✅ **Logging** and debugging - ✅ **Documentation** and examples --- **Implemented with Claude Sonnet 4 model**