Polish Academic MCP

Lokalny serwer MCP (Model Context Protocol) dla polskich baz naukowych, publicznych i kulturowych. Pakiet działa przez stdio (Node.js), więc można go podpiąć bezpośrednio do klientów MCP (Claude Desktop, Cursor i inne).

MCP (Model Context Protocol) to otwarty standard pozwalający modelom językowym (Claude, GPT, Bielik.AI itp.) na wywoływanie zewnętrznych narzędzi i API w ustandaryzowany sposób.

Aktualna konstrukcja projektu

• Lokalny serwer stdio (Node.js), uruchamiany z dist/index.js.
• Brak warstw OAuth, token mintingu i rate-limitingu z wcześniejszej wersji cloudflare'owej.
• Cache in-memory w runtime lokalnym.
• Dystrybucja jako npm package + bundle MCPB (manifest.json).

Jeśli korzystasz z publicznie hostowanej instancji MCP (nie tej lokalnej z repo), polityka telemetryczna zależy od operatora tej instancji.

Dostępne bazy danych i narzędzia

| Narzędzie | Baza danych | Opis | | ------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- | | bn_search_publications | Biblioteka Nauki | Wyszukiwanie pełnotekstowe (API JSON portalu — frazy, tytuły, abstrakty) | | bn_search_articles | Biblioteka Nauki | Listowanie rekordów OAI-PMH (ListRecords) po datach i/lub zbiorze czasopisma — bez zapytań słownych | | bn_get_article | Biblioteka Nauki | Pobranie metadanych pojedynczego artykułu po ID (OAI-PMH GetRecord) | | rcin_search | RCIN — Repozytorium Cyfrowe Instytutów Naukowych | OAI-PMH ListRecords (metadane obiektów; opcjonalnie zakres dat / zbiór OAI) | | rcin_get_record | RCIN | OAI-PMH GetRecord po ID lub oai:rcin.org.pl:… | | ruj_search | RUJ — Repozytorium UJ | Wyszukiwanie publikacji z Repozytorium Jagiellońskiego | | ruj_get_item | RUJ | Pobranie metadanych pozycji po UUID | | agh_search | AGH — Repozytorium AGH | Wyszukiwanie prac i publikacji AGH w Krakowie | | agh_get_item | AGH | Pobranie metadanych pozycji po UUID | | amu_search | AMU — Repozytorium UAM | Wyszukiwanie publikacji Uniwersytetu Adama Mickiewicza | | amu_get_item | AMU | Pobranie metadanych pozycji po UUID | | uafm_search | UAFM — Repozytorium UAFM | Wyszukiwanie publikacji Akademii Nauk Stosowanych w Nowym Sączu | | uafm_get_item | UAFM | Pobranie metadanych pozycji po UUID | | icm_search | ICM — Otwarte Dane Badawcze UW | Wyszukiwanie danych badawczych ICM UW | | icm_get_item | ICM | Pobranie metadanych pozycji po UUID | | rodbuk_search | RODBuK | Wyszukiwanie zbiorów danych badawczych uczelni krakowskich | | repod_search | RePOD | Wyszukiwanie polskich otwartych danych badawczych | | repod_get_dataset | RePOD | Pobranie metadanych zbioru danych po DOI | | dane_search | dane.gov.pl | Wyszukiwanie danych otwartych z portalu rządowego | | dane_get_dataset | dane.gov.pl | Pobranie szczegółów zbioru danych po ID | | polon_search | POL-on / RAD-on | Zbiory otwarte: uczelnie, pracownicy, projekty, publikacje, kursy (JSON, token strony) | | pbn_search_publications | PBN — Polska Bibliografia Naukowa | Wyszukiwanie publikacji (JSON; wymaga PBN_APP_ID + PBN_APP_TOKEN) | | pbn_search_persons | PBN | Wyszukiwanie osób / ORCID (JSON; te same nagłówki co wyżej) | | pbn_get_publication | PBN | Metadane publikacji po id obiektu (JSON) | | bdl_search_subjects | BDL — Bank Danych Lokalnych (GUS) | Wyszukiwanie tematów (subjectów) po fragmencie nazwy (API v1) | | bdl_search_variables | BDL / GUS | Wyszukiwanie zmiennych statystycznych (cech) | | bdl_search_units | BDL / GUS | Wyszukiwanie jednostek terytorialnych (TERYT itd.) | | bdl_get_variable | BDL / GUS | Metadane jednej zmiennej po id liczbowym | | bdl_get_data_by_variable | BDL / GUS | Wartości dla jednej zmiennej po jednostkach (np. województwa) | | bdl_get_data_by_unit | BDL / GUS | Wartości dla jednej jednostki i wskazanych zmiennych | | imgw_synop | IMGW-PIB | Aktualne odczyty ze stacji synoptycznych (pogodowych) | | imgw_hydro | IMGW-PIB | Aktualne odczyty z wodowskazów i stacji hydrologicznych | | imgw_meteo | IMGW-PIB | Aktualne odczyty ze stacji meteorologicznych | | imgw_warnings | IMGW-PIB | Aktywne ostrzeżenia meteorologiczne i hydrologiczne | | pkn_search | PKN — Polski Komitet Normalizacyjny | Wyszukiwarka treści strony www.pkn.pl (Drupal / Solr, HTML) | | wiedza_search_norms | WIEDZA — PKN | Wyszukiwarka norm (Liferay; sesja + POST, HTML) | | wiedza_get_standard | WIEDZA | Karta pojedynczej normy po numerze katalogowym (HTML) | | blz_search | Baza Legalnych Źródeł (Legalna Kultura) | WordPress REST /wp/v2/listings — źródła kultury cyfrowej (JSON) | | blz_get_listing | Baza Legalnych Źródeł | Pojedyncze źródło po ID (JSON) | | blz_listing_categories | Baza Legalnych Źródeł | Taksonomia listing_cat (Filmy, Muzyka, Biblioteki…) — ID do blz_search | | baztol_search | BazTOL — brama zasobów PUT | Wyszukiwanie pełnotekstowe (HTML; katalog nieaktualizowany od 2022) | | baztol_browse_domain | BazTOL | Przeglądanie po dziedzinie (id z menu) | | baztol_get_resource | BazTOL | Szczegóły zasobu po ID (HTML) | | nac_news_rss | NAC — Narodowe Archiwum Cyfrowe | Kanał RSS aktualności instytucji (XML) | | nac_site_search | NAC | Wyszukiwarka WordPress REST (?rest_route=/wp/v2/search; posty/strony; JSON) | | nac_get_post | NAC | Pojedynczy wpis blogowy po id (JSON) | | nac_get_page | NAC | Pojedyncza strona statyczna po id (JSON) | | sum_aleph_find | Katalog Biblioteki ŚUM (Aleph) | X-Services op=find — zapytanie WWW (wrd=, wti=…; XML; możliwy błąd SRU po stronie serwera) | | sum_aleph_present | Katalog ŚUM / Aleph | X-Services op=present — rekord(y) MARC/XML (set_no, set_entry) | | ludzie_search | Ludzie Nauki | Wyszukiwanie profili naukowców (nazwisko, dziedzina, paginacja) | | ludzie_semantic_search | Ludzie Nauki | Wyszukiwanie semantyczne / pełnotekstowe po frazie | | ludzie_get_scientist | Ludzie Nauki | ORCID, stopnie/tytuły, słowa kluczowe dla profilu po ID | | pauart_search | PAUart — PAU | Wyszukiwanie katalogu dzieł (Collectio / PAU) | | pauart_get_artwork | PAUart | Metadane pojedynczego dzieła po ID z katalogu | | isap_search_acts | ISAP — ELI API Sejmu | Wyszukiwanie aktów prawnych (tytuł, słowa kluczowe ISAP, daty, DU/MP itd.) | | isap_get_act | ISAP / ELI | Metadane pojedynczego aktu po ELI, np. DU/2026/370 | | bs_sejm_search | Biblioteka Sejmowa — OPAC | Wyszukiwanie słowne (func=find-b); zwraca HTML listy (np. bis01, pos01) | | bs_sejm_get_item | Biblioteka Sejmowa | Karta bibliograficzna (func=item-global) po doc_library + doc_number — HTML | | saos_search_judgments | SAOS | Wyszukiwanie orzeczeń (fraza all, daty, sygnatura, sąd, typ orzeczenia) | | saos_get_judgment | SAOS / API przeglądania | Pełne orzeczenie po id liczbowym z wyszukiwarki | | saos_dump_services | SAOS / API pobierania | Lista endpointów hurtowego pobierania (dump) | | saos_dump_common_courts | SAOS — dump | Słownik sądów powszechnich (stronicowanie) | | saos_dump_sc_chambers | SAOS — dump | Słownik izb SN (stronicowanie) | | saos_dump_judgments | SAOS — dump | Hurtowe orzeczenia (filtry dat / synchronizacja; duże odpowiedzi) | | saos_dump_enrichments | SAOS — dump | Etykiety modułu wzbogacania (stronicowanie) | | wolnelektury_list_taxonomy | Wolne Lektury | Słowniki: autorzy, epoki, gatunki, rodzaje, motywy, kolekcje (slugi) | | wolnelektury_filter_books | Wolne Lektury | Lista utworów po filtrach (autor/epoka/gatunek/rodzaj); nie woła /api/books/ w całości | | wolnelektury_get_book | Wolne Lektury | Metadane i linki do plików po slugu utworu | | wolnelektury_get_collection | Wolne Lektury | Kolekcja tematyczna + lista książek w kolekcji | | ninateka_search | Ninateka — FINA VOD | Wyszukiwanie materiałów po słowie kluczowym (JSON API frontu; platform=BROWSER) | | ninateka_get_vod | Ninateka | Metadane pojedynczego materiału po id liczbowym z wyszukiwarki (JSON) | | gapla_search | Gapla — galeria plakatu filmowego FINA | Wyszukiwanie plakatów (szukaj.html — tytuł / autor / reżyseria; HTML) | | gapla_get_poster | Gapla | Strona pojedynczego plakatu po id (plakat/{id}.html — HTML) | | fototeka_search | Fototeka — FN INA | Wyszukiwanie fotosów i zdjęć (wyszukiwarka.html — tytuł / osoba / reżyseria / słowa kluczowe; HTML, paginacja pageNumber / howmany) | | fototeka_get_photo | Fototeka | Strona pojedynczego zdjęcia po id (/pl/foto/view/{id}.html — HTML) | | filmpolski_search | FilmPolski.pl (PWSFTviT) | Wyszukiwarka bazy filmu (index.php?szukaj=&rodzaj= — HTML parsowane do JSON: osoby, filmy; tryby fragment / początek / dokładnie) | | filmpolski_get_item | FilmPolski.pl | Karta rekordu po id (index.php/{id}) — tekst z <article id="film|osoba"> (obcięty) | | fototekaslaska_search | Fototeka Śląska (MWO Opole) | Wyszukiwanie zdjęć (WordPress GET ?s=&t=&y=; HTML z .search-list → JSON: slug, URL, podpis, miniatura) | | fototekaslaska_get_photo | Fototeka Śląska | Strona rekordu /galeria/{slug}/ — tytuł, nr katalogowy, URL zdjęcia, opis i tabela (tekst) | | fn_repo_search | Repozytorium FN | Wyszukiwanie Solr (HTML — kafelki wyników; brak publicznego JSON API) | | fn_repo_get_node | Repozytorium FN | Karta rekordu po id węzła Drupal (/?q=pl/node/{id} — HTML) | | fn_repo_film_index | Repozytorium FN | Indeks tytułów po pierwszej literze (A–Ż / INNE — HTML) | | fn_repo_browse_kind | Repozytorium FN | Przegląd: fabularne / dokumentalne / animacje / magazyn (HTML) | | dokumenty_slaska_get_page | Dokumenty Śląska | Pobranie pojedynczej strony statycznej po ścieżce względnej (indeks …, dokument …, podkatalogi — HTML) | | dokumenty_slaska_medieval_catalog | Dokumenty Śląska | Lista JSON ścieżek do głównej serii dokumentów średniowiecznych (okresy do 1333 r.) — pomoc nawigacyjna | | eval_response | — (lokalnie) | Ewaluacja odpowiedzi modelu względem rekordu źródłowego (RQ2) |

