Sezzlee XML

@sezzlee/xml-mcp

A read-only, sandboxed MCP server that reads local XML documents. It builds on @sezzlee/file-core; it does not depend on @sezzlee/core and imports nothing from packages/lab/xml-lab.

Documentation: https://docs.sezzlee.app/docs/xml-mcp/introduction — a tutorial, task guides, and the tool, error-code and limit reference generated from this package.

Quick start

The root is the only argument, as an absolute path; there is no environment variable for it.

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

With Claude Code:

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

Readable extensions: .xml, .xsd, .xhtml, .svg, .csproj, .props, .targets, .config, .resx. An extension like .config is not a guarantee of XML — a parse error there is expected behavior. Requires Node.js 22 or 24 on macOS (x64, arm64), glibc Linux (x64, arm64) or Windows x64.

Tools

Every argument, error code and limit is listed in the reference.

A document over the 8 MiB resident ceiling is read in a reduced-capability chunked mode: select_xpath, find_in_document and aggregate_document are unavailable there, while project_records still works.

Configuration

createXmlMcpServer(root, options) takes two optional settings; the CLI always uses the defaults.

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

documentCacheSize (S) is the single knob; the worker pool's capacity is derived as W = 2S, and the invariant W >= 2S-1 is pinned by a test — the worker keeps a document alive while the store still holds it, so its map must fit every store entry plus the one being adopted. This is a budget, not enforcement: worker.resourceLimits bounds the JS heap, not WASM linear memory, so exceeding the budget is a process crash rather than a clean resource_limit error. Measured cost is 9.25-10.08x the source byte count, so roughly 81 MiB resident per document at the 8 MiB ceiling; the default S=4 is safe on the smallest supported host.

Rules

Parsing happens in the worker. The main process only ever holds a serializable handle; a WASM pointer never crosses the boundary. No disposal hook was needed on @sezzlee/file-core's document store because of this.

Layout follows the worker/host boundary. engine/ is the worker-side graph and never names host/ or tools/; model/ and primitives/ are the shared vocabulary between the two sides. index.ts, cli.ts, xml-worker.ts and server.ts stay at the root — the tarball entry point, bin, the CI tarball check and the ../package.json read respectively tie them there.

The worker entry never imports the host surface. src/xml-worker.ts only sees node:worker_threads, node:buffer, libxml2-wasm and a type-only protocol; a lint rule enforces this. A worker returns a code string, and the host side constructs the error object.

DOCTYPE is refused before parsing. The prolog scanner runs in the main process; doc.dtd is only the second check. Measured: XML_PARSE_NO_XXE does not block the internal DTD subset.

The worker's stdout never mixes into the parent's fd 1. It is isolated with stdout: true; on stdio MCP, a single stray line breaks JSON-RPC.

diag is off in production and cannot be turned on through an environment variable: it costs 24.9% and its raw report carries an engine pointer.

Unsupported encodings are refused before parsing. The prolog scanner applies the XML 1.0 Appendix F four-byte autodetection; the UCS-4 and EBCDIC families get unsupported_encoding. Measured: the previous scanner missed DOCTYPE in these families.

libxml2-wasm is pinned to exact 0.7.2. A caret would silently invalidate the F0-01 integrity record; the CI tarball checker enforces this.

Development

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

Run tests through Turbo, not pnpm --filter @sezzlee/xml-mcp test: the bare filter skips dependsOn: ["^build"].

A change to a tool's arguments, an error code or a limit changes the generated reference in apps/docs; run pnpm --filter @sezzlee/docs gen and commit the result, or pnpm turbo run validate --filter=@sezzlee/docs fails.

Large-document tests are opt-in and skipped by default; set SEZZLEE_XML_LARGE=1 to run them.