mcp-browser-operator

Policy-first MCP facility for browser operations with explicit control boundaries.

Why this exists

Automating browser tasks without constraints is fragile and unsafe. This project separates three actions and enforces policy before execution:

• read: inspect page state
• stage: draft content into UI fields
• submit: finalize an action (requires explicit confirmation)

Core constraints

• Dry-run defaults to true
• URL/domain allowlist is enforced
• submit requires human confirmation token
• Every action emits a machine-readable receipt

Initial scope

• In-process policy engine
• Mock browser adapter for deterministic testing
• MCP server entrypoint (optional mcp dependency)
• Security and architecture docs

Quick start

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev,mcp]'
pytest

Run as an MCP stdio server:

export MCP_BROWSER_OPERATOR_POLICY=examples/policies/default_policy.yaml
export MCP_BROWSER_OPERATOR_CONFIRM_TOKEN=change-me
mcp-browser-operator

Tool contract (v0)

• browser_read(url, selector="body", dry_run=true)
• browser_stage(url, selector, text, dry_run=true)
• browser_submit(url, selector, confirm_token, dry_run=false)

Security posture

See:

• docs/SECURITY_MODEL.md
• docs/CISO_CONTROLS.md
• docs/STAKEHOLDER_GUARDRAILS.md
• docs/ARCHITECTURE.md
• docs/API.md

License

MIT