oxml-mcp 0.0.9

Model Context Protocol server exposing oxml's XML parsing, XPath and XSD validation
Documentation

Contents

Getting started

The oxml ecosystem

Reference

  • Tools — xml_query, xml_validate, xml_check, xml_inspect
  • Protocol — MCP 2025-11-25 and 2026-07-28, and the two kinds of failure
  • Errors — the two kinds, and which is which
  • Design — why four tools, and why documents are strings
  • Capabilities in 0.0.9 — release inventory
  • Ecosystem comparison — how this compares to the alternatives
  • Benchmarks — latency per request, measured in pairs

Practical

Why a model wants this

A 40 MB XML file does not fit in a context window, and pasting a fraction of it produces confident answers about the fraction.

count(//record) fits in twelve characters and returns a number. That is the whole argument: give the model a query interface and the document stays on disk.

The secondary argument is arithmetic. A model asked to count elements in a document it can see will approximate. xml_query with count(//record) will not.

Install

cargo install oxml-mcp

Without a Rust toolchain, the same binary ships as an image on GHCR (the MCP registry entry points at it):

docker run --rm -i ghcr.io/sebastienrousseau/oxml-mcp:0.0.9

Transports

One binary, three ways to reach it. Every server in the suite takes the same flags.

Command Transport Endpoint Protocol revisions
oxml-mcp stdio stdin and stdout 2024-11-05 to 2026-07-28
oxml-mcp --transport streamable-http --host 127.0.0.1 --port 8000 Streamable HTTP http://127.0.0.1:8000/mcp 2025-11-25 and 2026-07-28
oxml-mcp --transport sse --port 8001 HTTP+SSE (legacy) http://127.0.0.1:8001/sse, /messages/ 2024-11-05

Streamable HTTP serves both current revisions on the one endpoint: a client that sends initialize gets a session and an Mcp-Session-Id; a client that names 2026-07-28 in each request's _meta is served statelessly, with server/discover in place of the handshake. Responses stream as server-sent events, and GET /mcp opens the server-to-client stream. The SSE transport is the older one, for hosts that still expect an endpoint event and a message URL.

The HTTP transports bind the loopback interface unless --host says otherwise, and they do not authenticate. Put the server behind a gateway you trust before binding a routable address. --version and --help do what they say.

Quick Start

The server speaks JSON-RPC 2.0 over stdio, so three lines are enough to see it work — the handshake, then a call — and no client is required:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"me","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"xml_query","arguments":{"xml":"<library><book><title>Dune</title></book></library>","xpath":"//title"}}}' \
  | oxml-mcp | tail -n 1

{"jsonrpc":"2.0","id":2,"result":{"resultType":"complete","content":[{"type":"text","text":"Dune"}],"structuredContent":{"count":1,"values":["Dune"]},"isError":false}}

For day-to-day use you want a client to do that for you — see Configure.

Configure

Add it to your MCP client's server list. For Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "oxml": {
      "command": "oxml-mcp"
    }
  }
}

For Claude Code:

claude mcp add oxml -- oxml-mcp

Without arguments the server speaks JSON-RPC 2.0 over stdin and stdout, one message per line, which is what these clients expect. A client that connects over HTTP instead points at a server started with --transport streamable-http — see Transports. There is no configuration file.

The oxml ecosystem

Crate What it is
oxml The library: parser, tree, XPath 1.0
xmlschema XSD validation
oxml-cli The command line
oxml-wasm WebAssembly bindings
oxml-mcp This crate — MCP server
oxml-lsp Language Server Protocol server

All six ship one version number, in steps of 0.0.1.

Tools

xml_query

Evaluate an XPath 1.0 expression and return the matching values.

Argument Type
xml string The document
xpath string An XPath 1.0 expression
namespaces object Optional. Prefix-to-URI bindings for the expression 
{"name":"xml_query","arguments":{"xml":"<r><t>Dune</t><t>Germinal</t></r>","xpath":"//t"}}

Dune
Germinal

