使用说明

x3d mcp

该项目已被Web3D联盟采纳。 发展仍在继续 Web3DConsortium/x3d_mcp，X3D下的官方MCP服务器人工智能与X3D特别兴趣小组。此存储库作为原始实现保留，并用于发布。

MCP服务器，使AI模型能够验证、查找、生成、分析和呈现三维组件内容。

X3D（可扩展3D图形）是用于以XML表示3D场景和对象的ISO标准（ISO/IEC 19775）。这模型上下文协议（MCP）是一个允许AI模型调用外部工具的标准。该服务器连接了这两者：它公开了24个工具和4个工作流提示，让AI使用权威的规范数据而不是训练数据猜测来使用X3D，生成模式有效输出，为其设置动画，并在浏览器中渲染。

特性

验证 --根据官方X3D 4.0 XML模式（26000+行XSD）验证X3D内容，捕获无效节点、错误属性类型和层次结构违规
语义检查 --捕捉XSD无法捕捉的真实世界创作错误：形状上缺少几何体、空分组节点、DEF/USE引用损坏、DEF名称重复、字段无效或类型不匹配的ROUTE以及缺少视点
规格查找 --查询完整的X3D统一对象模型：200多个具体节点、带约束的字段类型、继承链、组件/配置文件浏览和父子层次结构检查。节点和字段描述在启动时通过人类可读的创作指南——提示和警告——得到了丰富，这些指南来源于官方的X3D Edit工具提示配置文件(x3d-4.0.profile.xml)
场景生成 --通过官方的X3D.py库（X3DPSAIL）以编程方式创建X3D内容，使用目标节点插入操作场景，并转换为独立的X3DOM HTML页面以供浏览器渲染
场景操纵 --在现有场景上完成CRUD操作：修改DEF节点上的字段值，按DEF或类型+索引删除节点，并使用循环检测重新分配节点
动画与互动 --根据目标DEF和字段名称自动生成完整的TimeSensor+Interpolator+ROUTE链（根据字段的类型选择正确的插值器），通过完整的类型/访问类型检查验证和插入单个ROUTE，并查找动画参考文档
文件操作 --将现有的X3D场景解析为可读的树视图，按类型和组件获取节点统计信息，列出所有命名（DEF）节点，并提取特定的节点子树
引导式工作流程 --MCP提示执行常见的多步骤任务：从头开始构建场景、审核现有文件、设置场景动画以及转换为X3DOM

快速入门

先决条件： Python 3.12+，紫外线

git clone <repo-url>
cd x3d-mcp
uv sync

服务器使用stdio传输，设计为由MCP客户端启动（见下面的配置），而不是独立运行。要验证它是否正确启动：

uv run python server.py

MCP检查员

您可以使用MCP检查器交互式地测试服务器，该检查器与 mcp[cli] 附属国：

uv run mcp dev server.py

这将打开一个web UI，您可以在其中调用每个工具，查看输入模式并检查响应。

MCP客户端配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "x3d": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/absolute/path/to/x3d-mcp"
    }
  }
}

光标

添加 .cursor/mcp.json 在您的项目根目录中。使用 uv run --directory 指向x3d mcp项目（这比 cwd，尤其是包含空格的路径）：

{
  "mcpServers": {
    "x3d": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/x3d-mcp", "python", "server.py"]
    }
  }
}

替换 /absolute/path/to/x3d-mcp 以及此存储库的实际路径。如果光标找不到 uv使用完整路径（例如。， /opt/homebrew/bin/uv 在macOS上）。

工具

验证

工具	参数	说明
`validate_x3d`	`x3d_xml` （string）	根据X3D 4.0模式验证X3D XML字符串
`validate_x3d_file_tool`	`filepath` （string）	验证 `.x3d` 磁盘上的文件

规格查找

工具	参数	说明
`x3d_node_info`	`node_name` （string）	获取节点的完整规范信息：字段、类型、默认值、约束、继承
`x3d_search_nodes`	`query` （string）	按名称或描述搜索节点
`x3d_list_components`	`component_name` （字符串，可选）	列出所有组件或特定组件中的所有节点
`x3d_list_profiles`	--	列出所有X3D配置文件及其说明
`x3d_field_type_info`	`field_type` （string）	解释字段类型（例如。 `SFVec3f`)或枚举类型
`x3d_check_hierarchy`	`parent_node`, `child_node` （string）	检查父子节点关系是否有效

场景生成

工具	参数	说明
`x3d_scene_template`	`profile`, `title`, `include_viewpoint`, `include_light`	生成完整有效的X3D场景模板
`x3d_generate_node`	`node_name`, `fields` （JSON字符串）	生成单个X3D节点XML片段
`x3d_add_node`	`scene_xml`, `node_xml`, `parent_def`	将节点插入到现有场景中
`x3dom_page`	`x3d_content`, `title`, `width`, `height`, `show_stats`, `show_log`	将X3D内容包装在独立的X3DOM HTML页面中
`x3dom_starter`	--	生成一个带有示例场景的可打开X3DOM页面

文件操作

工具	参数	说明
`x3d_parse_scene`	`x3d_source` （文件路径或XML字符串）	将场景图解析并显示为缩进树
`x3d_scene_stats`	`x3d_source`	获取统计数据：按类型和X3D组件统计节点数
`x3d_list_defs`	`x3d_source`	列出所有具有父/子上下文的DEF（命名）节点
`x3d_extract_node`	`x3d_source`, `def_name`, `node_type`, `index`	将特定的节点子树提取为XML

场景操纵

工具	参数	说明
`x3d_modify_node`	`x3d_source`, `def_name`, `field_changes` （JSON字符串）	更新DEF节点上的属性值
`x3d_remove_node`	`x3d_source`, `def_name`, `node_type`, `index`	按DEF或按类型+索引删除节点（及其子节点）
`x3d_move_node`	`x3d_source`, `def_name`, `new_parent_def`	将节点修复给新的父节点（或 `<Scene>` 根）；检测循环

语义验证

工具	参数	说明
`x3d_semantic_check`	`x3d_source`	运行XSD之外的创作检查：形状完整性、空组、重复的DEF、损坏的USE引用、路由有效性（DEF引用+字段名+访问类型+类型匹配）、缺少视点

动画与互动

工具	参数	说明
`x3d_animate`	`x3d_source`, `target_def`, `field_name`, `from_value`, `to_value`, `duration`, `loop`	为目标字段生成完整的动画链（时间传感器+正确的插值器+2个ROUTE），并将其插入场景中
`x3d_route`	`x3d_source`, `from_node`, `from_field`, `to_node`, `to_field`	验证（DEF存在、字段存在、accessType兼容性、类型匹配）并插入ROUTE语句
`x3d_animation_info`	`topic` （可选： `interpolators`, `timesensor`, `routes`, `examples`)	X3D事件驱动动画系统的参考文档

提示

提示	参数	说明
`build_scene`	`description` （可选）	从头开始构建X3D场景的分步指南
`audit_scene`	`filepath` （可选）	分析和审核现有X3D文件的指南（现在包括语义检查步骤）
`convert_to_x3dom`	--	将X3D内容转换为浏览器可查看的HTML页面的指南
`animate_scene`	`target_description` （可选）	向X3D场景添加动画的分步指南

常见工作流

构建3D场景

1. x3d_scene_template(profile="Interchange", title="My Scene")
2. x3d_node_info("Sphere")                          -- check available fields
3. x3d_generate_node("Sphere", '{"radius": 2.5}')   -- create geometry
4. x3d_add_node(scene_xml, node_xml)                 -- insert into scene
5. validate_x3d(scene_xml)                           -- verify against schema
6. x3dom_page(scene_xml, title="My Scene")           -- render in browser

审核现有的X3D文件

1. x3d_parse_scene("/path/to/model.x3d")          -- see the scene graph tree
2. x3d_scene_stats("/path/to/model.x3d")          -- get node counts by type/component
3. x3d_list_defs("/path/to/model.x3d")            -- list all named nodes
4. validate_x3d_file_tool("/path/to/model.x3d")   -- check schema compliance
5. x3d_semantic_check("/path/to/model.x3d")       -- catch authoring bugs (broken ROUTEs, etc.)
6. x3d_extract_node("/path/to/model.x3d", def_name="SomeNode")  -- inspect specific nodes

修改现有场景并设置动画

1. x3d_list_defs(scene_xml)                       -- find DEF names to target
2. x3d_modify_node(scene_xml, "RedMat",
                   '{"diffuseColor": "0 1 0"}')   -- recolor a material
3. x3d_animation_info("interpolators")            -- reference: which interp matches the field
4. x3d_animate(scene_xml, target_def="MyTransform",
               field_name="rotation",
               from_value="0 1 0 0",
               to_value="0 1 0 6.283",
               duration=4.0, loop=True)           -- spin a transform around Y
5. x3d_semantic_check(scene_xml)                  -- verify ROUTEs are correctly wired
6. x3dom_page(scene_xml, title="Animated")        -- render in browser

示例：X3D输入/输出

带有红色球体的最小X3D场景：

<?xml version="1.0" encoding="UTF-8"?>
<X3D profile="Interchange" version="4.0">
  <Scene>
    <Viewpoint description="Front" position="0 0 10"/>
    <Shape>
      <Appearance>
        <Material diffuseColor="1 0 0"/>
      </Appearance>
      <Sphere radius="2"/>
    </Shape>
  </Scene>
</X3D>

关键X3D图案：

形状 =外观（材质+可选纹理）+几何形状（长方体、球体、圆柱体等）
变换用平移、旋转和缩放来包装儿童
DEF/USE 名称允许您定义一次节点并重用它
SF颜色 在[0,1]范围内有3个浮点数（例如。， 1 0 0 =红色）
S旋转 是轴角： x y z angle_in_radians

建筑

