docs: add BrowserOS MCP browser backend RFC

[mason5052]

Summary

Add examples/proposals/browseros_mcp_browser_backend.md, a docs-only RFC for a future optional BrowserOS MCP browser backend for PentAGI agents. The RFC keeps the existing scraper backend as the default and frames BrowserOS MCP as disabled-by-default design work for maintainer review before any runtime implementation.

Problem

Issue #342 asks for BrowserOS MCP support because the current backend/pkg/tools/browser.go browser tool is scraper-style: it fetches markdown, HTML, links, and screenshots through configured scraper URLs, but it does not provide a stateful browser session for click/type/navigation/login-page interaction. That feature is large enough to need design agreement first, especially because BrowserOS MCP can expose browser state, cookies, history, bookmarks, and app integrations if it is not scoped carefully.

Solution

Add a focused RFC under examples/proposals/ that:

• Builds on the existing mcp_client_integration.md direction instead of defining a separate MCP stack.
• Proposes BrowserOS MCP as an optional browser backend, disabled by default, with scraper remaining the default behavior.
• Defines a narrow browser-tool surface for future navigation, observation, screenshot, click, fill/type, wait, and submit-style workflows.
• Explicitly excludes runtime code, BrowserOS client code, schema changes, DB migrations, frontend UI, Docker Compose changes, .env.example changes, generated files, and new env vars.
• Calls out target allowlists, SSRF protection, DNS/private-network checks, cross-flow session isolation, cookie/session leakage, operator approval for sensitive actions, redaction, and explicit host reachability instead of assuming host.docker.internal.
• Requires interactive actions such as navigation, click, fill/type, submit, dialog handling, and file upload to be visible in logs with flow/task/subtask context.

User Impact

• Gives maintainers a concrete design artifact to review before BrowserOS MCP runtime work lands.
• Clarifies how BrowserOS could improve JavaScript-heavy and interactive browsing without changing today's scraper behavior.
• No runtime impact. This is documentation only.

Test Plan

• git diff --check clean.
• git diff --name-only upstream/main...HEAD shows only examples/proposals/browseros_mcp_browser_backend.md.
• git status --short clean after commit.
• Confirmed default branch is still main.
• Confirmed Issue [New Feature]: Add BrowserOS MCP support for better agent-controlled browsing #342 is still open.
• Confirmed no open PR currently covers BrowserOS MCP browser backend design.
• Verified diff is docs-only: no code, schema, generated, config, Docker Compose, frontend, or .env.example changes.

Refs #342

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a docs-only RFC proposing an optional BrowserOS MCP-backed browser backend for PentAGI, focusing on session isolation, safety controls, and auditability while keeping the existing scraper backend as the default.

Changes:

• Introduces an RFC describing how BrowserOS MCP would integrate via the generic MCP client layer.
• Defines proposed backend selection modes (scraper / browseros_mcp / hybrid) and flow-scoped session isolation expectations.
• Provides an illustrative configuration sketch plus failure modes, security requirements, and incremental milestones.

---

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