Chrome DevTools for coding agents
feat: memory debugging tools (#2169)
Nikolay Vitkov021739725742
diff --git a/README.md b/README.mdindex b5291249..cfe7dd3e 100644--- a/README.md+++ b/README.md@@ -609,8 +609,8 @@ The Chrome DevTools MCP server supports the following configuration option: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.- **Type:** boolean-- **`--experimentalMemory`/ `--experimental-memory`**- Whether to enable experimental memory tools.+- **`--memoryDebugging`/ `--memory-debugging`, `-experimentalMemory`**+ Whether to enable memory debugging tools.- **Type:** boolean- **`--experimentalStructuredContent`/ `--experimental-structured-content`**diff --git a/docs/tool-reference.md b/docs/tool-reference.mdindex 99fec2df..91380a00 100644--- a/docs/tool-reference.md+++ b/docs/tool-reference.md@@ -457,7 +457,7 @@ in the DevTools Elements panel (if any).### `close_heapsnapshot`-**Description:** Closes a previously loaded memory heapsnapshot, freeing its memory. (requires flag: --experimentalMemory=true)+**Description:** Closes a previously loaded memory heapsnapshot, freeing its memory. (requires flag: --memoryDebugging=true)**Parameters:**@@ -467,7 +467,7 @@ in the DevTools Elements panel (if any).### `get_heapsnapshot_class_nodes`-**Description:** Loads a memory heapsnapshot and returns instances of a specific class with their IDs. (requires flag: --experimentalMemory=true)+**Description:** Loads a memory heapsnapshot and returns instances of a specific class with their IDs. (requires flag: --memoryDebugging=true)**Parameters:**@@ -480,7 +480,7 @@ in the DevTools Elements panel (if any).### `get_heapsnapshot_details`-**Description:** Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --experimentalMemory=true)+**Description:** Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --memoryDebugging=true)**Parameters:**@@ -492,7 +492,7 @@ in the DevTools Elements panel (if any).### `get_heapsnapshot_retainers`-**Description:** Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --experimentalMemory=true)+**Description:** Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --memoryDebugging=true)**Parameters:**@@ -505,7 +505,7 @@ in the DevTools Elements panel (if any).### `get_heapsnapshot_summary`-**Description:** Loads a memory heapsnapshot and returns snapshot summary stats. (requires flag: --experimentalMemory=true)+**Description:** Loads a memory heapsnapshot and returns snapshot summary stats. (requires flag: --memoryDebugging=true)**Parameters:**diff --git a/skills/chrome-devtools/SKILL.md b/skills/chrome-devtools/SKILL.mdindex 1a3cf649..622619bd 100644--- a/skills/chrome-devtools/SKILL.md+++ b/skills/chrome-devtools/SKILL.md@@ -5,9 +5,13 @@ description: Uses Chrome DevTools via MCP for efficient debugging, troubleshooti## Core Concepts-**Browser lifecycle**: Browser starts automatically on first tool call using a persistent Chrome profile. Configure via CLI args in the MCP server configuration: `npx chrome-devtools-mcp@latest --help`. To enable extensions, use `--categoryExtensions`.-**Page selection**: Tools operate on the currently selected page. Use `list_pages` to see available pages, then `select_page` to switch context.+**Browser lifecycle**: Browser starts automatically on first tool call using a persistent Chrome profile. Configure via CLI args in the MCP server configuration: `npx chrome-devtools-mcp@latest --help`.+Addional tooling can be enabled by providing the following flags:++- For extension tooling, use the `--categoryExtensions` flag.+- For memory tooling, use the `--memoryDebugging` flag.+**Page selection**: Tools operate on the currently selected page. Use `list_pages` to see available pages, then `select_page` to switch context.**Element interaction**: Use `take_snapshot` to get page structure with element `uid`s. Each element has a unique `uid` for interaction. If an element isn't found, take a fresh snapshot - the element may have been removed or the page changed.## Workflow Patternsdiff --git a/skills/memory-leak-debugging/SKILL.md b/skills/memory-leak-debugging/SKILL.mdindex c025e332..1aebb197 100644--- a/skills/memory-leak-debugging/SKILL.md+++ b/skills/memory-leak-debugging/SKILL.md@@ -22,11 +22,11 @@ When investigating a frontend web application memory leak, utilize the `chrome-d- Use tools like `click`, `navigate_page`, `fill`, etc., to manipulate the page into the desired state.- Revert the page back to the original state after interactions to see if memory is released.- Repeat the same user interactions 10 times to amplify the leak.-- Use `take_memory_snapshot` to save `.heapsnapshot` files to disk at baseline, target (after actions), and final (after reverting actions) states.+- Use `take_heapsnapshot` to save `.heapsnapshot` files to disk at baseline, target (after actions), and final (after reverting actions) states.### 2. Using Memlab to Find Leaks (Recommended)-Once you have generated `.heapsnapshot` files using `take_memory_snapshot`, use `memlab` to automatically find memory leaks.+Once you have generated `.heapsnapshot` files using `take_heapsnapshot`, use `memlab` to automatically find memory leaks.- Read [references/memlab.md](references/memlab.md) for how to use `memlab` to analyze the generated heapsnapshots.- Do **not** read raw `.heapsnapshot` files using `read_file` or `cat`.diff --git a/skills/memory-leak-debugging/references/memlab.md b/skills/memory-leak-debugging/references/memlab.mdindex 207efdbb..f75efabf 100644--- a/skills/memory-leak-debugging/references/memlab.md+++ b/skills/memory-leak-debugging/references/memlab.md@@ -8,7 +8,7 @@## Analyzing Snapshots-You can use the `take_memory_snapshot` tool provided by the `chrome-devtools-mcp` extension to generate heap snapshots during an investigation. To find leaks, you generally need 3 snapshots:+You can use the `take_heapsnapshot` tool provided by the `chrome-devtools-mcp` extension to generate heap snapshots during an investigation. To find leaks, you generally need 3 snapshots:1. **Baseline:** Before the suspect action.2. **Target:** After the suspect action.diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.mdindex 2eeb817c..6793f996 100644--- a/skills/troubleshooting/SKILL.md+++ b/skills/troubleshooting/SKILL.md@@ -43,7 +43,7 @@ If the server starts successfully but `list_pages` returns an empty list or crea#### Symptom: Missing Tools / Only 9 tools available-If the server starts successfully but only a limited subset of tools (like `list_pages`, `get_console_message`, `lighthouse_audit`, `take_memory_snapshot`) are available, this is likely because the MCP client is enforcing a **read-only mode**.+If the server starts successfully but only a limited subset of tools (like `list_pages`, `get_console_message`, `lighthouse_audit`, `take_heapsnapshot`) are available, this is likely because the MCP client is enforcing a **read-only mode**.All tools in `chrome-devtools-mcp` are annotated with `readOnlyHint: true` (for safe, non-modifying tools) or `readOnlyHint: false` (for tools that modify browser state, like `emulate`, `click`, `navigate_page`). To access the full suite of tools, the user must disable read-only mode in their MCP client (e.g., by exiting "Plan Mode" in Gemini CLI or adjusting their client's tool safety settings).diff --git a/src/bin/chrome-devtools-cli-options.ts b/src/bin/chrome-devtools-cli-options.tsindex 646fe7ca..235c02b3 100644--- a/src/bin/chrome-devtools-cli-options.ts+++ b/src/bin/chrome-devtools-cli-options.ts@@ -83,7 +83,7 @@ export const commands: Commands = {},close_heapsnapshot: {description:- 'Closes a previously loaded memory heapsnapshot, freeing its memory. (requires flag: --experimentalMemory=true)',+ 'Closes a previously loaded memory heapsnapshot, freeing its memory. (requires flag: --memoryDebugging=true)',category: 'Memory',args: {filePath: {@@ -306,7 +306,7 @@ export const commands: Commands = {},get_heapsnapshot_class_nodes: {description:- 'Loads a memory heapsnapshot and returns instances of a specific class with their IDs. (requires flag: --experimentalMemory=true)',+ 'Loads a memory heapsnapshot and returns instances of a specific class with their IDs. (requires flag: --memoryDebugging=true)',category: 'Memory',args: {filePath: {@@ -337,7 +337,7 @@ export const commands: Commands = {},get_heapsnapshot_details: {description:- 'Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --experimentalMemory=true)',+ 'Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --memoryDebugging=true)',category: 'Memory',args: {filePath: {@@ -362,7 +362,7 @@ export const commands: Commands = {},get_heapsnapshot_retainers: {description:- 'Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --experimentalMemory=true)',+ 'Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --memoryDebugging=true)',category: 'Memory',args: {filePath: {@@ -393,7 +393,7 @@ export const commands: Commands = {},get_heapsnapshot_summary: {description:- 'Loads a memory heapsnapshot and returns snapshot summary stats. (requires flag: --experimentalMemory=true)',+ 'Loads a memory heapsnapshot and returns snapshot summary stats. (requires flag: --memoryDebugging=true)',category: 'Memory',args: {filePath: {diff --git a/src/bin/chrome-devtools-mcp-cli-options.ts b/src/bin/chrome-devtools-mcp-cli-options.tsindex f510744d..b65929e1 100644--- a/src/bin/chrome-devtools-mcp-cli-options.ts+++ b/src/bin/chrome-devtools-mcp-cli-options.ts@@ -161,9 +161,10 @@ 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.',},- experimentalMemory: {+ memoryDebugging: {type: 'boolean',- describe: 'Whether to enable experimental memory tools.',+ describe: 'Whether to enable memory debugging tools.',+ alias: 'experimentalMemory',},experimentalStructuredContent: {type: 'boolean',diff --git a/src/telemetry/flag_usage_metrics.json b/src/telemetry/flag_usage_metrics.jsonindex 9982b183..941baad2 100644--- a/src/telemetry/flag_usage_metrics.json+++ b/src/telemetry/flag_usage_metrics.json@@ -222,11 +222,13 @@},{"name": "experimental_memory",- "flagType": "boolean"+ "flagType": "boolean",+ "isDeprecated": true},{"name": "experimental_memory_present",- "flagType": "boolean"+ "flagType": "boolean",+ "isDeprecated": true},{"name": "experimental_navigation_allowlist",@@ -295,5 +297,13 @@{"name": "category_experimental_third_party","flagType": "boolean"+ },+ {+ "name": "memory_debugging_present",+ "flagType": "boolean"+ },+ {+ "name": "memory_debugging",+ "flagType": "boolean"}]diff --git a/src/tools/memory.ts b/src/tools/memory.tsindex 792a0599..3a0519d3 100644--- a/src/tools/memory.ts+++ b/src/tools/memory.ts@@ -44,7 +44,7 @@ export const getHeapSnapshotSummary = defineTool({annotations: {category: ToolCategory.MEMORY,readOnlyHint: true,- conditions: ['experimentalMemory'],+ conditions: ['memoryDebugging'],},schema: {filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),@@ -68,7 +68,7 @@ export const getHeapSnapshotDetails = defineTool({annotations: {category: ToolCategory.MEMORY,readOnlyHint: true,- conditions: ['experimentalMemory'],+ conditions: ['memoryDebugging'],},schema: {filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),@@ -102,7 +102,7 @@ export const getHeapSnapshotClassNodes = defineTool({annotations: {category: ToolCategory.MEMORY,readOnlyHint: true,- conditions: ['experimentalMemory'],+ conditions: ['memoryDebugging'],},schema: {filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),@@ -132,7 +132,7 @@ export const getHeapSnapshotRetainers = defineTool({annotations: {category: ToolCategory.MEMORY,readOnlyHint: true,- conditions: ['experimentalMemory'],+ conditions: ['memoryDebugging'],},blockedByDialog: false,verifyFilesSchema: ['filePath'],@@ -162,7 +162,7 @@ export const closeHeapSnapshot = defineTool({annotations: {category: ToolCategory.MEMORY,readOnlyHint: false,- conditions: ['experimentalMemory'],+ conditions: ['memoryDebugging'],},verifyFilesSchema: ['filePath'],schema: {diff --git a/tests/index.test.ts b/tests/index.test.tsindex d0fb4b6b..952f1cb8 100644--- a/tests/index.test.ts+++ b/tests/index.test.ts@@ -171,6 +171,19 @@ describe('e2e', () => {);});+ it('has memory debugging tools', async () => {+ await withClient(+ async client => {+ const {tools} = await client.listTools();+ const getHeapSnapshotSummary = tools.find(+ t => t.name === 'get_heapsnapshot_summary',+ );+ assert.ok(getHeapSnapshotSummary);+ },+ ['--memoryDebugging'],+ );+ });+it('updates roots when client notifies', async () => {const roots = [{uri: 'file:///test-root', name: 'test-root'}];let resolvePromise: () => void;