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

package/build/src/devtools/DevtoolsUtils.js

@@ -0,0 +1,307 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DevTools } from '../third_party/index.js';
+import { McpHostBindingAdapter } from './McpHostBindingAdapter.js';
+/**
+ * A mock implementation of an issues manager that only implements the methods
+ * that are actually used by the IssuesAggregator
+ */
+export class FakeIssuesManager extends DevTools.Common.ObjectWrapper
+    .ObjectWrapper {
+    issues() {
+        return [];
+    }
+}
+export function overrideDevToolsGlobals({ loadResource, }) {
+    DevTools.Host.InspectorFrontendHost.installInspectorFrontendHost(new McpHostBindingAdapter(loadResource));
+    // DevTools CDP errors can get noisy.
+    DevTools.ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
+    const noopAgentCommand = () => {
+        return Promise.resolve({
+            getError: () => undefined,
+        });
+    };
+    // Stub out Network emulation commands on the DevTools Agent prototype globally.
+    // This prevents the DevTools Frontend from ever resetting/clearing Puppeteer's
+    // active network blocking/throttling rules during target setup or session lifetime.
+    const networkAgentPrototype = DevTools.ProtocolClient.InspectorBackend.inspectorBackend.agentPrototypes.get('Network');
+    if (networkAgentPrototype) {
+        Object.defineProperty(networkAgentPrototype, 'invoke_emulateNetworkConditionsByRule', {
+            value: () => {
+                return Promise.resolve({
+                    ruleIds: [],
+                    getError: () => undefined,
+                });
+            },
+            writable: true,
+            configurable: true,
+            enumerable: true,
+        });
+        Object.defineProperty(networkAgentPrototype, 'invoke_overrideNetworkState', {
+            value: noopAgentCommand,
+            writable: true,
+            configurable: true,
+            enumerable: true,
+        });
+        Object.defineProperty(networkAgentPrototype, 'invoke_enable', {
+            value: noopAgentCommand,
+            writable: true,
+            configurable: true,
+            enumerable: true,
+        });
+        Object.defineProperty(networkAgentPrototype, 'invoke_disable', {
+            value: noopAgentCommand,
+            writable: true,
+            configurable: true,
+            enumerable: true,
+        });
+        Object.defineProperty(networkAgentPrototype, 'invoke_setBlockedURLs', {
+            value: noopAgentCommand,
+            writable: true,
+            configurable: true,
+            enumerable: true,
+        });
+    }
+    // Puppeteer already collects issues from its own Audits subscription. Avoid
+    // enabling the DevTools Frontend's redundant subscription, which can replay
+    // a large retained issue backlog and delay unrelated page work.
+    const auditsAgentPrototype = DevTools.ProtocolClient.InspectorBackend.inspectorBackend.agentPrototypes.get('Audits');
+    if (auditsAgentPrototype) {
+        Object.defineProperty(auditsAgentPrototype, 'invoke_enable', {
+            value: noopAgentCommand,
+            writable: true,
+            configurable: true,
+            enumerable: true,
+        });
+    }
+    DevTools.I18n.DevToolsLocale.DevToolsLocale.instance({
+        create: true,
+        data: {
+            navigatorLanguage: 'en-US',
+            settingLanguage: 'en-US',
+            lookupClosestDevToolsLocale: l => l,
+        },
+    });
+    DevTools.I18n.i18n.registerLocaleDataForTest('en-US', {});
+    DevTools.Formatter.FormatterWorkerPool.FormatterWorkerPool.instance({
+        forceNew: true,
+        entrypointURL: import.meta
+            .resolve('../third_party/devtools-formatter-worker.js'),
+    });
+}
+export async function createTargetUniverse(session, options) {
+    const settingStorage = new DevTools.Common.Settings.SettingsStorage({});
+    const universe = new DevTools.Foundation.Universe.Universe({
+        settingsCreationOptions: {
+            syncedStorage: settingStorage,
+            globalStorage: settingStorage,
+            localStorage: settingStorage,
+            settingRegistrations: DevTools.Common.SettingRegistration.getRegisteredSettings(),
+        },
+        overrideAutoStartModels: new Set([DevTools.DebuggerModel]),
+        hostConfig: {},
+        inspectorFrontendHost: DevTools.Host.InspectorFrontendHost.InspectorFrontendHostInstance,
+        supportsEmulation: false,
+    });
+    const sourceMaps = options?.sourceMaps ?? true;
+    const jsSourceMapsSetting = universe.settings.resolve(DevTools.SDKSettings.jsSourceMapsEnabledSettingDescriptor);
+    jsSourceMapsSetting.set(sourceMaps);
+    const cssSourceMapsSetting = universe.settings.resolve(DevTools.SDKSettings.cssSourceMapsEnabledSettingDescriptor);
+    cssSourceMapsSetting.set(sourceMaps);
+    const setting = universe.settings.resolve(DevTools.SourceMapManager.lazyLoadingSettingDescriptor);
+    setting.set(true);
+    const skipAllPausesSetting = universe.settings.resolve(DevTools.skipAllPausesSettingDescriptor);
+    skipAllPausesSetting.set(true);
+    // @ts-expect-error devtools-frontend has diffrent types.
+    const connection = new DevTools.PuppeteerDevToolsConnection(session);
+    const targetManager = universe.context.get(DevTools.TargetManager);
+    targetManager.observeModels(DevTools.NetworkManager.NetworkManager, DISABLE_NETWORK);
+    const target = targetManager.createTarget('main', '', 'frame', // eslint-disable-line @typescript-eslint/no-explicit-any
+    /* parentTarget */ null, session.id(), undefined, connection);
+    return { target, universe, session };
+}
+// Not recording network requests in the DevTools universe.
+//
+// The network requests are collected through pptr and there isn't a use case for
+// enabling devtools SDK's network domain.
+const DISABLE_NETWORK = {
+    modelAdded(model) {
+        void model.target().networkAgent().invoke_disable();
+    },
+    modelRemoved() {
+        // Do nothing.
+    },
+};
+/**
+ * Constructed from Runtime.ExceptionDetails of an uncaught error.
+ *
+ * TODO: Also construct from a RemoteObject of subtype 'error'.
+ *
+ * Consists of the message, a fully resolved stack trace and a fully resolved 'cause' chain.
+ */
+export class SymbolizedError {
+    message;
+    stackTrace;
+    cause;
+    constructor(message, stackTrace, cause) {
+        this.message = message;
+        this.stackTrace = stackTrace;
+        this.cause = cause;
+    }
+    static async fromDetails(opts) {
+        const message = SymbolizedError.#getMessage(opts.details);
+        if (!opts.includeStackAndCause || !opts.devTools) {
+            return new SymbolizedError(message, opts.resolvedStackTraceForTesting, opts.resolvedCauseForTesting);
+        }
+        let stackTrace;
+        if (opts.resolvedStackTraceForTesting) {
+            stackTrace = opts.resolvedStackTraceForTesting;
+        }
+        else if (opts.details.stackTrace) {
+            try {
+                stackTrace = await createStackTrace(opts.devTools, opts.details.stackTrace, opts.targetId);
+            }
+            catch {
+                // ignore
+            }
+        }
+        // TODO: Turn opts.details.exception into a JSHandle and retrieve the 'cause' property.
+        //       If its an Error, recursively create a SymbolizedError.
+        let cause;
+        if (opts.resolvedCauseForTesting) {
+            cause = opts.resolvedCauseForTesting;
+        }
+        else if (opts.details.exception) {
+            try {
+                const causeRemoteObj = await SymbolizedError.#lookupCause(opts.devTools, opts.details.exception, opts.targetId);
+                if (causeRemoteObj) {
+                    cause = await SymbolizedError.fromError({
+                        devTools: opts.devTools,
+                        error: causeRemoteObj,
+                        targetId: opts.targetId,
+                    });
+                }
+            }
+            catch {
+                // Ignore
+            }
+        }
+        return new SymbolizedError(message, stackTrace, cause);
+    }
+    static async fromError(opts) {
+        const details = await SymbolizedError.#getExceptionDetails(opts.devTools, opts.error, opts.targetId);
+        if (details) {
+            return SymbolizedError.fromDetails({
+                details,
+                devTools: opts.devTools,
+                targetId: opts.targetId,
+                includeStackAndCause: true,
+            });
+        }
+        return new SymbolizedError(SymbolizedError.#getMessageFromException(opts.error));
+    }
+    static #getMessage(details) {
+        // For Runtime.exceptionThrown with a present exception object, `details.text` will be "Uncaught" and
+        // we have to manually parse out the error text from the exception description.
+        // In the case of Runtime.getExceptionDetails, `details.text` has the Error.message.
+        if (details.text === 'Uncaught' && details.exception) {
+            return ('Uncaught ' +
+                SymbolizedError.#getMessageFromException(details.exception));
+        }
+        return details.text;
+    }
+    static #getMessageFromException(error) {
+        const messageWithRest = error.description?.split('\n    at ', 2) ?? [];
+        return messageWithRest[0] ?? '';
+    }
+    static async #getExceptionDetails(devTools, error, targetId) {
+        if (!devTools || (error.type !== 'object' && error.subtype !== 'error')) {
+            return null;
+        }
+        const targetManager = devTools.universe.context.get(DevTools.TargetManager);
+        const target = targetId
+            ? targetManager.targetById(targetId) || devTools.target
+            : devTools.target;
+        const model = target.model(DevTools.RuntimeModel);
+        return ((await model.getExceptionDetails(error.objectId)) ?? null);
+    }
+    static async #lookupCause(devTools, error, targetId) {
+        if (!devTools || (error.type !== 'object' && error.subtype !== 'error')) {
+            return null;
+        }
+        const targetManager = devTools.universe.context.get(DevTools.TargetManager);
+        const target = targetId
+            ? targetManager.targetById(targetId) || devTools.target
+            : devTools.target;
+        const properties = await target.runtimeAgent().invoke_getProperties({
+            objectId: error.objectId,
+        });
+        if (properties.getError()) {
+            return null;
+        }
+        return properties.result.find(prop => prop.name === 'cause')?.value ?? null;
+    }
+    static createForTesting(message, stackTrace, cause) {
+        return new SymbolizedError(message, stackTrace, cause);
+    }
+}
+export async function createStackTraceForConsoleMessage(devTools, consoleMessage) {
+    const message = consoleMessage;
+    const rawStackTrace = message._rawStackTrace();
+    if (rawStackTrace) {
+        return createStackTrace(devTools, rawStackTrace, message._targetId());
+    }
+    return undefined;
+}
+export async function createStackTrace(devTools, rawStackTrace, targetId) {
+    const targetManager = devTools.universe.context.get(DevTools.TargetManager);
+    const target = targetId
+        ? targetManager.targetById(targetId) || devTools.target
+        : devTools.target;
+    const model = target.model(DevTools.DebuggerModel);
+    // DevTools doesn't wait for source maps to attach before building a stack trace, rather it'll send
+    // an update event once a source map was attached and the stack trace retranslated. This doesn't
+    // work in the MCP case, so we'll collect all script IDs upfront and wait for any pending source map
+    // loads before creating the stack trace. We might also have to wait for Debugger.ScriptParsed events if
+    // the stack trace is created particularly early.
+    const scriptIds = new Set();
+    for (const frame of rawStackTrace.callFrames) {
+        scriptIds.add(frame.scriptId);
+    }
+    for (let asyncStack = rawStackTrace.parent; asyncStack; asyncStack = asyncStack.parent) {
+        for (const frame of asyncStack.callFrames) {
+            scriptIds.add(frame.scriptId);
+        }
+    }
+    const signal = AbortSignal.timeout(1_000);
+    await Promise.all([...scriptIds].map(id => waitForScript(model, id, signal)
+        .then(script => model.sourceMapManager().sourceMapForClientPromise(script))
+        .catch()));
+    const binding = devTools.universe.context.get(DevTools.DebuggerWorkspaceBinding);
+    // DevTools uses branded types for ScriptId and others. Casting the puppeteer protocol type to the DevTools protocol type is safe.
+    return binding.createStackTraceFromProtocolRuntime(rawStackTrace, target);
+}
+// Waits indefinitely for the script so pair it with Promise.race.
+async function waitForScript(model, scriptId, signal) {
+    while (true) {
+        if (signal.aborted) {
+            throw signal.reason;
+        }
+        const script = model.scriptForId(scriptId);
+        if (script) {
+            return script;
+        }
+        await new Promise((resolve, reject) => {
+            signal.addEventListener('abort', () => reject(signal.reason), {
+                once: true,
+            });
+            void model
+                .once('ParsedScriptSource')
+                .then(resolve);
+        });
+    }
+}
+//# sourceMappingURL=DevtoolsUtils.js.map

