Babylon.js MCP Tools 全景解析：用 Model Context Protocol 打通 Babylon.js 全套创作工作流

• 图形学
• 游戏开发
• 3D渲染

Babylon.js 在packages/tools目录下维护了一套基于 Model Context Protocol（MCP）的工具包，将 Node Material、Flow Graph、GUI、Node Geometry、Node Render Graph、Node Particle 与 Smart Filters 等创作子系统逐一封装为可被 MCP 兼容客户端（AI 助手、编辑器、自动化管线）直接调用的服务器。本文以仓库内的 packages/tools/README.md 为主线，结合各子包 README 与源码，系统讲解这套 MCP 工具族的架构分工、通用工作流、共享约定、构建方式与已知边界，读完后你将清楚掌握如何把 Babylon.js 的图形化创作能力接入任何 MCP 生态。

一、目录定位：MCP 工具族在仓库中的位置

packages/tools是 Babylon.js 官方开发工具集散地，包含编辑器（nodeEditor、guiEditor、flowGraphEditor、playground 等）、解码器（ktx2Decoder）、测试工具与若干 MCP 服务器。其中MCP（Model Context Protocol）工具族专门负责把 Babylon.js 的创作工作流暴露给 MCP 兼容客户端：

This directory contains the Babylon.js Model Context Protocol tooling packages used to expose Babylon.js authoring workflows to MCP-compatible clients.

这意味着 AI 助手可以绕过 GUI，通过标准化的工具调用（tool call）来创建、编辑、校验和导出各类 Babylon.js 图结构。这是将「可视化节点编辑器」能力转化为「程序化可调用的 API 面」的核心工程。

二、包族谱：8 个包的职责分工

MCP 工具族目前由 8 个包组成，职责如下（引自 packages/tools/README.md 的 Packages 表格）：

1. mcp-server-core：所有服务器的公共底座

mcp-server-core不是独立的 MCP 服务器，而是被其余服务器入口共同消费的基础设施（见 packages/tools/mcp-server-core/README.md）。其核心能力包括：

• 文本交接助手：内联 JSON 与文件型 JSON 输入的统一解析（textHandoff.ts）
• 共享 JSON 解析与输入校验助手（jsonValidation.ts、inputValidation.ts）
• 通用 MCP 文本响应构造器（response.ts）
• 共享的 JSON 导入/导出/snippet 响应助手（jsonToolResponses.ts）
• 供多个工具复用的 Zod 字段级 schema 片段（toolSchemas.ts）
• Scene 专属的 schema 分组与附件校验（sceneToolSchemas.ts、sceneAttachmentValidation.ts）
• 浏览器安全的 WebMCP 注册、生命周期与写者仲裁助手（webMcp.ts）

服务器包通过入口从该包复用 MCP 样板代码，典型用法如下：

import { CreateJsonExportResponse, CreateJsonImportResponse, CreateOutputFileSchema, CreateJsonFileSchema } from "../../mcp-server-core/dist/index.js";

这样既能集中维护重复的处理器逻辑，又能保留各包本地的工具定义。其单元测试位于 packages/tools/mcp-server-core/test/unit，覆盖输入校验、JSON 工具响应、场景附件校验等关键行为。

2. nme-mcp-server：Node Material 图创作

该服务器面向 AI 驱动的 Node Material 创作（README），提供：

• 创建、检查、删除内存中的 Node Material 图
• 添加 block、连接端口、更新 block 属性
• 导入/导出 NME JSON
• 从 Babylon.js snippet 导入、保存到 snippet
• 可选的 Node Material Editor 实时会话桥接

其二进制入口为babylonjs-node-material。相关源码结构：src/index.ts（MCP 工具注册）、src/materialGraph.ts（内存图管理器）、src/sessionServer.ts（可选会话桥）。

3. flow-graph-mcp-server：Flow Graph 创作

面向 Flow Graph（行为/逻辑图）创作（README），提供：

• 创建、检查、校验、删除 flow graph
• 添加 block，连接数据端口（data）与信号端口（signal）
• 更新 block 属性与上下文变量
• 导出协调器 JSON 或纯图 JSON
• 导入此前导出的 flow graph JSON

