@yezack/chrome-devtools-mcp-108 0.0.0-stage → 1.10.2

package/build/src/SlimMcpResponse.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { McpResponse } from './McpResponse.js';
+export class SlimMcpResponse extends McpResponse {
+    async handle(_context) {
+        const text = {
+            type: 'text',
+            text: this.responseLines.join('\n'),
+        };
+        return {
+            content: [text],
+            structuredContent: text,
+        };
+    }
+}
+//# sourceMappingURL=SlimMcpResponse.js.map

package/build/src/TextSnapshot.js

@@ -0,0 +1,315 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { logger } from './utils/logger.js';
+export class TextSnapshot {
+    static nextSnapshotId = 1;
+    static resetCounter() {
+        TextSnapshot.nextSnapshotId = 1;
+    }
+    root;
+    idToNode;
+    snapshotId;
+    selectedElementUid;
+    hasSelectedElement;
+    verbose;
+    constructor(data) {
+        this.root = data.root;
+        this.idToNode = data.idToNode;
+        this.snapshotId = data.snapshotId;
+        this.selectedElementUid = data.selectedElementUid;
+        this.hasSelectedElement = data.hasSelectedElement;
+        this.verbose = data.verbose;
+    }
+    static async create(page, options = {}) {
+        const verbose = options.verbose ?? false;
+        const rootNode = await page.pptrPage.accessibility.snapshot({
+            includeIframes: true,
+            interestingOnly: !verbose,
+        });
+        if (!rootNode) {
+            throw new Error('Failed to create accessibility snapshot');
+        }
+        const { uniqueBackendNodeIdToMcpId } = page;
+        const snapshotId = TextSnapshot.nextSnapshotId++;
+        // Iterate through the whole accessibility node tree and assign node ids that
+        // will be used for the tree serialization and mapping ids back to nodes.
+        let idCounter = 0;
+        const idToNode = new Map();
+        const seenUniqueIds = new Set();
+        const seenBackendNodeIds = new Set();
+        const assignIds = (node) => {
+            let id = '';
+            // @ts-expect-error untyped backendNodeId.
+            const backendNodeId = node.backendNodeId;
+            // @ts-expect-error untyped loaderId.
+            const uniqueBackendId = `${node.loaderId}_${backendNodeId}`;
+            const existingMcpId = uniqueBackendNodeIdToMcpId.get(uniqueBackendId);
+            if (existingMcpId !== undefined) {
+                // Re-use MCP exposed ID if the uniqueId is the same.
+                id = existingMcpId;
+            }
+            else {
+                // Only generate a new ID if we have not seen the node before.
+                id = `${snapshotId}_${idCounter++}`;
+                uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);
+            }
+            seenUniqueIds.add(uniqueBackendId);
+            seenBackendNodeIds.add(backendNodeId);
+            const nodeWithId = {
+                ...node,
+                id,
+                children: node.children
+                    ? node.children.map(child => assignIds(child))
+                    : [],
+            };
+            // The AXNode for an option doesn't contain its `value`.
+            // Therefore, set text content of the option as value.
+            if (node.role === 'option') {
+                const optionText = node.name;
+                if (optionText) {
+                    nodeWithId.value = optionText.toString();
+                }
+            }
+            idToNode.set(nodeWithId.id, nodeWithId);
+            return nodeWithId;
+        };
+        const rootNodeWithId = assignIds(rootNode);
+        await TextSnapshot.insertExtraNodes(page, idToNode, seenUniqueIds, snapshotId, idCounter, rootNodeWithId, seenBackendNodeIds, options.extraHandles ?? []);
+        const snapshot = new TextSnapshot({
+            root: rootNodeWithId,
+            snapshotId: String(snapshotId),
+            idToNode,
+            hasSelectedElement: false,
+            verbose,
+        });
+        const data = options.devtoolsData ?? (await page.getDevToolsData());
+        if (data?.cdpBackendNodeId) {
+            snapshot.hasSelectedElement = true;
+            snapshot.selectedElementUid = snapshot.resolveCdpElementId(data.cdpBackendNodeId);
+        }
+        // Clean up unique IDs that we did not see anymore.
+        for (const key of uniqueBackendNodeIdToMcpId.keys()) {
+            if (!seenUniqueIds.has(key)) {
+                uniqueBackendNodeIdToMcpId.delete(key);
+            }
+        }
+        return snapshot;
+    }
+    resolveCdpElementId(cdpBackendNodeId) {
+        if (!cdpBackendNodeId) {
+            logger?.('no cdpBackendNodeId');
+            return;
+        }
+        // TODO: index by backendNodeId instead.
+        const queue = [this.root];
+        while (queue.length) {
+            const current = queue.pop();
+            if (current.backendNodeId === cdpBackendNodeId) {
+                return current.id;
+            }
+            for (const child of current.children) {
+                queue.push(child);
+            }
+        }
+        return;
+    }
+    // ExtraHandles represent DOM nodes which might not be part of the accessibility tree, e.g. DOM nodes
+    // returned by third-party developer tools. We insert them into the tree by finding the closest ancestor
+    // in the tree and inserting the node as a child. The ancestor's child nodes are re-parented if necessary.
+    static async insertExtraNodes(page, idToNode, seenUniqueIds, snapshotId, idCounter, rootNodeWithId, seenBackendNodeIds, extraHandles) {
+        const { uniqueBackendNodeIdToMcpId } = page;
+        const createExtraNode = async (handle) => {
+            const backendNodeId = await handle.backendNodeId();
+            if (!backendNodeId || seenBackendNodeIds.has(backendNodeId)) {
+                return null;
+            }
+            const uniqueBackendId = `custom_${backendNodeId}`;
+            if (seenUniqueIds.has(uniqueBackendId)) {
+                return null;
+            }
+            seenBackendNodeIds.add(backendNodeId);
+            let id = '';
+            const mcpId = uniqueBackendNodeIdToMcpId.get(uniqueBackendId);
+            if (mcpId !== undefined) {
+                id = mcpId;
+            }
+            else {
+                id = `${snapshotId}_${idCounter++}`;
+                uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);
+            }
+            seenUniqueIds.add(uniqueBackendId);
+            const tagHandle = await handle.getProperty('localName');
+            const tagValue = await tagHandle.jsonValue();
+            const extraNode = {
+                role: tagValue,
+                id,
+                backendNodeId,
+                children: [],
+                elementHandle: async () => handle,
+            };
+            return extraNode;
+        };
+        const findAncestorNode = async (handle) => {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                let ancestorHandle = await handle.evaluateHandle(el => el.parentElement);
+                const stack = __addDisposableResource(env_1, new DisposableStack(), false);
+                while (ancestorHandle) {
+                    stack.use(ancestorHandle);
+                    const ancestorElement = ancestorHandle.asElement();
+                    if (!ancestorElement) {
+                        return null;
+                    }
+                    const ancestorBackendId = await ancestorElement.backendNodeId();
+                    if (ancestorBackendId) {
+                        const ancestorNode = idToNode
+                            .values()
+                            .find(node => node.backendNodeId === ancestorBackendId);
+                        if (ancestorNode) {
+                            return ancestorNode;
+                        }
+                    }
+                    const nextHandle = await ancestorElement.evaluateHandle(el => el.parentElement);
+                    ancestorHandle = nextHandle;
+                }
+                return null;
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
+            }
+        };
+        const findDescendantNodes = async (backendNodeId) => {
+            const descendantIds = new Set();
+            if (!backendNodeId) {
+                return descendantIds;
+            }
+            try {
+                // @ts-expect-error internal API
+                const client = page.pptrPage._client();
+                if (client) {
+                    const { node } = await client.send('DOM.describeNode', {
+                        backendNodeId,
+                        depth: -1,
+                        pierce: true,
+                    });
+                    const collect = (node) => {
+                        if (node.backendNodeId && node.backendNodeId !== backendNodeId) {
+                            descendantIds.add(node.backendNodeId);
+                        }
+                        if (node.children) {
+                            for (const child of node.children) {
+                                collect(child);
+                            }
+                        }
+                    };
+                    collect(node);
+                }
+            }
+            catch (e) {
+                logger?.(`Failed to collect descendants for backend node ${backendNodeId}`, e);
+            }
+            return descendantIds;
+        };
+        const moveChildNodes = (attachTarget, extraNode, descendantIds) => {
+            let firstMovedIndex = -1;
+            if (descendantIds.size > 0 && attachTarget.children) {
+                const remainingChildren = [];
+                for (const child of attachTarget.children) {
+                    if (child.backendNodeId && descendantIds.has(child.backendNodeId)) {
+                        if (firstMovedIndex === -1) {
+                            firstMovedIndex = remainingChildren.length;
+                        }
+                        extraNode.children.push(child);
+                    }
+                    else {
+                        remainingChildren.push(child);
+                    }
+                }
+                attachTarget.children = remainingChildren;
+            }
+            return firstMovedIndex !== -1
+                ? firstMovedIndex
+                : attachTarget.children
+                    ? attachTarget.children.length
+                    : 0;
+        };
+        if (extraHandles.length) {
+            page.extraHandles = extraHandles;
+        }
+        const reorgInfo = [];
+        for (const handle of page.extraHandles) {
+            const extraNode = await createExtraNode(handle);
+            if (!extraNode) {
+                continue;
+            }
+            idToNode.set(extraNode.id, extraNode);
+            const attachTarget = (await findAncestorNode(handle)) || rootNodeWithId;
+            const descendantIds = await findDescendantNodes(extraNode.backendNodeId);
+            reorgInfo.push({ extraNode, attachTarget, descendantIds });
+        }
+        for (const { extraNode, attachTarget, descendantIds } of reorgInfo) {
+            const index = moveChildNodes(attachTarget, extraNode, descendantIds);
+            attachTarget.children.splice(index, 0, extraNode);
+        }
+    }
+}
+//# sourceMappingURL=TextSnapshot.js.map

