Skip to main content
Glama
geldersarchief-mcp

geldersarchief-mcp

Gelders Archief scan core

Lokale MCP-server, Python-core en CLI voor het zoeken van Gelders Archief-aktes, het ontdekken van alle registerscans en downloaden met provenance. De MCP-server draait via stdio met de officiële SDK. OCR is optioneel en standaard uitgeschakeld in MCP; zoeken, inspecteren en expliciet downloaden werken zonder OCR.

uv sync --frozen
uv run --frozen geldersarchief-mcp

Verbind een MCP-client met de clientconfiguratie. Zie MCP-tools en gebruik voor de volledige interface en downloadflow.

De voorbeeldpermalink is live getest op 5 oktober 2026: 192 unieke scans, met volgorde 1–192. De viewer laadt aanvankelijk 25 referenties. De core ontdekt alle scans rechtstreeks via HTTP, zonder Chromium te starten. Scan 176 is via de expliciete viewer-downloadlink opgeslagen als JPEG, 3019 × 4170 pixels, 1.372.341 bytes. SHA256:

c9488c8abf3aa2c97921c7f04e080cc2299a52af79156f606640f36b04091611

Dit is de door de viewer aangeboden downloadrepresentatie. Het archiefmaster- bestand is niet onafhankelijk beschikbaar gesteld of op byte-identiteit getest. Scan 176 is een technisch testobject; er is niet vastgesteld dat deze scan de akte uit de voorbeeldpermalink bevat.

Installatie

Vereist: Python 3.12+ en uv.

uv sync --frozen
# Alleen nodig voor vieweronderzoek en browserfallbacks:
uv run playwright install chromium

Related MCP server: Open Archives MCP Server

CLI

uv run geldersarchief inspect \
  'https://permalink.geldersarchief.nl/E42035012A364A3E9190403665F46E77'

uv run geldersarchief download-scan \
  'https://permalink.geldersarchief.nl/E42035012A364A3E9190403665F46E77' \
  --sequence 176

JSON-resultaten staan op stdout; geredigeerde JSON-logs op stderr. Gebruik geldersarchief --debug inspect URL voor batchdiagnostiek. Downloads komen standaard in data/downloads/; --output DIRECTORY overschrijft dat per opdracht.

Bestanden heten <register>_scan-<volgnummer>.<ext>. De sidecar bevat bronpermalink, register, inventaris, scan-ID, oorspronkelijke download-URL, UTC-downloadtijd, SHA256, dimensies, discoverymethode en representatietype. Aktenummer en confidence blijven bij een expliciet gekozen CLI-scan null. MCP-downloads bewaren daarnaast de resolutiestatus en het eventuele bewijs van een aktekoppeling. Afbeeldingen worden zonder hercompressie opgeslagen.

Vieweronderzoek

uv run python scripts/inspect_viewer.py --load-all --output debug/research

Dit legt consolemeldingen, requests, redirects, relevante JSON/JavaScript, DOM, scriptbronnen, window-keys en stores vast. --load-all laadt de batches van het geselecteerde register opeenvolgend met 350 ms vertraging. --headed opent een zichtbaar venster. Een expliciete viewer-URL kan als positioneel argument worden meegegeven om ook de iframe-/tileviewer te onderzoeken.

Op de ontwikkelmachine sluit het lokale netwerkverkeer van Chromium verbindingen met deze site af, terwijl HTTP met OS-certificaatvertrouwen werkt. Hiervoor is er een expliciete transportoptie:

uv run python scripts/inspect_viewer.py --http-transport --load-all
GA_BROWSER_HTTP_TRANSPORT=true uv run pytest -m live

Hierbij voert Chromium nog steeds de viewer-JavaScript uit en traceert Playwright requests; HTTPX verzorgt het transport met gecontroleerde TLS via de OS-truststore. TLS-verificatie wordt niet uitgeschakeld. Deze optie is geen site-authenticatie- of CAPTCHA-omzeiling. Normale CLI-discovery heeft deze optie niet nodig.

Python-interface

import asyncio
from geldersarchief_mcp.archives.geldersarchief import GeldersArchiefAdapter

async def main():
    async with GeldersArchiefAdapter() as archive:
        register = await archive.inspect_register(
            'https://permalink.geldersarchief.nl/E42035012A364A3E9190403665F46E77'
        )
        image = await archive.get_scan(register.scans[175])
        # image bevat de originele bytes van de viewer-downloadrepresentatie.

asyncio.run(main())

