chromedevtools--chrome-devtools-mcp
Natasha Gorshunova
02b4492ca6
## Support for Network Blocklists and Allowlists (`--blocked-url-pattern` & `--allowed-url-pattern` arguments) This PR adds support for CLI options to restrict network access in the browser session via URL patterns. ### Key Features & How It Works - **Pattern Matching:** Utilizes the [URLPattern Standard](https://urlpattern.spec.whatwg.org/) for pattern matching. - **Target Detachment:** Silently detaches from targets (pages/tabs) whose URLs match blocked patterns (or do not match allowed patterns) upon connection. - **Runtime Blocking:** Prevents navigations and blocks runtime requests (such as fetch/XHR and subresources) if they violate the pattern rules. - **Mutual Exclusivity:** `--blocked-url-pattern` and `--allowed-url-pattern` conflict with each other and cannot be configured simultaneously. - **Browser Requirements:** - **`--allowed-url-pattern`**: Requires **Chrome 149+**. - **`--blocked-url-pattern`**: Works on Chrome versions older than 149, but **Chrome 149+ is highly recommended**. ### Important Limitations & Side Effects - **Network Emulation/Throttling Conflict:** Network throttling is disabled when a network blocklist/allowlist is configured, to avoid conflicting with Puppeteer's underlying blocking mechanisms. - Using the `emulate` tool to modify `networkConditions` (e.g. setting to `Offline`) will throw an error: *`Network throttling is not supported when network blocking (allowlist/blocklist) is configured.`* - Other emulation settings (e.g., `cpuThrottlingRate`, `geolocation`, `viewport`) are unaffected and remain fully functional. --- ### Configuration Examples #### 1. Blocking specific domains or endpoints (Blocklist) Add the `--blocked-url-pattern` options to the `args` list in your MCP settings file: ```json { "mcpServers": { "chrome-devtools": { "command": "npx", "args": [ "chrome-devtools-mcp@latest", "--blocked-url-pattern=*://*.blocked-example.com/*", "--blocked-url-pattern=*://*.another-blocked-example.com/*" ] } } } ``` #### 2. Restricting access to authorized domains (Allowlist) Add the `--allowed-url-pattern` options to restrict the browser to permitted hosts (requires Chrome 149+): ```json { "mcpServers": { "chrome-devtools": { "command": "npx", "args": [ "chrome-devtools-mcp@latest", "--allowed-url-pattern=https://*.allowed-example.com/*", "--allowed-url-pattern=https://*.another-allowed-example.com/*" ] } } } ``` --------- Co-authored-by: Natallia Harshunova <nharshunova@chromium.org> Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
180 行
5.1 KiB
TypeScript
180 行
5.1 KiB
TypeScript
/**
|
|
* @license
|
|
* Copyright 2025 Google LLC
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
import assert from 'node:assert';
|
|
import os from 'node:os';
|
|
import path from 'node:path';
|
|
import {describe, it} from 'node:test';
|
|
|
|
import {executablePath} from 'puppeteer';
|
|
|
|
import {detectDisplay, ensureBrowserConnected, launch} from '../src/browser.js';
|
|
|
|
import {serverHooks} from './server.js';
|
|
|
|
describe('browser', () => {
|
|
it('detects display does not crash', () => {
|
|
detectDisplay();
|
|
});
|
|
|
|
it('cannot launch multiple times with the same profile', async () => {
|
|
const tmpDir = os.tmpdir();
|
|
const folderPath = path.join(tmpDir, `temp-folder-${crypto.randomUUID()}`);
|
|
const browser1 = await launch({
|
|
headless: true,
|
|
isolated: false,
|
|
userDataDir: folderPath,
|
|
executablePath: await executablePath(),
|
|
devtools: false,
|
|
});
|
|
try {
|
|
try {
|
|
const browser2 = await launch({
|
|
headless: true,
|
|
isolated: false,
|
|
userDataDir: folderPath,
|
|
executablePath: await executablePath(),
|
|
devtools: false,
|
|
});
|
|
await browser2.close();
|
|
assert.fail('not reached');
|
|
} catch (err) {
|
|
assert.strictEqual(
|
|
err.message,
|
|
`The browser is already running for ${folderPath}. Use --isolated to run multiple browser instances.`,
|
|
);
|
|
}
|
|
} finally {
|
|
await browser1.close();
|
|
}
|
|
});
|
|
|
|
it('launches with the initial viewport', async () => {
|
|
const tmpDir = os.tmpdir();
|
|
const folderPath = path.join(tmpDir, `temp-folder-${crypto.randomUUID()}`);
|
|
const browser = await launch({
|
|
headless: true,
|
|
isolated: false,
|
|
userDataDir: folderPath,
|
|
executablePath: await executablePath(),
|
|
viewport: {
|
|
width: 1501,
|
|
height: 801,
|
|
},
|
|
devtools: false,
|
|
});
|
|
try {
|
|
const [page] = await browser.pages();
|
|
const result = await page.evaluate(() => {
|
|
return {width: window.innerWidth, height: window.innerHeight};
|
|
});
|
|
assert.deepStrictEqual(result, {
|
|
width: 1501,
|
|
height: 801,
|
|
});
|
|
} finally {
|
|
await browser.close();
|
|
}
|
|
});
|
|
it('connects to an existing browser with userDataDir', async () => {
|
|
const tmpDir = os.tmpdir();
|
|
const folderPath = path.join(tmpDir, `temp-folder-${crypto.randomUUID()}`);
|
|
const browser = await launch({
|
|
headless: true,
|
|
isolated: false,
|
|
userDataDir: folderPath,
|
|
executablePath: await executablePath(),
|
|
devtools: false,
|
|
chromeArgs: ['--remote-debugging-port=0'],
|
|
});
|
|
try {
|
|
const connectedBrowser = await ensureBrowserConnected({
|
|
userDataDir: folderPath,
|
|
devtools: false,
|
|
});
|
|
assert.ok(connectedBrowser);
|
|
assert.ok(connectedBrowser.connected);
|
|
connectedBrowser.disconnect();
|
|
} finally {
|
|
await browser.close();
|
|
}
|
|
});
|
|
|
|
describe('Blocking', () => {
|
|
const server = serverHooks();
|
|
|
|
it('blocks URLs in blocklist', async () => {
|
|
server.addHtmlRoute('/allowed.html', '<html><body>Allowed</body></html>');
|
|
server.addHtmlRoute('/blocked.html', '<html><body>Blocked</body></html>');
|
|
|
|
const browser = await launch({
|
|
headless: true,
|
|
isolated: true,
|
|
executablePath: await executablePath(),
|
|
devtools: false,
|
|
blocklist: ['*://*:*/blocked.html'],
|
|
});
|
|
try {
|
|
const page = await browser.newPage();
|
|
|
|
// Access allowed URL
|
|
await page.goto(server.getRoute('/allowed.html'));
|
|
const content = await page.evaluate(() => document.body.textContent);
|
|
assert.strictEqual(content, 'Allowed');
|
|
|
|
// Fetch of blocked URL from the page
|
|
const fetchSucceeded = await page.evaluate(async url => {
|
|
try {
|
|
await fetch(url);
|
|
return true;
|
|
} catch {
|
|
return false;
|
|
}
|
|
}, server.getRoute('/blocked.html'));
|
|
|
|
assert.strictEqual(fetchSucceeded, false);
|
|
} finally {
|
|
await browser.close();
|
|
}
|
|
});
|
|
|
|
it('blocks URLs not in allowlist', async () => {
|
|
server.addHtmlRoute('/allowed.html', '<html><body>Allowed</body></html>');
|
|
server.addHtmlRoute('/blocked.html', '<html><body>Blocked</body></html>');
|
|
|
|
const browser = await launch({
|
|
headless: true,
|
|
isolated: true,
|
|
executablePath: await executablePath(),
|
|
devtools: false,
|
|
allowlist: ['*://*:*/allowed.html'],
|
|
});
|
|
try {
|
|
const page = await browser.newPage();
|
|
|
|
// Access allowed URL
|
|
await page.goto(server.getRoute('/allowed.html'));
|
|
const content = await page.evaluate(() => document.body.textContent);
|
|
assert.strictEqual(content, 'Allowed');
|
|
|
|
// Fetch of blocked URL from the page
|
|
const fetchSucceeded = await page.evaluate(async url => {
|
|
try {
|
|
await fetch(url);
|
|
return true;
|
|
} catch {
|
|
return false;
|
|
}
|
|
}, server.getRoute('/blocked.html'));
|
|
|
|
assert.strictEqual(fetchSucceeded, false);
|
|
} finally {
|
|
await browser.close();
|
|
}
|
|
});
|
|
});
|
|
});
|