MCP |

tei-mcp v0.3: codificare in TEI senza riscrivere la fonte

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

Quando ho , lo scopo era impedire agli assistenti IA di allucinare marcatura TEI. L’ancoraggio allo schema ha risolto una parte del problema: con un accesso diretto, per mezzo di strumenti, alla specifica P5, il modello non deve più indovinare che cosa significhi un elemento o quali attributi accetti. L’output passa la validazione.

Ma nella codifica TEI l’allucinazione ha due facce, e lo schema ne coglie una sola. Validare rispetto alla specifica vi dice che la marcatura è ben formata; non dice nulla del testo che quella marcatura racchiude. Ed è lì, nel testo, che si annidano le allucinazioni più dannose. La composizione span-locked, novità di punta della v0.3, è pensata apposta per impedirle.

Indice dei Contenuti

L’allucinazione che lo schema non vede

Chiedete a un modello di codificare una lettera francese del Cinquecento e otterrete spesso un documento TEI dall’aria impeccabile: header compilato, tag <persName> al posto giusto, <dateline> ben formata. Passatelo per validate_document, e passa.

Poi confrontate il corpo con la fonte.

mesme è diventato même. Una virgola è migrata. luy è stato modernizzato in lui senza dir niente a nessuno. Una frase ostica nel manoscritto è stata «corretta» in qualcosa di più pulito. Nessuna di queste modifiche era stata richiesta; nessuna viene segnalata. Il documento è valido per lo schema e sbagliato in silenzio.

In un flusso di lavoro archivistico – dove il testo codificato diventa il documento definitivo su cui contano lettori, indici di ricerca e citazioni – è questo il guasto che conta di più. Un tag malformato è una seccatura; una grafia modernizzata che nessuno nota per cinque anni è una corruzione.

La composizione span-locked

La nuova versione (v0.3) include un meccanismo di prevenzione delle allucinazioni mirato proprio a questo guasto. L’obiettivo di progetto è rendere le allucinazioni nel corpo del testo impossibili per costruzione, non semplicemente improbabili.

L’idea è semplice: il modello non batte mai il corpo del testo.

Il flusso di lavoro, invece, è questo:

Il modello chiama get_source("letter_001") e riceve il testo semplice di partenza come stringa immutabile.
Per ogni tag che vuole applicare, chiama tag_span("letter_001", start, end, element_path, attrs), registrando un elemento TEI su un intervallo di caratteri della fonte.
Quando ha finito, chiama compose("letter_001"). Il server intercala i tag registrati nel testo semplice originale, produce la TEI finale e poi verifica byte per byte che il contenuto testuale piatto del documento prodotto sia uguale alla fonte.

Se i byte coincidono, il documento viene restituito. Se non coincidono – se i tag del modello implicano in qualche modo un corpo che differisce dalla fonte anche di un solo carattere – compose() solleva un’eccezione invece di consegnare un documento corrotto.

Non esiste percorso, in questo flusso, che porti il modello a produrre un documento TEI con un corpo diverso dalla fonte. L’invariante è meccanico, non comportamentale: non dovete fidarvi del modello perché non allucini; dovete fidarvi di un == fra due stringhe di byte.

Che cos’è, e che cosa non è

La composizione span-locked è complementare all’ancoraggio allo schema, non lo sostituisce. Gli strumenti di ancoraggio (validate_document, lookup_element, valid_children e il resto dei sedici originali) aiutano il modello a produrre TEI valida; la composizione span-locked garantisce che il corpo del testo dentro quella TEI sia fedele alla fonte. Un flusso di codifica che si possa mettere in produzione deve soddisfare entrambi gli assi, e ora un solo server li copre tutti e due.

Non è nemmeno la panacea. compose() non verifica ancora che i tag registrati siano ammessi da una personalizzazione ODD caricata: arriverà. I tag registrati vivono nella memoria del processo e non sopravvivono a un riavvio. E i file di partenza devono essere leggibili da dove gira il server. Sono tutte cose risolvibili, e nessuna intacca l’invariante di fondo.

Perché conta, al di là della TEI

Lo schema si generalizza. Ogni volta che si chiede a un modello di annotare, trasformare o incapsulare un testo – e ogni volta che l’integrità di quel testo conta più della capacità del modello di «migliorarlo» – la soluzione ha la stessa forma. Non chiedete al modello di ribattere il testo; chiedetegli istruzioni sul testo, e lasciate che un compositore deterministico le applichi sotto un invariante di uguaglianza.

Per le edizioni digitali, in particolare, questo cambia ciò che si può affidare a un modello senza rimorsi. La codifica diventa d’un tratto un compito delegabile, senza dover confrontare a mano ogni output con la fonte. La macchina fa la parte noiosa; il curatore rivede la marcatura, non l’ortografia.

Come aggiornare

Se avete già tei-mcp:

uvx tei-mcp@latest

Oppure da zero:

pip install tei-mcp

Per usare la composizione span-locked, indicate al server una directory di file di testo semplice:

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

