operagx-connector-plus

npm version npm downloads Node.js >=18 License: MIT Open issues

An MCP server that adds real browser interaction — click, type, keyboard, form-fill, drag, scroll, select — on top of the read-only OperaGX connector (go-to-page, list-tabs, tab-content, screenshot, close-tab, history). Run both MCP servers side by side; this one doesn't replace the original, it fills the gap between "read the page" and "act on it."

Why the Chrome DevTools Protocol, not OS-level input

Two ways exist to make an agent actually click/type in a browser:

OS-level hardware events (SendInput on Windows, robotjs, xdotool) — simulate input at the operating system, blind to window coordinates, steal the real mouse cursor, need the window focused and on-screen, and need OS accessibility permissions.
Chrome DevTools Protocol (Input.dispatchMouseEvent / Input.dispatchKeyEvent) — simulates input inside the browser's own input pipeline. Indistinguishable from real hardware input to the page (unlike element.click()/dispatchEvent() in JS, which skip native browser behavior and are trivially detectable by sites), works in the background, doesn't touch the real OS cursor, and needs no extra OS permissions.

Since Opera GX is Chromium-based, it already speaks CDP. This server uses playwright-core purely as a typed CDP client (chromium.connectOverCDP) — no Playwright-managed browser is launched; it attaches to your existing, already-running Opera GX.

Install

npm install
npm run build

Requires Node.js 18+.

Setup

Launch Opera GX with a remote debugging port. Add a flag to wherever you launch it from:
```
--remote-debugging-port=9222
```
This applies to a shortcut's target, a Run-at-login entry, or any launcher — see docs/enabling-cdp.md for exact steps on Windows (taskbar pin, Start Menu shortcut, autostart registry entry).

Register the server with your MCP client. For the Claude Code CLI, at user scope (available in every project):

claude mcp add operagx-connector-plus -s user \
  -e OPERAGX_CDP_URL=http://localhost:9222 \
  -- node /absolute/path/to/operagx-connector-plus/dist/index.js

For other clients, the equivalent JSON config is:

{
  "mcpServers": {
    "operagx-connector-plus": {
      "command": "node",
      "args": ["/absolute/path/to/operagx-connector-plus/dist/index.js"],
      "env": { "OPERAGX_CDP_URL": "http://localhost:9222" }
    }
  }
}

Also register the base OperaGX connector (screenshot, tab-content, go-to-page, ...) — this server is designed to complement it, not replace it. See the section below for the recommended combined workflow.

The interaction loop

This server pairs with the base connector's screenshot tool for visual grounding ("set-of-marks" style):

operagx_map_elements — scans the DOM for clickable/fillable elements, returns each with a small integer id, role, text, and coordinates, and draws numbered badges on the live page.
Call the base connector's screenshot tool — the badges let you visually confirm which numbered id is which element.
operagx_click / operagx_type_text / operagx_fill_form / operagx_select_option / operagx_drag_and_drop / etc., addressed by elementId (preferred), a raw CSS selector, or absolute x/y coordinates.
operagx_clear_annotations when done, so badges don't linger in future screenshots.

Tools

Tool	Does	Read-only	Idempotent
`operagx_list_tabs`	Enumerate tabs with a stable `tabId` usable by every other tool here	✅	✅
`operagx_map_elements`	Map clickable/fillable elements to numbered ids + coordinates, annotate the page	✅	—
`operagx_clear_annotations`	Remove the numbered overlay badges	—	✅
`operagx_click`	Real CDP mouse click (left/right/middle, single/double/triple)	—	—
`operagx_hover`	Move the mouse over an element/point	—	✅
`operagx_type_text`	Focus + type real per-character key events	—	—
`operagx_press_key`	Send a key or chord (`Enter`, `Control+A`, ...)	—	—
`operagx_fill_form`	Fill multiple fields in one call, optional submit key	—	—
`operagx_select_option`	Choose a `<select>` option by value/label/index	—	✅
`operagx_drag_and_drop`	Real mouse-down → move → mouse-up drag	—	—
`operagx_scroll`	Mouse-wheel scroll, or scroll an element into view	—	—
`operagx_wait_for`	Wait for a selector to reach a state (visible/hidden/attached/detached)	✅	✅

Every tool accepts an optional tab selector (tabId, tabIndex, matchUrl, matchTitle); omitting it defaults to the first open tab. Every tool also declares MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and a structured outputSchema, so clients that support structuredContent get typed results, not just text.

Evaluations

evaluations/eval.xml has 10 read-only, verifiable QA pairs for testing whether an LLM can use this server effectively, following the MCP evaluation guidelines. Since this server deliberately has no navigation tool (that's the base connector's job), each question assumes both servers are available, exactly as described above.

Security notes

This server can act on whatever page is open — treat it like giving a script mouse/keyboard access to the browser. Don't point an autonomous agent at a tab with an authenticated session you don't want touched.
There is no execute-script/arbitrary-JS tool by design, to keep the attack surface to well-defined interaction primitives.
CDP is unauthenticated by default on localhost — don't expose the debugging port beyond localhost/a trusted network. This server binds outbound to whatever OPERAGX_CDP_URL you configure; it does not open any listening port itself.
All inputs are validated with Zod .strict() schemas before any tool executes.

Development

npm run dev     # tsc --watch
npm run build   # one-shot build to dist/
npx @modelcontextprotocol/inspector node dist/index.js   # interactive testing

Contributing

See CONTRIBUTING.md.

License

MIT