@gabrielbryk/arc-devtools-mcp 1.3.0

package/build/src/TextSnapshot.js

@@ -0,0 +1,236 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from './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 = page.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;
+    }
+    // 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) => {
+            let ancestorHandle = await handle.evaluateHandle(el => el.parentElement);
+            while (ancestorHandle) {
+                const ancestorElement = ancestorHandle.asElement();
+                if (!ancestorElement) {
+                    await ancestorHandle.dispose();
+                    return null;
+                }
+                const ancestorBackendId = await ancestorElement.backendNodeId();
+                if (ancestorBackendId) {
+                    const ancestorNode = idToNode
+                        .values()
+                        .find(node => node.backendNodeId === ancestorBackendId);
+                    if (ancestorNode) {
+                        await ancestorHandle.dispose();
+                        return ancestorNode;
+                    }
+                }
+                const nextHandle = await ancestorElement.evaluateHandle(el => el.parentElement);
+                await ancestorHandle.dispose();
+                ancestorHandle = nextHandle;
+            }
+            return null;
+        };
+        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,223 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from './logger.js';
+import { McpResponse } from './McpResponse.js';
+import { SlimMcpResponse } from './SlimMcpResponse.js';
+import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
+import { bucketizeLatency } from './telemetry/transformation.js';
+import { zod } from './third_party/index.js';
+import { labels, OFF_BY_DEFAULT_CATEGORIES } from './tools/categories.js';
+import { pageIdSchema } from './tools/ToolDefinition.js';
+export function buildFlag(category) {
+    return `category${category.charAt(0).toUpperCase() + category.slice(1)}`;
+}
+function buildDisabledMessage(toolName, flag, categoryLabel) {
+    const reason = categoryLabel
+        ? `is in category ${categoryLabel} which`
+        : `requires experimental feature ${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 getCategoryStatus(category, serverArgs) {
+    const categoryFlag = buildFlag(category);
+    const flagValue = serverArgs[categoryFlag];
+    const isDisabled = OFF_BY_DEFAULT_CATEGORIES.includes(category)
+        ? !flagValue
+        : flagValue === false;
+    if (isDisabled) {
+        return {
+            categoryFlag,
+            disabled: true,
+        };
+    }
+    return {
+        disabled: false,
+    };
+}
+function getConditionStatus(condition, serverArgs) {
+    if (condition && !serverArgs[condition]) {
+        return { conditionFlag: condition, disabled: true };
+    }
+    return { disabled: false };
+}
+function getToolStatusInfo(tool, serverArgs) {
+    const category = tool.annotations.category;
+    const categoryCheck = getCategoryStatus(category, serverArgs);
+    if (category && categoryCheck.disabled) {
+        if (!categoryCheck.categoryFlag) {
+            throw new Error('when the category is disabled there should always be a flag set');
+        }
+        return {
+            disabled: true,
+            reason: buildDisabledMessage(tool.name, `--${categoryCheck.categoryFlag}`, labels[category]),
+        };
+    }
+    for (const condition of tool.annotations.conditions || []) {
+        const conditionCheck = getConditionStatus(condition, serverArgs);
+        if (conditionCheck.disabled) {
+            if (!conditionCheck.conditionFlag) {
+                throw new Error('when the condition is disabled there should always be a flag set');
+            }
+            return {
+                disabled: true,
+                reason: buildDisabledMessage(tool.name, `--${conditionCheck.conditionFlag}`),
+            };
+        }
+    }
+    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.`;
+}
+export class ToolHandler {
+    tool;
+    serverArgs;
+    getContext;
+    toolMutex;
+    inputSchema;
+    registeredInputSchema;
+    shouldRegister;
+    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.shouldRegister = !(disabled && !serverArgs.viaCli);
+        this.inputSchema =
+            'pageScoped' in tool &&
+                tool.pageScoped &&
+                serverArgs.experimentalPageIdRouting &&
+                !serverArgs.slim
+                ? { ...pageIdSchema, ...tool.schema }
+                : tool.schema;
+        this.registeredInputSchema = zod.object(this.inputSchema).passthrough();
+    }
+    unknownArgumentNames(params) {
+        return Object.keys(params).filter(key => !Object.hasOwn(this.inputSchema, key));
+    }
+    async handle(params) {
+        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 guard = await this.toolMutex.acquire();
+        const startTime = Date.now();
+        let success = false;
+        try {
+            logger?.(`${this.tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+            const context = await this.getContext();
+            logger?.(`${this.tool.name} context: resolved`);
+            await context.detectOpenDevToolsWindows();
+            const response = this.serverArgs.slim
+                ? new SlimMcpResponse(this.serverArgs)
+                : new McpResponse(this.serverArgs);
+            response.setRedactNetworkHeaders(this.serverArgs.redactNetworkHeaders);
+            try {
+                if (this.tool.verifyFilesSchema) {
+                    for (const key of this.tool.verifyFilesSchema) {
+                        const filePath = params[key];
+                        await context.validatePath(filePath);
+                    }
+                }
+                if (isPageScopedTool(this.tool)) {
+                    const pageId = typeof params.pageId === 'number' ? params.pageId : undefined;
+                    const page = this.serverArgs.experimentalPageIdRouting &&
+                        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);
+            }
+            const { content, structuredContent } = await response.handle(this.tool.name, context, this.serverArgs.experimentalToonFormat ?? false);
+            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: bucketizeLatency(Date.now() - startTime),
+            });
+            guard.dispose();
+        }
+    }
+}
+//# sourceMappingURL=ToolHandler.js.map

package/build/src/WaitForHelper.js

@@ -0,0 +1,190 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from './logger.js';
+export class WaitForHelper {
+    #abortController = new AbortController();
+    #page;
+    #stableDomTimeout;
+    #stableDomFor;
+    #expectNavigationIn;
+    #navigationTimeout;
+    #dialogOpened = false;
+    #initialUrl;
+    constructor(page, cpuTimeoutMultiplier, networkTimeoutMultiplier) {
+        this.#stableDomTimeout = 3000 * cpuTimeoutMultiplier;
+        this.#stableDomFor = 100 * cpuTimeoutMultiplier;
+        this.#expectNavigationIn = 100 * cpuTimeoutMultiplier;
+        this.#navigationTimeout = 3000 * networkTimeoutMultiplier;
+        this.#page = page;
+        this.#initialUrl = page.url();
+    }
+    /**
+     * A wrapper that executes a action and waits for
+     * a potential navigation, after which it waits
+     * for the DOM to be stable before returning.
+     */
+    async waitForStableDom() {
+        const stableDomObserver = await this.#page.evaluateHandle(timeout => {
+            let timeoutId;
+            function callback() {
+                clearTimeout(timeoutId);
+                timeoutId = setTimeout(() => {
+                    domObserver.resolver.resolve();
+                    domObserver.observer.disconnect();
+                }, timeout);
+            }
+            const domObserver = {
+                resolver: Promise.withResolvers(),
+                observer: new MutationObserver(callback),
+            };
+            // It's possible that the DOM is not gonna change so we
+            // need to start the timeout initially.
+            callback();
+            domObserver.observer.observe(document.body, {
+                childList: true,
+                subtree: true,
+                attributes: true,
+            });
+            return domObserver;
+        }, this.#stableDomFor);
+        this.#abortController.signal.addEventListener('abort', async () => {
+            try {
+                await stableDomObserver.evaluate(observer => {
+                    observer.observer.disconnect();
+                    observer.resolver.resolve();
+                });
+                await stableDomObserver.dispose();
+            }
+            catch {
+                // Ignored cleanup errors
+            }
+        });
+        return Promise.race([
+            stableDomObserver.evaluate(async (observer) => {
+                return await observer.resolver.promise;
+            }),
+            this.timeout(this.#stableDomTimeout).then(() => {
+                throw new Error('Timeout');
+            }),
+        ]);
+    }
+    async waitForNavigationStarted() {
+        // Currently Puppeteer does not have API
+        // For when a navigation is about to start
+        const navigationStartedPromise = new Promise(resolve => {
+            const listener = (event) => {
+                if ([
+                    'historySameDocument',
+                    'historyDifferentDocument',
+                    'sameDocument',
+                ].includes(event.navigationType)) {
+                    resolve(false);
+                    return;
+                }
+                resolve(true);
+            };
+            this.#page._client().on('Page.frameStartedNavigating', listener);
+            this.#abortController.signal.addEventListener('abort', () => {
+                resolve(false);
+                this.#page._client().off('Page.frameStartedNavigating', listener);
+            });
+        });
+        return await Promise.race([
+            navigationStartedPromise,
+            this.timeout(this.#expectNavigationIn).then(() => false),
+        ]);
+    }
+    timeout(time) {
+        return new Promise(res => {
+            const id = setTimeout(res, time);
+            this.#abortController.signal.addEventListener('abort', () => {
+                res();
+                clearTimeout(id);
+            });
+        });
+    }
+    async waitForEventsAfterAction(action, options) {
+        if (this.#abortController.signal.aborted) {
+            throw new Error("Can't re-use a WaitForHelper");
+        }
+        if (options?.handleDialog) {
+            const dialogHandler = (dialog) => {
+                this.#dialogOpened = true;
+                if (options.handleDialog === 'dismiss') {
+                    void dialog.dismiss();
+                }
+                else if (options.handleDialog === 'accept') {
+                    void dialog.accept();
+                }
+                else {
+                    void dialog.accept(options.handleDialog);
+                }
+            };
+            this.#page.on('dialog', dialogHandler);
+            this.#abortController.signal.addEventListener('abort', () => {
+                this.#page.off('dialog', dialogHandler);
+            });
+        }
+        const navigationFinished = this.waitForNavigationStarted()
+            .then(navigationStated => {
+            if (navigationStated) {
+                return this.#page.waitForNavigation({
+                    timeout: options?.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;
+            if (this.#dialogOpened) {
+                return this.#getResult();
+            }
+            // Wait for stable dom after navigation so we execute in
+            // the correct context
+            await this.waitForStableDom();
+        }
+        catch (error) {
+            logger?.(error);
+        }
+        finally {
+            this.#abortController.abort();
+        }
+        return this.#getResult();
+    }
+    #getResult() {
+        const urlAfterAction = this.#page.url();
+        return {
+            ...(urlAfterAction !== this.#initialUrl
+                ? { navigatedToUrl: urlAfterAction }
+                : {}),
+        };
+    }
+}
+export function getNetworkMultiplierFromString(condition) {
+    const puppeteerCondition = condition;
+    switch (puppeteerCondition) {
+        case 'Fast 4G':
+            return 1;
+        case 'Slow 4G':
+            return 2.5;
+        case 'Fast 3G':
+            return 5;
+        case 'Slow 3G':
+            return 10;
+    }
+    return 1;
+}
+//# sourceMappingURL=WaitForHelper.js.map

package/build/src/bin/check-latest-version.js

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+function getRegistry() {
+    // Use the user's configured npm registry so update checks work behind
+    // corporate proxies and private registries. `npm config get registry`
+    // honors .npmrc files at every scope and respects npm_config_registry,
+    // so it covers direct CLI invocations as well as `npx` / `npm run`.
+    try {
+        const registry = execSync('npm config get registry', {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        })
+            .trim()
+            .replace(/\/$/, '');
+        if (registry && registry !== 'undefined' && /^https?:\/\//.test(registry)) {
+            return registry;
+        }
+    }
+    catch {
+        // npm not on PATH or other errors, fall back to default.
+    }
+    return DEFAULT_REGISTRY;
+}
+const cachePath = process.argv[2];
+if (cachePath) {
+    try {
+        const response = await fetch(`${getRegistry()}/chrome-devtools-mcp/latest`);
+        const data = response.ok ? await response.json() : null;
+        if (data &&
+            typeof data === 'object' &&
+            'version' in data &&
+            typeof data.version === 'string') {
+            await fs.mkdir(path.dirname(cachePath), { recursive: true });
+            await fs.writeFile(cachePath, JSON.stringify({ version: data.version }));
+        }
+    }
+    catch {
+        // Ignore errors.
+    }
+}
+//# sourceMappingURL=check-latest-version.js.map