Polish Academic MCP

Zdalny serwer MCP działający na Cloudflare Workers, który udostępnia wiele polskich baz danych i serwisów publicznych jako narzędzia wywoływane przez AI.

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.

WAŻNE! Serwer zdalny (link do cloudflare) zbiera domyślnie anonimowe dane ewaluacyjne z każdego zapytania narzędzia MCP jako dane do dalszych badań i ewaluacji, czyli jak używasz tego narzędzia to tak jakbyś wypełniał dla mnie ankietę do badań <3 Dzięki za zrozumienie!

Jeśli nie chcesz przekazywać mi danych badawczych wystarczy odpalić serwer lokalnie ;)

Autoreklama: Token JWT i wsparcie dla OAuth

Jeśli interesuje Ciebie większy rate limiting i w tym wsparcie do OAuth co da ci możliwość podpiąć MCP np. pod Perplexity to napisz na artur@sendyka.dev z zapytaniem. Jeśli wykorzystanie będzie znaczne (no tak powyżej 100 requestów na dobę) czy komercyjne to niestety będzie to już odpłatne.

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 API (/wp-json/wp/v2/…). 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). nac_site_search może zwracać HTTP 403 z niektórych sieci — z edge Cloudflare zachowanie bywa inne.

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 (pbn_*): dostęp do API produkcyjnego wymaga par PBN_APP_ID / PBN_APP_TOKEN (oraz opcjonalnie PBN_USER_TOKEN) — rejestracja aplikacji instytucji według Centrum pomocy PBN.

Wymagania dla developmentu

• Node.js 18 lub nowszy

• Konto Cloudflare (darmowe)

• Wrangler CLI (instalowany jako zależność deweloperska)

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. Uruchom serwer deweloperski
npm run dev
# → Serwer MCP dostępny pod adresem http://localhost:8788/mcp

Testowanie z MCP Inspector

npx @modelcontextprotocol/inspector@latest
# Otwórz http://localhost:5173
# W polu "Server URL" wpisz: http://localhost:8788/mcp
# Kliknij "Connect"

Wdrożenie na Cloudflare Workers

Krok 1 — Zaloguj się do Cloudflare

npx wrangler login

Krok 2 — Utwórz przestrzenie nazw KV

npx wrangler kv namespace create "CACHE_KV"
# Skopiuj zwrócone "id" i wklej do wrangler.jsonc jako id dla CACHE_KV

npx wrangler kv namespace create "RATE_LIMIT_KV"
# Skopiuj zwrócone "id" i wklej do wrangler.jsonc jako id dla RATE_LIMIT_KV

Krok 3 — Zaktualizuj wrangler.jsonc

Otwórz wrangler.jsonc i zastąp wartości placeholder prawdziwymi ID:

"kv_namespaces": [
  {
    "binding": "CACHE_KV",
    "id": "WKLEJ_TUTAJ_ID_CACHE_KV",
    "preview_id": "WKLEJ_TUTAJ_ID_CACHE_KV"
  },
  {
    "binding": "RATE_LIMIT_KV",
    "id": "WKLEJ_TUTAJ_ID_RATE_LIMIT_KV",
    "preview_id": "WKLEJ_TUTAJ_ID_RATE_LIMIT_KV"
  }
]

Krok 4 — Wdróż

npm run deploy
# → Dostępny pod adresem: https://polish-academic-mcp.<twoje-konto>.workers.dev/mcp

Podłączenie klientów MCP

Claude Desktop

Dodaj do pliku konfiguracyjnego Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "polish-academic": {
      "command": "npx",
      "args": ["mcp-remote", "https://polish-academic-mcp.kolpol25.workers.dev/mcp"]
    }
  }
}

Lokalizacja pliku konfiguracyjnego:

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

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

Claude.ai (Connector)

1. Przejdź do Ustawienia → Connectors → Dodaj własny connector

2. Wpisz URL serwera: https://polish-academic-mcp.kolpol25.workers.dev/mcp

3. Kliknij Zapisz

Podłączenie z OpenAI / ChatGPT

