feat: add press_key MCP tool for keyboard input simulation by jasonanovak · Pull Request #82 · mozilla/firefox-devtools-mcp

jasonanovak · 2026-05-03T12:55:41Z

Lets the model send keyboard input to the browser — named keys (Enter, Escape, Tab, arrows, F1–F12), modifier combinations (ctrl+l, ctrl+shift+t, alt+F4), or plain characters — directed at a specific snapshot element (uid) or at the currently focused element.

Implementation:

dom.ts: add KEY_MAP and MODIFIER_MAP (named keys and modifier aliases mapped to Selenium Key.* unicode constants) and a pressKey(key, uid?) method that parses "ctrl+shift+t"-style combos. With a uid it routes through Key.chord + sendKeys on the element; without one it drives selenium's W3C Actions keyboard source directly so the key goes to the active element.
firefox/index.ts: expose FirefoxClient.pressKey with a not-connected guard.
tools/input.ts: define pressKeyTool schema and handlePressKey, with the same UID error mapping used by the other input tools.
tools/index.ts, src/index.ts: register the tool and handler.

Also drops an orphaned yaml dev-dependency entry from package-lock.

juliandescottes

Can you amend the commit to not be co-authored by the agent?

(I had a PR to add this to AGENTS.md, but I only merged it today sorry!)

Otherwise the feature looks useful. There's a small gap in terms of inputs if you want to type text in a field, you either have fill_by_uid, which overwrites everything. Or we could reuse that new tool, but at the moment it's really meant for single key usage.

One thing to note is that after using the tool a bit, the agent started using it to type text, one command per character. Either we update the description to explain that you can actually send several keys at once, or we make it really clear that this should not be used for typing.

Could you add some tests as well?

juliandescottes · 2026-05-04T06:48:47Z

