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

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

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