MEK-MCP

MCP server and FastAPI microservice exposing the search interfaces of two Hungarian digital libraries — the Hungarian Electronic Library (Magyar Elektronikus Könyvtár, mek.oszk.hu) and the OSZK Digitális Könyvtár (oszkdk.oszk.hu) — to agentic tools (Claude Code, Claude Desktop, Codex and any MCP-capable client) and to plain REST consumers. Documentation below is in Hungarian.

A projekt két üzemmódban használható, két önálló keresőmotorral (mek_mcp_server.py a MEK-hez, oszkdk_mcp_server.py az OSZKDK-hoz):

1. Lokális MCP szerver (stdio) — a két könyvtár egymástól függetlenül is bekötető Claude Code-ba vagy Claude Desktopba.

2. Hostolt microservice (FastAPI) — REST API /v1/* és /v1/oszkdk/* végpontokkal és egyetlen közös távoli MCP végponttal a /mcp útvonalon, amely mind a kilenc toolt kínálja (öt MEK + négy OSZKDK); Fly.io-ra deployolható ebből a repóból, GitHub Actions-szel automatikusan.

Miért két könyvtár? A MEK és az OSZKDK csak részben fedik egymást: a MEK inkább klasszikus/régebbi magyar irodalmat és szürke irodalmat gyűjt, az OSZKDK viszont ISBN-es, modern könyvekre és monográfiákra súlyoz. Ha az egyikben nincs találat egy modern, ISBN-es magyar könyvre, érdemes a másikban is megnézni — ezért érdemes mindkét toolkészletet egyszerre elérhetővé tenni egy agent számára.

Toolok / végpontok

MEK (Magyar Elektronikus Könyvtár)

OSZKDK (OSZK Digitális Könyvtár)

Interaktív API-dokumentáció futó szolgáltatásnál: /docs.

Related MCP server: barracuda-mcp

1) Lokális MCP szerver (stdio)

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# csak a MEK
claude mcp add --transport stdio mek -- \
  $PWD/.venv/bin/python $PWD/mek_mcp_server.py

# csak az OSZKDK
claude mcp add --transport stdio oszkdk -- \
  $PWD/.venv/bin/python $PWD/oszkdk_mcp_server.py

Ellenőrzés: claude mcp list → a szerverek ✓ Connected állapotban.

2) Hostolt szolgáltatás Fly.io-n, ebből a repóból

A repo tartalmazza a Dockerfile-t, a fly.toml-t és a .github/workflows/fly-deploy.yml workflow-t: minden main-re történő push automatikusan deployol.

Egyszeri beállítás:

# 1. App létrehozása a Fly-fiókban (a név globálisan egyedi kell legyen)
fly apps create mek-search-api

# 2. App-hatókörű deploy token generálása
fly tokens create deploy -a mek-search-api

A kapott tokent add hozzá a GitHub repóhoz secretként: Settings → Secrets and variables → Actions → New repository secret, név: FLY_API_TOKEN. Ezután egy push a main-re (vagy az Actions fülön a „Fly Deploy" workflow kézi indítása) elvégzi a deployt.

Opcionális API-kulcs védelem:

fly secrets set MEK_API_KEY=valami-titok -a mek-search-api

Ha be van állítva, minden kérésnek X-API-Key: <kulcs> vagy Authorization: Bearer <kulcs> fejlécet kell vinnie (kivéve /, /healthz, /docs).

Távoli MCP használat deploy után

claude mcp add --transport http mek-oszkdk https://mek-search-api.fly.dev/mcp
# API-kulccsal:
claude mcp add --transport http mek-oszkdk https://mek-search-api.fly.dev/mcp \
  --header "X-API-Key: valami-titok"

Egyetlen URL mögött mind a kilenc tool elérhető (mek_* és oszkdk_* előtaggal, névütközés nélkül), így lokális telepítés nélkül, bármely gépről (vagy claude.ai custom connectorként) használható mindkét könyvtár.

Példa promptok az agentnek

MEK:

• „Keress magyar nyelvű műveket a mesterséges intelligencia témájában, de zárd ki a programozási tankönyveket." → subject=mesterséges intelligencia AND language=magyar NOT subject=programozás.

• „Petőfi szerzőként, témaként és közreműködőként." → három keresés az author / subject / contributor mezőkre (35 / 50 / 4 találat) — a subject-es halmaz a róla szóló (szekunder) irodalom.

• „Nézd meg, milyen tárgyszóalakok vannak a néprajz körül, és ezekre keress." → mek_browse_index(subject, néprajz) → célzott keresések.

• Ékezetkezelés: 0 találatnál automatikus ékezetfüggetlen újrapróbálás, a válaszban accent_fallback_used=true jelzi a bővülést.

OSZKDK:

• „Keress Petőfitől szerzőként műveket, de zárd ki az Ibolyák címűt." → author=Petőfi Sándor NOT title=Ibolyák (exact_phrase).

• „Mi a legnépszerűbb könyv az OSZK digitális könyvtárban idén?" → oszkdk_top_list(period=year).

• „Ez a könyv szabadon olvasható, vagy csak a könyvtárban?" → oszkdk_get_record → files[].access (Nyilvános vs. Dedikált hálózaton belül = csak OSZK-pontokon).

• Ha a MEK-ben nincs találat egy modern, ISBN-es könyvre, próbáld az OSZKDK-ban (és fordítva) — a két gyűjtemény kiegészíti egymást.

Implementációs jegyzetek

MEK:

• A modern /hu/search/ végpontok UTF-8-at, a régi /katalog/*.php3 CGI-k ISO-8859-2 kódolású form-adatot várnak — a kliens ezt kezeli (e nélkül az ékezetes keresések némán 0 találatot adnak).

• Az összetett kereső oldalanként max. 100 találatot ad; lapozás offset-tel (100, 200, ...). Az egyszerű és teljes szövegű kereső 10/50/100-as lapmérettel lapozható.

• Tárgyszavak, típusok, névalakok kontrollált szótárból jönnek; a mek_browse_index search_value mezője a kereshető alak.

• Névformátum: „Családnév Utónév" (Petőfi Sándor), külföldi szerzőknél gyakran Vezetéknév, Utónév (Verne, Jules). Csonkolás: *.

OSZKDK:

• Az összes végpont sima UTF-8-at használ, nincs szükség speciális kódolás-kezelésre (szemben a MEK legacy /katalog végpontjával).

• A találati oldalak fix, 10-es lapmérettel dolgoznak; nincs lapméret-paraméter, csak offset (0-alapú).

• Az összetett keresőnek pontosan 3 sora van (ennyit enged a saját UI is); csak 3 mező érhető el ténylegesen: cím (dc.title), szerző (dc.author), bármely mező (cql.serverChoice) — más dc.* nevek (pl. dc.subject) csendben 0 találatot adnak, mert a backend nem támogatja őket, hiába tűnne logikusnak.

• A dokumentumtípus-szűrő (document_type) csak globálisan, az ELSŐ feltételről érvényesül — ez a hivatalos UI valódi korlátja, nem a kliens hibája.

• any_word és all_words egyezési mód a jelenlegi backenden minden tesztelt esetben azonos találati halmazt adott; exact_phrase az egyetlen mód, ami megbízhatóan szűkít.

• Egyes rekordok csak „Dedikált hálózaton belül" (OSZK-pontokon) érhetők el, nem szabadon letölthetők — ezt a files[].access mező jelzi minden fájlnál.

Közös / hosztolás:

• A hostolt szolgáltatás stateless, nem igényel persistent volume-ot; a fly.toml auto_stop_machines beállításával üresjáratban leáll.

• A /mcp végpont a két modul tooljait egyetlen kombinált MCP szerverbe gyűjti (combined_mcp az app.py-ban); stdio módban viszont a két modul továbbra is teljesen önállóan futtatható.

Tesztelés

Élő integrációs tesztek mindkét könyvtár ellen (keresők, NOT-operátor, ékezet-fallback, index, rekord, lapozás, top-lista, hibakezelés):

.venv/bin/python test_live.py