+
+    try {
+      await firefox.pressKey(key, uid);
+      return successResponse(uid ? `✅ press_key "${key}" on ${uid}` : `✅ press_key "${key}"`);


Remove the emojis from the logs

juliandescottes · 2026-05-04T06:54:29Z

Is the package-lock update necessary? If not, can you remove it from this changeset?

Removed it.

juliandescottes · 2026-05-04T07:00:50Z

+      // Key.chord concatenates modifiers + key + Key.NULL (releases all modifiers)
+      await el.sendKeys(Key.chord(...modifiers, mainKey));
+    } else {
+      // Send to the currently focused element via W3C Actions keyboard source


Maybe WebDriver instead of W3C ? https://www.w3.org/TR/webdriver2/#actions

W3C actions is a bit vague.

made this webdriver consistently

juliandescottes · 2026-05-04T07:01:13Z

+      // Key.chord concatenates modifiers + key + Key.NULL (releases all modifiers)
+      await el.sendKeys(Key.chord(...modifiers, mainKey));
+    } else {
+      // Send to the currently focused element via W3C Actions keyboard source


Maybe WebDriver instead of W3C ? https://www.w3.org/TR/webdriver2/#actions

W3C actions is a bit vague.

made this webdriver consistently

juliandescottes · 2026-05-04T08:07:55Z

+// Map of lowercase key names → Selenium unicode values
+const KEY_MAP: Record<string, string> = {
+  enter: Key.RETURN,
+  return: Key.RETURN,


RETURN and ENTER are mapped to different keys in selenium, I think we should stick to that. https://github.com/SeleniumHQ/selenium/blob/trunk/javascript/selenium-webdriver/lib/input.js#L53-L54

Overall we are missing a few keys, might be good to add them.

Changed the mapping and added the keys that are in selenium.

I didn't realize that Selenium's Key.ENTER was the numpad one. I'm not sure what's the best approach between being faithful to selenium's Key definition or aliasing enter to Key.RETURN.

It probably doesn't change much in most cases, but maybe for now we should revert to what you had, and add numpadenter: Key.ENTER?

Measured: Return arrives as code=Enter, Enter as code=NumpadEnter. +1 to enter -> Key.RETURN plus numpadenter: Key.ENTER.

juliandescottes · 2026-05-04T08:20:12Z

+      if (part in MODIFIER_MAP) {
+        modifiers.push(MODIFIER_MAP[part]!);
+      } else {
+        mainKey = KEY_MAP[part] ?? part;


Consider throwing here if mainKey was already set. I asked it to press ctrl+k+l, which resulted in only ctrl+l being sent.

Maybe adapt the tool description as well to mention that you can use many modifiers, but only one key?

juliandescottes · 2026-07-30T16:56:43Z

@jasonanovak we would still be interested to merge this PR if you have time to update it.

In case we don't hear back or if you can't update it, hopefully it's fine if I rebase it and apply my suggestions in a followup.

jasonanovak · 2026-08-17T00:22:01Z

Hi @juliandescottes sorry for the delayed response. Life got nuts. I am going to update the PR now and address your comments.

Sends a single key, optionally with modifiers, either to a snapshot element or to whatever currently has focus. Covers submitting (Return), dismissing (Escape), navigating (Tab, arrows) and shortcuts such as ctrl+shift+t. Key names map to the WebDriver code points selenium exposes as Key.*, keeping return and enter distinct as selenium does. Combinations accept any number of modifiers but exactly one key, so "ctrl+k+l" is rejected rather than silently dropping a key, and unknown multi-character names are rejected rather than being typed as text.

jasonanovak · 2026-08-17T01:13:12Z

Ok! Made the changes.

Added tests as well.

Finally, tried to make it clear that this wasn't for typing and that's more fill_by_uid.

juliandescottes · 2026-08-18T08:59:03Z

Thanks @jasonanovak !

Will take a look today, cc-ing @freema for review as well since he's working on a similar PR.

juliandescottes

Sorry for the delay! Main comment is that we should try to consistently use actions and stop falling back to sendKey if a uid is passed.

Once the last comments are addressed we should be good to go!

Thanks

juliandescottes · 2026-08-20T21:24:56Z

+        throw new Error('pressKey: resolveUid callback not set. Ensure snapshot is initialized.');
+      }
+      const el = await this.resolveUid(uid);
+      await el.sendKeys(Key.chord(...modifiers, mainKey));


Instead of using sendKeys when we have a uid and actions in the other case, could we try to focus the element corresponding to the uid and then use actions ?

Otherwise I'm worried we would get slightly different behaviors when using a uid or not.

+1, measured: Key.chord appends Key.NULL and Element Send Keys dispatches it, so press_key Escape with a uid yields Escape plus a phantom Unidentified keydown/keyup (actions path: Escape only). On <input type=file> it fails with File not found:, which handleUidError rewrites to "stale uid, take_snapshot", so the model loops. Focus-then-actions fixes both locally; a non-focusable uid then needs its own error, and the caret lands at the start of a contenteditable instead of the end.

juliandescottes · 2026-08-20T21:52:28Z

+// Map of lowercase key names → Selenium unicode values
+const KEY_MAP: Record<string, string> = {
+  enter: Key.RETURN,
+  return: Key.RETURN,


I didn't realize that Selenium's Key.ENTER was the numpad one. I'm not sure what's the best approach between being faithful to selenium's Key definition or aliasing enter to Key.RETURN.

It probably doesn't change much in most cases, but maybe for now we should revert to what you had, and add numpadenter: Key.ENTER?

juliandescottes · 2026-08-20T21:56:28Z

+      key: {
+        type: 'string',
+        description:
+          'One key, optionally preceded by "+"-separated modifiers, such as "Escape", "F5" or "ctrl+shift+t". Modifiers: ctrl, alt, shift, meta. Named keys: Enter (numpad), Return, Tab, Backspace, Delete, Insert, Space, Escape, Home, End, PageUp, PageDown, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, F1-F12, Numpad0-Numpad9, Clear, Pause, Help, Cancel, Semicolon, Equals, Add, Subtract, Multiply, Divide, Decimal, Separator. Anything else must be a single character.',


Might be confusing to mention F5 here. Most readers (and models) would probably interpret that as the "reload" shortcut, but it would only work from Chrome/privileged context, and will be misleading in other situations.

To be safe I would remove it.

ctrl+shift+t has the same issue: from content neither triggers the browser action (checked: tab count unchanged, no reload). A page-level example like shift+Tab would be safer. On macOS ctrl+a also does not select all (meta+a does).

freema

Thanks for picking this up @jasonanovak, and thanks @juliandescottes for the ping. Ran the branch against Firefox 154 (macOS, headless): lint, typecheck, tests and build green, merges cleanly with main; measurements behind Julian's points are in the threads. Nothing exercises DomInteractions.pressKey itself, I can port the integration test from #153 if useful (the README tool overview could list press_key too). Once the uid path goes through actions I am happy and will rebase #153 on top so it shrinks to type_text.

juliandescottes requested changes May 4, 2026

View reviewed changes

jasonanovak force-pushed the inputsimulation branch from 19ee6e2 to 0663bd7 Compare August 17, 2026 01:08

juliandescottes mentioned this pull request Aug 17, 2026

feat: add press_key and type_text tools #153

Open

juliandescottes requested a review from freema August 18, 2026 08:59

juliandescottes requested changes Aug 20, 2026

View reviewed changes

freema reviewed Aug 23, 2026

View reviewed changes

Uh oh!

Conversation

jasonanovak commented May 3, 2026

Uh oh!

juliandescottes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juliandescottes commented Jul 30, 2026

Uh oh!

jasonanovak commented Aug 17, 2026

Uh oh!

jasonanovak commented Aug 17, 2026

Uh oh!

juliandescottes commented Aug 18, 2026

Uh oh!

juliandescottes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

freema left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

freema left a comment •

edited

Loading