inspect_register geeft alleen een volledig register terug. Ontbrekende batches, conflicterende posities of een onbekend totaal geven een expliciete exception. download_scan geeft naast bytes ook de gevalideerde URL, MIME en dimensies terug. Een verlopen URL vereist verse registerdiscovery; langdurige tokencaching is nog niet geïmplementeerd.

Configuratie

Variabele

Default

GA_DATA_DIR

data

GA_DOWNLOAD_DIR

<GA_DATA_DIR>/downloads

GA_BROWSER_HEADLESS

true

GA_BROWSER_HTTP_TRANSPORT

false

GA_MAX_CONCURRENT_REQUESTS

2

GA_MAX_IMAGE_DOWNLOADS

2

Eén adapter beheert één herbruikbare browser, maximaal twee contexts, maximaal twee registeroperaties en twee downloads met de defaults. Bulk-batches zijn sequentieel met 350 ms vertraging. HTTP 429/502/503/504 krijgt beperkte retries met back-off en Retry-After. Alleen openbare bronnen worden gebruikt; geen externe AI-services. De resolver gebruikt uitsluitend lokale OCR en een lokale observatiecache.

Debugoutput en lokale downloads zijn uitgesloten via .gitignore. Debugoutput redigeert sessies en toegangstokens, ook in base64-HTML en ge-escapete JSON. Lokale provenance bevat de volledige publieke download-URL voor reproduceerbaarheid; publiceer die sidecars niet zonder de URL-tokens te redigeren.

Tests

uv run pytest            # offline; live tests uitgesloten
uv run pytest -m live    # bewuste publieke netwerkcontrole

Offline tests dekken parsing, volgorde, ontdubbeling, storeselectie, ontbrekende batches, downloadvalidatie, provenance, concurrency, redactie en back-off. Live tests herhalen discovery/download met verse HTTP-clients en browserinstances. CI draait alleen offline tests, op Python 3.12 en 3.14.

De bewezen HTTP-route is primair. Browserstore-, DOM- en navigatiefallbacks zijn voor toekomstige wijzigingen; hun algemene werking buiten het geteste register is niet aangetoond. Zie het onderzoeksrapport voor waarnemingen, beperkingen en de tien onderzoeksvragen.

Docker is nog niet geïmplementeerd. De observatiecache is geen volledige registerindex.

MIT-licentie. Het project is niet verbonden aan het Gelders Archief of DE REE.

Open Archieven-integratie

Zoeken en het normaliseren van records zijn geïmplementeerd via de officiële Open Archieven 1.1 API. Zoekresultaten worden verrijkt met de volledige A2A-records, zodat aktenummer, inventarisnummer en archiefbron beschikbaar zijn.

uv run geldersarchief search-acts --name 'Derk Jan van Brink' \
  --place Terwolde --year 1921 --record-type geboorte

uv run geldersarchief get-record \
  'gld:E4203501-2A36-4A3E-9190-403665F46E77'

uv run geldersarchief inspect \
  --record 'gld:E4203501-2A36-4A3E-9190-403665F46E77'

download-scan accepteert eveneens --record in plaats van een URL, maar vereist nog steeds een expliciet --sequence. Dat is geen automatische akte→scan-match. De sidecar bewaart het aangevraagde record apart van de ongeverifieerde aktevelden.

Typen: birth/geboorte, death/overlijden, marriage/huwelijk. Een --date filtert op de gebeurtenisdatum. --limit (1–100) en --start bedienen paginering; number_found is het aantal persoonstreffers van de API, vóór lokale filtering en ontdubbeling op record-ID. next_start verwijst naar de volgende API-pagina.

De bekende geboorteakte heeft event_date=1921-12-30, act_date=1922-01-02 en act_number="1". De resolver gebruikt de aktedatum voor nummerpositionering. Onvolledige datums worden niet aangevuld met verzonnen maanden of dagen.

De client begrenst opeenvolgende calls tot maximaal één per 350 ms. Ontbrekende records, HTTP-fouten en API-foutcodes worden expliciet afgehandeld. Er is geen API-key of AI-provider nodig. Configureer GA_USER_AGENT met je project-URL of contactadres bij publiek gebruik, zoals Open Archieven vraagt.

Details en bronnen: Open Archieven-integratie.

Conservatieve akte→scan-resolver

Installeer voor resolve lokaal Tesseract en Nederlandse taaldata, bijvoorbeeld op macOS met brew install tesseract tesseract-lang.

uv run geldersarchief resolve \
  --record 'gld:E4203501-2A36-4A3E-9190-403665F46E77' --max-scans 12

uv run geldersarchief resolve 'https://permalink.geldersarchief.nl/E42035012A364A3E9190403665F46E77' \
  --act 1 --date 1922-01-02 --name 'Derk Jan van Brink'

