proxypro-harness

Headless ProxyPro AI harness — drive a Playwright browser through the ProxyPro capturing proxy and expose it to Claude Code (or any MCP HTTP client), with native action ↔ network-flow correlation.

Run ProxyPro's engine + MCP server without the desktop GUI, so an AI agent can develop and test a web app end-to-end: serve a mocked backend, drive a real browser through the proxy, see which network calls each UI action triggered, and inject faults — all over MCP.

Quick start

npx proxypro-harness
# → boots the engine + MCP server on http://127.0.0.1:9091/mcp
# then connect a client:
claude mcp add --transport http proxypro http://127.0.0.1:9091/mcp

Scenario skills

This package bundles two complementary Claude Code skills. install-skill copies both into a skills directory without needing the source repo:

npx proxypro-harness install-skill                  # → ~/.claude/skills/{proxypro-scenario, proxypro-scenario-gen}
npx proxypro-harness install-skill --dir .claude/skills   # project-local

• proxypro-scenario — run a YAML scenario (decrypt scope + Map-Local mocks
  • browser steps + network/DOM assertions + fault variants) against the harness.
• proxypro-scenario-gen — generate such a scenario YAML from edge cases (errors, auth, slow networks, edge payloads); emits the file, then hand it to proxypro-scenario to run.

Prerequisites

• Node.js ≥ 18.
• The proxypro-engine binary. Resolved automatically in order:
  1. --engine <path> flag
  2. PROXYPRO_ENGINE environment variable
  3. an installed ProxyPro.app on macOS (/Applications/ProxyPro.app/Contents/Resources/proxypro-engine) — auto-detected, no config needed
  4. a source build (make engine in a checkout)
  5. auto-downloaded on first run (macOS only) from GitHub Releases, cached at ~/.proxypro/engine/<tag>/proxypro-engine — subsequent runs use the cache. Pass --engine or PROXYPRO_ENGINE to skip the download entirely. The repo is private — the download requires a GitHub token with repo read access. Set GITHUB_TOKEN or GH_TOKEN, or authenticate with gh auth login (the gh CLI token is used automatically). Without a token the download returns 404.
• Chromium. Auto-installed on first run via playwright install chromium (~150 MB, one-time). Skip with --no-auto-install and install manually.

Options

| Flag | Default | Description | |------|---------|-------------| | --engine <path> | auto-resolved | Path to the proxypro-engine binary. | | --data-dir <path> | shared (app default) | Engine data dir (rules.db, captures.db, CA). Set to isolate a run so tests don't clobber your real captures/rules/SSL allowlist. | | --headed | off (headless) | Launch the browser with a visible window to watch it live. | | --record | off | Record browser sessions to .webm (saved when browser_close is called). | | --no-auto-install | off | Don't auto-install Chromium on first run. | | -h, --help | — | Show help. |

What you get

The harness exposes ProxyPro's engine MCP tools (captures, rules, Map Local mocks, replay, SSL proxying) plus headless-only browser + correlation tools: browser_launch, browser_goto, browser_click, browser_fill, browser_snapshot, browser_screenshot, browser_eval, browser_close, and flows_for_action / wait_for_idle to learn which captured flows each browser action triggered.

The browser routes through the proxy with TLS errors ignored (dev convenience). SSL capture defaults to allowlist mode — ask the agent to set_ssl_proxying_mode("all") for full visibility during a session.

Shared capture sessions (.ppsession)

Review a teammate's captured traffic without their machine: in the ProxyPro GUI they hit Export Session (current filtered view, full bodies capped at 1 MB each) and send you the .ppsession file. An agent then debugs from it directly:

• import_session(path) — load the file; returns a session id
• list_sessions — enumerate loaded sessions
• list_captures / get_capture / get_capture_body accept an optional session param to read the snapshot instead of live traffic (body responses carry a truncated flag when the export cap cut them)

Example ask: "import /tmp/qa-checkout.ppsession and explain why POST /checkout returned 500" — the agent imports, lists, reads the failing flow's body, and answers from the real recorded traffic. Sessions are in-memory snapshots: restart = re-import. Note .ppsession files contain real headers (cookies, tokens) — share them like secrets.

License

MIT — see the ProxyPro repository.