Biblioteka Sejmowa — katalog OPAC

Katalog Biblioteki Sejmowej działa w systemie Aleph (interfejs jak w przeglądarce). Nie udostępnia publicznego API JSON ani dokumentacji SRU dla maszynowego dostępu w stylu REST — narzędzia bs_sejm_search i bs_sejm_get_item wołają te same adresy co formularz WWW (func=find-b — lista wyników, func=item-global — pełna karta rekordu) i zwracają surowe HTML.

Typowy przepływ: bs_sejm_search z parametrem local_base (np. bis01 — katalog główny, bis05 — artykuły z czasopism, pos01 — nagrania z posiedzeń, tek01 — teksty konstytucji) → z HTML listy wyników odczytaj z linków item-global wartości doc_library i doc_number → bs_sejm_get_item. Pełna lista baz jest na stronie startowej katalogu.

Uwaga: to nie jest to samo co api.sejm.gov.pl — akty prawne i metadane ISAP obsługują osobne narzędzia isap_* (ELI API).

Fototeka, FilmPolski, Fototeka Śląska i Dokumenty Śląska

Fototeka (Filmoteka Narodowa — INA) nie publikuje osobnego REST/OpenAPI. Wyniki wyszukiwania są serwowane jako HTML (/pl/strona/wyszukiwarka.html z parametrami key, search_type, pageNumber, howmany). fototeka_get_photo zwraca stronę rekordu (/pl/foto/view/{id}.html). Wewnętrzny endpoint ajax.html (JSON z fragmentami HTML) wymaga pełnego formularza sesji i nie jest używany w narzędziu.

