# 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](https://modelcontextprotocol.io/) 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

```text
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

```powershell
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

```powershell
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.

```dotenv
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:

```powershell
vro-mcp
```

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

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

Linux launch helpers are available under [`scripts/`](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`](.env.example) for the complete configuration surface.

## Development

Run the focused regression suite:

```powershell
python -m pytest -q
```

Run the dependency-light smoke checks:

```powershell
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](docs/SPECIFICATION.md)
- [Example environment configuration](.env.example)
- [Smoke-test harness](scripts/smoke_test.py)

## 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.