MCP |

tei-mcp v0.3: codificar em TEI sem reescrever a fonte

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

Quando , o objetivo era impedir os assistentes de IA de alucinar marcação TEI. A ancoragem no esquema resolveu parte do problema: com acesso direto, por ferramentas, à especificação P5, o modelo já não tem de adivinhar o que um elemento significa nem que atributos aceita. O resultado valida.

Mas a alucinação tem duas faces na codificação TEI, e o esquema só apanha uma delas. Validar contra a especificação diz-nos que a marcação está bem formada. Nada diz sobre o texto que essa marcação envolve. E é aí – no próprio texto – que vivem as alucinações mais nocivas. A composição por intervalos bloqueados, a grande novidade da v0.3, foi concebida especificamente para as impedir.

Lista de Conteúdos

A alucinação que o esquema não apanha

Peça-se a um modelo que codifique uma carta francesa do século XVI e receber-se-á muitas vezes um documento TEI de aspeto impecável. O cabeçalho está preenchido, as etiquetas <persName> estão bem colocadas, o <dateline> está bem formado. Passe-se pelo validate_document e ele passa.

Compare-se depois o corpo com a fonte.

mesme passou a même. Uma vírgula mudou de sítio. luy foi silenciosamente modernizado em lui. Uma oração de leitura difícil no manuscrito foi «corrigida» para algo mais limpo. Nenhuma destas alterações foi pedida. Nenhuma é assinalada. O documento é válido segundo o esquema e está discretamente errado.

Para um fluxo de trabalho de arquivo – em que o texto codificado se torna o registo permanente de que dependem leitores, índices de pesquisa e citações – é este o modo de falha que mais importa. Uma etiqueta malformada é um incómodo. Uma grafia modernizada de que ninguém dá conta durante cinco anos é uma corrupção.

A composição por intervalos bloqueados

A nova versão (v0.3) traz um mecanismo de prevenção de alucinações apontado diretamente a este modo de falha. O objetivo de design é tornar as alucinações no corpo do texto impossíveis por construção, e não apenas improváveis.

A ideia é simples: o modelo nunca escreve texto de corpo.

Em vez disso, o fluxo de trabalho é o seguinte:

O modelo chama get_source("letter_001") e recebe o texto simples da fonte como cadeia imutável.
Para cada etiqueta que queira aplicar, chama tag_span("letter_001", start, end, element_path, attrs) – registando um elemento TEI sobre um intervalo de caracteres da fonte.
Quando termina, chama compose("letter_001"). O servidor intercala as etiquetas registadas com o texto simples original, gera o TEI final e verifica depois, byte a byte, que o conteúdo textual plano do documento gerado é igual à fonte.

Se os bytes coincidem, o documento é devolvido. Se não coincidem – se as etiquetas do modelo implicarem de algum modo um corpo que difere da fonte num único caráter que seja –, compose() lança uma exceção em vez de devolver um documento corrompido.

Não há caminho, neste fluxo de trabalho, em que o modelo produza um documento TEI cujo corpo difira da fonte. O invariante é mecânico, não comportamental. Não é preciso confiar que o modelo não alucina; basta confiar numa comparação == entre duas cadeias de bytes.

O que isto é, e o que não é

A composição por intervalos bloqueados é complementar da ancoragem no esquema; não a substitui. As ferramentas de ancoragem no esquema (validate_document, lookup_element, valid_children e as restantes das dezasseis originais) ajudam o modelo a produzir TEI válida. A composição por intervalos bloqueados garante que o corpo do texto dentro dessa TEI é fiel à fonte. Um fluxo de codificação que se possa pôr em produção tem de satisfazer os dois eixos, e agora ambos ficam cobertos por um único servidor.

Também não é uma varinha mágica para tudo. compose() ainda não verifica se as etiquetas registadas são admissíveis segundo uma personalização ODD carregada – fica para uma próxima versão. As etiquetas registadas vivem na memória do processo e não sobrevivem a um reinício. E os ficheiros-fonte têm de ser legíveis a partir de onde quer que o servidor corra. Tudo isto tem solução; nada disto abala o invariante central.

Porque é que isto importa para lá da TEI

O padrão generaliza-se. Sempre que se pede a um modelo que anote, transforme ou envolva um pedaço de texto – e sempre que a integridade do texto subjacente importa mais do que a capacidade do modelo para o «melhorar» –, aplica-se a mesma forma de solução. Não peça ao modelo que reescreva o texto. Peça-lhe que produza instruções sobre o texto, e deixe que um compositor determinista as aplique sob um invariante de igualdade.

Para as edições digitais em particular, isto muda o que se pode pedir a um modelo com responsabilidade. A codificação torna-se de repente uma tarefa delegável sem ter de comparar à mão cada resultado com a fonte. A máquina faz o caminho enfadonho; o editor revê a marcação, não a ortografia.

Obter a atualização

Se já tem o tei-mcp instalado:

