chrome-devtools-mcp 0.17.0 → 0.17.2

package/README.md

@@ -113,12 +113,34 @@ Chrome DevTools MCP will not start the browser instance automatically using this
 
 <details>
   <summary>Claude Code</summary>
-    Use the Claude Code CLI to add the Chrome DevTools MCP server (<a href="https://code.claude.com/docs/en/mcp">guide</a>):
+
+**Install via CLI (MCP only)**
+
+Use the Claude Code CLI to add the Chrome DevTools MCP server (<a href="https://code.claude.com/docs/en/mcp">guide</a>):
 
 ```bash
 claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
 ```
 
+**Install as a Plugin (MCP + Skills)**
+
+> [!NOTE]  
+> If you already had Chrome DevTools MCP installed previously for Claude Code, make sure to remove it first from your installation and configuration files.
+
+To install Chrome DevTools MCP with skills, add the marketplace registry in Claude Code:
+
+```sh
+/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
+```
+
+Then, install the plugin:
+
+```sh
+/plugin install chrome-devtools-mcp
+```
+
+Restart Claude Code to have the MCP server and skills load (check with `/skills`).
+
 </details>
 
 <details>
@@ -128,7 +150,7 @@ claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
 
 <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>
+  Follow the <a href="https://developers.openai.com/codex/mcp/#configure-with-the-cli">configure MCP guide</a>
   using the standard config from above. You can also install the Chrome DevTools MCP server using the Codex CLI:
 
 ```bash
@@ -266,6 +288,30 @@ Or, from the IDE **Activity Bar** > `Kiro` > `MCP Servers` > `Click Open MCP Con
 
 </details>
 
+<details>
+  <summary>Katalon Studio</summary>
+
+The Chrome DevTools MCP server can be used with <a href="https://docs.katalon.com/katalon-studio/studioassist/mcp-servers/setting-up-chrome-devtools-mcp-server-for-studioassist">Katalon StudioAssist</a> via an MCP proxy.
+
+**Step 1:** Install the MCP proxy by following the <a href="https://docs.katalon.com/katalon-studio/studioassist/mcp-servers/setting-up-mcp-proxy-for-stdio-mcp-servers">MCP proxy setup guide</a>.
+
+**Step 2:** Start the Chrome DevTools MCP server with the proxy:
+
+```bash
+mcp-proxy --transport streamablehttp --port 8080 -- npx -y chrome-devtools-mcp@latest
+```
+
+**Note:** You may need to pick another port if 8080 is already in use.
+
+**Step 3:** In Katalon Studio, add the server to StudioAssist with the following settings:
+
+- **Connection URL:** `http://127.0.0.1:8080/mcp`
+- **Transport type:** `HTTP`
+
+Once connected, the Chrome DevTools MCP tools will be available in StudioAssist.
+
+</details>
+
 <details>
   <summary>OpenCode</summary>
 
@@ -669,11 +715,4 @@ Please consult [these instructions](./docs/debugging-android.md).
 
 ## Known limitations
 
