企业官网建设流程全解析

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

导读

@tools/nge-mcp-server是 Babylon.js 官方仓库中面向 AI Agent 的 MCP（Model Context Protocol）服务，它把 Babylon.js 的 Node Geometry（节点几何）创作能力封装成一组标准化的 MCP 工具，让 AI 或任意 MCP 客户端可以通过"创建图 → 加节点 → 连线 → 设属性 → 校验 → 导出"的方式，纯文本地构建可在运行时解析的程序化几何体。读完本文你将掌握：该服务的全部工具与资源清单、典型工作流、如何构建运行、导出 JSON 如何被 Scene MCP 消费，以及底层图管理器GeometryGraphManager的序列化与校验原理。

该服务属于 Babylon.js 官方 MCP 生态的一部分，与 Scene MCP、Node Geometry Editor 协作，覆盖"AI 自动生成几何图 → 图数据序列化为 NGE JSON → 编辑器或运行时消费"的完整链路。

服务定位：为 AI 代理提供的 Node Geometry 创作入口

在 Babylon.js 中，Node Geometry（NGE）是一种基于图的可视化程序化几何构建器：不再用代码逐个创建 Mesh，而是连接一个个带类型的"块"（Block），图在运行时求值生成网格顶点数据。而nge-mcp-server正是把这一套能力以 MCP 协议暴露给 AI 的桥梁。

从 src/index.ts 的实现看，该服务基于官方 MCP SDK 构建：

• McpServer注册名为babylonjs-node-geometry，版本1.0.0；
• 传输层使用标准StdioServerTransport（stdio 是本地工具服务器的标准 MCP 传输方式）；
• 全部几何数据托管在一个单例GeometryGraphManager中（见 ngeMcpCommon/src/geometryGraph.ts）；
• 同时挂载一个基于 SSE 的编辑器会话服务器（McpEditorSessionController，默认端口 3001），用于把图的变更实时推送给 Node Geometry Editor 的 MCP 会话面板。

服务暴露的能力在 README.md 中概括为六类：

典型工作流：一次完整的程序化几何创作管线

README 给出了最核心的调用链：

create_geometry -> add_block -> connect_blocks -> set_block_properties -> validate_geometry -> export_geometry_json

服务端在注册时把这条工作流固化进了 MCP 的instructions字段（见 src/index.ts），并附加两条铁律：

1. 每个几何图必须有一个GeometryOutputBlock（唯一输出节点），否则几何体无法构建；
2. 连线之前先用get_block_type_info查询端口的类型，避免接错。

服务内置的提示模板create-box-geometry（src/index.ts）给出了最小可运行示例的逐步指令，翻译为实际工具调用序列如下：

1. create_geometry with name 'MyBox' 2. Add BoxBlock named 'box' 3. Add GeometryOutputBlock named 'output' 4. Connect box.geometry → output.geometry 5. validate_geometry, then export_geometry_json

这一序列对应的内存图就是一个BoxBlock直连输出节点，导出的 JSON 与仓库自带的示例 examples/SimpleBox.json 完全一致：customType为BABYLON.NodeGeometry，两个 block（BoxBlockid=1、GeometryOutputBlockid=2），outputNodeId指向 2，连接关系记录在目标块输入的targetBlockId/targetConnectionName字段中，并附带编辑器布局数据editorData.locations。

构建与运行

README 指定了包管理命令与可执行二进制名：

二进制名（全局可执行文件）：

babylonjs-node-geometry

构建与启动：

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

对应 package.json 中的脚本：build执行rollup -c打包，start执行node dist/index.js启动，另有dev（tsc --watch）与clean（rimraf dist）脚本。该包是私有包（"private": true，版本1.0.0），依赖包括：

