# rejestr-umow-mcp-server

Serwer MCP (Model Context Protocol) do wyszukiwania umów w **Centralnym
Rejestrze Umów** jednostek sektora finansów publicznych (CRU JSFP),
publicznie dostępnym pod [rejestrumow.gov.pl](https://rejestrumow.gov.pl).
Dzięki niemu asystent AI może wyszukiwać i pobierać umowy (strony,
przedmiot, wartość, daty, status, finansowanie z UE) zamiast ręcznego
przeszukiwania strony.

## Czym jest Centralny Rejestr Umów

CRU to publiczna baza umów zawieranych przez instytucje sektora finansów
publicznych (ministerstwa, urzędy, samorządy, szkoły, szpitale itd.),
uruchomiona 1 lipca 2026 r. Każdy może sprawdzić strony, przedmiot i
wartość umowy bez składania wniosku o dostęp do informacji publicznej.

Ministerstwo Finansów udostępnia też **API integracyjne (CRU API JSFP)**
z autoryzacją nagłówkiem `X-API-KEY`, które oprócz publikacji i
aktualizacji umów przez jednostki obowiązane pozwala też na **wyszukiwanie
zestawień już opublikowanych dokumentów** oraz pobieranie ich
szczegółów. Dokumentacja integracyjna:

- Produkcja: https://jsfp.rejestrumow.gov.pl/api-gw/docs/int/api.html
- Środowisko testowe: https://jsfp-cru-test.mf.gov.pl/api-gw/docs/int/api.html
- Kontakt / zgłoszenie o dostęp: `wsparcie.cru.jsfp@mf.gov.pl`

## Status weryfikacji API (ważne!)

Sesja, w której powstał ten kod, działa w środowisku z ograniczoną
polityką sieciową, która **blokuje połączenia do domen `*.gov.pl`**
(potwierdzone na poziomie proxy — `gateway answered 403 to CONNECT
(policy denial)` dla `jsfp.rejestrumow.gov.pl` i `rejestrumow.gov.pl`).
W efekcie nie było możliwe:

- pobranie strony dokumentacji integracyjnej (`api.html`) i odczytanie
  rzeczywistych ścieżek endpointów, nazw parametrów i kształtu odpowiedzi,
- sprawdzenie publicznej wyszukiwarki na rejestrumow.gov.pl pod kątem
  ewentualnego (nieudokumentowanego) endpointu JSON używanego przez UI,
- zweryfikowanie, czy indywidualny/jednoosobowy wniosek o klucz API
  zostanie w ogóle rozpatrzony pozytywnie (API wygląda na adresowane
  przede wszystkim do jednostek JSFP publikujących własne umowy).

**Co z tego wynika dla tego kodu:** ścieżki żądań w `src/constants.ts` /
`.env.example` (`CRU_SEARCH_PATH`, `CRU_CONTRACT_PATH`) oraz nazwy
parametrów zapytania w `src/tools.ts` (np. `fraza`, `dataOd`,
`numerStrony`) to **przypuszczenia oparte na typowej konwencji REST**, a
nie potwierdzone fakty z dokumentacji. Kod jest skonstruowany tak, by
łatwo je poprawić (jedna zmienna środowiskowa / jedno miejsce w kodzie),
ale **przed pierwszym realnym użyciem trzeba je zweryfikować** względem
oficjalnej dokumentacji (dostępnej z przeglądarki bez ograniczeń tej
sesji) i w razie potrzeby skorygować.

## Dwie ścieżki dalszej pracy

1. **Oficjalne API CRU JSFP (zaimplementowane w tym folderze).**
   Wymaga zgłoszenia się po klucz `X-API-KEY` do Ministerstwa Finansów.
   Najbardziej stabilne i "legalne" rozwiązanie długoterminowo, ale
   nieznany czas/warunki przyznania dostępu dla podmiotu spoza JSFP.
2. **Publiczna wyszukiwarka na rejestrumow.gov.pl (nie zaimplementowane).**
   Strona nie wymaga logowania dla obywatela, więc teoretycznie dałoby
   się zbudować "agregator" odpytujący jej wewnętrzny endpoint JSON —
   ale wymaga to podejrzenia ruchu sieciowego w przeglądarce (Network tab)
   przez kogoś z dostępem do domeny, nie jest udokumentowane, i może
   naruszać regulamin serwisu. Rekomendacja: sprawdzić `robots.txt` i
   regulamin serwisu, zanim ktokolwiek pójdzie tą drogą.

**Rekomendacja:** zacznij od ścieżki 1 — wyślij zapytanie o dostęp na
`wsparcie.cru.jsfp@mf.gov.pl`, a po otrzymaniu klucza i realnej
dokumentacji popraw `CRU_SEARCH_PATH`/`CRU_CONTRACT_PATH` oraz mapowanie
pól w `src/tools.ts` i `src/format.ts` na rzeczywisty kształt odpowiedzi.

## Narzędzia MCP

- `rejestr_umow_search_contracts` — wyszukuje umowy po tekście, stronie
  umowy (nazwa/NIP), jednostce JSFP, zakresie dat i wartości, z paginacją.
- `rejestr_umow_get_contract` — pobiera pełne szczegóły jednej umowy po
  identyfikatorze/numerze.

Oba narzędzia są tylko do odczytu (`readOnlyHint: true`) — serwer nie
publikuje ani nie modyfikuje żadnych umów.

## Instalacja i konfiguracja

```bash
cd rejestr-umow-mcp
npm install
cp .env.example .env
# uzupełnij CRU_API_KEY w .env po otrzymaniu klucza od MF
# zweryfikuj/popraw CRU_SEARCH_PATH i CRU_CONTRACT_PATH względem dokumentacji
npm run build
```

## Uruchomienie

```bash
npm start
```

Serwer komunikuje się przez stdio — podłącz go do klienta MCP (np. Claude
Desktop/Claude Code) w konfiguracji serwerów MCP, wskazując
`node dist/index.js` w katalogu `rejestr-umow-mcp` i przekazując zmienną
środowiskową `CRU_API_KEY`.

## Struktura projektu

```
rejestr-umow-mcp/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   ├── index.ts       # inicjalizacja serwera MCP (stdio)
│   ├── tools.ts        # definicje narzędzi (search / get)
│   ├── client.ts        # klient HTTP + obsługa błędów
│   ├── constants.ts     # konfiguracja z env (base URL, ścieżki, klucz)
│   ├── format.ts        # formatowanie odpowiedzi na markdown
│   └── types.ts          # typy odpowiedzi API (celowo permisywne)
└── dist/                  # skompilowany kod (po `npm run build`)
```