Chrome DevTools for coding agents
docs: fix some reported issues (#3099)
Nikolay Vitkovd5d2f08a3118
diff --git a/docs/configuration.md b/docs/configuration.mdindex a3d93498..b0d33d6c 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -230,7 +230,7 @@ The Chrome DevTools MCP server supports the following configuration option:- **Default:** `false`- **`--allowUnrestrictedPaths`/ `--allow-unrestricted-paths`**- If set, disables the default path restriction that applies when the MCP client does not negotiate the roots capability. By default, file-writing tools are restricted to the OS temp directory when no roots are configured. Use this only when connecting a trusted local client that does not implement MCP roots and requires access to paths outside the temp directory.+ If set, disables the default path restriction that applies when the MCP client does not negotiate the roots capability. By default, tools that read or write local files are restricted to the OS temp directory when no roots are configured. Use this only when connecting a trusted local client that does not implement MCP roots and requires access to paths outside the temp directory.- **Type:** boolean- **Default:** `false`diff --git a/docs/tool-reference.md b/docs/tool-reference.mdindex ace49e47..a64e95f9 100644--- a/docs/tool-reference.md+++ b/docs/tool-reference.md@@ -277,21 +277,21 @@### `emulate`-**Description:** Emulates various features on the target page.+**Description:** Emulates various features on the target page. Each call replaces all emulation settings (except extraHttpHeaders), so pass all desired settings in a single call.**Parameters:**- **pageId** (number) **(required)**: Targets a specific page by ID.-- **colorScheme** (enum: "dark", "light", "auto") _(optional)_: [`Emulate`](#emulate) the dark or the light mode. Set to "auto" to reset to the default.+- **colorScheme** (enum: "dark", "light", "auto") _(optional)_: [`Emulate`](#emulate) the dark or the light mode. Omit or set to "auto" to reset to the default.- **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling- **extraHttpHeaders** (string) _(optional)_: Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.-- **forcedColors** (enum: "active", "none", "auto") _(optional)_: [`Emulate`](#emulate) the `forced-colors` CSS media feature. Set to "auto" to reset to the default.+- **forcedColors** (enum: "active", "none", "auto") _(optional)_: [`Emulate`](#emulate) the `forced-colors` CSS media feature. Omit or set to "auto" to reset to the default.- **geolocation** (string) _(optional)_: Geolocation (`<latitude>,<longitude>`) to [`emulate`](#emulate). Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.- **networkConditions** (enum: "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Omit to disable throttling.-- **prefersContrast** (enum: "more", "less", "custom", "no-preference", "auto") _(optional)_: [`Emulate`](#emulate) the `prefers-contrast` CSS media feature. Set to "auto" to reset to the default.-- **prefersReducedMotion** (enum: "reduce", "no-preference", "auto") _(optional)_: [`Emulate`](#emulate) the `prefers-reduced-motion` CSS media feature. Set to "auto" to reset to the default.-- **userAgent** (string) _(optional)_: User agent to [`emulate`](#emulate). Set to empty string to clear the user agent override.-- **viewport** (string) _(optional)_: [`Emulate`](#emulate) device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to [`emulate`](#emulate) mobile devices. 'landscape' to [`emulate`](#emulate) landscape mode.+- **prefersContrast** (enum: "more", "less", "custom", "no-preference", "auto") _(optional)_: [`Emulate`](#emulate) the `prefers-contrast` CSS media feature. Omit or set to "auto" to reset to the default.+- **prefersReducedMotion** (enum: "reduce", "no-preference", "auto") _(optional)_: [`Emulate`](#emulate) the `prefers-reduced-motion` CSS media feature. Omit or set to "auto" to reset to the default.+- **userAgent** (string) _(optional)_: User agent to [`emulate`](#emulate). Omit or set to empty string to clear the user agent override.+- **viewport** (string) _(optional)_: [`Emulate`](#emulate) device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to [`emulate`](#emulate) mobile devices. 'landscape' to [`emulate`](#emulate) landscape mode. Omit to clear the viewport override.---@@ -384,7 +384,7 @@**Parameters:**- **pageId** (number) **(required)**: Targets a specific page by ID.-- **args** (array) _(optional)_: An optional list of arguments to pass to the function.+- **args** (array) _(optional)_: An optional list of arguments (element uids from the page content snapshot) to pass to the function.- **dialogAction** (string) _(optional)_: Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.- **filePath** (string) _(optional)_: The absolute or relative path to a file to save the script output to. If omitted, the output is returned inline.- **format** (enum: "function", "script") _(optional)_: How to interpret the source. "function" treats it as a function declaration and supports args. "script" evaluates it as classic JavaScript and does not support args. Defaults to "function". ECMAScript modules are not supported.diff --git a/skills/chrome-devtools-cli/SKILL.md b/skills/chrome-devtools-cli/SKILL.mdindex 5a4348aa..7e50f198 100644--- a/skills/chrome-devtools-cli/SKILL.md+++ b/skills/chrome-devtools-cli/SKILL.md@@ -66,7 +66,7 @@ chrome-devtools list_pages # Get a list of pages open in the browserchrome-devtools navigate_page 1 --url "https://example.com" # Navigates the currently selected page to a URLchrome-devtools navigate_page 1 --type "reload" --ignoreCache true # Reload page ignoring cachechrome-devtools navigate_page 1 --url "https://example.com" --timeout 5000 # Navigate with a timeout-chrome-devtools navigate_page 1 --handleBeforeUnload "accept" # Handle before unload dialog+chrome-devtools navigate_page 1 --type "reload" --handleBeforeUnload "accept" # Handle before unload dialogchrome-devtools navigate_page 1 --type "back" --initScript "foo()" # Navigate back and run an init scriptchrome-devtools new_page "https://example.com" # Creates a new pagechrome-devtools new_page "https://example.com" --background true --timeout 5000 # Create new page in background@@ -77,18 +77,20 @@ chrome-devtools select_page 1 --bringToFront true # Select a page and bring it t## Emulation+Each `emulate` call replaces all previously configured emulation settings (except `--extraHttpHeaders`), so pass all desired settings in a single call.+```bash-chrome-devtools emulate 1 --networkConditions "Offline" # Emulate network conditions-chrome-devtools emulate 1 --cpuThrottlingRate 4 --geolocation "0,0" # Emulate CPU throttling and geolocation-chrome-devtools emulate 1 --colorScheme "dark" --viewport "1920x1080" # Emulate color scheme and viewport-chrome-devtools emulate 1 --userAgent "Mozilla/5.0..." # Emulate user agent+chrome-devtools emulate 1 --networkConditions "Offline" # Emulate network conditions (resets other settings)+chrome-devtools emulate 1 --cpuThrottlingRate 4 --geolocation "0,0" # Emulate CPU throttling and geolocation (resets other settings)+chrome-devtools emulate 1 --colorScheme "dark" --viewport "1920x1080" # Emulate color scheme and viewport (resets other settings)+chrome-devtools emulate 1 --userAgent "Mozilla/5.0..." # Emulate user agent (resets other settings)chrome-devtools resize_page 1 1920 1080 # Resizes the selected page's window```## Performance```bash-chrome-devtools performance_analyze_insight 1 "1" "LCPBreakdown" # Get more details on a specific Performance Insight (pageId, insightSetId, insightName)+chrome-devtools performance_analyze_insight 1 "NAVIGATION_0" "LCPBreakdown" # Get more details on a specific Performance Insight (pageId, insightSetId, insightName)chrome-devtools performance_start_trace 1 --reload true --autoStop false # Starts a performance trace recording (reload, autoStop)chrome-devtools performance_start_trace 1 --reload true --autoStop true --filePath "t.json.gz" # Start trace and save to a filechrome-devtools performance_stop_trace 1 # Stops the active performance trace@@ -122,10 +124,10 @@ chrome-devtools close_heapsnapshot "./snap.heapsnapshot" # Free memory from load```bashchrome-devtools get_network_request 1 # Get the currently selected network request for page 1chrome-devtools get_network_request 1 --reqid 1 --requestFilePath "req.md" # Get request by id and save to file-chrome-devtools get_network_request 1 --responseFilePath "res.md" # Save response body to file+chrome-devtools get_network_request 1 --reqid 1 --responseFilePath "res.md" # Save response body to filechrome-devtools list_network_requests 1 # List all network requests for page 1chrome-devtools list_network_requests 1 --pageSize 50 --pageIdx 0 # List network requests with pagination-chrome-devtools list_network_requests 1 --resourceTypes Fetch # Filter requests by resource type+chrome-devtools list_network_requests 1 --resourceTypes fetch # Filter requests by resource typechrome-devtools list_network_requests 1 --includePreservedRequests true # Include preserved requests```diff --git a/skills/debug-optimize-lcp/SKILL.md b/skills/debug-optimize-lcp/SKILL.mdindex 4067d908..89b48b64 100644--- a/skills/debug-optimize-lcp/SKILL.md+++ b/skills/debug-optimize-lcp/SKILL.md@@ -62,7 +62,7 @@ The `url` field tells you what resource to look for in the network waterfall. IfUse `list_network_requests` to see when the LCP resource loaded relative to other resources:-- Call `list_network_requests` with `pageId` filtered by `resourceTypes: ["Image", "Font"]` (adjust based on Step 3).+- Call `list_network_requests` with `pageId` filtered by `resourceTypes: ["image", "font"]` (adjust based on Step 3).- Then use `get_network_request` with `pageId` and the LCP resource's request ID for full details.**Key Checks:**diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.mdindex 72e45aec..94a23d4c 100644--- a/skills/troubleshooting/SKILL.md+++ b/skills/troubleshooting/SKILL.md@@ -9,7 +9,7 @@ You are acting as a troubleshooting wizard to help the user configure and fix th### Step 1: Find and Read Configuration-Your first action should be to locate and read the MCP configuration file. Search for the following files in the user's workspace: `.mcp.json`, `gemini-extension.json`, `.claude/settings.json`, `.vscode/launch.json`, or `.gemini/settings.json`.+Your first action should be to locate and read the MCP configuration file. Search for the following files in the user's workspace: `.mcp.json`, `.vscode/mcp.json`, `gemini-extension.json`, or `.gemini/settings.json` (or user-scoped files such as `~/.claude.json` if accessible).If you find a configuration file, read and interpret it to identify potential issues such as:diff --git a/src/McpContext.ts b/src/McpContext.tsindex 06b361d6..c1ee385a 100644--- a/src/McpContext.ts+++ b/src/McpContext.ts@@ -65,8 +65,9 @@ interface McpContextOptions {// The block list of URL patterns to block loading resources.blocklist?: string[];// Whether to skip path validation when the client did not negotiate the roots- // capability. When false (default), file-writing tools are restricted to the- // OS temp directory. When true, the previous permissive behavior is restored.+ // capability. When false (default), tools that read or write local files are+ // restricted to the OS temp directory. When true, the previous permissive+ // behavior is restored.allowUnrestrictedPaths?: boolean;// Whether this context replaces a previous one after a browser reconnect.// Surfaces a one-time note in the next response.diff --git a/src/config/cli-options.ts b/src/config/cli-options.tsindex 55a5cd76..0325d3b3 100644--- a/src/config/cli-options.ts+++ b/src/config/cli-options.ts@@ -231,7 +231,8 @@ export const commands: Commands = {},},emulate: {- description: 'Emulates various features on the target page.',+ description:+ 'Emulates various features on the target page. Each call replaces all emulation settings (except extraHttpHeaders), so pass all desired settings in a single call.',category: 'Emulation',args: {pageId: {@@ -265,14 +266,14 @@ export const commands: Commands = {name: 'userAgent',type: 'string',description:- 'User agent to emulate. Set to empty string to clear the user agent override.',+ 'User agent to emulate. Omit or set to empty string to clear the user agent override.',required: false,},colorScheme: {name: 'colorScheme',type: 'string',description:- 'Emulate the dark or the light mode. Set to "auto" to reset to the default.',+ 'Emulate the dark or the light mode. Omit or set to "auto" to reset to the default.',required: false,enum: ['dark', 'light', 'auto'],},@@ -280,7 +281,7 @@ export const commands: Commands = {name: 'forcedColors',type: 'string',description:- 'Emulate the `forced-colors` CSS media feature. Set to "auto" to reset to the default.',+ 'Emulate the `forced-colors` CSS media feature. Omit or set to "auto" to reset to the default.',required: false,enum: ['active', 'none', 'auto'],},@@ -288,7 +289,7 @@ export const commands: Commands = {name: 'prefersContrast',type: 'string',description:- 'Emulate the `prefers-contrast` CSS media feature. Set to "auto" to reset to the default.',+ 'Emulate the `prefers-contrast` CSS media feature. Omit or set to "auto" to reset to the default.',required: false,enum: ['more', 'less', 'custom', 'no-preference', 'auto'],},@@ -296,7 +297,7 @@ export const commands: Commands = {name: 'prefersReducedMotion',type: 'string',description:- 'Emulate the `prefers-reduced-motion` CSS media feature. Set to "auto" to reset to the default.',+ 'Emulate the `prefers-reduced-motion` CSS media feature. Omit or set to "auto" to reset to the default.',required: false,enum: ['reduce', 'no-preference', 'auto'],},@@ -304,7 +305,7 @@ export const commands: Commands = {name: 'viewport',type: 'string',description:- "Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.",+ "Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode. Omit to clear the viewport override.",required: false,},extraHttpHeaders: {@@ -353,7 +354,8 @@ export const commands: Commands = {args: {name: 'args',type: 'array',- description: 'An optional list of arguments to pass to the function.',+ description:+ 'An optional list of arguments (element uids from the page content snapshot) to pass to the function.',required: false,},filePath: {diff --git a/src/config/mcp-options.ts b/src/config/mcp-options.tsindex 06df883b..47e41424 100644--- a/src/config/mcp-options.ts+++ b/src/config/mcp-options.ts@@ -185,7 +185,7 @@ export const mcpOptions = {deprecated: 'Use --workspace=/ instead.',describe:'If set, disables the default path restriction that applies when the MCP client does not negotiate ' +- 'the roots capability. By default, file-writing tools are restricted to the OS temp directory when ' ++ 'the roots capability. By default, tools that read or write local files are restricted to the OS temp directory when ' +'no roots are configured. Use this only when connecting a trusted local client that does not implement ' +'MCP roots and requires access to paths outside the temp directory.',},diff --git a/src/index.ts b/src/index.tsindex b2cf5ef2..c5d82599 100644--- a/src/index.ts+++ b/src/index.ts@@ -122,7 +122,7 @@ export class McpServer {) {console.warn('[chrome-devtools-mcp] The connecting client did not negotiate the MCP roots ' +- 'capability. File-writing tools will be restricted to the OS temp directory. ' ++ 'capability. Tools that read or write local files will be restricted to the OS temp directory. ' +'To restore the previous unrestricted behavior, start the server with ' +'--allow-unrestricted-paths.',);diff --git a/src/tools/emulation.ts b/src/tools/emulation.tsindex 7ccacb6a..06c53b77 100644--- a/src/tools/emulation.ts+++ b/src/tools/emulation.ts@@ -52,7 +52,7 @@ const throttlingOptions: [string, ...string[]] = [export const emulate = definePageTool(() => ({name: 'emulate',- description: `Emulates various features on the target page.`,+ description: `Emulates various features on the target page. Each call replaces all emulation settings (except extraHttpHeaders), so pass all desired settings in a single call.`,annotations: {category: ToolCategory.EMULATION,readOnlyHint: false,@@ -81,38 +81,38 @@ export const emulate = definePageTool(() => ({.string().optional().describe(- 'User agent to emulate. Set to empty string to clear the user agent override.',+ 'User agent to emulate. Omit or set to empty string to clear the user agent override.',),colorScheme: zod.enum(['dark', 'light', 'auto']).optional().describe(- 'Emulate the dark or the light mode. Set to "auto" to reset to the default.',+ 'Emulate the dark or the light mode. Omit or set to "auto" to reset to the default.',),forcedColors: zod.enum([...FORCED_COLORS_VALUES, 'auto']).optional().describe(- 'Emulate the `forced-colors` CSS media feature. Set to "auto" to reset to the default.',+ 'Emulate the `forced-colors` CSS media feature. Omit or set to "auto" to reset to the default.',),prefersContrast: zod.enum([...PREFERS_CONTRAST_VALUES, 'auto']).optional().describe(- 'Emulate the `prefers-contrast` CSS media feature. Set to "auto" to reset to the default.',+ 'Emulate the `prefers-contrast` CSS media feature. Omit or set to "auto" to reset to the default.',),prefersReducedMotion: zod.enum([...PREFERS_REDUCED_MOTION_VALUES, 'auto']).optional().describe(- 'Emulate the `prefers-reduced-motion` CSS media feature. Set to "auto" to reset to the default.',+ 'Emulate the `prefers-reduced-motion` CSS media feature. Omit or set to "auto" to reset to the default.',),viewport: zod.string().transform(viewportTransform).optional().describe(- `Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.`,+ `Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode. Omit to clear the viewport override.`,),extraHttpHeaders: zod.string()diff --git a/src/tools/script.ts b/src/tools/script.tsindex e9550e51..4c426c39 100644--- a/src/tools/script.ts+++ b/src/tools/script.ts@@ -68,7 +68,9 @@ Example with arguments: \`(el) => el.innerText\`),).optional()- .describe(`An optional list of arguments to pass to the function.`),+ .describe(+ `An optional list of arguments (element uids from the page content snapshot) to pass to the function.`,+ ),filePath: zod.string().optional()