opera-devtools-mcp 0.6.1 → 0.8.0

package/README.md

@@ -10,7 +10,7 @@ control and inspect a live browser. It acts as a Model-Context-Protocol
 DevTools for reliable automation, in-depth debugging, and performance analysis.
 When connected to Opera Neon, it also exposes Opera's built-in AI capabilities.
 
-## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)
+## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md) | [Stress testing](./docs/stress-testing.md)
 
 ## Key features
 

package/build/src/McpContext.js

@@ -15,6 +15,7 @@ import { Locator, } from './third_party/index.js';
 import { listPages } from './tools/pages.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
 import { getTempFilePath, resolveCanonicalPath } from './utils/files.js';
+import { isAllowedUrl } from './utils/url.js';
 // Page ids are handed out from a process-wide counter so they stay unique
 // across all contexts, in particular across browser reconnects. An id issued
 // before a reconnect then fails to resolve instead of hitting an unrelated
@@ -81,6 +82,12 @@ export class McpContext {
     }
     #onTargetCreated = async (target) => {
         try {
+            const url = target.url();
+            if (!isAllowedUrl(url, {
+                categoryExtensions: this.#options.categoryExtensions,
+            })) {
+                return;
+            }
             const page = await target.page();
             if (!page) {
                 return;
@@ -137,28 +144,30 @@ export class McpContext {
     }
     async validatePath(filePath) {
         if (filePath === undefined) {
-            return;
+            return undefined;
+        }
+        let canonicalPath;
+        try {
+            canonicalPath = await resolveCanonicalPath(filePath);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            console.error(`[MCP Context] Error resolving real path for ${filePath}: ${errMsg}`);
+            throw new Error(`Access denied: Cannot resolve base path for ${filePath}.`);
         }
         // If the client never negotiated roots and the operator has explicitly
         // opted into unrestricted access via --allow-unrestricted-paths, restore
         // the previous permissive behavior and skip validation.
         if (this.#roots === undefined && this.#allowUnrestrictedPaths) {
-            return;
+            // Canonical path might not exist yet so we fallback to
+            // path.resolve(filePath). Consumers should not follow symlinks.
+            return canonicalPath || path.resolve(filePath);
         }
         // roots() always returns at least the temp directory, even if the
         // connecting client never negotiated the optional `roots` capability.
         // Path validation must not be skipped just because no workspace roots
         // were configured.
         const roots = this.roots();
-        let canonicalPath;
-        try {
-            canonicalPath = await resolveCanonicalPath(filePath);
-        }
-        catch (err) {
-            const errMsg = err instanceof Error ? err.message : String(err);
-            console.error(`[MCP Context] Error resolving real path for ${filePath}: ${errMsg}`);
-            throw new Error(`Access denied: Cannot resolve base path for ${filePath}.`);
-        }
         let allowed = false;
         const resolvedRoots = await Promise.allSettled(roots.map(async (root) => {
             const rootPathUri = root.uri;
@@ -186,12 +195,12 @@ export class McpContext {
         if (!allowed) {
             throw new Error(`Access denied: path ${filePath} (canonical: ${canonicalPath}) is not within any of the configured workspace roots.`);
         }
+        return canonicalPath || path.resolve(filePath);
     }
     async ensureExtension(filePath, extension) {
-        const resolvedPath = path.resolve(filePath);
-        const currentExtension = path.extname(resolvedPath);
-        const outputPath = `${resolvedPath.slice(0, resolvedPath.length - currentExtension.length)}${extension}`;
-        await this.validatePath(outputPath);
+        const resolved = await this.validatePath(filePath);
+        const currentExtension = path.extname(resolved);
+        const outputPath = `${resolved.slice(0, resolved.length - currentExtension.length)}${extension}`;
         return outputPath;
     }
     async newPage(background, isolatedContextName) {
@@ -202,7 +211,7 @@ export class McpContext {
                 ctx = await this.browser.createBrowserContext();
                 this.#isolatedContexts.set(isolatedContextName, ctx);
             }
-            page = await ctx.newPage();
+            page = await ctx.newPage({ background });
         }
         else {
             page = await this.browser.newPage({ background });
@@ -266,6 +275,21 @@ export class McpContext {
         }
         return page;
     }
+    getSelectedMcpPageUrl(page) {
+        let targetPage = page;
+        if (!targetPage) {
+            try {
+                targetPage = this.getSelectedMcpPage();
+            }
+            catch {
+                return undefined;
+            }
+        }
+        if (targetPage?.pptrPage?.isClosed() === false) {
+            return targetPage.pptrPage.url();
+        }
+        return undefined;
+    }
     async getDevToolsData(page) {
         const targetPage = page ?? this.#selectedPage;
         if (!targetPage) {
@@ -372,6 +396,7 @@ export class McpContext {
                 hasNetworkBlockOrAllowlist: this.#hasNetworkBlockOrAllowlist,
                 isolatedContextName: this.#getBrowserContextToNameMap().get(page.browserContext()),
                 navigationTimeout: this.#options.navigationTimeout,
+                sourceMaps: this.#options.sourceMaps,
             });
             this.#mcpPages.set(page, mcpPage);
             await mcpPage.init();
@@ -409,29 +434,38 @@ export class McpContext {
     }
     async #fetchBrowserPages() {
         const allPages = (await this.browser.pages(this.#options.experimentalIncludeAllPages)).filter(page => {
-            return (this.#options.experimentalDevToolsDebugging ||
-                !page.url().startsWith('devtools://'));
-        });
-        const allTargets = this.browser.targets();
-        const extensionTargets = allTargets.filter(target => {
-            return (target.url().startsWith('chrome-extension://') &&
-                target.type() === 'page');
+            if (!this.#options.experimentalDevToolsDebugging &&
+                page.url().startsWith('devtools://')) {
+                return false;
+            }
+            return isAllowedUrl(page.url(), {
+                categoryExtensions: this.#options.categoryExtensions,
+            });
         });
-        await Promise.allSettled(extensionTargets.map(async (target) => {
-            try {
-                let page = await target.page();
-                if (!page) {
-                    page = await target.asPage();
+        if (this.#options.categoryExtensions) {
+            const allTargets = this.browser.targets();
+            const extensionTargets = allTargets.filter(target => {
+                return (target.url().startsWith('chrome-extension://') &&
+                    target.type() === 'page');
+            });
+            await Promise.allSettled(extensionTargets.map(async (target) => {
+                try {
+                    let page = await target.page();
+                    if (!page) {
+                        page = await target.asPage();
+                    }
+                    this.#extensionPages.set(target, page);
+                    if (page &&
+                        isAllowedUrl(page.url(), { categoryExtensions: true }) &&
+                        !allPages.includes(page)) {
+                        allPages.push(page);
+                    }
                 }
-                this.#extensionPages.set(target, page);
-                if (page && !allPages.includes(page)) {
-                    allPages.push(page);
+                catch (e) {
+                    this.logger?.('Failed to get page for extension target', e);
                 }
-            }
-            catch (e) {
-                this.logger?.('Failed to get page for extension target', e);
-            }
-        }));
+            }));
+        }
         return allPages;
     }
     getExtensionServiceWorkers() {
@@ -441,16 +475,16 @@ export class McpContext {
         return this.#extensionServiceWorkerMap.get(extensionServiceWorker.target);
     }
     async #writeFile(filepath, data) {
-        await this.validatePath(filepath);
+        const resolved = await this.validatePath(filepath);
         try {
-            await fs.mkdir(path.dirname(filepath), { recursive: true });
+            await fs.mkdir(path.dirname(resolved), { recursive: true });
             // 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.
-            await fs.writeFile(filepath, data, {
+            await fs.writeFile(resolved, data, {
                 flag: fs.constants.O_WRONLY |
                     fs.constants.O_CREAT |
                     fs.constants.O_TRUNC |
@@ -515,6 +549,9 @@ export class McpContext {
     async getHeapSnapshotDuplicateStrings(filePath) {
         return await this.#heapSnapshotManager.getDuplicateStrings(filePath);
     }
+    async queryHeapSnapshotObjects(filePath, options) {
+        return await this.#heapSnapshotManager.queryObjects(filePath, options);
+    }
     async getHeapSnapshotStats(filePath) {
         return await this.#heapSnapshotManager.getStats(filePath);
     }
@@ -585,8 +622,8 @@ export class McpContext {
                 return response.text();
             }
             case 'file:': {
-                await this.validatePath(fileURLToPath(url));
-                return await fs.readFile(url, 'utf-8');
+                const resolved = await this.validatePath(fileURLToPath(url));
+                return await fs.readFile(resolved, 'utf-8');
             }
             default:
                 throw new Error(`Unsupported protocol for: ${url}`);

package/build/src/McpPage.js

@@ -139,10 +139,12 @@ export class McpPage {
     #hasNetworkBlockOrAllowlist;
     #locatorClass;
     #navigationTimeout;
+    #sourceMaps;
     constructor(page, id, options) {
         this.#hasNetworkBlockOrAllowlist = options.hasNetworkBlockOrAllowlist;
         this.#locatorClass = options.locatorClass;
         this.#navigationTimeout = options.navigationTimeout ?? NAVIGATION_TIMEOUT;
+        this.#sourceMaps = options.sourceMaps ?? true;
         this.pptrPage = page;
         this.id = id;
         this.isolatedContextName = options.isolatedContextName;
@@ -183,7 +185,9 @@ export class McpPage {
         }
         try {
             const session = await this.pptrPage.createCDPSession();
-            this.#devtoolsUniverse = await createTargetUniverse(session);
+            this.#devtoolsUniverse = await createTargetUniverse(session, {
+                sourceMaps: this.#sourceMaps,
+            });
         }
         catch (e) {
             logger?.('Failed to initialize DevTools universe', e);

package/build/src/ToolHandler.js

@@ -5,71 +5,44 @@
  *
  * Modified by Opera Software AS: optional `hooks` seam (see
  * ./opera/toolHandlerHooks.ts) for mutex bypass, browser relaunch and log
- * streaming. Keep the diff to the three `this.hooks?.` call sites.
+ * streaming, plus one page-resolution call that tolerates a selection the user
+ * closed (see ./opera/pageRecovery.ts). Keep the diff to the three
+ * `this.hooks?.` call sites and that line.
  */
 import { McpResponse } from './McpResponse.js';
 import { CLI_BIN_NAME } from './opera/branding.js';
+import { resolveSelectedPage } from './opera/pageRecovery.js';
 import { SlimMcpResponse } from './SlimMcpResponse.js';
 import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
-import { bucketizeLatency, buildContext } from './telemetry/transformation.js';
 import { zod } from './third_party/index.js';
-import { labels, OFF_BY_DEFAULT_CATEGORIES } from './tools/categories.js';
+import { labels } from './tools/categories.js';
+import { categoryToFlagName } from './config/category-options.js';
 import { pageIdSchema } from './tools/ToolDefinition.js';
 import { logger } from './utils/logger.js';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isLocalhost } from './utils/url.js';
-export function buildFlag(category) {
-    return `category${category.charAt(0).toUpperCase() + category.slice(1)}`;
-}
 function buildDisabledMessage(toolName, flag, categoryLabel) {
     const reason = categoryLabel
         ? `is in category ${categoryLabel} which`
-        : `requires experimental feature ${flag} and`;
+        : `requires ${flag.startsWith('--experimental') ? 'experimental feature' : 'flag'} ${flag} and`;
     return `Tool ${toolName} ${reason} is currently disabled. Enable it by running ${CLI_BIN_NAME} start ${flag}=true. For more information check the README.`;
 }
-function getCategoryStatus(category, serverArgs) {
-    const categoryFlag = buildFlag(category);
-    const flagValue = serverArgs[categoryFlag];
-    const isDisabled = OFF_BY_DEFAULT_CATEGORIES.includes(category)
-        ? !flagValue
-        : flagValue === false;
-    if (isDisabled) {
-        return {
-            categoryFlag,
-            disabled: true,
-        };
-    }
-    return {
-        disabled: false,
-    };
-}
-function getConditionStatus(condition, serverArgs) {
-    if (condition && !serverArgs[condition]) {
-        return { conditionFlag: condition, disabled: true };
-    }
-    return { disabled: false };
-}
 function getToolStatusInfo(tool, serverArgs) {
     const category = tool.annotations.category;
-    const categoryCheck = getCategoryStatus(category, serverArgs);
-    if (category && categoryCheck.disabled) {
-        if (!categoryCheck.categoryFlag) {
-            throw new Error('when the category is disabled there should always be a flag set');
+    if (category) {
+        const flag = categoryToFlagName(category);
+        if (!serverArgs[flag]) {
+            return {
+                disabled: true,
+                reason: buildDisabledMessage(tool.name, `--${flag}`, labels[category]),
+            };
         }
-        return {
-            disabled: true,
-            reason: buildDisabledMessage(tool.name, `--${categoryCheck.categoryFlag}`, labels[category]),
-        };
     }
     for (const condition of tool.annotations.conditions || []) {
-        const conditionCheck = getConditionStatus(condition, serverArgs);
-        if (conditionCheck.disabled) {
-            if (!conditionCheck.conditionFlag) {
-                throw new Error('when the condition is disabled there should always be a flag set');
-            }
+        if (!serverArgs[condition]) {
             return {
                 disabled: true,
-                reason: buildDisabledMessage(tool.name, `--${conditionCheck.conditionFlag}`),
+                reason: buildDisabledMessage(tool.name, `--${condition}`),
             };
         }
     }
@@ -89,14 +62,20 @@ function buildUnknownArgumentsMessage(toolName, unknownArgumentNames, expectedAr
     const correction = unknownArgumentNames.length === 1 ? 'Remove it' : 'Remove them';
     return `Unknown ${unknownLabel} for tool "${toolName}": ${formatArgumentNames(unknownArgumentNames)}. ${expectedArguments} ${correction} and retry.`;
 }
-function extractPaths(value) {
-    if (typeof value === 'string') {
-        return [value];
+async function validateAndResolvePathOrUrl(filePathOrUrl, context) {
+    try {
+        const url = new URL(filePathOrUrl);
+        if (url.protocol === 'file:') {
+            return pathToFileURL(await context.validatePath(fileURLToPath(url))).href;
+        }
+        else if (['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)) {
+            return filePathOrUrl;
+        }
     }
-    if (Array.isArray(value)) {
-        return value.filter(item => typeof item === 'string');
+    catch {
+        // Suppress parsing errors for regular file paths.
     }
-    return [];
+    return await context.validatePath(filePathOrUrl);
 }
 function isLocalBrowser(context) {
     if (context.browser.process()) {
@@ -122,27 +101,25 @@ function shouldValidateFile(option, isLocal) {
 }
 async function validateToolFiles(tool, params, context) {
     const isLocal = isLocalBrowser(context);
-    const pathsOrUrlsToValidate = [];
     for (const [key, option] of Object.entries(tool.verifyFilesSchema)) {
         if (shouldValidateFile(option, isLocal)) {
-            pathsOrUrlsToValidate.push(...extractPaths(params[key]));
-        }
-    }
-    for (const filePathOrUrl of pathsOrUrlsToValidate) {
-        let filePath = filePathOrUrl;
-        try {
-            const url = new URL(filePathOrUrl);
-            if (url.protocol === 'file:') {
-                filePath = fileURLToPath(url);
+            const val = params[key];
+            if (typeof val === 'string') {
+                params[key] = await validateAndResolvePathOrUrl(val, context);
             }
-            else if (['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)) {
-                continue;
+            else if (Array.isArray(val)) {
+                const updated = [];
+                for (const item of val) {
+                    if (typeof item === 'string') {
+                        updated.push(await validateAndResolvePathOrUrl(item, context));
+                    }
+                    else {
+                        throw new Error('Unexpected non-string value as a file path or URL');
+                    }
+                }
+                params[key] = updated;
             }
         }
-        catch {
-            // Suppress parsing errors for regular file paths.
-        }
-        await context.validatePath(filePath);
     }
 }
 export class ToolHandler {
@@ -167,7 +144,7 @@ export class ToolHandler {
         this.inputSchema =
             'pageScoped' in tool &&
                 tool.pageScoped &&
-                serverArgs.experimentalPageIdRouting &&
+                serverArgs.pageIdRouting &&
                 !serverArgs.slim
                 ? { ...pageIdSchema, ...tool.schema }
                 : tool.schema;
@@ -226,11 +203,11 @@ export class ToolHandler {
                 if (isPageScopedTool(this.tool)) {
                     const pageId = typeof params.pageId === 'number' ? params.pageId : undefined;
                     page =
-                        this.serverArgs.experimentalPageIdRouting &&
+                        this.serverArgs.pageIdRouting &&
                             pageId !== undefined &&
                             !this.serverArgs.slim
                             ? context.getPageById(pageId)
-                            : context.getSelectedMcpPage();
+                            : await resolveSelectedPage(context, response);
                     response.setPage(page);
                     if (this.tool.blockedByDialog) {
                         page.throwIfDialogOpen();
@@ -252,10 +229,7 @@ export class ToolHandler {
                 response.setError(err);
             }
             devToolsData = await context.getDevToolsData(page);
-            const targetPage = page ?? context.getSelectedMcpPage();
-            if (targetPage?.pptrPage?.isClosed() === false) {
-                pageUrl = targetPage.pptrPage.url();
-            }
+            pageUrl = context.getSelectedMcpPageUrl(page);
             // Resolve data format: --experimentalDataFormat takes precedence, fall back to legacy --experimentalToonFormat
             let dataFormat = 'default';
             if (this.serverArgs.experimentalDataFormat) {
@@ -294,14 +268,18 @@ export class ToolHandler {
             };
         }
         finally {
-            const context = buildContext(devToolsData, pageUrl);
+            // Before telemetry and the mutex release: the claim `beforeInvoke` took
+            // has to be released even when the invocation failed, or the next Opera
+            // AI tool waits on a browser this one only looks like it is using.
+            this.hooks?.afterInvoke(this.tool);
             void ClearcutLogger.get()?.logToolInvocation({
                 toolName: this.tool.name,
                 params,
                 schema: this.inputSchema,
                 success,
-                latencyMs: bucketizeLatency(Date.now() - startTime),
-                context,
+                latencyMs: Date.now() - startTime,
+                devToolsData,
+                pageUrl,
             });
             guard?.[Symbol.dispose]();
         }

package/build/src/bin/chrome-devtools-mcp-main.js

@@ -8,7 +8,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 { ENV_CRASH_ON_UNCAUGHT, PACKAGE_NAME, PRODUCT_NAME, } from '../opera/branding.js';
 import { enforceTelemetryPolicy } from '../opera/policy.js';
 import { ClearcutLogger } from '../telemetry/ClearcutLogger.js';
@@ -17,7 +17,7 @@ import { StdioServerTransport } from '../third_party/index.js';
 import { checkForUpdates } from '../utils/check-for-updates.js';
 import { logger, saveLogsToFile } from '../utils/logger.js';
 import { VERSION } from '../version.js';
-import { cliOptions, parseArguments } from './chrome-devtools-mcp-cli-options.js';
+import { mcpOptions, parseArguments } from '../config/mcp-options.js';
 await checkForUpdates(`Run \`npm install ${PACKAGE_NAME}@latest\` to update.`);
 export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
@@ -65,7 +65,7 @@ process.on('SIGINT', () => {
 process.on('SIGHUP', () => {
     void shutdown('SIGHUP');
 });
-const { server } = await createMcpServer(args, {
+const server = await McpServer.from(args, {
     logFile,
 });
 const transport = new StdioServerTransport();
@@ -73,5 +73,5 @@ await server.connect(transport);
 logger?.(`${PRODUCT_NAME} connected`);
 logDisclaimers(args);
 void ClearcutLogger.get()?.logDailyActiveIfNeeded();
-void ClearcutLogger.get()?.logServerStart(computeFlagUsage(args, cliOptions));
+void ClearcutLogger.get()?.logServerStart(computeFlagUsage(args, mcpOptions));
 //# sourceMappingURL=chrome-devtools-mcp-main.js.map