uvx tei-mcp@latest

Ou de raiz:

pip install tei-mcp

Para usar a composição por intervalos bloqueados, aponte o servidor para uma diretoria de ficheiros-fonte em texto simples:

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

O radical do nome de cada ficheiro passa a ser o seu identificador de documento (letter_001.txt → letter_001).

Código-fonte, documentação completa e notas de design do invariante:

tei-mcp

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

tei-mcp: a TEI P5 ao alcance dos agentes de IA

O tei-mcp é um servidor de código aberto que dá aos assistentes de programação por IA acesso direto à especificação . Em vez de se fiar em dados de treino memorizados – o que produz muitas vezes marcação plausível, mas incorreta –, a IA pode consultar a especificação em tempo real.

Funcionalidades

O servidor analisa a ODD da TEI P5 e expõe 16 ferramentas:

Consultar qualquer elemento, classe, macro ou módulo pelo nome, sem distinção de maiúsculas e com sugestões em caso de gralha
Resolver atributos ao longo de toda a hierarquia de classes da TEI (locais + herdados)
Expandir modelos de conteúdo em árvores estruturadas, com resolução de classes e macros
Validar o aninhamento – relação direta pai-filho ou acessibilidade recursiva, com registo do caminho
Validar documentos contra a TEI P5: modelos de conteúdo, atributos, listas fechadas de valores, integridade das referências e avisos de depreciação
Validar elementos isolados para fluxos de edição incremental
Carregar personalizações ODD para restringir o esquema a um subconjunto específico do projeto
Pesquisar em todos os tipos de entidade com expressões regulares

Instalação

pip install tei-mcp

Ou executar diretamente com:

uvx tei-mcp

Utilização

Acrescente-o a qualquer cliente compatível com MCP (Claude, Cursor, Windsurf, etc.):

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

O código-fonte e a documentação estão no .

tei-mcp: a TEI P5 ao alcance dos agentes de IA

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

Quem já tenha usado um assistente de programação por IA para escrever XML TEI terá reparado que ele se engana. Aparecem elementos onde não deviam. Inventam-se atributos. Ignoram-se as regras de aninhamento. O modelo tem uma ideia vaga do aspeto da TEI, mas nenhum conhecimento fiável da especificação.

O tei-mcp resolve o problema dando aos agentes de IA acesso direto, por meio de ferramentas, às Guidelines da TEI P5.

Lista de Conteúdos

O que é o MCP?

O (MCP) é uma norma aberta que permite às aplicações de IA ligar-se a fontes de dados e ferramentas externas. Pense-se nele como uma porta USB para a IA: um protocolo único que permite a qualquer cliente compatível – Claude, Cursor, Windsurf e outros – ligar-se a serviços especializados.

Um servidor MCP expõe ferramentas que a IA pode invocar durante uma conversa. Em vez de se fiar em dados de treino memorizados, o modelo pode consultar uma fonte viva e autorizada.

O que faz o tei-mcp

O tei-mcp analisa a especificação ODD da TEI P5 e expõe 16 ferramentas que cobrem as perguntas mais frequentes de um editor ou codificador:

O que é este elemento? Consultar qualquer elemento, classe, macro ou módulo pelo nome, sem distinção de maiúsculas e com sugestões em caso de gralha.
Que atributos aceita? Resolver os atributos ao longo de toda a hierarquia de classes – primeiro os locais, depois os herdados, por ordem.
O que pode conter? Expandir os modelos de conteúdo em árvores estruturadas, ou obter uma lista simples dos filhos válidos.
Este elemento pode ir aqui? Verificar o aninhamento pai-filho, ou seguir a acessibilidade através de toda a hierarquia de elementos.
O meu documento é válido? Validar um ficheiro XML TEI contra a especificação: modelos de conteúdo, valores de atributos, listas fechadas de valores, integridade das referências e avisos de depreciação.
E o esquema do meu projeto? Carregar um ficheiro de personalização ODD para restringir tudo o que precede ao subconjunto de TEI próprio do seu projeto.

Porque é que isto importa

Codificar em TEI exige consultar as Guidelines a toda a hora. Os codificadores experientes interiorizam os padrões mais comuns, mas até eles têm de verificar a especificação quando se trata de elementos menos familiares ou de modelos de conteúdo complexos. Para os assistentes de IA, que não têm esse conhecimento interiorizado, o problema é pior: alucinam marcação de aspeto plausível, mas incorreta.

Com o tei-mcp, a IA não tem de adivinhar. Pode procurar a resposta na especificação antes de escrever um único parêntese angular. O resultado é marcação conforme à TEI P5 – ou à personalização ODD do seu projeto.

Primeiros passos

Instale a partir do PyPI:

pip install tei-mcp

Depois, acrescente-o à configuração do seu cliente MCP:

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

O servidor descarrega a especificação TEI na primeira execução e funciona com qualquer cliente compatível com MCP.

Código-fonte e documentação completa: