@vibebrowser/chrome-devtools-mcp 0.26.0

package/build/src/formatters/IssueFormatter.js

@@ -0,0 +1,193 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ISSUE_UTILS } from '../issue-descriptions.js';
+import { logger } from '../logger.js';
+import { DevTools } from '../third_party/index.js';
+export class IssueFormatter {
+    #issue;
+    #options;
+    constructor(issue, options) {
+        this.#issue = issue;
+        this.#options = options;
+    }
+    toString() {
+        return convertIssueConciseToString(this.toJSON());
+    }
+    toStringDetailed() {
+        return convertIssueDetailedToString(this.toJSONDetailed());
+    }
+    toJSON() {
+        return {
+            type: 'issue',
+            title: this.#getTitle(),
+            count: this.#issue.getAggregatedIssuesCount(),
+            id: this.#options.id,
+        };
+    }
+    toJSONDetailed() {
+        return {
+            id: this.#options.id,
+            type: 'issue',
+            count: this.#issue.getAggregatedIssuesCount(),
+            title: this.#getTitle(),
+            description: this.#getDescription(),
+            links: this.#issue.getDescription()?.links,
+            affectedResources: this.#getAffectedResources(),
+        };
+    }
+    #getAffectedResources() {
+        const issues = this.#issue.getAllIssues();
+        const affectedResources = [];
+        for (const singleIssue of issues) {
+            const details = singleIssue.details();
+            if (!details) {
+                continue;
+            }
+            // We send the remaining details as untyped JSON because the DevTools
+            // frontend code is currently not re-usable.
+            const data = structuredClone(details);
+            let uid;
+            let request;
+            if ('violatingNodeId' in details &&
+                details.violatingNodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.violatingNodeId);
+                delete data.violatingNodeId;
+            }
+            if ('nodeId' in details &&
+                details.nodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.nodeId);
+                delete data.nodeId;
+            }
+            if ('documentNodeId' in details &&
+                details.documentNodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.documentNodeId);
+                delete data.documentNodeId;
+            }
+            if ('request' in details && details.request) {
+                request = details.request.url;
+                if (details.request.requestId && this.#options.requestIdResolver) {
+                    const resolvedId = this.#options.requestIdResolver(details.request.requestId);
+                    if (resolvedId) {
+                        request = resolvedId;
+                        const requestData = data.request;
+                        delete requestData.requestId;
+                    }
+                }
+            }
+            // These fields has no use for the MCP client (redundant or irrelevant).
+            delete data.errorType;
+            delete data.frameId;
+            affectedResources.push({
+                uid,
+                data: data,
+                request,
+            });
+        }
+        return affectedResources;
+    }
+    isValid() {
+        return this.#getTitle() !== undefined;
+    }
+    // Helper to extract title
+    #getTitle() {
+        const markdownDescription = this.#issue.getDescription();
+        const filename = markdownDescription?.file;
+        if (!filename) {
+            logger(`no description found for issue:` + this.#issue.code());
+            return undefined;
+        }
+        // We already have the description logic in #getDescription, but title extraction is separate
+        // We can reuse the logic or cache it.
+        // Ideally we should process markdown once.
+        const rawMarkdown = ISSUE_UTILS.getIssueDescription(filename);
+        if (!rawMarkdown) {
+            logger(`no markdown ${filename} found for issue:` + this.#issue.code());
+            return undefined;
+        }
+        try {
+            const processedMarkdown = DevTools.MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription?.substitutions);
+            const markdownAst = DevTools.Marked.Marked.lexer(processedMarkdown);
+            const title = DevTools.MarkdownIssueDescription.findTitleFromMarkdownAst(markdownAst);
+            if (!title) {
+                logger('cannot read issue title from ' + filename);
+                return undefined;
+            }
+            return title;
+        }
+        catch {
+            logger('error parsing markdown for issue ' + this.#issue.code());
+            return undefined;
+        }
+    }
+    #getDescription() {
+        const markdownDescription = this.#issue.getDescription();
+        const filename = markdownDescription?.file;
+        if (!filename) {
+            return undefined;
+        }
+        const rawMarkdown = ISSUE_UTILS.getIssueDescription(filename);
+        if (!rawMarkdown) {
+            return undefined;
+        }
+        try {
+            return DevTools.MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription?.substitutions);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function convertIssueConciseToString(issue) {
+    return `msgid=${issue.id} [issue] ${issue.title} (count: ${issue.count})`;
+}
+function convertIssueDetailedToString(issue) {
+    const result = [];
+    result.push(`ID: ${issue.id}`);
+    const bodyParts = [];
+    const description = issue.description;
+    let processedMarkdown = description?.trim();
+    // Remove heading in order not to conflict with the whole console message response markdown
+    if (processedMarkdown?.startsWith('# ')) {
+        processedMarkdown = processedMarkdown.substring(2).trimStart();
+    }
+    if (processedMarkdown) {
+        bodyParts.push(processedMarkdown);
+    }
+    else {
+        bodyParts.push(issue.title ?? 'Unknown Issue');
+    }
+    const links = issue.links;
+    if (links && links.length > 0) {
+        bodyParts.push('Learn more:');
+        for (const link of links) {
+            bodyParts.push(`[${link.linkTitle}](${link.link})`);
+        }
+    }
+    const affectedResources = issue.affectedResources;
+    if (affectedResources.length) {
+        bodyParts.push('### Affected resources');
+        bodyParts.push(...affectedResources.map(item => {
+            const details = [];
+            if (item.uid) {
+                details.push(`uid=${item.uid}`);
+            }
+            if (item.request) {
+                details.push((typeof item.request === 'number' ? `reqid=` : 'url=') +
+                    item.request);
+            }
+            if (item.data) {
+                details.push(`data=${JSON.stringify(item.data)}`);
+            }
+            return details.join(' ');
+        }));
+    }
+    result.push(`Message: issue> ${bodyParts.join('\n')}`);
+    return result.join('\n');
+}
+//# sourceMappingURL=IssueFormatter.js.map

package/build/src/formatters/NetworkFormatter.js

@@ -0,0 +1,236 @@
+/**
+ * @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;
+        for (const request of redirectChain.reverse()) {
+            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,140 @@
+/**
+ * @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 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,
+            })
+            : 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,
+            });
+        if (context?.browser !== browser) {
+            context = await McpContext.from(browser, logger, {
+                experimentalDevToolsDebugging: devtools,
+                experimentalIncludeAllPages: serverArgs.experimentalIncludeAllPages,
+                performanceCrux: serverArgs.performanceCrux,
+            });
+            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