Skip to content

Chrome DevTools for coding agents

refactor: wrap Server into a class (#2633)

Nikolay Vitkov1a092ff551c8
diff --git a/src/bin/chrome-devtools-mcp-main.ts b/src/bin/chrome-devtools-mcp-main.ts
index caaabadf..ef35b8f8 100644
--- a/src/bin/chrome-devtools-mcp-main.ts
+++ b/src/bin/chrome-devtools-mcp-main.ts
@@ -9,7 +9,7 @@ import '../utils/polyfill.js';
import process from 'node:process';
import {closeBrowser} from '../browser.js';
-import {createMcpServer, logDisclaimers} from '../index.js';
+import {McpServer, logDisclaimers} from '../index.js';
import {ClearcutLogger} from '../telemetry/ClearcutLogger.js';
import {computeFlagUsage} from '../telemetry/flagUtils.js';
import {StdioServerTransport} from '../third_party/index.js';
@@ -72,7 +72,7 @@ process.on('SIGHUP', () => {
});
logger?.(`Starting Chrome DevTools MCP Server v${VERSION}`);
-const {server} = await createMcpServer(args, {
+const server = await McpServer.from(args, {
logFile,
});
const transport = new StdioServerTransport();
diff --git a/src/index.ts b/src/index.ts
index ecbd8965..2c35b00d 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -6,26 +6,28 @@
import type fs from 'node:fs';
-import {type ParsedArguments} from './config/mcp-options.js';
import type {Channel} from './browser.js';
import {ensureBrowserConnected, ensureBrowserLaunched} from './browser.js';
+import {type ParsedArguments} from './config/mcp-options.js';
import {loadIssueDescriptions} from './devtools/issueDescriptions.js';
import {McpContext} from './McpContext.js';
import {ClearcutLogger} from './telemetry/ClearcutLogger.js';
import {FilePersistence} from './telemetry/persistence.js';
import {
- McpServer,
+ McpServer as SdkMcpServer,
type CallToolResult,
type Root,
+ type Transport,
SetLevelRequestSchema,
ListRootsResultSchema,
RootsListChangedNotificationSchema,
+ Mutex,
+ puppeteer,
} from './third_party/index.js';
import {ToolHandler} from './ToolHandler.js';
import type {DefinedPageTool, ToolDefinition} from './tools/ToolDefinition.js';
import {createTools} from './tools/tools.js';
import {logger} from './utils/logger.js';
-import {Mutex, puppeteer} from './third_party/index.js';
import {VERSION} from './version.js';
export {buildFlag} from './ToolHandler.js';
@@ -42,174 +44,233 @@ puppeteer.setFollowSymlinks(false);
*/
const ROOTS_REQUEST_TIMEOUT = 5_000;
-export async function createMcpServer(
- serverArgs: ParsedArguments,
- options: {
- logFile?: fs.WriteStream;
- },
-) {
- if (serverArgs.usageStatistics) {
- ClearcutLogger.initialize({
- persistence: new FilePersistence(),
- logFile: serverArgs.logFile,
- appVersion: VERSION,
- clearcutEndpoint: serverArgs.clearcutEndpoint,
- clearcutForceFlushIntervalMs: serverArgs.clearcutForceFlushIntervalMs,
- clearcutIncludePidHeader: serverArgs.clearcutIncludePidHeader,
+export interface McpServerOptions {
+ logFile?: fs.WriteStream;
+}
+
+export class McpServer {
+ readonly server: SdkMcpServer;
+ #serverArgs: ParsedArguments;
+ #options: McpServerOptions;
+ #context?: McpContext;
+
+ /**
+ * Roots are client state rather than browser state, so the last listing stays
+ * valid across browser reconnects and only the client can invalidate it, via
+ * the `roots/list_changed` notification handled below
+ */
+ #lastRoots?: Root[];
+ #toolMutex = new Mutex();
+
+ private constructor(
+ serverArgs: ParsedArguments,
+ options: McpServerOptions = {},
+ ) {
+ this.#serverArgs = serverArgs;
+ this.#options = options;
+
+ if (this.#serverArgs.usageStatistics) {
+ ClearcutLogger.initialize({
+ persistence: new FilePersistence(),
+ logFile: this.#serverArgs.logFile,
+ appVersion: VERSION,
+ clearcutEndpoint: this.#serverArgs.clearcutEndpoint,
+ clearcutForceFlushIntervalMs:
+ this.#serverArgs.clearcutForceFlushIntervalMs,
+ clearcutIncludePidHeader: this.#serverArgs.clearcutIncludePidHeader,
+ });
+ }
+
+ this.server = new SdkMcpServer(
+ {
+ name: 'chrome_devtools',
+ title: 'Chrome DevTools MCP server',
+ version: VERSION,
+ },
+ {capabilities: {logging: {}}},
+ );
+
+ this.server.server.setRequestHandler(SetLevelRequestSchema, () => {
+ return {};
});
+
+ this.server.server.oninitialized = () => {
+ const clientName = this.server.server.getClientVersion()?.name;
+ if (clientName) {
+ ClearcutLogger.get()?.setClientName(clientName);
+ }
+ if (this.server.server.getClientCapabilities()?.roots) {
+ void this.#updateRoots();
+ this.server.server.setNotificationHandler(
+ RootsListChangedNotificationSchema,
+ () => {
+ void this.#updateRoots();
+ },
+ );
+ } else if (!this.#serverArgs.allowUnrestrictedPaths) {
+ console.warn(
+ '[chrome-devtools-mcp] The connecting client did not negotiate the MCP roots ' +
+ 'capability. File-writing tools will be restricted to the OS temp directory. ' +
+ 'To restore the previous unrestricted behavior, start the server with ' +
+ '--allow-unrestricted-paths.',
+ );
+ }
+ };
}
- const server = new McpServer(
- {
- name: 'chrome_devtools',
- title: 'Chrome DevTools MCP server',
- version: VERSION,
- },
- {capabilities: {logging: {}}},
- );
- server.server.setRequestHandler(SetLevelRequestSchema, () => {
- return {};
- });
-
- // Roots are client state rather than browser state, so the last listing stays
- // valid across browser reconnects and only the client can invalidate it, via
- // the `roots/list_changed` notification handled below
- let lastRoots: Root[] | undefined;
-
- // `timeout` is only passed where a tool call is waiting on the result – the
- // background refreshes below block nobody, so bounding them would just discard
- // roots a slow client was about to send
- const updateRoots = async (timeout?: number) => {
- if (!server.server.getClientCapabilities()?.roots) {
+ async connect(transport: Transport): Promise<void> {
+ return await this.server.connect(transport);
+ }
+
+ /**
+ * Closes the MCP connection and disposes internal context/listeners.
+ */
+ async close(): Promise<void> {
+ this.#context?.dispose();
+ this.#context = undefined;
+ await this.server.close();
+ }
+
+ [Symbol.dispose](): void {
+ this.close().catch(() => {
+ // TODO: wire up the logger
+ });
+ }
+
+ async [Symbol.asyncDispose](): Promise<void> {
+ await this.close();
+ }
+
+ static async from(
+ serverArgs: ParsedArguments,
+ options: McpServerOptions = {},
+ ): Promise<McpServer> {
+ const server = new McpServer(serverArgs, options);
+ await server.#init();
+ return server;
+ }
+
+ async #init(): Promise<void> {
+ const tools = createTools(this.#serverArgs);
+ for (const tool of tools) {
+ this.#registerTool(tool);
+ }
+ await loadIssueDescriptions();
+ }
+
+ /**
+ * `timeout` is only passed where a tool call is waiting on the result – the
+ * background refreshes below block nobody, so bounding them would just discard
+ * roots a slow client was about to send
+ */
+ async #updateRoots(timeout?: number): Promise<void> {
+ if (!this.server.server.getClientCapabilities()?.roots) {
return;
}
try {
- const roots = await server.server.request(
+ const roots = await this.server.server.request(
{method: 'roots/list'},
ListRootsResultSchema,
timeout === undefined ? undefined : {timeout},
);
- lastRoots = roots.roots;
- context?.setRoots(lastRoots);
+ this.#lastRoots = roots.roots;
+ this.#context?.setRoots(this.#lastRoots);
} catch (e) {
logger?.('Failed to list roots', e);
}
- };
-
- server.server.oninitialized = () => {
- const clientName = server.server.getClientVersion()?.name;
- if (clientName) {
- ClearcutLogger.get()?.setClientName(clientName);
- }
- if (server.server.getClientCapabilities()?.roots) {
- void updateRoots();
- server.server.setNotificationHandler(
- RootsListChangedNotificationSchema,
- () => {
- void updateRoots();
- },
- );
- } else if (!serverArgs.allowUnrestrictedPaths) {
- console.warn(
- '[chrome-devtools-mcp] The connecting client did not negotiate the MCP roots ' +
- 'capability. File-writing tools will be restricted to the OS temp directory. ' +
- 'To restore the previous unrestricted behavior, start the server with ' +
- '--allow-unrestricted-paths.',
- );
- }
- };
+ }
- let context: McpContext;
- async function getContext(): Promise<McpContext> {
- const chromeArgs: string[] = (serverArgs.chromeArg ?? []).map(String);
+ async #getContext(): Promise<McpContext> {
+ const chromeArgs: string[] = (this.#serverArgs.chromeArg ?? []).map(String);
const ignoreDefaultChromeArgs: string[] = (
- serverArgs.ignoreDefaultChromeArg ?? []
+ this.#serverArgs.ignoreDefaultChromeArg ?? []
).map(String);
- if (serverArgs.proxyServer) {
- chromeArgs.push(`--proxy-server=${serverArgs.proxyServer}`);
+ if (this.#serverArgs.proxyServer) {
+ chromeArgs.push(`--proxy-server=${this.#serverArgs.proxyServer}`);
}
- const devtools = serverArgs.experimentalDevtools ?? false;
- const blocklist = serverArgs.blockedUrlPattern
- ? serverArgs.blockedUrlPattern.map(String)
+ const devtools = this.#serverArgs.experimentalDevtools ?? false;
+ const blocklist = this.#serverArgs.blockedUrlPattern
+ ? this.#serverArgs.blockedUrlPattern.map(String)
: undefined;
- const allowlist = serverArgs.allowedUrlPattern
- ? serverArgs.allowedUrlPattern.map(String)
+ const allowlist = this.#serverArgs.allowedUrlPattern
+ ? this.#serverArgs.allowedUrlPattern.map(String)
: undefined;
+ const channel = this.#serverArgs.channel as Channel | undefined;
+
const browser =
- serverArgs.browserUrl || serverArgs.wsEndpoint || serverArgs.autoConnect
+ this.#serverArgs.browserUrl ||
+ this.#serverArgs.wsEndpoint ||
+ this.#serverArgs.autoConnect
? await ensureBrowserConnected({
- browserURL: serverArgs.browserUrl,
- wsEndpoint: serverArgs.wsEndpoint,
- wsHeaders: serverArgs.wsHeaders,
+ browserURL: this.#serverArgs.browserUrl,
+ wsEndpoint: this.#serverArgs.wsEndpoint,
+ wsHeaders: this.#serverArgs.wsHeaders,
// Important: only pass channel, if autoConnect is true.
- channel: serverArgs.autoConnect
- ? (serverArgs.channel as Channel)
- : undefined,
- userDataDir: serverArgs.userDataDir,
+ channel: this.#serverArgs.autoConnect ? channel : undefined,
+ userDataDir: this.#serverArgs.userDataDir,
devtools,
blocklist,
allowlist,
})
: await ensureBrowserLaunched({
- headless: serverArgs.headless,
- executablePath: serverArgs.executablePath,
- channel: serverArgs.channel as Channel,
- isolated: serverArgs.isolated ?? false,
- userDataDir: serverArgs.userDataDir,
- logFile: options.logFile,
- viewport: serverArgs.viewport,
+ headless: this.#serverArgs.headless,
+ executablePath: this.#serverArgs.executablePath,
+ channel,
+ isolated: this.#serverArgs.isolated ?? false,
+ userDataDir: this.#serverArgs.userDataDir,
+ logFile: this.#options.logFile,
+ viewport: this.#serverArgs.viewport,
chromeArgs,
ignoreDefaultChromeArgs,
- acceptInsecureCerts: serverArgs.acceptInsecureCerts,
+ acceptInsecureCerts: this.#serverArgs.acceptInsecureCerts,
devtools,
- enableExtensions: serverArgs.categoryExtensions,
- viaCli: serverArgs.viaCli,
+ enableExtensions: this.#serverArgs.categoryExtensions,
+ viaCli: this.#serverArgs.viaCli,
blocklist,
allowlist,
});
- if (context?.browser !== browser) {
- context?.dispose();
- context = await McpContext.from(browser, logger, {
+ if (this.#context?.browser !== browser) {
+ this.#context?.dispose();
+ this.#context = await McpContext.from(browser, logger, {
experimentalDevToolsDebugging: devtools,
- experimentalIncludeAllPages: serverArgs.experimentalIncludeAllPages,
- performanceCrux: serverArgs.performanceCrux,
+ experimentalIncludeAllPages:
+ this.#serverArgs.experimentalIncludeAllPages,
+ performanceCrux: this.#serverArgs.performanceCrux,
allowList: allowlist,
blocklist: blocklist,
- allowUnrestrictedPaths: serverArgs.allowUnrestrictedPaths,
+ allowUnrestrictedPaths: this.#serverArgs.allowUnrestrictedPaths,
// Surfaces a one-time note in the next response after a reconnect.
- reconnected: context !== undefined,
+ reconnected: this.#context !== undefined,
});
- if (lastRoots === undefined) {
+ if (this.#lastRoots === undefined) {
// Nothing listed yet, so this call has to wait – bounded, since it is
// holding the tool mutex, and a later background refresh still lands
- await updateRoots(ROOTS_REQUEST_TIMEOUT);
+ await this.#updateRoots(ROOTS_REQUEST_TIMEOUT);
} else {
// Carry the known roots over and refresh out of band, so a reconnect
// never pays for a client round-trip
- context.setRoots(lastRoots);
- void updateRoots();
+ this.#context.setRoots(this.#lastRoots);
+ void this.#updateRoots();
}
}
- return context;
+ return this.#context;
}
- const toolMutex = new Mutex();
-
- function registerTool(tool: ToolDefinition | DefinedPageTool): void {
+ #registerTool(tool: ToolDefinition | DefinedPageTool): void {
const toolHandler = new ToolHandler(
tool,
- serverArgs,
- getContext,
- toolMutex,
+ this.#serverArgs,
+ () => this.#getContext(),
+ this.#toolMutex,
);
if (!toolHandler.shouldRegister) {
return;
}
- server.registerTool(
+ this.server.registerTool(
tool.name,
{
description: tool.description,
@@ -221,15 +282,21 @@ export async function createMcpServer(
},
);
}
+}
- const tools = createTools(serverArgs);
- for (const tool of tools) {
- registerTool(tool);
- }
-
- await loadIssueDescriptions();
-
- return {server};
+/**
+ * Creates and initializes a Chrome DevTools MCP server instance.
+ *
+ * Maintained as a public API for backwards compatibility because external
+ * consumers and integrations rely on `createMcpServer()`. For new code,
+ * prefer using `McpServer.from(serverArgs, options)`.
+ */
+export async function createMcpServer(
+ serverArgs: ParsedArguments,
+ options: McpServerOptions = {},
+): Promise<{server: SdkMcpServer}> {
+ const server = await McpServer.from(serverArgs, options);
+ return {server: server.server};
}
export const logDisclaimers = (args: ParsedArguments) => {
diff --git a/src/third_party/index.ts b/src/third_party/index.ts
index b7597df2..dfb779ac 100644
--- a/src/third_party/index.ts
+++ b/src/third_party/index.ts
@@ -22,6 +22,7 @@ export {type ShapeOutput} from '@modelcontextprotocol/sdk/server/zod-compat.js';
export {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
export {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';
export {Client} from '@modelcontextprotocol/sdk/client/index.js';
+export type {Transport} from '@modelcontextprotocol/sdk/shared/transport.js';
export {
type CallToolResult,
SetLevelRequestSchema,