内容
# x3d_mcp
[Extensible 3D (X3D) 图形](https://www.web3d.org/x3d/what-x3d) 是 Web 上发布、查看、打印和存档交互式 3D 模型的开放、免版税国际标准。X3D 进一步支持人形动画（HAnim）标准，该标准包括人类身体的清晰表示。 这些是强大的功能。
该开放项目为使用官方 X3D 国际标准开发的资产和工具提供了一个 [Model Context Protocol (MCP)](https://en.wikipedia.org/wiki/Model_Context_Protocol) 服务器，用于生成、验证和转换有效的 X3D 内容。
该项目支持 [Web3D 联盟](https://www.web3d.org) 的 [AI with X3D 特別兴趣小组](https://www.web3d.org/working-groups/ai-x3d)，融合了 [ricklentz/x3d_mcp](https://github.com/ricklentz/x3d_mcp) 和 [niknarra/x3d-mcp](https://github.com/niknarra/x3d-mcp) 的功能。除非另有说明，否则默认的开源许可证是 BSD 风格的 [Web3D 联盟开源许可证](https://www.web3d.org/license)。
## 概述
x3d_mcp 通过 Model Context Protocol (MCP) 向 LLMs 公开 X3D 功能。它使用 XML、JSON 和 ClassicVRML 编码生成符合规范的 X3D 场景，并针对 ISO/IEC 19775 标准进行全面验证。
LLM 对 3D 空间有空间和视觉理解。X3D（可扩展 3D）提供了一种声明式、基于 XML 的方法来表达这种理解，即有效的、可互操作的 3D 内容。该服务器连接了两者。
## 快速入门
**先决条件：** Python 3.12+、[uv](https://docs.astral.sh/uv/)、git
```bash
git clone https://github.com/Web3DConsortium/x3d_mcp.git
cd x3d_mcp
uv sync
```
要验证服务器是否正确启动：
```bash
uv run python src/server.py
```
服务器使用 stdio 传输，设计用于由 MCP 客户端启动，而不是单独运行。参见下面的客户端配置部分。
### MCP 检验
使用 MCP 检验（与 `mcp[cli]` 依赖捆绑）以交互方式测试服务器：
```bash
uv run mcp dev src/server.py
```
这将打开一个 Web 界面，您可以在其中调用每个工具，检查输入模式，并查看响应 — 在连接客户端之前验证您的设置非常有用。
## 客户端配置
### 克劳德桌面
添加到您的 `claude_desktop_config.json`：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"x3d": {
"command": "uv",
"args": ["run", "python", "src/server.py"],
"cwd": "/absolute/path/to/x3d_mcp"
}
}
}
```
将 `/absolute/path/to/x3d_mcp` 替换为存储库的实际路径。在保存后重启克劳德桌面。
### 克劳德代码
在终端中运行以下命令以全局注册服务器：
```bash
claude mcp add x3d -- uv run --directory /absolute/path/to/x3d_mcp python src/server.py
```
或手动将其添加到 `~/.claude/mcp.json`：
```json
{
"mcpServers": {
"x3d": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/x3d_mcp", "python", "src/server.py"]
}
}
}
```
### 光标
在项目根目录的 `.cursor/mcp.json` 中添加（如果文件不存在，请创建）：
```json
{
"mcpServers": {
"x3d": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/x3d_mcp", "python", "src/server.py"]
}
}
}
```
使用 `--directory` 比 `cwd` 更可靠，适用于包含空格的路径。如果光标找不到 `uv`，请使用其完整路径（例如 macOS 上的 `/opt/homebrew/bin/uv`）。
### 其他 MCP 客户端
任何支持 MCP stdio 传输的客户端都可以连接到此服务器。使用以下命令：
```bash
uv run --directory /absolute/path/to/x3d_mcp python src/server.py
```
## 设计决策
### 语言：Python
- **`x3d.py`** （PyPI `x3d` v4.0.65，BSD-3）-- 官方 Web3D 联盟软件包，从 X3DUOM 自动生成
- **`lxml`** -- XSD 和 ISO-Schematron 验证，比纯 Python 替代方案快 42 倍
- **`FastMCP`** （PyPI `mcp`）-- 官方 Anthropic MCP SDK，基于装饰器的工具注册
- 所有依赖项都使用 BSD/MIT 许可证。项目使用 [Web3D 联盟开源许可证](https://www.web3d.org/license)。
### 两种操作模式
**工作流模式** -- 适用于端到端场景生成的顶级工具。LLM 描述它想要的内容；服务器处理构造、验证和序列化。工具调用较少，可靠性较高。
**粒度模式** -- 适用于节点级场景构造的低级工具。LLM 逐步构建场景图：创建节点、设置字段、添加子节点、定义路由。完全控制复杂或迭代工作流。
两种模式在返回之前都会验证输出。
### JSON 转换
JSON 和 ClassicVRML 编码使用 `x3d.py` 的内置 `.JSON()` 和 `.VRML()` 序列化方法。这些方法从 X3DUOM 自动生成，直接生成符合规范的输出。Web3D 联盟的 `X3dToJson.xslt` 是 XSLT 2.0，与 lxml（XSLT 1.0 仅）不兼容，因此我们使用本机 Python 序列化。
### 验证管道
四层，匹配 X3D 规范的验证层次结构：
1. **生成时类型检查** -- `x3d.py` 在场景构造期间强制执行字段类型、范围和枚举。
2. **XSD 验证** -- `lxml.etree.XMLSchema` 针对 `x3d-4.1.xsd`（附带配套模式）。
3. **JSON 模式验证** -- `jsonschema.Draft202012Validator` 针对 `x3d-4.0-JSONSchema.json`（Web3D 联盟，364 `$defs`）。捕获拼写错误的键（`head`/`meta`/等）、`Scene` 内的未知节点名称、缺少必填字段（`encoding`、`@version`、`@profile`、`Scene`）、错误类型的值。Web3D 尚未发布 4.1 JSON 模式，因此在此期间捆绑 4.0 模式。
4. **语义检查** -- 针对 XSD 无法表达的作者级错误进行命令式 Python 检查：Shape 上缺少几何/外观、空分组节点、重复 DEF、USE/DEF 一致性、ROUTE 字段/访问类型/类型有效性、缺少视点。改编自 [niknarra/x3d-mcp](https://github.com/niknarra/x3d-mcp) （Nikhil Narra，Nicholas Polys -- Virginia Tech / Web3D 联盟）。
### X3DUOM 作为基础
`X3dUnifiedObjectModel-4.1.xml`（X3DUOM）是所有 265 个具体节点（4.1 中的 5 个新节点：EnvironmentLight、FontLibrary、HAnimPose、InlineGeometry、Tangent）、抽象类型、简单类型和语句的单一真实来源。在构建时解析以生成：
- 节点/字段元数据查找表
- 容器字段映射规则
- 枚举值集
- 默认值表
- 继承层次结构
## 架构
```
x3d_mcp/
src/
server.py # FastMCP 服务器，工具注册
tools/
workflow.py # 高级场景生成工具
granular.py # 低级节点操作工具
validate_tool.py # 验证 MCP 工具包装器
convert.py # 编码转换（XML、JSON、VRML）
query.py # 节点/字段元数据查询
render.py # X3DOM HTML 页面包装器，用于浏览器查看
scene_ops.py # 场景 CRUD：修改、删除、移动节点
animate.py # 动画链生成（TimeSensor + Interpolator + ROUTE）
prompts.py # 用于引导工作流的 MCP 提示
x3d_utils/
scene.py # 场景图状态管理
x3duom.py # X3DUOM 解析器，节点/字段元数据
validation/
validate.py # XSD + JSON 验证管道
semantic.py # 第 4 层语义检查（DEF/USE、ROUTE 有效性等）
schemas/ # 捆绑的 x3d-4.1.xsd、x3d-4.1.dtd、X3DUOM 4.1
dataset/
schema.py # 规范化训练示例模式
normalize.py # JSONL 模式规范化 CLI
validate_schema.py # JSONL 模式验证 CLI
augment.py # 可调增强管道 CLI
filter.py # 按来源和令牌预算过滤/分割数据集
generate.py # 数值序列示例生成器 CLI
generators/
numeric_sequences.py # 索引面集、挤出、插值器生成器
tests/
output/
logs/ # 每个问题的容器日志
docs/ # 研究和参考文档
Dockerfile
docker-compose.yml
pyproject.toml
README.md
```
## MCP 工具
### 工作流工具
| 工具 | 描述 |
|------|-------------|
| `create_scene` | 从自然语言描述中生成完整的 X3D 场景。返回请求编码（xml、json、vrml）的验证 X3D。 |
| `create_geometry` | 生成具有材质、变换和可选动画的单个几何对象。 |
| `compose_scene` | 将多个对象、光源、视点和背景组合成完整的场景。 |
### 粒度工具
| 工具 | 描述 |
|------|-------------|
| `create_node` | 按类型名称创建 X3D 节点。返回用于进一步操作的节点句柄。 |
| `set_field` | 在节点上设置字段值（具有类型验证）。 |
| `add_child` | 将子节点添加到父节点（验证容器字段规则）。 |
| `add_route` | 在两个节点字段之间创建 ROUTE（验证字段存在和类型兼容性）。 |
| `def_node` | 为节点分配 DEF 名称。 |
| `use_node` | 通过 USE 引用先前定义的节点。 |
| `remove_node` | 从场景图中删除节点。 |
| `get_scene` | 将当前场景状态序列化为 X3D（xml、json 或 vrml）。 |
| `reset_scene` | 清除所有节点并将场景重置为空状态。 |
### 验证工具
| 工具 | 描述 |
|------|-------------|
| `validate_x3d` | 验证 X3D 文档（XML 或 JSON）是否符合 XSD 模式。返回带有详细错误消息的通过/失败。 |
| `validate_current_scene` | 验证当前粒度场景是否符合 XSD 模式。 |
| `validate_semantic` | 对 X3D XML 进行语义检查，超出 XSD 范围：Shape 上缺少几何/外观、空分组节点、重复 DEF、USE/DEF 一致性、ROUTE 字段/访问类型/类型匹配有效性、缺少视点。返回降级报告。 |
### 转换工具
| 工具 | 描述 |
|------|-------------|
| `convert_x3d` | 在 X3D 编码之间转换：xml、json、vrml。使用 x3d.py 原生序列化。 |
### 查询工具
| 工具 | 描述 |
|------|-------------|
| `list_nodes` | 列出可用的 X3D 节点，可选地按组件过滤。 |
| `describe_node` | 获取节点的完整字段定义：字段名称、类型、默认值、范围、访问类型。 |
| `list_components` | 列出所有 X3D 组件及其支持级别。 |
| `list_profiles` | 列出可用的配置文件及其组件要求。 |
### 渲染工具
| 工具 | 描述 |
|------|-------------|
| `x3dom_page` | 将 X3D 内容（完整文档或场景片段）包装在独立的 X3DOM HTML 页面中，以便浏览器查看。降低标签/属性名称，剥离命名空间声明，从 CDN 嵌入 X3DOM 1.8.2。改编自 [niknarra/x3d-mcp](https://github.com/niknarra/x3d-mcp)。 |
| `x3dom_starter` | 返回具有小示例场景的启动 X3DOM HTML 页面。有用的作为已知良好的基准。 |
### 场景操作工具
对序列化 X3D 内容（文件路径或内联 XML）进行操作并返回修改后的文档。与粒度工具不同，粒度工具会改变内存中的 `SceneManager` 状态。
| 工具 | 描述 |
|------|-------------|
| `modify_x3d_node` | 更新 DEF 节点的属性值。字段更改作为 JSON 对象字符串传递。改编自 [niknarra/x3d-mcp](https://github.com/niknarra/x3d-mcp)。 |
| `remove_x3d_node` | 删除节点及其子节点。按 DEF 名称或节点类型加索引标识。 |
| `move_x3d_node` | 重新父节点 DEF 节点。空 `new_parent_def` 将其移动到场景根目录。拒绝可能创建循环的移动。 |
### 动画工具
在 X3D 内容中生成事件驱动的动画（TimeSensor + Interpolator + ROUTE 链）。改编自 [niknarra/x3d-mcp](https://github.com/niknarra/x3d-mcp)。
| 工具 | 描述 |
|------|-------------|
| `animate_x3d_node` | 为目标字段插入完整的动画链。自动从字段类型通过 X3DUOM 选择插值器（SFRotation -> OrientationInterpolator，SFVec3f -> PositionInterpolator，SFColor -> ColorInterpolator，SFFloat -> ScalarInterpolator 等）。 |
| `add_x3d_route` | 验证并插入单个 ROUTE 语句，具有完整的 DEF / 字段 / 访问类型 / 类型匹配检查。 |
| `x3d_animation_info` | X3D 动画系统参考文档。主题：`interpolators`、`timesensor`、`routes`、`examples`，或为空以获取概述。 |
## MCP 提示
引导多步骤工作流。提示引导 LLM 完成任务的正确工具序列，其中顺序很重要。改编自 [niknarra/x3d-mcp](https://github.com/niknarra/x3d-mcp)。
| 提示 | 参数 | 描述 |
|--------|----------|-------------|
| `build_scene` | `description` | 从头开始构建 X3D 场景的分步指南。涵盖工作流和粒度路径、验证和 X3DOM 渲染。 |
| `audit_scene` | `content` | 审计现有的 X3D 内容以查找模式和作者问题。遍历 `validate_x3d`、`validate_semantic`、`describe_node` 和场景 CRUD 工具。 |
| `animate_scene` | `target_description` | 添加动画。遍历 `x3d_animation_info`、`describe_node`、`animate_x3d_node`、验证和渲染。 |
| `convert_to_x3dom` | -- | 通过 `validate_x3d` 和 `x3dom_page` 将 X3D 内容转换为可浏览器查看的 X3DOM HTML 页面。 |
## 数据管道
用于为微调构建 X3D 训练数据的数据工具。
### 模式标准化
将混合类型元数据字段标准化为一致的模式：
```bash
python -m dataset.normalize input.jsonl output.jsonl --report
python -m dataset.validate_schema input.jsonl
```
### 增强
具有可配置指令多样性、X3D 变化和令牌预算的可调增强：
```bash
python -m dataset.augment base.jsonl augmented.jsonl \
--ratio 5 --seed 42 \
--instruction-diversity 0.5 \
--x3d-mutation 0.3 \
--max-tokens 8192
```
### 过滤
按来源（原始/增强）和令牌预算进行过滤：
```bash
python -m dataset.filter input.jsonl output.jsonl --source original --max-tokens 8192
```
### 数值序列生成
为目标长数值数组（IndexedFaceSet、Extrusion、Interpolator）生成训练示例：
```bash
python -m dataset.generate output.jsonl \
--type all --count 50 --complexity mixed \
--validate --seed 42
```
## X3D 标准参考
此服务器针对 **X3D 版本 4.1**（候选草案，基于 ISO/IEC 19775-1:2023 v4.0）。
### 支持的编码
| 编码 | 扩展名 | 规范 |
|----------|-----------|------|
| XML | `.x3d` | ISO/IEC 19776-1 |
| JSON | `.x3dj` | ISO/IEC 19776-5 |
| ClassicVRML | `.x3dv` | ISO/IEC 19776-2 |
### 配置文件
默认配置文件是 `Interchange`（静态几何、纹理、照明、导航）。当场景使用传感器、动画、脚本或高级组件时，自动升级到 `Immersive` 或 `Full`。
| 配置文件 | 用例 |
|---------|----------|
| 核心 | 最小基准 |
| 交换 | 资产共享、静态 3D 模型 |
| 交互式 | 用户交互、基本行为 |
| 沉浸式 | 传感器、动画、脚本、物理 |
| 完整 | 所有 |
| CAD 交换 | 工程/产品设计 |
### 关键组件（共 37 个）
Geometry3D、Shape、Grouping、Rendering、Lighting、Texturing、Navigation、EnvironmentalEffects、Interpolation、PointingDeviceSensor、EnvironmentalSensor、KeyDeviceSensor、EventUtilities、Sound、Text、Scripting、Shaders、NURBS、Geospatial、HAnim、CADGeometry、RigidBodyPhysics、ParticleSystems、VolumeRendering、Followers、Picking、Layering、Layout、Texturing3D、CubeMapTexturing、TextureProjection、Annotation、DIS、Core、Time、Networking、Geometry2D。
完整节点参考：[docs/x3d-node-reference.md](docs/x3d-node-reference.md)
## 依赖项
| 包 | 版本 | 用途 |
|---------|---------|---------|
| `mcp` | >=1.7 | MCP SDK（FastMCP） |
| `x3d` | >=4.0.65 | 官方 X3D 场景构造和类型验证 |
| `lxml` | >=6.0 | XSD 验证、Schematron 验证、XSLT 转换 |
| `xmlschema` | >=4.3 | 纯 Python XSD 验证（备用） |
| `jsonschema` | >=4.26 | X3D JSON 编码的 JSON 模式验证 |
## Docker
所有代码都位于主机上。只有在测试和验证时才使用 Docker。
```bash
docker compose up --build
```
容器挂载 `src/` 和 `tests/` 来自主机。日志写入 `output/logs/`。
## 参考文档
| 文档 | 描述 |
|----------|-------------|
| [docs/x3d-standard-overview.md](docs/x3d-standard-overview.md) | ISO 标准、场景图架构、配置文件、组件、字段类型、执行模型 |
| [docs/x3d-file-structure.md](docs/x3d-file-structure.md) | 最小有效文件（XML/JSON/VRML）、DOCTYPE 声明、编码规则、4 层验证 |
| [docs/x3d-node-reference.md](docs/x3d-node-reference.md) | 所有约 260 个节点按组件组织并描述 |
| [docs/x3d-examples.md](docs/x3d-examples.md) | 从 Hello World 到 PBR 和动画的代码模式。链接到 4142+ Web3D 示例场景 |
| [docs/x3d-tools-and-references.md](docs/x3d-tools-and-references.md) | 模式、DTD、X3DUOM、验证器、查看器、转换器、库的 URL |
| [docs/x3d-validation-strategy.md](docs/x3d-validation-strategy.md) | 验证方法：X3DUOM 解析、XSD、Schematron、容器字段规则 |
| [docs/ecosystem-research.md](docs/ecosystem-research.md) | 现有工具的调查、Python 与 TypeScript 分析、社区资源 |
## 外部参考
- X3D 规范（v4.1 草案）：https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/Architecture.html
- X3D 规范（v4.0）：https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-WD2/Part01/Architecture.html
- X3D 提示（HTML）：https://www.web3d.org/x3d/tooltips/X3dTooltips.html
- X3D 提示配置文件（XML）：https://www.web3d.org/x3d/tooltips/x3d-4.0.profile.xml
- X3D 示例存档：https://www.web3d.org/x3d/content/examples/X3dForAdvancedModeling/
- X3D 资源：https://www.web3d.org/x3d/content/examples/X3dResources.html
- X3D 模式和 DTD：https://www.web3d.org/specifications/
- X3D 统一对象模型：https://www.web3d.org/specifications/X3DUOM.html
- X3D Schematron 质量保证：https://www.web3d.org/x3d/tools/schematron/X3dSchematron.html
- X3D JSON 编码（19776-5）：https://www.web3d.org/documents/specifications/19776-5/V3.3/Part05/concepts.html
- x3d.py Python 包：https://www.web3d.org/x3d/stylesheets/python/python.html
- MCP 规范：https://modelcontextprotocol.io/specification/2025-11-25
- FastMCP 文档：https://gofastmcp.com/servers/tools
- Web3D 联盟：https://www.web3d.org
## 致谢
以下功能基于 Web3D 联盟和 X3D AI 工作组的 **Nikhil Narra**（[@niknarra](https://github.com/niknarra)）、**Nicholas Polys**（[@npolys](https://github.com/npolys)）和 **Don Brutzman**（[@brutzman](https://github.com/brutzman)）的指导意见采纳：
- **语义验证**（验证工具，管道的第 4 层）-- DEF/USE 一致性、ROUTE 有效性、形状完整性、空组检测、缺失视点建议
- **动画工具** -- TimeSensor + Interpolator + ROUTE 链自动生成、单个 ROUTE 插入并进行类型检查、动画参考文档
- **X3DOM 渲染** -- 用于浏览器预览的独立 HTML 页面包装器
- **场景 CRUD** -- 修改/删除/移动序列化 X3D 内容的操作，并进行循环检测
- **MCP 引导提示** -- `build_scene`、`audit_scene`、`animate_scene`、`convert_to_x3dom`
参考实现：[niknarra/x3d-mcp](https://github.com/niknarra/x3d-mcp)。相关已发表作品：
- Nikhil Narra, Anuj Marisetty, Nicholas Polys, 和 Ben Sandbrook. **X3Test：一种基于无头浏览器的自动性能基准测试框架，用于 X3D/X3DOM 场景。** *Proceedings of the 30th International Conference on 3D Web Technology (Web3D '25)*，意大利锡耶纳，2025 年 9 月 9-10 日。ACM，ISBN 979-8-4007-2038-3。[doi:10.1145/3746237.3746315](https://doi.org/10.1145/3746237.3746315) -- 2025 年 Web3D 工具竞赛第三名。仓库：[VT-Visionarium/X3Test](https://github.com/VT-Visionarium/X3Test)。VTechworks 副本：[471dddd8](https://vtechworks.lib.vt.edu/items/471dddd8-7665-4e6f-a8f5-7f9276213835)。
- 早期关于 LLM 中视觉/空间知识的探索工作：[doi:10.1145/3665318.3677159](https://doi.org/10.1145/3665318.3677159)，附带实证制品 [LLM-generated X3D Model Browser](https://metagrid1.sv.vt.edu/~bsandbro/x3dgen/all_models/)。
通过 X3D AI 工作组（[ai@web3d.org](https://web3d.org/mailman/listinfo/ai_web3d.org)）和 Web3D 联盟继续协调。
## 许可证
[Web3D 联盟开源许可证](https://www.web3d.org/license) -- 见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器