package/build/src/devtools/McpHostBindingAdapter.js

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/* eslint-disable @typescript-eslint/no-empty-function */
+import { DevTools } from '../third_party/index.js';
+/**
+ * BaseClass that is noop or throws for methods.
+ * the McpHostBindingAdapter should only implement methods
+ * that it needs to support.
+ */
+class BaseMcpHostBindingAdapter {
+    connectAutomaticFileSystem() { }
+    disconnectAutomaticFileSystem() { }
+    addFileSystem() { }
+    loadCompleted() { }
+    indexPath() { }
+    setInspectedPageBounds() { }
+    showCertificateViewer() { }
+    setWhitelistedShortcuts() { }
+    setEyeDropperActive() { }
+    inspectElementCompleted() { }
+    openInNewTab() { }
+    openSearchResultsInNewTab() { }
+    showItemInFolder() { }
+    removeFileSystem() { }
+    requestFileSystems() { }
+    save() { }
+    append() { }
+    close() { }
+    searchInPath() { }
+    stopIndexing() { }
+    bringToFront() { }
+    closeWindow() { }
+    copyText() { }
+    inspectedURLChanged() { }
+    isolatedFileSystem() {
+        throw new Error('Not implemented');
+    }
+    registerPreference() { }
+    getPreferences() { }
+    getPreference() { }
+    setPreference() { }
+    removePreference() { }
+    clearPreferences() { }
+    getSyncInformation() { }
+    getHostConfig() { }
+    upgradeDraggedFileSystemPermissions() { }
+    platform() {
+        throw new Error('Not implemented');
+    }
+    recordCountHistogram() { }
+    recordEnumeratedHistogram() { }
+    recordPerformanceHistogram() { }
+    recordPerformanceHistogramMedium() { }
+    recordUserMetricsAction() { }
+    recordNewBadgeUsage() { }
+    sendMessageToBackend() { }
+    setDevicesDiscoveryConfig() { }
+    setDevicesUpdatesEnabled() { }
+    openRemotePage() { }
+    openNodeFrontend() { }
+    setInjectedScriptForOrigin() { }
+    setIsDocked() { }
+    showSurvey() { }
+    canShowSurvey() { }
+    zoomFactor() {
+        throw new Error('Not implemented');
+    }
+    zoomIn() { }
+    zoomOut() { }
+    resetZoom() { }
+    showContextMenuAtPoint() { }
+    reattach() { }
+    readyForTest() { }
+    connectionReady() { }
+    setOpenNewWindowForPopups() { }
+    isHostedMode() {
+        throw new Error('Not implemented');
+    }
+    setAddExtensionCallback() { }
+    initialTargetId() {
+        throw new Error('Not implemented');
+    }
+    doAidaConversation(_request, _streamId, cb) {
+        cb({
+            error: 'Not implemented',
+        });
+    }
+    registerAidaClientEvent(_request, cb) {
+        cb({
+            error: 'Not implemented',
+        });
+    }
+    aidaCodeComplete(_request, cb) {
+        cb({
+            error: 'Not implemented',
+        });
+    }
+    dispatchHttpRequest(_request, cb) {
+        cb({
+            error: 'Not implemented',
+        });
+    }
+    recordImpression() { }
+    recordResize() { }
+    recordClick() { }
+    recordHover() { }
+    recordDrag() { }
+    recordChange() { }
+    recordKeyDown() { }
+    recordSettingAccess() { }
+    recordFunctionCall() { }
+    setChromeFlag() { }
+    requestRestart() { }
+    loadNetworkResource(_urlString, _headers, _streamId, _callback) { }
+}
+export class McpHostBindingAdapter extends BaseMcpHostBindingAdapter {
+    #loadResource;
+    constructor(loadResource) {
+        super();
+        this.#loadResource = loadResource;
+    }
+    isolatedFileSystem() {
+        return null;
+    }
+    platform() {
+        switch (process.platform) {
+            case 'darwin':
+                return 'mac';
+            case 'win32':
+                return 'windows';
+            default:
+                return 'linux';
+        }
+    }
+    zoomFactor() {
+        return 1;
+    }
+    isHostedMode() {
+        return true;
+    }
+    initialTargetId() {
+        return Promise.resolve(null);
+    }
+    loadNetworkResource(urlString, _headers, streamId, callback) {
+        if (!URL.canParse(urlString)) {
+            callback({
+                statusCode: 404,
+                urlValid: false,
+            });
+            return;
+        }
+        this.#loadResource(urlString)
+            .then(content => {
+            DevTools.Host.ResourceLoader.streamWrite(streamId, content);
+            callback({ statusCode: 200 });
+        })
+            .catch(() => {
+            callback({ statusCode: 404 });
+        });
+    }
+}
+//# sourceMappingURL=McpHostBindingAdapter.js.map

