opera-devtools-mcp 0.6.1 → 0.8.0

package/build/src/daemon/daemon.js

@@ -4,11 +4,17 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import fs, { constants, openSync, writeSync, closeSync } from 'node:fs';
+import fs, { constants, writeSync, closeSync } from 'node:fs';
 import { createServer } from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
+import { claimPidFile } from '../opera/daemonPidFile.js';
+import { installShutdownHandlers, recordShutdownReason, } from '../opera/daemonShutdown.js';
+import { dispatchSocketMessage, reportStartupFailure, } from '../opera/daemonSocket.js';
+import { attachLogForwarding } from '../opera/daemonStreaming.js';
+import { callDaemonTool } from '../opera/daemonToolCall.js';
+import { superviseMcpServer } from '../opera/mcpServerSupervisor.js';
 import { Client, PipeTransport, StdioClientTransport, } from '../third_party/index.js';
 import { logger, puppeteerLogger } from '../utils/logger.js';
 import { VERSION } from '../version.js';
@@ -54,16 +60,11 @@ catch (err) {
 }
 let fd = -1;
 try {
-    // Open the file with flags to:
-    // - O_WRONLY: Write-only
-    // - O_CREAT: Create if it doesn't exist
-    // - O_TRUNC: Truncate to zero length if it exists
-    // - O_NOFOLLOW: DO NOT follow symlinks.
-    // - 0o600: Permissions: read/write for owner, no permissions for others.
-    fd = openSync(pidFilePath, constants.O_WRONLY |
-        constants.O_CREAT |
-        constants.O_TRUNC |
-        constants.O_NOFOLLOW, 0o600);
+    // The claim is `O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW` — write only,
+    // create if absent, fail if another daemon owns it, never follow a symlink —
+    // at 0o600. See `opera/daemonPidFile.ts` for why it is not upstream's
+    // `O_TRUNC`.
+    fd = claimPidFile(sessionId);
     writeSync(fd, process.pid.toString());
 }
 catch (err) {
@@ -88,33 +89,54 @@ const mcpServerArgs = process.argv.slice(2);
 let mcpClient = null;
 let mcpTransport = null;
 let server = null;
+/** Set once `listen` succeeds, so a later failure knows it owns the socket. */
+let bound = false;
+/** Brings the MCP server back when its stdio child dies; see the module. */
+const mcpSupervisor = superviseMcpServer({
+    sessionId,
+    connect: setupMCPClient,
+    handles: () => ({ client: mcpClient, transport: mcpTransport }),
+    giveUp: () => cleanup(1),
+});
 async function setupMCPClient() {
     console.log('Setting up MCP client connection...');
     // Create stdio transport for chrome-devtools-mcp
-    mcpTransport = new StdioClientTransport({
+    const transport = new StdioClientTransport({
         command: process.execPath,
         args: [INDEX_SCRIPT_PATH, ...mcpServerArgs],
         env: process.env,
     });
+    mcpTransport = transport;
     mcpClient = new Client({
         name: DAEMON_CLIENT_NAME,
         version: VERSION,
     }, {
         capabilities: {},
     });
-    await mcpClient.connect(mcpTransport);
+    // Set onclose BEFORE connect: the SDK's Protocol.connect() captures the
+    // transport's existing onclose and wraps it. Setting it after connect
+    // overwrites that wrapper, so _onclose() never runs and pending callTool
+    // requests hang forever when the MCP server dies. The callback carries the
+    // transport it belongs to, so a respawn can tell a server it replaced from the
+    // one it is watching.
+    transport.onclose = () => mcpSupervisor.onTransportClosed(transport);
+    await mcpClient.connect(transport);
+    // Opera AI tools stream their output as `notifications/message` chunks; the
+    // socket protocol carries them to the CLI. See `opera/daemonStreaming.ts`.
+    attachLogForwarding(mcpClient);
     console.log('MCP client connected');
 }
-async function handleRequest(msg) {
+async function handleRequest(msg, streamToken) {
     try {
         if (msg.method === 'invoke_tool') {
             if (!mcpClient) {
                 throw new Error('MCP client not initialized');
             }
             const { tool, args } = msg;
-            const result = (await mcpClient.callTool({
-                name: tool,
-                arguments: args || {},
+            const result = (await callDaemonTool(mcpClient, {
+                tool,
+                args,
+                streamToken,
             }));
             return {
                 success: true,
@@ -126,7 +148,7 @@ async function handleRequest(msg) {
             await started;
             // Trigger cleanup asynchronously.
             setImmediate(() => {
-                void cleanup();
+                void cleanup(0, 'stopped by request');
             });
             return {
                 success: true,
@@ -177,7 +199,7 @@ async function startSocketServer() {
             const transport = new PipeTransport(socket, socket, puppeteerLogger);
             transport.onmessage = async (message) => {
                 logger?.('onmessage', message);
-                const response = await handleRequest(JSON.parse(message));
+                const response = await dispatchSocketMessage(message, transport, handleRequest);
                 transport.send(JSON.stringify(response));
                 socket.end();
             };
@@ -190,6 +212,7 @@ async function startSocketServer() {
             readableAll: false,
             writableAll: false,
         }, async () => {
+            bound = true;
             console.log(`Daemon server listening on ${socketPath}`);
             try {
                 // Setup MCP client
@@ -206,7 +229,14 @@ async function startSocketServer() {
         });
     });
 }
-async function cleanup(exitCode = 0) {
+async function cleanup(exitCode = 0, reason) {
+    // The reason is the diagnostic, so it goes first: `recordShutdownReason` is
+    // best-effort, and nothing else in this teardown should be able to cost us it.
+    recordShutdownReason(sessionId, reason);
+    // Then stop supervising. Closing the client below closes the transport, which
+    // would otherwise land in the respawn path and spawn a replacement server
+    // while this teardown is running.
+    mcpSupervisor.stop();
     console.log('Cleaning up daemon...');
     try {
         await mcpClient?.close();
@@ -239,28 +269,21 @@ async function cleanup(exitCode = 0) {
     }
     process.exit(exitCode);
 }
-// Handle shutdown signals
-process.on('SIGTERM', () => {
-    void cleanup();
-});
-process.on('SIGINT', () => {
-    void cleanup();
-});
-process.on('SIGHUP', () => {
-    void cleanup();
-});
-// Handle uncaught errors
-process.on('uncaughtException', error => {
-    logger?.('Uncaught exception:', error);
-    void cleanup(1);
-});
-process.on('unhandledRejection', error => {
-    logger?.('Unhandled rejection:', error);
-    void cleanup(1);
+// The shutdown wiring — three signals and the two uncaught-error handlers, each
+// naming itself in the reason the CLI reports — lives in
+// `opera/daemonShutdown.ts`. Every path that reaches it records why it left, so
+// "left no reason behind" means only what it says: a SIGKILL or the OOM killer.
+installShutdownHandlers({
+    onSignal: reason => cleanup(0, reason),
+    onException: reason => cleanup(1, reason),
 });
 // Start the server
 const started = startSocketServer().catch(error => {
     logger?.('Failed to start daemon server:', error);
-    void cleanup(1);
+    void reportStartupFailure(error, {
+        socketBound: bound,
+        sessionId,
+        teardown: reason => cleanup(1, reason),
+    });
 });
 //# sourceMappingURL=daemon.js.map

package/build/src/daemon/utils.js

@@ -110,6 +110,12 @@ export function serializeArgs(options, argv) {
             continue;
         }
         const value = argv[key];
+        const option = options[key];
+        // Yargs reuses the option `default` object; skip it so the daemon parser
+        // still sees the original default (needed for filesystemRoot identity).
+        if (option !== undefined && value === option.default) {
+            continue;
+        }
         const kebabKey = key.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
         if (typeof value === 'boolean') {
             if (value) {

package/build/src/devtools/DevtoolsUtils.js

@@ -19,6 +19,11 @@ export function overrideDevToolsGlobals({ loadResource, }) {
     DevTools.Host.InspectorFrontendHost.installInspectorFrontendHost(new McpHostBindingAdapter(loadResource));
     // DevTools CDP errors can get noisy.
     DevTools.ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
+    const noopAgentCommand = () => {
+        return Promise.resolve({
+            getError: () => undefined,
+        });
+    };
     // Stub out Network emulation commands on the DevTools Agent prototype globally.
     // This prevents the DevTools Frontend from ever resetting/clearing Puppeteer's
     // active network blocking/throttling rules during target setup or session lifetime.
@@ -36,41 +41,37 @@ export function overrideDevToolsGlobals({ loadResource, }) {
             enumerable: true,
         });
         Object.defineProperty(networkAgentPrototype, 'invoke_overrideNetworkState', {
-            value: () => {
-                return Promise.resolve({
-                    getError: () => undefined,
-                });
-            },
+            value: noopAgentCommand,
             writable: true,
             configurable: true,
             enumerable: true,
         });
         Object.defineProperty(networkAgentPrototype, 'invoke_enable', {
-            value: () => {
-                return Promise.resolve({
-                    getError: () => undefined,
-                });
-            },
+            value: noopAgentCommand,
             writable: true,
             configurable: true,
             enumerable: true,
         });
         Object.defineProperty(networkAgentPrototype, 'invoke_disable', {
-            value: () => {
-                return Promise.resolve({
-                    getError: () => undefined,
-                });
-            },
+            value: noopAgentCommand,
             writable: true,
             configurable: true,
             enumerable: true,
         });
         Object.defineProperty(networkAgentPrototype, 'invoke_setBlockedURLs', {
-            value: () => {
-                return Promise.resolve({
-                    getError: () => undefined,
-                });
-            },
+            value: noopAgentCommand,
+            writable: true,
+            configurable: true,
+            enumerable: true,
+        });
+    }
+    // Puppeteer already collects issues from its own Audits subscription. Avoid
+    // enabling the DevTools Frontend's redundant subscription, which can replay
+    // a large retained issue backlog and delay unrelated page work.
+    const auditsAgentPrototype = DevTools.ProtocolClient.InspectorBackend.inspectorBackend.agentPrototypes.get('Audits');
+    if (auditsAgentPrototype) {
+        Object.defineProperty(auditsAgentPrototype, 'invoke_enable', {
+            value: noopAgentCommand,
             writable: true,
             configurable: true,
             enumerable: true,
@@ -91,7 +92,7 @@ export function overrideDevToolsGlobals({ loadResource, }) {
             .resolve('../third_party/devtools-formatter-worker.js'),
     });
 }
-export async function createTargetUniverse(session) {
+export async function createTargetUniverse(session, options) {
     const settingStorage = new DevTools.Common.Settings.SettingsStorage({});
     const universe = new DevTools.Foundation.Universe.Universe({
         settingsCreationOptions: {
@@ -105,6 +106,11 @@ export async function createTargetUniverse(session) {
         inspectorFrontendHost: DevTools.Host.InspectorFrontendHost.InspectorFrontendHostInstance,
         supportsEmulation: false,
     });
+    const sourceMaps = options?.sourceMaps ?? true;
+    const jsSourceMapsSetting = universe.settings.resolve(DevTools.SDKSettings.jsSourceMapsEnabledSettingDescriptor);
+    jsSourceMapsSetting.set(sourceMaps);
+    const cssSourceMapsSetting = universe.settings.resolve(DevTools.SDKSettings.cssSourceMapsEnabledSettingDescriptor);
+    cssSourceMapsSetting.set(sourceMaps);
     const setting = universe.settings.resolve(DevTools.SourceMapManager.lazyLoadingSettingDescriptor);
     setting.set(true);
     const skipAllPausesSetting = universe.settings.resolve(DevTools.skipAllPausesSettingDescriptor);

package/build/src/formatters/NetworkFormatter.js

@@ -6,6 +6,7 @@
 import { isUtf8 } from 'node:buffer';
 import { DevTools, } from '../third_party/index.js';
 const BODY_CONTEXT_SIZE_LIMIT = 10000;
+const URL_CONTEXT_SIZE_LIMIT = 255;
 export class NetworkFormatter {
     #request;
     #options;
@@ -178,8 +179,10 @@ function getSizeLimitedString(text, sizeLimit) {
     return text;
 }
 function convertNetworkRequestConciseToString(data) {
-    // TODO truncate the URL
-    return `reqid=${data.requestId} ${data.method} ${data.url} [${data.status}]${data.selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
+    // Long URLs (e.g., data: URLs) bloat the concise list output. The full URL
+    // remains available via the detailed view and the structured content.
+    const url = getSizeLimitedString(data.url, URL_CONTEXT_SIZE_LIMIT);
+    return `reqid=${data.requestId} ${data.method} ${url} [${data.status}]${data.selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
 }
 function formatHeaders(headers) {
     const response = [];

package/build/src/index.js

@@ -5,21 +5,22 @@
  *
  * Modified by Opera Software AS.
  */
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
 import { loadIssueDescriptions } from './devtools/issueDescriptions.js';
 import { McpContext } from './McpContext.js';
 import { BROWSER_EXPOSURE_DISCLAIMER, showUsageStatisticsDisclaimer, } from './opera/policy.js';
-import { createOperaToolHooks } from './opera/toolHandlerHooks.js';
 import { buildLaunchOptions } from './opera/browserLaunch.js';
+import { createOperaToolHooks, } from './opera/toolHandlerHooks.js';
 import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
 import { FilePersistence } from './telemetry/persistence.js';
-import { McpServer, SetLevelRequestSchema, ListRootsResultSchema, RootsListChangedNotificationSchema, } from './third_party/index.js';
+import { McpServer as SdkMcpServer, SetLevelRequestSchema, ListRootsResultSchema, RootsListChangedNotificationSchema, Mutex, puppeteer, } from './third_party/index.js';
 import { ToolHandler } from './ToolHandler.js';
 import { createTools } from './tools/tools.js';
 import { logger } from './utils/logger.js';
-import { Mutex } from './third_party/index.js';
 import { VERSION } from './version.js';
-export { buildFlag } from './ToolHandler.js';
+puppeteer.setFollowSymlinks(false);
 /**
  * Timeout for a `roots/list` that a tool call is waiting on, matching the 5s
  * default used for page operations. `getContext()` awaits it while
@@ -29,84 +30,151 @@ export { buildFlag } from './ToolHandler.js';
  * slow client sends late still land.
  */
 const ROOTS_REQUEST_TIMEOUT = 5_000;
-export async function createMcpServer(serverArgs, options) {
-    // Opera forces `usageStatistics` off in ./opera/policy.ts, so this stays
-    // dormant. Kept identical to upstream so the seam is the policy, not this file.
-    if (serverArgs.usageStatistics) {
-        ClearcutLogger.initialize({
-            persistence: new FilePersistence(),
-            logFile: serverArgs.logFile,
-            appVersion: VERSION,
-            clearcutEndpoint: serverArgs.clearcutEndpoint,
-            clearcutForceFlushIntervalMs: serverArgs.clearcutForceFlushIntervalMs,
-            clearcutIncludePidHeader: serverArgs.clearcutIncludePidHeader,
+export class McpServer {
+    server;
+    #serverArgs;
+    #options;
+    #context;
+    /**
+     * Client roots stay valid across browser reconnects and only the client can
+     * invalidate them through a `roots/list_changed` notification. CLI-configured
+     * roots are read from `#serverArgs` when combining roots.
+     */
+    #lastClientRoots;
+    #toolMutex = new Mutex();
+    #operaHooks;
+    constructor(serverArgs, options = {}) {
+        this.#serverArgs = serverArgs;
+        this.#options = options;
+        this.#operaHooks = createOperaToolHooks({
+            serverArgs: this.#serverArgs,
+            logFile: this.#options.logFile,
+            resetContext: () => {
+                this.#context?.dispose();
+                this.#context = undefined;
+            },
         });
+        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 &&
+                (this.#serverArgs.filesystemRoot ?? []).length === 0) {
+                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.');
+            }
+        };
+    }
+    async connect(transport) {
+        return await this.server.connect(transport);
+    }
+    /**
+     * Closes the MCP connection and disposes internal context/listeners.
+     */
+    async close() {
+        this.#context?.dispose();
+        this.#context = undefined;
+        await this.server.close();
+    }
+    [Symbol.dispose]() {
+        this.close().catch(() => {
+            // TODO: wire up the logger
+        });
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    static async from(serverArgs, options = {}) {
+        const server = new McpServer(serverArgs, options);
+        await server.#init();
+        return server;
+    }
+    async #init() {
+        const tools = createTools(this.#serverArgs);
+        for (const tool of tools) {
+            this.#registerTool(tool);
+        }
+        await loadIssueDescriptions();
     }
-    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;
-    // `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) => {
-        if (!server.server.getClientCapabilities()?.roots) {
+    #combinedRoots() {
+        const configuredRoots = (this.#serverArgs.allowUnrestrictedPaths
+            ? []
+            : (this.#serverArgs.filesystemRoot ?? [])).map(root => {
+            const rootPath = path.resolve(String(root));
+            return {
+                uri: pathToFileURL(rootPath).href,
+                name: path.basename(rootPath) || rootPath,
+            };
+        });
+        if (configuredRoots.length === 0 && this.#lastClientRoots === undefined) {
+            return undefined;
+        }
+        return [...configuredRoots, ...(this.#lastClientRoots ?? [])];
+    }
+    /**
+     * `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) {
+        if (!this.server.server.getClientCapabilities()?.roots) {
             return;
         }
         try {
-            const roots = await server.server.request({ method: 'roots/list' }, ListRootsResultSchema, timeout === undefined ? undefined : { timeout });
-            lastRoots = roots.roots;
-            context?.setRoots(lastRoots);
+            const roots = await this.server.server.request({ method: 'roots/list' }, ListRootsResultSchema, timeout === undefined ? undefined : { timeout });
+            this.#lastClientRoots = roots.roots;
+            this.#context?.setRoots(this.#combinedRoots());
         }
         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;
-    async function getContext() {
-        const devtools = serverArgs.experimentalDevtools ?? false;
-        const blocklist = serverArgs.blockedUrlPattern
-            ? serverArgs.blockedUrlPattern.map(String)
+    }
+    async #getContext() {
+        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 browser = serverArgs.browserUrl || serverArgs.wsEndpoint || serverArgs.autoConnect
+        const channel = this.#serverArgs.channel;
+        const browser = 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
-                    : undefined,
-                userDataDir: serverArgs.userDataDir,
+                channel: this.#serverArgs.autoConnect ? channel : undefined,
+                userDataDir: this.#serverArgs.userDataDir,
                 devtools,
                 blocklist,
                 allowlist,
@@ -114,52 +182,45 @@ export async function createMcpServer(serverArgs, options) {
             : await ensureBrowserLaunched(
             // Pass the already-derived values so the launched browser uses the
             // exact same flags as the connected branch and `McpContext`.
-            buildLaunchOptions(serverArgs, options.logFile, {
+            buildLaunchOptions(this.#serverArgs, this.#options.logFile, {
                 devtools,
                 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,
+                sourceMaps: this.#serverArgs.sourceMaps,
                 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,
+                categoryExtensions: this.#serverArgs.categoryExtensions,
             });
-            if (lastRoots === undefined) {
+            this.#context.setRoots(this.#combinedRoots());
+            if (this.#lastClientRoots === 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();
+                void this.#updateRoots();
             }
         }
-        return context;
+        return this.#context;
     }
-    const operaHooks = createOperaToolHooks({
-        serverArgs,
-        logFile: options.logFile,
-        resetContext: () => {
-            context?.dispose();
-            context = undefined;
-        },
-    });
-    const toolMutex = new Mutex();
-    function registerTool(tool) {
-        const toolHandler = new ToolHandler(tool, serverArgs, getContext, toolMutex, operaHooks);
+    #registerTool(tool) {
+        const toolHandler = new ToolHandler(tool, this.#serverArgs, () => this.#getContext(), this.#toolMutex, this.#operaHooks);
         if (!toolHandler.shouldRegister) {
             return;
         }
-        server.registerTool(tool.name, {
+        this.server.registerTool(tool.name, {
             description: tool.description,
             inputSchema: toolHandler.registeredInputSchema,
             annotations: tool.annotations,
@@ -167,12 +228,17 @@ export async function createMcpServer(serverArgs, options) {
             return await toolHandler.handle(params, extra);
         });
     }
-    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, options = {}) {
+    const server = await McpServer.from(serverArgs, options);
+    return { server: server.server };
 }
 export const logDisclaimers = (args) => {
     console.error(BROWSER_EXPOSURE_DISCLAIMER);

package/build/src/opera/branding.js

@@ -15,8 +15,10 @@
 export const PACKAGE_NAME = 'opera-devtools-mcp';
 /** MCP server binary / daemon app name, also used as `process.title`. */
 export const MCP_BIN_NAME = PACKAGE_NAME;
-/** CLI binary name, e.g. `opera-devtools start`. */
-export const CLI_BIN_NAME = 'opera-devtools';
+/** CLI binary name, e.g. `opera-browser-cli start`. The fork's sole CLI. */
+export const CLI_BIN_NAME = 'opera-browser-cli';
+/** Directory under `$HOME` holding the per-user config file (matches the CLI binary name). */
+export const STATE_DIR_NAME = '.opera-browser-cli';
 /** Human-readable product name used in log lines. */
 export const PRODUCT_NAME = 'Opera DevTools MCP Server';
 /** Public repository, referenced from help text and disclaimers. */