Bij resolve betekent --date de aktedatum. De zoekstrategie controleert expliciete scanmetadata, bemonstert het register en gebruikt interpolatie alleen bij voldoende monotone nummerankers. Het scanbudget voorkomt een onbeperkte OCR-doorloop. Kandidaten en buurscans zijn verwijzingen, geen automatische download van een als juist bevestigde akte.

Live proef op het voorbeeldregister: na 12 bekeken scans blijft het resultaat AMBIGUOUS. Tesseract las losse nummers, maar bevestigde geen bijbehorende datum of naam. Vervolgonderzoek heeft scan 3 visueel bevestigd als akte 1. De optionele lokale Kraken-reader herkent de aktedatum en stelt scan 3 voor als kandidaat (AMBIGUOUS), maar bevestigt de akte nog niet automatisch. Zie lokale HTR voor installatie en downloadbewijs. Algorithmische tests met gecontroleerde observaties bewijzen de zoeklogica, niet de leeskwaliteit van deze handgeschreven bron. Zie resolver en live beperkingen.

Variabele

Default

GA_CACHE_DB

<GA_DATA_DIR>/cache.sqlite

GA_RESOLVER_MAX_SCANS

24

GA_OCR_EXECUTABLE

tesseract

GA_OCR_LANGUAGE

nld

De lokale SQLite-cache bewaart OCR-tekst met afbeeldings-SHA256 en readeridentiteit. Verwijder de cache na het vervangen van taalmodelbestanden; hun inhoud is geen onderdeel van de readeridentiteit. Cache en scans blijven buiten Git.

Available Tools

6 tools
download_actB

Resolve and download an act; original means unchanged viewer-download bytes.

FOUND downloads its bound scans. Uncertain results return files=[]. A supplied scan_sequence explicitly selects a scan (status SELECTED). allow_probable permits a PROBABLE download while preserving that status. No archive-master claim or silent first-record/candidate selection is made.

Inputs: record_id (required), reader, max_scans, output_format, +2 more.

download_scanA

Download an explicitly selected one-based scan with SHA256 and local provenance.

Provide exactly one record_id/source_url. Selection does not verify act identity. Files are exposed through resource_uri/provenance_uri, not inline base64 JSON.

Inputs: sequence (required), record_id, source_url.

get_recordC
Read-only

Get a gld: record with act number, act/event dates, source and relatives.

Inputs: record_id (required). Returns: object

inspect_registerB
Read-only

Discover all scan references; return the proven total and a paginated scan list.

start is one-based. Missing batches/unknown totals are errors, never complete results.

Inputs: url (required), limit, start. Returns: object

resolve_act_scanA

Resolve an act using exactly one of record_id/source_url; date means act date.

Default: explicit archive metadata only, with no OCR or image downloads. Optional installed local readers return bounded evidence and candidates. AMBIGUOUS/PROBABLE must not be treated as a confirmed act.

Inputs: date, name, reader, max_scans, +3 more. Returns: object

search_actsB
Read-only

Search Gelders Archief acts in Open Archieven; date filters the event date.

Multiple records remain separate; number_found counts API person hits. Use record_id for subsequent calls. next_start enables pagination.

Inputs: name (required), date, year, limit, +3 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have distinct purposes (search, get, inspect, resolve, download), but resolve_act_scan and download_act overlap since download_act also resolves, and download_scan vs download_act both download scans. Descriptions provide enough guidance to differentiate them, keeping this a minor issue.

    Naming Consistency5/5

    All six tools follow a consistent snake_case verb_noun pattern: get_record, search_acts, inspect_register, resolve_act_scan, download_scan, download_act. The convention is predictable and readable throughout.

    Tool Count5/5

    Six tools is well-scoped for a focused archival/genealogy resolution workflow. Each tool targets a distinct stage (search, retrieve, inspect, resolve, download) without redundancy bloat.

    Completeness4/5

    The surface covers the full discovery-to-download lifecycle: searching acts, fetching records, inspecting registers, resolving acts to scans, and downloading scans/acts. Minor gap in that there's no explicit listing of collections/registers beyond inspect_register, but core workflows are covered.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables users to search and access digital collections from the Swedish National Archives (Riksarkivet) through multiple APIs. Supports searching records by keywords, exploring collections, and downloading historical images and documents.
      2
      27
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Family history research toolkit with 79 archives and databases, name variants, historical calendars, kinship, evidence checks, GEDCOM auditing and archive-request drafts. An MIT-licensed Python MCP server that runs locally without API keys or network requests.
      31
      124 PyPI
      10
      MIT