Skip to main content
Glama
Sign In
MEK-MCP

MEK-MCP

by hvj78
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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)

MCP tool

REST végpont

Mire jó

mek_simple_search

GET /v1/search/simple

Gyors keresés cím / téma / szerző / MEK ID szerint (ÉS-kapcsolat)

mek_advanced_search

POST /v1/search/advanced

Max. 5 feltétel és / vagy / nem operátorokkal, 24 mező

mek_fulltext_search

GET /v1/search/fulltext

Szabad szavas keresés a dokumentumok teljes szövegében

mek_browse_index

GET /v1/browse

Kontrollált szótár (tárgyszó-, névalakok) böngészése

mek_get_record

GET /v1/records/{id}

Egy rekord teljes metaadata

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

MCP tool

REST végpont

Mire jó

oszkdk_simple_search

GET /v1/oszkdk/search/simple

Gyors, szabad szavas keresés az összes indexelt mezőben

oszkdk_advanced_search

POST /v1/oszkdk/search/advanced

Max. 3 feltétel és / vagy / nem operátorokkal, cím / szerző / bármely mező

oszkdk_get_record

GET /v1/oszkdk/records/{id}

Rekord metaadata + letölthető fájlok listája (formátum, méret, hozzáférés)

oszkdk_top_list

GET /v1/oszkdk/top

Legolvasottabb címek (hónap / év / minden idők)

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

Available Tools

5 tools
mek_advanced_searchA

Advanced (fielded) search in the MEK catalogue with up to 5 conditions combined via AND / OR / NOT over 24 metadata fields.

Available fields: main_title, subtitle, collection_title, part_title, parallel_title, original_title, series, author, author_role, corporate_author, contributor, contributor_role, publisher, subject, geographic_subject, period_subject, document_type, format, language, original_language, printed_source, rights_owner, rights_note, creative_commons.

Typical patterns:

  • Works BY a person: field=author, value='Petőfi Sándor'.

  • Works ABOUT a person: field=subject, value='Petőfi Sándor'.

  • Person in any role: run separate author / subject / contributor searches (OR across different fields of different records is best done client-side by merging results).

  • Exclusions: add a condition with operator='not' (e.g. document_type='útikönyv' with 'not' to drop travel guides).

  • Language filter: field=language, value='magyar' / 'angol' / ...

  • Values are matched against controlled vocabulary; use mek_browse_index to discover exact term forms, and * for prefixes.

Returns: {total, offset, hits: [{mek_id, url, authors, title, date_added}], has_more, accent_fallback_used}.

Inputs: conditions (required), offset, accent_insensitive, auto_accent_fallback. Returns: object

mek_browse_indexA

Browse the controlled-vocabulary index of a catalogue field around a given term. Use this BEFORE subject/type/name searches to discover the exact term forms stored in the catalogue, then run mek_advanced_search with the returned search_value strings.

Returns: {field, term, entries: [{display, search_value}]}. Pass search_value (not display) as the value in mek_advanced_search.

Inputs: term (required), field (required). Returns: object

mek_fulltext_searchA

Free-text search in the full text of MEK documents. Returns matching documents with a text snippet around the match and a direct link to the match location. Use this when the query concerns document CONTENT rather than catalogue metadata, or as a fallback when metadata searches find nothing.

Returns: {total, offset, limit, hits: [{mek_id, url, authors, title, snippet, match_location_url}], has_more}.

Inputs: query (required), limit, offset, broad_topic. Returns: object

mek_get_recordA

Fetch the metadata of a single MEK record: title, authors, themes (topic hierarchy), subject headings, description, dates, identifiers. Use it to inspect / classify individual hits (e.g. to decide whether a work is fiction, history or ethnography, or whether it is BY or ABOUT a person).

Returns: {mek_id, url, title, themes, subjects, description, date_added, urn}.

Inputs: mek_id_or_url (required). Returns: object

mek_simple_searchA

Simple search in the MEK catalogue by title, subject, author and/or MEK ID. All given words are combined with AND. Words may be typed in lowercase and without accents: if nothing is found, the MEK server automatically retries accent-free and then stemmed.

Good for quick, broad lookups. For field-precise queries, OR-logic, exclusions (NOT) or language/type filtering use mek_advanced_search.

Returns: {total, offset, limit, hits: [{mek_id, url, authors, title, date_added}], has_more}.

Inputs: limit, title, author, mek_id, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool serves a clearly distinct purpose: advanced fielded search, controlled vocabulary browsing, full-text search, single-record retrieval, and simple broad search. No two tools overlap significantly; even simple and advanced search are differentiated by complexity and query capabilities.

    Naming Consistency5/5

    All tool names follow a consistent 'mek_verb_noun' pattern (e.g., mek_advanced_search, mek_browse_index, mek_fulltext_search). The naming is predictable and self-documenting.

    Tool Count5/5

    With 5 tools, the server is well-scoped for a library catalogue interface. The tools cover the essential operations without unnecessary bloat, providing a balanced set for both simple and advanced queries.

    Completeness5/5

    The tool surface covers the key use cases: searching by metadata (simple and advanced), browsing controlled vocabularies, full-text search, and fetching full record details. There are no obvious gaps for a read-only catalogue query service.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • barracuda-mcp

      Sourcery-info
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables searching OpenAleph entities and documents using natural language queries through the MCP protocol.
      13 npm
      1
      MIT

    • MEK MCP

      wlagyorgy
      F
      license
      A
      quality
      D
      maintenance
      MCP server to access the Hungarian Electronic Library (MEK) search engines, enabling agentic tools to search and retrieve content.
      4
      -

    • theses-mcp

      koprjaa
      A
      license
      A
      quality
      B
      maintenance
      MCP server that enables searching and retrieving Czech university theses from theses.cz, including full-text search, metadata, and direct PDF downloads with optional cookie-based authentication.
      3
      AGPL 3.0