ideamans-chrome-devtools-mcp 0.11.2

package/build/node_modules/chrome-devtools-frontend/mcp/mcp.js

@@ -0,0 +1,35 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+// Instantiating a DevTools universe requires settings from these meta files.
+// Until settings registration is handled differently, the easiest solution is to
+// just import relevant meta files (as long as they don't contain any UI related code)
+import '../front_end/core/sdk/sdk-meta.js';
+import '../front_end/models/workspace/workspace-meta.js';
+import { installInspectorFrontendHost } from '../front_end/core/host/InspectorFrontendHost.js';
+import { McpHostBindings } from './HostBindings.js';
+/**
+ * IMPORTANT! Make sure that any class that is exported here has related unit
+ * tests added to foundation_unittests. See front_end/core/i18n/BUILD.gn as an
+ * example.
+ */
+export * as Common from '../front_end/core/common/common.js';
+export * as I18n from '../front_end/core/i18n/i18n.js';
+export { ConnectionTransport } from '../front_end/core/protocol_client/ConnectionTransport.js';
+export * as ProtocolClient from '../front_end/core/protocol_client/protocol_client.js';
+export { DebuggerModel } from '../front_end/core/sdk/DebuggerModel.js';
+export { Target } from '../front_end/core/sdk/Target.js';
+export { TargetManager } from '../front_end/core/sdk/TargetManager.js';
+export * as Foundation from '../front_end/foundation/foundation.js';
+export { PerformanceInsightFormatter } from '../front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.js';
+export { PerformanceTraceFormatter } from '../front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.js';
+export { AgentFocus } from '../front_end/models/ai_assistance/performance/AIContext.js';
+export { DebuggerWorkspaceBinding } from '../front_end/models/bindings/DebuggerWorkspaceBinding.js';
+export { Issue } from '../front_end/models/issues_manager/Issue.js';
+export { AggregatedIssue, IssueAggregator } from '../front_end/models/issues_manager/IssueAggregator.js';
+export { createIssuesFromProtocolIssue, IssuesManager } from '../front_end/models/issues_manager/IssuesManager.js';
+export * as MarkdownIssueDescription from '../front_end/models/issues_manager/MarkdownIssueDescription.js';
+export * as StackTrace from '../front_end/models/stack_trace/stack_trace.js';
+export * as TraceEngine from '../front_end/models/trace/trace.js';
+export * as Marked from '../front_end/third_party/marked/marked.js';
+installInspectorFrontendHost(new McpHostBindings());

package/build/src/DevToolsConnectionAdapter.js

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CDPSessionEvent } from './third_party/index.js';
+/**
+ * This class makes a puppeteer connection look like DevTools CDPConnection.
+ *
+ * Since we connect "root" DevTools targets to specific pages, we scope everything to a puppeteer CDP session.
+ *
+ * We don't have to recursively listen for 'sessionattached' as the "root" CDP session sees all child session attached
+ * events, regardless how deeply nested they are.
+ */
+export class PuppeteerDevToolsConnection {
+    #connection;
+    #observers = new Set();
+    #sessionEventHandlers = new Map();
+    constructor(session) {
+        this.#connection = session.connection();
+        session.on(CDPSessionEvent.SessionAttached, this.#startForwardingCdpEvents.bind(this));
+        session.on(CDPSessionEvent.SessionDetached, this.#stopForwardingCdpEvents.bind(this));
+        this.#startForwardingCdpEvents(session);
+    }
+    send(method, params, sessionId) {
+        if (sessionId === undefined) {
+            throw new Error('Attempting to send on the root session. This must not happen');
+        }
+        const session = this.#connection.session(sessionId);
+        if (!session) {
+            throw new Error('Unknown session ' + sessionId);
+        }
+        // Rolled protocol version between puppeteer and DevTools doesn't necessarily match
+        /* eslint-disable @typescript-eslint/no-explicit-any */
+        return session
+            .send(method, params)
+            .then(result => ({ result }))
+            .catch(error => ({ error }));
+        /* eslint-enable @typescript-eslint/no-explicit-any */
+    }
+    observe(observer) {
+        this.#observers.add(observer);
+    }
+    unobserve(observer) {
+        this.#observers.delete(observer);
+    }
+    #startForwardingCdpEvents(session) {
+        const handler = this.#handleEvent.bind(this, session.id());
+        this.#sessionEventHandlers.set(session.id(), handler);
+        session.on('*', handler);
+    }
+    #stopForwardingCdpEvents(session) {
+        const handler = this.#sessionEventHandlers.get(session.id());
+        if (handler) {
+            session.off('*', handler);
+        }
+    }
+    #handleEvent(sessionId, type, event) {
+        if (typeof type === 'string' &&
+            type !== CDPSessionEvent.SessionAttached &&
+            type !== CDPSessionEvent.SessionDetached) {
+            this.#observers.forEach(observer => observer.onEvent({
+                method: type,
+                sessionId,
+                params: event,
+            }));
+        }
+    }
+}