-### Operating system sandboxes
-
-Some MCP clients allow sandboxing the MCP server using macOS Seatbelt or Linux
-containers. If sandboxes are enabled, `chrome-devtools-mcp` is not able to start
-Chrome that requires permissions to create its own sandboxes. As a workaround,
-either disable sandboxing for `chrome-devtools-mcp` in your MCP client or use
-`--browser-url` to connect to a Chrome instance that you start manually outside
-of the MCP client sandbox.
+See [Troubleshooting](./docs/troubleshooting.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-devtools-mcp",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "MCP server for Chrome DevTools",
   "type": "module",
   "bin": "./build/src/index.js",
@@ -20,7 +20,7 @@
     "test:no-build": "node scripts/test.mjs",
     "test:only": "npm run build && node scripts/test.mjs --test-only",
     "test:update-snapshots": "npm run build && node scripts/test.mjs --test-update-snapshots",
-    "prepare": "node --experimental-strip-types scripts/prepare.ts",
+    "prepare": "npm run clean && node --experimental-strip-types scripts/prepare.ts",
     "verify-server-json-version": "node --experimental-strip-types scripts/verify-server-json-version.ts",
     "eval": "npm run build && CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=true node --experimental-strip-types scripts/eval_gemini.ts",
     "count-tokens": "node --experimental-strip-types scripts/count_tokens.ts"
@@ -54,7 +54,7 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1581449",
+    "chrome-devtools-frontend": "1.0.1583146",
     "core-js": "3.48.0",
     "debug": "4.4.3",
     "eslint": "^9.35.0",
@@ -62,11 +62,12 @@
     "eslint-plugin-import": "^2.32.0",
     "globals": "^17.0.0",
     "prettier": "^3.6.2",
-    "puppeteer": "24.37.2",
+    "puppeteer": "24.37.4",
     "rollup": "4.57.1",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-license": "^3.6.0",
     "sinon": "^21.0.0",
+    "tiktoken": "^1.0.22",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.43.0",
     "yargs": "18.0.0"

package/build/src/DevToolsConnectionAdapter.js

@@ -1,69 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import { CDPSessionEvent } from './third_party/index.js';
-/**
- * This class makes a puppeteer connection look like DevTools CDPConnection.
- *
- * Since we connect "root" DevTools targets to specific pages, we scope everything to a puppeteer CDP session.
- *
- * We don't have to recursively listen for 'sessionattached' as the "root" CDP session sees all child session attached
- * events, regardless how deeply nested they are.
- */
-export class PuppeteerDevToolsConnection {
-    #connection;
-    #observers = new Set();
-    #sessionEventHandlers = new Map();
-    constructor(session) {
-        this.#connection = session.connection();
-        session.on(CDPSessionEvent.SessionAttached, this.#startForwardingCdpEvents.bind(this));
-        session.on(CDPSessionEvent.SessionDetached, this.#stopForwardingCdpEvents.bind(this));
-        this.#startForwardingCdpEvents(session);
-    }
-    send(method, params, sessionId) {
-        if (sessionId === undefined) {
-            throw new Error('Attempting to send on the root session. This must not happen');
-        }
-        const session = this.#connection.session(sessionId);
-        if (!session) {
-            throw new Error('Unknown session ' + sessionId);
-        }
-        // Rolled protocol version between puppeteer and DevTools doesn't necessarily match
-        /* eslint-disable @typescript-eslint/no-explicit-any */
-        return session
-            .send(method, params)
-            .then(result => ({ result }))
-            .catch(error => ({ error }));
-        /* eslint-enable @typescript-eslint/no-explicit-any */
-    }
-    observe(observer) {
-        this.#observers.add(observer);
-    }
-    unobserve(observer) {
-        this.#observers.delete(observer);
-    }
-    #startForwardingCdpEvents(session) {
-        const handler = this.#handleEvent.bind(this, session.id());
-        this.#sessionEventHandlers.set(session.id(), handler);
-        session.on('*', handler);
-    }
-    #stopForwardingCdpEvents(session) {
-        const handler = this.#sessionEventHandlers.get(session.id());
-        if (handler) {
-            session.off('*', handler);
-        }
-    }
-    #handleEvent(sessionId, type, event) {
-        if (typeof type === 'string' &&
-            type !== CDPSessionEvent.SessionAttached &&
-            type !== CDPSessionEvent.SessionDetached) {
-            this.#observers.forEach(observer => observer.onEvent({
-                method: type,
-                sessionId,
-                params: event,
-            }));
-        }
-    }
-}

package/build/src/DevtoolsUtils.js

