opera-devtools-mcp 0.2.4 → 0.4.0

package/build/src/opera/toolHandlerHooks.js

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+import { ToolCategory } from '../tools/categories.js';
+import { ensureBrowserFlagsForTool } from './browserFlags.js';
+export function createOperaToolHooks(deps) {
+    return {
+        bypassMutex(tool) {
+            return tool.annotations.category === ToolCategory.OPERA;
+        },
+        async beforeInvoke(tool) {
+            await ensureBrowserFlagsForTool(tool.name, deps.serverArgs, deps.logFile, { resetContext: deps.resetContext });
+        },
+        makeLogCallback(extra) {
+            const sendNotification = extra?.sendNotification;
+            if (!sendNotification) {
+                return undefined;
+            }
+            return (message) => {
+                // `logger` carries the MCP request ID so the opera-cli bridge can route
+                // this chunk to the correct HTTP response (see bridge.ts requestLoggers).
+                // `data` stays a plain string so non-bridge MCP hosts (Claude Desktop,
+                // VS Code, etc.) continue to render it as readable text.
+                void sendNotification.call(extra, {
+                    method: 'notifications/message',
+                    params: {
+                        level: 'info',
+                        data: message,
+                        logger: String(extra?.requestId),
+                    },
+                });
+            };
+        },
+    };
+}
+//# sourceMappingURL=toolHandlerHooks.js.map

package/build/src/{tools → opera/tools}/opera.js

@@ -4,28 +4,11 @@
  *
  * This file is an original work developed by Opera.
  */
-import { zod } from '../third_party/index.js';
-import { ToolCategory } from './categories.js';
-import { definePageTool } from './ToolDefinition.js';
+import { zod } from '../../third_party/index.js';
+import { ToolCategory } from '../../tools/categories.js';
+import { definePageTool } from '../../tools/ToolDefinition.js';
+import { withServiceWorkerRetry } from '../serviceWorkerRetry.js';
 const getCDPSession = (page) => page._client();
