波兰学术数据库检索 MCP 服务

Polish Academic MCP

Serwer MCP, dzięki któremu asystent AI (Claude, Copilot, Cursor, Gemini, model lokalny w LM Studio i inne) przeszukuje polskie bazy naukowe, publiczne i kulturowe: Bibliotekę Nauki, repozytoria uczelni, GUS, ISAP, orzeczenia sądów, Wolne Lektury, archiwa filmowe i fotograficzne. 125 narzędzi, 55 źródeł, bez kont i kluczy API (poza opcjonalnym PBN).

Serwer działa na Twoim komputerze: aplikacja AI uruchamia go sama w tle, a serwer łączy się bezpośrednio z bazami, bez pośredniczących usług.

MCP (Model Context Protocol) to otwarty standard, dzięki któremu asystenci AI mogą korzystać z zewnętrznych narzędzi i baz danych.

Szybki start (bez programowania)

1. Zainstaluj Node.js. Wejdź na nodejs.org, pobierz wersję LTS i zainstaluj ją jak zwykły program (wszystkie opcje domyślne).

2. Uruchom kreator. Otwórz terminal:

• Windows: menu Start → wpisz „PowerShell” → Enter,
• macOS: Cmd+Spacja → wpisz „Terminal” → Enter,
• Linux: Ctrl+Alt+T,

a potem wklej i zatwierdź Enterem:

npx -y polish-academic-mcp setup

Kreator sam znajdzie zainstalowane aplikacje AI, zapyta, które bazy włączyć, i dopisze serwer do ich ustawień (z kopią zapasową poprzednich). Przed zapisem zamknij te aplikacje.

3. Uruchom aplikację AI ponownie (całkowicie: zamknij ją też z zasobnika systemowego lub paska menu) i zapytaj na przykład:

Wyszukaj w Bibliotece Nauki artykuły o odnawialnych źródłach energii z 2024 roku.

Coś nie działa? Uruchom npx -y polish-academic-mcp doctor, a potem zajrzyj do rozwiązywania problemów.

Instalacja jednym kliknięciem

Jeśli masz już Node.js:

Przyciski dodają wszystkie 125 narzędzi. Cursor pokazuje modelowi najwyżej ok. 40 narzędzi, więc tam lepiej wybrać jedną lub dwie grupy baz.

Quick start (English)

Install Node.js LTS, then run npx -y polish-academic-mcp setup. The wizard detects your AI apps and adds the server to their MCP config (with a backup). Restart the app. Use --sources=nauka,prawo (or the POLISH_ACADEMIC_SOURCES env var) to expose only some of the 125 tools, and npx -y polish-academic-mcp doctor to diagnose problems.

Obsługiwane aplikacje

Szczegółowe instrukcje dla każdej aplikacji (pliki konfiguracyjne, ręczna konfiguracja, weryfikacja): docs/CLIENTS.md. Jeśli konfigurację ma wykonać agent AI, daj mu docs/AGENT-GUIDE.md.

Wersja chmurowa (Cloudflare Workers + Pages)

Oprócz lokalnego npx możesz wdrożyć zdalne środowisko z katalogu cloud/:

• serwer MCP HTTP z OAuth 2.1 (ORCID, email+hasło, passkey) pod /mcp,
• limity: 100 zapytań narzędzi / miesiąc (MCP), 2 / tydzień AI Search bez logowania, 5 / tydzień po zalogowaniu,
• wyszukiwanie językiem naturalnym w przeglądarce (AI Mode) z Cloudflare AI Gateway i modelem anthropic/claude-haiku-5.5,
• strony /connectors, /privacy, /terms pod oficjalne konektory Claude, ChatGPT i Perplexity.

Instrukcja wdrożenia i sekrety: docs/CLOUDFLARE.md.

Opcje kreatora

