# Perchance MCP Lite - Under 512MB RAM (No Browser)

**For Render Free Tier 512MB - Uses external Byparr/Camoufox solver on separate Render account**

Main MCP needs 1-2GB for Chromium (SeleniumBase UC). This lite version stays **80-120MB** by offloading Turnstile solving to a separate service.

## Architecture - Split for 512MB

```
Render Account 1 (512MB, 750h) - perchance-mcp-lite (this repo)
  - 80-120MB RAM, no browser
  - Only curl_cffi + httpx + mcp + fastapi
  - Calls solver via SOLVER_URL env var
  - Endpoints: /sse, /mcp, /ping (health)

Render Account 2 (512MB, 750h) - perchance-solver (separate repo)
  - 250-350MB RAM, Camoufox Firefox stealth (Byparr)
  - Solves Turnstile sitekey 0x4AAAAAAAA8g8NphwaSOT59
  - Returns userKey + generates images via curl_cffi
  - Endpoints: /solve, /generate, /ping, /v1 (FlareSolverr-compatible)
  - Docker: ghcr.io/thephaseless/byparr:latest or custom solver.py
```

Each Render workspace has 750h/month free, so 2 accounts = 1500h total, both can be kept alive via UptimeRobot.

## Why Byparr/Camoufox?

- **FlareSolverr official v3.5.2** fixed Turnstile in #1634 but still Chromium + undetected-chromedriver = 400MB+ and detectable
- **Byparr** = custom fork using **Camoufox Firefox** - C++ fingerprint patches (not JS), 0% detection on CreepJS, BrowserScan, **200MB vs 400MB+**, 2-5x better success rate on Turnstile in 2026 benchmarks
- **Unlimited**: Self-hosted, no Browserless 1000/mo limit

## Quick Start

### 1. Deploy Solver (Render Account 2)

```bash
cd /home/user/perchance-solver
# Push to GitHub perchance-solver repo
git init && git add . && git commit -m "Byparr solver" && git push

# Render → New Web Service → Connect repo → Docker → Port 8000 → Health /ping → Free 512MB
# URL: https://perchance-solver.onrender.com
# Test: curl https://perchance-solver.onrender.com/ping → {"status":"ok"}
```

Keep alive solver:
- UptimeRobot free → Monitor `https://perchance-solver.onrender.com/ping` every 5 min

### 2. Deploy Lite MCP (Render Account 1)

```bash
cd /home/user/perchance-mcp-lite
# Push to GitHub perchance-mcp-lite repo

# Render → New Web Service → Docker → Port 8000 → Health /ping → Free 512MB
# Env vars:
#   SOLVER_URL=https://perchance-solver.onrender.com
#   PORT=8000
# URL: https://perchance-mcp-lite.onrender.com
# Test: curl https://perchance-mcp-lite.onrender.com/ping
```

Keep alive lite:
- UptimeRobot → Monitor `https://perchance-mcp-lite.onrender.com/ping` every 5 min

### 3. Connect MCP Clients

```json
{
  "mcpServers": {
    "perchance-lite": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://perchance-mcp-lite.onrender.com/sse"]
    }
  }
}
```

Or for solver direct (if you want images directly from solver):
```json
{
  "mcpServers": {
    "perchance-solver": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://perchance-solver.onrender.com/sse"]
    }
  }
}
```

## Tools (same 15 as full MCP, but lite)

- `generate_image` - Main: calls solver if SOLVER_URL set, else needs PERCHANCE_USER_KEY
- `get_user_key_status` - Check cached key + solver health
- `get_ad_code` - Ad code via curl_cffi (no browser, unlimited)
- `list_styles`, `get_generator_info`, `generate_batch`

## Env Vars

- `SOLVER_URL` - https://your-solver.onrender.com (Byparr/Camoufox solver on separate Render account) - **recommended for 512MB**
- `PERCHANCE_USER_KEY` - 64-char hex from browser localStorage (manual, no solver, valid 30s IP-bound)
- `PORT` - Render sets automatically (8000)

## Memory

- Lite MCP: 80-120MB (no browser) - fits Render 512MB
- Solver: 250-350MB (Camoufox) - fits separate Render 512MB
- Full MCP: 800MB-1.5GB (SeleniumBase UC) - needs 2GB, OOM on Render

## How it works

1. Lite: `get_ad_code_via_curl_cffi()` - TLS impersonation `impersonate="chrome"`, bypasses JA3, 200 OK 64 hex, no browser
2. Lite: If no cached userKey, `POST SOLVER_URL/solve` → solver launches Camoufox, solves Turnstile `0x4AAAAAAAA8g8NphwaSOT59`, calls `verifyUser?browserId&token&thread=0` → userKey 64 hex
3. Lite: Option A - Generate via `POST SOLVER_URL/generate` (solver does curl_cffi generate + download, returns base64, same IP as solve, no invalid_key)
   Option B - Generate via curl_cffi directly (if userKey IP matches Lite IP - may fail if solver IP != lite IP, so Option A recommended)
4. Download via curl_cffi immediate (token single-use expires 5min, IP-bound)

## FlareSolverr-compatible API

Solver also exposes `/v1` for drop-in Byparr/FlareSolverr clients:

```bash
curl -X POST https://perchance-solver.onrender.com/v1 -H "Content-Type: application/json" -d '{
  "cmd": "request.get",
  "url": "https://image-generation.perchance.org/embed",
  "maxTimeout": 60000
}'
→ {"status":"ok","solution":{"cookies":[...],"userAgent":"...","response":"<html>..."}}
```

## Custom Fork - How we got Turnstile solving

- Official FlareSolverr v3.5.2 fixed Turnstile in PR #1634
- Byparr is custom fork using Camoufox Firefox (C++ patches, not JS) - better fingerprint, 200MB
- For Perchance, we built custom solver that does exactly `turnstile.render({sitekey: '0x4AAAAAAAA8g8NphwaSOT59'})` → token → verifyUser → userKey
- Docker: `ghcr.io/thephaseless/byparr:latest` is drop-in, no custom code needed for generic, but custom solver returning userKey is more reliable for Perchance

## Test Lite

```bash
pip install -r requirements.txt
export SOLVER_URL=https://perchance-solver.onrender.com
python server.py
# or
python -m uvicorn remote_server:app --host 0.0.0.0 --port 8000
```