tei-mcp

tei-mcp

AI エージェントが有効な TEI XML を読み書きできるようにする MCP サーバーです。TEI P5 仕様を解析し、相互に補完する 2 つの機能にまたがる 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 エージェントはローカルファイルを読み込み、その内容をリモートサーバーに送信できます。詳しくは、以下のドキュメントの操作をご覧ください。

ツール

ツール	説明
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	ドキュメントに記録されたタグを消去します

スキーマに基づくツールの多くは、完全な TEI P5 の代わりにカスタマイズされたスキーマを照会するための use_odd=True を受け付けます。スパンロックされたツール（get_source、tag_span、compose、list_tags、reset_tags）を使用するには、TEI_MCP_SPAN_SOURCE_ROOT の設定が必要です（スパンロックされた構成をご覧ください）。

ドキュメントの操作

validate_document と load_customisation はどちらも XML ファイルへのアクセスが必要です。ファイルの受け取り方法は次の 2 つです。

• ファイルパスを指定（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="<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 内の本文テキストがソースに 忠実である ことを保証します。この2つを組み合わせることで、運用可能なエンコードのワークフローが満たすべき2つの側面を網羅できます。

設定

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. 1つ以上の 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