feat: support device scale factor in --viewport

Author: Aalivexy

README.md

@@ -502,7 +502,7 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** string
 
 - **`--viewport`**
-  Initial viewport size for the Chrome instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.
+  Initial viewport size for the Chrome instances started by the server. For example, `1280x720` or `1280x720x2` to set the device scale factor. In headless mode, max size is 3840x2160px.
   - **Type:** string
 
 - **`--proxyServer`/ `--proxy-server`**

src/bin/chrome-devtools-mcp-cli-options.ts

@@ -7,6 +7,39 @@
 import type {YargsOptions} from '../third_party/index.js';
 import {yargs, hideBin} from '../third_party/index.js';
 
+function parseViewportOption(arg: string | undefined) {
+  if (arg === undefined) {
+    return;
+  }
+
+  const dimensions = arg.split('x');
+  if (dimensions.length < 2 || dimensions.length > 3) {
+    throw new Error(
+      'Invalid viewport. Expected format is `1280x720` or `1280x720x2`.',
+    );
+  }
+
+  const [width, height, deviceScaleFactor] = dimensions.map(Number);
+  if (
+    !width ||
+    !height ||
+    Number.isNaN(width) ||
+    Number.isNaN(height) ||
+    (deviceScaleFactor !== undefined &&
+      (deviceScaleFactor <= 0 || Number.isNaN(deviceScaleFactor)))
+  ) {
+    throw new Error(
+      'Invalid viewport. Expected format is `1280x720` or `1280x720x2`.',
+    );
+  }
+
+  return {
+    width,
+    height,
+    ...(deviceScaleFactor === undefined ? {} : {deviceScaleFactor}),
+  };
+}
+
 export const cliOptions = {
   autoConnect: {
     type: 'boolean',
@@ -124,20 +157,8 @@ export const cliOptions = {
   viewport: {
     type: 'string',
     describe:
-      'Initial viewport size for the Chrome instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.',
-    coerce: (arg: string | undefined) => {
-      if (arg === undefined) {
-        return;
-      }
-      const [width, height] = arg.split('x').map(Number);
-      if (!width || !height || Number.isNaN(width) || Number.isNaN(height)) {
-        throw new Error('Invalid viewport. Expected format is `1280x720`.');
-      }
-      return {
-        width,
-        height,
-      };
-    },
+      'Initial viewport size for the Chrome instances started by the server. For example, `1280x720` or `1280x720x2` to set the device scale factor. In headless mode, max size is 3840x2160px.',
+    coerce: parseViewportOption,
   },
   proxyServer: {
     type: 'string',
@@ -297,6 +318,10 @@ export function parseArguments(version: string, argv = process.argv) {
         '$0 --viewport 1280x720',
         'Launch Chrome with the initial viewport size of 1280x720px',
       ],
+      [
+        '$0 --viewport 1280x720x2',
+        'Launch Chrome with the initial viewport size of 1280x720px and device scale factor 2',
+      ],
       [
         `$0 --chrome-arg='--no-sandbox' --chrome-arg='--disable-setuid-sandbox'`,
         'Launch Chrome without sandboxes. Use with caution.',

src/browser.ts

@@ -144,6 +144,7 @@ interface McpLaunchOptions {
   viewport?: {
     width: number;
     height: number;
+    deviceScaleFactor?: number;
   };
   chromeArgs?: string[];
   ignoreDefaultChromeArgs?: string[];
@@ -242,6 +243,14 @@ export async function launch(options: McpLaunchOptions): Promise<Browser> {
         contentWidth: options.viewport.width,
         contentHeight: options.viewport.height,
       });
+      if (options.viewport.deviceScaleFactor !== undefined) {
+        // page.resize() only affects the content size. Apply DPR separately.
+        await page?.setViewport({
+          width: options.viewport.width,
+          height: options.viewport.height,
+          deviceScaleFactor: options.viewport.deviceScaleFactor,
+        });
+      }
     }
     return browser;
   } catch (error) {

tests/browser.test.ts

@@ -77,6 +77,41 @@ describe('browser', () => {
       await browser.close();
     }
   });
+
+  it('launches with the initial viewport device scale factor', async () => {
+    const tmpDir = os.tmpdir();
+    const folderPath = path.join(tmpDir, `temp-folder-${crypto.randomUUID()}`);
+    const browser = await launch({
+      headless: true,
+      isolated: false,
+      userDataDir: folderPath,
+      executablePath: executablePath(),
+      viewport: {
+        width: 1501,
+        height: 801,
+        deviceScaleFactor: 2,
+      },
+      devtools: false,
+    });
+    try {
+      const [page] = await browser.pages();
+      const result = await page.evaluate(() => {
+        return {
+          width: window.innerWidth,
+          height: window.innerHeight,
+          devicePixelRatio: window.devicePixelRatio,
+        };
+      });
+      assert.deepStrictEqual(result, {
+        width: 1501,
+        height: 801,
+        devicePixelRatio: 2,
+      });
+    } finally {
+      await browser.close();
+    }
+  });
+
   it('connects to an existing browser with userDataDir', async () => {
     const tmpDir = os.tmpdir();
     const folderPath = path.join(tmpDir, `temp-folder-${crypto.randomUUID()}`);

tests/cli.test.ts

@@ -131,6 +131,27 @@ describe('cli args parsing', () => {
     });
   });
 
+  it('parses viewport with device scale factor', async () => {
+    const args = parseArguments('1.0.0', [
+      'node',
+      'main.js',
+      '--viewport',
+      '888x777x2',
+    ]);
+    assert.deepStrictEqual(args, {
+      ...defaultArgs,
+      _: [],
+      headless: false,
+      $0: 'npx chrome-devtools-mcp@latest',
+      channel: 'stable',
+      viewport: {
+        width: 888,
+        height: 777,
+        deviceScaleFactor: 2,
+      },
+    });
+  });
+
   it('parses chrome args', async () => {
     const args = parseArguments('1.0.0', [
       'node',