One value per line. Expressions returning a number, string or boolean return that value directly, so count(//t) gives 2. Every tool also returns its answer as structuredContent, against the outputSchema it advertises — here {"count": 2, "values": ["Dune", "Germinal"]}.

xml_inspect

Summarise a document's shape: root element, maximum depth, every element name with its count, and the namespaces it uses.

{"name":"xml_inspect","arguments":{"xml":"<r><t>x</t></r>"}}

Root element: r
Maximum depth: 3
Elements:
  r: 1
  t: 1

Call this first. A model that knows the element names can write a query that works; one that guesses writes //item against a document whose elements are called record.

xml_check

Report whether a document is well-formed, with a line and column if it is not.

{"name":"xml_check","arguments":{"xml":"<a/>"}}

The document is well-formed (2 nodes).

xml_validate

Validate against an XML Schema, returning every violation with the path to the element it concerns.

Argument Type
xml string The document
xsd string The schema

Protocol

MCP over JSON-RPC 2.0, implemented by rmcp, the official Rust SDK. Two revisions are current and both are served: 2025-11-25, with an initialize handshake, and 2026-07-28, which has no handshake — each request names its revision in _meta and server/discover describes the server. Older revisions back to 2024-11-05 are accepted from a client that asks for them.

Method
initialize Capabilities, server info, the negotiated revision
server/discover The same, for the stateless revision
tools/list The four tools: input schema, output schema, annotations
tools/call Invoke one
ping Answered

Every tool is annotated read-only, idempotent and closed-world, so a client can call it without asking.

The two kinds of failure are kept apart, because MCP distinguishes them and a model only ever sees one of them.

A tool that ran and could not do the job — a malformed document, an invalid expression — is a successful JSON-RPC response carrying isError: true. The model sees the text and can correct itself.

A request the protocol rejects — malformed JSON, an unknown method, a request with an id but no method — is a JSON-RPC error with the standard code, or an HTTP status over HTTP. Nothing ran, and the client handles it rather than the model.

Situation Reply
Malformed document result, isError: true
Invalid XPath expression result, isError: true
Schema violation result, isError: true, with the violations as structuredContent
Missing or mistyped argument result, isError: true, naming the field
Unknown tool result, isError: true, naming the four that exist
Unknown method error, -32601
id with no method error
Malformed JSON HTTP 415 over HTTP; skipped over stdio, the session continues

Errors

A malformed document is not a crash and not a protocol error:

{"name":"xml_check","arguments":{"xml":"<a>"}}

{"content":[{"text":"…not well-formed…","type":"text"}],"isError":true}

The model reads that text and can fix the document or tell the user.

Design

Four tools, not fourteen. Every tool description is in the model's context on every request. A server with twenty narrow tools spends more context describing itself than a document would.

Documents are passed as strings, not paths. The server never opens a file. The client decides what the model may read, which is where that decision belongs — a server that took paths would be a way to read any file on the machine.

One protocol implementation, not ours. The JSON-RPC and MCP layers are the official SDK's. Three protocol revisions and three transports are a protocol project, and keeping a hand-written one honest against them is not where the value of an XML server lies. What is this crate's own is the four functions and the text a model reads.

Capabilities in 0.0.9

  • Four tools: query, inspect, check, validate
  • XPath 1.0: ten axes, 25 functions, all four value types
  • XSD validation
  • JSON-RPC 2.0 over stdio, MCP 2024-11-05
  • Escaped surrogate pairs in JSON input, so a document containing an emoji works from a Python client
  • No filesystem access, no network access

Not yet: resources, prompts, streaming, documents by path or URI.

Ecosystem comparison

The alternatives are ways of getting XML in front of a model rather than competing servers:

Approach Document size Precision Reaches the network
oxml-mcp bounded by the tool call, not the context window an XPath expression with an exact answer never
Paste into the context must fit, and costs tokens every turn the model pattern-matches by eye no
A filesystem or shell server unbounded whatever grep gives you depends on the server
A generic HTTP fetch server unbounded none yes, by design

The last row is the one worth pausing on. A server that fetches is a server that can be pointed at your internal network by a document it was asked to read. The tools here have no code that opens a socket; the only listener is the one you start with --transport, and it only ever answers.

Benchmarks

cargo bench --bench protocol

Latency per request, since an MCP client sends one and waits. The JSON-RPC layer adds roughly 10–25% over the bare parse on a 200 KB payload and is a few microseconds on a small one. See doc/BENCHMARKS.md, which also explains why that comparison has to be measured in pairs.

Examples

examples/ drives the real binary over stdio and asserts the responses, so the invocations in this README fail CI when they stop being true.

Example What it shows
session.sh A full session: initialise, list, call each tool
errors.sh Malformed documents, bad expressions, protocol errors

When not to use oxml-mcp

  • The document fits in context. Paste it; a tool round-trip is slower and adds nothing.
  • You need the model to write XML. These tools read.
  • You need XSLT or XPath 2.0. Neither is available.
  • The document is larger than memory. It is parsed in full.
  • You want the server to fetch documents. It never will; that is the point.

FAQ

Why does the model have to pass the whole document every time?

Because the server holds no state between calls. That keeps it correct when several clients share one binary, and it means there is no cache to invalidate or leak between sessions.

For a large document this is genuinely wasteful, and a future release may add a handle-based flow. Until then, xml_inspect once and a precise xml_query beats several exploratory ones.

Can it read a file from disk?

No, and it will not be able to. The server takes document contents. A server that took paths would let any model with access to it read any file the server process can — the client is where that decision belongs.

Is it safe to point at untrusted XML?

Yes. External entities are never dereferenced, so a document containing <!ENTITY xxe SYSTEM "file:///etc/passwd"> cannot make the server read that file. Entity expansion and nesting depth are bounded.

Why are there only four tools?

Every tool's description occupies context on every request. Four broad tools cost less than twenty narrow ones and cover the same ground, because XPath is already a query language.

Does it work with clients other than Claude?

It implements MCP with no client-specific behaviour, over stdio and both HTTP transports, so any compliant client should work. It is checked against the Python SDK's client over both HTTP transports and scores 100/100 with an independent MCP auditor in both current protocol eras.

My document contains an emoji and the call failed.

That was a bug, fixed in 0.0.3. Python's json.dumps escapes non-ASCII by default, so an emoji arrives as a surrogate pair — 😀 — and the JSON parser rejected escaped surrogate pairs. Any Python client sending an emoji hit it.

How do I query a document with namespaces?

Pass them with the query:

{"name":"xml_query","arguments":{
  "xml":"…","xpath":"//m:item","namespaces":{"m":"urn:example"}}}

A prefix resolves against these bindings, not against the document, so the same expression works across documents that spell the prefix differently — only the URI has to match. An unbound prefix is an error that names the argument to pass and points at xml_inspect.

xml_inspect reports the namespaces a document uses, which is what makes the argument usable: a model cannot bind a URI it cannot see.

Namespaces (pass these to xml_query as `namespaces`):
  urn:example: 12 element(s)

An unprefixed name test matches only nodes in no namespace, which is what XPath 1.0 specifies. namespace-uri() still works and needs no binding.

What happens if the model sends invalid JSON?

A JSON-RPC parse error, -32700. The server does not exit; the next line is read as normal.

Why is an unknown tool isError rather than a JSON-RPC error?

Until 0.0.8 it was -32602. In the stateless HTTP revision the SDK carries that code as an HTTP 400, which a client reports as a transport fault and a model never reads. A model that misspelt a tool name is better served by text naming the four tools that exist. See Protocol.

Development

./scripts/gate.sh

That runs everything CI runs, in the order that fails fastest: format, clippy, tests, rustdoc, the #![forbid(unsafe_code)] check, the examples, the 95% coverage floor and an MSRV build. It pins the toolchain rather than trusting rust-toolchain.toml, because a RUSTUP_TOOLCHAIN in the environment silently overrides that file and a lint that exists in one release and not another then makes a green local run and a red CI one.

The individual steps, if you want them one at a time:

cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all --check
cargo bench --bench protocol
OXML_MCP="$PWD/target/release/oxml-mcp" ./examples/run-all.sh

CI runs the same set on Linux, macOS and Windows.

Security

The tools never open a file or a socket. External entities are never dereferenced. Entity expansion and recursion are bounded. #![forbid(unsafe_code)]. The HTTP listeners exist only when asked for on the command line, bind loopback by default, and do not authenticate — see Transports.

The threat model is that both the document and the JSON around it are hostile — the document because a model was asked to look at something from the internet, and the JSON because it is the program's entire input. See https://github.com/sebastienrousseau/oxml/blob/main/doc/SECURITY-MODEL.md.

Documentation

Acknowledgements

oxml-mcp exists because of work that came before it:

  • Anthropic — for the Model Context Protocol specification this server implements.
  • lxml and libxml2 — the reference for what an XML toolkit should offer, and decades of hard-won correctness.
  • W3C — for the XPath 1.0 specification that xml_query follows.

License

Dual-licensed under either the Apache License, Version 2.0 or the MIT License, at your option.