brave-mcp 0.2.0 → 0.2.1

package/build/src/HeapSnapshotManager.js

@@ -0,0 +1,61 @@
+/**
+ * @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';
+export class HeapSnapshotManager {
+    #snapshots = new Map();
+    async getSnapshot(filePath) {
+        const absolutePath = path.resolve(filePath);
+        const cached = this.#snapshots.get(absolutePath);
+        if (cached) {
+            return cached.snapshot;
+        }
+        const { snapshot, worker } = await this.#loadSnapshot(absolutePath);
+        this.#snapshots.set(absolutePath, { snapshot, worker });
+        return snapshot;
+    }
+    async getAggregates(filePath) {
+        const snapshot = await this.getSnapshot(filePath);
+        const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
+        return await snapshot.aggregatesWithFilter(filter);
+    }
+    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 #loadSnapshot(absolutePath) {
+        const workerProxy = new DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy(() => {
+            /* noop */
+        }, import.meta.resolve('./third_party/devtools-heap-snapshot-worker.js'));
+        const { promise: snapshotPromise, resolve: resolveSnapshot } = Promise.withResolvers();
+        const loaderProxy = workerProxy.createLoader(1, 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 };
+    }
+    dispose(filePath) {
+        const absolutePath = path.resolve(filePath);
+        const cached = this.#snapshots.get(absolutePath);
+        if (cached) {
+            cached.worker.dispose();
+            this.#snapshots.delete(absolutePath);
+        }
+    }
+}

package/build/src/McpContext.js

@@ -6,6 +6,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { UniverseManager } from './DevtoolsUtils.js';
+import { HeapSnapshotManager } from './HeapSnapshotManager.js';
 import { McpPage } from './McpPage.js';
 import { NetworkCollector, ConsoleCollector, } from './PageCollector.js';
 import { Locator } from './third_party/index.js';
@@ -42,6 +43,7 @@ export class McpContext {
     #traceResults = [];
     #locatorClass;
     #options;
+    #heapSnapshotManager = new HeapSnapshotManager();
     constructor(browser, logger, options, locatorClass) {
         this.browser = browser;
         this.logger = logger;
@@ -673,4 +675,13 @@ export class McpContext {
     getExtension(id) {
         return this.#extensionRegistry.getById(id);
     }
+    async getHeapSnapshotAggregates(filePath) {
+        return await this.#heapSnapshotManager.getAggregates(filePath);
+    }
+    async getHeapSnapshotStats(filePath) {
+        return await this.#heapSnapshotManager.getStats(filePath);
+    }
+    async getHeapSnapshotStaticData(filePath) {
+        return await this.#heapSnapshotManager.getStaticData(filePath);
+    }
 }

package/build/src/McpResponse.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { ConsoleFormatter } from './formatters/ConsoleFormatter.js';
+import { HeapSnapshotFormatter } from './formatters/HeapSnapshotFormatter.js';
 import { IssueFormatter } from './formatters/IssueFormatter.js';
 import { NetworkFormatter } from './formatters/NetworkFormatter.js';
 import { SnapshotFormatter } from './formatters/SnapshotFormatter.js';
@@ -118,6 +119,7 @@ export class McpResponse {
     #attachedLighthouseResult;
     #textResponseLines = [];
     #images = [];
+    #heapSnapshotOptions;
     #networkRequestsOptions;
     #consoleDataOptions;
     #listExtensions;
@@ -254,6 +256,22 @@ export class McpResponse {
     appendResponseLine(value) {
         this.#textResponseLines.push(value);
     }
+    setHeapSnapshotAggregates(aggregates, options) {
+        this.#heapSnapshotOptions = {
+            ...this.#heapSnapshotOptions,
+            include: true,
+            aggregates,
+            pagination: options,
+        };
+    }
+    setHeapSnapshotStats(stats, staticData) {
+        this.#heapSnapshotOptions = {
+            ...this.#heapSnapshotOptions,
+            include: true,
+            stats,
+            staticData,
+        };
+    }
     attachImage(value) {
         this.#images.push(value);
     }
@@ -598,6 +616,32 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 structuredContent.snapshot = data.snapshot.toJSON();
             }
         }