flowchart TD
    Server["server.py\n24 MCP tools + 4 prompts"] --> Validation["src/validation.py\nxmlschema"]
    Server --> SpecLookup["src/spec_lookup.py\nquery functions"]
    Server --> Generation["src/generation.py\nx3d.py + lxml"]
    Server --> FileOps["src/file_ops.py\nparse + analyze"]
    Server --> SceneOps["src/scene_manipulation.py\nmodify / remove / move"]
    Server --> Semantic["src/semantic_check.py\nauthoring checks"]
    Server --> Animation["src/animation.py\nTimeSensor + Interp + ROUTE"]

    SpecLookup --> X3DUOM["src/x3duom_loader.py\nin-memory index"]
    FileOps --> X3DUOM
    Semantic --> X3DUOM
    Animation --> X3DUOM

    SceneOps --> FileOps
    Semantic --> FileOps
    Animation --> FileOps

    Validation --> XSD["spec/x3d-4.0.xsd"]
    X3DUOM --> UOM["spec/X3dUnifiedObjectModel-4.0.xml"]
    X3DUOM --> Tooltips["src/tooltip_loader.py\ntooltip enrichment"]
    Tooltips --> Profile["wiki/x3d-4.0.profile.xml\nX3D-Edit authoring profile"]

    Generation --> Validation

文件	角色
`server.py`	MCP入口点。注册所有24个工具和4个提示 `FastMCP` 并运行stdio传输。
`src/validation.py`	通过以下方式加载X3D 4.0 XSD `xmlschema`，剥离命名空间/DOCTYPE处理指令，并验证XML字符串或文件。
`src/x3duom_loader.py`	将43000行X3DUOM XML解析到内存字典中。解析完整继承链以收集任何节点的所有字段。加载时调用 `tooltip_loader` 以覆盖更丰富的描述。辛格尔顿通过 `lru_cache`.
`src/tooltip_loader.py`	解析 `wiki/x3d-4.0.profile.xml` （X3D编辑创作配置文件）和每个节点和每个字段的工具提示文本索引，包括人类可读的描述、创作提示和Web3D联盟的警告。启动时合并到X3DUOM索引中。
`src/spec_lookup.py`	X3DUOM索引上的查询层：节点信息、搜索、组件/配置文件列表、字段类型文档、具有继承感知类型匹配的层次结构检查。
`src/generation.py`	通过官方的X3D.py（X3DPSAIL）库构建X3D节点，使用lxml操纵场景树，并将X3D XML转换为X3DOM兼容的HTML（小写标签、显式结束标签、命名空间剥离）。
`src/file_ops.py`	读取并分析现有的X3D内容：场景图树视图、按类型/组件统计、DEF节点列表和节点提取。暴露 `parse_x3d_source` 和 `find_scene` 作为操纵、语义和动画模块使用的共享解析基础。
`src/scene_manipulation.py`	完成X3D场景的CRUD循环：修改DEF节点上的字段值，按DEF或类型+索引删除节点，并使用循环检测重新分配节点。
`src/semantic_check.py`	XSD之外的编写级别检查：形状完整性、空分组节点、重复DEF、DEF/USE一致性、路由有效性（DEF引用+字段名+访问类型+类型匹配）和缺少视点。
`src/animation.py`	自动生成用于动画的TimeSensor+Interpolator+ROUTE链（通过X3DUOM查找从目标字段的类型中选择正确的插值器），验证并插入单个ROUTE，并为X3D的事件驱动动画系统提供参考文档。
`spec/`	捆绑的官方规范文件：X3D 4.0 XSD（带Web3D扩展模式）和X3D统一对象模型XML。
`wiki/x3d-4.0.profile.xml`	X3D编辑Web3D联盟（Don Brutzman）的创作配置文件。包含每个X3D 4.0节点和属性的丰富工具提示文本，供 `tooltip_loader.py` 以丰富规范查找输出。

发展

安装所有依赖项，包括开发工具：

uv sync --group dev

运行测试套件：

uv run pytest

目前，在七个测试文件中有171个测试：

测试文件	计数	封面
`tests/test_validation.py`	8	有效/无效文档的模式验证、XSI属性剥离、文件处理、边缘情况
`tests/test_spec_lookup.py`	31	X3DUOM加载、节点信息、搜索、组件、配置文件、字段类型、层次结构检查
`tests/test_generation.py`	26	场景模板、节点生成、场景合成、X3DOM页面输出、HTML转义
`tests/test_file_ops.py`	36	场景解析、统计、DEF列表、节点提取、文件路径处理
`tests/test_scene_manipulation.py`	26	修改、删除和移动节点；循环检测；往返模式验证
`tests/test_semantic_check.py`	19	形状完整性、空组、重复DEF、DEF/USE一致性、路线有效性、缺少视点
`tests/test_animation.py`	25	用于旋转/平移/颜色/标量场的动画链生成、路由验证、动画参考文档

添加新工具

在适当的地方实现该功能 src/ 模块
在中注册 server.py 随着 @mcp.tool() 装饰器
编写一个详细的文档字符串——AI模型将其视为工具描述
在相应的中添加测试 tests/test_*.py 文件