• @modelcontextprotocol/sdk：MCP 协议 SDK；
• @tools/mcp-server-core：通用 MCP 编辑器会话控制器（会话管理、SSE 通知、文件读写 schema 等）；
• @tools/nge-mcp-common：共享的浏览器安全的图管理器与块目录；
• @tools/snippet-loader：Snippet 服务加载/保存；
• zod：工具输入参数的运行时校验 schema。

启动时服务监听 stdio，AI Agent（或任何 MCP 客户端）通过标准输入输出与之通信；若调用create_geometry、get_session_url等工具，还会在本机起一个 SSE 会话服务（默认端口 3001），返回可在 Node Geometry Editor 的 MCP 会话面板中粘贴的 URL。

工具集深度剖析

在 src/index.ts 中共注册了 20 余个工具，可按下表分类使用：

属性设置：add_block/set_block_properties的 properties 契约

add_block的properties参数是键值对，不同块类型的合法键由 blockRegistry.ts 中的propertyMetadata约束，非法键会直接返回错误。常见类型：

• GeometryInputBlock：type（Int/Float/Vector2/Vector3/Vector4/Matrix）、contextualValue（None/Positions/Normals/UV/VertexID/FaceID 等）、value（常量值）、min/max（Inspector 滑杆范围）；
• MathBlock：operation（MathBlockOperations：0=Add、1=Subtract、2=Multiply、3=Divide、4=Max、5=Min）；
• BooleanGeometryBlock：operation（BooleanGeometryOperations：0=Intersect、1=Subtract、2=Union）；
• GeometryTrigonometryBlock：operation（GeometryTrigonometryBlockOperations：0=Cos、1=Sin、2=Abs、3=Exp、4=Round … 20=Exp2）；
• ConditionBlock：test（ConditionBlockTests：0=Equal、1=NotEqual、2=LessThan …）；
• 许多块支持evaluateContext（boolean），用于开启逐顶点求值（Set 类块默认开启）。

连线：connect_blocks的规则

connect_blocks需要四个参数：sourceBlockId、outputName、targetBlockId、inputName，数据从源输出流向目标输入。底层的GeometryGraphManager.connectBlocks（ngeMcpCommon/src/geometryGraph.ts）在建立连接前会做三重防护：

1. 端口存在性检查：输出/输入名不存在时报错并列出可用端口；
2. 类型兼容性检查：通过_getConnectionTypeError解析两端类型，不兼容则拒绝（例如 Vector3 不能接到只收 Float 的端口，除非端口声明了acceptedConnectionPointTypes）；
3. 环检测：通过_wouldCreateCycle做 BFS，若连接会形成回路则拒绝。

一个输入端口只能有一条连接，新连接会覆盖旧连接。disconnect_input则通过清除inputName/targetBlockId/targetConnectionName三个字段断开。

GeometryInputBlock 的两种模式

这是最容易出错也最关键的块。根据 referenceData.ts 中的NgeConceptsMarkdown：

模式一：上下文源（Contextual Source）。contextualValue取Positions、Normals、UV、VertexID等枚举值，块的输出类型由ContextualSourceToType映射自动推导：

模式二：常量值（Constant Value）。设置type为 Int/Float/Vector2/Vector3/Vector4/Matrix，再设value。值会被规范化：标量直接存为 number 且valueType="number"；{x,y}对象转为[x,y]（Vector2）、{x,y,z}转为[x,y,z]（Vector3）、{x,y,z,w}转为[x,y,z,w]（Vector4）；Matrix 类型的 number 会被替换为 16 元素单位矩阵。这些转换逻辑见_normaliseInputBlockValue/_ensureDefaultValue（ngeMcpCommon/src/geometryGraph.ts）。

如果既没设contextualValue（或为 None）也没设value，管理器会给出警告：该输入块不提供任何数据。

源块的尺寸端口：输入端口而非标量属性

一个高频陷阱：BoxBlock、SphereBlock、PlaneBlock等源块的尺寸参数（size、width、diameter、subdivisions等）都是可选的输入端口，不是标量属性。要覆盖默认值，必须新增一个GeometryInputBlock并连线：