Il nome di ogni file, senza estensione, diventa l’ID del documento (letter_001.txt → letter_001).

Codice sorgente, documentazione completa e note di progetto sull’invariante:

tei-mcp

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

tei-mcp: la TEI P5 per gli agenti IA

tei-mcp è un server open source che dà agli assistenti IA per la programmazione un accesso diretto alla specifica . Invece di affidarsi a ciò che ricorda dell’addestramento – da cui esce spesso una marcatura plausibile ma sbagliata – l’IA interroga la specifica in tempo reale.

Funzionalità

Il server analizza l’ODD della TEI P5 ed espone 16 strumenti:

Ricerca di qualunque elemento, classe, macro o modulo per nome, senza distinguere maiuscole e minuscole e con suggerimenti in caso di refuso
Risoluzione degli attributi lungo l’intera gerarchia di classi TEI (locali ed ereditati)
Espansione dei modelli di contenuto in alberi strutturati, con risoluzione di classi e macro
Verifica dell’annidamento: rapporto diretto genitore-figlio, o raggiungibilità ricorsiva con tracciamento del percorso
Validazione dei documenti rispetto alla TEI P5: modelli di contenuto, attributi, liste chiuse di valori, integrità dei riferimenti e avvisi di deprecazione
Validazione di singoli elementi per chi lavora per ritocchi successivi
Caricamento di personalizzazioni ODD per restringere lo schema al sottoinsieme proprio di un progetto
Ricerca in tutti i tipi di entità con espressioni regolari

Installazione

pip install tei-mcp

Oppure si esegue direttamente con:

uvx tei-mcp

Uso

Si aggiunge a qualsiasi client compatibile con MCP (Claude, Cursor, Windsurf ecc.):

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

Il codice sorgente e la documentazione sono nel .

tei-mcp: la TEI P5 per gli agenti IA

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

Chi ha provato a far scrivere XML TEI a un assistente IA per la programmazione sa già come va a finire: sbaglia. Gli elementi spuntano dove non dovrebbero, gli attributi vengono inventati, le regole di annidamento ignorate. Il modello ha un’idea vaga dell’aspetto della TEI, ma nessuna conoscenza affidabile della specifica.

tei-mcp rimedia dando agli agenti IA un accesso diretto, per mezzo di strumenti, alle Guidelines della TEI P5.

Indice dei Contenuti

Che cos’è MCP?

Il (MCP) è uno standard aperto che permette alle applicazioni di IA di collegarsi a fonti di dati e strumenti esterni. Pensate a una porta USB per l’IA: un solo protocollo con cui qualunque client compatibile – Claude, Cursor, Windsurf e altri – si innesta su servizi specializzati.

Un server MCP espone degli strumenti che l’IA può chiamare nel corso di una conversazione. Invece di affidarsi a ciò che ricorda dell’addestramento, il modello interroga una fonte viva e autorevole.

Che cosa fa tei-mcp

tei-mcp analizza la specifica ODD della TEI P5 ed espone 16 strumenti, che rispondono alle domande più comuni di chi cura o codifica un’edizione:

Che cos’è questo elemento? Cerca qualunque elemento, classe, macro o modulo per nome, senza distinguere maiuscole e minuscole e con suggerimenti in caso di refuso.
Quali attributi accetta? Risolve gli attributi lungo l’intera gerarchia di classi: prima quelli locali, poi quelli ereditati, in ordine.
Che cosa può contenere? Espande i modelli di contenuto in alberi strutturati, oppure restituisce l’elenco piatto dei figli ammessi.
Questo elemento può stare qui? Verifica l’annidamento genitore-figlio, o segue la raggiungibilità lungo l’intera gerarchia degli elementi.
Il mio documento è valido? Valida un file XML TEI rispetto alla specifica: modelli di contenuto, valori degli attributi, liste chiuse di valori, integrità dei riferimenti e avvisi di deprecazione.
E lo schema del mio progetto? Carica un file di personalizzazione ODD per restringere tutto quanto sopra al sottoinsieme di TEI proprio del vostro progetto.

Perché conta

Codificare in TEI vuol dire consultare le Guidelines di continuo. I codificatori esperti hanno interiorizzato gli schemi più comuni, ma anche loro devono controllare la specifica per gli elementi meno familiari o per i modelli di contenuto più intricati. Per gli assistenti IA, che di quella conoscenza interiorizzata non hanno nulla, il problema è peggiore: allucinano una marcatura plausibile all’occhio e sbagliata nella sostanza.

Con tei-mcp l’IA non deve più tirare a indovinare: cerca la risposta nella specifica prima di scrivere una sola parentesi angolare. Il risultato è una marcatura conforme alla TEI P5, o alla personalizzazione ODD del vostro progetto.

Per cominciare

Si installa da PyPI:

pip install tei-mcp

Poi lo si aggiunge alla configurazione del client MCP:

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

Al primo avvio il server scarica la specifica TEI; funziona con qualsiasi client compatibile con MCP.

Codice sorgente e documentazione completa: