tei MCP

tei mcp

一 主控程序 帮助AI代理读取和写入有效数据的服务器 文本编码倡议 XML。它解析了TEI P5规范，并公开了21个工具，涵盖了两个互补的功能： 模式接地 （元素查找、属性解析、内容模型扩展、嵌套验证、文档验证、ODD定制）以及 跨度锁定合成 （在不让模型重写正文的情况下注释源文本）。


特性

• 元素、类、宏和模块查找 不区分大小写的匹配和拼写建议
• 属性分辨率 跨整个TEI类层次结构（本地+继承）
• 内容模型扩展 具有类和宏分辨率的结构化树
• 嵌套验证 （带路径跟踪的直接父子和递归可达性）
• 文档验证 针对TEI P5：内容模型、属性、封闭值列表、引用完整性、弃用警告
• 单元素验证 用于增量编辑工作流
• ODD定制 支持：加载项目ODD以约束模式（moduleRef过滤、elementSpec删除/更改、attDef修改）
• 正则表达式搜索 跨所有实体类型（元素、类、宏、模块）
• 弃用意识 有有效的截止日期和更换建议
• 属性建议 按意图描述（关键字与属性描述匹配）
• 跨度锁定组合 具有字节相等体文本不变性：模型通过注册标签偏移量来注释源明文，作曲家组装最终的TEI，而不让模型重写体。看 跨度锁定组合 在......下面
• 本地和远程使用：所有工具在服务器在您的计算机上运行和在远程服务器上运行时都能工作

需求

• Python 3.10+
• 紫外线 （推荐）或pip

安装

最快的方法是通过 uvx，它自动获取并运行服务器：

uvx tei-mcp

或者从PyPI安装：

pip install tei-mcp

或者从源代码克隆并安装：

git clone https://github.com/Pantagrueliste/tei-mcp.git
cd tei-mcp
uv sync

首次运行时，服务器下载 p5subset.xml 从TEI网站（~5MB）下载并在本地缓存。

用法

本地服务器（stdio）

当你在自己的机器上运行tei-mcp时，它会通过stdio进行通信。将以下内容添加到客户端的MCP服务器配置中：

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

此文件所在的位置取决于您的客户：

远程服务器（HTTP）

tei-mcp也可以作为远程HTTP服务器运行，因此您不需要在本地安装任何东西。运行它：

fastmcp run tei_mcp/server.py:mcp --transport streamable-http --host 0.0.0.0 --port 8000

然后将MCP客户端指向服务器URL（例如。， http://your-server:8000/mcp).

当服务器远程运行时，它无法访问您计算机上的文件。处理文档的工具(validate_document, load_customisation)直接接受XML内容作为字符串，这样AI代理就可以读取您的本地文件并将其内容发送到远程服务器。看 处理文档 在......下面

工具

大多数模式基础工具都接受 use_odd=True 以查询定制模式而不是完整的TEI P5。跨度锁定工具(get_source, tag_span, compose, list_tags, reset_tags)要求 TEI_MCP_SPAN_SOURCE_ROOT 待配置（请参见 跨度锁定组合).

处理文档

validate_document 和 load_customisation 两者都需要访问XML文件。他们支持两种接收方式：

• 按文件路径 (file_path / odd_path)：服务器从磁盘打开文件。当服务器在您自己的机器上运行时，这是最简单的选择。
• 按内容 (xml_content / odd_content)：XML直接以字符串形式传递。这就是远程服务器的工作方式——AI代理读取您的本地文件并将其内容发送到服务器。

你不需要选择或配置任何东西。当您要求AI代理验证文档时，它将根据服务器是本地还是远程自动使用正确的方法。

示例

本地服务器（文件路径）：

validate_document(file_path="/path/to/my-document.xml")
load_customisation(odd_path="/path/to/my-project.odd")

远程服务器（内容）：

validate_document(xml_content="...")
load_customisation(odd_content="...")

validate_document 还支持两种形式的权限文件（用于引用完整性检查）： authority_files 对于本地路径， authority_contents 对于XML字符串。

ODD定制

加载特定于项目的ODD文件以约束架构：

1. Call load_customisation(odd_path="/path/to/my-project.odd")
   — or load_customisation(odd_content="...") for remote servers
2. Use use_odd=True on subsequent tool calls
3. Call unload_customisation() to revert to the full spec

支持的ODD功能：

• moduleRef 和 include / except 过滤
• elementSpec mode="delete" 删除元素
• elementSpec mode="change" 和 attDef 修改（删除、更改、添加）
• 封闭/半值列表限制

跨度锁定组合

一种使用语言模型对TEI进行编码而不让它们重写源代码的模式。

在标准生成中，模型被要求直接从源文本中生成TEI。该模型通常会产生以下输出 *外表* 正确但无声地修改身体——现代化拼写(mesme → même)，去掉逗号，用古代词代替(luy → lui)，或完全虚构的段落。下游的验证器无法捕捉到这些错误：输出格式良好，模式有效，只有与源代码的字符级差异才会出现差异。对于编码文本成为永久记录的归档工作流程，这是最重要的失败模式。

跨度锁定组合可防止这种情况 根据构造。该模型从不键入正文。它通过以下方式检索源 get_source，通过以下方式将标签注册为该源上的偏移范围 tag_span，然后要求服务器通过以下方式组装最终的TEI compose作曲家将记录的标签与源明文交织在一起，并在返回之前逐字节验证渲染的TEI的平面文本内容是否等于源。如果模型的标签会产生正文与源文本不同的文档， compose() 引发而不是返回损坏的文档。

这是对模式基础的补充。模式接地工具(validate_document, lookup_element, valid_children等）帮助模型生成 *有效的* TEI；span locked composition保证TEI中的正文是 *忠实的* 到源头。这两者共同涵盖了可部署编码工作流必须满足的两个轴。

配置

集 TEI_MCP_SPAN_SOURCE_ROOT 到包含源明文文件的目录。每个文件的词干成为其文档ID（例如。， letter_001.txt 被称为 letter_001).源文件在第一次引用时延迟加载，并在服务器进程的生命周期内缓存。

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

工作流程

1. 呼叫 get_source("letter_001") 检索不可变的正文。
2. 发布一个或多个 tag_span("letter_001", start, end, element_path, attrs) 调用以字符偏移量注册标签。
3. 呼叫 compose("letter_001") 以获得最终的TEI片段，并强制执行正文字节相等性检查。
4. 可选呼叫 list_tags 检查，或 reset_tags 重新开始。

element_path 是记录嵌套上下文的斜线分隔路径（例如。 TEI/text/body/p/persName)；只有最后一段成为元素的本地名称。其余的记录来源。

局限性

• 记录的标签保存在进程内存中，无法在服务器重启后继续使用。
• compose() 当前不检查注册的标签是否符合加载的ODD定制。使用验证组合输出 validate_document 如果模式有效性对您的工作流很重要，那么这是一个单独的步骤。
• 源文件在第一次引用时从磁盘读取，因此源根目录在当时必须是可读的 get_source 被调用。

环境变量

发展

# Install dev dependencies
uv sync

# Run tests
uv run pytest

# Run tests with coverage info
uv run pytest -v

许可证

麻省理工学院