chrome-devtools-mcp 0.2.1 → 0.2.3

package/README.md

@@ -66,6 +66,17 @@ claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
   Follow https://docs.cline.bot/mcp/configuring-mcp-servers and use the config provided above.
 </details>
 
+<details>
+  <summary>Codex</summary>
+  Follow the <a href="https://github.com/openai/codex/blob/main/docs/advanced.md#model-context-protocol-mcp">configure MCP guide</a>
+  using the standard config from above. You can also install the Chrome DevTools MCP server using the Codex CLI:
+
+```bash
+codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+```
+
+</details>
+
 <details>
   <summary>Copilot / VS Code</summary>
   Follow the MCP install <a href="https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server">guide</a>,
@@ -101,6 +112,19 @@ Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided ab
   using the standard config from above.
 </details>
 
+### Your first prompt
+
+Enter the following prompt in your MCP Client to check if everything is working:
+
+```
+Check the performance of https://developers.chrome.com
+```
+
+Your MCP client should open the browser and record a performance trace.
+
+> [!NOTE]  
+> The MCP server will start the browser automatically once the MCP client uses a tool that requires a running browser instance. Connecting to the Chrome DevTools MCP server on its own will not automatically start the browser.
+
 ## Tools
 
 <!-- BEGIN AUTO GENERATED TOOLS -->

package/build/src/McpResponse.js

