Components
| Component | Responsibility |
|---|---|
| Chrome extension | Owns Chrome permissions and performs tab, DOM, screenshot, and DevTools Protocol operations. |
| Loopback bridge | Authenticates commands with the shared token and relays them between HTTP clients and the extension WebSocket. |
| MCP server | Exposes a small standard stdio interface: status and generic browser commands. |
| MCP client | Provides the agent and decides which tool calls to make. This is the trust boundary for prompts and model behavior. |
Command lifecycle
- An MCP client calls
browser_commandover stdio. - The MCP server posts the action to
127.0.0.1:8765, authenticated by the bridge token. - The local bridge forwards the command through its existing extension WebSocket.
- The Chrome extension uses Chrome APIs, content-script execution, or the DevTools Protocol as needed.
- The result returns through the same path as structured JSON.
Interaction strategy
The agent should first use a viewport-only snapshot. The extension walks the standard DOM, open shadow roots, and same-origin frames, returning accessible names and a temporary agentId. The next action can use that ID rather than guessing a CSS selector or physical location.
For inputs controlled by frontend frameworks, type uses the native value setter and dispatches input events. For rich text, insert_text, press, and clear send trusted DevTools Protocol input, which many editors require.
Boundaries and limitations
- Cross-origin iframe DOM cannot be inspected because browser same-origin protections still apply.
- Closed shadow roots cannot be traversed.
- The extension must be installed in the Chrome profile that contains the session to be controlled.
- This is an interactive developer tool, not a replacement for deterministic end-to-end test automation.
For implementation detail, see the extension source and the MCP server.