package/build/src/ToolHandler.js

@@ -0,0 +1,322 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { McpResponse } from './McpResponse.js';
+import { SlimMcpResponse } from './SlimMcpResponse.js';
+import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
+import { zod } from './third_party/index.js';
+import { labels } from './tools/categories.js';
+import { categoryToFlagName } from './config/category-options.js';
+import { logger } from './utils/logger.js';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isLocalhost } from './utils/url.js';
+function buildDisabledMessage(toolName, flag, categoryLabel) {
+    const reason = categoryLabel
+        ? `is in category ${categoryLabel} which`
+        : `requires ${flag.startsWith('--experimental') ? 'experimental feature' : 'flag'} ${flag} and`;
+    return `Tool ${toolName} ${reason} is currently disabled. Enable it by running chrome-devtools start ${flag}=true. For more information check the README.`;
+}
+function getToolStatusInfo(tool, serverArgs) {
+    const category = tool.annotations.category;
+    if (category) {
+        const flag = categoryToFlagName(category);
+        if (!serverArgs[flag]) {
+            return {
+                disabled: true,
+                reason: buildDisabledMessage(tool.name, `--${flag}`, labels[category]),
+            };
+        }
+    }
+    for (const condition of tool.annotations.conditions || []) {
+        if (!serverArgs[condition]) {
+            return {
+                disabled: true,
+                reason: buildDisabledMessage(tool.name, `--${condition}`),
+            };
+        }
+    }
+    return { disabled: false };
+}
+function isPageScopedTool(tool) {
+    return 'pageScoped' in tool && tool.pageScoped === true;
+}
+function formatArgumentNames(names) {
+    return names.map(name => `"${name}"`).join(', ');
+}
+function buildUnknownArgumentsMessage(toolName, unknownArgumentNames, expectedArgumentNames) {
+    const unknownLabel = unknownArgumentNames.length === 1 ? 'argument' : 'arguments';
+    const expectedArguments = expectedArgumentNames.length
+        ? `Expected arguments: ${formatArgumentNames(expectedArgumentNames)}.`
+        : 'This tool does not accept any arguments.';
+    const correction = unknownArgumentNames.length === 1 ? 'Remove it' : 'Remove them';
+    return `Unknown ${unknownLabel} for tool "${toolName}": ${formatArgumentNames(unknownArgumentNames)}. ${expectedArguments} ${correction} and retry.`;
+}
+async function validateAndResolvePathOrUrl(filePathOrUrl, context) {
+    try {
+        const url = new URL(filePathOrUrl);
+        if (url.protocol === 'file:') {
+            return pathToFileURL(await context.validatePath(fileURLToPath(url))).href;
+        }
+        else if (['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)) {
+            return filePathOrUrl;
+        }
+    }
+    catch {
+        // Suppress parsing errors for regular file paths.
+    }
+    return await context.validatePath(filePathOrUrl);
+}
+function isLocalBrowser(context) {
+    if (context.browser.process()) {
+        return true;
+    }
+    const wsEndpoint = context.browser.wsEndpoint();
+    if (wsEndpoint && isLocalhost(wsEndpoint)) {
+        return true;
+    }
+    return false;
+}
+function shouldValidateFile(option, isLocal) {
+    if (option === true) {
+        return true;
+    }
+    if (typeof option === 'object' && option !== null) {
+        if (isLocal) {
+            return Boolean(option.local);
+        }
+        return Boolean(option.remote);
+    }
+    return false;
+}
+async function validateToolFiles(tool, params, context) {
+    const isLocal = isLocalBrowser(context);
+    for (const [key, option] of Object.entries(tool.verifyFilesSchema)) {
+        if (shouldValidateFile(option, isLocal)) {
+            const val = params[key];
+            if (typeof val === 'string') {
+                params[key] = await validateAndResolvePathOrUrl(val, context);
+            }
+            else if (Array.isArray(val)) {
+                const updated = [];
+                for (const item of val) {
+                    if (typeof item === 'string') {
+                        updated.push(await validateAndResolvePathOrUrl(item, context));
+                    }
+                    else {
+                        throw new Error('Unexpected non-string value as a file path or URL');
+                    }
+                }
+                params[key] = updated;
+            }
+        }
+    }
+}
+export class ToolHandler {
+    tool;
+    serverArgs;
+    getContext;
+    toolMutex;
+    inputSchema;
+    registeredInputSchema;
+    disabled;
+    disabledReason;
+    constructor(tool, serverArgs, getContext, toolMutex) {
+        this.tool = tool;
+        this.serverArgs = serverArgs;
+        this.getContext = getContext;
+        this.toolMutex = toolMutex;
+        const { disabled, reason } = getToolStatusInfo(tool, serverArgs);
+        this.disabledReason = reason;
+        this.disabled = disabled && !serverArgs.viaCli;
+        this.inputSchema = tool.schema;
+        this.registeredInputSchema = zod.object(this.inputSchema).loose();
+    }
+    unknownArgumentNames(params) {
+        return Object.keys(params).filter(key => !Object.hasOwn(this.inputSchema, key));
+    }
+    handle = async (params) => {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const _guard = __addDisposableResource(env_1, await this.toolMutex.acquire(), false);
+            if (this.disabledReason) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: this.disabledReason,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const unknownArgumentNames = this.unknownArgumentNames(params);
+            if (unknownArgumentNames.length) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: buildUnknownArgumentsMessage(this.tool.name, unknownArgumentNames, Object.keys(this.inputSchema)),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const startTime = Date.now();
+            let success = false;
+            let devToolsData;
+            let pageUrl;
+            try {
+                logger?.(`${this.tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+                const context = await this.getContext();
+                logger?.(`${this.tool.name} context: resolved`);
+                const response = this.serverArgs.slim
+                    ? new SlimMcpResponse(this.serverArgs)
+                    : new McpResponse(this.serverArgs);
+                response.setRedactNetworkHeaders(this.serverArgs.redactNetworkHeaders);
+                if (context.consumeReconnectNotice()) {
+                    response.setReconnectNotice();
+                }
+                let page;
+                try {
+                    await validateToolFiles(this.tool, params, context);
+                    if (isPageScopedTool(this.tool)) {
+                        const pageId = typeof params.pageId === 'number' ? params.pageId : undefined;
+                        page =
+                            this.serverArgs.pageIdRouting &&
+                                pageId !== undefined &&
+                                !this.serverArgs.slim
+                                ? context.getPageById(pageId)
+                                : context.getSelectedMcpPage();
+                        response.setPage(page);
+                        if (this.tool.blockedByDialog) {
+                            page.throwIfDialogOpen();
+                        }
+                        await this.tool.handler({
+                            params,
+                            page,
+                        }, response, context);
+                    }
+                    else {
+                        await this.tool.handler({
+                            params,
+                        }, response, context);
+                    }
+                }
+                catch (err) {
+                    response.setError(err);
+                }
+                devToolsData = await context.getDevToolsData(page);
+                pageUrl = context.getSelectedMcpPageUrl(page);
+                // Resolve data format: --experimentalDataFormat takes precedence, fall back to legacy --experimentalToonFormat
+                let dataFormat = 'default';
+                if (this.serverArgs.experimentalDataFormat) {
+                    dataFormat = this.serverArgs.experimentalDataFormat;
+                }
+                else if (this.serverArgs.experimentalToonFormat) {
+                    dataFormat = 'toon';
+                }
+                const { content, structuredContent } = await response.handle(context, dataFormat);
+                const result = {
+                    content,
+                };
+                if (response.error) {
+                    result.isError = true;
+                }
+                success = true;
+                if (this.serverArgs.experimentalStructuredContent) {
+                    result.structuredContent = structuredContent;
+                }
+                return result;
+            }
+            catch (err) {
+                logger?.(`${this.tool.name} error:`, err, err?.stack);
+                let errorText = err && 'message' in err ? err.message : String(err);
+                if ('cause' in err && err.cause) {
+                    errorText += `\nCause: ${err.cause.message}`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: errorText,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            finally {
+                void ClearcutLogger.get()?.logToolInvocation({
+                    toolName: this.tool.name,
+                    params,
+                    schema: this.inputSchema,
+                    success,
+                    latencyMs: Date.now() - startTime,
+                    devToolsData,
+                    pageUrl,
+                });
+            }
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    };
+}
+//# sourceMappingURL=ToolHandler.js.map