@gabrielbryk/arc-devtools-mcp 1.3.0

package/build/src/formatters/NetworkFormatter.js

@@ -0,0 +1,238 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ * */
+import { isUtf8 } from 'node:buffer';
+import { DevTools, } from '../third_party/index.js';
+const BODY_CONTEXT_SIZE_LIMIT = 10000;
+export class NetworkFormatter {
+    #request;
+    #options;
+    #requestBody;
+    #responseBody;
+    #requestBodyFilePath;
+    #responseBodyFilePath;
+    constructor(request, options) {
+        this.#request = request;
+        this.#options = options;
+    }
+    static async from(request, options) {
+        const instance = new NetworkFormatter(request, options);
+        if (options.fetchData) {
+            await instance.#loadDetailedData();
+        }
+        return instance;
+    }
+    async #loadDetailedData() {
+        // Load Request Body
+        if (this.#request.hasPostData()) {
+            let data;
+            try {
+                data =
+                    this.#request.postData() ?? (await this.#request.fetchPostData());
+            }
+            catch {
+                // Ignore parsing errors
+            }
+            const requestBodyNotAvailableMessage = '<Request body not available anymore>';
+            if (this.#options.requestFilePath) {
+                if (!this.#options.saveFile) {
+                    throw new Error('saveFile is not provided');
+                }
+                if (data) {
+                    const result = await this.#options.saveFile(Buffer.from(data), this.#options.requestFilePath, '.network-request');
+                    this.#requestBodyFilePath = result.filename;
+                }
+                else {
+                    this.#requestBody = requestBodyNotAvailableMessage;
+                }
+            }
+            else {
+                if (data) {
+                    this.#requestBody = getSizeLimitedString(data, BODY_CONTEXT_SIZE_LIMIT);
+                }
+                else {
+                    this.#requestBody = requestBodyNotAvailableMessage;
+                }
+            }
+        }
+        // Load Response Body
+        const response = this.#request.response();
+        if (response) {
+            const responseBodyNotAvailableMessage = '<Response body not available anymore>';
+            if (this.#options.responseFilePath) {
+                try {
+                    const buffer = await response.buffer();
+                    if (!this.#options.saveFile) {
+                        throw new Error('saveFile is not provided');
+                    }
+                    const result = await this.#options.saveFile(buffer, this.#options.responseFilePath, '.network-response');
+                    this.#responseBodyFilePath = result.filename;
+                }
+                catch {
+                    // Flatten error handling for buffer() failure and save failure
+                }
+                if (!this.#responseBodyFilePath) {
+                    this.#responseBody = responseBodyNotAvailableMessage;
+                }
+            }
+            else {
+                this.#responseBody = await this.#getFormattedResponseBody(response, BODY_CONTEXT_SIZE_LIMIT);
+            }
+        }
+    }
+    toString() {
+        return convertNetworkRequestConciseToString(this.toJSON());
+    }
+    toStringDetailed() {
+        return converNetworkRequestDetailedToStringDetailed(this.toJSONDetailed());
+    }
+    toJSON() {
+        return {
+            requestId: this.#options.requestId,
+            method: this.#request.method(),
+            url: this.#request.url(),
+            status: this.#getStatusFromRequest(this.#request),
+            selectedInDevToolsUI: this.#options.selectedInDevToolsUI,
+        };
+    }
+    #redactNetworkHeaders(headers) {
+        const headersList = Object.entries(headers).map(item => {
+            return { name: item[0], value: item[1] };
+        });
+        const redacted = DevTools.NetworkRequestFormatter.sanitizeHeaders(headersList);
+        return redacted.reduce((acc, item) => {
+            acc[item.name] = item.value;
+            return acc;
+        }, {});
+    }
+    toJSONDetailed() {
+        const redirectChain = this.#request.redirectChain();
+        const formattedRedirectChain = redirectChain.reverse().map(request => {
+            const id = this.#options.requestIdResolver
+                ? this.#options.requestIdResolver(request)
+                : undefined;
+            const formatter = new NetworkFormatter(request, {
+                requestId: id,
+                saveFile: this.#options.saveFile,
+                redactNetworkHeaders: this.#options.redactNetworkHeaders,
+            });
+            return formatter.toJSON();
+        });
+        const responseHeaders = this.#request.response()?.headers();
+        return {
+            ...this.toJSON(),
+            requestHeaders: this.#options.redactNetworkHeaders
+                ? this.#redactNetworkHeaders(this.#request.headers())
+                : this.#request.headers(),
+            requestBody: this.#requestBody,
+            requestBodyFilePath: this.#requestBodyFilePath,
+            responseHeaders: this.#options.redactNetworkHeaders && responseHeaders
+                ? this.#redactNetworkHeaders(responseHeaders)
+                : this.#request.response()?.headers(),
+            responseBody: this.#responseBody,
+            responseBodyFilePath: this.#responseBodyFilePath,
+            failure: this.#request.failure()?.errorText,
+            redirectChain: formattedRedirectChain.length
+                ? formattedRedirectChain
+                : undefined,
+        };
+    }
+    #getStatusFromRequest(request) {
+        const httpResponse = request.response();
+        const failure = request.failure();
+        let status;
+        if (httpResponse) {
+            status = httpResponse.status().toString();
+        }
+        else if (failure) {
+            status = failure.errorText;
+        }
+        else {
+            status = 'pending';
+        }
+        return status;
+    }
+    async #getFormattedResponseBody(httpResponse, sizeLimit = BODY_CONTEXT_SIZE_LIMIT) {
+        try {
+            const responseBuffer = await httpResponse.buffer();
+            if (isUtf8(responseBuffer)) {
+                const responseAsTest = responseBuffer.toString('utf-8');
+                if (responseAsTest.length === 0) {
+                    return '<empty response>';
+                }
+                return getSizeLimitedString(responseAsTest, sizeLimit);
+            }
+            return '<binary data>';
+        }
+        catch {
+            return '<not available anymore>';
+        }
+    }
+}
+function getSizeLimitedString(text, sizeLimit) {
+    if (text.length > sizeLimit) {
+        return text.substring(0, sizeLimit) + '... <truncated>';
+    }
+    return text;
+}
+function convertNetworkRequestConciseToString(data) {
+    // TODO truncate the URL
+    return `reqid=${data.requestId} ${data.method} ${data.url} [${data.status}]${data.selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
+}
+function formatHeadlers(headers) {
+    const response = [];
+    for (const [name, value] of Object.entries(headers)) {
+        response.push(`- ${name}:${value}`);
+    }
+    return response;
+}
+function converNetworkRequestDetailedToStringDetailed(data) {
+    const response = [];
+    response.push(`## Request ${data.url}`);
+    response.push(`Status: ${data.status}`);
+    response.push(`### Request Headers`);
+    for (const line of formatHeadlers(data.requestHeaders)) {
+        response.push(line);
+    }
+    if (data.requestBody) {
+        response.push(`### Request Body`);
+        response.push(data.requestBody);
+    }
+    else if (data.requestBodyFilePath) {
+        response.push(`### Request Body`);
+        response.push(`Saved to ${data.requestBodyFilePath}.`);
+    }
+    if (data.responseHeaders) {
+        response.push(`### Response Headers`);
+        for (const line of formatHeadlers(data.responseHeaders)) {
+            response.push(line);
+        }
+    }
+    if (data.responseBody) {
+        response.push(`### Response Body`);
+        response.push(data.responseBody);
+    }
+    else if (data.responseBodyFilePath) {
+        response.push(`### Response Body`);
+        response.push(`Saved to ${data.responseBodyFilePath}.`);
+    }
+    if (data.failure) {
+        response.push(`### Request failed with`);
+        response.push(data.failure);
+    }
+    const redirectChain = data.redirectChain;
+    if (redirectChain?.length) {
+        response.push(`### Redirect chain`);
+        let indent = 0;
+        // `redirectChain` is already ordered by toJSONDetailed(); don't reverse it
+        // again here or the text output contradicts structuredContent (the JSON).
+        for (const request of redirectChain) {
+            response.push(`${'  '.repeat(indent)}${convertNetworkRequestConciseToString(request)}`);
+            indent++;
+        }
+    }
+    return response.join('\n');
+}
+//# sourceMappingURL=NetworkFormatter.js.map

