bpp-mcp 0.1.0__py3-none-any.whl

bpp_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""Serwer MCP dla API BPP (Bibliografia Publikacji Pracowników).
+
+Wystawia read-only API BPP (`/api/v1/`) jako kuratorowane narzędzia MCP:
+wyszukiwanie publikacji i autorów, pobieranie rozwiniętych rekordów
+(z autorami/źródłem/streszczeniami zamiast hyperlinków), harvest list
+publikacji oraz małe słowniki referencyjne.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

bpp_mcp/auth.py

@@ -0,0 +1,110 @@
+"""Warstwa OAuth Resource Server: weryfikacja opaque tokenu BPP przez
+``whoami`` oraz przekazanie tokenu BIEŻĄCEGO requestu do BppClient.
+
+Token BPP jest OPAQUE (nie JWT) — weryfikacja tylko zdalnie przez
+``GET /api/v1/whoami/``: 200 → ważny, 401/403 → nieważny (``None`` →
+transportowy 401), inne/sieć/nie-JSON → :class:`WhoamiUnavailable` (BPP
+niedostępne; materializuje się jako HTTP 500 — klient NIE robi re-auth).
+
+UWAGA (K1): do passthrough NIE używamy ``get_access_token()`` — w stateful
+streamable HTTP zwraca on token z chwili ``initialize`` (stale). Token
+bieżącego requestu bierzemy z ``ctx.request_context.request`` (patrz
+``server._client``) i mostkujemy przez ContextVar poniżej.
+"""
+
+from __future__ import annotations
+
+import time
+from contextvars import ContextVar
+
+import httpx
+from mcp.server.auth.provider import AccessToken
+
+_current_bearer: ContextVar[str | None] = ContextVar(
+    "bpp_mcp_current_bearer", default=None
+)
+
+
+class WhoamiUnavailable(Exception):
+    """BPP niedostępne przy weryfikacji tokenu (nie-200/401/403, sieć, nie-JSON).
+
+    Różne od ``None`` (token nieważny → re-auth): token mógł być ważny, więc
+    nie wymuszamy re-autoryzacji — request kończy się błędem serwera (5xx).
+    """
+
+
+def set_current_bearer(token: str | None) -> None:
+    """Zapisz token bieżącego requestu w kontekście (dla BppClient)."""
+    _current_bearer.set(token)
+
+
+def current_bearer() -> str | None:
+    """Zwróć token bieżącego requestu z kontekstu (``None`` poza http)."""
+    return _current_bearer.get()
+
+
+def bearer_from_request(request) -> str | None:
+    """Wyłuskaj surowy token z nagłówka ``Authorization: Bearer`` (lub None)."""
+    if request is None:
+        return None
+    authz = request.headers.get("authorization", "")
+    if authz.lower().startswith("bearer "):
+        return authz.split(" ", 1)[1].strip()
+    return None
+
+
+class WhoamiTokenVerifier:
+    """``TokenVerifier`` (protokół SDK) oparty o ``whoami`` BPP, z positive-cache.
+
+    Cache (``ttl`` s) redukuje +1 request/wywołanie i wygładza blipy; ma eviction
+    (usuwa wygasłe) i twardy cap ``max_entries`` (drop najstarszego), by proces
+    nie akumulował zrewokowanych tokenów w nieskończoność.
+    """
+
+    def __init__(
+        self, base_url: str, *, ttl: float = 30.0, max_entries: int = 256
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._ttl = ttl
+        self._max_entries = max_entries
+        self._cache: dict[str, tuple[AccessToken, float]] = {}
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        now = time.monotonic()
+        cached = self._cache.get(token)
+        if cached is not None and cached[1] > now:
+            return cached[0]
+        url = f"{self._base_url}/api/v1/whoami/"
+        headers = {"Authorization": f"Bearer {token}", "Accept": "application/json"}
+        try:
+            async with httpx.AsyncClient(
+                timeout=httpx.Timeout(10.0, connect=5.0), follow_redirects=True
+            ) as client:
+                resp = await client.get(url, headers=headers)
+        except httpx.HTTPError as exc:
+            raise WhoamiUnavailable(f"whoami niedostępne: {exc}") from exc
+        if resp.status_code in (401, 403):
+            return None
+        if resp.status_code != 200:
+            raise WhoamiUnavailable(f"whoami zwróciło {resp.status_code}")
+        try:
+            data = resp.json()
+        except ValueError as exc:
+            raise WhoamiUnavailable(f"whoami zwróciło nie-JSON: {exc}") from exc
+        access = AccessToken(
+            token=token,
+            client_id="bpp-mcp",
+            scopes=["read"],
+            subject=str(data["id"]) if data.get("id") is not None else None,
+            claims=data,
+        )
+        self._store(token, access, now)
+        return access
+
+    def _store(self, token: str, access: AccessToken, now: float) -> None:
+        if len(self._cache) >= self._max_entries:
+            for k in [k for k, (_, exp) in self._cache.items() if exp <= now]:
+                del self._cache[k]
+            while len(self._cache) >= self._max_entries:
+                self._cache.pop(next(iter(self._cache)))
+        self._cache[token] = (access, now + self._ttl)

bpp_mcp/catalog.py

@@ -0,0 +1,163 @@
+"""Kuratorowana wiedza o kształcie API BPP dzielona przez narzędzia MCP.
+
+Zawiera:
+
+* :data:`CATALOG` — mapa ``typ → {endpoint, relacje do rozwinięcia}`` dla
+  pięciu typów rekordów obecnych w :class:`Rekord` (ciągłe, zwarte, patent,
+  praca doktorska, praca habilitacyjna). Steruje głębokością rozwijania
+  hyperlinków w :func:`bpp_mcp.tools.pobierz_rekord`,
+* :data:`SLOWNIKI` — biała lista MAŁYCH tabel referencyjnych dostępnych przez
+  :func:`bpp_mcp.tools.slownik`,
+* :data:`SLOWNIKI_WOLUMENOWE` — jawnie odrzucane „słowniki" o dużej liczności
+  (konferencja/wydawca/nagroda), które nie należą do :func:`slownik`,
+* helpery normalizacji identyfikatorów rekordów.
+
+Świadomie utrzymywane ręcznie (bez generatora z YAML — YAGNI). Weryfikowane
+z serializerami ``src/api_v1/serializers/`` instancji BPP.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TypRekordu:
+    """Opis jednego typu publikacji i jego relacji do rozwinięcia."""
+
+    endpoint: str
+    # Pole listy przez-autorskiej (through) z płaskim ``zapisany_jako``.
+    # ``None`` gdy typ nie ma tabeli through (prace dr/hab mają pojedynczy
+    # ``autor`` jako bezpośredni URL — patrz ``relacje_pojedyncze``).
+    autorzy: str | None = None
+    # Relacje 1:1 — pojedynczy URL do rozwinięcia w obiekt.
+    relacje_pojedyncze: tuple[str, ...] = ()
+    # Relacje 1:N — lista URL-i do rozwinięcia w listę obiektów.
+    relacje_wielokrotne: tuple[str, ...] = ()
+    # Białe listy filtrów opcjonalnych (poza uniwersalnym zakresem roku
+    # i ``zmienione_po``) faktycznie honorowanych przez django-filter danego
+    # endpointu. django-filter CICHO ignoruje nieznane parametry, więc
+    # doklejenie np. ``charakter_formalny`` do typu, który go nie filtruje,
+    # dałoby fałszywie „przefiltrowany" wynik. Sterują walidacją w
+    # :func:`bpp_mcp.tools.lista_publikacji`.
+    filtry_dodatkowe: frozenset[str] = frozenset()
+
+
+CATALOG: dict[str, TypRekordu] = {
+    # Wydawnictwo ciągłe: autorzy (through), źródło, streszczenia, zewn. bazy.
+    "wydawnictwo_ciagle": TypRekordu(
+        endpoint="wydawnictwo_ciagle",
+        autorzy="autorzy_set",
+        relacje_pojedyncze=("zrodlo",),
+        relacje_wielokrotne=("streszczenia", "zewnetrzna_baza_danych"),
+        filtry_dodatkowe=frozenset({"charakter_formalny"}),
+    ),
+    # Wydawnictwo zwarte: NIE ma zrodlo ani zewnetrzna_baza_danych; ma serię.
+    # ``wydawnictwo_nadrzedne`` świadomie NIE rozwijane (ryzyko rekurencji) —
+    # pozostaje jako goły URL w wyniku.
+    "wydawnictwo_zwarte": TypRekordu(
+        endpoint="wydawnictwo_zwarte",
+        autorzy="autorzy_set",
+        relacje_pojedyncze=("seria_wydawnicza",),
+        relacje_wielokrotne=("streszczenia",),
+        filtry_dodatkowe=frozenset({"charakter_formalny"}),
+    ),
+    # Patent: tylko autorzy (through). rodzaj_prawa/zasieg są inline (string).
+    "patent": TypRekordu(
+        endpoint="patent",
+        autorzy="autorzy_set",
+    ),
+    # Prace dr/hab: pojedynczy bezpośredni autor (+ promotor/jednostka/wydawca),
+    # bez tabeli through.
+    "praca_doktorska": TypRekordu(
+        endpoint="praca_doktorska",
+        autorzy=None,
+        relacje_pojedyncze=("autor", "promotor", "jednostka", "wydawca"),
+    ),
+    "praca_habilitacyjna": TypRekordu(
+        endpoint="praca_habilitacyjna",
+        autorzy=None,
+        relacje_pojedyncze=("autor", "jednostka", "wydawca"),
+    ),
+}
+
+TYPY_REKORDOW: tuple[str, ...] = tuple(CATALOG.keys())
+
+
+# Biała lista małych tabel referencyjnych (jedno żądanie ?limit=500).
+SLOWNIKI: tuple[str, ...] = (
+    "charakter_formalny",
+    "typ_kbn",
+    "jezyk",
+    "dyscyplina_naukowa",
+    "rodzaj_zrodla",
+    "poziom_wydawcy",
+    "funkcja_autora",
+    "tytul",
+    "czas_udostepnienia_openaccess",
+)
+
+# Dane wolumenowe udające słowniki — jawnie odrzucane z czytelnym błędem.
+SLOWNIKI_WOLUMENOWE: tuple[str, ...] = (
+    "konferencja",
+    "wydawca",
+    "nagroda",
+    "seria_wydawnicza",
+    "zrodlo",
+    "autor",
+    "jednostka",
+)
+
+
+# Biała lista prefiksów endpointów, których odpowiedzi wolno cache'ować w
+# procesie (:meth:`bpp_mcp.client.BppClient.get_json`). To WYŁĄCZNIE stabilne,
+# powtarzalnie odpytywane tabele referencyjne / encje słownikowe (jednostka,
+# źródło, wydawca, słowniki). Świadomie POZA whitelistą: rekordy publikacji,
+# streszczenia, tabele through-autorów oraz raporty ``recent_*`` — to dane
+# zmienne albo jednorazowe, których cache'owanie tylko puchłoby i groziło
+# staleness. Brak prefiksu na liście ⇒ odpowiedź NIE ląduje w cache, nawet
+# przy ``use_cache=True``.
+PREFIKSY_CACHOWALNE: frozenset[str] = frozenset(SLOWNIKI) | frozenset(
+    {
+        "jednostka",
+        "zrodlo",
+        "wydawca",
+        "seria_wydawnicza",
+        "konferencja",
+        "nagroda",
+    }
+)
+
+
+def rozbij_rekord_url(url: str | None) -> tuple[str | None, str | None]:
+    """Z ``rekord_url`` (``/szukaj/``) wyłuskaj ``(typ, pk)``.
+
+    Mapę ct→typ budujemy dynamicznie z samego URL-a (segment endpointu),
+    NIE z numerycznych ID ContentType (per-instancja). Przykład::
+
+        ".../api/v1/wydawnictwo_ciagle/123/" -> ("wydawnictwo_ciagle", "123")
+    """
+    if not url:
+        return (None, None)
+    segmenty = [s for s in url.split("/") if s]
+    for i, seg in enumerate(segmenty):
+        if seg in CATALOG and i + 1 < len(segmenty):
+            return (seg, segmenty[i + 1])
+    return (None, None)
+
+
+def rozbij_tuple_id(surowy: object) -> tuple[int | None, int | None]:
+    """Sparsuj identyfikator ``Rekord`` w formacie ``"(6, 123)"`` z ``recent_*``.
+
+    Zwraca ``(content_type_id, pk)`` lub ``(None, None)`` przy złym wejściu.
+    """
+    if not isinstance(surowy, str):
+        return (None, None)
+    wnetrze = surowy.strip().strip("()")
+    czesci = wnetrze.split(",")
+    if len(czesci) != 2:
+        return (None, None)
+    try:
+        return (int(czesci[0]), int(czesci[1]))
+    except ValueError:
+        return (None, None)

bpp_mcp/client.py

@@ -0,0 +1,304 @@
+"""Asynchroniczny klient HTTP dla API BPP.
+
+Cechy (wg specu Fazy 2):
+
+* jeden współdzielony ``httpx.AsyncClient`` (zakładany w lifespanie serwera),
+* ``timeout = Timeout(10.0, connect=5.0)``,
+* nagłówek ``Accept: application/json`` (NIE ``?format=json``),
+* retry×2 z narastającym backoffem na błędy sieciowe / 5xx (GET jest
+  idempotentny),
+* semafor współbieżności (domyślnie 8) — ogranicza równoległe rozwijanie
+  hyperlinków w :func:`bpp_mcp.tools.pobierz_rekord`,
+* procesowy cache ``URL → JSON`` OGRANICZONY do białej listy prefiksów
+  słownikowo-referencyjnych (:data:`bpp_mcp.catalog.PREFIKSY_CACHOWALNE` —
+  jednostka/źródło/wydawca/słowniki). Rekordy publikacji, streszczenia,
+  through-autorzy i raporty ``recent_*`` NIE są cache'owane (dane zmienne /
+  jednorazowe → cache tylko by puchł i groził staleness),
+* auto-follow paginacji ``LimitOffset`` porcjami po ``PAGE_LIMIT`` do zadanego
+  ``limit`` (z twardym sufitem liczby stron — bezpiecznik przed zapętleniem),
+* mapowanie 404 na czytelny :class:`BppNotFound` zamiast tracebacku; przy 4xx
+  do komunikatu dołączamy fragment ciała odpowiedzi (wskazówka walidacji DRF).
+
+Żadnego bare ``except`` — łapiemy wąskie typy httpx i re-raise'ujemy sensowny
+błąd domenowy.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from .auth import current_bearer
+from .catalog import PREFIKSY_CACHOWALNE
+
+# Rozmiar pojedynczej strony przy auto-follow paginacji. Stronicujemy porcjami
+# zamiast żądać całego ``limit`` jednym requestem — chroni instancję BPP przed
+# skrajnie dużym ``?limit=`` (BPP nie deklaruje ``max_limit`` po stronie DRF).
+PAGE_LIMIT = 50
+
+
+class BppError(Exception):
+    """Bazowy, czytelny błąd domenowy zwracany narzędziom MCP.
+
+    Gdy błąd pochodzi z odpowiedzi HTTP (4xx/5xx), niesie ``status_code`` oraz
+    (dla 4xx z ciałem JSON) zdeserializowany ``payload`` — narzędzia mapują je
+    na sensowne komunikaty (np. 400 DjangoQL → pozycja błędu, 503 → „zawęź").
+    """
+
+    def __init__(
+        self, *args: object, status_code: int | None = None, payload: Any = None
+    ) -> None:
+        super().__init__(*args)
+        self.status_code = status_code
+        self.payload = payload
+
+
+class BppNotFound(BppError):
+    """Zasób zwrócił 404 (rekord ukryty, niewidoczny lub nieistniejący)."""
+
+
+class BppNetworkError(BppError):
+    """Trwały błąd sieci / 5xx po wyczerpaniu prób."""
+
+
+class BppClient:
+    """Cienka, kuratorowana warstwa nad ``httpx.AsyncClient``."""
+
+    def __init__(
+        self,
+        config,
+        *,
+        concurrency: int = 8,
+        max_retries: int = 2,
+        backoff_base: float = 0.5,
+    ) -> None:
+        self._api_root = config.api_root
+        self._auth_tuple = config.auth_tuple
+        self._transport = config.transport
+        self._client = httpx.AsyncClient(
+            timeout=httpx.Timeout(10.0, connect=5.0),
+            headers={"Accept": "application/json"},
+            follow_redirects=True,
+        )
+        self._sem = asyncio.Semaphore(concurrency)
+        self._cache: dict[str, Any] = {}
+        self._max_retries = max_retries
+        self._backoff_base = backoff_base
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    @property
+    def transport(self) -> str:
+        """Tryb transportu (``stdio``/``http``) — steruje hybrydową
+        podpowiedzią logowania w narzędziach zapytań DjangoQL."""
+        return self._transport
+
+    async def __aenter__(self) -> BppClient:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    def _full_url(self, url: str, params: dict | None = None) -> httpx.URL:
+        """Zbuduj pełny URL: bezwzględny przyjmujemy wprost, względny
+        doklejamy do korzenia API. ``params`` mergujemy w query string."""
+        if url.startswith("http://") or url.startswith("https://"):
+            full = httpx.URL(url)
+        else:
+            full = httpx.URL(f"{self._api_root}/{url.lstrip('/')}")
+        if params:
+            czyste = {k: v for k, v in params.items() if v is not None}
+            if czyste:
+                full = full.copy_merge_params(czyste)
+        return full
+
+    def _auth_kwargs(self) -> dict[str, Any]:
+        """Per-request auth. Bearer (bieżący request) wygrywa zawsze. W trybie
+        http brak bearera = błąd (żadnego cichego fallbacku na konto serwisowe).
+        W stdio: Basic (gdy skonfigurowany) albo anonimowo."""
+        bearer = current_bearer()
+        if bearer:
+            return {"headers": {"Authorization": f"Bearer {bearer}"}}
+        if self._transport == "http":
+            raise BppError(
+                "Brak tokenu OAuth w kontekście żądania (tryb http) — nie "
+                "forwarduję anonimowo ani przez konto serwisowe."
+            )
+        if self._auth_tuple:
+            return {"auth": self._auth_tuple}
+        return {}
+
+    async def _request(self, full: httpx.URL, *, retry_5xx: bool = True) -> Any:
+        """Wykonaj GET z retry×N i backoffem. Zwraca zdeserializowany JSON.
+
+        ``retry_5xx=False`` wyłącza ponawianie na 5xx (błąd sieci nadal jest
+        ponawiany) — używane przez zapytania DjangoQL, bo 503 = deterministyczny
+        ``statement_timeout``, więc ponawianie tylko 3× re-uruchamiałoby ten sam
+        wolny SQL.
+        """
+        auth_kwargs = self._auth_kwargs()
+        ostatni: Exception | None = None
+        for proba in range(self._max_retries + 1):
+            async with self._sem:
+                try:
+                    resp = await self._client.get(full, **auth_kwargs)
+                except httpx.HTTPError as exc:
+                    # Błąd transportu (connect/read/timeout) — kwalifikuje do retry.
+                    ostatni = exc
+                else:
+                    if resp.status_code == 404:
+                        raise BppNotFound(
+                            f"Zasób nie istnieje lub jest niewidoczny: {full}"
+                        )
+                    if resp.status_code >= 500:
+                        blad_5xx = BppNetworkError(
+                            f"Serwer BPP zwrócił {resp.status_code} dla {full}",
+                            status_code=resp.status_code,
+                        )
+                        # ``retry_5xx=False`` → od razu podnosimy (bez ponawiania
+                        # deterministycznego 503 statement_timeout).
+                        if not retry_5xx:
+                            raise blad_5xx
+                        ostatni = blad_5xx
+                    else:
+                        try:
+                            resp.raise_for_status()
+                        except httpx.HTTPStatusError as exc:
+                            # 4xx: dołącz fragment ciała odpowiedzi — DRF zwraca
+                            # tam komunikat walidacji (np. że charakter_formalny
+                            # oczekuje PK ze slownik(...)), co jest wskazówką dla
+                            # LLM-a. Bez tego zostawał sam suchy kod stanu.
+                            tresc = " ".join(resp.text.split())[:300]
+                            dodatek = f" — {tresc}" if tresc else ""
+                            try:
+                                # Ciało 4xx bywa JSON-em (DjangoQL 400:
+                                # {error,line,column,mark}) — zachowaj strukturę.
+                                payload = resp.json()
+                            except ValueError:
+                                payload = None
+                            raise BppError(
+                                f"Błąd HTTP {resp.status_code} dla {full}{dodatek}",
+                                status_code=resp.status_code,
+                                payload=payload,
+                            ) from exc
+                        return resp.json()
+            if proba < self._max_retries:
+                await asyncio.sleep(self._backoff_base * (proba + 1))
+        raise BppNetworkError(
+            f"Nie udało się pobrać {full} po {self._max_retries + 1} próbach: {ostatni}"
+        ) from ostatni
+
+    @staticmethod
+    def _prefiks_cachowalny(full: httpx.URL) -> bool:
+        """Czy pierwszy segment ścieżki po ``/api/v1/`` jest na białej liście
+        prefiksów wolno-cache'owalnych (:data:`PREFIKSY_CACHOWALNE`)."""
+        segmenty = [s for s in full.path.split("/") if s]
+        if "v1" in segmenty:
+            idx = segmenty.index("v1")
+            prefiks = segmenty[idx + 1] if idx + 1 < len(segmenty) else None
+        else:
+            prefiks = segmenty[0] if segmenty else None
+        return prefiks in PREFIKSY_CACHOWALNE
+
+    async def get_json(
+        self,
+        url: str,
+        params: dict | None = None,
+        *,
+        use_cache: bool = True,
+        retry_5xx: bool = True,
+    ) -> Any:
+        """Pobierz i zdeserializuj JSON.
+
+        Cache procesowy po pełnym URL-u działa TYLKO gdy ``use_cache`` jest
+        prawdą ORAZ prefiks endpointu jest na białej liście
+        :data:`PREFIKSY_CACHOWALNE` (słowniki, jednostki, źródła, wydawcy).
+        Rekordy publikacji, streszczenia i through-autorzy nie trafiają do
+        cache nawet przy ``use_cache=True`` — cache nie rośnie w nieskończoność.
+        """
+        full = self._full_url(url, params)
+        klucz = str(full)
+        cachowalne = use_cache and self._prefiks_cachowalny(full)
+        if cachowalne and klucz in self._cache:
+            return self._cache[klucz]
+        dane = await self._request(full, retry_5xx=retry_5xx)
+        if cachowalne:
+            self._cache[klucz] = dane
+        return dane
+
+    async def get_paginated(
+        self,
+        path: str,
+        params: dict | None = None,
+        limit: int = 25,
+        *,
+        page_limit: int = PAGE_LIMIT,
+        retry_5xx: bool = True,
+    ) -> tuple[list[Any], int, bool]:
+        """Auto-follow paginacji ``LimitOffset`` do zebrania ``limit`` pozycji.
+
+        Stronicuje porcjami po ``min(page_limit, limit)`` (NIE żąda całego
+        ``limit`` jednym requestem — chroni instancję BPP), podążając za
+        ``next`` aż do wyczerpania stron (``next == null``) lub osiągnięcia
+        ``limit``. Strony list nie są cache'owane (zmienne, jednorazowe).
+
+        Zwraca krotkę ``(zebrane, laczna_liczba, niepelne)``:
+
+        * ``laczna_liczba`` — serwerowy ``count`` z pierwszej strony
+          (rzeczywista liczba trafień po stronie BPP, ≠ ``len(zebrane)`` przy
+          obcięciu do ``limit``),
+        * ``niepelne`` — ``True`` gdy pętlę przerwał BEZPIECZNIK (sufit liczby
+          stron / powtórzony ``next``) mimo że ``next`` był wciąż niepusty, więc
+          pobranie mogło NIE objąć wszystkiego, co było w zasięgu ``limit``.
+          ``False`` przy naturalnym końcu (``next == null``) lub dobiciu limitu.
+
+        Bezpieczniki przed zapętleniem zbugowanego serwera:
+
+        * twardy sufit liczby stron (``limit // per_page + 2``),
+        * przerwanie, gdy ``next`` wskazuje na dokładnie ten sam URL co przed
+          chwilą, albo gdy strona nie wniosła żadnych nowych pozycji.
+        """
+        per_page = max(1, min(page_limit, limit))
+        maks_stron = limit // per_page + 2
+        zebrane: list[Any] = []
+        laczna: int | None = None
+        query = dict(params or {})
+        query["limit"] = per_page
+        url: str | None = path
+        pierwsza = True
+        poprzedni_url: str | None = None
+        strony = 0
+        niepelne = False
+        while url is not None and len(zebrane) < limit:
+            if strony >= maks_stron or url == poprzedni_url:
+                # Przerwanie przez bezpiecznik (NIE naturalne next=null ani
+                # dobicie limitu): ``next`` wciąż wskazuje kolejną stronę, ale
+                # zatrzymujemy się, by nie zapętlić się na zbugowanym serwerze.
+                # Sygnalizujemy, że pobranie może być niepełne.
+                niepelne = True
+                break
+            poprzedni_url = url
+            if pierwsza:
+                dane = await self.get_json(
+                    url, params=query, use_cache=False, retry_5xx=retry_5xx
+                )
+                pierwsza = False
+            else:
+                dane = await self.get_json(url, use_cache=False, retry_5xx=retry_5xx)
+            strony += 1
+            if not isinstance(dane, dict):
+                break
+            if laczna is None and isinstance(dane.get("count"), int):
+                laczna = dane["count"]
+            nowe = dane.get("results", [])
+            if not nowe:
+                break
+            zebrane.extend(nowe)
+            url = dane.get("next")
+        zebrane = zebrane[:limit]
+        if laczna is None:
+            laczna = len(zebrane)
+        return zebrane, laczna, niepelne

