opera-devtools-mcp 0.2.3 → 0.3.0

package/build/src/SlimMcpResponse.js

@@ -5,7 +5,7 @@
  */
 import { McpResponse } from './McpResponse.js';
 export class SlimMcpResponse extends McpResponse {
-    async handle(_toolName, _context) {
+    async handle(_context) {
         const text = {
             type: 'text',
             text: this.responseLines.join('\n'),

package/build/src/TextSnapshot.js

@@ -3,7 +3,59 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { logger } from './logger.js';
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { logger } from './utils/logger.js';
 export class TextSnapshot {
     static nextSnapshotId = 1;
     static resetCounter() {
@@ -88,7 +140,7 @@ export class TextSnapshot {
         const data = options.devtoolsData ?? (await page.getDevToolsData());
         if (data?.cdpBackendNodeId) {
             snapshot.hasSelectedElement = true;
-            snapshot.selectedElementUid = page.resolveCdpElementId(data.cdpBackendNodeId);
+            snapshot.selectedElementUid = snapshot.resolveCdpElementId(data.cdpBackendNodeId);
         }
         // Clean up unique IDs that we did not see anymore.
         for (const key of uniqueBackendNodeIdToMcpId.keys()) {
@@ -98,6 +150,24 @@ export class TextSnapshot {
         }
         return snapshot;
     }
+    resolveCdpElementId(cdpBackendNodeId) {
+        if (!cdpBackendNodeId) {
+            logger?.('no cdpBackendNodeId');
+            return;
+        }
+        // TODO: index by backendNodeId instead.
+        const queue = [this.root];
+        while (queue.length) {
+            const current = queue.pop();
+            if (current.backendNodeId === cdpBackendNodeId) {
+                return current.id;
+            }
+            for (const child of current.children) {
+                queue.push(child);
+            }
+        }
+        return;
+    }
     // ExtraHandles represent DOM nodes which might not be part of the accessibility tree, e.g. DOM nodes
     // returned by third-party developer tools. We insert them into the tree by finding the closest ancestor
     // in the tree and inserting the node as a child. The ancestor's child nodes are re-parented if necessary.
@@ -135,28 +205,37 @@ export class TextSnapshot {
             return extraNode;
         };
         const findAncestorNode = async (handle) => {
-            let ancestorHandle = await handle.evaluateHandle(el => el.parentElement);
-            while (ancestorHandle) {
-                const ancestorElement = ancestorHandle.asElement();
-                if (!ancestorElement) {
-                    await ancestorHandle.dispose();
-                    return null;
-                }
-                const ancestorBackendId = await ancestorElement.backendNodeId();
-                if (ancestorBackendId) {
-                    const ancestorNode = idToNode
-                        .values()
-                        .find(node => node.backendNodeId === ancestorBackendId);
-                    if (ancestorNode) {
-                        await ancestorHandle.dispose();
-                        return ancestorNode;
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                let ancestorHandle = await handle.evaluateHandle(el => el.parentElement);
+                const stack = __addDisposableResource(env_1, new DisposableStack(), false);
+                while (ancestorHandle) {
+                    stack.use(ancestorHandle);
+                    const ancestorElement = ancestorHandle.asElement();
+                    if (!ancestorElement) {
+                        return null;
                     }
+                    const ancestorBackendId = await ancestorElement.backendNodeId();
+                    if (ancestorBackendId) {
+                        const ancestorNode = idToNode
+                            .values()
+                            .find(node => node.backendNodeId === ancestorBackendId);
+                        if (ancestorNode) {
+                            return ancestorNode;
+                        }
+                    }
+                    const nextHandle = await ancestorElement.evaluateHandle(el => el.parentElement);
+                    ancestorHandle = nextHandle;
                 }
-                const nextHandle = await ancestorElement.evaluateHandle(el => el.parentElement);
-                await ancestorHandle.dispose();
-                ancestorHandle = nextHandle;
+                return null;
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
+            }
+            finally {
+                __disposeResources(env_1);
             }
-            return null;
         };
         const findDescendantNodes = async (backendNodeId) => {
             const descendantIds = new Set();
@@ -186,7 +265,7 @@ export class TextSnapshot {
                 }
             }
             catch (e) {
-                logger(`Failed to collect descendants for backend node ${backendNodeId}`, e);
+                logger?.(`Failed to collect descendants for backend node ${backendNodeId}`, e);
             }
             return descendantIds;
         };

package/build/src/ToolHandler.js

@@ -2,14 +2,22 @@
  * @license
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
+ *
+ * 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.
  */
-import { logger } from './logger.js';
 import { McpResponse } from './McpResponse.js';
+import { CLI_BIN_NAME } from './opera/branding.js';
 import { SlimMcpResponse } from './SlimMcpResponse.js';
 import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
-import { bucketizeLatency } from './telemetry/metricUtils.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 { pageIdSchema } from './tools/ToolDefinition.js';
+import { logger } from './utils/logger.js';
+import { fileURLToPath } from 'node:url';
+import { isLocalhost } from './utils/url.js';
 export function buildFlag(category) {
     return `category${category.charAt(0).toUpperCase() + category.slice(1)}`;
 }
@@ -17,7 +25,7 @@ function buildDisabledMessage(toolName, flag, categoryLabel) {
     const reason = categoryLabel
         ? `is in category ${categoryLabel} which`
         : `requires experimental feature ${flag} and`;
-    return `Tool ${toolName} ${reason} is currently disabled. Enable it by running chrome-devtools start ${flag}=true. For more information check the README.`;
+    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);
@@ -70,19 +78,89 @@ function getToolStatusInfo(tool, serverArgs) {
 function isPageScopedTool(tool) {
     return 'pageScoped' in tool && tool.pageScoped === true;
 }
+function formatArgumentNames(names) {
+    return names.map(name => `"${name}"`).join(', ');
+}
+function buildUnknownArgumentsMessage(toolName, unknownArgumentNames, expectedArgumentNames) {
+    const unknownLabel = unknownArgumentNames.length === 1 ? 'argument' : 'arguments';
+    const expectedArguments = expectedArgumentNames.length
+        ? `Expected arguments: ${formatArgumentNames(expectedArgumentNames)}.`
+        : 'This tool does not accept any arguments.';
+    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];
+    }
+    if (Array.isArray(value)) {
+        return value.filter(item => typeof item === 'string');
+    }
+    return [];
+}
+function isLocalBrowser(context) {
+    if (context.browser.process()) {
+        return true;
+    }
+    const wsEndpoint = context.browser.wsEndpoint();
+    if (wsEndpoint && isLocalhost(wsEndpoint)) {
+        return true;
+    }
+    return false;
+}
+function shouldValidateFile(option, isLocal) {
+    if (option === true) {
+        return true;
+    }
+    if (typeof option === 'object' && option !== null) {
+        if (isLocal) {
+            return Boolean(option.local);
+        }
+        return Boolean(option.remote);
+    }
+    return false;
+}
+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);
+            }
+            else if (['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)) {
+                continue;
+            }
+        }
+        catch {
+            // Suppress parsing errors for regular file paths.
+        }
+        await context.validatePath(filePath);
+    }
+}
 export class ToolHandler {
     tool;
     serverArgs;
     getContext;
     toolMutex;
+    hooks;
     inputSchema;
+    registeredInputSchema;
     shouldRegister;
     disabledReason;
-    constructor(tool, serverArgs, getContext, toolMutex) {
+    constructor(tool, serverArgs, getContext, toolMutex, hooks) {
         this.tool = tool;
         this.serverArgs = serverArgs;
         this.getContext = getContext;
         this.toolMutex = toolMutex;
+        this.hooks = hooks;
         const { disabled, reason } = getToolStatusInfo(tool, serverArgs);
         this.disabledReason = reason;
         this.shouldRegister = !(disabled && !serverArgs.viaCli);
@@ -91,10 +169,14 @@ export class ToolHandler {
                 tool.pageScoped &&
                 serverArgs.experimentalPageIdRouting &&
                 !serverArgs.slim
-                ? { ...tool.schema, ...pageIdSchema }
+                ? { ...pageIdSchema, ...tool.schema }
                 : tool.schema;
+        this.registeredInputSchema = zod.object(this.inputSchema).passthrough();
     }
-    async handle(params) {
+    unknownArgumentNames(params) {
+        return Object.keys(params).filter(key => !Object.hasOwn(this.inputSchema, key));
+    }
+    async handle(params, extra) {
         if (this.disabledReason) {
             return {
                 content: [
@@ -106,26 +188,49 @@ export class ToolHandler {
                 isError: true,
             };
         }
-        const guard = await this.toolMutex.acquire();
+        const unknownArgumentNames = this.unknownArgumentNames(params);
+        if (unknownArgumentNames.length) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: buildUnknownArgumentsMessage(this.tool.name, unknownArgumentNames, Object.keys(this.inputSchema)),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const guard = this.hooks?.bypassMutex(this.tool)
+            ? undefined
+            : await this.toolMutex.acquire();
         const startTime = Date.now();
         let success = false;
+        let devToolsData;
+        let pageUrl;
         try {
-            logger(`${this.tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+            logger?.(`${this.tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+            await this.hooks?.beforeInvoke(this.tool);
             const context = await this.getContext();
-            logger(`${this.tool.name} context: resolved`);
-            await context.detectOpenDevToolsWindows();
+            logger?.(`${this.tool.name} context: resolved`);
+            const logCallback = this.hooks?.makeLogCallback(extra);
             const response = this.serverArgs.slim
-                ? new SlimMcpResponse(this.serverArgs)
-                : new McpResponse(this.serverArgs);
+                ? new SlimMcpResponse(this.serverArgs, logCallback)
+                : new McpResponse(this.serverArgs, logCallback);
             response.setRedactNetworkHeaders(this.serverArgs.redactNetworkHeaders);
+            if (context.consumeReconnectNotice()) {
+                response.setReconnectNotice();
+            }
+            let page;
             try {
+                await validateToolFiles(this.tool, params, context);
                 if (isPageScopedTool(this.tool)) {
                     const pageId = typeof params.pageId === 'number' ? params.pageId : undefined;
-                    const page = this.serverArgs.experimentalPageIdRouting &&
-                        pageId !== undefined &&
-                        !this.serverArgs.slim
-                        ? context.getPageById(pageId)
-                        : context.getSelectedMcpPage();
+                    page =
+                        this.serverArgs.experimentalPageIdRouting &&
+                            pageId !== undefined &&
+                            !this.serverArgs.slim
+                            ? context.getPageById(pageId)
+                            : context.getSelectedMcpPage();
                     response.setPage(page);
                     if (this.tool.blockedByDialog) {
                         page.throwIfDialogOpen();
@@ -133,18 +238,33 @@ export class ToolHandler {
                     await this.tool.handler({
                         params,
                         page,
+                        signal: extra?.signal,
                     }, response, context);
                 }
                 else {
                     await this.tool.handler({
                         params,
+                        signal: extra?.signal,
                     }, response, context);
                 }
             }
             catch (err) {
                 response.setError(err);
             }
-            const { content, structuredContent } = await response.handle(this.tool.name, context);
+            devToolsData = await context.getDevToolsData(page);
+            const targetPage = page ?? context.getSelectedMcpPage();
+            if (targetPage?.pptrPage?.isClosed() === false) {
+                pageUrl = targetPage.pptrPage.url();
+            }
+            // Resolve data format: --experimentalDataFormat takes precedence, fall back to legacy --experimentalToonFormat
+            let dataFormat = 'default';
+            if (this.serverArgs.experimentalDataFormat) {
+                dataFormat = this.serverArgs.experimentalDataFormat;
+            }
+            else if (this.serverArgs.experimentalToonFormat) {
+                dataFormat = 'toon';
+            }
+            const { content, structuredContent } = await response.handle(context, dataFormat);
             const result = {
                 content,
             };
@@ -158,7 +278,7 @@ export class ToolHandler {
             return result;
         }
         catch (err) {
-            logger(`${this.tool.name} error:`, err, err?.stack);
+            logger?.(`${this.tool.name} error:`, err, err?.stack);
             let errorText = err && 'message' in err ? err.message : String(err);
             if ('cause' in err && err.cause) {
                 errorText += `\nCause: ${err.cause.message}`;
@@ -174,14 +294,16 @@ export class ToolHandler {
             };
         }
         finally {
+            const context = buildContext(devToolsData, pageUrl);
             void ClearcutLogger.get()?.logToolInvocation({
                 toolName: this.tool.name,
                 params,
                 schema: this.inputSchema,
                 success,
                 latencyMs: bucketizeLatency(Date.now() - startTime),
+                context,
             });
-            guard.dispose();
+            guard?.[Symbol.dispose]();
         }
     }
 }

package/build/src/bin/check-latest-version.js

@@ -5,13 +5,39 @@
  *
  * Modified by Opera Software AS.
  */
+import { execSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
+import { PACKAGE_NAME } from '../opera/branding.js';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+function getRegistry() {
+    // Use the user's configured npm registry so update checks work behind
+    // corporate proxies and private registries. `npm config get registry`
+    // honors .npmrc files at every scope and respects npm_config_registry,
+    // so it covers direct CLI invocations as well as `npx` / `npm run`.
+    try {
+        const registry = execSync('npm config get registry', {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+            windowsHide: true,
+        })
+            .trim()
+            .replace(/\/$/, '');
+        if (registry && registry !== 'undefined' && /^https?:\/\//.test(registry)) {
+            return registry;
+        }
+    }
+    catch {
+        // npm not on PATH or other errors, fall back to default.
+    }
+    return DEFAULT_REGISTRY;
+}
 const cachePath = process.argv[2];
 if (cachePath) {
     try {
-        const response = await fetch('https://registry.npmjs.org/opera-devtools-mcp/latest');
+        const response = await fetch(`${getRegistry()}/${PACKAGE_NAME}/latest`);
         const data = response.ok ? await response.json() : null;
         if (data &&
             typeof data === 'object' &&