npx -y polish-academic-mcp setup                          # interaktywnie
npx -y polish-academic-mcp setup --list                   # obsługiwane aplikacje i ścieżki plików
npx -y polish-academic-mcp setup --client cursor --sources nauka --yes   # bez pytań
npx -y polish-academic-mcp setup --dry-run                # pokaż zmiany, nic nie zapisuj
npx -y polish-academic-mcp setup --pin                    # przypnij bieżącą wersję (zob. Aktualizacje)
npx -y polish-academic-mcp setup --print zed              # konfiguracja do wklejenia ręcznie
npx -y polish-academic-mcp uninstall                      # usuń serwer z aplikacji
npx -y polish-academic-mcp doctor                         # diagnostyka

Kreator zachowuje inne serwery i ustawienia w plikach (także Twoje zmienne we wpisie serwera, np. klucze PBN, przy ponownym uruchomieniu), przed każdą zmianą robi kopię (*.bak-<data>) i nie rusza plików z komentarzami (JSONC); dla nich wypisuje wpis do wklejenia. Na Windows zapisuje polecenie cmd /c npx …, a przy Node.js zainstalowanym przez nvm, fnm lub volta pełną ścieżkę do npx. Dzięki temu aplikacje okienkowe znajdą Node.js.

Wybór baz

Opisy wszystkich 125 narzędzi zajmują ok. 38 tys. tokenów kontekstu przy każdym zapytaniu. Dla Claude czy GPT to nie problem, ale małe modele lokalne gubią się przy tylu narzędziach, a część aplikacji ma limity (Cursor ok. 40, Windsurf 100, VS Code 128 narzędzi łącznie ze wszystkich serwerów). Włącz tylko to, czego potrzebujesz:

Kreator setup pyta o grupy. Ręcznie ustawisz je zmienną POLISH_ACADEMIC_SOURCES w sekcji env serwera:

{
  "mcpServers": {
    "polish-academic": {
      "command": "npx",
      "args": ["-y", "polish-academic-mcp"],
      "env": { "POLISH_ACADEMIC_SOURCES": "nauka,prawo" }
    }
  }
}

albo argumentem: "args": ["-y", "polish-academic-mcp", "--sources=nauka,prawo"]. Możesz łączyć grupy z pojedynczymi bazami (nauka,isap) i wykluczać (nauka,-pbn). Pełna lista identyfikatorów: npx -y polish-academic-mcp --list-sources. Nieznane nazwy są pomijane z ostrzeżeniem w logu, a pusty wybór włącza wszystko, więc literówka nie wyłączy serwera.

Wszystkie bazy i narzędzia

Kraków — Otwarte Dane, MSIP i Bank Informacji o Mieście i Metropolii

Trzy źródła grupy dane pokrywają wszystkie publicznie dostępne dane Miasta Krakowa:

