Fayeblade MCP

🚀 Venice Browser MCP Bridge

A lightweight, production-ready browser bridge that communicates via a JSON-RPC-like protocol over stdin/stdout.

🚀 Quick Start

1) Create an isolated environment (recommended)

python3 -m venv .venv && source .venv/bin/activate

2) Install dependencies

pip install -r requirements.txt
playwright install chromium

3) Run the bridge (line framing by default)

make run-line

In another terminal, run the example host:

make test-line

Expected output:

Navigate...
{"id":"nav-1","result":{"ok":true,"final_url":"https://example.com/","title":"Example Domain"}}

To use Content-Length framing

make run-cl    # terminal A
make test-cl   # terminal B

✨ Features

• Two transport framers: Supports line and content-length framing out of the box.
• Playwright integration: Uses Playwright for real browser automation with a single persistent context.
• Robust implementation: Avoids common pitfalls like logging to stdout and protocol mismatches.

📦 Installation

The installation steps are included in the Quick Start section. You can also use the following Makefile target to install Python dependencies and the Playwright browser:

make install

💻 Usage Examples

Basic Usage

To run the bridge in line mode:

make run-line

To test the line mode:

make test-line

Advanced Usage

To run the bridge in content-length mode:

make run-cl

To test the content-length mode:

make test-cl

📚 Documentation

Repo Layout

venice-browser-mcp/
├─ src/
│  ├─ venice_browser_mcp.py             # entrypoint
│  ├─ venice_browser_mcp_core.py        # env plumbing
│  └─ venice_browser_mcp_v23_impl.py    # framing + browser logic (patched)
├─ examples/
│  ├─ line_host.py                      # spawns bridge (line) and sends a request
│  └─ hard_mcp_host.py                  # spawns bridge (content-length) and sends a request
├─ docs/
│  ├─ ARCHITECTURE.md
│  └─ TROUBLESHOOTING.md
├─ Makefile
├─ requirements.txt
├─ .gitignore
├─ LICENSE
└─ README.md

Configuration

The bridge is configured via environment variables. Here are the available variables and their meanings:

⚠️ Important 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 clean — remove caches/artifacts

Troubleshooting

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.

🔧 Technical Details

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.

📄 License

The project includes a LICENSE file. Please refer to it for license information.