Maibaamvfx

mcp-vfx-parsers

用于解析 VFX 文件格式的 MCP 服务。解析并生成 Nuke .nk、MaterialX .mtlx 和 USD ASCII .usda 文件——全部通过 MCP stdio 协议完成。支持稳定的往返转换。

工具

工具	描述
parse_nuke	解析 .nk 脚本 → JSON AST（节点、属性、DAG 连线）
parse_mtlx	解析 .mtlx XML → JSON AST（节点图、输入、材质）
parse_usda	解析 .usda 文本 → JSON AST（prims、属性、变体、连接）
generate_nuke	JSON AST → .nk 脚本（往返转换稳定）
generate_mtlx	JSON AST → .mtlx XML（往返转换稳定）
generate_usda	JSON AST → .usda 文本（语义往返转换）

所有工具均为只读——它们只转换文本，不会访问文件系统。

安装

npx -y mcp-vfx-parsers

在 Claude Code 中使用

将其添加到 Claude Code MCP 设置（~/.claude/settings.json）：

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

在 Claude Desktop 中使用

将其添加到 claude_desktop_config.json：

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

支持的格式

Nuke .nk

Foundry Nuke 合成脚本。解析基于 TCL 的堆栈连线节点图格式：

• 节点类型、属性、位置
• 通过 set/push 堆栈指令连接输入
• 根设置（合并重复的 Root 块）
• TCL 表达式和 UserKnob 块（以不透明文本形式保留）
• 引号值中的转义序列（\"、\\、\n、\t、\r、\0）

MaterialX .mtlx

MaterialX 着色网络定义。解析基于 XML 的格式：

• 带类型的输入/输出节点图
• 材质分配
• nodename 连接引用（提取 DAG 边）
• 保留属性（引号样式、顺序）
• 注释和 XML 序言
• XML 实体编码/解码（&、{、）

USD ASCII .usda

Pixar Universal Scene Description（ASCII 图层格式）。完整支持语法：

• Prim 层级结构（def、over、class）
• 带 uniform/custom 修饰符的类型化属性
• .connect 连接（UsdShade 节点图）
• .timeSamples 动画数据
• 关系（单个目标和目标数组）
• 带嵌套变体主体的 VariantSets
• 组合弧：引用、负载、继承、特化
• 图层和 prim 元数据
• 三引号字符串和资产路径（@...@、@@@...@@@）

往返保证

所有解析器都严格遵循往返不变性：

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

Nuke 和 MaterialX 会生成字节完全一致的输出。USDA 会以规范化美化打印格式生成语义一致的输出（注释会被剥离——这是有文档记录的限制）。

安全性与健壮性

• 输入大小限制：所有工具都会拒绝大于 10 MB 的输入
• 格式错误的 JSON：生成工具会返回清晰的错误消息，而不会崩溃
• 不访问文件系统：纯文本转换，可安全用于沙箱
• 不使用 eval/exec：不执行动态代码
• 无外部依赖：仅依赖 @modelcontextprotocol/sdk
• 防 XXE：MaterialX 解析器不会评估 DOCTYPE/实体声明
• Unicode：三个解析器均完整支持 UTF-8

开发

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

更新日志

v0.2.0

• 服务加固：JSON.parse() 使用安全处理器封装——格式错误的输入会返回错误，而不会导致 MCP 服务崩溃
• 输入大小限制：全部 6 个工具都会拒绝大于 10 MB 的输入，以防内存耗尽
• Nuke 重复 Root：合并多个 Root 块（后面的值优先），而不是静默丢弃第一个
• Nuke 转义序列：unquote() 现在除 \" 和 \\ 外，还会处理 \n、\t、\r、\0
• USDA 数据保留：.connect 数组和关系目标中的非路径值会以 <INVALID:kind:value> 形式保留，而不是静默丢弃

v0.1.0

• 初始版本：3 个解析器（Nuke、MaterialX、USDA）、6 个 MCP 工具、13 项测试

许可证

MIT