GeometryInputBlock(Float, value=10) → PlaneBlock.size GeometryInputBlock(Float, value=0.5) → SphereBlock.diameter GeometryInputBlock(Int, value=64) → GridBlock.subdivisions

不需要自定义的尺寸端口可以完全不接，保留默认值。服务内置提示create-scattered-instances（src/index.ts）演示了完整用法：用PlaneBlock做底面、SphereBlock做实例、InstantiateOnFacesBlock做散布，并用三个GeometryInputBlock分别喂入面大小（Float 10）、球直径（Float 0.2）和实例数（Int 100）。

尾随空格陷阱：VectorConverterBlock / IntFloatConverterBlock

VectorConverterBlock的输入端口名带尾随空格（用于与同名输出区分），连线时必须原样保留：

• 输入：'xyzw '（Vector4）、'xyz '（Vector3）、'xy '/'zw '（Vector2）、'x '/'y '/'z '/'w '（Float）；
• 输出：'xyzw'、'xyz'、'xy'、'zw'、'x'、'y'、'z'、'w'（无空格）。

connect_blocks(sourceId, 'output', vectorConverterId, 'x ') # 输入带空格 connect_blocks(vectorConverterId, 'xyz', targetId, ...) # 输出不带空格

IntFloatConverterBlock遵循同样的模式（输入'float '、'int '；输出'float'、'int'）。内置提示create-deformed-terrain（src/index.ts）综合展示了这些块的组合：GridBlock+SetPositionsBlock+NoiseSampleBlock+VectorConverterBlock+CreateVector3Block+AddBlock+ComputeNormalsBlock构建噪声地形。

底层原理：GeometryGraphManager 如何工作

所有工具都落在一个无 Babylon.js 运行时依赖的纯 JSON 数据模型上（ngeMcpCommon/src/geometryGraph.ts）。其设计目标在文件头部注释中明确说明：MCP 服务必须保持轻量独立进程，因此直接操作与NodeGeometry.serialize()输出格式一致的 JSON 结构。

序列化格式

ISerializedGeometry顶层字段为：

• customType：固定BABYLON.NodeGeometry（导入校验的硬性条件，见ValidateNodeGeometryAttachmentPayload）；
• outputNodeId：唯一的输出块 ID；
• blocks：块数组，每个块含customType、id、name、inputs、outputs及块私有属性；
• editorData.locations：编辑器布局坐标（每块{blockId, x, y}）；
• comment：可选描述。

导出前的自动修复

exportJSON（ngeMcpCommon/src/geometryGraph.ts）在序列化前做最后一遍"安全化"：

1. 对GeometryInputBlock再次规范化值与默认值；
2. 从注册表补齐defaultSerializedProperties（如evaluateContext），这些字段是 Babylon 反序列化器所必需的，缺失可能导致构建期崩溃；
3. 把残余的字符串枚举值转成数字。

随后执行_layoutGraph：从输出节点出发做最长路径 BFS 分层，再按列用重心（barycenter）启发式排序，最终写入editorData.locations，列宽 340px、行高 180px，保证导出的图在编辑器中打开时排布美观（输入在左、输出在右）。

校验规则

validateGeometry（ngeMcpCommon/src/geometryGraph.ts）输出的问题以ERROR/WARNING前缀标记：

• 缺少GeometryOutputBlock或多个输出块 → ERROR；
• outputNodeId未设置、指向不存在块或非输出块 → ERROR；
• 必需输入未连接 → WARNING（如SetPositionsBlock.positions、GeometryOutputBlock.geometry）；
• 悬空引用（target 块或输出名不存在）→ ERROR / WARNING；
• 无上下文源也无常量值的GeometryInputBlock→ WARNING；
• 无任何连接的孤儿块 → WARNING。

isError标志由问题中是否存在ERROR决定，供 MCP 客户端判断调用是否失败。

