Chrome DevTools for coding agents
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import type {WebMCPTool} from 'puppeteer-core';
import type {ReadonlyServerConfig} from './config/ServerConfig.js';
import {
CommentFormatter,
type StructuredCommentThread,
} from './formatters/CommentFormatter.js';
import {ConsoleFormatter} from './formatters/ConsoleFormatter.js';
import {
type CascadeRule,
CssFormatter,
type CssFormatterOptions,
resolveContainerQueries,
} from './formatters/CssFormatter.js';
import {
collectRankedContexts,
type ContextAnalysisReport,
type ContextFilterOptions,
formatName,
HeapSnapshotFormatter,
type HeapSnapshotFormatOptions,
isEdgeLike,
isNodeLike,
} from './formatters/HeapSnapshotFormatter.js';
import {IssueFormatter} from './formatters/IssueFormatter.js';
import {NetworkFormatter} from './formatters/NetworkFormatter.js';
import {SnapshotFormatter} from './formatters/SnapshotFormatter.js';
import {WebAuthnFormatter} from './formatters/WebAuthnFormatter.js';
import type {
HeapSnapshotAggregateData,
HeapSnapshotClassDiff,
HeapSnapshotClassDiffTotals,
HeapSnapshotDetailedClassDiff,
HeapSnapshotDiff,
DuplicateStringGroup,
} from './processors/HeapSnapshotManager.js';
import type {McpContext} from './McpContext.js';
import type {McpPage} from './McpPage.js';
import {UncaughtError} from './collectors/PageCollector.js';
import {TextSnapshot} from './TextSnapshot.js';
import {
DevTools,
getToonEncode,
getGcfEncode,
type ConsoleMessage,
type ImageContent,
type ResourceType,
type TextContent,
type Extension,
type HTTPRequest,
type Protocol,
} from './third_party/index.js';
import {handleDialog, listPages} from './tools/pages.js';
import type {ToolGroups} from './tools/thirdPartyDeveloper.js';
import type {
DevToolsData,
ImageContentData,
LighthouseData,
MatchedStyles,
Response,
SnapshotParams,
WebAuthnAuthenticatorState,
} from './tools/ToolDefinition.js';
import {LIST_CONSOLE_MESSAGES_TOOL_NAME} from './tools/toolNames.js';
import {
type InsightName,
type TraceResult,
getInsightOutput,
getTraceSummary,
} from './processors/PerformanceTrace.js';
import type {CD4ACommentThread, PaginationOptions} from './types.js';
import {stableIdSymbol, type WithSymbolId} from './utils/id.js';
import {paginate} from './utils/pagination.js';
import {getFilterableResourceType} from './utils/resourceType.js';
import {truncateText} from './utils/text.js';
import type {WaitForEventsResult} from './utils/WaitForHelper.js';
const {formatBytesToKb} = DevTools.I18n.ByteUtilities;
/** How many errors raised during a call the response lists. */
const MAX_CONSOLE_ERRORS = 10;
export type DataFormat = 'default' | 'toon' | 'gcf';
interface TraceInsightData {
trace: TraceResult;
insightSetId: string;
insightName: InsightName;
}
interface ContextAnalysisOptions
extends PaginationOptions, ContextFilterOptions, HeapSnapshotFormatOptions {}
export class McpResponse implements Response {
#includePages = false;
#includeExtensionServiceWorkers = false;
#includeExtensionPages = false;
#snapshotParams?: SnapshotParams;
#attachedNetworkRequestId?: number;
#attachedNetworkRequestOptions?: {
requestFilePath?: string;
responseFilePath?: string;
};
#attachedConsoleMessageId?: number;
#attachedTraceSummary?: TraceResult;
#attachedTraceInsight?: TraceInsightData;
#attachedLighthouseResult?: LighthouseData;
#textResponseLines: string[] = [];
#images: ImageContentData[] = [];
#heapSnapshotOptions?: {
include: boolean;
aggregateData?: HeapSnapshotAggregateData;
pagination?: PaginationOptions;
stats?: DevTools.HeapSnapshotModel.HeapSnapshotModel.Statistics;
staticData?: DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData | null;
nativeContextSizes?: DevTools.HeapSnapshotModel.HeapSnapshotModel.NativeContextSizes;
retainedByContextSummary?: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary;
nodes?: DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange;
retainingPaths?: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingPaths;
dominators?: DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain;
diff?: HeapSnapshotDiff;
detailedClassDiff?: HeapSnapshotDetailedClassDiff;
duplicateStrings?: DuplicateStringGroup[];
objectInfo?: DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo;
contextAnalysis?: DevTools.HeapSnapshotModel.HeapSnapshotModel.ContextAnalysisResult;
contextAnalysisOptions?: ContextAnalysisOptions;
formatOptions?: HeapSnapshotFormatOptions;
};
#networkRequestsOptions?: {
include: boolean;
pagination?: PaginationOptions;
resourceTypes?: ResourceType[];
includePreservedRequests?: boolean;
networkRequestIdInDevToolsUI?: number;
};
#consoleDataOptions?: {
include: boolean;
pagination?: PaginationOptions;
types?: string[];
includePreservedMessages?: boolean;
includeStackTraces?: boolean;
serviceWorkerId?: string;
};
#cssStylesData?: {
matchedStyles: MatchedStyles;
options: CssFormatterOptions & PaginationOptions;
};
#listExtensions?: boolean;
#listThirdPartyDeveloperTools?: boolean;
#listWebMcpTools?: boolean;
#devToolsData?: DevToolsData;
#tabId?: string;
#config: ReadonlyServerConfig;
#page?: McpPage;
#error?: Error;
#attachedWaitForResult?: WaitForEventsResult;
#consoleErrorsFrom?: {page: McpPage; lastMessageId: number};
#reconnectNotice = false;
#devToolsComments?: CD4ACommentThread[];
#webAuthnFormatter?: WebAuthnFormatter;
get #deviceScope(): DevTools.CrUXManager.DeviceScope {
return this.#page?.viewport?.isMobile ? 'PHONE' : 'DESKTOP';
}
constructor(config: ReadonlyServerConfig) {
this.#config = config;
}
setPage(page: McpPage): void {
this.#page = page;
}
/**
* Surfaces a one-time note that the browser reconnected and page ids changed.
* Set by the tool handler when the context reports a pending reconnect notice.
*/
setReconnectNotice(): void {
this.#reconnectNotice = true;
}
attachDevToolsData(data: DevToolsData): void {
this.#devToolsData = data;
}
setTabId(tabId: string): void {
this.#tabId = tabId;
}
setIncludePages(value: boolean): void {
this.#includePages = value;
if (this.#config.resolved.categoryExtensions) {
this.#includeExtensionServiceWorkers = value;
this.#includeExtensionPages = value;
}
}
setIncludeExtensionServiceWorkers(value: boolean): void {
this.#includeExtensionServiceWorkers = value;
}
includeSnapshot(params?: SnapshotParams): void {
this.#snapshotParams = params ?? {
verbose: false,
};
}
setListExtensions(): void {
this.#listExtensions = true;
}
setListThirdPartyDeveloperTools(): void {
this.#listThirdPartyDeveloperTools = true;
}
setListWebMcpTools(): void {
this.#listWebMcpTools = true;
}
setIncludeNetworkRequests(
value: boolean,
options?: PaginationOptions & {
resourceTypes?: ResourceType[];
includePreservedRequests?: boolean;
networkRequestIdInDevToolsUI?: number;
},
): void {
if (!value) {
this.#networkRequestsOptions = undefined;
return;
}
this.#networkRequestsOptions = {
include: value,
pagination:
options?.pageSize !== undefined
? {
pageSize: options.pageSize,
pageIdx: options.pageIdx,
}
: undefined,
resourceTypes: options?.resourceTypes,
includePreservedRequests: options?.includePreservedRequests,
networkRequestIdInDevToolsUI: options?.networkRequestIdInDevToolsUI,
};
}
setIncludeConsoleData(
value: boolean,
options?: PaginationOptions & {
types?: string[];
includePreservedMessages?: boolean;
includeStackTraces?: boolean;
serviceWorkerId?: string;
},
): void {
if (!value) {
this.#consoleDataOptions = undefined;
return;
}
this.#consoleDataOptions = {
include: value,
pagination:
options?.pageSize !== undefined
? {
pageSize: options.pageSize,
pageIdx: options.pageIdx,
}
: undefined,
types: options?.types,
includePreservedMessages: options?.includePreservedMessages,
includeStackTraces: options?.includeStackTraces,
serviceWorkerId: options?.serviceWorkerId,
};
}
includeConsoleErrorsFrom(page: McpPage): void {
this.#consoleErrorsFrom = {
page,
lastMessageId: page.getLatestConsoleMessageId(),
};
}
setIncludeCssStyles(
matchedStyles: MatchedStyles,
options: CssFormatterOptions & PaginationOptions,
): void {
this.#cssStylesData = {
matchedStyles,
options,
};
}
setError(error: Error): void {
this.#error = error;
}
attachNetworkRequest(
reqId: number,
options?: {requestFilePath?: string; responseFilePath?: string},
): void {
this.#attachedNetworkRequestId = reqId;
this.#attachedNetworkRequestOptions = options;
}
attachConsoleMessage(msgid: number): void {
this.#attachedConsoleMessageId = msgid;
}
attachWebAuthnAuthenticator(
authenticator: WebAuthnAuthenticatorState | undefined,
): void {
this.#webAuthnFormatter = new WebAuthnFormatter(authenticator);
}
attachTraceSummary(result: TraceResult): void {
this.#attachedTraceSummary = result;
}
attachTraceInsight(
trace: TraceResult,
insightSetId: string,
insightName: InsightName,
): void {
this.#attachedTraceInsight = {
trace,
insightSetId,
insightName,
};
}
attachLighthouseResult(result: LighthouseData): void {
this.#attachedLighthouseResult = result;
}
get includePages(): boolean {
return this.#includePages;
}
get attachedTraceSummary(): TraceResult | undefined {
return this.#attachedTraceSummary;
}
get attachedTracedInsight(): TraceInsightData | undefined {
return this.#attachedTraceInsight;
}
get attachedLighthouseResult(): LighthouseData | undefined {
return this.#attachedLighthouseResult;
}
get includeNetworkRequests(): boolean {
return this.#networkRequestsOptions?.include ?? false;
}
get includeConsoleData(): boolean {
return this.#consoleDataOptions?.include ?? false;
}
get attachedNetworkRequestId(): number | undefined {
return this.#attachedNetworkRequestId;
}
get networkRequestsPageIdx(): number | undefined {
return this.#networkRequestsOptions?.pagination?.pageIdx;
}
get consoleMessagesPageIdx(): number | undefined {
return this.#consoleDataOptions?.pagination?.pageIdx;
}
get consoleMessagesTypes(): string[] | undefined {
return this.#consoleDataOptions?.types;
}
get error(): Error | undefined {
return this.#error;
}
appendResponseLine(value: string): void {
this.#textResponseLines.push(value);
}
attachWaitForResult(result: WaitForEventsResult): void {
this.#attachedWaitForResult = result;
}
setDevToolsComments(threads: CD4ACommentThread[]): void {
this.#devToolsComments = threads;
}
get devToolsComments(): readonly CD4ACommentThread[] | undefined {
return this.#devToolsComments;
}
setHeapSnapshotAggregates(
aggregateData: HeapSnapshotAggregateData,
options?: PaginationOptions & HeapSnapshotFormatOptions,
): void {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
include: true,
aggregateData,
pagination: options,
formatOptions: options,
};
}
setHeapSnapshotStats(
stats: DevTools.HeapSnapshotModel.HeapSnapshotModel.Statistics,
staticData: DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData | null,
nativeContextSizes: DevTools.HeapSnapshotModel.HeapSnapshotModel.NativeContextSizes,
retainedByContextSummary: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary,
options?: HeapSnapshotFormatOptions,
): void {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
include: true,
stats,
staticData,
nativeContextSizes,
retainedByContextSummary,
formatOptions: options,
};
}
setHeapSnapshotNodes(
nodes: DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange,
options?: PaginationOptions & HeapSnapshotFormatOptions,
): void {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
include: true,
nodes,
pagination: options,
formatOptions: options,
};
}
setHeapSnapshotDuplicateStrings(
duplicateStrings: DuplicateStringGroup[],
options?: PaginationOptions & HeapSnapshotFormatOptions,
): void {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
include: true,
duplicateStrings,
pagination: options,
formatOptions: options,
};
}
setHeapSnapshotRetainingPaths(
retainingPaths: DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingPaths,
options?: HeapSnapshotFormatOptions,
): void {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
include: true,
retainingPaths,
formatOptions: options,
};
}
setHeapSnapshotDominators(
dominators: DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain,
options?: HeapSnapshotFormatOptions,
): void {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
include: true,
dominators,
formatOptions: options,
};
}
setHeapSnapshotClassDiffs(
diff: HeapSnapshotDiff,
options?: PaginationOptions & HeapSnapshotFormatOptions,
): void {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
include: true,
diff,
pagination: options,
formatOptions: options,
};
}
setHeapSnapshotDetailedClassDiff(
detailedClassDiff: HeapSnapshotDetailedClassDiff,
options?: PaginationOptions & HeapSnapshotFormatOptions,
): void {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
include: true,
detailedClassDiff,
pagination: options,
formatOptions: options,
};
}
setHeapSnapshotObjectDetails(
objectInfo: DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo,
options?: HeapSnapshotFormatOptions,
): void {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
include: true,
objectInfo,
formatOptions: options,
};
}
setHeapSnapshotContextAnalysis(
contextAnalysis: DevTools.HeapSnapshotModel.HeapSnapshotModel.ContextAnalysisResult,
options?: ContextAnalysisOptions,
): void {
this.#heapSnapshotOptions = {
...this.#heapSnapshotOptions,
include: true,
contextAnalysis,
contextAnalysisOptions: options,
formatOptions: options,
};
}
attachImage(value: ImageContentData): void {
this.#images.push(value);
}
get responseLines(): readonly string[] {
return this.#textResponseLines;
}
get images(): ImageContentData[] {
return this.#images;
}
get snapshotParams(): SnapshotParams | undefined {
return this.#snapshotParams;
}
get listWebMcpTools(): boolean | undefined {
return this.#listWebMcpTools;
}
async #handleSnapshot(
context: McpContext,
): Promise<SnapshotFormatter | string | undefined> {
if (!this.#snapshotParams) {
return undefined;
}
if (!this.#page) {
throw new Error('Response must have a page');
}
this.#page.textSnapshot = await TextSnapshot.create(this.#page, {
verbose: this.#snapshotParams.verbose,
devtoolsData: this.#devToolsData,
});
const formatter = new SnapshotFormatter(this.#page.textSnapshot);
if (this.#snapshotParams.filePath) {
const result = await context.saveFile(
new TextEncoder().encode(formatter.toString()),
this.#snapshotParams.filePath,
'.txt',
);
return result.filename;
}
return formatter;
}
async #handleAttachedNetworkRequest(
context: McpContext,
): Promise<NetworkFormatter | undefined> {
if (!this.#attachedNetworkRequestId) {
return undefined;
}
if (!this.#page) {
throw new Error(`Response must have an McpPage`);
}
const request = this.#page.getNetworkRequestById(
this.#attachedNetworkRequestId,
);
return await NetworkFormatter.from(request, {
requestId: this.#attachedNetworkRequestId,
requestIdResolver: req => this.getNetworkRequestStableId(req),
fetchData: true,
requestFilePath: this.#attachedNetworkRequestOptions?.requestFilePath,
responseFilePath: this.#attachedNetworkRequestOptions?.responseFilePath,
saveFile: (data, filename, extension) =>
context.saveFile(data, filename, extension),
redactNetworkHeaders: this.#config.resolved.redactNetworkHeaders,
});
}
async #handleAttachedConsoleMessage(): Promise<
ConsoleFormatter | IssueFormatter | undefined
> {
if (!this.#attachedConsoleMessageId) {
return undefined;
}
if (!this.#page) {
throw new Error(`Response must have an McpPage`);
}
const message = this.#page.getConsoleMessageById(
this.#attachedConsoleMessageId,
);
const consoleMessageStableId = this.#attachedConsoleMessageId;
if ('args' in message || message instanceof UncaughtError) {
const consoleMessage = message as ConsoleMessage | UncaughtError;
return await ConsoleFormatter.from(consoleMessage, {
id: consoleMessageStableId,
fetchDetailedData: true,
devTools: this.#page.devtoolsUniverse,
});
}
if (message instanceof DevTools.AggregatedIssue) {
const formatter = new IssueFormatter(message, {
id: consoleMessageStableId,
requestIdResolver: this.#page.resolveCdpRequestId.bind(this.#page),
elementIdResolver: this.#page.textSnapshot?.resolveCdpElementId.bind(
this.#page.textSnapshot,
),
});
if (!formatter.isValid()) {
throw new Error(
"Can't provide details for the msgid " + consoleMessageStableId,
);
}
return formatter;
}
return undefined;
}
async #handleThirdPartyDeveloperTools(): Promise<ToolGroups | undefined> {
if (
this.#config.resolved.categoryExperimentalThirdParty &&
this.#listThirdPartyDeveloperTools &&
this.#page
) {
return await this.#page.discoverThirdPartyDeveloperTools();
}
return undefined;
}
async #handleWebMCP(): Promise<WebMCPTool[] | undefined> {
if (
this.#config.resolved.categoryExperimentalWebmcp &&
this.#listWebMcpTools &&
this.#page
) {
return this.#page.getWebMcpTools();
}
return undefined;
}
async #handleConsoleList(
context: McpContext,
): Promise<Array<ConsoleFormatter | IssueFormatter> | undefined> {
if (!this.#consoleDataOptions?.include) {
return undefined;
}
let messages;
let page: McpPage | undefined;
if (this.#consoleDataOptions.serviceWorkerId) {
messages = context.getServiceWorkerConsoleData(
this.#consoleDataOptions.serviceWorkerId,
);
} else {
page = this.#page;
if (!page) {
throw new Error(`Response must have an McpPage`);
}
messages = page.getConsoleData(
this.#consoleDataOptions.includePreservedMessages,
);
}
return await this.#formatConsoleData(
messages,
page,
this.#consoleDataOptions,
);
}
async #handleConsoleErrors(): Promise<
Array<ConsoleFormatter | IssueFormatter> | undefined
> {
const errorsFrom = this.#consoleErrorsFrom;
// A tool that lists or shows console messages itself already covers these.
if (
!errorsFrom ||
this.#consoleDataOptions?.include ||
this.#attachedConsoleMessageId !== undefined ||
errorsFrom.page.isClosed()
) {
return undefined;
}
return await this.#formatConsoleData(
errorsFrom.page.getConsoleDataAfter(errorsFrom.lastMessageId),
errorsFrom.page,
{types: ['error']},
);
}
async #formatConsoleData(
messages: Array<
ConsoleMessage | Error | DevTools.AggregatedIssue | UncaughtError
>,
page: McpPage | undefined,
options: {types?: string[]; includeStackTraces?: boolean},
): Promise<Array<ConsoleFormatter | IssueFormatter>> {
if (options.types?.length) {
const normalizedTypes = new Set(options.types);
messages = messages.filter(message => {
if ('type' in message) {
return normalizedTypes.has(message.type());
}
if (message instanceof DevTools.AggregatedIssue) {
return normalizedTypes.has('issue');
}
return normalizedTypes.has('error');
});
}
return (
await Promise.all(
messages.map(
async (item): Promise<ConsoleFormatter | IssueFormatter | null> => {
const consoleMessageStableId = this.getConsoleMessageStableId(item);
if ('args' in item || item instanceof UncaughtError) {
const consoleMessage = item as ConsoleMessage | UncaughtError;
return await ConsoleFormatter.from(consoleMessage, {
id: consoleMessageStableId,
fetchDetailedData: false,
fetchStackTrace: options.includeStackTraces,
devTools: page ? page.devtoolsUniverse : undefined,
});
}
if (item instanceof DevTools.AggregatedIssue) {
const formatter = new IssueFormatter(item, {
id: consoleMessageStableId,
});
if (!formatter.isValid()) {
return null;
}
return formatter;
}
return null;
},
),
)
).filter(item => item !== null);
}
async #handleNetworkRequestList(
context: McpContext,
): Promise<NetworkFormatter[] | undefined> {
if (!this.#networkRequestsOptions?.include) {
return undefined;
}
if (!this.#page) {
throw new Error(`Response must have an McpPage`);
}
let requests = this.#page.getNetworkRequests(
this.#networkRequestsOptions?.includePreservedRequests,
);
// Apply resource type filtering if specified
if (this.#networkRequestsOptions.resourceTypes?.length) {
const normalizedTypes = new Set(
this.#networkRequestsOptions.resourceTypes,
);
requests = requests.filter(request => {
return normalizedTypes.has(getFilterableResourceType(request));
});
}
return await Promise.all(
requests.map(request =>
NetworkFormatter.from(request, {
requestId: this.getNetworkRequestStableId(request),
selectedInDevToolsUI:
this.getNetworkRequestStableId(request) ===
this.#networkRequestsOptions?.networkRequestIdInDevToolsUI,
fetchData: false,
saveFile: (data, filename, extension) =>
context.saveFile(data, filename, extension),
redactNetworkHeaders: this.#config.resolved.redactNetworkHeaders,
}),
),
);
}
async #handleComments(): Promise<
| {
formatter: CommentFormatter;
commentsSnapshotRegenerated?: 'standard' | 'verbose';
}
| undefined
> {
const comments = this.#devToolsComments;
if (!comments) {
return undefined;
}
const page = this.#page;
const initialSnapshot = page?.textSnapshot;
const formatter = await CommentFormatter.from(comments, {
resolveBackendNodeId: page
? (id: number) => page.resolveBackendNodeId(id)
: undefined,
resolveCdpRequestId: page
? (id: string) => page.resolveCdpRequestId(id)
: undefined,
});
let commentsSnapshotRegenerated: 'standard' | 'verbose' | undefined;
if (page?.textSnapshot && page.textSnapshot !== initialSnapshot) {
commentsSnapshotRegenerated = page.textSnapshot.verbose
? 'verbose'
: 'standard';
}
return {formatter, commentsSnapshotRegenerated};
}
async handle(
context: McpContext,
dataFormat: DataFormat = 'default',
): Promise<{
content: Array<TextContent | ImageContent>;
structuredContent: object;
}> {
if (this.#includePages || this.#attachedWaitForResult?.openedPages) {
await context.createPagesSnapshot();
}
if (this.#includePages && (!this.#page || this.#page.isClosed())) {
try {
this.#page = context.getSelectedMcpPage();
} catch {
this.#page = undefined;
}
}
const [
snapshot,
detailedNetworkRequest,
detailedConsoleMessage,
thirdPartyDeveloperTools,
webmcpTools,
consoleMessages,
consoleErrors,
networkRequests,
commentsResult,
] = await Promise.all([
this.#handleSnapshot(context),
this.#handleAttachedNetworkRequest(context),
this.#handleAttachedConsoleMessage(),
this.#handleThirdPartyDeveloperTools(),
this.#handleWebMCP(),
this.#handleConsoleList(context),
this.#handleConsoleErrors(),
this.#handleNetworkRequestList(context),
this.#handleComments(),
]);
if (this.#includeExtensionServiceWorkers) {
context.createWorkersSnapshot();
}
let extensions: Map<string, Extension> | undefined;
if (this.#listExtensions) {
extensions = await context.listExtensions();
}
return await this.format(
context,
{
detailedConsoleMessage,
consoleMessages,
consoleErrors,
snapshot,
detailedNetworkRequest,
networkRequests,
traceInsight: this.#attachedTraceInsight,
traceSummary: this.#attachedTraceSummary,
extensions,
lighthouseResult: this.#attachedLighthouseResult,
thirdPartyDeveloperTools,
webmcpTools,
comments: commentsResult?.formatter,
commentsSnapshotRegenerated:
commentsResult?.commentsSnapshotRegenerated,
errorMessage: this.#error?.message,
},
dataFormat,
);
}
getConsoleMessageStableId(
message: ConsoleMessage | Error | DevTools.AggregatedIssue | UncaughtError,
): number {
return (message as WithSymbolId<typeof message>)[stableIdSymbol] ?? -1;
}
getNetworkRequestStableId(request: HTTPRequest): number {
return (request as WithSymbolId<typeof request>)[stableIdSymbol] ?? -1;
}
async format(
context: McpContext,
data: {
detailedConsoleMessage: ConsoleFormatter | IssueFormatter | undefined;
consoleMessages: Array<ConsoleFormatter | IssueFormatter> | undefined;
consoleErrors?: Array<ConsoleFormatter | IssueFormatter>;
snapshot: SnapshotFormatter | string | undefined;
detailedNetworkRequest?: NetworkFormatter;
networkRequests?: NetworkFormatter[];
traceSummary?: TraceResult;
traceInsight?: TraceInsightData;
extensions?: Map<string, Extension>;
lighthouseResult?: LighthouseData;
thirdPartyDeveloperTools?: ToolGroups;
webmcpTools?: WebMCPTool[];
comments?: CommentFormatter;
commentsSnapshotRegenerated?: 'standard' | 'verbose';
errorMessage?: string;
},
dataFormat: DataFormat = 'default',
): Promise<{
content: Array<TextContent | ImageContent>;
structuredContent: object;
}> {
const structuredContent: {
snapshot?: object;
snapshotFilePath?: string;
tabId?: string;
networkRequest?: object;
networkRequests?: object[];
consoleMessage?: object;
consoleMessages?: object[];
consoleErrors?: object[];
traceSummary?: string;
traceInsights?: Array<{
insightName: string;
insightKey: string | undefined;
}>;
traceInsight?: string;
error?: string;
lighthouseResult?: object;
extensions?: object[];
thirdPartyDeveloperTools?: object[];
webmcpTools?: object[];
message?: string;
reconnected?: boolean;
networkConditions?: string;
navigationTimeout?: number;
viewport?: object;
userAgent?: string;
cpuThrottlingRate?: number;
colorScheme?: string;
forcedColors?: string;
prefersContrast?: string;
prefersReducedMotion?: string;
dialog?: {
type: string;
message: string;
defaultValue?: string;
};
pages?: object[];
openedPages?: object[];
pagination?: object;
heapSnapshot?: {
stats?: object;
staticData?: object;
nativeContextSizes?: object;
retainedByContextSummary?: object;
aggregateStats?: {
objectCount: number;
totalSelfSize: number;
};
classDiffStats?: HeapSnapshotClassDiffTotals;
};
heapSnapshotAggregates?: readonly object[];
heapSnapshotNodes?: readonly object[];
heapSnapshotRetainingPaths?: object;
heapSnapshotDominators?: readonly object[];
heapSnapshotClassDiffs?: readonly HeapSnapshotClassDiff[];
heapSnapshotDetailedClassDiff?: HeapSnapshotDetailedClassDiff;
heapSnapshotDuplicateStrings?: readonly DuplicateStringGroup[];
heapSnapshotObjectDetails?: DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo;
heapSnapshotContextAnalysis?: ContextAnalysisReport;
extensionServiceWorkers?: object[];
extensionPages?: object[];
comments?: StructuredCommentThread[];
commentsSnapshotRegenerated?: 'standard' | 'verbose';
matchedStyles?: object;
webauthnAuthenticator?: WebAuthnAuthenticatorState | null;
errorMessage?: string;
navigatedToUrl?: string;
geolocation?: {latitude: number; longitude: number};
} = {};
// Resolve the compact encoder based on the chosen format
let compactEncode: ((val: unknown) => string) | undefined;
if (dataFormat === 'toon') {
try {
compactEncode = await getToonEncode();
} catch {
throw new Error(
'The `@toon-format/toon` package is required to use --experimentalDataFormat=toon. ' +
'Make sure the peer dependency is installed:\n' +
'- For npx: npx --package chrome-devtools-mcp@latest --package @toon-format/toon@latest chrome-devtools-mcp --experimentalDataFormat=toon\n' +
'- For npm: npm install @toon-format/toon (add -g if installed globally)',
);
}
} else if (dataFormat === 'gcf') {
try {
compactEncode = await getGcfEncode();
} catch {
throw new Error(
'The `@blackwell-systems/gcf` package is required to use --experimentalDataFormat=gcf. ' +
'Make sure the peer dependency is installed:\n' +
'- For npx: npx --package chrome-devtools-mcp@latest --package @blackwell-systems/gcf@latest chrome-devtools-mcp --experimentalDataFormat=gcf\n' +
'- For npm: npm install @blackwell-systems/gcf (add -g if installed globally)',
);
}
}
const response = [];
if (this.#reconnectNotice) {
structuredContent.reconnected = true;
response.push(
`Note: the browser was restarted or reconnected since the last call. Page ids have changed. Call ${listPages(this.#config.resolved).name} to see open pages.`,
);
}
if (this.#textResponseLines.length) {
structuredContent.message = this.#textResponseLines.join('\n');
response.push(...this.#textResponseLines);
}
if (this.#attachedWaitForResult) {
if (this.#attachedWaitForResult.navigatedToUrl) {
response.push(
`Page navigated to ${this.#attachedWaitForResult.navigatedToUrl}.`,
);
structuredContent.navigatedToUrl =
this.#attachedWaitForResult.navigatedToUrl;
}
if (this.#attachedWaitForResult.openedPages) {
const openedPages = this.#attachedWaitForResult.openedPages;
const openedMcpPages = context
.getPages()
.filter(mcpPage => openedPages.has(mcpPage.target));
if (openedMcpPages.length) {
const targetInfos = await context.getTargetInfos();
response.push('## Opened pages');
const structuredPages = [];
for (const mcpPage of openedMcpPages) {
const page = formatPage(
mcpPage,
context,
targetInfos.get(mcpPage.targetId),
);
response.push(page.text);
structuredPages.push(page.structured);
}
structuredContent.openedPages = structuredPages;
}
}
}
const page = this.#page;
const networkConditions = page?.networkConditions;
if (page && networkConditions) {
const timeout = page.pptrPage.getDefaultNavigationTimeout();
response.push(`Emulating network conditions: ${networkConditions}`);
response.push(`Default navigation timeout set to ${timeout} ms`);
structuredContent.networkConditions = networkConditions;
structuredContent.navigationTimeout = timeout;
}
const geolocation = this.#page?.geolocation;
if (geolocation) {
response.push(
`Emulating geolocation: latitude=${geolocation.latitude}, longitude=${geolocation.longitude}`,
);
structuredContent.geolocation = geolocation;
}
const viewport = this.#page?.viewport;
if (viewport) {
response.push(`Emulating viewport: ${JSON.stringify(viewport)}`);
structuredContent.viewport = viewport;
}
const userAgent = this.#page?.userAgent;
if (userAgent) {
response.push(`Emulating user agent: ${userAgent}`);
structuredContent.userAgent = userAgent;
}
const cpuThrottlingRate = this.#page?.cpuThrottlingRate ?? 1;
if (cpuThrottlingRate > 1) {
response.push(`Emulating CPU throttling: ${cpuThrottlingRate}x slowdown`);
structuredContent.cpuThrottlingRate = cpuThrottlingRate;
}
const colorScheme = this.#page?.colorScheme;
if (colorScheme) {
response.push(`Emulating color scheme: ${colorScheme}`);
structuredContent.colorScheme = colorScheme;
}
const forcedColors = this.#page?.forcedColors;
if (forcedColors) {
response.push(`Emulating forced-colors: ${forcedColors}`);
structuredContent.forcedColors = forcedColors;
}
const prefersContrast = this.#page?.prefersContrast;
if (prefersContrast) {
response.push(`Emulating prefers-contrast: ${prefersContrast}`);
structuredContent.prefersContrast = prefersContrast;
}
const prefersReducedMotion = this.#page?.prefersReducedMotion;
if (prefersReducedMotion) {
response.push(
`Emulating prefers-reduced-motion: ${prefersReducedMotion}`,
);
structuredContent.prefersReducedMotion = prefersReducedMotion;
}
const dialog = this.#page?.getDialog();
if (dialog) {
const defaultValueIfNeeded =
dialog.type() === 'prompt'
? ` (default value: "${dialog.defaultValue()}")`
: '';
response.push(`# Open dialog
${dialog.type()}: ${dialog.message()}${defaultValueIfNeeded}.
Call ${handleDialog(this.#config.resolved).name} to handle it before continuing.`);
structuredContent.dialog = {
type: dialog.type(),
message: dialog.message(),
defaultValue: dialog.defaultValue(),
};
}
if (this.#includePages) {
const allPages = context.getPages();
const {regularPages, extensionPages} = allPages.reduce(
(
acc: {regularPages: McpPage[]; extensionPages: McpPage[]},
mcpPage: McpPage,
) => {
if (mcpPage.url().startsWith('chrome-extension://')) {
acc.extensionPages.push(mcpPage);
} else {
acc.regularPages.push(mcpPage);
}
return acc;
},
{regularPages: [], extensionPages: []},
);
const selectionFallback = context.getSelectedPageFallback();
if (selectionFallback) {
let selectedPageId: number | undefined;
try {
selectedPageId = context.getSelectedMcpPage().id;
} catch {
selectedPageId = undefined;
}
response.push(
`Note: the previously selected page ${selectionFallback.wasClosed ? 'was closed' : 'is no longer listed'}.${selectedPageId !== undefined ? ` Page ${selectedPageId} is now selected.` : ''}`,
);
}
const targetInfos =
regularPages.length ||
(this.#includeExtensionPages && extensionPages.length)
? await context.getTargetInfos()
: new Map<string, Protocol.Target.TargetInfo>();
if (regularPages.length) {
const parts = [`## Pages`];
const structuredPages = [];
for (const mcpPage of regularPages) {
const isolatedContextName = mcpPage.isolatedContextName;
const contextLabel = isolatedContextName
? ` isolatedContext=${isolatedContextName}`
: '';
const page = formatPage(
mcpPage,
context,
targetInfos.get(mcpPage.targetId),
);
parts.push(
`${page.text}${context.isPageSelected(mcpPage) ? ' [selected]' : ''}${contextLabel}${formatWebAuthnLabel(mcpPage)}`,
);
structuredPages.push(page.structured);
}
response.push(...parts);
structuredContent.pages = structuredPages;
}
if (this.#includeExtensionPages) {
if (extensionPages.length) {
response.push(`## Extension Pages`);
const structuredExtensionPages = [];
for (const mcpPage of extensionPages) {
const isolatedContextName = mcpPage.isolatedContextName;
const contextLabel = isolatedContextName
? ` isolatedContext=${isolatedContextName}`
: '';
const page = formatPage(
mcpPage,
context,
targetInfos.get(mcpPage.targetId),
);
response.push(
`${page.text}${context.isPageSelected(mcpPage) ? ' [selected]' : ''}${contextLabel}${formatWebAuthnLabel(mcpPage)}`,
);
structuredExtensionPages.push(page.structured);
}
structuredContent.extensionPages = structuredExtensionPages;
}
}
}
if (this.#includeExtensionServiceWorkers) {
const extensionServiceWorkers = context
.getWorkers()
.filter(worker => worker.type === 'service_worker');
if (extensionServiceWorkers.length) {
response.push(`## Extension Service Workers`);
}
for (const extensionServiceWorker of extensionServiceWorkers) {
response.push(
`${extensionServiceWorker.id}: ${extensionServiceWorker.url}`,
);
}
structuredContent.extensionServiceWorkers = extensionServiceWorkers.map(
extensionServiceWorker => {
return {
id: extensionServiceWorker.id,
url: extensionServiceWorker.url,
};
},
);
}
if (this.#tabId) {
structuredContent.tabId = this.#tabId;
}
if (data.traceSummary) {
const summary = getTraceSummary(data.traceSummary, this.#deviceScope);
response.push(summary);
structuredContent.traceSummary = summary;
structuredContent.traceInsights = [];
for (const insightSet of data.traceSummary.insights?.values() ?? []) {
for (const [insightName, model] of Object.entries(insightSet.model)) {
structuredContent.traceInsights.push({
insightName,
insightKey:
typeof model === 'object' &&
model !== null &&
'insightKey' in model
? model.insightKey
: undefined,
});
}
}
}
if (data.traceInsight) {
const insightOutput = getInsightOutput(
data.traceInsight.trace,
data.traceInsight.insightSetId,
data.traceInsight.insightName,
this.#deviceScope,
);
if ('error' in insightOutput) {
response.push(insightOutput.error);
structuredContent.error = insightOutput.error;
} else {
response.push(insightOutput.output);
structuredContent.traceInsight = insightOutput.output;
}
}
if (data.lighthouseResult) {
structuredContent.lighthouseResult = data.lighthouseResult;
const {summary, failedAudits, reports} = data.lighthouseResult;
response.push('## Lighthouse audit results');
response.push(`Mode: ${summary.mode}`);
response.push(`Device: ${summary.device}`);
response.push(`URL: ${summary.url}`);
response.push('### Category scores');
for (const score of summary.scores) {
// Lighthouse uses a null score for categories that could not be
// scored and renders scores as Math.round(score * 100).
const formattedScore =
score.score === null ? 'n/a' : Math.round(score.score * 100);
response.push(`- ${score.title}: ${formattedScore} (${score.id})`);
}
response.push('### Audit summary');
response.push(`Passed: ${summary.audits.passed}`);
response.push(`Failed: ${summary.audits.failed}`);
response.push(`Total timing: ${summary.timing.total}ms`);
if (failedAudits.length) {
response.push('### Failed audits');
for (const audit of failedAudits) {
const categories = audit.categories.length
? ` [${audit.categories.join(', ')}]`
: '';
const displayValue = audit.displayValue
? ` (${audit.displayValue})`
: '';
response.push(
`- ${audit.id}${categories}: ${audit.title}${displayValue} (score: ${audit.score})`,
);
if (audit.description) {
response.push(` ${collapseWhitespace(audit.description)}`);
}
if (audit.totalNodes) {
const shown =
audit.totalNodes > audit.nodes.length
? `, showing ${audit.nodes.length}`
: '';
response.push(` Nodes (${audit.totalNodes}${shown}):`);
}
for (const node of audit.nodes) {
// Values are JSON-encoded so that quotes or spaces within them
// cannot be confused with the `key=value` delimiters.
const parts: string[] = [];
if (node.selector) {
parts.push(`selector=${JSON.stringify(node.selector)}`);
}
if (node.nodeLabel) {
parts.push(
`label=${JSON.stringify(collapseWhitespace(node.nodeLabel))}`,
);
}
if (node.snippet) {
parts.push(
`snippet=${JSON.stringify(collapseWhitespace(node.snippet))}`,
);
}
response.push(` - ${parts.join(' ')}`);
if (node.explanation) {
response.push(` ${collapseWhitespace(node.explanation)}`);
}
}
}
}
response.push('### Reports');
for (const report of reports) {
response.push(`- ${report}`);
}
}
if (data.snapshot) {
if (typeof data.snapshot === 'string') {
response.push(`Saved snapshot to ${data.snapshot}.`);
structuredContent.snapshotFilePath = data.snapshot;
} else {
structuredContent.snapshot = data.snapshot.toJSON();
response.push('## Latest page snapshot');
response.push(
compactEncode
? compactEncode(structuredContent.snapshot)
: data.snapshot.toString(),
);
}
}
if (this.#heapSnapshotOptions?.include) {
response.push('## Heap Snapshot Data');
const formatOptions = this.#heapSnapshotOptions.formatOptions ?? {};
const stats = this.#heapSnapshotOptions.stats;
const staticData = this.#heapSnapshotOptions.staticData;
if (stats) {
response.push(`Statistics: ${JSON.stringify(stats, null, 2)}`);
structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
structuredContent.heapSnapshot.stats = stats;
}
if (staticData) {
response.push(`Static Data: ${JSON.stringify(staticData, null, 2)}`);
structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
structuredContent.heapSnapshot.staticData = staticData;
}
const nativeContextSizes = this.#heapSnapshotOptions.nativeContextSizes;
if (nativeContextSizes) {
response.push('### Native Contexts');
response.push(
HeapSnapshotFormatter.formatNativeContextSizes(
nativeContextSizes,
formatOptions,
),
);
structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
structuredContent.heapSnapshot.nativeContextSizes = nativeContextSizes;
}
const retainedByContextSummary =
this.#heapSnapshotOptions.retainedByContextSummary;
if (retainedByContextSummary) {
response.push('### Retained by Context Summary');
response.push(
HeapSnapshotFormatter.formatRetainedByContextSummary(
retainedByContextSummary,
),
);
structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
structuredContent.heapSnapshot.retainedByContextSummary =
retainedByContextSummary;
}
const aggregateData = this.#heapSnapshotOptions.aggregateData;
if (aggregateData) {
const paginationData = this.#dataWithPagination(
aggregateData.aggregates,
this.#heapSnapshotOptions.pagination,
);
response.push(`Objects: ${aggregateData.objectCount}`);
response.push(
`Total shallow size: ${formatBytesToKb(aggregateData.totalSelfSize)}`,
);
structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
structuredContent.heapSnapshot.aggregateStats = {
objectCount: aggregateData.objectCount,
totalSelfSize: aggregateData.totalSelfSize,
};
structuredContent.pagination = paginationData.pagination;
response.push(...paginationData.info);
structuredContent.heapSnapshotAggregates = paginationData.items;
response.push(
compactEncode
? compactEncode(
paginationData.items.map(aggregate => ({
...aggregate,
className: formatName(aggregate.className, formatOptions),
})),
)
: HeapSnapshotFormatter.formatAggregates(
paginationData.items,
formatOptions,
),
);
}
const nodes = this.#heapSnapshotOptions.nodes;
if (nodes) {
let items = Array.from(nodes.items);
const firstItem = nodes.items[0];
if (firstItem) {
if (isNodeLike(firstItem)) {
items = items
.filter(isNodeLike)
.sort((a, b) => b.retainedSize - a.retainedSize);
} else if (isEdgeLike(firstItem)) {
items = items.filter(isEdgeLike);
}
}
const paginationData = this.#dataWithPagination(
items,
this.#heapSnapshotOptions.pagination,
);
response.push(
HeapSnapshotFormatter.formatNodes(
paginationData.items,
formatOptions,
),
);
structuredContent.pagination = paginationData.pagination;
response.push(...paginationData.info);
structuredContent.heapSnapshotNodes = paginationData.items;
}
const retainingPaths = this.#heapSnapshotOptions.retainingPaths;
if (retainingPaths) {
response.push('### Retaining Paths');
const {paths, limitsReached} = retainingPaths;
if (paths.length === 0) {
response.push('No retaining paths found.');
} else {
response.push(
HeapSnapshotFormatter.formatRetainingPaths(paths, formatOptions),
);
}
const reached = Object.entries(limitsReached)
.filter(([, hit]) => hit)
.map(([limit]) => limit);
if (reached.length > 0) {
response.push(
`Note: results are truncated, the following limits were reached: ${reached.join(', ')}.`,
);
}
structuredContent.heapSnapshotRetainingPaths =
retainingPaths as unknown as object;
}
const dominators = this.#heapSnapshotOptions.dominators;
if (dominators) {
response.push('### Dominator Chain');
if (dominators.length === 0) {
response.push('No dominators found.');
} else {
response.push(
HeapSnapshotFormatter.formatDominators(dominators, formatOptions),
);
}
structuredContent.heapSnapshotDominators = dominators;
}
const diff = this.#heapSnapshotOptions.diff;
if (diff) {
response.push('### Heap Snapshot Diff');
response.push(HeapSnapshotFormatter.formatDiffTotals(diff.totals));
structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
structuredContent.heapSnapshot.classDiffStats = diff.totals;
const paginationData = this.#dataWithPagination(
diff.classDiffs,
this.#heapSnapshotOptions.pagination,
);
structuredContent.pagination = paginationData.pagination;
response.push(...paginationData.info);
response.push(
compactEncode
? compactEncode(
paginationData.items.map(diff => ({
...diff,
className: formatName(diff.className, formatOptions),
})),
)
: HeapSnapshotFormatter.formatDiffSummary(
paginationData.items,
formatOptions,
),
);
structuredContent.heapSnapshotClassDiffs = paginationData.items;
}
const detailedClassDiff = this.#heapSnapshotOptions.detailedClassDiff;
if (detailedClassDiff) {
response.push('### Heap Snapshot Detailed Diff');
const {classDiff, objects} = detailedClassDiff;
const paginationData = this.#dataWithPagination(
objects,
this.#heapSnapshotOptions.pagination,
);
structuredContent.pagination = paginationData.pagination;
response.push(
compactEncode
? compactEncode({
...classDiff,
className: formatName(classDiff.className, formatOptions),
})
: HeapSnapshotFormatter.formatDetailedClassDiffHeader(
classDiff,
formatOptions,
),
);
response.push(...paginationData.info);
response.push(
compactEncode
? compactEncode(paginationData.items)
: HeapSnapshotFormatter.formatDetailedClassDiffObjects(
paginationData.items,
),
);
structuredContent.heapSnapshotDetailedClassDiff = {
classDiff,
objects: paginationData.items,
};
}
const duplicateStrings = this.#heapSnapshotOptions.duplicateStrings;
if (duplicateStrings) {
response.push('### Duplicate Strings');
const paginationData = this.#dataWithPagination(
duplicateStrings,
this.#heapSnapshotOptions.pagination,
);
structuredContent.pagination = paginationData.pagination;
response.push(...paginationData.info);
const formatted = HeapSnapshotFormatter.formatDuplicateStrings(
paginationData.items,
formatOptions,
);
response.push(formatted);
structuredContent.heapSnapshotDuplicateStrings = paginationData.items;
}
const objectInfo = this.#heapSnapshotOptions.objectInfo;
if (objectInfo) {
response.push('### Object Details');
if (compactEncode) {
response.push(
compactEncode({
...objectInfo,
name: formatName(objectInfo.name, formatOptions),
}),
);
} else {
response.push(
HeapSnapshotFormatter.formatObjectInfo(objectInfo, formatOptions),
);
}
structuredContent.heapSnapshotObjectDetails = objectInfo;
}
const contextAnalysis = this.#heapSnapshotOptions.contextAnalysis;
if (contextAnalysis) {
const contextAnalysisOptions =
this.#heapSnapshotOptions.contextAnalysisOptions;
const rankedContexts = collectRankedContexts(contextAnalysis, {
retainedSize: contextAnalysisOptions?.retainedSize,
scopeInfoNodeId: contextAnalysisOptions?.scopeInfoNodeId,
});
const paginationData = this.#dataWithPagination(rankedContexts, {
pageIdx: contextAnalysisOptions?.pageIdx ?? 0,
pageSize: contextAnalysisOptions?.pageSize,
});
const report: ContextAnalysisReport = {
contexts: paginationData.items,
scriptsWithoutScopes: contextAnalysis.scriptsWithoutScopes,
};
response.push('### Context Analysis');
structuredContent.pagination = paginationData.pagination;
response.push(...paginationData.info);
response.push(
compactEncode
? compactEncode(report)
: HeapSnapshotFormatter.formatContextAnalysis(
report,
formatOptions,
),
);
structuredContent.heapSnapshotContextAnalysis = report;
}
}
if (data.detailedNetworkRequest) {
response.push(data.detailedNetworkRequest.toStringDetailed());
structuredContent.networkRequest =
data.detailedNetworkRequest.toJSONDetailed();
}
if (data.detailedConsoleMessage) {
response.push(data.detailedConsoleMessage.toStringDetailed());
structuredContent.consoleMessage =
data.detailedConsoleMessage.toJSONDetailed();
}
if (data.extensions) {
const extensionArray = Array.from(data.extensions.values());
structuredContent.extensions = extensionArray;
response.push('## Extensions');
if (extensionArray.length === 0) {
response.push('No unpacked extensions found.');
} else {
const extensionsMessage = extensionArray
.map(extension => {
return `id=${extension.id} "${extension.name}" v${extension.version} ${extension.enabled ? 'Enabled' : 'Disabled'}`;
})
.join('\n');
response.push(extensionsMessage);
}
}
const thirdPartyDeveloperTools = data.thirdPartyDeveloperTools;
if (this.#listThirdPartyDeveloperTools && thirdPartyDeveloperTools) {
structuredContent.thirdPartyDeveloperTools = thirdPartyDeveloperTools;
response.push('## Third-party developer tools');
if (thirdPartyDeveloperTools.length === 0) {
response.push('No third-party developer tools available.');
} else {
for (const toolGroup of thirdPartyDeveloperTools) {
response.push(`${toolGroup.name}: ${toolGroup.description}`);
response.push('Available tools:');
const toolDefinitionsMessage = toolGroup.tools
.map(tool => {
return `name="${tool.name}", description="${tool.description}", inputSchema=${JSON.stringify(
tool.inputSchema,
)}`;
})
.join('\n');
response.push(toolDefinitionsMessage);
}
}
}
if (this.#listWebMcpTools && data.webmcpTools) {
structuredContent.webmcpTools = data.webmcpTools.map(
({name, description, inputSchema, annotations}) => ({
name,
description,
inputSchema,
annotations,
}),
);
response.push('## WebMCP tools');
if (data.webmcpTools.length === 0) {
response.push('No WebMCP tools available.');
} else {
const webmcpToolsMessage = data.webmcpTools
.map(tool => {
return `name="${tool.name}", description="${tool.description}", inputSchema=${JSON.stringify(
tool.inputSchema,
)}, annotations=${JSON.stringify(tool.annotations)}`;
})
.join('\n');
response.push(webmcpToolsMessage);
}
}
if (this.#networkRequestsOptions?.include && data.networkRequests) {
const requests = data.networkRequests;
response.push('## Network requests');
if (requests.length) {
const paginationData = this.#dataWithPagination(
requests,
this.#networkRequestsOptions.pagination,
);
structuredContent.pagination = paginationData.pagination;
response.push(...paginationData.info);
if (data.networkRequests) {
structuredContent.networkRequests = paginationData.items.map(i =>
i.toJSON(),
);
response.push(
...(compactEncode
? [compactEncode(structuredContent.networkRequests)]
: paginationData.items.map(i => i.toString())),
);
}
} else {
response.push('No requests found.');
}
}
if (this.#consoleDataOptions?.include) {
const messages = data.consoleMessages ?? [];
response.push('## Console messages');
if (messages.length) {
const grouped = ConsoleFormatter.groupConsecutive(messages);
const paginationData = this.#dataWithPagination(
grouped,
this.#consoleDataOptions.pagination,
);
structuredContent.pagination = paginationData.pagination;
structuredContent.consoleMessages = paginationData.items.map(item =>
item.toJSON(),
);
response.push(...paginationData.info);
if (compactEncode) {
response.push(compactEncode(structuredContent.consoleMessages));
} else {
response.push(...paginationData.items.map(item => item.toString()));
}
if (
structuredContent.consoleMessages.some(
message => 'stackTrace' in message,
)
) {
response.push(
'Note: stack trace line and column numbers use 1-based indexing',
);
}
} else {
response.push('<no console messages found>');
}
}
if (data.consoleErrors?.length) {
const grouped = ConsoleFormatter.groupConsecutive(data.consoleErrors);
const shown = grouped.slice(0, MAX_CONSOLE_ERRORS);
structuredContent.consoleErrors = shown.map(item => item.toJSON());
response.push('## Console errors during this call');
if (compactEncode) {
response.push(compactEncode(structuredContent.consoleErrors));
} else {
response.push(...shown.map(item => item.toString()));
}
if (grouped.length > shown.length) {
response.push(
`${grouped.length - shown.length} more not shown. Call ${LIST_CONSOLE_MESSAGES_TOOL_NAME} to list them.`,
);
}
}
if (data.comments) {
const commentsJson = data.comments.toJSON();
structuredContent.comments = commentsJson;
response.push(
compactEncode ? compactEncode(commentsJson) : data.comments.toString(),
);
if (data.commentsSnapshotRegenerated) {
response.push(
`Note: DevTools comments regenerated the ${data.commentsSnapshotRegenerated} text snapshot.`,
);
structuredContent.commentsSnapshotRegenerated =
data.commentsSnapshotRegenerated;
}
}
if (this.#webAuthnFormatter) {
structuredContent.webauthnAuthenticator =
this.#webAuthnFormatter.toJSON();
response.push(
compactEncode
? compactEncode(structuredContent.webauthnAuthenticator)
: this.#webAuthnFormatter.toString(),
);
}
if (this.#cssStylesData) {
const resolveUid = (backendNodeId: number): string | undefined =>
this.#page?.textSnapshot?.resolveCdpElementId(backendNodeId);
const containerDetails = await resolveContainerQueries(
this.#cssStylesData.matchedStyles,
resolveUid,
);
const options = {
...this.#cssStylesData.options,
resolveUid,
containerDetails,
};
const allRules = CssFormatter.collectRules(
this.#cssStylesData.matchedStyles,
options,
);
let rules: readonly CascadeRule[] = allRules;
const hasPagination =
this.#cssStylesData.options.pageSize !== undefined ||
this.#cssStylesData.options.pageIdx !== undefined;
if (hasPagination) {
const paginationData = this.#dataWithPagination(
allRules,
this.#cssStylesData.options,
);
structuredContent.pagination = paginationData.pagination;
response.push(...paginationData.info);
rules = paginationData.items;
}
const formatter = new CssFormatter(
this.#cssStylesData.matchedStyles,
options,
rules,
);
structuredContent.matchedStyles = formatter.toJSON();
if (compactEncode) {
response.push(compactEncode(structuredContent.matchedStyles));
} else {
response.push(formatter.toString());
}
}
if (data.errorMessage) {
response.push(`Error: ${data.errorMessage}`);
structuredContent.errorMessage = data.errorMessage;
}
const text: TextContent = {
type: 'text',
text: response.join('\n'),
};
const images: ImageContent[] = this.#images.map(imageData => {
return {
type: 'image',
...imageData,
} as const;
});
return {
content: [text, ...images],
structuredContent,
};
}
#dataWithPagination<T>(
data: readonly T[],
pagination?: PaginationOptions,
): {
info: string[];
items: readonly T[];
pagination: {
currentPage: number;
totalPages: number;
hasNextPage: boolean;
hasPreviousPage: boolean;
startIndex: number;
endIndex: number;
invalidPage: boolean;
};
} {
const response = [];
const paginationResult = paginate<T>(data, pagination);
if (paginationResult.invalidPage) {
response.push('Invalid page number provided. Showing first page.');
}
const {startIndex, endIndex, currentPage, totalPages} = paginationResult;
const displayStartIndex = data.length === 0 ? 0 : startIndex + 1;
response.push(
`Showing ${displayStartIndex}-${endIndex} of ${data.length} (Page ${currentPage + 1} of ${totalPages}).`,
);
if (pagination) {
if (paginationResult.hasNextPage) {
response.push(`Next page: ${currentPage + 1}`);
}
if (paginationResult.hasPreviousPage) {
response.push(`Previous page: ${currentPage - 1}`);
}
}
return {
info: response,
items: paginationResult.items,
pagination: {
currentPage: paginationResult.currentPage,
totalPages: paginationResult.totalPages,
hasNextPage: paginationResult.hasNextPage,
hasPreviousPage: paginationResult.hasPreviousPage,
startIndex: paginationResult.startIndex,
endIndex: paginationResult.endIndex,
invalidPage: paginationResult.invalidPage,
},
};
}
resetResponseLineForTesting(): void {
this.#textResponseLines = [];
}
}
function truncateTitle(title: string, maxLength = 50): string {
return truncateText(title, maxLength, {includeEllipsisInLength: true});
}
const collapseWhitespace = (value: string): string => {
return value.replace(/\s+/g, ' ').trim();
};
function formatPage(
mcpPage: McpPage,
context: McpContext,
targetInfo: Protocol.Target.TargetInfo | undefined,
): {text: string; structured: ReturnType<typeof createStructuredPage>} {
const title = mcpPage.getTitle(targetInfo);
const url = mcpPage.url();
const pageLabel = title ? `${truncateTitle(title)} (${url})` : url;
return {
text: `${mcpPage.id}: ${pageLabel}`,
structured: createStructuredPage(mcpPage, context, title),
};
}
function getWebAuthnLabel(mcpPage: McpPage): string | undefined {
const authenticator = mcpPage.getWebAuthnAuthenticator();
return authenticator
? `${authenticator.protocol}/${authenticator.transport}`
: undefined;
}
function formatWebAuthnLabel(mcpPage: McpPage): string {
const label = getWebAuthnLabel(mcpPage);
return label ? ` webauthn=${label}` : '';
}
function createStructuredPage(
mcpPage: McpPage,
context: McpContext,
rawTitle: string,
): {
id: number | undefined;
url: string;
title: string;
selected: boolean;
isolatedContext?: string;
webauthn?: string;
} {
const isolatedContextName = mcpPage.isolatedContextName;
const title = truncateTitle(rawTitle);
const entry: {
id: number | undefined;
url: string;
title: string;
selected: boolean;
isolatedContext?: string;
webauthn?: string;
} = {
id: mcpPage.id,
url: mcpPage.url(),
title,
selected: context.isPageSelected(mcpPage),
};
if (isolatedContextName) {
entry.isolatedContext = isolatedContextName;
}
const webAuthnLabel = getWebAuthnLabel(mcpPage);
if (webAuthnLabel) {
entry.webauthn = webAuthnLabel;
}
return entry;
}