x3d MCP

x3d mcp

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 
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上）。

工具

验证

规格查找

场景生成

文件操作

场景操纵

语义验证

动画与互动

提示

常见工作流

构建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场景：

关键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

发展

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

uv sync --group dev

运行测试套件：

uv run pytest

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

添加新工具

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