reduck-local-agent

Local Node agent that exposes a Playwright-controlled Chrome over an authenticated WebSocket, tunneled via Cloudflare Quick Tunnel so a remote MCP can drive the user's real browser.

Quick start (npx)

Prerequisites:

• Node.js ≥ 18
• Google Chrome installed
• cloudflared on your PATH (brew install cloudflared on macOS)

# First run only — downloads Playwright's Chromium binaries
npx -y playwright@latest install chromium

# Start the agent
npx -y @reduck-ai/reduck-local-agent

Within ~10 seconds you'll see:

Remote MCP connection info:
wss://<random-words>.trycloudflare.com?token=<token>

Hand that wss://…?token=… URL to the remote MCP. Keep the terminal open for the duration of the session — Ctrl-C tears everything down cleanly.

What it does

1. Launches Chrome with chromium.launchServer() (native Playwright protocol, not CDP).
2. Wraps the local WS endpoint in a token-gated proxy bound to 127.0.0.1.
3. Opens a Cloudflare Quick Tunnel to that proxy.
4. Prints wss://<tunnel>.trycloudflare.com?token=... for the remote MCP to consume.

Setup

npm install
npx playwright install chromium

You also need cloudflared on your PATH.

Run

npm start

Pass BROWSER_TOKEN=... in the environment to pin the token; otherwise one is generated per run.

The agent prints a wss://...trycloudflare.com?token=... URL — hand that to the remote MCP. Keep the terminal open for the duration of the session; Ctrl-C tears down the browser and the tunnel.

Smoke test the connection

In another terminal:

node client.js "wss://<tunnel>.trycloudflare.com?token=<token>"

It connects, opens example.com, and prints the page title.

Remote MCP usage

import { chromium } from "playwright";

const browser = await chromium.connect(wsEndpoint);
const page = await browser.newPage();
await page.goto("https://example.com");

Bootstrapped by an LLM agent

The intended end-to-end flow once published to npm:

1. Claude (or another LLM agent) connects to the remote Reduck MCP.
2. The MCP returns instructions — or points the agent at AGENT.md — telling it to run npx -y @reduck-ai/reduck-local-agent.
3. The agent reads stdout, extracts the wss://…?token=… line, and calls the MCP's registration tool with that URL.
4. The remote MCP connects with chromium.connect(wsEndpoint) (same shape as client.js) and drives the user's real browser for the rest of the session.

See AGENT.md for the exact prerequisite checks, capture regex, and security boundaries the LLM is expected to follow.

Security notes

• Token is required on every upgrade (?token= or Authorization: Bearer ...).
• Proxy listens on 127.0.0.1 only; the tunnel is the sole public path.
• Browser session is fresh per run, no persistent profile.
• Quick Tunnels are appropriate for prototype/beta only. For production, swap in a named Cloudflare tunnel or your own relay.