# vies-smoother

SLA'd EU VAT number validation for AI agents. Wraps the European
Commission's [VIES](https://ec.europa.eu/taxation_customs/vies/) service
(authoritative but flaky -- rate limits, per-country outages, inconsistent
errors) with:

- A 24-hour cache
- A per-country circuit breaker (stops hammering a member state that's
  currently down)
- An honest three-state answer, never a guess:
  - `valid` -- the number is registered and active
  - `invalid` -- the number does not exist or is inactive
  - `unavailable_upstream` -- VIES is down and there's no cache; you are
    **not charged** for this

Free tier: 100 lookups per key, no card required. $0.01/lookup after that
($5 / 500-credit minimum top-up).

This repo is the MCP client only (a thin wrapper over the hosted REST API
at `https://vantane.com`) -- it doesn't reimplement the cache/circuit
breaker logic, which lives server-side so metering is centralized
regardless of how you connect.

## Quickstart

Claim a free key:

```bash
curl -s -X POST https://vantane.com/keys/claim
```

### Option A: hosted, no install

Point any MCP client directly at the hosted endpoint:

```json
{
  "mcpServers": {
    "vies-smoother": {
      "url": "https://vantane.com/mcp",
      "headers": { "X-API-Key": "sk_live_..." }
    }
  }
}
```

### Option B: run this locally (stdio)

```bash
pip install -r requirements.txt
export RAILS_API_KEY=sk_live_...
python server.py
```

MCP client config:

```json
{
  "mcpServers": {
    "vies-smoother": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": { "RAILS_API_KEY": "sk_live_..." }
    }
  }
}
```

## Tools

- `validate_vat(country_code, vat_number)` -- single lookup, 1 credit
- `validate_vat_batch(items)` -- up to 50 per call, 1 credit each

## REST API (if you'd rather not use MCP)

- `POST /keys/claim` -- claim a free key
- `POST /vies/validate` -- single lookup
- `POST /vies/validate/batch` -- batch, max 50
- `GET /vies/status` -- live VIES availability, cache hit rate, 7-day SLA (free, no key)
- `POST /topup` -- buy more credits (requires an existing key)

## License

MIT