package/build/src/devtools/issueDescriptions.js

@@ -0,0 +1,42 @@
+/**
+ * @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 = {};
+    const results = await Promise.all(files
+        .filter(file => file.endsWith('.md'))
+        .map(async (file) => {
+        const content = await fs.promises.readFile(path.join(DESCRIPTIONS_PATH, file), 'utf-8');
+        return { file, content };
+    }));
+    for (const { file, content } of results) {
+        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=issueDescriptions.js.map

package/build/src/formatters/CommentFormatter.js

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function formatCommentThread(thread) {
+    const lines = [
+        `### Thread: ${thread.id}`,
+        `- Comment: ${thread.text}`,
+    ];
+    if (thread.elementUid) {
+        lines.push(`- Target element (snapshot UID): ${thread.elementUid}`);
+    }
+    if (thread.reqid !== undefined) {
+        lines.push(`- Network request ID (reqid): ${thread.reqid}`);
+    }
+    if (thread.editor) {
+        const location = thread.editor.filePath
+            ? `${thread.editor.filePath}:${thread.editor.lineNumber}`
+            : `line ${thread.editor.lineNumber}`;
+        lines.push(`- Editor location: ${location}`);
+    }
+    return lines.join('\n');
+}
+function formatComments(threads) {
+    if (threads.length === 0) {
+        return 'No open DevTools comments found.';
+    }
+    const lines = [
+        `Found ${threads.length} DevTools comment thread(s):`,
+    ];
+    for (const thread of threads) {
+        lines.push(`\n${formatCommentThread(thread)}`);
+    }
+    return lines.join('\n');
+}
+export class CommentFormatter {
+    #threads;
+    constructor(threads) {
+        this.#threads = threads;
+    }
+    static async from(threads, options) {
+        const structuredThreads = [];
+        for (const thread of threads) {
+            let elementUid;
+            const resolveBackendNodeId = options?.resolveBackendNodeId;
+            if (thread.backendNodeId !== undefined && resolveBackendNodeId) {
+                elementUid = await resolveBackendNodeId(thread.backendNodeId);
+            }
+            let reqid;
+            const resolveCdpRequestId = options?.resolveCdpRequestId;
+            if (thread.networkRequestId !== undefined && resolveCdpRequestId) {
+                reqid = resolveCdpRequestId(thread.networkRequestId);
+            }
+            const item = {
+                id: thread.id,
+                text: thread.text,
+            };
+            if (elementUid) {
+                item.elementUid = elementUid;
+            }
+            if (reqid !== undefined) {
+                item.reqid = reqid;
+            }
+            if (thread.editor) {
+                item.editor = thread.editor;
+            }
+            structuredThreads.push(item);
+        }
+        return new CommentFormatter(structuredThreads);
+    }
+    static formatThread(thread) {
+        return formatCommentThread(thread);
+    }
+    toJSON() {
+        return [...this.#threads];
+    }
+    toString() {
+        return formatComments(this.toJSON());
+    }
+}
+//# sourceMappingURL=CommentFormatter.js.map