-const MAX_SW_RETRIES = 5;
-const SW_RETRY_DELAY_MS = 2500;
-const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
-async function withServiceWorkerRetry(fn) {
-    let lastError;
-    for (let attempt = 0; attempt < MAX_SW_RETRIES; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (e) {
-            lastError = e;
-            if (attempt < MAX_SW_RETRIES - 1) {
-                await sleep(SW_RETRY_DELAY_MS);
-            }
-        }
-    }
-    throw lastError;
-}
 const dispatchAction = async (session, payload) => {
     const response = (await withServiceWorkerRetry(() => session.send('Opera.dispatchAction', { payload })));
     return response.result;
@@ -77,6 +60,7 @@ export const operaChat = definePageTool({
     name: 'opera_chat',
     description: "Send a chat prompt to Opera's built-in AI and return the response. Only available when connected to Opera Neon.",
     blockedByDialog: false,
+    verifyFilesSchema: {},
     annotations: {
         category: ToolCategory.OPERA,
         readOnlyHint: false,
@@ -111,6 +95,7 @@ export const operaDo = definePageTool({
     name: 'opera_do',
     description: "Instruct Opera's built-in AI to perform an action on the current page and return the result. Only available when connected to Opera Neon.",
     blockedByDialog: false,
+    verifyFilesSchema: {},
     annotations: {
         category: ToolCategory.OPERA,
         readOnlyHint: false,
@@ -142,6 +127,7 @@ export const operaMake = definePageTool({
     name: 'opera_make',
     description: "Ask Opera's built-in AI to create or generate content and return the result. Only available when connected to Opera Neon.",
     blockedByDialog: false,
+    verifyFilesSchema: {},
     annotations: {
         category: ToolCategory.OPERA,
         readOnlyHint: false,
@@ -168,6 +154,7 @@ export const operaResearch = definePageTool({
     name: 'opera_research',
     description: "Ask Opera's built-in AI to research a topic and return a summary. Only available when connected to Opera Neon.",
     blockedByDialog: false,
+    verifyFilesSchema: {},
     annotations: {
         category: ToolCategory.OPERA,
         readOnlyHint: false,
@@ -205,6 +192,7 @@ export const operaListModels = definePageTool({
     name: 'opera_list_models',
     description: 'List available AI models for Opera chat. Returns model IDs, display names, and which is the default. Only available when connected to Opera Neon.',
     blockedByDialog: false,
+    verifyFilesSchema: {},
     annotations: {
         category: ToolCategory.OPERA,
         readOnlyHint: true,
@@ -222,4 +210,111 @@ export const operaListModels = definePageTool({
         }
     },
 });
+export const operaListMcpServers = definePageTool({
+    name: 'opera_list_mcp_servers',
+    description: 'List MCP servers registered in the browser, ' +
+        'including their connection status. ' +
+        'Only available when connected to Opera Neon.',
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    annotations: {
+        category: ToolCategory.OPERA,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (request, response) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const session = getCDPSession(request.page.pptrPage);
+        try {
+            const result = await dispatchAction(session, {
+                action: 'listMcpServers',
+            });
+            response.appendResponseLine(result);
+        }
+        catch (e) {
+            response.appendResponseLine(`Opera.dispatchAction(listMcpServers) failed with error: ${e.message}`);
+        }
+    },
+});
+export const operaListMcpTools = definePageTool({
+    name: 'opera_list_mcp_tools',
+    description: 'List the tools exposed by a single MCP server. Prefer opera_list_mcp_servers ' +
+        'when discovering everything at once; use this for a targeted refresh of one server. ' +
+        'Only available when connected to Opera Neon.',
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    annotations: {
+        category: ToolCategory.OPERA,
+        readOnlyHint: true,
+    },
+    schema: {
+        server: zod
+            .string()
+            .min(1)
+            .describe('The MCP server name (from opera_list_mcp_servers).'),
+    },
+    handler: async (request, response) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const session = getCDPSession(request.page.pptrPage);
+        try {
+            const result = await dispatchAction(session, {
+                action: 'listMcpTools',
+                server: request.params.server,
+            });
+            response.appendResponseLine(result);
+        }
+        catch (e) {
+            response.appendResponseLine(`Opera.dispatchAction(listMcpTools) failed with error: ${e.message}`);
+        }
+    },
+});
+export const operaCallMcpTool = definePageTool({
+    name: 'opera_call_mcp_tool',
+    description: 'Execute a tool on a specific MCP server registered in the browser. ' +
+        'Use opera_list_mcp_servers to discover available ' +
+        'servers and tools. ' +
+        'Only available when connected to Opera Neon.',
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    annotations: {
+        category: ToolCategory.OPERA,
+        readOnlyHint: false,
+    },
+    schema: {
+        server: zod
+            .string()
+            .min(1)
+            .describe('The MCP server name (from opera_list_mcp_servers).'),
+        tool: zod
+            .string()
+            .min(1)
+            .describe('The tool name to execute on the server.'),
+        parameters: zod
+            .record(zod.unknown())
+            .optional()
+            .describe('Parameters to pass to the tool. Omit if the tool takes none.'),
+    },
+    handler: async (request, response) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const session = getCDPSession(request.page.pptrPage);
+        try {
+            const payload = {
+                action: 'callMcpTool',
+                server: request.params.server,
+                tool: request.params.tool,
+            };
+            if (request.params.parameters !== undefined) {
+                payload['parameters'] = request.params.parameters;
+            }
+            const result = await dispatchWithStreamedResponse(session, payload, chunk => response.sendLog(chunk), request.signal);
+            response.appendResponseLine(result);
+        }
+        catch (e) {
+            if (e.name === 'AbortError') {
+                throw e;
+            }
+            response.appendResponseLine(`Opera.dispatchWithStreamedResponse(callMcpTool) failed with error: ${e.message}`);
+        }
+    },
+});
 //# sourceMappingURL=opera.js.map

package/build/src/processors/HeapSnapshotManager.js

@@ -0,0 +1,258 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { DevTools } from '../third_party/index.js';
+import { createIdGenerator, stableIdSymbol, } from '../utils/id.js';
+export class HeapSnapshotManager {
+    #snapshotIdGenerator = createIdGenerator();
+    #snapshots = new Map();
+    async getSnapshot(filePath) {
+        const absolutePath = path.resolve(filePath);
+        const cached = this.#snapshots.get(absolutePath);
+        if (cached) {
+            return cached.snapshot;
+        }
+        const uid = this.#snapshotIdGenerator();
+        const { snapshot, worker } = await this.#loadSnapshot(absolutePath, uid);
+        this.#snapshots.set(absolutePath, {
+            snapshot,
+            worker,
+            idToClassKey: [''],
+            classKeyToId: new Map(),
+        });
+        return snapshot;
+    }
+    async #applyNodeFilter(snapshot, filter, filterName, objectId) {
+        if (filterName === 'attributedToSpecificNativeContext') {
+            if (objectId === undefined) {
+                throw new Error('objectId is required when filterName is attributedToSpecificNativeContext');
+            }
+            const nodeIndex = await snapshot.nodeIndexForId(objectId);
+            if (nodeIndex === undefined) {
+                throw new Error(`Node with ID ${objectId} not found`);
+            }
+            filter.filterName = `nativeContext_${nodeIndex}`;
+        }
+        else if (filterName) {
+            filter.filterName = filterName;
+        }
+    }
+    async getAggregates(filePath, filterName, objectId) {
+        const snapshot = await this.getSnapshot(filePath);
+        const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
+        await this.#applyNodeFilter(snapshot, filter, filterName, objectId);
+        const aggregates = await snapshot.aggregatesWithFilter(filter);
+        let objectCount = 0;
+        let totalSelfSize = 0;
+        for (const [key, aggregate] of Object.entries(aggregates)) {
+            const id = await this.getOrCreateIdForClassKey(filePath, key);
+            aggregate[stableIdSymbol] = id;
+            objectCount += aggregate.count;
+            totalSelfSize += aggregate.self;
+        }
+        return {
+            aggregates,
+            objectCount,
+            totalSelfSize,
+        };
+    }
+    async getStats(filePath) {
+        const snapshot = await this.getSnapshot(filePath);
+        return await snapshot.getStatistics();
+    }
+    async getStaticData(filePath) {
+        const snapshot = await this.getSnapshot(filePath);
+        return snapshot.staticData;
+    }
+    async getNativeContextSizes(filePath) {
+        const snapshot = await this.getSnapshot(filePath);
+        return await snapshot.getNativeContextSizes();
+    }
+    async getRetainedByContextSummary(filePath) {
+        const snapshot = await this.getSnapshot(filePath);
+        return await snapshot.getRetainedByContextSummary();
+    }
+    async getOrCreateIdForClassKey(filePath, classKey) {
+        const cached = this.#getCachedSnapshot(filePath);
+        let id = cached.classKeyToId.get(classKey);
+        if (!id) {
+            id = cached.idToClassKey.length;
+            cached.classKeyToId.set(classKey, id);
+            cached.idToClassKey.push(classKey);
+        }
+        return id;
+    }
+    async getNodesById(filePath, id, filterName, objectId) {
+        const snapshot = await this.getSnapshot(filePath);
+        const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
+        await this.#applyNodeFilter(snapshot, filter, filterName, objectId);
+        const className = await this.resolveClassKeyFromId(filePath, id);
+        if (!className) {
+            throw new Error(`Class with ID ${id} not found in heap snapshot`);
+        }
+        const provider = snapshot.createNodesProviderForClass(className, filter);
+        return await provider.serializeItemsRange(0, Infinity);
+    }
+    async getRetainers(filePath, nodeId) {
+        const snapshot = await this.getSnapshot(filePath);
+        const nodeIndex = await snapshot.nodeIndexForId(nodeId);
+        if (nodeIndex === undefined) {
+            throw new Error(`Node with ID ${nodeId} not found`);
+        }
+        const provider = snapshot.createRetainingEdgesProvider(nodeIndex);
+        return await provider.serializeItemsRange(0, Infinity);
+    }
+    async getObjectInfo(filePath, nodeId) {
+        const snapshot = await this.getSnapshot(filePath);
+        const nodeIndex = await snapshot.nodeIndexForId(nodeId);
+        if (nodeIndex === undefined) {
+            throw new Error(`Node with ID ${nodeId} not found`);
+        }
+        return await snapshot.getObjectInfo(nodeIndex);
+    }
+    async getRetainingPaths(filePath, nodeId, maxDepth, maxNodes, maxSiblings) {
+        const snapshot = await this.getSnapshot(filePath);
+        const nodeIndex = await snapshot.nodeIndexForId(nodeId);
+        if (nodeIndex === undefined) {
+            throw new Error(`Node with ID ${nodeId} not found`);
+        }
+        return await snapshot.getRetainingPaths(nodeIndex, maxDepth, maxNodes, maxSiblings);
+    }
+    async getDominatorsOf(filePath, nodeId) {
+        const snapshot = await this.getSnapshot(filePath);
+        const nodeIndex = await snapshot.nodeIndexForId(nodeId);
+        if (nodeIndex === undefined) {
+            throw new Error(`Node with ID ${nodeId} not found`);
+        }
+        return await snapshot.getDominatorsOf(nodeIndex);
+    }
+    async getEdges(filePath, nodeId, options) {
+        const snapshot = await this.getSnapshot(filePath);
+        const nodeIndex = await snapshot.nodeIndexForId(nodeId);
+        if (nodeIndex === undefined) {
+            throw new Error(`Node with ID ${nodeId} not found`);
+        }
+        const provider = snapshot.createEdgesProvider(nodeIndex, options);
+        return await provider.serializeItemsRange(0, Infinity);
+    }
+    async getClassDiffs(baseFilePath, currentFilePath) {
+        const rawDiffs = await this.#getSortedRawClassDiffs(baseFilePath, currentFilePath);
+        return rawDiffs.map(rawDiff => ({
+            className: rawDiff.name,
+            addedCount: rawDiff.addedCount,
+            removedCount: rawDiff.removedCount,
+            countDelta: rawDiff.countDelta,
+            addedSize: rawDiff.addedSize,
+            removedSize: rawDiff.removedSize,
+            sizeDelta: rawDiff.sizeDelta,
+        }));
+    }
+    async getDetailedClassDiff(baseFilePath, currentFilePath, classIndex) {
+        const classDiffs = await this.#getSortedRawClassDiffs(baseFilePath, currentFilePath);
+        const rawDiff = classDiffs[classIndex];
+        if (!rawDiff) {
+            throw new Error(`Invalid classIndex: ${classIndex}. Total classes with changes: ${classDiffs.length}`);
+        }
+        return {
+            className: rawDiff.name,
+            addedCount: rawDiff.addedCount,
+            removedCount: rawDiff.removedCount,
+            countDelta: rawDiff.countDelta,
+            addedSize: rawDiff.addedSize,
+            removedSize: rawDiff.removedSize,
+            sizeDelta: rawDiff.sizeDelta,
+            addedIds: rawDiff.addedIds ?? [],
+            addedSelfSizes: rawDiff.addedSelfSizes ?? [],
+            deletedIds: rawDiff.deletedIds ?? [],
+            deletedSelfSizes: rawDiff.deletedSelfSizes ?? [],
+        };
+    }
+    #getCachedSnapshot(filePath) {
+        const absolutePath = path.resolve(filePath);
+        const cached = this.#snapshots.get(absolutePath);
+        if (!cached) {
+            throw new Error(`Snapshot not loaded for ${filePath}`);
+        }
+        return cached;
+    }
+    async #getSortedRawClassDiffs(baseFilePath, currentFilePath) {
+        const baseSnapshot = await this.getSnapshot(baseFilePath);
+        const currentSnapshot = await this.getSnapshot(currentFilePath);
+        const interfaceDefinitions = await currentSnapshot.interfaceDefinitions();
+        const aggregatesForDiff = await baseSnapshot.aggregatesForDiff(interfaceDefinitions);
+        const baseSnapshotId = baseSnapshot.uid;
+        if (baseSnapshotId === undefined) {
+            throw new Error('Base snapshot UID is undefined');
+        }
+        // DevTools calculateSnapshotDiff uses the first parameter (baseSnapshotId)
+        // as a cache key. We pass the unique UID of the base snapshot.
+        const rawDiffs = await currentSnapshot.calculateSnapshotDiff(baseSnapshotId, aggregatesForDiff);
+        // Return a filtered and sorted array here to ensure that
+        // compare_heapsnapshot_summary and compare_heapsnapshot_details agree
+        // on indices.
+        return Object.values(rawDiffs)
+            .filter(diff => diff.addedCount > 0 || diff.removedCount > 0)
+            .sort((a, b) => b.sizeDelta - a.sizeDelta);
+    }
+    async resolveClassKeyFromId(filePath, id) {
+        const cached = this.#getCachedSnapshot(filePath);
+        return cached.idToClassKey[id];
+    }
+    async #loadSnapshot(absolutePath, uid) {
+        const workerProxy = new DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy(() => {
+            /* noop */
+        }, DevTools.Common.Console.Console.instance(), import.meta.resolve('../third_party/devtools-heap-snapshot-worker.js'));
+        try {
+            const { promise: snapshotPromise, resolve: resolveSnapshot } = Promise.withResolvers();
+            const loaderProxy = workerProxy.createLoader(uid, snapshotProxy => {
+                resolveSnapshot(snapshotProxy);
+            });
+            const fileStream = fsSync.createReadStream(absolutePath, {
+                encoding: 'utf-8',
+                highWaterMark: 1024 * 1024,
+            });
+            for await (const chunk of fileStream) {
+                await loaderProxy.write(chunk);
+            }
+            await loaderProxy.close();
+            const snapshot = await snapshotPromise;
+            return { snapshot, worker: workerProxy };
+        }
+        catch (error) {
+            // The worker is created before the read, and a failed load never reaches
+            // the #snapshots map, so dispose()/disposeAll() can never clean it up.
+            // Dispose it here to avoid leaking a worker on every failed load (e.g. a
+            // missing or invalid .heapsnapshot path).
+            workerProxy.dispose();
+            throw error;
+        }
+    }
+    async getDuplicateStrings(filePath) {
+        const snapshot = await this.getSnapshot(filePath);
+        return await snapshot.getDuplicateStrings();
+    }
+    hasSnapshots() {
+        return this.#snapshots.size > 0;
+    }
+    disposeSnapshot(filePath) {
+        const absolutePath = path.resolve(filePath);
+        const cached = this.#snapshots.get(absolutePath);
+        if (cached) {
+            cached.worker.dispose();
+            this.#snapshots.delete(absolutePath);
+            return true;
+        }
+        return false;
+    }
+    dispose() {
+        for (const cached of this.#snapshots.values()) {
+            cached.worker.dispose();
+        }
+        this.#snapshots.clear();
+    }
+}
+//# sourceMappingURL=HeapSnapshotManager.js.map

package/build/src/{trace-processing/parse.js → processors/PerformanceTrace.js}

@@ -3,13 +3,13 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { logger } from '../logger.js';
 import { DevTools } from '../third_party/index.js';
+import { logger } from '../utils/logger.js';
 const engine = DevTools.TraceEngine.TraceModel.Model.createWithAllHandlers();
 export function traceResultIsSuccess(x) {
     return 'parsedTrace' in x;
 }
-export async function parseRawTraceBuffer(buffer) {
+export async function parseRawTraceBuffer(buffer, metadata) {
     engine.resetProcessor();
     if (!buffer) {
         return {
@@ -25,7 +25,7 @@ export async function parseRawTraceBuffer(buffer) {
     try {
         const data = JSON.parse(asString);
         const events = Array.isArray(data) ? data : data.traceEvents;
-        await engine.parse(events);
+        await engine.parse(events, { metadata });
         const parsedTrace = engine.parsedTrace();
         if (!parsedTrace) {
             return {
@@ -40,7 +40,7 @@ export async function parseRawTraceBuffer(buffer) {
     }
     catch (e) {
         const errorText = e instanceof Error ? e.message : JSON.stringify(e);
-        logger(`Unexpected error parsing trace: ${errorText}`);
+        logger?.(`Unexpected error parsing trace: ${errorText}`);
         return {
             error: errorText,
         };
@@ -51,9 +51,9 @@ const extraFormatDescriptions = `Information on performance traces may contain m
 ${DevTools.PerformanceTraceFormatter.callFrameDataFormatDescription}
 
 ${DevTools.PerformanceTraceFormatter.networkDataFormatDescription}`;
-export function getTraceSummary(result) {
+export function getTraceSummary(result, deviceScope) {
     const focus = DevTools.AgentFocus.fromParsedTrace(result.parsedTrace);
-    const formatter = new DevTools.PerformanceTraceFormatter(focus);
+    const formatter = new DevTools.PerformanceTraceFormatter(focus, deviceScope);
     const summaryText = formatter.formatTraceSummary();
     return `## Summary of Performance trace findings:
 ${summaryText}
@@ -61,7 +61,7 @@ ${summaryText}
 ## Details on call tree & network request formats:
 ${extraFormatDescriptions}`;
 }
-export function getInsightOutput(result, insightSetId, insightName) {
+export function getInsightOutput(result, insightSetId, insightName, deviceScope) {
     if (!result.insights) {
         return {
             error: 'No Performance insights are available for this trace.',
@@ -79,7 +79,7 @@ export function getInsightOutput(result, insightSetId, insightName) {
             error: `No Insight with the name ${insightName} found. Double check the name you provided is accurate and try again.`,
         };
     }
-    const formatter = new DevTools.PerformanceInsightFormatter(DevTools.AgentFocus.fromParsedTrace(result.parsedTrace), matchingInsight);
+    const formatter = new DevTools.PerformanceInsightFormatter(DevTools.AgentFocus.fromParsedTrace(result.parsedTrace), matchingInsight, deviceScope);
     return { output: formatter.formatInsight() };
 }
-//# sourceMappingURL=parse.js.map
+//# sourceMappingURL=PerformanceTrace.js.map