# mcp-wl-vat

MCP server dla polskiej **białej listy podatników VAT** (Wykaz Podatników VAT) przez
oficjalne, bezpłatne API Ministerstwa Finansów (`wl-api.mf.gov.pl`). Zero kluczy API.

Autor: Piotr Waśniowski, Legal Link.

Zbudowany dla Legal Link, w konwencji tego samego fleetu co `mcp-saos` / `mcp-krs` /
`mcp-nsa` / `mcp-isap` / `mcp-eu-sparql` (MateMatic) — ten sam kontrakt
`structuredContent.citations`, ten sam wzorzec kodów błędów, ten sam `drift` test.

## Dlaczego własny, a nie istniejący `nip-checker-mcp`

Sprawdziliśmy istniejący projekt (`solverio-pl/nip-checker-mcp`) przed napisaniem tego.
Braki, które zdecydowały o budowie od zera:

- brak rozróżnienia kodów błędów — awaria sieci, błędny NIP i **wyczerpany dzienny limit
  zapytań MF** wszystkie zwracały identyczny, generyczny komunikat,
- brak jakiejkolwiek ochrony przed przekroczeniem dziennego limitu MF (100 zapytań/dzień
  metodą `search`, do 5000 metodą `check`) — po przekroczeniu MF blokuje **cały adres IP**
  do północy, co przy jednym IP biurowym oznacza blokadę dla całej kancelarii,
- brak wyszukiwania po REGON i po numerze konta,
- zero testów.

## Tools

- **`search_nip(nip, date?)`** — status VAT + dane podmiotu po NIP.
- **`search_regon(regon, date?)`** — jak wyżej, po REGON.
- **`search_bank_account(bank_account, date?)`** — jaki podmiot ma przypisany dany rachunek.
- **`check_nip_bank_account(nip, bank_account, date?)`** — TAK/NIE: czy dany rachunek jest
  przypisany do danego NIP. Wyższy dzienny limit (5000) niż metoda `search` (100) —
  preferowany, gdy znasz oba identyfikatory.

Każda odpowiedź zawiera `structuredContent.citations`:
`{ title, url, nip, regon, krs, status_vat, checked_date, request_id }`.

## Ochrona przed limitem dziennym

Ten serwer prowadzi **lokalny licznik w pamięci procesu** (nietrwały — restart = reset) i
sam odmawia wykonania zapytania (`rate_limit_daily`) z marginesem przed oficjalnym limitem
MF (90/100 dla `search`, 4800/5000 dla `check`). To siatka bezpieczeństwa, nie księgowość —
nie chroni przed przekroczeniem realnego limitu MF, jeśli kilka osób w biurze pyta
niezależnie z tego samego adresu IP.

Walidacja NIP/REGON/rachunku (z sumami kontrolnymi) odbywa się **przed** wysłaniem
zapytania — literówka nie zużywa slotu z dziennego budżetu.

## Potwierdzone empirycznie (2026-08-05, live test na produkcyjnym API)

- **WL-111** ("Nieprawidłowy numer konta bankowego") — realny kod błędu MF, zwracany gdy
  numer rachunku ma poprawną długość (26 cyfr) ale błędną sumę kontrolną NRB. Ten serwer
  **nie liczy sam** sumy kontrolnej NRB (mod 97 z formatowaniem liter PL) — poprawnie
  mapuje odpowiedź MF na kod `invalid_bank_account`, ale samo zapytanie już zużywa slot
  z dziennego limitu (w przeciwieństwie do błędów wykrytych czysto lokalnie, np. zła
  długość czy zły NIP).
- `search_nip` na prawdziwym NIP (ORLEN, 7740001454) zwraca poprawne dane, zgodne co do
  NIP/REGON/KRS z tym, co zwraca `mcp-krs`.

## Wciąż niezweryfikowane

Dokładny format błędu MF przy przekroczeniu **dziennego limitu zapytań** (spodziewany kod
`WL-191` wg wpisów na forach branżowych, nie potwierdzony na żywo — nikt jeszcze nie
uderzył w ten limit w testach). Detekcja (`looksLikeDailyLimitError` w `src/format.ts`)
działa na dopasowaniu frazy, nie sztywnego kodu. Jeśli kiedyś faktycznie zobaczysz ten
błąd w praktyce, sprawdź, czy wykrywanie zadziałało poprawnie — jeśli nie, popraw regex.

## Build + run
```
npm install
npm run build
npm start # stdio transport

npm run drift # offline - spójność INSTRUCTIONS/TOOLS/ErrorCode
npm run test:offline # offline - walidacja sum kontrolnych, formatowanie
npm run smoke # LIVE - wl-api.mf.gov.pl, zużywa realny dzienny limit
```
## Konfiguracja Claude Desktop

```json
{
  "mcpServers": {
    "wl-vat": {
      "command": "node",
      "args": ["<ścieżka>/mcp-wl-vat/dist/index.js"]
    }
  }
}
```

## Limity API (oficjalne, gov.pl, stan 01.01.2025)

- Metoda `search`: 100 zapytań/dzień z jednego IP, po max 30 podmiotów na zapytanie.
- Metoda `check`: do 5000 podmiotów/dzień.
- Po przekroczeniu: blokada IP do północy — obejmuje też ludzką wyszukiwarkę na
  podatki.gov.pl.

Dokumentacja MF: <https://www.gov.pl/web/kas/api-wykazu-podatnikow-vat>

## License

MIT.