MCP |

tei-mcp v0.3: TEI coderen zonder de bron te herschrijven

Tue, 05 May 2026 00:00:00 +0000

Toen ik , was het doel te voorkomen dat AI-assistenten TEI-markup hallucineren. Schemaverankering loste een deel van het probleem op: met rechtstreekse, op tools gebaseerde toegang tot de P5-specificatie hoeft het model niet langer te raden wat een element betekent of welke attributen het aanvaardt. De uitvoer valideert.

Maar hallucinatie heeft bij TEI-codering twee gezichten, en het schema vangt er maar één van op. Validatie tegen de specificatie vertelt je dat de markup welgevormd is. Ze zegt niets over de tekst die de markup omsluit. En juist daar – in de tekst zelf – schuilen de schadelijkste hallucinaties. Span-locked composition, het paradepaardje van v0.3, is speciaal ontworpen om die te voorkomen.

Inhoudsopgave

De hallucinatie die het schema niet kan vangen

Vraag een model een zestiende-eeuwse Franse brief te coderen en je krijgt vaak een TEI-document terug dat er onberispelijk uitziet. De header is ingevuld, de <persName>-tags staan op de juiste plaats, de <dateline> is welgevormd. Haal het door validate_document en het slaagt.

Vergelijk dan de lopende tekst met de bron.

mesme is même geworden. Een komma is verhuisd. luy is stilzwijgend gemoderniseerd tot lui. Een zinsdeel dat in het handschrift moeilijk leesbaar was, is “verbeterd” tot iets netters. Om geen van die wijzigingen is gevraagd. Geen ervan wordt gemeld. Het document is schemageldig en in alle stilte fout.

Voor een archivistische workflow – waarin de gecodeerde tekst de blijvende versie wordt waarop latere lezers, zoekindexen en citaties vertrouwen – is dit de faalwijze die er het meest toe doet. Een misvormde tag is vervelend. Een gemoderniseerde spelling die vijf jaar lang niemand opmerkt, is een corruptie.

Span-locked composition

De nieuwe versie (v0.3) bevat een mechanisme tegen hallucinaties dat precies op deze faalwijze mikt. Het ontwerpdoel is hallucinaties in de lopende tekst per constructie onmogelijk te maken, niet alleen onwaarschijnlijk.

Het idee is eenvoudig: het model typt nooit lopende tekst.

De workflow ziet er in plaats daarvan zo uit:

Het model roept get_source("letter_001") aan en ontvangt de platte brontekst als onveranderlijke string.
Voor elke tag die het wil aanbrengen, roept het tag_span("letter_001", start, end, element_path, attrs) aan – het registreert daarmee een TEI-element op een tekenbereik in de bron.
Is het klaar, dan roept het compose("letter_001") aan. De server vlecht de geregistreerde tags door de oorspronkelijke platte tekst, rendert de definitieve TEI en controleert vervolgens byte voor byte of de platte tekstinhoud van het gerenderde document gelijk is aan de bron.

Komen de bytes overeen, dan komt het document terug. Zo niet – als de tags van het model op een of andere manier een lopende tekst impliceren die ook maar één teken van de bron afwijkt – dan werpt compose() een fout op in plaats van een corrupt document terug te geven.

Er is geen route door deze workflow waarlangs het model een TEI-document produceert waarvan de lopende tekst van de bron afwijkt. De invariant is mechanisch, niet gedragsmatig. Je hoeft er niet op te vertrouwen dat het model niet hallucineert; je hoeft alleen te vertrouwen op een ==-vergelijking tussen twee bytestrings.

Wat dit is, en wat het niet is

Span-locked composition is een aanvulling op schemaverankering, geen vervanging ervan. De tools voor schemaverankering (validate_document, lookup_element, valid_children en de rest van de oorspronkelijke zestien) helpen het model geldige TEI te produceren. Span-locked composition garandeert dat de lopende tekst binnen die TEI trouw is aan de bron. Een inzetbare codeerworkflow moet aan beide eisen voldoen, en nu dekt één server ze allebei.

Het is ook geen wondermiddel voor alles. compose() controleert nog niet of de geregistreerde tags toelaatbaar zijn volgens een geladen ODD-customisatie – dat komt later. Geregistreerde tags leven in het procesgeheugen en overleven een herstart niet. En de bronbestanden moeten leesbaar zijn vanaf de plek waar de server draait. Dat valt allemaal op te lossen; niets ervan ondergraaft de kerninvariant.

Waarom dit verder reikt dan TEI

Het patroon laat zich veralgemenen. Telkens wanneer een model wordt gevraagd een stuk tekst te annoteren, te transformeren of te omsluiten – en telkens wanneer de integriteit van de onderliggende tekst zwaarder weegt dan het vermogen van het model om die te “verbeteren” – past dezelfde vorm van oplossing. Vraag het model niet de tekst over te typen. Vraag het instructies over de tekst te produceren, en laat een deterministische composer die toepassen onder een gelijkheidsinvariant.

Voor digitale edities in het bijzonder verandert dit wat je een model verantwoord kunt vragen. Coderen wordt ineens een taak die je kunt delegeren zonder elke uitvoer handmatig met de bron te hoeven vergelijken. De machine neemt de saaie weg; de editeur beoordeelt de markup, niet de spelling.

De update ophalen

Heb je tei-mcp al geïnstalleerd:

