feat: add experimental WebMCP fast path via Chrome CDP

[alectimison-maker]

Summary

This pull request adds an experimental, opt-in WebMCP fast path to WebBrain. When the user enables Experimental WebMCP under Settings → General → Advanced, supporting Chrome pages let the agent discover and invoke structured capabilities registered by the page through Chrome DevTools Protocol instead of relying exclusively on screenshots, accessibility-tree targeting, or DOM interaction. The setting is off by default, so ordinary runs do not receive WebMCP tool schemas or prompt guidance.

The existing browser interaction stack remains the fallback for pages that do not expose WebMCP tools.

Motivation

WebBrain already supports visual, accessibility-tree, DOM, and limited observed-API interaction paths. Those approaches remain important, but they can be inefficient or brittle when a site offers an explicit machine-readable operation. WebMCP provides a browser-native way for a cooperating page to publish structured tool names, descriptions, input schemas, and callbacks while preserving the user's active browser session and page state.

This implementation follows the experimental Chrome CDP WebMCP domain and deliberately treats the page as an untrusted security principal.

What changed

Chrome CDP integration

• Added per-tab WebMCP sessions backed by WebMCP.enable and WebMCP.disable.
• Maintains a live catalog from WebMCP.toolsAdded and WebMCP.toolsRemoved events.
• Invokes registered callbacks through WebMCP.invokeTool and consumes asynchronous WebMCP.toolResponded events.
• Handles the protocol race where a response event can arrive around the command response.
• Cancels pending invocations on timeout, user stop, session cleanup, or debugger detach.
• Reports dispatched failures as outcome-unknown because the page may have changed state before returning an error.

Agent tools and routing

• Added a Chrome-only Experimental WebMCP toggle under Settings → General → Advanced; it defaults off.
• While disabled, WebMCP tool schemas and prompt guidance are omitted from model requests. Turning it off also closes active WebMCP CDP sessions.
• Added list_webmcp_tools for bounded, paginated capability discovery.
• Added execute_webmcp_tool for invoking a catalog entry through an opaque wmcp_* identifier.
• When enabled, exposes discovery in Ask, Act, and Dev on supported Chrome tool surfaces.
• Restricts execution to Act/Dev and Mid/Full tiers; Compact remains intentionally narrow.
• Marks execution as state-changing and navigation-prone so normal screenshot, navigation, loop, and completion-verification behavior still applies.
• Preserves existing accessibility-tree, DOM, and screenshot tools as the fallback path.

Security and trust boundaries

• Treats WebMCP names, descriptions, schemas, annotations, frame URLs, outputs, exceptions, and errors as page-supplied untrusted content.
• Routes discovery and execution results through the existing untrusted-content wrapper to prevent prompt-boundary breakout.
• Uses opaque local IDs instead of page-controlled tool names as model-call handles.
• Does not trust page-authored readOnly annotations as an authorization boundary.
• Allows Ask mode to list tools but never invoke them.
• Requires Act/Dev, fresh per-call confirmation, and the normal capability permission for every invocation.
• Charges permission to the actual registration-frame host rather than the top-level page host.
• Fails closed for missing, opaque, sandboxed, or non-HTTP(S) frame origins.
• Revalidates the frame ID and effective security origin immediately before dispatch, preventing a navigated iframe from borrowing a previously approved host grant.
• Bounds the catalog to 200 tools, returns at most 25 tools per page, sanitizes page-controlled schemas and outputs, and rejects oversized or non-serializable inputs before dispatch.

Browser compatibility

• Chrome receives the experimental CDP implementation behind the default-off opt-in.
• Firefox keeps mirrored schemas/security classifications for parity but does not expose the tools at runtime and returns an explicit unsupported/no-dispatch result if called internally.

Documentation

Updated the README and architecture, privacy/data-flow, prompt-injection, security-model, and testing documentation to describe:

• where to enable WebMCP and its default-off behavior;
• when WebMCP is available;
• what data enters model context;
• the untrusted-page boundary;
• permission and confirmation behavior;
• Chrome/Firefox differences;
• how to run the real-browser smoke test.

Testing

Main unit suite

node test/run.js