FilmPolski.pl — Internetowa Baza Filmu Polskiego; brak publicznego API JSON. Wyszukiwanie to GET na index.php (szukaj, rodzaj: fragment / początek / dokładnie). Osoby w bazie są jako „nazwisko, imię” (w trybie dokładnie wymagany jest przecinek). Narzędzia parsują HTML do zwartego JSON (filmpolski_search) i zwracają tekst z głównego artykułu rekordu (filmpolski_get_item). Regulamin serwisu ogranicza kopiowanie całej bazy — używaj krótkich fragmentów i podawaj źródło.

Fototeka Śląska (Muzeum Wsi Opolskiego) działa na WordPressie — istnieje ogólne /wp-json/, ale typ wpisów galerii nie ma publicznego endpointu wp/v2/... dla pojedynczych rekordów. Wyszukiwanie jak na stronie głównej: GET z s (fraza), t (tytuł / miejscowość / powiat / opis / nr katalogowy), opcjonalnie y (okres historyczny), paged (strona). fototekaslaska_search bierze tylko blok .search-list, żeby nie mieszać wyników z sekcją „Ostatnio dodane”. fototekaslaska_get_photo pobiera /galeria/{slug}/. Prawa do zdjęć pozostają po stronie muzeum — bez masowego pobierania plików.

