tei-mcp

tei-mcp

一个 MCP 服务，帮助 AI Agent 读取和编写有效的 TEI XML。它解析 TEI P5 规范，并提供 21 个工具，涵盖两种互补能力：架构依据（元素查询、属性解析、内容模型展开、嵌套验证、文档验证、ODD 自定义）和跨度锁定式编排（标注源文本，同时不让模型改写正文）。

功能

• 元素、类、宏和模块查询，支持不区分大小写的匹配和拼写错误建议
• 属性解析，覆盖完整的 TEI 类层次结构（本地属性 + 继承属性）
• 内容模型展开为结构化树，并解析类和宏
• 嵌套验证（直接父子关系，以及带路径追踪的递归可达性）
• 文档验证，依据 TEI P5 检查内容模型、属性、封闭值列表、引用完整性，并发出弃用警告
• 单元素验证，适用于增量编辑工作流
• 支持 ODD 自定义：加载项目 ODD 以限制架构（moduleRef 筛选、elementSpec 删除/更改、attDef 修改）
• 正则表达式搜索，涵盖所有实体类型（元素、类、宏、模块）
• 弃用信息，包含 validUntil 日期和替换建议
• 属性建议，根据意图描述匹配属性说明中的关键词
• 跨度锁定式编排，具有字节相等的正文文本不变量：模型通过登记标签偏移量来标注源纯文本，编排器据此组装最终 TEI，全程不会让模型改写正文。请参阅下文的跨度锁定式编排。
• 本地和远程使用：无论服务运行在你的机器上还是远程服务上，所有工具都能正常使用

要求

• Python 3.10+
• uv（推荐）或 pip

安装

最快捷的方式是使用 uvx，它会自动获取并运行服务：

uvx tei-mcp

也可以从 PyPI 安装：

pip install tei-mcp

或者克隆并从源码安装：

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

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

使用方法

本地服务（stdio）

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

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

配置文件的位置取决于你的客户端：

客户端	配置文件
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
Claude Code	项目目录中的 .mcp.json
Cursor	项目目录中的 .cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
其他客户端	请参阅客户端的 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 Agent 可以读取你的本地文件，并将其内容发送到远程服务。请参阅下文的处理文档。

工具

工具	描述
lookup_element	按名称查找元素（例如，persName）
lookup_class	按名称查找类（例如，att.global）
lookup_macro	按名称查找宏（例如，macro.paraContent）
list_module_elements	列出模块中的所有元素（例如，namesdates）
search	在所有 TEI 实体中进行正则表达式搜索
list_attributes	解析元素的所有属性（本地属性及继承属性）
class_membership_chain	显示完整的类层级链
expand_content_model	将内容模型展开为结构化树
valid_children	列出元素所有有效的直接子元素
check_nesting	检查某元素是否可以嵌套在另一元素中
check_nesting_batch	在一次调用中检查多个嵌套组合
suggest_attribute	根据意图描述查找相关属性
validate_document	根据规范验证 TEI XML 文档
validate_element	在上下文中验证单个元素
load_customisation	加载 ODD 自定义配置
unload_customisation	清除已加载的自定义配置
get_source	返回跨度锁定文档的源纯文本
tag_span	在源文本的字符范围内记录一个 TEI 标签
compose	根据已记录的标签组装最终 TEI；强制要求正文文本字节完全相同
list_tags	列出文档当前记录的标签
reset_tags	清除文档已记录的标签

大多数架构依据工具都接受 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 Agent 读取你的本地文件，并将其内容发送到服务。

你无需选择或配置任何内容。当你要求 AI Agent 验证文档时，它会根据服务是在本地还是远程运行，自动采用相应方式。

示例

本地服务（文件路径）：

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

远程服务（内容）：

validate_document(xml_content="<TEI xmlns='...'>...</TEI>")
load_customisation(odd_content="<TEI xmlns='...'>...</TEI>")

validate_document 也支持通过两种形式提供权威文件（用于引用完整性检查）：本地路径使用 authority_files，XML 字符串使用 authority_contents。

ODD 自定义配置

加载项目专用的 ODD 文件以限制架构：

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

支持的 ODD 功能：

• 带有 include / except 过滤条件的 moduleRef
• 用于移除元素的 elementSpec mode="delete"
• 带有 attDef 修改（删除、更改、新增）的 elementSpec mode="change"
• 封闭式／半封闭式值列表限制

跨度锁定式编排

一种利用语言模型编码 TEI，同时避免模型改写原文的模式。

在标准生成方式中，模型会根据一段原文直接生成 TEI。模型生成的输出通常 看起来 正确，却会悄悄改动正文——将拼写现代化（mesme → même）、删掉逗号、替换古旧代词（luy → lui），甚至编造整段内容。下游验证器无法发现这些错误：输出格式良好且符合架构，只有将其与原文进行逐字符比对，才能发现差异。对于编码文本会成为永久记录的档案工作流，这是最需要避免的失败模式。

跨度锁定式编排从机制上避免了这一问题。模型不会输入正文文本。它通过 get_source 获取原文，通过 tag_span 将标签注册为该原文上的偏移范围，然后调用 compose，让服务组装最终的 TEI。编排器会将已记录的标签与原始纯文本交织在一起，并在返回结果前逐字节验证，确保渲染后的 TEI 扁平文本内容与原文完全一致。如果模型添加的标签会导致文档正文与原文不同，compose() 就会抛出异常，而不会返回遭到篡改的文档。

这种方式与架构约束相辅相成。架构约束工具（validate_document、lookup_element、valid_children 等）可帮助模型生成有效的 TEI；跨度锁定式编排则保证该 TEI 中的正文忠实于原文。两者结合，覆盖了可部署编码工作流必须满足的两个方面。

配置

将 TEI_MCP_SPAN_SOURCE_ROOT 设置为包含原文纯文本文件的目录。每个文件的文件名主体都会成为其文档 ID（例如，letter_001.txt 的访问 ID 为 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 时，源目录必须可读。

环境变量

变量	默认值	说明
TEI_ODD_PATH	—	本地 p5subset.xml 的路径（跳过下载）
TEI_ODD_URL	TEI-C GitHub URL	ODD 文件的自定义 URL
TEI_MCP_SPAN_SOURCE_ROOT	./span_sources	包含跨度锁定式编排所需原文纯文本文件的目录。通过文件名主体访问文件。

开发

# Install dev dependencies
uv sync

# Run tests
uv run pytest

# Run tests with coverage info
uv run pytest -v

许可证

MIT