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

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

Podłączenie klientów MCP (konfiguracja npx)

Poniżej znajdziesz aktualne, praktyczne konfiguracje dla najpopularniejszych hostów MCP. Ten pakiet działa jako lokalny serwer stdio, więc podstawowy wariant to:

{
  "command": "npx",
  "args": ["-y", "polish-academic-mcp"]
}

0) Wymagania wspólne

1. Zainstaluj Node.js 18+.

2. Upewnij się, że npx działa w terminalu (npx --version).

3. W klientach GUI (Desktop) sprawdź, czy aplikacja widzi npx w PATH.

1) Claude Code (CLI)

Najprościej przez komendę:

claude mcp add --transport stdio polish-academic-mcp -- npx -y polish-academic-mcp

Sprawdzenie:

claude mcp list

Uwaga dla Windows (poza WSL):

claude mcp add --transport stdio polish-academic-mcp -- cmd /c npx -y polish-academic-mcp

2) Claude Desktop

Claude Desktop promuje obecnie Desktop Extensions (.mcpb), ale ręczna konfiguracja mcpServers nadal jest spotykana.

Przykład:

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

Typowe lokalizacje pliku konfiguracji:

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

• Windows: %APPDATA%/Claude/claude_desktop_config.json

• Linux: zależnie od sposobu instalacji desktopowej (zwykle katalog konfiguracyjny aplikacji Claude)

3) ChatGPT

W ChatGPT (Apps/Connectors oraz Responses API) oficjalnie używa się zdalnych MCP (HTTP/SSE), nie lokalnego stdio uruchamianego przez npx bezpośrednio w aplikacji.

To oznacza, że dla tego pakietu masz 2 ścieżki:

1. Używaj go lokalnie w klientach obsługujących stdio (Claude Code, Gemini CLI, LM Studio, AnythingLLM, Cursor).

2. Jeśli koniecznie chcesz ChatGPT: wystaw serwer jako zdalny endpoint MCP (HTTP/SSE), a potem podłącz URL w ChatGPT.

4) Gemini (Gemini CLI)

Gemini CLI obsługuje MCP przez mcpServers w settings.json oraz komendy gemini mcp ....

Przykład settings.json:

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

Lub przez CLI:

gemini mcp add polish-academic-mcp npx -y polish-academic-mcp

5) LM Studio

Od LM Studio 0.3.17 dostępne są lokalne i zdalne MCP. Konfiguracja używa formatu mcp.json (zgodnego z notacją Cursor).

Przykład mcp.json:

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

6) AnythingLLM (Desktop / Docker)

AnythingLLM czyta konfigurację z plugins/anythingllm_mcp_servers.json (w katalogu storage AnythingLLM).

Przykład:

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

Uwaga: AnythingLLM uruchamia MCP-y przy wejściu w „Agent Skills” lub wywołaniu agenta (niekoniecznie od razu przy starcie aplikacji).

7) Perplexity

Perplexity publikuje oficjalny własny serwer MCP (np. https://mcp.perplexity.ai/mcp) do użycia w klientach MCP.

Jeśli celem jest uruchomienie tego pakietu (polish-academic-mcp) bezpośrednio „wewnątrz Perplexity”, publiczna dokumentacja Perplexity skupia się obecnie na korzystaniu z endpointów MCP, a nie na lokalnym stdio przez npx jako w klasycznych klientach desktopowych.

8) Inne klienty (Cursor, Windsurf, Cline, Open WebUI itd.)

W większości przypadków działa standardowy wpis mcpServers:

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

Jeśli klient wspiera tylko zdalne MCP, potrzebny będzie endpoint HTTP/SSE zamiast lokalnego stdio.

Źródła (oficjalne / referencyjne)

• OpenAI Developers (MCP and Connectors): https://developers.openai.com/api/docs/guides/tools-connectors-mcp

• OpenAI Developers (Building MCP servers for ChatGPT Apps): https://developers.openai.com/api/docs/mcp

• Claude Code docs (MCP): https://code.claude.com/docs/en/mcp

• Claude Help Center (Claude Desktop + local MCP): https://support.claude.com/en/articles/10949351-getting-started-with-model-context-protocol-mcp-on-claude-for-desktop

• Gemini CLI docs (MCP servers): https://geminicli.com/docs/tools/mcp-server/

• LM Studio docs (Use MCP Servers): https://lmstudio.ai/docs/app/mcp

• AnythingLLM docs (overview): https://docs.anythingllm.com/mcp-compatibility/overview

• AnythingLLM docs (desktop): https://docs.anythingllm.com/mcp-compatibility/desktop

• AnythingLLM docs (docker): https://docs.anythingllm.com/mcp-compatibility/docker

• Perplexity MCP URL (referencje integracyjne): https://mcp.perplexity.ai/mcp

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 dla chętnych do pomocy:

• CONTRIBUTING.md

• AGENTS.md

Licencja

MIT