@@ -123,7 +123,12 @@ Call browser_handle_dialog to handle it before continuing.`);
         }
         if (this.#includeConsoleData && this.#formattedConsoleData) {
             response.push('## Console messages');
-            response.push(...this.#formattedConsoleData);
+            if (this.#formattedConsoleData.length) {
+                response.push(...this.#formattedConsoleData);
+            }
+            else {
+                response.push('<no console messages found>');
+            }
         }
         const text = {
             type: 'text',

package/build/src/WaitForHelper.js

@@ -99,16 +99,27 @@ export class WaitForHelper {
         });
     }
     async waitForEventsAfterAction(action) {
-        const navigationStartedPromise = this.waitForNavigationStarted();
-        await action();
-        try {
-            const navigationStated = await navigationStartedPromise;
+        const navigationFinished = this.waitForNavigationStarted()
+            .then(navigationStated => {
             if (navigationStated) {
-                await this.#page.waitForNavigation({
+                return this.#page.waitForNavigation({
                     timeout: this.#navigationTimeout,
                     signal: this.#abortController.signal,
                 });
             }
+            return;
+        })
+            .catch(error => logger(error));
+        try {
+            await action();
+        }
+        catch (error) {
+            // Clear up pending promises
+            this.#abortController.abort();
+            throw error;
+        }
+        try {
+            await navigationFinished;
             // Wait for stable dom after navigation so we execute in
             // the correct context
             await this.waitForStableDom();

package/build/src/index.js

@@ -71,6 +71,22 @@ export const cliOptions = {
         hidden: true,
     },
 };
+function readPackageJson() {
+    const currentDir = import.meta.dirname;
+    const packageJsonPath = path.join(currentDir, '..', '..', 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        return {};
+    }
+    try {
+        const json = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        assert.strict(json['name'], 'chrome-devtools-mcp');
+        return json;
+    }
+    catch {
+        return {};
+    }
+}
+const version = readPackageJson().version ?? 'unknown';
 const yargsInstance = yargs(hideBin(process.argv))
     .scriptName('npx chrome-devtools-mcp@latest')
     .options(cliOptions)
@@ -97,24 +113,9 @@ const yargsInstance = yargs(hideBin(process.argv))
 export const args = yargsInstance
     .wrap(Math.min(120, yargsInstance.terminalWidth()))
     .help()
+    .version(version)
     .parseSync();
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
-function readPackageJson() {
-    const currentDir = import.meta.dirname;
-    const packageJsonPath = path.join(currentDir, '..', '..', 'package.json');
-    if (!fs.existsSync(packageJsonPath)) {
-        return {};
-    }
-    try {
-        const json = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-        assert.strict(json['name'], 'chrome-devtools-mcp');
-        return json;
-    }
-    catch {
-        return {};
-    }
-}
-const version = readPackageJson().version ?? 'unknown';
 logger(`Starting Chrome DevTools MCP Server v${version}`);
 const server = new McpServer({
     name: 'chrome_devtools',

package/build/src/tools/performance.js

@@ -5,7 +5,7 @@
  */
 import z from 'zod';
 import { defineTool } from './ToolDefinition.js';
-import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, } from '../trace-processing/parse.js';
+import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
 import { logger } from '../logger.js';
 import { ToolCategories } from './categories.js';
 export const startTrace = defineTool({
@@ -122,20 +122,22 @@ async function stopTracingAndAppendOutput(page, response, context) {
         const traceEventsBuffer = await page.tracing.stop();
         const result = await parseRawTraceBuffer(traceEventsBuffer);
         response.appendResponseLine('The performance trace has been stopped.');
-        if (result) {
+        if (traceResultIsSuccess(result)) {
             context.storeTraceRecording(result);
-            const insightText = getTraceSummary(result);
-            if (insightText) {
-                response.appendResponseLine('Insights with performance opportunities:');
-                response.appendResponseLine(insightText);
-            }
-            else {
-                response.appendResponseLine('No insights have been found. The performance looks good!');
-            }
+            response.appendResponseLine('Here is a high level summary of the trace and the Insights that were found:');
+            const traceSummaryText = getTraceSummary(result);
+            response.appendResponseLine(traceSummaryText);
+        }
+        else {
+            response.appendResponseLine('There was an unexpected error parsing the trace:');
+            response.appendResponseLine(result.error);
         }
     }
     catch (e) {
-        logger(`Error stopping performance trace: ${e instanceof Error ? e.message : JSON.stringify(e)}`);
+        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+        logger(`Error stopping performance trace: ${errorText}`);
+        response.appendResponseLine('An error occured generating the response for this trace:');
+        response.appendResponseLine(errorText);
     }
     finally {
         context.setIsRunningPerformanceTrace(false);

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

@@ -9,14 +9,21 @@ import * as TraceEngine from '../../node_modules/chrome-devtools-frontend/front_
 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;
+}
 export async function parseRawTraceBuffer(buffer) {
     engine.resetProcessor();
     if (!buffer) {
-        return null;
+        return {
+            error: 'No buffer was provided.',
+        };
     }
     const asString = new TextDecoder().decode(buffer);
     if (!asString) {
-        return null;
+        return {
+            error: 'Decoding the trace buffer returned an empty string.',
+        };
     }
     try {
         const data = JSON.parse(asString);
@@ -24,25 +31,22 @@ export async function parseRawTraceBuffer(buffer) {
         await engine.parse(events);
         const parsedTrace = engine.parsedTrace();
         if (!parsedTrace) {
-            return null;
-        }
-        const insights = parsedTrace?.insights;
-        if (!insights) {
-            return null;
+            return {
+                error: 'No parsed trace was returned from the trace engine.',
+            };
         }
+        const insights = parsedTrace?.insights ?? null;
         return {
             parsedTrace,
             insights,
         };
     }
     catch (e) {
-        if (e instanceof Error) {
-            logger(`Error parsing trace: ${e.message}`);
-        }
-        else {
-            logger(`Error parsing trace: ${JSON.stringify(e)}`);
-        }
-        return null;
+        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+        logger(`Unexpeced error parsing trace: ${errorText}`);
+        return {
+            error: errorText,
+        };
     }
 }
 export function getTraceSummary(result) {
@@ -53,6 +57,11 @@ export function getTraceSummary(result) {
     return output;
 }
 export function getInsightOutput(result, insightName) {
+    if (!result.insights) {
+        return {
+            error: 'No Performance insights are available for this trace.',
+        };
+    }
     // Currently, we do not support inspecting traces with multiple navigations. We either:
     // 1. Find Insights from the first navigation (common case: user records a trace with a page reload to test load performance)
     // 2. Fall back to finding Insights not associated with a navigation (common case: user tests an interaction without a page load).

package/package.json

@@ -1,11 +1,9 @@
 {
   "name": "chrome-devtools-mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "MCP server for Chrome DevTools",
   "type": "module",
-  "bin": {
-    "chrome-devtools-mcp": "./build/src/index.js"
-  },
+  "bin": "./build/src/index.js",
   "main": "index.js",
   "scripts": {
     "build": "tsc && node --experimental-strip-types --no-warnings=ExperimentalWarning scripts/post-build.ts",
@@ -38,7 +36,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.18.1",
     "debug": "4.4.3",
-    "puppeteer-core": "24.22.0",
+    "puppeteer-core": "24.22.2",
     "yargs": "18.0.0"
   },
   "devDependencies": {
@@ -54,7 +52,7 @@
     "eslint": "^9.35.0",
     "globals": "^16.4.0",
     "prettier": "^3.6.2",
-    "puppeteer": "24.22.0",
+    "puppeteer": "24.22.2",
     "sinon": "^21.0.0",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.43.0"