VRO Camoufox MCP

<p align="center"> <strong>Read-oriented browser automation and evidence capture for Vinted Resale Ops.</strong> </p>

<p align="center"> <img alt="Python 3.12+" src="https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white"> <img alt="Model Context Protocol" src="https://img.shields.io/badge/MCP-Streamable_HTTP-6C47FF"> <img alt="Phase I read only" src="https://img.shields.io/badge/Phase_I-read--only-2EA44F"> <img alt="Tests" src="https://img.shields.io/badge/tests-15_passing-2EA44F"> </p>

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.

[!IMPORTANT] Phase I is intentionally read-only. Publishing listings, changing prices, messaging buyers, handling offers, purchasing, and other marketplace mutations remain human-controlled.

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

Area	Tool	Purpose
Browser	browser.start_session	Create an isolated controlled browser session.
Browser	browser.open_url	Open an allowlisted URL and classify the resulting page.
Browser	browser.inspect_page	Return bounded visible text and classified links.
Browser	browser.dismiss_overlay	Dismiss known cookie, app, login, and modal overlays.
Listings	listing.inspect_current	Extract the current listing when the page is a listing.
Listings	listing.enumerate_member_inventory	Scroll, deduplicate, and reconcile visible member inventory.
Listings	listing.crawl_member_inventory	Inspect discovered listings sequentially with partial-failure reporting.
Artifacts	artifact.capture_screenshot	Capture a screenshot, hash it, and register its manifest.
Artifacts	artifact.get	Retrieve artifact metadata and an optional signed URL.
Artifacts	artifact.list_pending	List artifacts awaiting verified remote persistence.
Artifacts	artifact.confirm_remote_sync	Confirm independently verified remote synchronization.
Artifacts	artifact.cleanup	Expire old confirmed local payloads with dry-run safety.

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

Variable	Default	Description
MCP_TRANSPORT	stdio	stdio, sse, or streamable-http.
MCP_HOST	127.0.0.1	HTTP bind address.
MCP_PORT	8765	HTTP listen port.
MCP_ENDPOINT	/mcp	Streamable HTTP endpoint.
MCP_ENABLE_DNS_REBINDING	true	Enable MCP host/origin validation.
MCP_ALLOWED_HOSTS	local hosts	Comma-separated accepted HTTP hosts.
BROWSER_HEADLESS	true	Run the browser without a visible window.
BROWSER_LOCALE	pl-PL	Browser locale.
BROWSER_TIMEZONE	Europe/Warsaw	Browser timezone.
ALLOWED_DOMAINS	Vinted Poland	Comma-separated navigation allowlist.
ARTIFACT_DIR	/var/lib/vro-mcp/artifacts	Server-controlled artifact storage.
ARTIFACT_RETENTION_HOURS	168	Confirmed local payload retention.
ARTIFACT_URL_TTL_SECONDS	900	Signed artifact URL lifetime.
PUBLIC_BASE_URL	placeholder	Client-reachable origin for artifact URLs.

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.