real-browser-mcp: Instructions file for Codex

AGENTS.md - Real Browser MCP

Overview

Real Browser MCP is an MCP-facing fork of the upstream browser bridge.

Architecture:

MCP Server <-> Local Broker <-> Native Host <-> Chrome Extension

Core files:

• bin/mcp-server.js: stdio MCP entrypoint for MCP clients
• bin/cli.js: installer, status, tool runner, and MCP launch wrapper
• bin/broker.cjs: local broker with per-session tab ownership
• bin/native-host.cjs: Chrome Native Messaging host
• extension/background.js: browser-side tool execution
• dist/plugin.js: bundled tool layer reused from the upstream implementation

Current State

• MCP startup works with Codex CLI 0.114.0.
• The MCP server accepts Codex's JSONL-style initialize/tools/* messages.
• The MCP server also serves text resources/* and prompt runbooks over the same stdio transport.
• Native host, broker, and Chrome extension have been verified end-to-end up to browser_status reporting hostConnected: true.
• browser_screenshot exposes fullPage.
• Download flows are verified for direct URL, selector-triggered, wait=true, and competing-download association cases.
• browser_extract and browser_task are implemented in the bundled tool layer and covered by self-test.
• rpa_run, rpa_runs_list, rpa_run_get, rpa_run_cancel, and rpa_templates_list now expose a native-first browser RPA layer above browser_task.
• browser_route now supports both block and mock actions on the profile backend.
• Both backends now expose browser_context_*, browser_trace_*, browser_har_*, and browser_video_*.
• On the native backend, isolated contexts are backed by split incognito windows and require Chrome's "Allow in Incognito" toggle.
• Backend selection now supports native, agent, and auto, with native as the default and auto available only when explicitly requested.
• MCP exposes resources/list, resources/read, resources/templates/list, prompts/list, and prompts/get.
• The fixed unpacked extension ID derived from the manifest key is hcghacpnkedkkbelmhapbobekbdfmppi.
• The broker's ensureSessionTab now receives the caller's preferredHostId so that auto-tab creation works when multiple browser hosts (regular + incognito) are connected.