opera-devtools-mcp 0.6.1 → 0.8.0

package/build/src/tools/slim/tools.js

@@ -6,6 +6,7 @@
 import { zod } from '../../third_party/index.js';
 import { ToolCategory } from '../categories.js';
 import { definePageTool } from '../ToolDefinition.js';
+import { validateUrl } from '../../utils/url.js';
 export const screenshot = definePageTool({
     name: 'screenshot',
     description: `Takes a screenshot`,
@@ -27,40 +28,46 @@ export const screenshot = definePageTool({
         response.appendResponseLine(filepath);
     },
 });
-export const navigate = definePageTool({
-    name: 'navigate',
-    description: `Loads a URL`,
-    annotations: {
-        category: ToolCategory.NAVIGATION,
-        readOnlyHint: false,
-    },
-    schema: {
-        url: zod.string().describe('URL to navigate to'),
-    },
-    blockedByDialog: false,
-    verifyFilesSchema: {},
-    handler: async (request, response) => {
-        const page = request.page;
-        const options = {
-            timeout: 30_000,
-        };
-        const dialogHandler = (dialog) => {
-            if (dialog.type() === 'beforeunload') {
-                response.appendResponseLine(`Accepted a beforeunload dialog.`);
-                void dialog.accept();
-                // We are not going to report the dialog like regular dialogs.
-                page.clearDialog();
+export const navigate = definePageTool(args => {
+    return {
+        name: 'navigate',
+        description: `Loads a URL`,
+        annotations: {
+            category: ToolCategory.NAVIGATION,
+            readOnlyHint: false,
+        },
+        schema: {
+            url: zod.string().describe('URL to navigate to'),
+        },
+        blockedByDialog: false,
+        verifyFilesSchema: {},
+        handler: async (request, response) => {
+            validateUrl(request.params.url, {
+                javascriptEvaluation: args?.javascriptEvaluation,
+                categoryExtensions: args?.categoryExtensions,
+            });
+            const page = request.page;
+            const options = {
+                timeout: 30_000,
+            };
+            const dialogHandler = (dialog) => {
+                if (dialog.type() === 'beforeunload') {
+                    response.appendResponseLine(`Accepted a beforeunload dialog.`);
+                    void dialog.accept();
+                    // We are not going to report the dialog like regular dialogs.
+                    page.clearDialog();
+                }
+            };
+            page.pptrPage.on('dialog', dialogHandler);
+            try {
+                await page.pptrPage.goto(request.params.url, options);
+                response.appendResponseLine(`Navigated to ${page.pptrPage.url()}.`);
             }
-        };
-        page.pptrPage.on('dialog', dialogHandler);
-        try {
-            await page.pptrPage.goto(request.params.url, options);
-            response.appendResponseLine(`Navigated to ${page.pptrPage.url()}.`);
-        }
-        finally {
-            page.pptrPage.off('dialog', dialogHandler);
-        }
-    },
+            finally {
+                page.pptrPage.off('dialog', dialogHandler);
+            }
+        },
+    };
 });
 export const evaluate = definePageTool({
     name: 'evaluate',
@@ -68,6 +75,7 @@ export const evaluate = definePageTool({
     annotations: {
         category: ToolCategory.DEBUGGING,
         readOnlyHint: false,
+        conditions: ['javascriptEvaluation'],
     },
     schema: {
         script: zod.string().describe(`JS script to run on the page`),

package/build/src/tools/snapshot.js

@@ -8,7 +8,7 @@ import { ToolCategory } from './categories.js';
 import { definePageTool, timeoutSchema } from './ToolDefinition.js';
 export const takeSnapshot = definePageTool({
     name: 'take_snapshot',
-    description: `Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a unique
+    description: `Take a text snapshot of the target page based on the a11y tree. The snapshot lists page elements along with a unique
 identifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected
 in the DevTools Elements panel (if any).`,
     annotations: {

package/build/src/tools/tools.js

@@ -6,6 +6,7 @@
  * Modified by Opera Software AS.
  */
 import * as operaTools from '../opera/tools/opera.js';
+import * as commentsTools from './comments.js';
 import * as consoleTools from './console.js';
 import * as emulationTools from './emulation.js';
 import * as extensionTools from './extensions.js';
@@ -27,6 +28,7 @@ export const createTools = (args) => {
     const rawTools = args.slim
         ? Object.values(slimTools)
         : [
+            ...(args.devtoolsComments ? Object.values(commentsTools) : []),
             ...Object.values(consoleTools),
             ...Object.values(emulationTools),
             ...Object.values(extensionTools),

package/build/src/utils/WaitForHelper.js

@@ -187,7 +187,7 @@ export class WaitForHelper {
         });
         // A scoped AbortController used to clean up navigation probe listeners.
         // When aborted (either after navigation detection finishes or if this.#abortController
-        // aborts), it removes the CDP Page.frameStartedNavigating listener and automatically
+        // aborts), it removes CDP navigation probe listeners and automatically
         // detaches the abort listener from this.#abortController.signal.
         const navigationAbortController = new AbortController();
         const navigationStartedResolvers = Promise.withResolvers();
@@ -201,11 +201,22 @@ export class WaitForHelper {
             }
             navigationStartedResolvers.resolve(true);
         };
+        const requestedNavigationListener = (event) => {
+            if (event.frameId === this.#page.mainFrame()._id) {
+                navigationStartedResolvers.resolve(true);
+            }
+        };
         this.#page._client().on('Page.frameStartedNavigating', navigationListener);
+        this.#page
+            ._client()
+            .on('Page.frameRequestedNavigation', requestedNavigationListener);
         navigationAbortController.signal.addEventListener('abort', () => {
             this.#page
                 ._client()
                 .off('Page.frameStartedNavigating', navigationListener);
+            this.#page
+                ._client()
+                .off('Page.frameRequestedNavigation', requestedNavigationListener);
         });
         this.#abortController.signal.addEventListener('abort', () => {
             navigationStartedResolvers.resolve(false);

package/build/src/utils/bytes.js

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+const BYTE_UNITS = {
+    b: 1,
+    byte: 1,
+    bytes: 1,
+    k: 1000,
+    kb: 1000,
+    kib: 1024,
+    m: 1000 * 1000,
+    mb: 1000 * 1000,
+    mib: 1024 * 1024,
+    g: 1000 * 1000 * 1000,
+    gb: 1000 * 1000 * 1000,
+    gib: 1024 * 1024 * 1024,
+    t: 1000 * 1000 * 1000 * 1000,
+    tb: 1000 * 1000 * 1000 * 1000,
+    tib: 1024 * 1024 * 1024 * 1024,
+};
+/**
+ * Parses a byte size string (e.g. "1M", "1MB", "500KB", "1.5GB", "1024") into bytes.
+ */
+export function parseByteSize(value) {
+    const trimmed = value.trim();
+    if (trimmed === '') {
+        throw new Error(`Invalid byte size: "${value}"`);
+    }
+    const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*([a-zA-Z]+)?$/);
+    if (!match) {
+        throw new Error(`Invalid byte size format: "${value}". Expected a number or format like "1024", "1M", "1MB", "1G", "1GB".`);
+    }
+    const numMatch = match[1];
+    if (numMatch === undefined) {
+        throw new Error(`Invalid byte size: "${value}"`);
+    }
+    const num = Number(numMatch);
+    if (!Number.isFinite(num) || num < 0) {
+        throw new Error(`Invalid byte size: "${value}"`);
+    }
+    const unitMatch = match[2];
+    if (unitMatch === undefined) {
+        return Math.round(num);
+    }
+    const unit = unitMatch.toLowerCase();
+    const multiplier = BYTE_UNITS[unit];
+    if (multiplier === undefined) {
+        throw new Error(`Unknown unit "${unitMatch}" in "${value}". Supported units: B, KB, KiB, MB, MiB, GB, GiB, TB, TiB.`);
+    }
+    const bytes = Math.round(num * multiplier);
+    if (!Number.isFinite(bytes)) {
+        throw new Error(`Invalid byte size: "${value}"`);
+    }
+    return bytes;
+}
+/**
+ * Parses an inclusive byte-size range (e.g. "1MB", "1MB-2MB", "-1MB", "1MB-").
+ */
+export function parseByteSizeRange(value) {
+    const trimmed = value.trim();
+    if (!trimmed.includes('-')) {
+        return { min: parseByteSize(trimmed), max: undefined };
+    }
+    const parts = trimmed.split('-');
+    if (parts.length !== 2) {
+        throw new Error(`Invalid byte size range: "${value}". Expected a size or range like "1MB", "1MB-2MB", "-1MB", or "1MB-".`);
+    }
+    const minValue = parts[0];
+    const maxValue = parts[1];
+    if (minValue === undefined || maxValue === undefined) {
+        throw new Error(`Invalid byte size range: "${value}"`);
+    }
+    const minText = minValue.trim();
+    const maxText = maxValue.trim();
+    if (minText === '' && maxText === '') {
+        throw new Error(`Invalid byte size range: "${value}". At least one bound is required.`);
+    }
+    const min = minText === '' ? 0 : parseByteSize(minText);
+    const max = maxText === '' ? undefined : parseByteSize(maxText);
+    if (max !== undefined && min > max) {
+        throw new Error(`Invalid byte size range: "${value}". The lower bound must not exceed the upper bound.`);
+    }
+    return { min, max };
+}
+export function byteSizeRangeSchema(description) {
+    return zod
+        .string()
+        .transform((value, context) => {
+        try {
+            return parseByteSizeRange(value);
+        }
+        catch (error) {
+            context.addIssue({
+                code: zod.ZodIssueCode.custom,
+                message: error instanceof Error ? error.message : 'Invalid byte size range',
+            });
+            return zod.NEVER;
+        }
+    })
+        .describe(description);
+}
+//# sourceMappingURL=bytes.js.map

package/build/src/utils/url.js

@@ -3,6 +3,7 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { isOperaStartPage } from '../opera/operaPages.js';
 const ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'ws:', 'wss:']);
 const IPV4_LOOPBACK_REGEX = /^127(?:\.(?:25[0-5]|2[0-4]\d|[01]?\d\d?)){3}$/;
 /**
@@ -40,4 +41,82 @@ export function isLocalhost(url) {
     }
     return false;
 }
+/**
+ * Determines whether a URL is allowed for navigation and page tracking.
+ *
+ * Disallowed schemes:
+ * - chrome: (except chrome://newtab/ and chrome://inspect*)
+ * - chrome-untrusted:
+ * - chrome-extension: (unless categoryExtensions is true)
+ *
+ * @param url The URL string to test.
+ * @param options Configuration specifying whether extensions are enabled.
+ * @returns true if the URL is allowed.
+ */
+export function isAllowedUrl(url, options) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === 'chrome:') {
+        const host = parsed.hostname.toLowerCase();
+        const path = parsed.pathname.toLowerCase();
+        if (host === 'newtab' || host === 'new-tab-page' || host === 'inspect') {
+            return true;
+        }
+        if (host === '' &&
+            (path === 'newtab' ||
+                path === 'new-tab-page' ||
+                path.startsWith('inspect'))) {
+            return true;
+        }
+        // Opera's start page, which is where every tab the user opens by hand
+        // begins; see `opera/operaPages.ts` for why it cannot be filtered out.
+        if (isOperaStartPage(parsed)) {
+            return true;
+        }
+    }
+    if (parsed.protocol === 'chrome:' ||
+        parsed.protocol === 'chrome-untrusted:') {
+        return false;
+    }
+    if (!options.categoryExtensions && parsed.protocol === 'chrome-extension:') {
+        return false;
+    }
+    return true;
+}
+const DISALLOWED_PROTOCOLS = new Set(['javascript:', 'data:', 'vbscript:']);
+/**
+ * Validates a URL string by parsing it with `new URL` and checking for disallowed protocols and restricted schemes.
+ *
+ * @param url The URL string to validate.
+ * @param options Options object containing javascriptEvaluation and categoryExtensions.
+ * @returns The parsed URL.
+ * @throws Error if the URL does not parse with `new URL`, or if JavaScript evaluation is disabled and a disallowed URL is passed,
+ * or if navigating to a restricted scheme.
+ */
+export function validateUrl(url, options) {
+    const { javascriptEvaluation, categoryExtensions } = options;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: "${url}". URLs must be valid according to the URL standard.`);
+    }
+    if (javascriptEvaluation === false &&
+        DISALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        throw new Error(`Navigating to ${parsed.protocol} URLs is not allowed when JavaScript evaluation is disabled.`);
+    }
+    if (!isAllowedUrl(url, { categoryExtensions })) {
+        if (parsed.protocol === 'chrome-extension:') {
+            throw new Error(`Navigating to chrome-extension: URLs is not allowed without --categoryExtensions.`);
+        }
+        throw new Error(`Navigating to ${parsed.protocol} URLs is not allowed.`);
+    }
+    return parsed;
+}
 //# sourceMappingURL=url.js.map

package/build/src/version.js

@@ -5,5 +5,5 @@
  *
  * Modified by Opera Software AS.
  */
-export const VERSION = '0.6.1';
+export const VERSION = '0.8.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "opera-devtools-mcp",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "MCP server for Opera DevTools",
   "type": "module",
   "bin": {
-    "opera-devtools-mcp": "./build/src/bin/opera-devtools-mcp.js",
-    "opera-devtools": "./build/src/bin/opera-devtools.js"
+    "opera-devtools-mcp": "./build/src/bin/opera-devtools-mcp.js"
   },
   "main": "./build/src/index.js",
   "scripts": {
@@ -13,10 +12,13 @@
     "clean": "node -e \"require('fs').rmSync('build', {recursive: true, force: true})\"",
     "bundle": "npm run clean && npm run build && rollup -c rollup.config.js && node -e \"require('fs').rmSync('build/node_modules', {recursive: true, force: true})\" && node scripts/append-lighthouse-notices.ts",
     "build": "tsc && node scripts/post-build.ts",
+    "prepublishOnly": "npm run bundle",
     "typecheck": "tsc --noEmit",
     "format": "eslint --cache --fix . && prettier --write --cache .",
     "check-format": "eslint --cache . && prettier --check --cache .;",
     "gen": "npm run build && npm run docs:generate && npm run cli:generate && npm run update-metrics && npm run format",
+    "link": "node scripts/link.ts",
+    "link:cli": "node scripts/link.ts --with-cli",
     "docs:generate": "node scripts/generate-docs.ts",
     "start": "npm run build && node build/src/bin/opera-devtools-mcp.js",
     "start-debug": "DEBUG=mcp:* DEBUG_COLORS=false npm run build && node build/src/bin/opera-devtools-mcp.js",
@@ -35,7 +37,9 @@
     "eval": "npm run build && node scripts/eval_gemini.ts",
     "count-tokens": "node scripts/count_tokens.ts",
     "profile": "npm run build && node scripts/profile/profile_mcp.ts",
-    "test:memory": "npm run build && node scripts/profile/profile_mcp.ts --threshold-percentage 1"
+    "test:memory": "npm run build && node scripts/profile/profile_mcp.ts --threshold-percentage 1",
+    "test:stress": "npm run build && STRESS_ALLOW_PROCESS_KILLS=true node --import ./build/tests/setup.js --test --test-force-exit --test-timeout=600000 build/tests/stress/runner.test.js",
+    "test:stress:docker": "node scripts/stress-docker.js"
   },
   "files": [
     "build/src",
@@ -51,6 +55,9 @@
   },
   "homepage": "https://github.com/operasoftware/opera-devtools-mcp#readme",
   "mcpName": "io.github.operasoftware/opera-devtools-mcp",
+  "dependencies": {
+    "@toon-format/toon": "^4.1.0"
+  },
   "devDependencies": {
     "@blackwell-systems/gcf": "^2.2.2",
     "@eslint/js": "^10.0.1",
@@ -60,7 +67,6 @@
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@stylistic/eslint-plugin": "^5.4.0",
-    "@toon-format/toon": "^4.1.0",
     "@types/filesystem": "^0.0.36",
     "@types/node": "^26.0.0",
     "@types/semver": "^7.7.1",
@@ -68,15 +74,15 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "core-js": "3.49.0",
+    "core-js": "3.50.0",
     "eslint": "^10.7.0",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "globals": "^17.0.0",
     "lighthouse": "13.4.1",
     "prettier": "^3.6.2",
-    "puppeteer": "25.6.0",
-    "rollup": "4.62.4",
+    "puppeteer": "25.10.0",
+    "rollup": "4.63.1",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-license": "^3.6.0",
     "semver": "^7.7.4",
@@ -86,6 +92,14 @@
     "yargs": "18.1.0",
     "zod": "^3.25.76"
   },
+  "peerDependencies": {
+    "@blackwell-systems/gcf": "^2.2.2"
+  },
+  "peerDependenciesMeta": {
+    "@blackwell-systems/gcf": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": "^20.19.0 || ^22.12.0 || >=23"
   },
@@ -94,5 +108,12 @@
       "eslint": "$eslint"
     },
     "puppeteer-core": "$puppeteer"
+  },
+  "allowScripts": {
+    "core-js": false,
+    "@google/genai": false,
+    "protobufjs": false,
+    "unrs-resolver": false,
+    "puppeteer": true
   }
 }

package/build/src/bin/opera-devtools.js

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-/**
- * @license
- * Copyright 2026 Opera Software AS.
- * SPDX-License-Identifier: Apache-2.0
- */
-// Opera-named bin entry (see `package.json` `bin`). The implementation lives in
-// the upstream-owned file and is branded via `src/opera/branding.ts`.
-import './chrome-devtools.js';
-//# sourceMappingURL=opera-devtools.js.map