二进制入口为babylonjs-flow-graph。源码结构：src/index.ts（工具注册）、src/flowGraphManager.ts（图管理与导入导出）、src/blockRegistry.ts（block 目录）。

4. gui-mcp-server：GUI 布局创作

面向 Babylon.js GUI 布局创作（README），提供：

• 在内存中创建和管理 GUI 与控件
• 添加控件、重设父级、更新控件属性
• 管理 Grid 的行与列
• 检查 GUI/控件结构
• 导出/导入 Babylon.js GUI JSON
• 从 snippet 导入、保存到 snippet

二进制入口为babylonjs-gui。源码结构：src/index.ts（工具注册）、src/guiManager.ts（GUI 状态与序列化）、src/catalog.ts（控件目录与共享属性元数据）。

5. nge-mcp-server：Node Geometry 图创作

面向 Node Geometry 创作（README），提供：

• 创建和管理内存中的 Node Geometry 图
• 添加 block、连接端口、设置 block 属性
• 检查图结构并校验几何图
• 导出/导入 NGE JSON
• 从 snippet 导入、保存到 snippet

二进制入口为babylonjs-node-geometry。值得注意的是，该服务器的图管理器与 block 目录被抽到了跨包共享的ngeMcpCommon中（浏览器安全复用），包括 geometryGraph.ts（共享图管理器与序列化逻辑）、blockRegistry.ts（共享 block 目录）、referenceData.ts（枚举与概念参考数据）。

6. nrge-mcp-server：Node Render Graph 创作

面向 Node Render Graph 创作（README），提供：

• 创建和管理自定义渲染图
• 添加渲染图 block、连接端口、设置属性
• 检查图结构并校验输出管线
• 导出/导入 NRGE 兼容 JSON
• 从 snippet 导入、保存到 snippet

二进制入口为babylonjs-node-render-graph。实践中，一个可用渲染图通常包含输入 block、渲染或后处理 block，以及输出 block。源码结构：src/index.ts（工具注册）、src/renderGraph.ts（图管理与导入导出）、src/blockRegistry.ts（block 目录）。

7. npe-mcp-server：Node Particle 创作

面向 Node Particle（粒子系统图）创作（README），提供：

• 创建和管理内存中的粒子图组
• 添加 block、连接端口、更新 block 属性
• 检查并校验粒子系统
• 导出/导入 NPE 兼容 JSON
• 从 snippet 导入、保存到 snippet

二进制入口为babylonjs-node-particle。大多数粒子图以SystemBlock结尾，导出前必须连接其强制输入。源码结构：src/index.ts（工具注册）、src/particleGraph.ts（图管理与校验）、src/blockRegistry.ts（block 目录）。

8. smart-filters-mcp-server：Smart Filters 后处理链创作

Smart Filters 服务器是包族中最「标准」的 MCP 服务器（README），可让 MCP 客户端完全通过工具调用构建 Smart Filter 后处理链，无需 GUI。其二进制入口为babylonjs-smart-filters。它提供了完整的工具分类：

它还暴露了 MCP 资源（Resource）与提示词（Prompt）：

• 资源：smart-filters://block-catalog（完整 block 类型目录）、smart-filters://enums（ConnectionPointType 枚举参考）、smart-filters://concepts（核心概念）
• 提示词：create-basic-filter（单效果滤镜链）、create-blur-filter（可配置尺寸的模糊滤镜）、create-tinted-desaturate（去饱和 + 色调合成）

可用 block 类型覆盖 Effects（BlackAndWhiteBlock、BlurBlock、DirectionalBlurBlock、PosterizeBlock、DesaturateBlock、ContrastBlock、PixelateBlock 等）、Transitions（CompositionBlock、TintBlock、WipeBlock）、Inputs（Float、Color3、Color4、Texture、Vector2、Boolean），以及自动随新图创建的 OutputBlock。

三、架构设计：这些包如何协同

按 packages/tools/README.md 的说明，MCP 包被组织为专门的图或创作服务器，每个服务器在内存中管理 Babylon.js 的一个子系统，并且都能独立完成创建、编辑、校验与导出自己的图格式：

