Sezzlee XML

@sezzlee/xml-mcp

ローカルの XML ドキュメントを読み込む、読み取り専用のサンドボックス化された MCP サーバーです。 @sezzlee/file-core を基盤としており、@sezzlee/core には依存せず、 packages/lab/xml-lab から何もインポートしません。

ドキュメント：https://docs.sezzlee.app/docs/xml-mcp/introduction — このパッケージから生成されたチュートリアル、タスクガイド、ツール、エラーコード、制限のリファレンスです。

クイックスタート

引数はルートのみで、絶対パスを指定します。ルートを指定する環境変数はありません。

{
  "mcpServers": {
    "xml": {
      "command": "npx",
      "args": ["-y", "@sezzlee/xml-mcp", "/path/to/xml/root"]
    }
  }
}

Claude Code の場合：

claude mcp add xml -- npx -y @sezzlee/xml-mcp /path/to/xml/root

読み取り可能な拡張子：.xml、.xsd、.xhtml、.svg、.csproj、.props、.targets、.config、 .resx。.config などの拡張子でも、XML であるとは限りません。その場合、パースエラーは想定された動作です。 macOS（x64、arm64）、glibc Linux（x64、arm64）、または Windows x64 で Node.js 22 または 24 が必要です。

ツール

ツール	機能
list_documents	ルート以下にある読み取り可能な XML ドキュメントを、パースせずに一覧表示します
describe_document	ドキュメント要素、安定したエイリアスを持つすべての名前空間、構造の件数、繰り返し要素の候補、および read_node が受け取るアドレスを表示します
read_node	ツリーの順序を保った、深さ優先のフラットなレコード形式による範囲を指定した読み取り
find_in_document	テキストノード、属性値、またはその両方からリテラルテキストを検索します
select_xpath	XPath 1.0 式をそのまま 1 つ実行し、型付きの結果を返します
project_records	繰り返し要素を行と名前付き列として表示し、セルごとにステータスを付与します
aggregate_document	件数、ユニーク件数、および numericMode: binary64 の場合はグループごとの合計と平均を表示します

すべての引数、エラーコード、制限については、 リファレンスをご覧ください。

8 MiB の常駐上限を超えるドキュメントは、機能を制限した chunked モードで読み込まれます。 このモードでは select_xpath、find_in_document、aggregate_document は利用できませんが、 project_records は引き続き動作します。

設定

createXmlMcpServer(root, options) は、任意の設定を 2 つ受け取ります。CLI では常にデフォルト値が使用されます。

オプション	デフォルト	意味
documentCacheSize	4	同時にメモリへ常駐させるドキュメント数（1～64）
maxConcurrentListings	4	同時実行できる list_documents 呼び出し数

createXmlMcpServer(root, {
  documentCacheSize: 4,
  maxConcurrentListings: 4,
});

documentCacheSize（S）が唯一の調整項目です。ワーカープールの容量は W = 2S として導出され、不変条件 W >= 2S-1 はテストで固定されています。ワーカーはストアがドキュメントを保持している間、そのドキュメントを保持し続けるため、マップの容量はストアのすべてのエントリに、取り込み対象の 1 件を加えた数を満たす必要があります。これは予算であり、強制される上限ではありません。worker.resourceLimits が制限するのは JS ヒープであり、WASM のリニアメモリではないため、予算を超えると正常な resource_limit エラーではなく、プロセスがクラッシュします。実測コストはソースのバイト数の 9.25～10.08 倍で、8 MiB の上限ではドキュメント 1 件あたり約 81 MiB が常駐します。デフォルトの S=4 は、サポート対象の最小ホストでも安全です。

ルール

解析はワーカー内で行います。 メインプロセスが保持するのはシリアライズ可能なハンドルだけであり、WASM ポインターが境界を越えることはありません。このため、@sezzlee/file-core のドキュメントストアに破棄フックは必要ありませんでした。

配置はワーカーとホストの境界に従います。 engine/ はワーカー側のグラフであり、host/ や tools/ を参照しません。model/ と primitives/ は両側で共有する用語です。index.ts、cli.ts、xml-worker.ts、server.ts はルートに置いたままにします。それぞれ、tarball のエントリーポイント、bin、CI の tarball チェック、../package.json の読み取りによって、その場所に置く必要があります。

ワーカーのエントリーポイントはホスト側のインターフェースをインポートしません。 src/xml-worker.ts が参照するのは node:worker_threads、node:buffer、libxml2-wasm、型のみのプロトコルだけです。これをリントルールで強制しています。ワーカーはコード文字列を返し、ホスト側でエラーオブジェクトを構築します。

DOCTYPE は解析前に拒否します。 プロローグスキャナーはメインプロセスで実行されます。doc.dtd は2つ目のチェックにすぎません。実測では、XML_PARSE_NO_XXE は内部 DTD サブセットをブロックしません。

ワーカーの stdout が親プロセスの fd 1 に混ざることはありません。 stdout: true で分離しています。stdio の MCP では、余計な行が1行でもあると JSON-RPC が壊れます。

本番環境では diag は無効であり、環境変数から有効にすることもできません。コストが 24.9% 増加し、未加工のレポートにエンジンポインターが含まれるためです。

サポート対象外のエンコーディングは解析前に拒否します。 プロローグスキャナーは XML 1.0 付録 F の4バイト自動検出を適用します。UCS-4 および EBCDIC 系列には unsupported_encoding を返します。実測では、以前のスキャナーはこれらの系列で DOCTYPE を検出できませんでした。

libxml2-wasm は正確なバージョン 0.7.2 に固定します。 キャレットを付けると F0-01 の整合性記録が予告なく無効になるため、CI の tarball チェッカーでこれを強制しています。

開発

pnpm turbo run build --filter=@sezzlee/xml-mcp
pnpm turbo run test --filter=@sezzlee/xml-mcp
pnpm turbo run check-types --filter=@sezzlee/xml-mcp

テストは Turbo 経由で実行してください。pnpm --filter @sezzlee/xml-mcp test では実行しないでください。フィルターのみを指定すると、dependsOn: ["^build"] がスキップされます。

ツールの引数、エラーコード、または制限を変更すると、apps/docs 内の生成済みリファレンスに影響します。pnpm --filter @sezzlee/docs gen を実行して結果をコミットしてください。そうしないと、pnpm turbo run validate --filter=@sezzlee/docs が失敗します。

大きなドキュメントのテストはオプトイン方式で、デフォルトではスキップされます。実行するには SEZZLEE_XML_LARGE=1 を設定してください。