oai-pmh-mcp 0.1.0

Uniwersalny serwer MCP dla protokołu OAI-PMH — odpytuj dowolne repozytorium (dLibra, DSpace, EPrints, PMC…) przez Model Context Protocol

oai-pmh-mcp

Nic nie trzeba konfigurować — adres repozytorium podaje się przy wywołaniu narzędzia, więc jedna instalacja obsługuje dowolną liczbę repozytoriów. Ten pakiet nie jest jeszcze na PyPI, dlatego linki do Cursora i VS Code instalują go prosto z gita (uvx --from git+https://…).

Uniwersalny serwer MCP dla protokołu OAI-PMH (Open Archives Initiative – Protocol for Metadata Harvesting).

Pozwala dowolnemu klientowi MCP (Claude, ChatGPT, Cursor…) odpytywać dowolne publiczne repozytorium OAI-PMH — biblioteki cyfrowe oparte o dLibrę (np. Wielkopolska Biblioteka Cyfrowa), a także DSpace, EPrints, PubMed Central i inne — bez konfiguracji per-host. Adres repozytorium (base_url) podaje się w każdym wywołaniu.

Możliwości

Wierny wrapper sześciu czasowników OAI-PMH + wygodna nakładka do masowego pobierania:

Narzędzie	Rola
identify	tożsamość repozytorium (nazwa, wersja protokołu, granularność, polityka usuniętych)
list_metadata_formats	dostępne formaty metadanych (oai_dc, mods, marc…)
list_sets	kolekcje / zestawy
list_identifiers	same nagłówki rekordów (tani przegląd)
list_records	strona pełnych rekordów + token paginacji
get_record	pojedynczy rekord po identyfikatorze
harvest_records	auto-paginacja: pobiera wiele stron do limitu, z możliwością wznowienia

Wyjście w trzech formatach (format): text (domyślny, oszczędny tokenowo), json (maszynowy), xml (surowy oryginał).

Instalacja

uvx oai-pmh-mcp        # uruchomienie bez instalacji (stdio)
# lub
uv tool install oai-pmh-mcp

Konfiguracja klienta MCP

Claude Code

claude mcp add oai-pmh -- uvx oai-pmh-mcp

mcp.json (Cursor / inne)

{
  "mcpServers": {
    "oai-pmh": { "command": "uvx", "args": ["oai-pmh-mcp"] }
  }
}

Transport

Domyślnie stdio. Tryb zdalny streamable-HTTP:

oai-pmh-mcp --transport http --host 0.0.0.0 --port 8000

Przykład

„Sprawdź, jakie kolekcje ma https://www.wbc.poznan.pl/dlibra/oai-pmh-repository.xml i pokaż 5 najnowszych rekordów."

Model wywoła identify → list_sets → list_records i złoży odpowiedź.

Rozwój

uv sync
uv run pytest            # testy jednostkowe (offline, fixture'y)
uv run pytest -m integration   # testy sieciowe (opcjonalne)
uv run ruff check .

Zakres

OAI-PMH to protokół metadanych — serwer nie pobiera treści obiektów (skanów, PDF-ów). To read-only, bez autoryzacji, bez cache.

Bezpieczeństwo

• Parsowanie XML jest hartowane — parser nie rozwija encji ani nie sięga do sieci/DTD (ochrona przed XXE i „billion laughs" z niezaufanych repozytoriów).
• harvest_records ma twarde limity (max rekordów, max stron, przerwanie przy braku postępu) — złośliwy serwer nie zapętli klienta.
• SSRF z natury narzędzia: serwer pobiera dowolny base_url podany przez klienta (taki jest cel). Dozwolone są tylko schematy http/https. Jeśli wdrażasz wariant zdalny (HTTP) w sieci z zasobami wewnętrznymi, uruchom go w środowisku z ograniczeniem sieci wychodzącej — model mógłby wskazać adres wewnętrzny (np. endpoint metadanych chmury).

Licencja

MIT