bpp_mcp/config.py

@@ -0,0 +1,84 @@
+"""Konfiguracja serwera MCP: bazowy URL instancji BPP oraz opcjonalny
+BasicAuth (używany wyłącznie dla raportów slotów — poza rdzeniem v1).
+
+Wielo-instancyjność: ta sama binarka obsługuje dowolne wdrożenie BPP
+(umlub oraz inne), różnicowane przez zmienną środowiskową ``BPP_BASE_URL``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+_BRAK_HOSTA = (
+    "Nie ustawiono BPP_BASE_URL — nie wiadomo, z którą instancją BPP rozmawiać.\n"
+    "Wskaż ją jawnie, np.:\n"
+    "    BPP_BASE_URL=https://bpp.twoja-uczelnia.pl bpp-mcp\n"
+    "W konfiguracji klienta MCP ustaw tę zmienną w sekcji `env`."
+)
+
+
+class BrakKonfiguracji(RuntimeError):
+    """Brakuje obowiązkowego ustawienia — serwer nie ma prawa zgadywać."""
+
+
+@dataclass(frozen=True)
+class Config:
+    """Niezmienny zestaw ustawień połączenia z instancją BPP."""
+
+    base_url: str
+    basic_auth: str | None = None
+    transport: str = "stdio"
+    http_host: str = "127.0.0.1"
+    http_port: int = 8000
+    resource_url: str | None = None
+
+    @classmethod
+    def from_env(cls) -> Config:
+        """Zbuduj konfigurację ze zmiennych środowiskowych.
+
+        - ``BPP_BASE_URL`` — bazowy URL instancji (WYMAGANY, bez domyślnego),
+        - ``BPP_BASIC_AUTH`` — opcjonalny ``user:pass`` (raporty slotów),
+        - ``BPP_MCP_TRANSPORT`` — ``stdio`` (dom.) | ``http`` (OAuth),
+        - ``BPP_MCP_HTTP_HOST`` / ``BPP_MCP_HTTP_PORT`` — bind serwera HTTP,
+        - ``BPP_MCP_RESOURCE_URL`` — nadpisanie pola ``resource`` w PRM.
+
+        ``BPP_BASE_URL`` nie ma wartości domyślnej celowo. Każde wdrożenie BPP
+        to inna uczelnia i inna bibliografia, więc zaszyty host oznaczałby, że
+        użytkownik bez tej zmiennej dostaje cudze dane wyglądające na własne —
+        błąd cichy i trudny do zauważenia. Lepiej nie wystartować.
+
+        :raises BrakKonfiguracji: gdy ``BPP_BASE_URL`` jest pusty lub nieustawiony.
+        """
+        base = (os.environ.get("BPP_BASE_URL") or "").strip()
+        if not base:
+            raise BrakKonfiguracji(_BRAK_HOSTA)
+        auth = os.environ.get("BPP_BASIC_AUTH") or None
+        transport = os.environ.get("BPP_MCP_TRANSPORT", "stdio").lower()
+        return cls(
+            base_url=base,
+            basic_auth=auth,
+            transport="http" if transport == "http" else "stdio",
+            http_host=os.environ.get("BPP_MCP_HTTP_HOST", "127.0.0.1"),
+            http_port=int(os.environ.get("BPP_MCP_HTTP_PORT", "8000")),
+            resource_url=os.environ.get("BPP_MCP_RESOURCE_URL") or None,
+        )
+
+    @property
+    def api_root(self) -> str:
+        """Korzeń API v1, bez końcowego ukośnika."""
+        return f"{self.base_url.rstrip('/')}/api/v1"
+
+    @property
+    def effective_resource_url(self) -> str:
+        """URL zasobu (pole ``resource`` w protected-resource-metadata).
+        Domyślnie kanoniczny URI serwera streamable: host:port + ``/mcp``."""
+        return self.resource_url or f"http://{self.http_host}:{self.http_port}/mcp"
+
+    @property
+    def auth_tuple(self) -> tuple[str, str] | None:
+        """Rozbij ``user:pass`` na krotkę dla httpx (lub ``None``)."""
+        if not self.basic_auth:
+            return None
+        user, _, password = self.basic_auth.partition(":")
+        return (user, password)