• 1,104 passed
• 0 failed
• 1,104 total
• All WebMCP regression tests pass, including the default-off model-context gate and mandatory per-invocation confirmation/frame-host permission under bypass modes.

The WebMCP coverage includes:

• feature, mode, and provider-tier gating;
• opaque IDs, pagination, and frame mapping;
• asynchronous invocation and early response races;
• untrusted-content boundary neutralization;
• hostile catalog and input limits;
• unsupported-domain cleanup;
• timeout, cancellation, and outcome-unknown behavior;
• permission metadata ownership;
• Ask-mode denial even for page-declared read-only tools;
• cross-origin frame permission scoping;
• opaque-origin and navigation-race fail-closed behavior;
• Firefox unsupported behavior.

Prompt-injection corpus

node test/security/injection-corpus.mjs

• 60/60 checks passed across Chrome and Firefox.

Existing browser fixtures

npm run test:fixtures

• 114 passed
• 0 failed

Real Chrome WebMCP smoke test

python test/webmcp-e2e.py against the included local fixture, using Chrome 150 with WebMCPTesting,DevToolsWebMCPSupport enabled:

• discovered two page-registered tools through CDP;
• transported the declared input schema;
• completed an asynchronous structured invocation;
• verified the resulting page UI state;
• propagated a predictable JavaScript exception;
• observed dynamic tool unregistration.

Packaging and static validation

• npm run build:zip successfully produced Chrome, Edge, and Firefox packages.
• JavaScript syntax checks passed for all touched agent, CDP, permission, and tool files.
• Python compilation passed for the WebMCP smoke test.
• git diff --check passed.

CI harness

npm run test:ci

• 9 scenarios validated
• cloud capture test passed

Local validation

No local test failures remain after merging current main.

Notes

WebMCP is experimental and only accelerates cooperating pages that register tools. It is not a general mechanism for reading arbitrary backend databases or bypassing site authorization. When the API or a relevant tool is unavailable, WebBrain continues through its established accessibility-tree, DOM, screenshot, and observed-API paths.

[vercel]

@alectimison-maker is attempting to deploy a commit to the esokullu's projects Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

Pull request overview

Adds an experimental Chrome-only WebMCP fast path while preserving existing browser interaction fallbacks.

Changes:

• Adds CDP-based WebMCP discovery and invocation.
• Integrates permission, confirmation, trust-boundary, and completion handling.
• Adds fixtures, regression coverage, documentation, and a real-Chrome smoke test.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/chrome/src/cdp/cdp-client.js	Implements WebMCP sessions, discovery, invocation, and cleanup.
src/chrome/src/agent/agent.js	Integrates execution, confirmation, routing, and lifecycle handling.
src/chrome/src/agent/tools.js	Defines and gates WebMCP agent tools.
src/chrome/src/agent/permission-gate.js	Classifies WebMCP permissions and untrusted results.
src/chrome/src/agent/completion-invariant.js	Requires post-invocation verification.
src/firefox/src/agent/agent.js	Returns explicit unsupported results.
src/firefox/src/agent/tools.js	Mirrors schemas and gating definitions.
src/firefox/src/agent/permission-gate.js	Mirrors security classifications.
src/firefox/src/agent/completion-invariant.js	Maintains completion parity.
test/run.js	Adds WebMCP regression tests.
test/webmcp-e2e.py	Adds a real-Chrome CDP smoke test.
test/fixtures/webmcp-page.html	Provides registered WebMCP fixture tools.
test/README.md	Documents smoke-test execution.
README.md	Documents availability and permissions.
docs/architecture.md	Describes the WebMCP architecture.
docs/security-model.md	Documents security boundaries.
docs/prompt-injection-defense.md	Classifies WebMCP data as untrusted.
docs/privacy-and-data-flow.md	Documents catalog and model data flow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[webbrain-one]

wow thank you this is amazing! we've been thinking about this: #305

[esokullu]

Because every token counts, especially with smaller local models, I'd like to land this as an explicitly opt-in setting under Settings > Advanced rather than enabling it by default. That keeps the default surface lean for users on tight token budgets, while still making the fast path available for those who want it.

I do hope WebMCP gains ground soon — we'd love to be an early cheerleader. If there's an official icon or support announcement we can use, happy to add it to the website. I didn't see one linked in the PR, so feel free to point me to it.