Venice Browser MCP Bridge

What this is:

A tiny, production-minded browser bridge that speaks a JSON-RPC-ish protocol over stdin/stdout.

It supports two transport framers out of the box:

• line — one JSON message per line (default). Simple, friendly, great for prototyping.

• content-length — HTTP-like Content-Length: N framed messages. Good for strict MCP hosts.

It uses Playwright for real browser automation with a single persistent context (optional cookie/session state).

This repo is hardened against the classic asyncio.StreamWriter(sys.stdout, ...) footgun by using a writer implementation that never logs to stdout, avoids protocol mismatches, and cleanly flushes per message.

Quick Start

1) Create an isolated env (recommended)

2) Install deps

3) Run the bridge (line framing by default)

In another terminal, run the example host:

Expect output like:

To exercise

Repo Layout

Configuration

The bridge is configured via environment variables. Reasonable defaults chosen for newbies.

Note: All logs go to stderr. Never print non-protocol text to stdout, or you will corrupt the transport.

RPC Methods

• browser.navigate — { "url": "https://example.com" }
  Opens/uses a single page, navigates, returns { ok, status, final_url, title }.

• ping — { "echo": "value" }
  Returns { "echo": "value" } for quick checks.

• mcp.shutdown — No params.
  Gracefully closes browser & exits main loop.

You can add more handlers in venice_browser_mcp_v23_impl.py under dispatch().

Makefile Targets

• make install — install Python deps and Playwright browser

• make run-line — run bridge in line mode (foreground)

• make run-cl — run bridge in content-length mode (foreground)

• make test-line — run example host for line mode

• make test-cl — run example host for content-length mode

• make fmt — basic Python formatting (via python -m json.tool checks and whitespace cleanup)

• make test — run the automated test suite

• make coverage — run tests and generate a coverage report

• make clean — remove caches/artifacts

Testing

This project includes a comprehensive test suite using pytest.

To run the tests:

“Stuck here?” Troubleshooting Lanes

1) Crash: AssertionError or 'Protocol' object has no attribute '_drain_helper'

Cause: Incorrect asyncio.StreamWriter construction (classic pitfall).
Fix: This repo does not use that pattern; it uses a safe writer. Ensure you are running these sources and not an unpatched file. Reinstall with git clean -xfd or re-extract the zip.

2) json.decoder.JSONDecodeError: Extra data

Cause: You leaked a non-JSON line to stdout (e.g., prints, warnings from other tools).
Fix: Ensure all diagnostics go to stderr. In Python: print(\"dbg\", file=sys.stderr, flush=True).

3) Expecting value: line 1 column 1 (char 0)

Cause: Host expected a JSON line but got empty/garbage, usually because the child process printed banners to stdout before the JSON.
Fix: Same as above; keep stdout pure protocol. Also verify your framing modes match (host vs bridge).

4) playwright._impl._errors.Error: BrowserType.launch: Executable doesn't exist

Cause: You forgot to install browsers.
Fix: playwright install chromium (or firefox / webkit if you changed BROWSER).

5) Headless works, but you need cookie persistence / “logged-in” state

• Set MCP_STORAGE_STATE=state.json (default already).

• Log in once with HEADLESS=false, then close. Subsequent sessions reuse that state.

6) Corporate proxy, weird TTY, or PTY quirks

If the host uses a PTY or non-pipe stdout, line-buffering can glitch. Prefer the included example hosts which spawn the bridge with a pipe and communicate cleanly.

Security Notes

• This project is a tooling bridge. It does not bypass web/app authentication, nor does it ship exploit logic.

• If you extend it, keep logs on stderr, and sanitize inputs when invoking shell or navigating to user-provided URLs.

• For red-team experiments: keep it abstracted and non-operational; do not automate harmful behaviors.

Sanity Checks

• Both framers verified with the included hosts.

• No stdout logging, atomic flush per message.

• Single Playwright context reused across calls, optional persistence enabled.

• Explicit timeouts on navigation.