Subscribe for Audits.issueAdded event

Author: Natallia Harshunova

scripts/post-build.ts

@@ -63,7 +63,7 @@ export const i18n = {
     return str;
   },
   lockedLazyString: () => {},
-  getLazilyComputedLocalizedString: () => {},
+  getLazilyComputedLocalizedString: () => ()=>{},
 };
 
 // TODO(jacktfranklin): once the DocumentLatency insight does not depend on
@@ -169,6 +169,19 @@ export const hostConfig = {};
   fs.copyFileSync(devtoolsLicenseFileSource, devtoolsLicenseFileDestination);
 
   copyThirdPartyLicenseFiles();
+  copyDevToolsDescriptionFiles();
+}
+
+function copyDevToolsDescriptionFiles() {
+  const sourceDir = path.join(
+   process.cwd(),
+   'node_modules/chrome-devtools-frontend/front_end/models/issues_manager/descriptions',
+    );
+   const destDir = path.join(
+    BUILD_DIR,
+    'node_modules/chrome-devtools-frontend/front_end/models/issues_manager/descriptions',
+    );
+    fs.cpSync(sourceDir, destDir, {recursive: true});
 }
 
 main();

src/McpContext.ts

@@ -7,6 +7,8 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
+import {type Issue} from '../node_modules/chrome-devtools-frontend/mcp/mcp.js';
+
 import {extractUrlLikeFromDevToolsTitle, urlsEqual} from './DevtoolsUtils.js';
 import type {ListenerMap} from './PageCollector.js';
 import {NetworkCollector, PageCollector} from './PageCollector.js';
@@ -29,6 +31,8 @@ import type {Context, DevToolsData} from './tools/ToolDefinition.js';
 import type {TraceResult} from './trace-processing/parse.js';
 import {WaitForHelper} from './WaitForHelper.js';
 
+
+
 export interface TextSnapshotNode extends SerializedAXNode {
   id: string;
   backendNodeId?: number;
@@ -90,7 +94,7 @@ export class McpContext implements Context {
   // The most recent snapshot.
   #textSnapshot: TextSnapshot | null = null;
   #networkCollector: NetworkCollector;
-  #consoleCollector: PageCollector<ConsoleMessage | Error>;
+  #consoleCollector: PageCollector<ConsoleMessage | Error | Issue.Issue>;
 
   #isRunningTrace = false;
   #networkConditionsMap = new WeakMap<Page, string>();
@@ -130,6 +134,9 @@ export class McpContext implements Context {
             collect(error);
           }
         },
+        issue: issue => {
+          collect(issue);
+        },
       } as ListenerMap;
     });
   }
