Chrome DevTools for coding agents
feat: add a press_key tool (#458)
Alex Rudenkob42739239287
diff --git a/README.md b/README.mdindex 91faecde..e0429202 100644--- a/README.md+++ b/README.md@@ -238,13 +238,14 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles<!-- BEGIN AUTO GENERATED TOOLS -->-- **Input automation** (7 tools)+- **Input automation** (8 tools)- [`click`](docs/tool-reference.md#click)- [`drag`](docs/tool-reference.md#drag)- [`fill`](docs/tool-reference.md#fill)- [`fill_form`](docs/tool-reference.md#fill_form)- [`handle_dialog`](docs/tool-reference.md#handle_dialog)- [`hover`](docs/tool-reference.md#hover)+ - [`press_key`](docs/tool-reference.md#press_key)- [`upload_file`](docs/tool-reference.md#upload_file)- **Navigation automation** (7 tools)- [`close_page`](docs/tool-reference.md#close_page)diff --git a/docs/tool-reference.md b/docs/tool-reference.mdindex a5ca013a..4872226c 100644--- a/docs/tool-reference.md+++ b/docs/tool-reference.md@@ -2,13 +2,14 @@# Chrome DevTools MCP Tool Reference-- **[Input automation](#input-automation)** (7 tools)+- **[Input automation](#input-automation)** (8 tools)- [`click`](#click)- [`drag`](#drag)- [`fill`](#fill)- [`fill_form`](#fill_form)- [`handle_dialog`](#handle_dialog)- [`hover`](#hover)+ - [`press_key`](#press_key)- [`upload_file`](#upload_file)- **[Navigation automation](#navigation-automation)** (7 tools)- [`close_page`](#close_page)@@ -102,6 +103,16 @@---+### `press_key`++**Description:** Press a key or key combination. Use this when other input methods like [`fill`](#fill)() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).++**Parameters:**++- **key** (string) **(required)**: A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta++---+### `upload_file`**Description:** Upload a file through a provided element.diff --git a/src/tools/input.ts b/src/tools/input.tsindex 9913ee56..6e4094dc 100644--- a/src/tools/input.ts+++ b/src/tools/input.ts@@ -7,6 +7,7 @@import type {McpContext, TextSnapshotNode} from '../McpContext.js';import {zod} from '../third_party/index.js';import type {ElementHandle} from '../third_party/index.js';+import {parseKey} from '../utils/keyboard.js';import {ToolCategory} from './categories.js';import {defineTool} from './ToolDefinition.js';@@ -270,3 +271,39 @@ export const uploadFile = defineTool({}},});++export const pressKey = defineTool({+ name: 'press_key',+ description: `Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).`,+ annotations: {+ category: ToolCategory.INPUT,+ readOnlyHint: false,+ },+ schema: {+ key: zod+ .string()+ .describe(+ 'A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta',+ ),+ },+ handler: async (request, response, context) => {+ const page = context.getSelectedPage();+ const tokens = parseKey(request.params.key);+ const [key, ...modifiers] = tokens;++ await context.waitForEventsAfterAction(async () => {+ for (const modifier of modifiers) {+ await page.keyboard.down(modifier);+ }+ await page.keyboard.press(key);+ for (const modifier of modifiers.toReversed()) {+ await page.keyboard.up(modifier);+ }+ });++ response.appendResponseLine(+ `Successfully pressed key: ${request.params.key}`,+ );+ response.setIncludeSnapshot(true);+ },+});diff --git a/src/utils/keyboard.ts b/src/utils/keyboard.tsnew file mode 100644index 00000000..c32b23ae--- /dev/null+++ b/src/utils/keyboard.ts@@ -0,0 +1,304 @@+/**+ * @license+ * Copyright 2025 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */+import type {KeyInput} from '../third_party';++// See the KeyInput type for the list of supported keys.+const validKeys = new Set([+ '0',+ '1',+ '2',+ '3',+ '4',+ '5',+ '6',+ '7',+ '8',+ '9',+ 'Power',+ 'Eject',+ 'Abort',+ 'Help',+ 'Backspace',+ 'Tab',+ 'Numpad5',+ 'NumpadEnter',+ 'Enter',+ '\r',+ '\n',+ 'ShiftLeft',+ 'ShiftRight',+ 'ControlLeft',+ 'ControlRight',+ 'AltLeft',+ 'AltRight',+ 'Pause',+ 'CapsLock',+ 'Escape',+ 'Convert',+ 'NonConvert',+ 'Space',+ 'Numpad9',+ 'PageUp',+ 'Numpad3',+ 'PageDown',+ 'End',+ 'Numpad1',+ 'Home',+ 'Numpad7',+ 'ArrowLeft',+ 'Numpad4',+ 'Numpad8',+ 'ArrowUp',+ 'ArrowRight',+ 'Numpad6',+ 'Numpad2',+ 'ArrowDown',+ 'Select',+ 'Open',+ 'PrintScreen',+ 'Insert',+ 'Numpad0',+ 'Delete',+ 'NumpadDecimal',+ 'Digit0',+ 'Digit1',+ 'Digit2',+ 'Digit3',+ 'Digit4',+ 'Digit5',+ 'Digit6',+ 'Digit7',+ 'Digit8',+ 'Digit9',+ 'KeyA',+ 'KeyB',+ 'KeyC',+ 'KeyD',+ 'KeyE',+ 'KeyF',+ 'KeyG',+ 'KeyH',+ 'KeyI',+ 'KeyJ',+ 'KeyK',+ 'KeyL',+ 'KeyM',+ 'KeyN',+ 'KeyO',+ 'KeyP',+ 'KeyQ',+ 'KeyR',+ 'KeyS',+ 'KeyT',+ 'KeyU',+ 'KeyV',+ 'KeyW',+ 'KeyX',+ 'KeyY',+ 'KeyZ',+ 'MetaLeft',+ 'MetaRight',+ 'ContextMenu',+ 'NumpadMultiply',+ 'NumpadAdd',+ 'NumpadSubtract',+ 'NumpadDivide',+ 'F1',+ 'F2',+ 'F3',+ 'F4',+ 'F5',+ 'F6',+ 'F7',+ 'F8',+ 'F9',+ 'F10',+ 'F11',+ 'F12',+ 'F13',+ 'F14',+ 'F15',+ 'F16',+ 'F17',+ 'F18',+ 'F19',+ 'F20',+ 'F21',+ 'F22',+ 'F23',+ 'F24',+ 'NumLock',+ 'ScrollLock',+ 'AudioVolumeMute',+ 'AudioVolumeDown',+ 'AudioVolumeUp',+ 'MediaTrackNext',+ 'MediaTrackPrevious',+ 'MediaStop',+ 'MediaPlayPause',+ 'Semicolon',+ 'Equal',+ 'NumpadEqual',+ 'Comma',+ 'Minus',+ 'Period',+ 'Slash',+ 'Backquote',+ 'BracketLeft',+ 'Backslash',+ 'BracketRight',+ 'Quote',+ 'AltGraph',+ 'Props',+ 'Cancel',+ 'Clear',+ 'Shift',+ 'Control',+ 'Alt',+ 'Accept',+ 'ModeChange',+ ' ',+ 'Print',+ 'Execute',+ '\u0000',+ 'a',+ 'b',+ 'c',+ 'd',+ 'e',+ 'f',+ 'g',+ 'h',+ 'i',+ 'j',+ 'k',+ 'l',+ 'm',+ 'n',+ 'o',+ 'p',+ 'q',+ 'r',+ 's',+ 't',+ 'u',+ 'v',+ 'w',+ 'x',+ 'y',+ 'z',+ 'Meta',+ '*',+ '+',+ '-',+ '/',+ ';',+ '=',+ ',',+ '.',+ '`',+ '[',+ '\\',+ ']',+ "'",+ 'Attn',+ 'CrSel',+ 'ExSel',+ 'EraseEof',+ 'Play',+ 'ZoomOut',+ ')',+ '!',+ '@',+ '#',+ '$',+ '%',+ '^',+ '&',+ '(',+ 'A',+ 'B',+ 'C',+ 'D',+ 'E',+ 'F',+ 'G',+ 'H',+ 'I',+ 'J',+ 'K',+ 'L',+ 'M',+ 'N',+ 'O',+ 'P',+ 'Q',+ 'R',+ 'S',+ 'T',+ 'U',+ 'V',+ 'W',+ 'X',+ 'Y',+ 'Z',+ ':',+ '<',+ '_',+ '>',+ '?',+ '~',+ '{',+ '|',+ '}',+ '"',+ 'SoftLeft',+ 'SoftRight',+ 'Camera',+ 'Call',+ 'EndCall',+ 'VolumeDown',+ 'VolumeUp',+]);++function throwIfInvalidKey(key: string): KeyInput {+ if (validKeys.has(key)) {+ return key as KeyInput;+ }+ throw new Error(+ `${key} is invalid. Valid keys are: ${Array.from(validKeys.values()).join(',')}.`,+ );+}++/**+ * Returns the primary key, followed by modifiers in original order.+ */+export function parseKey(keyInput: string): [KeyInput, ...KeyInput[]] {+ let key = '';+ const result: KeyInput[] = [];+ for (const ch of keyInput) {+ // Handle cases like Shift++.+ if (ch === '+' && key) {+ result.push(throwIfInvalidKey(key));+ key = '';+ } else {+ key += ch;+ }+ }+ if (key) {+ result.push(throwIfInvalidKey(key));+ }++ if (result.length === 0) {+ throw new Error(`Key ${keyInput} could not be parsed.`);+ }++ if (new Set(result).size !== result.length) {+ throw new Error(`Key ${keyInput} contains duplicate keys.`);+ }++ return [result.at(-1), ...result.slice(0, -1)] as [KeyInput, ...KeyInput[]];+}diff --git a/tests/tools/input.test.ts b/tests/tools/input.test.tsindex b788c7b5..8a621173 100644--- a/tests/tools/input.test.ts+++ b/tests/tools/input.test.ts@@ -15,7 +15,9 @@ import {drag,fillForm,uploadFile,+ pressKey,} from '../../src/tools/input.js';+import {parseKey} from '../../src/utils/keyboard.js';import {serverHooks} from '../server.js';import {html, withBrowser} from '../utils.js';@@ -431,4 +433,64 @@ describe('input', () => {});});});++ describe('press_key', () => {+ it('parses keys', () => {+ assert.deepStrictEqual(parseKey('Shift+A'), ['A', 'Shift']);+ assert.deepStrictEqual(parseKey('Shift++'), ['+', 'Shift']);+ assert.deepStrictEqual(parseKey('Control+Shift++'), [+ '+',+ 'Control',+ 'Shift',+ ]);+ assert.deepStrictEqual(parseKey('Shift'), ['Shift']);+ assert.deepStrictEqual(parseKey('KeyA'), ['KeyA']);+ });+ it('throws on empty key', () => {+ assert.throws(() => {+ parseKey('');+ });+ });+ it('throws on invalid key', () => {+ assert.throws(() => {+ parseKey('aaaaa');+ });+ });+ it('throws on multiple keys', () => {+ assert.throws(() => {+ parseKey('Shift+Shift');+ });+ });++ it('processes press_key', async () => {+ await withBrowser(async (response, context) => {+ const page = context.getSelectedPage();+ await page.setContent(`<!DOCTYPE html><script>+logs=[];+document.addEventListener('keydown', e => logs.push('d'+e.key));+document.addEventListener('keyup', e => logs.push('u'+e.key));+</script>`);+ await context.createTextSnapshot();++ await pressKey.handler(+ {+ params: {+ key: 'Control+Shift+C',+ },+ },+ response,+ context,+ );++ assert.deepStrictEqual(await page.evaluate('logs'), [+ 'dControl',+ 'dShift',+ 'dC',+ 'uC',+ 'uShift',+ 'uControl',+ ]);+ });+ });+ });});