package/build/src/formatters/SnapshotFormatter.js

@@ -0,0 +1,135 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class SnapshotFormatter {
+    #snapshot;
+    constructor(snapshot) {
+        this.#snapshot = snapshot;
+    }
+    toString() {
+        const chunks = [];
+        const root = this.#snapshot.root;
+        // Top-level content of the snapshot.
+        if (!this.#snapshot.verbose &&
+            this.#snapshot.hasSelectedElement &&
+            !this.#snapshot.selectedElementUid) {
+            chunks.push(`Note: there is a selected element in the DevTools Elements panel but it is not included into the current a11y tree snapshot.
+Get a verbose snapshot to include all elements if you are interested in the selected element.\n\n`);
+        }
+        chunks.push(this.#formatNode(root, 0));
+        return chunks.join('');
+    }
+    toJSON() {
+        return this.#nodeToJSON(this.#snapshot.root);
+    }
+    #formatNode(node, depth = 0) {
+        const chunks = [];
+        const attributes = this.#getAttributes(node);
+        const line = ' '.repeat(depth * 2) +
+            attributes.join(' ') +
+            (node.id === this.#snapshot.selectedElementUid
+                ? ' [selected in the DevTools Elements panel]'
+                : '') +
+            '\n';
+        chunks.push(line);
+        for (const child of node.children) {
+            chunks.push(this.#formatNode(child, depth + 1));
+        }
+        return chunks.join('');
+    }
+    #nodeToJSON(node) {
+        const rawAttrs = this.#getAttributesMap(node);
+        const children = node.children.map(child => this.#nodeToJSON(child));
+        const result = structuredClone(rawAttrs);
+        if (children.length > 0) {
+            result.children = children;
+        }
+        return result;
+    }
+    #getAttributes(serializedAXNodeRoot) {
+        const attributes = [`uid=${serializedAXNodeRoot.id}`];
+        if (serializedAXNodeRoot.role) {
+            attributes.push(serializedAXNodeRoot.role === 'none'
+                ? 'ignored'
+                : serializedAXNodeRoot.role);
+        }
+        if (serializedAXNodeRoot.name) {
+            attributes.push(`"${serializedAXNodeRoot.name}"`);
+        }
+        const simpleAttrs = this.#getAttributesMap(serializedAXNodeRoot, 
+        /* excludeSpecial */ true);
+        for (const attr of Object.keys(serializedAXNodeRoot).sort()) {
+            if (excludedAttributes.has(attr)) {
+                continue;
+            }
+            const mapped = booleanPropertyMap[attr];
+            if (mapped && simpleAttrs[mapped]) {
+                attributes.push(mapped);
+            }
+            const val = simpleAttrs[attr];
+            if (val === true) {
+                attributes.push(attr);
+            }
+            else if (typeof val === 'string' || typeof val === 'number') {
+                attributes.push(`${attr}="${val}"`);
+            }
+        }
+        return attributes;
+    }
+    #getAttributesMap(node, excludeSpecial = false) {
+        const result = {};
+        if (!excludeSpecial) {
+            result.id = node.id;
+            if (node.role) {
+                result.role = node.role;
+            }
+            if (node.name) {
+                result.name = node.name;
+            }
+        }
+        // Re-implementing the exact logic from original function for #getAttributes to be safe:
+        return {
+            ...result,
+            ...this.#extractedAttributes(node),
+        };
+    }
+    #extractedAttributes(node) {
+        const result = {};
+        for (const attr of Object.keys(node).sort()) {
+            if (excludedAttributes.has(attr)) {
+                continue;
+            }
+            const value = node[attr];
+            if (typeof value === 'boolean') {
+                if (booleanPropertyMap[attr]) {
+                    result[booleanPropertyMap[attr]] = true;
+                }
+                if (value) {
+                    result[attr] = true;
+                }
+            }
+            else if (typeof value === 'string' || typeof value === 'number') {
+                result[attr] = value;
+            }
+        }
+        return result;
+    }
+}
+const booleanPropertyMap = {
+    disabled: 'disableable',
+    expanded: 'expandable',
+    focused: 'focusable',
+    selected: 'selectable',
+};
+const excludedAttributes = new Set([
+    'id',
+    'role',
+    'name',
+    'elementHandle',
+    'children',
+    'backendNodeId',
+    'loaderId',
+]);
+//# sourceMappingURL=SnapshotFormatter.js.map