ChatGPT.com (plan Plus / Pro / Team / Enterprise)

ChatGPT obsługuje zdalne serwery MCP przez protokół Streamable HTTP.

1. Otwórz ChatGPT.com i zaloguj się

2. Przejdź do Ustawienia (Settings) → Połączone aplikacje (Connected apps)

3. Kliknij Dodaj narzędzia (Add tools) → Serwer MCP (MCP server)

4. Wpisz URL serwera:

   https://polish-academic-mcp.kolpol25.workers.dev/mcp

5. Nadaj nazwę (np. Polish Academic) i zapisz

Narzędzia będą dostępne podczas każdej rozmowy.

Uwaga: Funkcja dostępna dla subskrybentów ChatGPT Plus i wyższych planów. Opcja może znajdować się w innym miejscu menu w zależności od wersji interfejsu.

OpenAI Responses API (Python — programistycznie)

Biblioteka openai-agents (Python) obsługuje zdalne serwery MCP natywnie:

pip install openai-agents

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    async with MCPServerSse(
        url="https://polish-academic-mcp.kolpol25.workers.dev/mcp"
    ) as mcp_server:
        agent = Agent(
            name="Asystent Naukowy",
            model="gpt-4o",
            mcp_servers=[mcp_server],
        )
        result = await Runner.run(
            agent,
            "Wyszukaj artykuły o fotosytezie z Biblioteki Nauki",
        )
        print(result.final_output)

asyncio.run(main())

Możesz również użyć serwera MCP bezpośrednio przez Responses API:

from openai import OpenAI

client = OpenAI()  # OPENAI_API_KEY z env

response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_url": "https://polish-academic-mcp.kolpol25.workers.dev/mcp",
        "server_label": "polish-academic",
        "require_approval": "never",
    }],
    input="Znajdź polskie publikacje o uczeniu maszynowym",
)
print(response.output_text)

Podłączenie z Google Gemini

Gemini CLI

Gemini CLI obsługuje serwery MCP przez plik konfiguracyjny.

Edytuj plik ~/.gemini/settings.json (utwórz jeśli nie istnieje):

{
  "mcpServers": {
    "polish-academic": {
      "httpUrl": "https://polish-academic-mcp.kolpol25.workers.dev/mcp"
    }
  }
}

Po zapisaniu pliku uruchom Gemini CLI normalnie — narzędzia będą dostępne automatycznie:

gemini "Wyszukaj publikacje o astrofizyce w repozytorium Jagiellońskim"

Google AI Studio / Vertex AI Agent Builder

W Google AI Studio:

1. Otwórz projekt lub stwórz nowy

2. Przejdź do zakładki Tools → Add MCP server

3. Wpisz URL: https://polish-academic-mcp.kolpol25.workers.dev/mcp

4. Zapisz i przetestuj w Playground

Dla Vertex AI Agent Builder konfiguracja jest analogiczna w zakładce Tools → Extensions → MCP.

Google ADK (Agent Development Kit — Python)

pip install google-adk

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import MCPToolset, SseServerParams

academic_tools = MCPToolset(
    connection_params=SseServerParams(
        url="https://polish-academic-mcp.kolpol25.workers.dev/mcp"
    )
)

agent = Agent(
    name="asystent_naukowy",
    model="gemini-2.0-flash",
    tools=[academic_tools],
    instruction="Pomagasz w wyszukiwaniu polskiej literatury naukowej.",
)

Podłączenie z Perplexity

Perplexity nie obsługuje natywnie protokołu MCP w interfejsie webowym.
Możliwe podejścia:

Przez OpenAI-compatible SDK (Sonar API + narzędzia)

Perplexity Sonar API jest zgodne z formatem OpenAI. Możesz opisać narzędzia MCP ręcznie jako schematy funkcji:

from openai import OpenAI

client = OpenAI(
    api_key="<twój-klucz-perplexity>",
    base_url="https://api.perplexity.ai",
)