Dokumenty Śląska to statyczna witryna (pliki indeks … / dokument … i podkatalogi) — brak API i centralnej wyszukiwarki. dokumenty_slaska_get_page pobiera jeden zasób po bezpiecznej ścieżce względnej; dokumenty_slaska_medieval_catalog to stała lista JSON ścieżek głównej serii średniowiecznej (nawigacja, nie zapytanie full-text).

NAC i katalog ŚUM (Aleph)

Narodowe Archiwum Cyfrowe — strona instytucji na WordPressie: narzędzia nac_* używają kanału RSS (/feed/) oraz WordPress REST przez fallback ?rest_route=/wp/v2/... (często stabilniejszy niż /wp-json/... przy ochronach WAF). Zdigitalizowane materiały archiwalne są w serwisie Szukaj w Archiwach (informacje NAC) — brak tam publicznego, udokumentowanego API do przeszukiwania katalogu z Workerów; często działa też ochrona przed botami (Incapsula).

Katalog Biblioteki Śląskiego Uniwersytetu Medycznego to OPAC Aleph (Ex Libris). Interfejs maszynowy: Aleph X-Services pod https://katalog.sum.edu.pl/X (odpowiedzi XML), zgodnie z dokumentacją Ex Libris. sum_aleph_find woła op=find (np. request=wrd=…); na instalacji może pojawić się komunikat o braku konfiguracji bramki SRU — wtedy wyszukiwanie przez X-Server wymaga naprawy po stronie biblioteki. sum_aleph_present (op=present, format marc itd.) służy do pobrania rekordów z numeru zestawu i pozycji.