资源（Resources）与提示（Prompts）

除工具外，服务还注册了三个只读 Markdown 资源，供 Agent 按需拉取参考数据：

• nge://block-catalog：由GetBlockCatalogSummary()生成的块目录摘要（ngeMcpCommon/src/blockRegistry.ts）；
• nge://enums：GetNgeEnumsReference()生成的完整枚举参考，覆盖NodeGeometryBlockConnectionPointTypes（Int=0x0001、Float=0x0002、Vector2=0x0004、Vector3=0x0008、Vector4=0x0010、Matrix=0x0020、Geometry=0x0040、Texture=0x0080、AutoDetect=0x0400、BasedOnInput=0x0800、Undefined=0x1000）、NodeGeometryContextualSources、MathBlockOperations、GeometryTrigonometryBlockOperations、ConditionBlockTests、BooleanGeometryOperations、RandomBlockLocks、Aggregations、GeometryEaseBlockTypes、MappingTypes（详见 referenceData.ts）；
• nge://concepts：NgeConceptsMarkdown，一页式概念手册（图结构、两种输入模式、源块、变换/合并/布尔/实例化/逐顶点修改、常见错误清单）。

三个内置提示模板则分别对应三档复杂度：create-box-geometry（最小盒子）、create-scattered-instances（面散布实例）、create-deformed-terrain（噪声地形）。

与 Scene MCP 的集成

README 明确指出导出 JSON 的消费路径：Scene MCP 服务通过add_node_geometry_mesh消费导出的 NGE JSON，既可以内联传入，也可以通过ngeJsonFile传入文件路径。

nge-mcp-server 导出 NGE JSON │ ▼ Scene MCP add_node_geometry_mesh（inline 或 ngeJsonFile） │ ▼ 运行时创建 Mesh（NodeGeometry.parseSerializedObject / Parse）

此外还有两条在线协作路径：get_snippet_url把 JSON base64 编码进 URL 片段生成https://nge.babylonjs.com/#...的编辑器直达链接（大图建议改用 Snippet 服务）；save_snippet把图保存到 Babylon.js Snippet Server，返回Snippet ID与版本号，之后可在编辑器中用 ID 加载，或通过import_from_snippet拉回内存继续编辑（import_from_snippet会校验 Snippet 类型必须是nodeGeometry，ID 格式形如"ABC123"或"ABC123#2"带版本）。

示例与测试验证

仓库在 examples 下提供了五个可直接导入的 NGE JSON 示例，覆盖不同复杂度：

• SimpleBox.json：单 BoxBlock 直连输出（最小图）；
• BooleanCSG.json：布尔（CSG）运算图；
• MathPipeline.json：数学管线图；
• NoiseTerrain.json：噪声地形图；
• ScatteredInstances.json：散布实例图。

单元测试位于 test/unit，其中 graphManager.test.ts 验证了：创建/导出盒子图后 JSON 结构合法（customType为BABYLON.NodeGeometry、所有连接引用存在的块 ID）、生命周期操作（create/list/delete）、contextualValue: "Positions"自动推导为数值 1 且类型推导为 Vector3（0x0008）、常量值规范化等行为。registryDrift.test.ts则检查块目录与真实 NGE 块实现的同步性，generateExamples.test.ts保证 examples 目录的示例可由图管理器重新生成。

相关文件索引

从源码结构可以推断，src/geometryGraph.ts与src/blockRegistry.ts是薄兼容层（re-export），真正的实现集中在@tools/nge-mcp-common包中，这样图管理与块目录逻辑可以被 MCP 服务端与其他工具（如编辑器）共享，同时保持"零 Babylon.js 运行时依赖"的轻量特性。实际投入使用时，建议让 AI Agent 先调用list_block_types/get_block_type_info建立对端口与属性的认知，再沿 README 给出的工作流逐步构建、反复validate_geometry，最后导出 JSON 交给 Scene MCP 落地为运行时网格。

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