VRO Camoufox MCP

VRO Camoufox MCP is a Python Model Context Protocol server for controlled marketplace research. It opens allowlisted Vinted pages, classifies and extracts visible listing data, enumerates member inventory, and captures verifiable evidence without exposing marketplace mutation tools.

What it does

• Creates isolated Playwright browser sessions with bounded lifetime and page limits.

• Restricts navigation to configured Vinted domains and blocks unsafe URL schemes.

• Distinguishes home, member, listing, search, login, challenge, and error pages.

• Extracts visible listing details without inventing missing values.

• Reconciles member inventory counts through bounded scrolling and deduplication.

• Captures PNG evidence with SHA-256 hashes, manifests, and SQLite records.

• Issues expiring HMAC-signed artifact URLs.

• Tracks verified remote synchronization and safely expires local payloads.

• Returns consistent result envelopes with trace IDs, timing, warnings, evidence, and errors.

Architecture

AI harness
    |
    v
VRO Camoufox MCP
    |-- browser policy and page classification
    |-- listing and inventory extraction
    `-- artifact capture and verification
            |
            v
      human review / approval

The MCP server provides capabilities. The surrounding harness owns workflow orchestration, policy decisions, persistence, approvals, and final success criteria.

Tool surface

Quick start

1. Create an environment

git clone https://github.com/grappaheiss/camoufox.git
cd camoufox
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
playwright install chromium

On Linux or macOS, activate with source .venv/bin/activate.

2. Configure the server

Copy-Item .env.example .env

At minimum, replace the placeholder artifact signing secret. For HTTP deployment, also set a client-reachable PUBLIC_BASE_URL and an explicit host allowlist.

ARTIFACT_SIGNING_SECRET=replace-with-a-long-random-secret
PUBLIC_BASE_URL=http://127.0.0.1:8765
MCP_ALLOWED_HOSTS=127.0.0.1,127.0.0.1:8765,localhost,localhost:8765

3. Run it

The default transport is stdio:

vro-mcp

For Streamable HTTP at http://127.0.0.1:8765/mcp:

$env:MCP_TRANSPORT = "streamable-http"
vro-mcp

Linux launch helpers are available under scripts/.

Configuration

See .env.example for the complete configuration surface.

Development

Run the focused regression suite:

python -m pytest -q

Run the dependency-light smoke checks:

python scripts/smoke_test.py

The current baseline is 6 regression tests plus 9 smoke checks.

Security model

• Navigation is restricted by scheme and domain allowlists.

• Model-facing tools cannot choose arbitrary artifact filesystem paths.

• Artifact confirmation requires independent verification; supplied hashes must match.

• Cleanup is restricted to confirmed artifacts and defaults to dry-run.

• Extracted marketplace content is treated as data, never as executable instruction.

• Signed URLs bind the artifact identity, filename, expiry, and server-held secret.

For production, retain DNS-rebinding protection, use an explicit stable hostname, store secrets outside source control, and expose the service only through a trusted HTTPS boundary.

Documentation

• Full development, deployment, and acceptance specification

• Example environment configuration

• Smoke-test harness

Status

Version 0.1.0 is an initial Phase I implementation. Browser selectors remain marketplace-structure dependent and should be covered by live integration fixtures before production use.