chrome-devtools-mcp 0.2.7 → 0.3.0

package/build/src/main.js

@@ -3,17 +3,20 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import { McpResponse } from './McpResponse.js';
-import { McpContext } from './McpContext.js';
-import { logger, saveLogsToFile } from './logger.js';
+import { SetLevelRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { resolveBrowser } from './browser.js';
-import * as emulationTools from './tools/emulation.js';
+import { parseArguments } from './cli.js';
+import { logger, saveLogsToFile } from './logger.js';
+import { McpContext } from './McpContext.js';
+import { McpResponse } from './McpResponse.js';
+import { Mutex } from './Mutex.js';
 import * as consoleTools from './tools/console.js';
+import * as emulationTools from './tools/emulation.js';
 import * as inputTools from './tools/input.js';
 import * as networkTools from './tools/network.js';
 import * as pagesTools from './tools/pages.js';
@@ -21,55 +24,6 @@ import * as performanceTools from './tools/performance.js';
 import * as screenshotTools from './tools/screenshot.js';
 import * as scriptTools from './tools/script.js';
 import * as snapshotTools from './tools/snapshot.js';
-import path from 'node:path';
-import fs from 'node:fs';
-import assert from 'node:assert';
-import { Mutex } from './Mutex.js';
-export const cliOptions = {
-    browserUrl: {
-        type: 'string',
-        description: 'Connect to a running Chrome instance using port forwarding. For more details see: https://developer.chrome.com/docs/devtools/remote-debugging/local-server.',
-        alias: 'u',
-        coerce: (url) => {
-            new URL(url);
-            return url;
-        },
-    },
-    headless: {
-        type: 'boolean',
-        description: 'Whether to run in headless (no UI) mode.',
-        default: false,
-    },
-    executablePath: {
-        type: 'string',
-        description: 'Path to custom Chrome executable.',
-        conflicts: 'browserUrl',
-        alias: 'e',
-    },
-    isolated: {
-        type: 'boolean',
-        description: 'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed.',
-        default: false,
-    },
-    customDevtools: {
-        type: 'string',
-        description: 'Path to custom DevTools.',
-        hidden: true,
-        conflicts: 'browserUrl',
-        alias: 'd',
-    },
-    channel: {
-        type: 'string',
-        description: 'Specify a different Chrome channel that should be used. The default is the stable channel version.',
-        choices: ['stable', 'canary', 'beta', 'dev'],
-        conflicts: ['browserUrl', 'executablePath'],
-    },
-    logFile: {
-        type: 'string',
-        describe: 'Save the logs to file.',
-        hidden: true,
-    },
-};
 function readPackageJson() {
     const currentDir = import.meta.dirname;
     const packageJsonPath = path.join(currentDir, '..', '..', 'package.json');
@@ -86,34 +40,7 @@ function readPackageJson() {
     }
 }
 const version = readPackageJson().version ?? 'unknown';
-const yargsInstance = yargs(hideBin(process.argv))
-    .scriptName('npx chrome-devtools-mcp@latest')
-    .options(cliOptions)
-    .check(args => {
-    // We can't set default in the options else
-    // Yargs will complain
-    if (!args.channel && !args.browserUrl) {
-        args.channel = 'stable';
-    }
-    return true;
-})
-    .example([
-    [
-        '$0 --browserUrl http://127.0.0.1:9222',
-        'Connect to an existing browser instance',
-    ],
-    ['$0 --channel beta', 'Use Chrome Beta installed on this system'],
-    ['$0 --channel canary', 'Use Chrome Canary installed on this system'],
-    ['$0 --channel dev', 'Use Chrome Dev installed on this system'],
-    ['$0 --channel stable', 'Use stable Chrome installed on this system'],
-    ['$0 --logFile /tmp/log.txt', 'Save logs to a file'],
-    ['$0 --help', 'Print CLI options'],
-]);
-export const args = yargsInstance
-    .wrap(Math.min(120, yargsInstance.terminalWidth()))
-    .help()
-    .version(version)
-    .parseSync();
+export const args = parseArguments(version);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
 logger(`Starting Chrome DevTools MCP Server v${version}`);
 const server = new McpServer({

package/build/src/tools/ToolDefinition.js

@@ -6,3 +6,4 @@
 export function defineTool(definition) {
     return definition;
 }
+export const CLOSE_PAGE_ERROR = 'The last open page cannot be closed. It is fine to keep it open.';

package/build/src/tools/emulation.js

@@ -3,10 +3,10 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import z from 'zod';
-import { defineTool } from './ToolDefinition.js';
 import { PredefinedNetworkConditions } from 'puppeteer-core';
+import z from 'zod';
 import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
 const throttlingOptions = [
     'No emulation',
     ...Object.keys(PredefinedNetworkConditions),

package/build/src/tools/input.js

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import z from 'zod';
-import { defineTool } from './ToolDefinition.js';
 import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
 export const click = defineTool({
     name: 'click',
     description: `Clicks on the provided element`,
@@ -37,7 +37,7 @@ export const click = defineTool({
             response.setIncludeSnapshot(true);
         }
         finally {
-            handle.dispose();
+            void handle.dispose();
         }
     },
 });
@@ -64,7 +64,7 @@ export const hover = defineTool({
             response.setIncludeSnapshot(true);
         }
         finally {
-            handle.dispose();
+            void handle.dispose();
         }
     },
 });
@@ -91,7 +91,7 @@ export const fill = defineTool({
             response.setIncludeSnapshot(true);
         }
         finally {
-            handle.dispose();
+            void handle.dispose();
         }
     },
 });
