Sezzlee XML

@sezzlee/xml-mcp

一个只读、沙箱隔离的 MCP 服务，用于读取本地 XML 文档。 它基于 @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 表达式，完全按原样处理，并返回带类型的结果
project_records	将重复元素作为行和命名列返回，并为每个单元格提供状态
aggregate_document	按组统计数量、不同值数量，以及在 numericMode: binary64 下的总和与平均值

所有参数、错误代码和限制均列于参考文档。

超过 8 MiB 常驻内存上限的文档会以功能受限的 chunked 模式读取： 此模式下无法使用 select_xpath、find_in_document 和 aggregate_document，但仍可使用 project_records。

配置

createXmlMcpServer(root, options) 接受两个可选设置；CLI 始终使用默认值。

选项	默认值	含义
documentCacheSize	4	同时保留在内存中的文档数量（1–64）
maxConcurrentListings	4	并发 list_documents 调用数量

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

documentCacheSize（S）是唯一的调节参数；工作池容量按 W = 2S 推导，且由测试固定的 不变量 W >= 2S-1 必须成立——工作线程会在存储仍保留文档时继续持有该文档，因此其映射必须能容纳存储中的每个条目，以及正在接收的那个条目。这是预算，而非强制限制：worker.resourceLimits 限制的是 JS 堆，而不是 WASM 线性内存，因此超出预算会导致进程崩溃，而不是返回正常的 resource_limit 错误。实测成本为源文件字节数的 9.25-10.08 倍，因此在 8 MiB 上限下，每个文档的常驻内存约为 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 和纯类型协议；Lint 规则会强制执行这一点。工作线程返回代码字符串，由宿主侧构造错误对象。

解析前拒绝 DOCTYPE。 前言扫描器在主进程中运行；doc.dtd 仅是第二道检查。实测：XML_PARSE_NO_XXE 不会阻止内部 DTD 子集。

工作线程的 stdout 不会混入父进程的 fd 1。 通过 stdout: true 隔离 stdout；对于 stdio MCP，任何多余的一行都会破坏 JSON-RPC。

生产环境中关闭 diag，且无法通过环境变量启用：它会带来 24.9% 的开销，而且其原始报告包含引擎指针。

解析前拒绝不支持的编码。 前言扫描器会应用 XML 1.0 附录 F 的四字节自动检测；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 可运行这些测试。