+        if (this.#heapSnapshotOptions?.include) {
+            response.push('## Heap Snapshot Data');
+            const stats = this.#heapSnapshotOptions.stats;
+            const staticData = this.#heapSnapshotOptions.staticData;
+            if (stats) {
+                response.push(`Statistics: ${JSON.stringify(stats, null, 2)}`);
+                structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
+                structuredContent.heapSnapshot.stats = stats;
+            }
+            if (staticData) {
+                response.push(`Static Data: ${JSON.stringify(staticData, null, 2)}`);
+                structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
+                structuredContent.heapSnapshot.staticData = staticData;
+            }
+            const aggregates = this.#heapSnapshotOptions.aggregates;
+            if (aggregates) {
+                const sortedEntries = HeapSnapshotFormatter.sort(aggregates);
+                const paginationData = this.#dataWithPagination(sortedEntries, this.#heapSnapshotOptions.pagination);
+                structuredContent.pagination = paginationData.pagination;
+                response.push(...paginationData.info);
+                const paginatedRecord = Object.fromEntries(paginationData.items);
+                const formatter = new HeapSnapshotFormatter(paginatedRecord);
+                response.push(formatter.toString());
+                structuredContent.heapSnapshotData = formatter.toJSON();
+            }
+        }
         if (data.detailedNetworkRequest) {
             response.push(data.detailedNetworkRequest.toStringDetailed());
             structuredContent.networkRequest =

package/build/src/PageCollector.js

@@ -250,6 +250,11 @@ class PageEventSubscriber {
     };
     #onIssueAdded = (inspectorIssue) => {
         try {
+            // DevTools currently defines this protocol issue code but has no
+            // IssuesManager handler for it, so calling into the mapper only warns.
+            if (String(inspectorIssue.code) === 'PerformanceIssue') {
+                return;
+            }
             const issue = DevTools.createIssuesFromProtocolIssue(null, 
             // @ts-expect-error Protocol types diverge.
             inspectorIssue)[0];

package/build/src/bin/brave-devtools-mcp-cli-options.js

@@ -149,6 +149,11 @@ export const cliOptions = {
         describe: 'Whether to enable coordinate-based tools such as click_at(x,y). Usually requires a computer-use model able to produce accurate coordinates by looking at screenshots.',
         hidden: false,
     },
+    experimentalMemory: {
+        type: 'boolean',
+        describe: 'Whether to enable experimental memory tools.',
+        hidden: true,
+    },
     experimentalStructuredContent: {
         type: 'boolean',
         describe: 'Whether to output structured formatted content.',

package/build/src/bin/cliDefinitions.js

@@ -175,13 +175,13 @@ export const commands = {
             requestFilePath: {
                 name: 'requestFilePath',
                 type: 'string',
-                description: 'The absolute or relative path to save the request body to. If omitted, the body is returned inline.',
+                description: 'The absolute or relative path to a .network-request file to save the request body to. If omitted, the body is returned inline.',
                 required: false,
             },
             responseFilePath: {
                 name: 'responseFilePath',
                 type: 'string',
-                description: 'The absolute or relative path to save the response body to. If omitted, the body is returned inline.',
+                description: 'The absolute or relative path to a .network-response file to save the response body to. If omitted, the body is returned inline.',
                 required: false,
             },
         },
@@ -314,7 +314,7 @@ export const commands = {
         },
     },
     list_pages: {
-        description: 'Get a list of pages  open in the browser.',
+        description: 'Get a list of pages open in the browser.',
         category: 'Navigation automation',
         args: {},
     },

package/build/src/formatters/HeapSnapshotFormatter.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class HeapSnapshotFormatter {
+    #aggregates;
+    constructor(aggregates) {
+        this.#aggregates = aggregates;
+    }
+    #getSortedAggregates() {
+        return Object.values(this.#aggregates).sort((a, b) => b.self - a.self);
+    }
+    toString() {
+        const sorted = this.#getSortedAggregates();
+        const lines = [];
+        lines.push('className,count,selfSize,maxRetainedSize');
+        for (const info of sorted) {
+            lines.push(`"${info.name}",${info.count},${info.self},${info.maxRet}`);
+        }
+        return lines.join('\n');
+    }
+    toJSON() {
+        const sorted = this.#getSortedAggregates();
+        return sorted.map(info => ({
+            className: info.name,
+            count: info.count,
+            selfSize: info.self,
+            retainedSize: info.maxRet,
+        }));
+    }
+    static sort(aggregates) {
+        return Object.entries(aggregates).sort((a, b) => b[1].self - a[1].self);
+    }
+}

package/build/src/formatters/NetworkFormatter.js

@@ -227,7 +227,7 @@ function converNetworkRequestDetailedToStringDetailed(data) {
         response.push(`### Redirect chain`);
         let indent = 0;
         for (const request of redirectChain.reverse()) {
-            response.push(`${'  '.repeat(indent)}${convertNetworkRequestConciseToString(request)})}`);
+            response.push(`${'  '.repeat(indent)}${convertNetworkRequestConciseToString(request)}`);
             indent++;
         }
     }

package/build/src/index.js

@@ -111,6 +111,10 @@ export async function createMcpServer(serverArgs, options) {
             !serverArgs.experimentalVision) {
             return;
         }
+        if (tool.annotations.conditions?.includes('experimentalMemory') &&
+            !serverArgs.experimentalMemory) {
+            return;
+        }
         if (tool.annotations.conditions?.includes('experimentalInteropTools') &&
             !serverArgs.experimentalInteropTools) {
             return;

package/build/src/third_party/devtools-heap-snapshot-worker.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// eslint-disable-next-line no-restricted-imports
+import '../../node_modules/chrome-devtools-frontend/front_end/entrypoints/heap_snapshot_worker/heap_snapshot_worker-entrypoint.js';

package/build/src/third_party/index.js

@@ -8,6 +8,7 @@ import 'core-js/modules/es.set.union.v2.js';
 import 'core-js/proposals/iterator-helpers.js';
 export { default as yargs } from 'yargs';
 export { hideBin } from 'yargs/helpers';
+export { default as semver } from 'semver';
 export { default as debug } from 'debug';
 export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

package/build/src/tools/categories.js

@@ -13,6 +13,7 @@ export var ToolCategory;
     ToolCategory["DEBUGGING"] = "debugging";
     ToolCategory["EXTENSIONS"] = "extensions";
     ToolCategory["IN_PAGE"] = "in-page";
+    ToolCategory["MEMORY"] = "memory";
 })(ToolCategory || (ToolCategory = {}));
 export const labels = {
     [ToolCategory.INPUT]: 'Input automation',
@@ -23,4 +24,5 @@ export const labels = {
     [ToolCategory.DEBUGGING]: 'Debugging',
     [ToolCategory.EXTENSIONS]: 'Extensions',
     [ToolCategory.IN_PAGE]: 'In-page tools',
+    [ToolCategory.MEMORY]: 'Memory',
 };

package/build/src/tools/memory.js

@@ -6,7 +6,7 @@
 import { zod } from '../third_party/index.js';
 import { ensureExtension } from '../utils/files.js';
 import { ToolCategory } from './categories.js';
-import { definePageTool } from './ToolDefinition.js';
+import { definePageTool, defineTool } from './ToolDefinition.js';
 export const takeMemorySnapshot = definePageTool({
     name: 'take_memory_snapshot',
     description: `Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.`,
@@ -27,3 +27,20 @@ export const takeMemorySnapshot = definePageTool({
         response.appendResponseLine(`Heap snapshot saved to ${request.params.filePath}`);
     },
 });
+export const exploreMemorySnapshot = defineTool({
+    name: 'load_memory_snapshot',
+    description: 'Loads a memory heapsnapshot and returns snapshot summary stats.  ',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['experimentalMemory'],
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+    },
+    handler: async (request, response, context) => {
+        const stats = await context.getHeapSnapshotStats(request.params.filePath);
+        const staticData = await context.getHeapSnapshotStaticData(request.params.filePath);
+        response.setHeapSnapshotStats(stats, staticData);
+    },
+});

package/build/src/tools/network.js

@@ -87,11 +87,11 @@ export const getNetworkRequest = definePageTool({
         requestFilePath: zod
             .string()
             .optional()
-            .describe('The absolute or relative path to save the request body to. If omitted, the body is returned inline.'),
+            .describe('The absolute or relative path to a .network-request file to save the request body to. If omitted, the body is returned inline.'),
         responseFilePath: zod
             .string()
             .optional()
-            .describe('The absolute or relative path to save the response body to. If omitted, the body is returned inline.'),
+            .describe('The absolute or relative path to a .network-response file to save the response body to. If omitted, the body is returned inline.'),
     },
     handler: async (request, response, context) => {
         if (request.params.reqid) {

package/build/src/tools/pages.js

@@ -10,7 +10,7 @@ import { CLOSE_PAGE_ERROR, definePageTool, defineTool, timeoutSchema, } from './
 export const listPages = defineTool(args => {
     return {
         name: 'list_pages',
-        description: `Get a list of pages ${args?.categoryExtensions ? 'including extension service workers' : ''} open in the browser.`,
+        description: `Get a list of pages${args?.categoryExtensions ? ' including extension service workers' : ''} open in the browser.`,
         annotations: {
             category: ToolCategory.NAVIGATION,
             readOnlyHint: true,

package/build/src/utils/check-for-updates.js

@@ -8,6 +8,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
+import { semver } from '../third_party/index.js';
 import { VERSION } from '../version.js';
 /**
  * Notifies the user if an update is available.
@@ -34,7 +35,7 @@ export async function checkForUpdates(message) {
     catch {
         // Ignore errors reading cache.
     }
-    if (cachedVersion && cachedVersion !== VERSION) {
+    if (cachedVersion && semver.lt(VERSION, cachedVersion)) {
         console.warn(`\nUpdate available: ${VERSION} -> ${cachedVersion}\n${message}\n`);
     }
     const now = Date.now();

package/build/src/version.js

@@ -3,4 +3,4 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-export const VERSION = '0.1.0';
+export const VERSION = '0.2.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brave-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP server for Brave DevTools",
   "type": "module",
   "bin": {
@@ -58,6 +58,7 @@
     "@types/debug": "^4.1.12",
     "@types/filesystem": "^0.0.36",
     "@types/node": "^25.0.0",
+    "@types/semver": "^7.7.1",
     "@types/sinon": "^21.0.0",
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
@@ -75,6 +76,7 @@
     "rollup": "4.60.1",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-license": "^3.6.0",
+    "semver": "^7.7.4",
     "sinon": "^21.0.0",
     "tiktoken": "^1.0.22",
     "typescript": "^6.0.2",