MCP Server Ooxml

Ask the ECMA-376 schema what is legal in a .docx, .xlsx or .pptx, offline.

Why this project? • Install • Usage • How it works • Related projects

You ask your agent to change code that writes .docx, .xlsx or .pptx files. It writes the XML, the tests pass, and then Word says the file has unreadable content. Or Excel offers to repair it and drops half the sheet.

The agent guessed. Office files follow ECMA-376, a standard thousands of pages long, and the details that break a file are easy to get wrong from memory. Elements must appear in a fixed order. An attribute that works on one element doesn't exist on its neighbour. A value that looks reasonable isn't in the allowed list.

This project lets the agent look it up instead. Before it writes an element, it can ask:

• What can go inside this element, and in what order?
• Which attributes does it take, and what values do they accept?
• Why did the validator reject this file, and what would have been legal?

Answers come from the standard itself and cover Word, Excel and PowerPoint files. Everything runs on your machine, with no account and no network calls. Install it as an MCP server, or as an agent skill for agents with a shell like Claude Code and Codex.

docs/what-it-answers.md lists exactly what it can answer, and where a naive reading of the schemas goes wrong.

Install

MCP server

Add it to your MCP client's config. The database ships inside the npm package, so there is nothing to download on first run.

{
  "mcpServers": {
    "ooxml": {
      "command": "npx",
      "args": ["-y", "mcp-server-ooxml"]
    }
  }
}

Agent skill

Install ooxml-lookup into your agent's skills directory:

npx skills add shbernal/ooxml-ai-tooling

Which one?

The two return identical answers. Both are thin adapters over one shared core.

Usage

There is nothing to run yourself. Once installed, your agent looks things up when it is about to write Office XML. You can also point it there:

Add a first-line indent to the paragraphs in our .docx export. Check the schema before you write the XML. When Word or a validator rejects a file, paste the error and ask what would have been legal:

Word won't open this. The validator says The 'bogus' attribute is not declared at /w:document[1]/w:body[1]/w:p[1]/w:pPr[1]/w:ind[1]. skill/SKILL.md covers the CLI and mcp/README.md lists the MCP tools.

How it works

flowchart LR
  xsd["51 ECMA-376 XSDs<br/>vendored, checksummed"] --> build["build/<br/>ingest"]
  build --> db[("ooxml.db<br/>2.2 MB SQLite<br/>5,649 symbols")]
  db --> core["core/<br/>zero runtime deps"]
  core --> skill["ooxml-lookup<br/>agent skill"]
  core --> mcp["mcp-server-ooxml<br/>stdio MCP server"]

• The repo vendors the schemas byte-for-byte, with checksums in schemas/PROVENANCE.md.
• The build is deterministic. CI rebuilds the database and compares a canonical dump against the committed copies.
• The graph keys symbols on the vocabulary, not the namespace URI. Transitional and Strict are one vocabulary under two sets of URIs, so "is this in Strict too?" is a join, not a guess.
• The core uses only Node builtins like node:sqlite, which is why the skill runs from a bare checkout.

Related projects

ooxml-validate answers "is this file valid?" by wrapping Microsoft's OpenXmlValidator. This project answers "what is legal here?" and never opens your document. The two meet at explain, which reads an ooxml-validate diagnostic and answers from the schema.

superdoc-dev/ooxml-dev is the closest existing project, and it is good prior art. The difference is where it runs:

If your question is "what does the spec say about X", use ooxml.dev. If it is "what is structurally legal here", use this.

This project does not model what Word or Excel actually do. Implementations diverge from the standard, and it answers from the standard alone.