ego-browser-hermes

Hermes-native MCP adapter for the ego-lite agent browser. It gives Hermes an isolated Chromium task space with structured navigation, semantic snapshots, form interaction, screenshots, uploads, and downloads.

Status

v0.2.0 functional preview

Verified on Windows with Node.js 22 and Hermes Agent:

• TypeScript typecheck passes

• 74 unit/integration tests pass

• MCP stdio initialize and tools/list smoke test passes

• Hermes discovers all 17 safe tools

• Real Chromium smoke opens https://example.com, reads page info and semantic content, captures a screenshot, and closes its task space

The original DSH sidebar/live-view UI has not been ported. This release focuses on the Hermes MCP tool surface and the vendored ego-lite runtime.

Default tools

17 safe tools. The keyboard, scroll and control tools exist so that ordinary interactive work — submitting a search box, reaching lazy-loaded content, letting a human log in — never requires enabling the advanced surface. click and press take onDialog to answer a native alert/confirm/prompt they trigger.

• ego_browser_status

• ego_browser_space_open / ego_browser_space_close / ego_browser_space_list

• ego_browser_navigate / ego_browser_tabs

• ego_browser_snapshot / ego_browser_page_info

• ego_browser_click / ego_browser_fill / ego_browser_press / ego_browser_scroll / ego_browser_wait

• ego_browser_control (hand control to the user / take it back)

• ego_browser_screenshot

• ego_browser_upload / ego_browser_download

Raw JavaScript, CDP, arbitrary CLI scripts, and HTTP requests are disabled by default. They require EGO_BROWSER_ENABLE_ADVANCED=true; EGO_BROWSER_TOOLS can further restrict the exposed set.

Build and verify

npm install
npm run verify

npm run verify runs typecheck, 74 tests, production build, and a real MCP JSON-RPC tool-discovery smoke test.

npm run sim replays a Discord-shaped conversation (login wall, handoff to the human, takeover, search submit, screenshot, download) against the real MCP server over stdio with a faked Chrome — no browser required. The optional real-browser test is:

node scripts/real-browser-smoke.mjs

Hermes installation

See docs/HERMES.md. On the verified Windows setup:

hermes mcp add ego_browser \
  --command C:/Users/msdn/AppData/Local/hermes/node/node.exe \
  --connect-timeout 30 \
  --env EGO_LINUX_DATA_DIR=D:/Users/msdn/Hermes/ego-browser-data \
  --args D:/Users/msdn/Hermes/workspaces/dsh-ego-browser/mcp-server/dist/index.js

hermes mcp test ego_browser

The bundled skill lives at skills/ego-browser-hermes/SKILL.md.

Chat-host notes

Set EGO_BROWSER_OUTPUT_DIR to a directory the agent host can read. Screenshots and downloads without an explicit path land there, so a Discord/Telegram session can attach the file instead of quoting a path on a machine the user cannot see.

The active-space pointer lives in the server process and is shared by every chat that gateway serves; the bundled skill therefore requires an explicit space on every call.

Design and safety

• Local stdio MCP transport; Hermes remains the agent host.

• Browser calls are serialized per server process.

• Commands use spawn() with argv arrays, not shell interpolation.

• navigate only accepts http/https URLs; file:, javascript:, data:, and chrome:// are rejected before launch.

• A failed call (navigate, snapshot, click, fill, wait, screenshot, upload, download, or an advanced tool) does not change the active task space.

• Upload files must exist and use absolute paths.

• Screenshot/download destinations must be absolute.

• Safe downloads do not execute arbitrary trigger JavaScript.

• The runtime cursor identifies itself as Hermes while respecting an explicit user override.

• Control handoff is explicit in both directions: control never takes the browser back on its own.

• A download that completes without producing a file is reported as an error, not as a success.

• A native dialog can only be answered by the call that opened it (onDialog on click/press); observation tools fail fast with that explanation instead of stalling until timeout.

Upstream and attribution

This project adapts work from Fisfzy/dsh-ego-browser and the vendored ego-lite runtime. Upstream notices and runtime patch history are preserved in THIRD_PARTY_NOTICES.md and runtime/PATCHES.md.

License

MIT. Review third-party notices before redistribution.