package/build/src/index.js

@@ -0,0 +1,153 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
+import { loadIssueDescriptions } from './issue-descriptions.js';
+import { logger } from './logger.js';
+import { McpContext } from './McpContext.js';
+import { Mutex } from './Mutex.js';
+import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
+import { FilePersistence } from './telemetry/persistence.js';
+import { McpServer, SetLevelRequestSchema, ListRootsResultSchema, RootsListChangedNotificationSchema, } from './third_party/index.js';
+import { ToolHandler } from './ToolHandler.js';
+import { createTools } from './tools/tools.js';
+import { VERSION } from './version.js';
+export { buildFlag } from './ToolHandler.js';
+export async function createMcpServer(serverArgs, options) {
+    if (serverArgs.usageStatistics) {
+        ClearcutLogger.initialize({
+            persistence: new FilePersistence(),
+            logFile: serverArgs.logFile,
+            appVersion: VERSION,
+            clearcutEndpoint: serverArgs.clearcutEndpoint,
+            clearcutForceFlushIntervalMs: serverArgs.clearcutForceFlushIntervalMs,
+            clearcutIncludePidHeader: serverArgs.clearcutIncludePidHeader,
+        });
+    }
+    const server = new McpServer({
+        name: 'chrome_devtools',
+        title: 'Chrome DevTools MCP server',
+        version: VERSION,
+    }, { capabilities: { logging: {} } });
+    server.server.setRequestHandler(SetLevelRequestSchema, () => {
+        return {};
+    });
+    const updateRoots = async () => {
+        if (!server.server.getClientCapabilities()?.roots) {
+            return;
+        }
+        try {
+            const roots = await server.server.request({ method: 'roots/list' }, ListRootsResultSchema);
+            context?.setRoots(roots.roots);
+        }
+        catch (e) {
+            logger?.('Failed to list roots', e);
+        }
+    };
+    server.server.oninitialized = () => {
+        const clientName = server.server.getClientVersion()?.name;
+        if (clientName) {
+            ClearcutLogger.get()?.setClientName(clientName);
+        }
+        if (server.server.getClientCapabilities()?.roots) {
+            void updateRoots();
+            server.server.setNotificationHandler(RootsListChangedNotificationSchema, () => {
+                void updateRoots();
+            });
+        }
+    };
+    let context;
+    async function getContext() {
+        const chromeArgs = (serverArgs.chromeArg ?? []).map(String);
+        const ignoreDefaultChromeArgs = (serverArgs.ignoreDefaultChromeArg ?? []).map(String);
+        if (serverArgs.proxyServer) {
+            chromeArgs.push(`--proxy-server=${serverArgs.proxyServer}`);
+        }
+        const devtools = serverArgs.experimentalDevtools ?? false;
+        const blocklist = serverArgs.blockedUrlPattern
+            ? serverArgs.blockedUrlPattern.map(String)
+            : undefined;
+        const allowlist = serverArgs.allowedUrlPattern
+            ? serverArgs.allowedUrlPattern.map(String)
+            : undefined;
+        const browser = serverArgs.browserUrl || serverArgs.wsEndpoint || serverArgs.autoConnect
+            ? await ensureBrowserConnected({
+                browserURL: serverArgs.browserUrl,
+                wsEndpoint: serverArgs.wsEndpoint,
+                wsHeaders: serverArgs.wsHeaders,
+                // Important: only pass channel, if autoConnect is true.
+                channel: serverArgs.autoConnect
+                    ? serverArgs.channel
+                    : undefined,
+                userDataDir: serverArgs.userDataDir,
+                devtools,
+                blocklist,
+                allowlist,
+            })
+            : await ensureBrowserLaunched({
+                headless: serverArgs.headless,
+                executablePath: serverArgs.executablePath,
+                channel: serverArgs.channel,
+                isolated: serverArgs.isolated ?? false,
+                userDataDir: serverArgs.userDataDir,
+                logFile: options.logFile,
+                viewport: serverArgs.viewport,
+                chromeArgs,
+                ignoreDefaultChromeArgs,
+                acceptInsecureCerts: serverArgs.acceptInsecureCerts,
+                devtools,
+                enableExtensions: serverArgs.categoryExtensions,
+                viaCli: serverArgs.viaCli,
+                blocklist,
+                allowlist,
+            });
+        if (context?.browser !== browser) {
+            context = await McpContext.from(browser, logger, {
+                experimentalDevToolsDebugging: devtools,
+                experimentalIncludeAllPages: serverArgs.experimentalIncludeAllPages,
+                performanceCrux: serverArgs.performanceCrux,
+                arc: serverArgs.arc,
+                hasNetworkBlockOrAllowlist: Boolean((blocklist && blocklist.length > 0) ||
+                    (allowlist && allowlist.length > 0)),
+            });
+            await updateRoots();
+        }
+        return context;
+    }
+    const toolMutex = new Mutex();
+    function registerTool(tool) {
+        const toolHandler = new ToolHandler(tool, serverArgs, getContext, toolMutex);
+        if (!toolHandler.shouldRegister) {
+            return;
+        }
+        server.registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: toolHandler.registeredInputSchema,
+            annotations: tool.annotations,
+        }, async (params) => {
+            return await toolHandler.handle(params);
+        });
+    }
+    const tools = createTools(serverArgs);
+    for (const tool of tools) {
+        registerTool(tool);
+    }
+    await loadIssueDescriptions();
+    return { server };
+}
+export const logDisclaimers = (args) => {
+    console.error(`chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
+debug, and modify any data in the browser or DevTools.
+Avoid sharing sensitive or personal information that you do not want to share with MCP clients.`);
+    if (!args.slim && args.performanceCrux) {
+        console.error(`Performance tools may send trace URLs to the Google CrUX API to fetch real-user experience data. To disable, run with --no-performance-crux.`);
+    }
+    if (!args.slim && args.usageStatistics) {
+        console.error(`
+Google collects usage statistics to improve Chrome DevTools MCP. To opt-out, run with --no-usage-statistics.
+For more details, visit: https://github.com/ChromeDevTools/chrome-devtools-mcp#usage-statistics`);
+    }
+};
+//# sourceMappingURL=index.js.map