• 每个服务器维护一份内存中的图/文档状态，不依赖持久化存储；
• 各服务器之间通过JSON 格式解耦：导出方产出标准 JSON，消费方（未来的 Scene MCP）读取 JSON；
• 未来的 Scene MCP 服务器将扮演编排者（orchestrator），消费这些服务器导出的 JSON，把它们组装成可运行的场景。

各子包 README 也印证了这一点：NME JSON 通过add_material交给 Scene MCP（内联或经nmeJsonFile）；Flow Graph 的协调器 JSON 通过attach_flow_graph附加（内联或经coordinatorJsonFile）；GUI JSON 经attach_gui附加（内联或guiJsonFile）；NGE JSON 经add_node_geometry_mesh生成网格（内联或ngeJsonFile）；NRGE JSON 经attach_node_render_graph附加（内联或nrgJsonFile）。这种「生产-导出-装配」的分层设计，让 AI 助手可以先分域构建各子系统，再汇聚成完整场景。

四、典型工作流：五步通用模式

所有服务器遵循相同的通用模式（引自 packages/tools/README.md）：

1. Create a graph/document in memory 2. Add blocks/controls/nodes and configure them 3. Connect ports or set properties 4. Validate the graph 5. Export to JSON (inline or to a file via outputFile)

各子系统的具体调用链如下：

• NME：create_material -> add_block -> connect_blocks -> set_block_properties -> validate_material -> export_material_json
• Flow Graph：create_graph -> add_block -> connect_data/connect_signal -> set_block_properties -> validate_graph -> export_graph_json
• GUI：create_gui -> add_control -> set_properties -> describe_gui -> export_gui_json（Grid 布局通常在添加子控件前先做行列管理）
• NGE：create_geometry -> add_block -> connect_blocks -> set_block_properties -> validate_geometry -> export_geometry_json
• NRGE：create_render_graph -> add_block -> connect_blocks -> set_block_properties -> validate_graph -> export_graph_json
• NPE：create_particle_system -> add_block -> connect_blocks -> set_block_properties -> validate_particle_system -> export_particle_system_json

带参数的完整示例：Smart Filters

Smart Filters 服务器给出了最详尽的带参数示例（README），展示如何构建「纹理输入 → 黑白 → 合成 → 输出」的完整滤镜链：

1. create_filter_graph name="myFilter" 2. add_block graphId="myFilter" blockType="Texture" name="source" 3. add_block graphId="myFilter" blockType="BlackAndWhiteBlock" name="bw" 4. connect_blocks graphId="myFilter" outputBlockId=<source.id> outputName="output" inputBlockId=<bw.id> inputName="input" 5. connect_blocks graphId="myFilter" outputBlockId=<bw.id> outputName="output" inputBlockId=1 inputName="input" 6. validate_graph graphId="myFilter" 7. export_filter_graph_json graphId="myFilter" outputFile="myFilter.json"

该服务器导出的 JSON 遵循Smart Filter V1 序列化格式：

{ "format": "smartFilter", "formatVersion": 1, "name": "myFilter", "blocks": [ ... ], "connections": [ ... ] }

五、共享约定：跨服务器的参数一致性

为保证 MCP 客户端能用同一套心智模型操作不同子系统，packages/tools/README.md 明确列出了共享约定：

• JSON 导出工具普遍支持outputFile（把结果写到文件）；
• JSON 导入工具普遍支持json（内联 JSON 字符串）与jsonFile（指向本地 JSON 文件）；
• 启用 snippet 的服务器普遍支持snippetId（从 Babylon.js snippet 服务器读取或保存）；
• 共享的 schema、校验与响应助手集中在mcp-server-core中。

这套约定保证了「内联 vs 文件交接」两种输入方式在各服务器间的行为一致，也解释了为什么textHandoff.ts（内联/文件输入解析与文件写出）会被抽为公共模块。

六、构建与运行：开发工作流

绝大多数 MCP 服务器支持相同的开发命令（packages/tools/README.md）：

npm run build -w @tools/<package-name> npm run start -w @tools/<package-name>

以 nme 服务器为例，包名为@tools/nme-mcp-server：

npm run build -w @tools/nme-mcp-server npm run start -w @tools/nme-mcp-server

对应的二进制：