@@ -196,25 +203,25 @@ export class McpContext implements Context {
 
   getConsoleData(
     includePreservedMessages?: boolean,
-  ): Array<ConsoleMessage | Error> {
+  ): Array<ConsoleMessage | Error | Issue.Issue> {
     const page = this.getSelectedPage();
     return this.#consoleCollector.getData(page, includePreservedMessages);
   }
 
-  getConsoleMessageStableId(message: ConsoleMessage | Error): number {
+  getConsoleMessageStableId(message: ConsoleMessage | Error | Issue.Issue): number {
     return this.#consoleCollector.getIdForResource(message);
   }
 
-  getConsoleMessageById(id: number): ConsoleMessage | Error {
+  getConsoleMessageById(id: number): ConsoleMessage | Error | Issue.Issue {
     return this.#consoleCollector.getById(this.getSelectedPage(), id);
   }
 
   async newPage(): Promise<Page> {
     const page = await this.browser.newPage();
     const pages = await this.createPagesSnapshot();
     this.setSelectedPageIdx(pages.indexOf(page));
-    this.#networkCollector.addPage(page);
-    this.#consoleCollector.addPage(page);
+    await this.#networkCollector.addPage(page);
+    await this.#consoleCollector.addPage(page);
     return page;
   }
   async closePage(pageIdx: number): Promise<void> {

src/McpResponse.ts

@@ -3,6 +3,8 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { Issue } from '../node_modules/chrome-devtools-frontend/mcp/mcp.js';
+
 import type {ConsoleMessageData} from './formatters/consoleFormatter.js';
 import {
   formatConsoleEventShort,
@@ -16,6 +18,7 @@ import {
   getStatusFromRequest,
 } from './formatters/networkFormatter.js';
 import {formatSnapshotNode} from './formatters/snapshotFormatter.js';
+import {getIssueDescription} from './issue-descriptions.js';
 import type {McpContext} from './McpContext.js';
 import type {
   ConsoleMessage,
@@ -269,7 +272,7 @@ export class McpResponse implements Response {
           if ('type' in message) {
             return normalizedTypes.has(message.type());
           }
-          return normalizedTypes.has('error');
+          return normalizedTypes.has('error'); // TODO add filtering
         });
       }
 
@@ -295,6 +298,18 @@ export class McpResponse implements Response {
               ),
             };
           }
+          if (item instanceof Issue.Issue) {
+            const descriptionFile = item.getDescription()?.file;
+            const description = descriptionFile
+              ? getIssueDescription(descriptionFile)
+              : null;
+            return {
+              consoleMessageStableId,
+              type: 'issue',
+              message: item.primaryKey(),
+              args: description ? [description] : [],
+            };
+          }
           return {
             consoleMessageStableId,
             type: 'error',

src/PageCollector.ts

@@ -4,15 +4,22 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type * as CdpProtocol from '../node_modules/chrome-devtools-frontend/front_end/generated/protocol-proxy-api.js';
+import {IssuesManager, Issue} from '../node_modules/chrome-devtools-frontend/mcp/mcp.js';
+
 import {
   type Browser,
   type Frame,
   type Handler,
   type HTTPRequest,
   type Page,
-  type PageEvents,
+  type PageEvents as PuppeteerPageEvents,
 } from './third_party/index.js';
 
+interface PageEvents extends PuppeteerPageEvents {
+  issue: Issue.Issue;
+}
+
 export type ListenerMap<EventMap extends PageEvents = PageEvents> = {
   [K in keyof EventMap]?: (event: EventMap[K]) => void;
 };
@@ -58,15 +65,15 @@ export class PageCollector<T> {
   async init() {
     const pages = await this.#browser.pages();
     for (const page of pages) {
-      this.#initializePage(page);
+      await this.addPage(page);
     }
 
     this.#browser.on('targetcreated', async target => {
       const page = await target.page();
       if (!page) {
         return;
       }
-      this.#initializePage(page);
+      await this.addPage(page);
     });
     this.#browser.on('targetdestroyed', async target => {
       const page = await target.page();
@@ -77,15 +84,15 @@ export class PageCollector<T> {
     });
   }
 
-  public addPage(page: Page) {
-    this.#initializePage(page);
-  }
-
-  #initializePage(page: Page) {
+  public async addPage(page: Page) {
     if (this.storage.has(page)) {
       return;
     }
+    await this.#initializePage(page);
+  }
 
+  async #initializePage(page: Page) {
+    await this.subscribeForIssues(page);
     const idGenerator = createIdGenerator();
     const storedLists: Array<Array<WithSymbolId<T>>> = [[]];
     this.storage.set(page, storedLists);
@@ -113,6 +120,19 @@ export class PageCollector<T> {
     this.#listeners.set(page, listeners);
   }
 
+  protected async subscribeForIssues(page: Page) {
+    const session = await page.createCDPSession();
+     session.on('Audits.issueAdded',(data) => { // TODO unsubscribe
+      // @ts-expect-error Types of protocol from Puppeteer and CDP are incopatible for Issues
+        const issue = IssuesManager.createIssuesFromProtocolIssue(null, data.issue)[0]; // returns issue wrapped in array, need to get first element
+        if (!issue) {
+          return;
+        }
+        page.emit('issue', issue);
+    });
+    await session.send('Audits.enable');
+  }
+
   protected splitAfterNavigation(page: Page) {
     const navigations = this.storage.get(page);
     if (!navigations) {

src/issue-descriptions.ts

@@ -0,0 +1,49 @@
+/**
+ * @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(
+  process.cwd(),
+  'node_modules/chrome-devtools-frontend/front_end/models/issues_manager/descriptions',
+);
+
+let issueDescriptions: Record<string, string>= {};
+
+/**
+ * Reads all issue descriptions from the filesystem into memory.
+ */
+export async function loadIssueDescriptions(): Promise<void> {
+  if (Object.keys(issueDescriptions).length > 0) {
+    return;
+  }
+
+  const files = await fs.promises.readdir(DESCRIPTIONS_PATH);
+  const descriptions: Record<string, string> = {};
+
+  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: string): string | null {
+  return issueDescriptions[fileName] ?? null;
+}

src/main.ts

@@ -9,6 +9,7 @@ import './polyfill.js';
 import type {Channel} from './browser.js';
 import {ensureBrowserConnected, ensureBrowserLaunched} from './browser.js';
 import {parseArguments} from './cli.js';
+import {loadIssueDescriptions} from './issue-descriptions.js';
 import {logger, saveLogsToFile} from './logger.js';
 import {McpContext} from './McpContext.js';
 import {McpResponse} from './McpResponse.js';
@@ -188,6 +189,7 @@ for (const tool of tools) {
   registerTool(tool);
 }
 
+await loadIssueDescriptions();
 const transport = new StdioServerTransport();
 await server.connect(transport);
 logger('Chrome DevTools MCP Server connected');

src/tools/console.ts

@@ -9,10 +9,11 @@ import type {ConsoleMessageType} from '../third_party/index.js';
 
 import {ToolCategory} from './categories.js';
 import {defineTool} from './ToolDefinition.js';
+type ConsoleResponseType = ConsoleMessageType | 'issue';
 
 const FILTERABLE_MESSAGE_TYPES: readonly [
-  ConsoleMessageType,
-  ...ConsoleMessageType[],
+  ConsoleResponseType,
+  ...ConsoleResponseType[],
 ] = [
   'log',
   'debug',
@@ -33,6 +34,7 @@ const FILTERABLE_MESSAGE_TYPES: readonly [
   'count',
   'timeEnd',
   'verbose',
+  'issue'
 ];
 
 export const listConsoleMessages = defineTool({

test.txt

@@ -56,7 +56,10 @@
     "node_modules/chrome-devtools-frontend/front_end/third_party/legacy-javascript",
     "node_modules/chrome-devtools-frontend/front_end/third_party/source-map-scopes-codec",
     "node_modules/chrome-devtools-frontend/front_end/core/root",
-    "node_modules/chrome-devtools-frontend/front_end/third_party/third-party-web"
+    "node_modules/chrome-devtools-frontend/front_end/third_party/third-party-web",
+
+    "node_modules/chrome-devtools-frontend/front_end/models/issues_manager",
+    "node_modules/chrome-devtools-frontend/front_end/third_party/marked"
   ],
   "exclude": ["node_modules/chrome-devtools-frontend/**/*.test.ts"]
 }