package/build/src/DevtoolsUtils.js

@@ -0,0 +1,206 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DebuggerModel, Foundation, TargetManager, MarkdownIssueDescription, Marked, ProtocolClient, Common, I18n, } from '../node_modules/chrome-devtools-frontend/mcp/mcp.js';
+import { PuppeteerDevToolsConnection } from './DevToolsConnectionAdapter.js';
+import { ISSUE_UTILS } from './issue-descriptions.js';
+import { logger } from './logger.js';
+import { Mutex } from './Mutex.js';
+export function extractUrlLikeFromDevToolsTitle(title) {
+    const match = title.match(new RegExp(`DevTools - (.*)`));
+    return match?.[1] ?? undefined;
+}
+export function urlsEqual(url1, url2) {
+    const normalizedUrl1 = normalizeUrl(url1);
+    const normalizedUrl2 = normalizeUrl(url2);
+    return normalizedUrl1 === normalizedUrl2;
+}
+/**
+ * For the sake of the MCP server, when we determine if two URLs are equal we
+ * remove some parts:
+ *
+ * 1. We do not care about the protocol.
+ * 2. We do not care about trailing slashes.
+ * 3. We do not care about "www".
+ * 4. We ignore the hash parts.
+ *
+ * For example, if the user types "record a trace on foo.com", we would want to
+ * match a tab in the connected Chrome instance that is showing "www.foo.com/"
+ */
+function normalizeUrl(url) {
+    let result = url.trim();
+    // Remove protocols
+    if (result.startsWith('https://')) {
+        result = result.slice(8);
+    }
+    else if (result.startsWith('http://')) {
+        result = result.slice(7);
+    }
+    // Remove 'www.'. This ensures that we find the right URL regardless of if the user adds `www` or not.
+    if (result.startsWith('www.')) {
+        result = result.slice(4);
+    }
+    // We use target URLs to locate DevTools but those often do
+    // no include hash.
+    const hashIdx = result.lastIndexOf('#');
+    if (hashIdx !== -1) {
+        result = result.slice(0, hashIdx);
+    }
+    // Remove trailing slash
+    if (result.endsWith('/')) {
+        result = result.slice(0, -1);
+    }
+    return result;
+}
+/**
+ * A mock implementation of an issues manager that only implements the methods
+ * that are actually used by the IssuesAggregator
+ */
+export class FakeIssuesManager extends Common.ObjectWrapper
+    .ObjectWrapper {
+    issues() {
+        return [];
+    }
+}
+export function mapIssueToMessageObject(issue) {
+    const count = issue.getAggregatedIssuesCount();
+    const markdownDescription = issue.getDescription();
+    const filename = markdownDescription?.file;
+    if (!markdownDescription) {
+        logger(`no description found for issue:` + issue.code);
+        return null;
+    }
+    const rawMarkdown = filename
+        ? ISSUE_UTILS.getIssueDescription(filename)
+        : null;
+    if (!rawMarkdown) {
+        logger(`no markdown ${filename} found for issue:` + issue.code);
+        return null;
+    }
+    let processedMarkdown;
+    let title;
+    try {
+        processedMarkdown = MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription.substitutions);
+        const markdownAst = Marked.Marked.lexer(processedMarkdown);
+        title = MarkdownIssueDescription.findTitleFromMarkdownAst(markdownAst);
+    }
+    catch {
+        logger('error parsing markdown for issue ' + issue.code());
+        return null;
+    }
+    if (!title) {
+        logger('cannot read issue title from ' + filename);
+        return null;
+    }
+    return {
+        type: 'issue',
+        item: issue,
+        message: title,
+        count,
+        description: processedMarkdown,
+    };
+}
+// DevTools CDP errors can get noisy.
+ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
+I18n.DevToolsLocale.DevToolsLocale.instance({
+    create: true,
+    data: {
+        navigatorLanguage: 'en-US',
+        settingLanguage: 'en-US',
+        lookupClosestDevToolsLocale: l => l,
+    },
+});
+I18n.i18n.registerLocaleDataForTest('en-US', {});
+export class UniverseManager {
+    #browser;
+    #createUniverseFor;
+    #universes = new WeakMap();
+    /** Guard access to #universes so we don't create unnecessary universes */
+    #mutex = new Mutex();
+    constructor(browser, factory = DEFAULT_FACTORY) {
+        this.#browser = browser;
+        this.#createUniverseFor = factory;
+    }
+    async init(pages) {
+        try {
+            await this.#mutex.acquire();
+            const promises = [];
+            for (const page of pages) {
+                promises.push(this.#createUniverseFor(page).then(targetUniverse => this.#universes.set(page, targetUniverse)));
+            }
+            this.#browser.on('targetcreated', this.#onTargetCreated);
+            this.#browser.on('targetdestroyed', this.#onTargetDestroyed);
+            await Promise.all(promises);
+        }
+        finally {
+            this.#mutex.release();
+        }
+    }
+    get(page) {
+        return this.#universes.get(page) ?? null;
+    }
+    dispose() {
+        this.#browser.off('targetcreated', this.#onTargetCreated);
+        this.#browser.off('targetdestroyed', this.#onTargetDestroyed);
+    }
+    #onTargetCreated = async (target) => {
+        const page = await target.page();
+        try {
+            await this.#mutex.acquire();
+            if (!page || this.#universes.has(page)) {
+                return;
+            }
+            this.#universes.set(page, await this.#createUniverseFor(page));
+        }
+        finally {
+            this.#mutex.release();
+        }
+    };
+    #onTargetDestroyed = async (target) => {
+        const page = await target.page();
+        try {
+            await this.#mutex.acquire();
+            if (!page || !this.#universes.has(page)) {
+                return;
+            }
+            this.#universes.delete(page);
+        }
+        finally {
+            this.#mutex.release();
+        }
+    };
+}
+const DEFAULT_FACTORY = async (page) => {
+    const settingStorage = new Common.Settings.SettingsStorage({});
+    const universe = new Foundation.Universe.Universe({
+        settingsCreationOptions: {
+            syncedStorage: settingStorage,
+            globalStorage: settingStorage,
+            localStorage: settingStorage,
+            settingRegistrations: Common.SettingRegistration.getRegisteredSettings(),
+        },
+        overrideAutoStartModels: new Set([DebuggerModel]),
+    });
+    const session = await page.createCDPSession();
+    const connection = new PuppeteerDevToolsConnection(session);
+    const targetManager = universe.context.get(TargetManager);
+    targetManager.observeModels(DebuggerModel, SKIP_ALL_PAUSES);
+    const target = targetManager.createTarget('main', '', 'frame', // eslint-disable-line @typescript-eslint/no-explicit-any
+    /* parentTarget */ null, session.id(), undefined, connection);
+    return { target, universe };
+};
+// We don't want to pause any DevTools universe session ever on the MCP side.
+//
+// Note that calling `setSkipAllPauses` only affects the session on which it was
+// sent. This means DevTools can still pause, step and do whatever. We just won't
+// see the `Debugger.paused`/`Debugger.resumed` events on the MCP side.
+const SKIP_ALL_PAUSES = {
+    modelAdded(model) {
+        void model.agent.invoke_setSkipAllPauses({ skip: true });
+    },
+    modelRemoved() {
+        // Do nothing.
+    },
+};