package/build/src/issue-descriptions.js

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const DESCRIPTIONS_PATH = path.join(import.meta.dirname, 'third_party/issue-descriptions');
+let issueDescriptions = {};
+/**
+ * Reads all issue descriptions from the filesystem into memory.
+ */
+export async function loadIssueDescriptions() {
+    if (Object.keys(issueDescriptions).length > 0) {
+        return;
+    }
+    const files = await fs.promises.readdir(DESCRIPTIONS_PATH);
+    const descriptions = {};
+    for (const file of files) {
+        if (!file.endsWith('.md')) {
+            continue;
+        }
+        const content = await fs.promises.readFile(path.join(DESCRIPTIONS_PATH, file), 'utf-8');
+        descriptions[file] = content;
+    }
+    issueDescriptions = descriptions;
+}
+/**
+ * Gets an issue description from the in-memory cache.
+ * @param fileName The file name of the issue description.
+ * @returns The description of the issue, or null if it doesn't exist.
+ */
+export function getIssueDescription(fileName) {
+    return issueDescriptions[fileName] ?? null;
+}
+export const ISSUE_UTILS = {
+    loadIssueDescriptions,
+    getIssueDescription,
+};
+//# sourceMappingURL=issue-descriptions.js.map

package/build/src/logger.js

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import { debug } from './third_party/index.js';
+const mcpDebugNamespace = 'mcp:log';
+const namespacesToEnable = [
+    mcpDebugNamespace,
+    ...(process.env['DEBUG'] ? [process.env['DEBUG']] : []),
+];
+export function saveLogsToFile(fileName) {
+    // Enable overrides everything so we need to add them
+    debug.enable(namespacesToEnable.join(','));
+    const logFile = fs.createWriteStream(fileName, { flags: 'a+' });
+    debug.log = function (...chunks) {
+        logFile.write(`${chunks.join(' ')}\n`);
+    };
+    logFile.on('error', function (error) {
+        console.error(`Error when opening/writing to log file: ${error.message}`);
+        logFile.end();
+        process.exit(1);
+    });
+    return logFile;
+}
+export function flushLogs(logFile, timeoutMs = 2000) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(reject, timeoutMs);
+        logFile.end(() => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+}
+export const logger = debug(mcpDebugNamespace);
+//# sourceMappingURL=logger.js.map

package/build/src/polyfill.js

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// polyfills are now bundled with all other dependencies
+import './third_party/index.js';
+//# sourceMappingURL=polyfill.js.map