@@ -1,340 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import { PuppeteerDevToolsConnection } from './DevToolsConnectionAdapter.js';
-import { Mutex } from './Mutex.js';
-import { DevTools } from './third_party/index.js';
-export function extractUrlLikeFromDevToolsTitle(title) {
-    const match = title.match(new RegExp(`DevTools - (.*)`));
-    return match?.[1] ?? undefined;
-}
-export function urlsEqual(url1, url2) {
-    const normalizedUrl1 = normalizeUrl(url1);
-    const normalizedUrl2 = normalizeUrl(url2);
-    return normalizedUrl1 === normalizedUrl2;
-}
-/**
- * For the sake of the MCP server, when we determine if two URLs are equal we
- * remove some parts:
- *
- * 1. We do not care about the protocol.
- * 2. We do not care about trailing slashes.
- * 3. We do not care about "www".
- * 4. We ignore the hash parts.
- *
- * For example, if the user types "record a trace on foo.com", we would want to
- * match a tab in the connected Chrome instance that is showing "www.foo.com/"
- */
-function normalizeUrl(url) {
-    let result = url.trim();
-    // Remove protocols
-    if (result.startsWith('https://')) {
-        result = result.slice(8);
-    }
-    else if (result.startsWith('http://')) {
-        result = result.slice(7);
-    }
-    // Remove 'www.'. This ensures that we find the right URL regardless of if the user adds `www` or not.
-    if (result.startsWith('www.')) {
-        result = result.slice(4);
-    }
-    // We use target URLs to locate DevTools but those often do
-    // no include hash.
-    const hashIdx = result.lastIndexOf('#');
-    if (hashIdx !== -1) {
-        result = result.slice(0, hashIdx);
-    }
-    // Remove trailing slash
-    if (result.endsWith('/')) {
-        result = result.slice(0, -1);
-    }
-    return result;
-}
-/**
- * A mock implementation of an issues manager that only implements the methods
- * that are actually used by the IssuesAggregator
- */
-export class FakeIssuesManager extends DevTools.Common.ObjectWrapper
-    .ObjectWrapper {
-    issues() {
-        return [];
-    }
-}
-// DevTools CDP errors can get noisy.
-DevTools.ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
-DevTools.I18n.DevToolsLocale.DevToolsLocale.instance({
-    create: true,
-    data: {
-        navigatorLanguage: 'en-US',
-        settingLanguage: 'en-US',
-        lookupClosestDevToolsLocale: l => l,
-    },
-});
-DevTools.I18n.i18n.registerLocaleDataForTest('en-US', {});
-DevTools.Formatter.FormatterWorkerPool.FormatterWorkerPool.instance({
-    forceNew: true,
-    entrypointURL: import.meta
-        .resolve('./third_party/devtools-formatter-worker.js'),
-});
-export class UniverseManager {
-    #browser;
-    #createUniverseFor;
-    #universes = new WeakMap();
-    /** Guard access to #universes so we don't create unnecessary universes */
-    #mutex = new Mutex();
-    constructor(browser, factory = DEFAULT_FACTORY) {
-        this.#browser = browser;
-        this.#createUniverseFor = factory;
-    }
-    async init(pages) {
-        try {
-            await this.#mutex.acquire();
-            const promises = [];
-            for (const page of pages) {
-                promises.push(this.#createUniverseFor(page).then(targetUniverse => this.#universes.set(page, targetUniverse)));
-            }
-            this.#browser.on('targetcreated', this.#onTargetCreated);
-            this.#browser.on('targetdestroyed', this.#onTargetDestroyed);
-            await Promise.all(promises);
-        }
-        finally {
-            this.#mutex.release();
-        }
-    }
-    get(page) {
-        return this.#universes.get(page) ?? null;
-    }
-    dispose() {
-        this.#browser.off('targetcreated', this.#onTargetCreated);
-        this.#browser.off('targetdestroyed', this.#onTargetDestroyed);
-    }
-    #onTargetCreated = async (target) => {
-        const page = await target.page();
-        try {
-            await this.#mutex.acquire();
-            if (!page || this.#universes.has(page)) {
-                return;
-            }
-            this.#universes.set(page, await this.#createUniverseFor(page));
-        }
-        finally {
-            this.#mutex.release();
-        }
-    };
-    #onTargetDestroyed = async (target) => {
-        const page = await target.page();
-        try {
-            await this.#mutex.acquire();
-            if (!page || !this.#universes.has(page)) {
-                return;
-            }
-            this.#universes.delete(page);
-        }
-        finally {
-            this.#mutex.release();
-        }
-    };
-}
-const DEFAULT_FACTORY = async (page) => {
-    const settingStorage = new DevTools.Common.Settings.SettingsStorage({});
-    const universe = new DevTools.Foundation.Universe.Universe({
-        settingsCreationOptions: {
-            syncedStorage: settingStorage,
-            globalStorage: settingStorage,
-            localStorage: settingStorage,
-            settingRegistrations: DevTools.Common.SettingRegistration.getRegisteredSettings(),
-        },
-        overrideAutoStartModels: new Set([DevTools.DebuggerModel]),
-    });
-    const session = await page.createCDPSession();
-    const connection = new PuppeteerDevToolsConnection(session);
-    const targetManager = universe.context.get(DevTools.TargetManager);
-    targetManager.observeModels(DevTools.DebuggerModel, SKIP_ALL_PAUSES);
-    const target = targetManager.createTarget('main', '', 'frame', // eslint-disable-line @typescript-eslint/no-explicit-any
-    /* parentTarget */ null, session.id(), undefined, connection);
-    return { target, universe };
-};
-// We don't want to pause any DevTools universe session ever on the MCP side.
-//
-// Note that calling `setSkipAllPauses` only affects the session on which it was
-// sent. This means DevTools can still pause, step and do whatever. We just won't
-// see the `Debugger.paused`/`Debugger.resumed` events on the MCP side.
-const SKIP_ALL_PAUSES = {
-    modelAdded(model) {
-        void model.agent.invoke_setSkipAllPauses({ skip: true });
-    },
-    modelRemoved() {
-        // Do nothing.
-    },
-};
-/**
- * Constructed from Runtime.ExceptionDetails of an uncaught error.
- *
- * TODO: Also construct from a RemoteObject of subtype 'error'.
- *
- * Consists of the message, a fully resolved stack trace and a fully resolved 'cause' chain.
- */
-export class SymbolizedError {
-    message;
-    stackTrace;
-    cause;
-    constructor(message, stackTrace, cause) {
-        this.message = message;
-        this.stackTrace = stackTrace;
-        this.cause = cause;
-    }
-    static async fromDetails(opts) {
-        const message = SymbolizedError.#getMessage(opts.details);
-        if (!opts.includeStackAndCause || !opts.devTools) {
-            return new SymbolizedError(message, opts.resolvedStackTraceForTesting, opts.resolvedCauseForTesting);
-        }
-        let stackTrace;
-        if (opts.resolvedStackTraceForTesting) {
-            stackTrace = opts.resolvedStackTraceForTesting;
-        }
-        else if (opts.details.stackTrace) {
-            try {
-                stackTrace = await createStackTrace(opts.devTools, opts.details.stackTrace, opts.targetId);
-            }
-            catch {
-                // ignore
-            }
-        }
-        // TODO: Turn opts.details.exception into a JSHandle and retrieve the 'cause' property.
-        //       If its an Error, recursively create a SymbolizedError.
-        let cause;
-        if (opts.resolvedCauseForTesting) {
-            cause = opts.resolvedCauseForTesting;
-        }
-        else if (opts.details.exception) {
-            try {
-                const causeRemoteObj = await SymbolizedError.#lookupCause(opts.devTools, opts.details.exception, opts.targetId);
-                if (causeRemoteObj) {
-                    cause = await SymbolizedError.fromError({
-                        devTools: opts.devTools,
-                        error: causeRemoteObj,
-                        targetId: opts.targetId,
-                    });
-                }
-            }
-            catch {
-                // Ignore
-            }
-        }
-        return new SymbolizedError(message, stackTrace, cause);
-    }
-    static async fromError(opts) {
-        const details = await SymbolizedError.#getExceptionDetails(opts.devTools, opts.error, opts.targetId);
-        if (details) {
-            return SymbolizedError.fromDetails({
-                details,
-                devTools: opts.devTools,
-                targetId: opts.targetId,
-                includeStackAndCause: true,
-            });
-        }
-        return new SymbolizedError(SymbolizedError.#getMessageFromException(opts.error));
-    }
-    static #getMessage(details) {
-        // For Runtime.exceptionThrown with a present exception object, `details.text` will be "Uncaught" and
-        // we have to manually parse out the error text from the exception description.
-        // In the case of Runtime.getExceptionDetails, `details.text` has the Error.message.
-        if (details.text === 'Uncaught' && details.exception) {
-            return ('Uncaught ' +
-                SymbolizedError.#getMessageFromException(details.exception));
-        }
-        return details.text;
-    }
-    static #getMessageFromException(error) {
-        const messageWithRest = error.description?.split('\n    at ', 2) ?? [];
-        return messageWithRest[0] ?? '';
-    }
-    static async #getExceptionDetails(devTools, error, targetId) {
-        if (!devTools || (error.type !== 'object' && error.subtype !== 'error')) {
-            return null;
-        }
-        const targetManager = devTools.universe.context.get(DevTools.TargetManager);
-        const target = targetId
-            ? targetManager.targetById(targetId) || devTools.target
-            : devTools.target;
-        const model = target.model(DevTools.RuntimeModel);
-        return ((await model.getExceptionDetails(error.objectId)) ?? null);
-    }
-    static async #lookupCause(devTools, error, targetId) {
-        if (!devTools || (error.type !== 'object' && error.subtype !== 'error')) {
-            return null;
-        }
-        const targetManager = devTools.universe.context.get(DevTools.TargetManager);
-        const target = targetId
-            ? targetManager.targetById(targetId) || devTools.target
-            : devTools.target;
-        const properties = await target.runtimeAgent().invoke_getProperties({
-            objectId: error.objectId,
-        });
-        if (properties.getError()) {
-            return null;
-        }
-        return properties.result.find(prop => prop.name === 'cause')?.value ?? null;
-    }
-    static createForTesting(message, stackTrace, cause) {
-        return new SymbolizedError(message, stackTrace, cause);
-    }
-}
-export async function createStackTraceForConsoleMessage(devTools, consoleMessage) {
-    const message = consoleMessage;
-    const rawStackTrace = message._rawStackTrace();
-    if (rawStackTrace) {
-        return createStackTrace(devTools, rawStackTrace, message._targetId());
-    }
-    return undefined;
-}
-export async function createStackTrace(devTools, rawStackTrace, targetId) {
-    const targetManager = devTools.universe.context.get(DevTools.TargetManager);
-    const target = targetId
-        ? targetManager.targetById(targetId) || devTools.target
-        : devTools.target;
-    const model = target.model(DevTools.DebuggerModel);
-    // DevTools doesn't wait for source maps to attach before building a stack trace, rather it'll send
-    // an update event once a source map was attached and the stack trace retranslated. This doesn't
-    // work in the MCP case, so we'll collect all script IDs upfront and wait for any pending source map
-    // loads before creating the stack trace. We might also have to wait for Debugger.ScriptParsed events if
-    // the stack trace is created particularly early.
-    const scriptIds = new Set();
-    for (const frame of rawStackTrace.callFrames) {
-        scriptIds.add(frame.scriptId);
-    }
-    for (let asyncStack = rawStackTrace.parent; asyncStack; asyncStack = asyncStack.parent) {
-        for (const frame of asyncStack.callFrames) {
-            scriptIds.add(frame.scriptId);
-        }
-    }
-    const signal = AbortSignal.timeout(1_000);
-    await Promise.all([...scriptIds].map(id => waitForScript(model, id, signal)
-        .then(script => model.sourceMapManager().sourceMapForClientPromise(script))
-        .catch()));
-    const binding = devTools.universe.context.get(DevTools.DebuggerWorkspaceBinding);
-    // DevTools uses branded types for ScriptId and others. Casting the puppeteer protocol type to the DevTools protocol type is safe.
-    return binding.createStackTraceFromProtocolRuntime(rawStackTrace, target);
-}
-// Waits indefinitely for the script so pair it with Promise.race.
-async function waitForScript(model, scriptId, signal) {
-    while (true) {
-        if (signal.aborted) {
-            throw signal.reason;
-        }
-        const script = model.scriptForId(scriptId);
-        if (script) {
-            return script;
-        }
-        await new Promise((resolve, reject) => {
-            signal.addEventListener('abort', () => reject(signal.reason), {
-                once: true,
-            });
-            void model
-                .once('ParsedScriptSource')
-                .then(resolve);
-        });
-    }
-}