• Otwarte Dane Miasta Krakowa (krakow_od_*): 45 zbiorów w 12 kategoriach (m.in. bezrobocie i oferty pracy GUP, cudzoziemcy i zameldowani w 18 dzielnicach, statystyki demograficzne od 1995 r., żłobki/przedszkola/szkoły, parki miejskie i kieszonkowe, zarejestrowane pojazdy, ruch turystyczny od 2015 r., Komunikacja Miejska KMK, działalność Biblioteki Kraków, muzeów, teatrów i ośrodków kultury, biegi miejskie). Każdy zbiór z tabelami danych udostępnia REST API na api.um.krakow.pl (WSO2 API Manager, format OData JSON {value:[...]}, eksport JSON/CSV/XLSX, dokumentacja Swagger per tabela); katalog wszystkich 42 API OD-*: https://api.um.krakow.pl/api/am/devportal/v3/apis?limit=100, portal deweloperski: https://api.um.krakow.pl/devportal. Zbiory bez tabel API (np. KMK) linkują warstwy ArcGIS Hub ZTP.
• MSIP — Miejski System Informacji Przestrzennej (krakow_msip_*): Katalog danych i usług ze 179 zbiorami przestrzennymi (budynki/działki ewidencyjne, adresy i ulice EMUiA, dzielnice, MPZP i decyzje WZ, mapy hałasu, ortofotomapy, zameldowania) z plikami SHP/DXF/JSON (ZIP), usługami WMS/WFS i metadanymi ISO 19115; katalog metadanych Geoportal (863 rekordy, https://msip.um.krakow.pl/geoportal/rest/metadata/search); usługi ArcGIS REST na dwóch serwerach: https://msip3.um.krakow.pl/server/rest/services (ArcGIS Server 12.1, 36 folderów: Demografia, Geodezja, Planowanie, Pobieranie, Transport, Zdrowie, Zabytki…) oraz https://msip.um.krakow.pl/arcgis/rest/services (10.81: Obserwatorium, Metropolia Krakowska, Hosted), z zapytaniami query do warstw (EPSG:2178; folder Pobieranie: Adresy, Budynki, Decyzje_Pnb, Decyzje_Wz, Dzialki, Dzielnice, Ulice, Wybory).
• Strategia Krakowa — Bank Informacji o Mieście i Metropolii (krakow_strategia_*): Raport o stanie Gminy (od 2018 r., załączniki PDF na plikimpi.krakow.pl), Raport o stanie Miasta, Kraków w liczbach / Krakow in numbers, Biuletyn Statystyczny (BIP), prognozy demograficzne dla Krakowa i MOF do 2050 roku, statystyka eksperymentalna (dojazdy do pracy, sytuacja demograficzna/dochodowa Krakowa, KOM i OSI), badania społeczne (Barometr Krakowski od 2015 r., Badanie Jakości Życia i Jakości Usług Publicznych) oraz 16 dziedzin zarządzania; wyszukiwarka portalu Rozwój Krakowa (POST, sp_port_id=128) i wersja PDF każdego artykułu (getPdf/?dok_id=).

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

Rozwiązywanie problemów

Najpierw uruchom npx -y polish-academic-mcp doctor. Sprawdza wersję Node.js, połączenie z bazami i to, które aplikacje mają skonfigurowany serwer.

Logi. Komunikaty serwera trafiają do logów aplikacji, np. Claude Desktop: ~/Library/Logs/Claude/mcp-server-polish-academic.log (macOS) lub %APPDATA%\Claude\logs\ (Windows). Aby zobaczyć każde zapytanie HTTP do baz (adres bez wartości parametrów, status, czas), dodaj do env serwera "POLISH_ACADEMIC_DEBUG": "1".

Aktualizacje. Przy wpisie npx -y polish-academic-mcp (bez numeru wersji) npx przy starcie aplikacji sprawdza, czy jest nowsza wersja, i ją pobiera. Jeśli wolisz aktualizować świadomie (np. w pracowni lub firmie), przypnij wersję: npx -y polish-academic-mcp setup --pin zapisze polish-academic-mcp@<wersja>. Aktualizacja to wtedy npx -y polish-academic-mcp@<nowa-wersja> setup --pin po sprawdzeniu nowej wersji.

Odinstalowanie. npx -y polish-academic-mcp uninstall usuwa wpis z aplikacji (z kopią zapasową pliku).

Zmienne środowiskowe

Wszystkie są opcjonalne. Ustawia się je w sekcji env wpisu serwera w konfiguracji aplikacji.

Dla programistów

git clone https://github.com/asterixix/polish-academic-mcp.git
cd polish-academic-mcp
npm install
npm run build
npm test            # testy kontraktowe, konfiguracji klientów i polityki sieciowej
npm run dev         # serwer stdio z src/index.ts
npm run smoke:tools # test na żywo wszystkich narzędzi (wymaga internetu)

Lokalny build podłączysz do aplikacji poleceniem node i ścieżką bezwzględną do dist/index.js. Do ręcznych testów przyda się MCP Inspector: npx @modelcontextprotocol/inspector node dist/index.js.

Aplikacja AI (Claude, Cursor, VS Code…)
       │  stdio JSON-RPC
       ▼
src/index.ts   CLI (setup, doctor, --sources) + StdioServerTransport
src/server.ts  createServer(): rejestruje wybrane źródła z src/sources.ts
src/tools/*    jeden plik na bazę; odpowiedzi to surowe dane ze źródła
src/cache.ts   cache w pamięci, limit 30 s, jedna ponowna próba przy błędach sieci

Jak dodać nową bazę: AGENTS.md. Zasady współpracy: CONTRIBUTING.md.

Polityka prywatności (Privacy Policy)

Niniejsza sekcja określa zasady prywatności dla lokalnego serwera MCP (polish-academic-mcp, repozytorium: https://github.com/asterixix/polish-academic-mcp) oraz zdalnego konektora chmurowego dostępnego pod adresem https://pamcp.pl (wymóg katalogów Anthropic Claude, OpenAI ChatGPT oraz Perplexity). Pełna wersja online jest dostępna pod adresem https://pamcp.pl/privacy (oraz regulamin pod https://pamcp.pl/terms, dokumentacja konektora pod https://pamcp.pl/connectors).

1. Praktyki zbierania danych (Data Collection Practices):
   • Serwer lokalny (npx polish-academic-mcp): działa w całości na komputerze użytkownika i nie zbiera, nie przechowuje ani nie przesyła żadnych danych osobowych, telemetrii ani identyfikatorów sesji do autora pakietu.
   • Zdalny konektor chmurowy (https://pamcp.pl/mcp): stosuje minimalizację danych (Privacy by Design). Narzędzia przyjmują wyłącznie parametry wyszukiwania (frazy, identyfikatory rekordów, sygnatury aktów). Serwer nie pobiera historii czatu klienta, nie zbiera lokalizacji GPS ani danych wrażliwych (PHI, PCI DSS, numerów PESEL/SSN, haseł). Dla potrzeb autoryzacji OAuth 2.1 przetwarzany jest wyłącznie adres e-mail (lub ORCID iD / klucz publiczny passkey WebAuthn), kryptograficzny skrót SHA-256 tokenu OAuth oraz licznik przydziału zapytań.
2. Wykorzystanie i przechowywanie (Usage and Storage):
   • Dane konta i autoryzacji w wersji chmurowej służą wyłącznie do uwierzytelniania OAuth 2.1 (PKCE S256), realizacji zapytań w trybie tylko do odczytu (readOnlyHint: true, destructiveHint: false) oraz egzekwowania limitów zapytań w bazie Cloudflare D1.
   • Odpowiedzi z publicznych API są tymczasowo buforowane (cache) w pamięci RAM (lokalnie) lub Cloudflare KV (w chmurze) bez powiązania z tożsamością użytkownika.
3. Udostępnianie podmiotom trzecim (Third-Party Sharing):
   • Nie sprzedajemy ani nie udostępniamy danych osobowych podmiotom trzecim ani sieciom reklamowym.
   • Zapytania wyszukiwawcze (bez danych konta użytkownika) są wysyłane bezpośrednio do publicznych interfejsów API 51 polskich instytucji naukowych, statystycznych, prawnych i archiwalnych (m.in. Biblioteka Nauki, GUS BDL, Sejm ELI / ISAP, SAOS, Wolne Lektury, Archiwa Państwowe).
   • W wersji chmurowej podmiotem przetwarzającym infrastrukturę jest Cloudflare, Inc., a przy logowaniu przez ORCID — ORCID, Inc.
4. Okres przechowywania (Data Retention):
   • Dane konta: do momentu usunięcia konta na żądanie użytkownika.
   • Kody autoryzacyjne OAuth: 10 minut; tokeny dostępowe: 1 godzina; tokeny odświeżające: 30 dni lub do odwołania.
   • Cache publicznych odpowiedzi API: od 1 do 24 godzin.
5. Dane kontaktowe (Contact Information):
   • Administrator danych i wsparcie techniczne: Artur Sendyka
   • E-mail: artur@sendyka.dev
   • Serwis chmurowy i konektor MCP: https://pamcp.pl (https://pamcp.pl/mcp)
   • Strona autora: https://sendyka.dev
   • Kod źródłowy oraz zgłoszenia błędów i bezpieczeństwa: https://github.com/asterixix/polish-academic-mcp / Issues

Licencja

MIT