@@ -119,8 +119,8 @@ export const drag = defineTool({
             response.setIncludeSnapshot(true);
         }
         finally {
-            fromHandle.dispose();
-            toHandle.dispose();
+            void fromHandle.dispose();
+            void toHandle.dispose();
         }
     },
 });
@@ -148,7 +148,7 @@ export const fillForm = defineTool({
                 });
             }
             finally {
-                handle.dispose();
+                void handle.dispose();
             }
         }
         response.appendResponseLine(`Successfully filled out the form`);
@@ -195,7 +195,7 @@ export const uploadFile = defineTool({
             response.appendResponseLine(`File uploaded from ${filePath}.`);
         }
         finally {
-            handle.dispose();
+            void handle.dispose();
         }
     },
 });

package/build/src/tools/network.js

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import z from 'zod';
-import { defineTool } from './ToolDefinition.js';
 import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
 export const listNetworkRequests = defineTool({
     name: 'list_network_requests',
     description: `List all requests for the currently selected page`,
@@ -13,9 +13,25 @@ export const listNetworkRequests = defineTool({
         category: ToolCategories.NETWORK,
         readOnlyHint: true,
     },
-    schema: {},
-    handler: async (_request, response) => {
-        response.setIncludeNetworkRequests(true);
+    schema: {
+        pageSize: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Maximum number of requests to return. When omitted, returns all requests.'),
+        pageIdx: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('Page number to return (0-based). When omitted, returns the first page.'),
+    },
+    handler: async (request, response) => {
+        response.setIncludeNetworkRequests(true, {
+            pageSize: request.params.pageSize,
+            pageIdx: request.params.pageIdx,
+        });
     },
 });
 export const getNetworkRequest = defineTool({

package/build/src/tools/pages.js

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import z from 'zod';
-import { defineTool } from './ToolDefinition.js';
 import { ToolCategories } from './categories.js';
+import { CLOSE_PAGE_ERROR, defineTool } from './ToolDefinition.js';
 export const listPages = defineTool({
     name: 'list_pages',
     description: `Get a list of pages open in the browser.`,
@@ -50,7 +50,17 @@ export const closePage = defineTool({
             .describe('The index of the page to close. Call list_pages to list pages.'),
     },
     handler: async (request, response, context) => {
-        await context.closePage(request.params.pageIdx);
+        try {
+            await context.closePage(request.params.pageIdx);
+        }
+        catch (err) {
+            if (err.message === CLOSE_PAGE_ERROR) {
+                response.appendResponseLine(err.message);
+            }
+            else {
+                throw err;
+            }
+        }
         response.setIncludePages(true);
     },
 });

package/build/src/tools/performance.js

@@ -4,10 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import z from 'zod';
-import { defineTool } from './ToolDefinition.js';
-import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
 import { logger } from '../logger.js';
+import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
 import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
 export const startTrace = defineTool({
     name: 'performance_start_trace',
     description: 'Starts a performance trace recording on the selected page.',

package/build/src/tools/screenshot.js

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import z from 'zod';
-import { defineTool } from './ToolDefinition.js';
 import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
 export const screenshot = defineTool({
     name: 'take_screenshot',
     description: `Take a screenshot of the page or element.`,

package/build/src/tools/script.js

@@ -1,11 +1,6 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
 import z from 'zod';
-import { defineTool } from './ToolDefinition.js';
 import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
 export const evaluateScript = defineTool({
     name: 'evaluate_script',
     description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON
@@ -54,7 +49,9 @@ Example with arguments: \`(el) => {
             });
         }
         finally {
-            Promise.allSettled(args.map(arg => arg.dispose())).catch(() => { });
+            Promise.allSettled(args.map(arg => arg.dispose())).catch(() => {
+                // Ignore errors
+            });
         }
     },
 });

package/build/src/tools/snapshot.js

@@ -3,10 +3,10 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import z from 'zod';
-import { defineTool } from './ToolDefinition.js';
 import { Locator } from 'puppeteer-core';
+import z from 'zod';
 import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
 export const takeSnapshot = defineTool({
     name: 'take_snapshot',
     description: `Take a text snapshot of the currently selected page. The snapshot lists page elements along with a unique

package/build/src/trace-processing/parse.js

@@ -3,11 +3,11 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { PerformanceTraceFormatter } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.js';
 import { PerformanceInsightFormatter } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.js';
+import { PerformanceTraceFormatter } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.js';
+import { AgentFocus } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/performance/AIContext.js';
 import * as TraceEngine from '../../node_modules/chrome-devtools-frontend/front_end/models/trace/trace.js';
 import { logger } from '../logger.js';
-import { AgentFocus } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/performance/AIContext.js';
 const engine = TraceEngine.TraceModel.Model.createWithAllHandlers();
 export function traceResultIsSuccess(x) {
     return 'parsedTrace' in x;
@@ -50,9 +50,8 @@ export async function parseRawTraceBuffer(buffer) {
     }
 }
 export function getTraceSummary(result) {
-    const focus = AgentFocus.full(result.parsedTrace);
-    const serializer = new TraceEngine.EventsSerializer.EventsSerializer();
-    const formatter = new PerformanceTraceFormatter(focus, serializer);
+    const focus = AgentFocus.fromParsedTrace(result.parsedTrace);
+    const formatter = new PerformanceTraceFormatter(focus, PerformanceInsightFormatter.create);
     const output = formatter.formatTraceSummary();
     return output;
 }
@@ -81,6 +80,6 @@ export function getInsightOutput(result, insightName) {
             error: `No Insight with the name ${insightName} found. Double check the name you provided is accurate and try again.`,
         };
     }
-    const formatter = new PerformanceInsightFormatter(result.parsedTrace, matchingInsight);
+    const formatter = new PerformanceInsightFormatter(AgentFocus.fromParsedTrace(result.parsedTrace), matchingInsight);
     return { output: formatter.formatInsight() };
 }

package/build/src/utils/pagination.js

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const DEFAULT_PAGE_SIZE = 20;
+export function paginate(items, options) {
+    const total = items.length;
+    if (!options || noPaginationOptions(options)) {
+        return {
+            items,
+            currentPage: 0,
+            totalPages: 1,
+            hasNextPage: false,
+            hasPreviousPage: false,
+            startIndex: 0,
+            endIndex: total,
+            invalidPage: false,
+        };
+    }
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    const totalPages = Math.max(1, Math.ceil(total / pageSize));
+    const { currentPage, invalidPage } = resolvePageIndex(options.pageIdx, totalPages);
+    const startIndex = currentPage * pageSize;
+    const pageItems = items.slice(startIndex, startIndex + pageSize);
+    const endIndex = startIndex + pageItems.length;
+    return {
+        items: pageItems,
+        currentPage,
+        totalPages,
+        hasNextPage: currentPage < totalPages - 1,
+        hasPreviousPage: currentPage > 0,
+        startIndex,
+        endIndex,
+        invalidPage,
+    };
+}
+function noPaginationOptions(options) {
+    return options.pageSize === undefined && options.pageIdx === undefined;
+}
+function resolvePageIndex(pageIdx, totalPages) {
+    if (pageIdx === undefined) {
+        return { currentPage: 0, invalidPage: false };
+    }
+    if (pageIdx < 0 || pageIdx >= totalPages) {
+        return { currentPage: 0, invalidPage: true };
+    }
+    return { currentPage: pageIdx, invalidPage: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-devtools-mcp",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "MCP server for Chrome DevTools",
   "type": "module",
   "bin": "./build/src/index.js",
@@ -38,11 +38,12 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.18.1",
     "debug": "4.4.3",
-    "puppeteer-core": "24.22.2",
+    "puppeteer-core": "24.22.3",
     "yargs": "18.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.35.0",
+    "@stylistic/eslint-plugin": "^5.4.0",
     "@types/debug": "^4.1.12",
     "@types/filesystem": "^0.0.36",
     "@types/node": "^24.3.3",
@@ -50,14 +51,16 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1516909",
+    "chrome-devtools-frontend": "1.0.1520139",
     "eslint": "^9.35.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-import-resolver-typescript": "^4.4.4",
     "globals": "^16.4.0",
     "prettier": "^3.6.2",
-    "puppeteer": "24.22.2",
+    "puppeteer": "24.22.3",
     "sinon": "^21.0.0",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.43.0"
+    "typescript-eslint": "^8.43.0",
+    "typescript": "^5.9.2"
   },
   "engines": {
     "node": ">=22.12.0"