babylonjs-node-material babylonjs-flow-graph babylonjs-gui babylonjs-node-geometry babylonjs-node-render-graph babylonjs-node-particle babylonjs-smart-filters

Rollup 打包实现

MCP 服务器统一使用 Rollup 构建，并消费@tools/mcp-server-core的共享助手（packages/tools/README.md）。共享的 Rollup 配置位于 packages/tools/rollup.config.mcp.mjs：每个服务器调用createConfig("./src/index.ts")，产出单文件、自包含、经 esbuild 压缩的 ESM 包（dist/index.js），除 Node 内置模块外无外部依赖。配置细节包括：

• 保留#!/usr/bin/env nodeshebang，保证npx/ bin 直接调用可用；
• 剥离源码内多余 shebang，避免与 banner 冲突；
• 用zodV3CompatAlias将zod/v3兼容导入别名到已安装的 zod 包；
• 对node_modules内 zod 相关的循环依赖警告做白名单过滤；
• monaco-editor保持 external（snippet-loader 对 playground 转译的懒加载路径在 MCP 服务器中不会被触发，因为服务器只加载数据型 snippet）。

以 nme-mcp-server/package.json 为例，服务器依赖@modelcontextprotocol/sdk、@tools/mcp-server-core、@tools/snippet-loader与zod，脚本含clean（rimraf dist）、build（rollup -c）、start（node dist/index.js）、dev（tsc --watch）。

Workspace 级 MCP 配置

packages/tools/README.md 说明：workspace 级别的 MCP 服务器命令映射位于仓库根目录的.vscode/mcp.json，在本地从 VS Code 或其他 MCP 客户端测试服务器时非常有用。需要留意的是，在当前这份只读检出中并未包含该文件，因此若要在本地实验，需要按你的客户端约定自行创建该配置文件，将上述二进制命令映射到对应工具/服务器。

七、测试与质量保障

公共底座mcp-server-core提供了覆盖全面的单元测试（packages/tools/mcp-server-core/test/unit），运行方式：

npx jest packages/tools/mcp-server-core/test/unit --runInBand

测试覆盖editorSessionServer、inputValidation、jsonToolResponses、jsonValidation、response、sceneAttachmentValidation、sceneToolSchemas、textHandoff、toolSchemas与webMcp等模块，从输入校验到响应塑形再到场景附件契约，均有自动化验证。

八、已知限制与演进方向

作为对 README 的补充，当前 MCP 工具族存在明确的边界（以 smart-filters-mcp-server/README.md 为例）：

• 无 snippet 集成：Smart Filters 服务器暂不支持从 Babylon.js snippet 服务器存取；
• 无运行时钩子：export_runtime_descriptor与validate_against_runtime被推迟（需要 Babylon.js 引擎依赖）；
• 无实时预览：服务器基于内存模型工作，实时预览需要运行中的 Babylon.js 场景。

在更大的演进方向上，mcp-server-core的 WEBMCP_MIGRATION_PLAN.md 描述了为 Babylon.js 浏览器编辑器增加WebMCP的分阶段架构与推广计划，即在保留现有 MCP 服务器与编辑器会话的前提下，把 MCP 能力下沉到浏览器端；webMcp.ts模块（通过@tools/mcp-server-core/webMcp浏览器入口导出）已经提供浏览器安全的 WebMCP 类型、注册、特性检测与写者仲裁。而 README 中预告的Scene MCP 服务器作为编排者角色，将把这些服务器产出的 JSON 最终组装为可运行场景——这构成了整套工具族「分域创作 → JSON 交换 → 统一装配」的完整闭环。

小结

Babylon.js MCP Tools 是一套分工清晰、约定统一的创作型 MCP 服务器族：mcp-server-core沉淀公共能力，7 个专业服务器各自负责一个图/布局子系统，统一遵循「创建 → 添加 → 连接/配置 → 校验 → 导出」的五步模型，并通过outputFile、json/jsonFile、snippetId等共享约定保持参数面一致。配合 Rollup 单文件打包、jest 单元测试与未来的 WebMCP / Scene MCP 演进，这套基础设施为 AI 驱动的 Babylon.js 全栈创作提供了可直接接入的标准化入口。

• 图形学
• 游戏开发
• 3D渲染