feat: Shadow DOM support, headless mode, proxy, SSL ignore, max tabs, API testing

Competitive advantages over Playwright MCP / Appium MCP:

- Shadow DOM piercing: deepQuery/deepQueryAll traverse shadow roots
  (Playwright MCP issue #90 — users can't interact with Shadow DOM)
- Headless mode: --headless flag for CI/CD
  (Playwright MCP issue #126 — 'how to set headless?')
- Custom Chrome path: chrome_path parameter
  (Playwright MCP issue #139 — custom browser executable)
- Proxy support: --proxy-server=URL
  (Playwright MCP issue #203 — proxy configuration)
- SSL certificate ignore: --ignore-certificate-errors
  (Playwright MCP issues #94, MS#1358 — SSL errors)
- Max tabs limit (default 20): prevents runaway tab creation
  (MS Playwright MCP issue #1299 — agent opens 1000 tabs)
- http_request tool: GET/POST/PUT/PATCH/DELETE with JSON/headers
  (Playwright MCP issues #166, #164 — API testing support)

Total MCP tools: ~150

Author: GitLab CI

lib/src/bridge/cdp_driver.dart

@@ -15,6 +15,11 @@ class CdpDriver implements AppDriver {
   final String _url;
   final int _port;
   final bool _launchChrome;
+  final bool _headless;
+  final String? _chromePath;
+  final String? _proxy;
+  final bool _ignoreSsl;
+  final int _maxTabs;
 
   WebSocket? _ws;
   bool _connected = false;
@@ -30,13 +35,28 @@ class CdpDriver implements AppDriver {
   /// [url] is the page to navigate to.
   /// [port] is the Chrome remote debugging port.
   /// [launchChrome] whether to launch a new Chrome instance.
+  /// [headless] run Chrome in headless mode (default: false).
+  /// [chromePath] custom Chrome/Chromium executable path.
+  /// [proxy] proxy server URL (e.g. 'http://proxy:8080').
+  /// [ignoreSsl] ignore SSL certificate errors.
+  /// [maxTabs] maximum number of tabs to allow (prevents runaway tab creation).
   CdpDriver({
     required String url,
     int port = 9222,
     bool launchChrome = true,
+    bool headless = false,
+    String? chromePath,
+    String? proxy,
+    bool ignoreSsl = false,
+    int maxTabs = 20,
   })  : _url = url,
         _port = port,
-        _launchChrome = launchChrome;
+        _launchChrome = launchChrome,
+        _headless = headless,
+        _chromePath = chromePath,
+        _proxy = proxy,
+        _ignoreSsl = ignoreSsl,
+        _maxTabs = maxTabs;
 
   @override
   String get frameworkName => 'CDP (Web)';
@@ -1413,6 +1433,14 @@ class CdpDriver implements AppDriver {
   }
 
   Future<Map<String, dynamic>> newTab(String url) async {
+    // Enforce max_tabs limit to prevent runaway tab creation
+    try {
+      final tabs = await getTabs();
+      final tabList = tabs['tabs'] as List?;
+      if (tabList != null && tabList.length >= _maxTabs) {
+        return {"success": false, "error": "Max tabs limit reached ($_maxTabs). Close some tabs first."};
+      }
+    } catch (_) {}
     final result = await _call('Target.createTarget', {'url': url});
     return {"success": true, "targetId": result['targetId']};
   }
@@ -1622,21 +1650,31 @@ class CdpDriver implements AppDriver {
       chromePaths.add(r'C:\Program Files (x86)\Google\Chrome\Application\chrome.exe');
     }
 
+    // Allow custom Chrome path
+    if (_chromePath != null) {
+      chromePaths.insert(0, _chromePath!);
+    }
+
     // Create a temporary user data dir so we don't conflict with existing Chrome
     final tmpDir = await Directory.systemTemp.createTemp('cdp_chrome_');
 
+    final chromeArgs = [
+      '--remote-debugging-port=$_port',
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--user-data-dir=${tmpDir.path}',
+      '--disable-background-timer-throttling',
+      '--disable-backgrounding-occluded-windows',
+      '--disable-renderer-backgrounding',
+      if (_headless) '--headless=new',
+      if (_proxy != null) '--proxy-server=$_proxy',
+      if (_ignoreSsl) '--ignore-certificate-errors',
+      _url,
+    ];
+
     for (final chromePath in chromePaths) {
       try {
-        _chromeProcess = await Process.start(chromePath, [
-          '--remote-debugging-port=$_port',
-          '--no-first-run',
-          '--no-default-browser-check',
-          '--user-data-dir=${tmpDir.path}',
-          '--disable-background-timer-throttling',
-          '--disable-backgrounding-occluded-windows',
-          '--disable-renderer-backgrounding',
-          _url,
-        ]);
+        _chromeProcess = await Process.start(chromePath, chromeArgs);
         return;
       } catch (_) {
         continue;
@@ -1739,6 +1777,36 @@ class CdpDriver implements AppDriver {
     );
   }
 
+  /// JavaScript helper that pierces Shadow DOM when querying elements.
+  /// Use `deepQuery(selector)` instead of `document.querySelector(selector)`
+  /// and `deepQueryAll(selector)` instead of `document.querySelectorAll(selector)`.
+  static const String _shadowDomHelper = '''
+function deepQuery(selector, root) {
+  root = root || document;
+  let el = root.querySelector(selector);
+  if (el) return el;
+  const shadows = root.querySelectorAll('*');
+  for (const node of shadows) {
+    if (node.shadowRoot) {
+      el = deepQuery(selector, node.shadowRoot);
+      if (el) return el;
+    }
+  }
+  return null;
+}
+function deepQueryAll(selector, root) {
+  root = root || document;
+  let results = Array.from(root.querySelectorAll(selector));
+  const nodes = root.querySelectorAll('*');
+  for (const node of nodes) {
+    if (node.shadowRoot) {
+      results = results.concat(deepQueryAll(selector, node.shadowRoot));
+    }
+  }
+  return results;
+}
+''';
+
   Future<Map<String, dynamic>> _evalJs(String expression) async {
     return _call('Runtime.evaluate', {
       'expression': expression,
@@ -1780,18 +1848,37 @@ class CdpDriver implements AppDriver {
 
   /// Generate JS code to find an element by selector or text.
   String _jsFindElement(String selector, {String? text, String? ref}) {
+    // Deep query helper pierces Shadow DOM
+    const deepQ = '''
+function _dq(sel, root) {
+  root = root || document;
+  let el = root.querySelector(sel);
+  if (el) return el;
+  for (const n of root.querySelectorAll('*')) {
+    if (n.shadowRoot) { el = _dq(sel, n.shadowRoot); if (el) return el; }
+  }
+  return null;
+}
+function _dqAll(sel, root) {
+  root = root || document;
+  let r = Array.from(root.querySelectorAll(sel));
+  for (const n of root.querySelectorAll('*')) {
+    if (n.shadowRoot) r = r.concat(_dqAll(sel, n.shadowRoot));
+  }
+  return r;
+}
+''';
+
     if (text != null) {
       final escaped = text.replaceAll("'", "\\'").replaceAll('\n', '\\n');
       return '''(() => {
-        // Try CSS selector first
-        let el = document.querySelector('$selector');
+        $deepQ
+        let el = _dq('$selector');
         if (el) return el;
-        // Search by text content
-        const all = document.querySelectorAll('a, button, input, select, textarea, label, span, p, h1, h2, h3, h4, h5, h6, div, li, td, th, [role]');
+        const all = _dqAll('a, button, input, select, textarea, label, span, p, h1, h2, h3, h4, h5, h6, div, li, td, th, [role]');
         for (const e of all) {
           if (e.textContent && e.textContent.trim() === '$escaped') return e;
         }
-        // Partial match
         for (const e of all) {
           if (e.textContent && e.textContent.trim().includes('$escaped')) return e;
         }
@@ -1818,7 +1905,8 @@ class CdpDriver implements AppDriver {
             tagSelector = '*';
         }
         return '''(() => {
-          const candidates = document.querySelectorAll('$tagSelector');
+          $deepQ
+          const candidates = _dqAll('$tagSelector');
           for (const e of candidates) {
             const t = (e.textContent || '').trim();
             const label = e.getAttribute('aria-label') || e.getAttribute('placeholder') || '';
@@ -1832,7 +1920,10 @@ class CdpDriver implements AppDriver {
         })()''';
       }
     }
-    return "document.querySelector('$selector')";
+    return '''(() => {
+      $deepQ
+      return _dq('$selector');
+    })()''';
   }
 
   /// Get element bounds (returns {x, y, w, h, cx, cy} or null).

lib/src/cli/server.dart

@@ -711,6 +711,46 @@ They will automatically route through the CDP connection.""",
               "description":
                   "Launch a new Chrome instance (default: true). Set to false to connect to already-running Chrome."
             },
+            "headless": {
+              "type": "boolean",
+              "description": "Run Chrome in headless mode (default: false). Useful for CI/CD."
+            },
+            "chrome_path": {
+              "type": "string",
+              "description": "Custom Chrome/Chromium executable path."
+            },
+            "proxy": {
+              "type": "string",
+              "description": "Proxy server URL (e.g. 'http://proxy:8080' or 'socks5://proxy:1080')."
+            },
+            "ignore_ssl": {
+              "type": "boolean",
+              "description": "Ignore SSL certificate errors (default: false)."
+            },
+            "max_tabs": {
+              "type": "integer",
+              "description": "Maximum number of tabs allowed (default: 20). Prevents runaway tab creation."
+            },
+          },
+          "required": ["url"],
+        },
+      },
+
+      // HTTP Request tool (API testing)
+      {
+        "name": "http_request",
+        "description": """Make an HTTP request for API testing.
+
+Supports GET, POST, PUT, PATCH, DELETE with JSON bodies, custom headers, and authentication.
+Returns status code, headers, and response body.""",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "url": {"type": "string", "description": "Request URL"},
+            "method": {"type": "string", "description": "HTTP method (GET, POST, PUT, PATCH, DELETE). Default: GET"},
+            "headers": {"type": "object", "description": "Request headers as key-value pairs"},
+            "body": {"type": "string", "description": "Request body (typically JSON string)"},
+            "timeout": {"type": "integer", "description": "Timeout in milliseconds (default: 30000)"},
           },
           "required": ["url"],
         },
@@ -3379,10 +3419,78 @@ function toggleImg(el) { el.classList.toggle('expanded'); }
       };
     }
 
+    if (name == 'http_request') {
+      final url = args['url'] as String;
+      final method = (args['method'] as String? ?? 'GET').toUpperCase();
+      final headers = (args['headers'] as Map<String, dynamic>?)?.map((k, v) => MapEntry(k, v.toString())) ?? {};
+      final body = args['body'] as String?;
+      final timeout = args['timeout'] as int? ?? 30000;
+
+      try {
+        final client = http.Client();
+        final uri = Uri.parse(url);
+        http.Response response;
+
+        final reqHeaders = Map<String, String>.from(headers);
+        if (body != null && !reqHeaders.containsKey('content-type') && !reqHeaders.containsKey('Content-Type')) {
+          reqHeaders['Content-Type'] = 'application/json';
+        }
+
+        switch (method) {
+          case 'POST':
+            response = await client.post(uri, headers: reqHeaders, body: body)
+                .timeout(Duration(milliseconds: timeout));
+            break;
+          case 'PUT':
+            response = await client.put(uri, headers: reqHeaders, body: body)
+                .timeout(Duration(milliseconds: timeout));
+            break;
+          case 'PATCH':
+            response = await client.patch(uri, headers: reqHeaders, body: body)
+                .timeout(Duration(milliseconds: timeout));
+            break;
+          case 'DELETE':
+            response = await client.delete(uri, headers: reqHeaders)
+                .timeout(Duration(milliseconds: timeout));
+            break;
+          default: // GET
+            response = await client.get(uri, headers: reqHeaders)
+                .timeout(Duration(milliseconds: timeout));
+        }
+        client.close();
+
+        // Try to parse JSON body
+        dynamic responseBody;
+        try {
+          responseBody = jsonDecode(response.body);
+        } catch (_) {
+          responseBody = response.body.length > 10000
+              ? '${response.body.substring(0, 10000)}... (truncated)'
+              : response.body;
+        }
+
+        return {
+          "status": response.statusCode,
+          "headers": response.headers,
+          "body": responseBody,
+          "content_length": response.contentLength,
+          "method": method,
+          "url": url,
+        };
+      } catch (e) {
+        return {"error": e.toString(), "method": method, "url": url};
+      }
+    }
+
     if (name == 'connect_cdp') {
       final url = args['url'] as String;
       final port = args['port'] as int? ?? 9222;
       final launchChrome = args['launch_chrome'] ?? true;
+      final headless = args['headless'] ?? false;
+      final chromePath = args['chrome_path'] as String?;
+      final proxy = args['proxy'] as String?;
+      final ignoreSsl = args['ignore_ssl'] ?? false;
+      final maxTabs = args['max_tabs'] as int? ?? 20;
 
       // Disconnect existing CDP connection if any
       if (_cdpDriver != null) {
@@ -3391,7 +3499,16 @@ function toggleImg(el) { el.classList.toggle('expanded'); }
       }
 
       try {
-        final driver = CdpDriver(url: url, port: port, launchChrome: launchChrome);
+        final driver = CdpDriver(
+          url: url,
+          port: port,
+          launchChrome: launchChrome,
+          headless: headless,
+          chromePath: chromePath,
+          proxy: proxy,
+          ignoreSsl: ignoreSsl,
+          maxTabs: maxTabs,
+        );
         await driver.connect();
         _cdpDriver = driver;