Większość baz oferuje otwarty dostęp do odczytu bez obowiązkowych kluczy API. Wyjątki: narzędzia WIEDZA (wiedza_*) nie buforują odpowiedzi w KV (sesja Liferay); PKN www (pkn_search) ma krótszy TTL cache niż repozytoria akademickie. BDL (GUS) działa anonimowo, ale możesz ustawić zmienną środowiskową BDL_CLIENT_ID (nagłówek X-ClientId), jeśli masz klucz z Portalu API GUS — wtedy wyższe limity wywołań po stronie GUS. Dokumentacja REST: https://bdl.stat.gov.pl/api/v1/ (OpenAPI: …/swagger/doc/swagger.json).

PBN (wymagane dostępy): aby włączyć narzędzia pbn_search_publications, pbn_search_persons i pbn_get_publication, musisz mieć aktywny dostęp do API PBN i ustawić co najmniej PBN_APP_ID + PBN_APP_TOKEN (opcjonalnie PBN_USER_TOKEN). Dostęp i rejestracja aplikacji: OpenAPI PBN oraz Centrum pomocy PBN.

Wymagania

• Node.js 18+
• npm

Instalacja i uruchomienie lokalne

# 1. Sklonuj repozytorium
git clone https://github.com/asterixix/polish-academic-mcp.git
cd polish-academic-mcp

# 2. Zainstaluj zależności
npm install

# 3. Zbuduj projekt
npm run build

# 4. Uruchom serwer MCP
npm start

Tryb deweloperski:

npm run dev

Uruchomienie bez lokalnego builda (globalnie przez npm registry):

npx -y polish-academic-mcp

Bundle MCPB

Repo zawiera manifest MCPB i wspiera pakowanie do pliku bundle.

npm run bundle:mcpb

Wynik:

• release/polish-academic-mcp.mcpb

Pełny flow release (build, testy, bundle, publish):

npm run release

Podłączenie klientów MCP

Claude Desktop

Preferowana konfiguracja (stabilniejsza niż npx w środowiskach GUI):

{
  "mcpServers": {
    "polish-academic-mcp": {
      "command": "node",
      "args": ["D:/polish-academic-mcp/dist/index.js"]
    }
  }
}

Lokalizacja pliku:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Cursor i inne klienty MCP

Użyj analogicznego polecenia stdio:

node D:/polish-academic-mcp/dist/index.js

Troubleshooting (Claude: "Server transport closed unexpectedly")

Jeśli po initialize połączenie się zamyka:

1. Użyj bezpośrednio node + ścieżki absolutnej do dist/index.js (nie npx).
2. Upewnij się, że build istnieje: npm run build.
3. Sprawdź, czy Claude widzi poprawny Node w swoim środowisku PATH.
4. Odczytaj stderr serwera:
   • stdin end
   • stdin close

Wpisy stdin end/close zwykle oznaczają, że host zamknął stdin procesu MCP.

Zmienne środowiskowe

Opcjonalne zmienne używane przez wybrane narzędzia:

• BDL_CLIENT_ID
• WEB3FORMS_ACCESS_KEY
• PBN_APP_ID
• PBN_APP_TOKEN
• PBN_USER_TOKEN

Architektura techniczna (obecna)

Klient MCP (Claude/Cursor/itp.)
       │  stdio JSON-RPC
       ▼
Node runtime (src/index.ts)
  ├── StdioServerTransport
  ├── createServer(env)
  └── tools/* (rejestracja narzędzi źródłowych)

Kluczowe decyzje projektowe:

• Lokalny, prosty transport stdio.
• Brak middleware OAuth/rate-limit (usunięte z wersji cloudflare).
• Odpowiedzi z narzędzi zwracane w formacie przyjaznym MCP.
• In-memory cache dla runtime lokalnego.

Development

npm run lint
npm run build

Wskazówki contributorskie:

• CONTRIBUTING.md
• AGENTS.md

Licencja

MIT