# Przykładowe wywołanie z function calling
tools = [
    {
        "type": "function",
        "function": {
            "name": "ruj_search",
            "description": "Szuka publikacji w Repozytorium UJ",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Zapytanie"},
                    "page": {"type": "integer", "default": 0},
                    "size": {"type": "integer", "default": 10},
                },
                "required": ["query"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Znajdź artykuły o kwantach"}],
    tools=tools,
)

Wywołania narzędzi musisz następnie obsłużyć ręcznie, przekazując je do serwera MCP przez HTTP.

Przez mcp-remote (lokalny proxy)

Jeśli używasz lokalnego klienta zgodnego z OpenAI tools, możesz uruchomić mcp-remote jako most:

# Zainstaluj mcp-remote
npm install -g mcp-remote

# Uruchom proxy (przekazuje wywołania MCP ↔ HTTP)
npx mcp-remote https://polish-academic-mcp.kolpol25.workers.dev/mcp

Proxy nawiązuje lokalne połączenie stdio, z którego możesz korzystać w dowolnym narzędziu obsługującym MCP stdio.

Inne klienty MCP

Wyślij żądanie HTTP POST do /mcp z nagłówkiem Accept: application/json, text/event-stream i treścią JSON-RPC 2.0.

Limity i buforowanie

Ograniczenie liczby żądań (Rate Limiting)

• 10 wywołań narzędzi na godzinę na adres IP klienta

• Żądania protokołu (inicjalizacja, lista narzędzi, ping) nie są wliczane do limitu

• Przy przekroczeniu limitu serwer zwraca HTTP 429 z nagłówkiem Retry-After

Cache odpowiedzi API

Odpowiedzi z zewnętrznych API są buforowane w Cloudflare KV:

Eksport danych ewaluacyjnych do Nextcloud (WebDAV)

Jeśli ustawisz EVAL_WEBDAV_ENABLED=true (w wrangler.jsonc/env), serwer zapisuje dane ewaluacyjne dla każdego wywołania MCP tools/call do Nextcloud przez WebDAV.

Wymagane zmienne:

• NEXTCLOUD_WEBDAV_BASE_URL

• NEXTCLOUD_WEBDAV_USERNAME

• NEXTCLOUD_WEBDAV_PASSWORD

Opcjonalne:

• NEXTCLOUD_WEBDAV_PATH_PREFIX (domyślnie mcp-eval)

• EVAL_WEBDAV_MAX_JSON_BYTES (domyślnie 120000)

Dla każdego tools/call robione jest PUT pliku JSON do WebDAV: NEXTCLOUD_WEBDAV_PATH_PREFIX/<tool>-<timestamp>-<uuid>.json. Plik zawiera surową odpowiedź (w tym _span) oraz pole rqEval — policzone metryki RQ1–RQ4, o ile wywołanie pasuje do przypadku testowego z scripts/eval/test-cases.ts.

Limity ogólne

Architektura techniczna

Klient MCP (Claude)
       │  HTTP POST /mcp (JSON-RPC 2.0)
       ▼
Cloudflare Worker (index.ts)
  ├── Rate limit check (RATE_LIMIT_KV)
  └── createMcpHandler(createServer(env))
           └── tools/
               ├── biblioteka-nauki.ts → Biblioteka Nauki (JSON + OAI-PMH)
               ├── ruj.ts, agh.ts, amu.ts, uafm.ts, icm.ts → DSpace 7 REST
               ├── rodbuk.ts, repod.ts → Dataverse REST
               ├── dane.ts → dane.gov.pl API
               ├── polon.ts → RAD-on Open Data (POL-on)
               ├── pbn.ts → Polska Bibliografia Naukowa (PBN REST; wymaga `PBN_APP_ID` / `PBN_APP_TOKEN`)
               ├── bdl.ts → BDL GUS
               ├── rcin.ts → RCIN OAI-PMH
               ├── pkn.ts, wiedza.ts → PKN / WIEDZA (HTML)
               ├── blz.ts → bazalegalnychzrodel.pl (WordPress REST)
               ├── baztol.ts → BazTOL PUT (HTML)
               ├── nac.ts → NAC nac.gov.pl (RSS + WordPress REST)
               ├── sum.ts → katalog.sum.edu.pl — Aleph X-Server (XML)
               ├── isap.ts → api.sejm.gov.pl/eli
               ├── sejm-bs.ts → Biblioteka Sejmowa OPAC (HTML)
               ├── saos.ts → SAOS API
               ├── wolne-lektury.ts → Wolne Lektury API (JSON)
               ├── ninateka.ts → Ninateka / FINA (JSON)
               ├── gapla.ts → Gapla FINA (HTML)
               ├── fototeka.ts → Fototeka FN (HTML)
               ├── filmpolski.ts → FilmPolski.pl (parsowanie HTML → JSON / tekst)
               ├── fototekaslaska.ts → Fototeka Śląska MWO (parsowanie HTML → JSON / tekst)
               ├── filmoteka-repo.ts → Repozytorium FN (HTML / Solr)
               ├── dokumenty-slaska.ts → Dokumenty Śląska (statyczny HTML)
               ├── ludzie-nauki.ts → Ludzie Nauki REST
               ├── imgw.ts → IMGW public API
               └── response-eval.ts → eval_response (lokalnie)

Kluczowe decyzje projektowe:

• Bezstanowy — nowa instancja McpServer na każde żądanie (wymagane od SDK 1.26.0)

• Kompaktowe podsumowania JSON dla repozytoriów DSpace 7 (RUJ, AGH, AMU, UAFM, ICM) zamiast surowego HAL+JSON — zmniejsza zużycie tokenów

• Surowe odpowiedzi XML/JSON/HTML bez warstwy normalizacji: Biblioteka Nauki (OAI-PMH XML oraz odpowiedź JSON z /api/search; dokumentacja OAI: doc.bibliotekanauki.pl), RCIN (OAI-PMH), WordPress REST (Baza Legalnych Źródeł, treści na nac.gov.pl), RAD-on JSON (POL-on), PBN (JSON), dane.gov.pl, BDL (GUS), ELI / ISAP (api.sejm.gov.pl), IMGW, katalog ŚUM (Aleph X-Server XML), Biblioteka Sejmowa OPAC (HTML), Ninateka (JSON API frontu SPA), Gapla (HTML), Fototeka (HTML), Repozytorium FN (HTML / Solr), Dokumenty Śląska (statyczny HTML) — oszczędza czas CPU

• Parsowanie HTML do JSON / tekstu (brak publicznego API pod wyszukiwarkę / galerię): FilmPolski.pl (filmpolski_*), Fototeka Śląska (fototekaslaska_*) — mniejsze zużycie tokenów niż pełne strony HTML

• Normalizacja wyników Dataverse dla rodbuk_search i repod_search do stabilnych pól (title, author, date, doi) przy zachowaniu danych źródłowych

• Fire-and-forget zapisy do KV — nie blokują odpowiedzi

Aktualizacje implementacji (RQ3/RQ4)

W ramach hardeningu ewaluacji dodano:

• Tryb minimalizacji danych osobowych (minimize_pii) w:

  • ruj_search — ukrywa pola autorów/afiliacji i redaguje typowe wzorce PII,

  • bn_search_articles — redaguje wzorce PII w odpowiedzi XML (m.in. ORCID, e-mail, PESEL-like, phone-like).

• Normalizację odpowiedzi Dataverse w:

  • rodbuk_search,

  • repod_search.

• Fallback odpornościowy w bn_search_articles:

  • gdy zapytanie z restrykcyjnym set zwróci noRecordsMatch, narzędzie ponawia zapytanie raz bez set (z zachowaniem from_date/until_date i metadata_format).

Domyślne zachowanie narzędzi pozostaje bezpieczne wstecznie (minimize_pii=false), więc istniejące integracje nie wymagają zmian.

Rozwój i wkład

Przeczytaj CONTRIBUTING.md — wskazówki dotyczące zgłaszania błędów, propozycji nowych baz danych i tworzenia pull requestów.

Dla agentów AI kodujących w tym projekcie: przeczytaj AGENTS.md.

Licencja

MIT © 2026 Artur Sendyka vel. asterixix na poczet Polskiej Nauki z wykorzystaniem AI