mcp-vfx-parsers

MCP server for VFX file format parsing. Parse and generate Nuke .nk, MaterialX .mtlx, and USD ASCII .usda files — all via the MCP stdio protocol. Round-trip stable.

Tools

| Tool | Description | |------|-------------| | parse_nuke | Parse .nk script → JSON AST (nodes, properties, DAG wiring) | | parse_mtlx | Parse .mtlx XML → JSON AST (node graphs, inputs, materials) | | parse_usda | Parse .usda text → JSON AST (prims, attributes, variants, connections) | | generate_nuke | JSON AST → .nk script (round-trip stable) | | generate_mtlx | JSON AST → .mtlx XML (round-trip stable) | | generate_usda | JSON AST → .usda text (semantic round-trip) |

All tools are read-only — they transform text, never touch the filesystem.

Install

npx -y mcp-vfx-parsers

Usage with Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "vfx-parsers": {
      "command": "npx",
      "args": ["-y", "mcp-vfx-parsers"]
    }
  }
}

Usage with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "vfx-parsers": {
      "command": "npx",
      "args": ["-y", "mcp-vfx-parsers"]
    }
  }
}

Supported Formats

Nuke .nk

Foundry Nuke compositing scripts. Parses the TCL-based stack-wired node graph format:

• Node types, properties, positions
• Input wiring via set/push stack directives
• Root settings (merges duplicate Root blocks)
• TCL expressions and UserKnob blocks (preserved as opaque text)
• Escape sequences in quoted values (\", \\, \n, \t, \r, \0)

MaterialX .mtlx

MaterialX shading network definitions. Parses the XML-based format:

• Node graphs with typed inputs/outputs
• Material assignments
• nodename connection references (DAG edge extraction)
• Attribute preservation (quote style, order)
• Comments and XML prolog
• XML entity encoding/decoding (&, {, )

USD ASCII .usda

Pixar Universal Scene Description (ASCII layer format). Full grammar support:

• Prim hierarchy (def, over, class)
• Typed attributes with uniform/custom modifiers
• .connect connections (UsdShade node graphs)
• .timeSamples animation data
• Relationships (single + array targets)
• VariantSets with nested variant bodies
• Composition arcs: references, payloads, inherits, specializes
• Layer and prim metadata
• Triple-quoted strings and asset paths (@...@, @@@...@@@)

Round-Trip Guarantee

All parsers maintain a strict round-trip invariant:

parse(generate(parse(input))) === parse(input)

Nuke and MaterialX produce byte-identical output. USDA produces semantically identical output in canonical pretty-print form (comments stripped — documented limitation).

Safety & Robustness

• Input size limit: All tools reject inputs larger than 10 MB
• Malformed JSON: Generate tools return clear error messages instead of crashing
• No filesystem access: Pure text transforms, safe for sandboxing
• No eval/exec: No dynamic code execution
• No external dependencies: Only @modelcontextprotocol/sdk
• XXE-safe: MaterialX parser does not evaluate DOCTYPE/entity declarations
• Unicode: Full UTF-8 support across all three parsers

Development

git clone https://github.com/MABAAM/mcp-vfx-parsers.git
cd mcp-vfx-parsers
npm install
npm test
node src/server.mjs

Changelog

v0.2.0

• Server hardening: JSON.parse() wrapped in safe handler — malformed input returns error instead of crashing the MCP server
• Input size limits: All 6 tools reject inputs > 10 MB to prevent memory exhaustion
• Nuke duplicate Root: Multiple Root blocks are merged (later values win) instead of silently discarding the first
• Nuke escape sequences: unquote() now handles \n, \t, \r, \0 in addition to \" and \\
• USDA data preservation: Non-path values in .connect arrays and relationship targets are preserved as <INVALID:kind:value> instead of silently dropped

v0.1.0

• Initial release: 3 parsers (Nuke, MaterialX, USDA), 6 MCP tools, 13 tests

License

MIT