uvx tei-mcp@latest

Of bij een nieuwe installatie:

pip install tei-mcp

Om span-locked composition te gebruiken, wijs je de server naar een map met platte bronbestanden:

export TEI_MCP_SPAN_SOURCE_ROOT=/path/to/sources
uvx tei-mcp

De naam van elk bestand (zonder extensie) wordt zijn document-ID (letter_001.txt → letter_001).

Broncode, volledige documentatie en de ontwerpnotities bij de invariant:

tei-mcp

Sun, 15 Mar 2026 00:00:00 +0000

tei-mcp: TEI P5 voor AI-agents

tei-mcp is een opensource-server voor die AI-codeerassistenten rechtstreeks toegang geeft tot de -specificatie. In plaats van te vertrouwen op uit het hoofd geleerde trainingsdata – wat vaak plausibele maar foute markup oplevert – kan de AI de specificatie in realtime bevragen.

Functies

De server parseert de ODD van TEI P5 en biedt 16 tools aan:

Opzoeken van elk element, elke klasse, macro of module op naam, hoofdletterongevoelig en met suggesties bij tikfouten
Attributen oplossen over de volledige TEI-klassenhiërarchie (lokaal + geërfd)
Inhoudsmodellen uitklappen tot gestructureerde bomen, met resolutie van klassen en macro’s
Nesting valideren – directe ouder-kindrelatie of recursieve bereikbaarheid, met padregistratie
Documenten valideren tegen TEI P5: inhoudsmodellen, attributen, gesloten waardelijsten, referentie-integriteit en waarschuwingen bij verouderde elementen
Afzonderlijke elementen valideren voor incrementele bewerkingsworkflows
ODD-customisaties laden om het schema te beperken tot een projectspecifieke deelverzameling
Zoeken in alle entiteitstypen met reguliere expressies

Installatie

pip install tei-mcp

Of rechtstreeks uitvoeren met:

uvx tei-mcp

Gebruik

Voeg toe aan elke MCP-compatibele client (Claude, Cursor, Windsurf enz.):

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

De broncode en documentatie vind je in de .

tei-mcp: TEI P5 voor AI-agents

Sun, 15 Mar 2026 00:00:00 +0000

Wie ooit een AI-codeerassistent TEI-XML heeft laten schrijven, heeft het vast gemerkt: het gaat mis. Elementen duiken op waar ze niet horen. Attributen worden verzonnen. Nestingregels worden genegeerd. Het model heeft een ruw idee van hoe TEI eruitziet, maar geen betrouwbare kennis van de specificatie.

tei-mcp lost dat op door AI-agents rechtstreeks, via tools, toegang te geven tot de TEI P5 Guidelines.

Inhoudsopgave

Wat is MCP?

Het (MCP) is een open standaard waarmee AI-toepassingen verbinding kunnen maken met externe gegevensbronnen en tools. Zie het als een USB-poort voor AI: één protocol waarmee elke compatibele client – Claude, Cursor, Windsurf en andere – op gespecialiseerde diensten kan aansluiten.

Een MCP-server stelt tools beschikbaar die de AI tijdens een gesprek kan aanroepen. In plaats van te vertrouwen op uit het hoofd geleerde trainingsdata kan het model een actuele, gezaghebbende bron bevragen.

Wat tei-mcp doet

tei-mcp parseert de ODD-specificatie van TEI P5 en biedt 16 tools aan die de meest voorkomende vragen van een editeur of encoder beantwoorden:

Wat is dit element? Zoek elk element, elke klasse, macro of module op naam op, hoofdletterongevoelig en met suggesties bij tikfouten.
Welke attributen neemt het? Los attributen op over de hele klassenhiërarchie – eerst de lokale, dan de geërfde, in volgorde.
Wat mag erin? Klap inhoudsmodellen uit tot gestructureerde bomen, of vraag een platte lijst van geldige kinderen op.
Mag dit element hier staan? Controleer de nesting van ouder en kind, of volg de bereikbaarheid door de volledige elementenhiërarchie.
Is mijn document geldig? Valideer een TEI-XML-bestand tegen de specificatie: inhoudsmodellen, attribuutwaarden, gesloten waardelijsten, referentie-integriteit en waarschuwingen bij verouderde elementen.
En mijn projectschema? Laad een ODD-customisatiebestand om dit alles te beperken tot de specifieke TEI-deelverzameling van je project.

Waarom het ertoe doet

TEI-codering vereist dat je voortdurend de Guidelines raadpleegt. Ervaren encoders kennen de gangbaarste patronen uit het hoofd, maar zelfs zij moeten de specificatie erbij nemen voor minder vertrouwde elementen of ingewikkelde inhoudsmodellen. Voor AI-assistenten, die zulke verinnerlijkte kennis niet hebben, is het probleem erger: ze hallucineren markup die er plausibel uitziet maar niet klopt.

Met tei-mcp hoeft de AI niet te gokken. Het kan het antwoord in de specificatie opzoeken voordat het één punthaak schrijft. Het resultaat is markup die voldoet aan TEI P5 – of aan de ODD-customisatie van je project.

Aan de slag

Installeer vanaf PyPI:

pip install tei-mcp

Voeg de server daarna toe aan de configuratie van je MCP-client:

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

De server downloadt de TEI-specificatie bij de eerste start en werkt met elke MCP-compatibele client.

Broncode en volledige documentatie: