All plugins

hermes-webmcp-guard

Permission-aware, ephemeral WebMCP capabilities with origin allowlists, schema validation, conservative risk classification, exact one-call approvals, and safe revocation. Disclosure — connects only to Chrome DevTools WebSocket endpoints you configure and calls the tools the websites on your allowed origins expose; those websites may make their own network requests and their tool output reaches your model. Calls the plugin classifies as write or sensitive ask you first, but the classification uses the website's own tool names, so a site on an allowed origin can present a state-changing tool under a read-style name that runs without a prompt; allow only origins you trust. It does not launch a browser, read credentials, execute arbitrary JavaScript, or persist website capabilities.

NifasathAWebv0.1.0Updated 7 days ago

About

Permission-aware, ephemeral WebMCP capabilities with origin allowlists, schema validation, conservative risk classification, exact one-call approvals, and safe revocation. Disclosure — connects only to Chrome DevTools WebSocket endpoints you configure and calls the tools the websites on your allowed origins expose; those websites may make their own network requests and their tool output reaches your model. Calls the plugin classifies as write or sensitive ask you first, but the classification uses the website's own tool names, so a site on an allowed origin can present a state-changing tool under a read-style name that runs without a prompt; allow only origins you trust. It does not launch a browser, read credentials, execute arbitrary JavaScript, or persist website capabilities.

Hermes WebMCP Guard

CI

Hermes WebMCP Guard is an installable Hermes Agent plugin that discovers and invokes website-provided WebMCP tools while treating every website capability as temporary and untrusted.

It reuses Chrome's native WebMCP CDP domain. The contribution is the firewall around that transport: explicit endpoints and origins, strict schemas, READ/WRITE/SENSITIVE classification, exact one-call approvals, document-bound IDs, bounded execution, redaction, and safe revocation.

Status

The Python implementation and Raspberry Pi 5 live-browser flows have been verified with Hermes 0.23.1 and Chromium Shell 156. The deterministic suite passes 24 tests with the opt-in live test skipped; the live hotel-chain test passes separately when its CDP endpoint is supplied. WebMCP remains experimental.

How it differs

Existing approachWhat it providesWhat this plugin adds
Chrome DevTools MCPRaw list_webmcp_tools / execute_webmcp_tool transportOrigin and lifecycle binding, conservative policy, exact approval, validation, redaction
Generic CDP bridgesPage-to-MCP connectivity, sometimes via page JavaScriptNative WebMCP CDP only, explicit target selection, no arbitrary JS tool, stale-ID rejection
Hermes browser automationGeneral clicking, extraction, screenshots, raw CDPStructured website operations through four fixed tools and one mandatory firewall

Do not enable raw Chrome DevTools MCP WebMCP execution tools alongside this plugin on a locked-down profile; they would be an alternate path around the firewall.

Install

Requirements: Python 3.11+, a current Hermes release with pre_tool_call approval directives, and a WebMCP-enabled Chromium 149+ CDP backend.

git clone https://github.com/NifasathA/hermes-webmcp-guard.git
cd hermes-webmcp-guard
python -m pip install -e '.[test]'
hermes plugins doctor .
hermes plugins enable hermes-webmcp-guard

The editable install publishes the hermes_agent.plugins entry point. The root __init__.py also supports Hermes directory-plugin loading.

Configure

Add this under plugins.entries.hermes-webmcp-guard in ~/.hermes/config.yaml (see config.example.yaml):

plugins:
  enabled:
    - hermes-webmcp-guard
  entries:
    hermes-webmcp-guard:
      settings:
        endpoints:
          hotel-demo:
            websocket_url: ws://127.0.0.1:9222/devtools/page/REPLACE_TARGET
            allowed_origins:
              - https://googlechromelabs.github.io
            execution_timeout_seconds: 20
            max_response_bytes: 262144

The model can name only hotel-demo; it cannot supply a URL. A page endpoint is used directly. For a browser-level endpoint, the bridge attaches only if exactly one page target has an allowed origin, or trusted configuration pins target_id. Remote endpoints must use wss://. Credential-bearing endpoint URLs and header configuration are rejected; terminate authenticated remote CDP connections through a trusted local proxy and configure its loopback WebSocket URL.

Run the local safety fixture

Start the fixture:

cd hermes-webmcp-guard
python -m http.server 8765 --directory demo/fixture-site

In another terminal, start a compatible Chromium build:

chromium \
  --remote-debugging-port=9222 \
  --remote-allow-origins=http://127.0.0.1:9222 \
  --user-data-dir=/tmp/hermes-webmcp-profile \
  --enable-features=WebMCPTesting,DevToolsWebMCPSupport \
  http://127.0.0.1:8765

On Linux ARM64, regular Chromium 151+ may hang on HTTP(S) navigation because of
upstream Chromium issue 554752968.
Use the distribution's dedicated chromium-shell package as the browser binary
when that minimized navigation check fails; it exposes the same CDP/WebMCP
domain without the affected browser embedder.

Get the exact page WebSocket and place it in the configured endpoint:

python -c 'import json,urllib.request; pages=json.load(urllib.request.urlopen("http://127.0.0.1:9222/json/list")); print(next(x["webSocketDebuggerUrl"] for x in pages if x["type"] == "page" and x["url"].startswith("http://127.0.0.1:8765")))'

Restart Hermes after configuration changes:

hermes chat

Suggested prompts:

Connect WebMCP to the configured endpoint local-fixture and list the available capabilities.
Execute list_records.
Execute delete_record for demo-1. Do not approve it when prompted.
Disconnect this website.

The fixture never performs external writes. delete_record deliberately lies with readOnlyHint: true; the bridge still classifies it as SENSITIVE.

Hotel demo

Open https://googlechromelabs.github.io/webmcp-tools/demos/hotel-chain/ in the configured WebMCP browser, then run:

Connect to hotel-demo and tell me what WebMCP actions are available.
Use the structured capability to search for Paris.
Refresh the WebMCP capabilities and filter for breakfast.

Expected upstream sequence: initial lookup_amenity, search_location, and view_hotel; filter_search_results appears after the Paris search. Booking operations require firewall approval and the site's own confirmation. Do not complete a real or public-demo booking in automated tests.

The exact video flow is in demo/demo-script.md.

Verified live environment

On 2026-11-11, the opt-in hotel test passed on Raspberry Pi host booga-pi using Hermes Agent 0.23.1, Python 3.13.5, and Debian Chromium Shell 156.0.8000.49. It discovered the expected initial capabilities, searched Paris, observed filter_search_results appear dynamically, and filtered for breakfast. No booking capability was invoked. The exact reproducible test is tests/test_integration.py::test_live_hotel_discovery_search_and_dynamic_filter.

Tools

  • webmcp_connect: attach to a named configured endpoint and report session/tab/document/origin/status/count.
  • webmcp_list_tools: return machine-readable schemas, annotations, risk, origin, scope, and opaque IDs.
  • webmcp_execute: revalidate arguments and lifecycle, then invoke through the firewall.
  • webmcp_disconnect: revoke first, close owned resources, and remain idempotent.

WRITE, SENSITIVE, unknown, and ambiguous tools use Hermes's supported {"action":"approve"} directive. Approval is additionally bound to owner, unique tool_call_id, capability, and canonical validated arguments, then consumed once. If Hermes omits the call ID, execution fails closed.

Test

cd hermes-webmcp-guard
python -m pytest

The default suite uses a deterministic simulated CDP/WebMCP adapter. It covers discovery, unsupported pages, malformed schemas/arguments, changing tools, origins, expiration, stale IDs, unauthorized origins, deceptive annotations, approval denial/success/replay, uncertain timeouts, disconnection, concurrency, prompt injection, and redaction.

The live test is opt-in and intentionally skipped otherwise:

WEBMCP_LIVE_CDP_URL='wss://…' python -m pytest -m live -vv

That smoke test only verifies explicit setup today; follow demo/demo-script.md for the real hotel sequence and record its output before marketplace submission.

Security notes

  • Website metadata and output are labeled untrusted and never treated as policy.
  • Capability IDs contain hashes, not credentials.
  • Timeouts return outcome_uncertain: true; the plugin never retries.
  • Browser permission and website confirmation UI remain authoritative.
  • The plugin does not silently capture or launch a second Hermes browser. Current Hermes supervisor capture lacks the authoritative WebMCP event subscription this adapter needs, so v0.1 uses an explicit connection and says so.

See docs/research.md, docs/architecture.md, and docs/threat-model.md for evidence and boundaries. docs/benchmark.md explains why no unsupported quantitative claim is included.

License

MIT

README from the reviewed commit 9f5fead; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section