范加德·达兹

版本0.2.0 |DAZ Studio的MCP服务器

______________________________________________________________________

这是什么？

此MCP服务器允许Claude（通过Claude Desktop或其他MCP客户端）直接控制DAZ Studio：

查询场景信息（人物、相机、灯光、空间位置）
读取和修改节点属性（变换、变形）
发现和应用变形，包括按名称模式搜索
遍历和操纵场景层次（父/子、骨架）
将情感表达应用于角色
协调多角色互动（看、伸手、拥抱、握手）
执行批处理操作（在一次调用中设置多个属性，速度快5-10倍）
控制摄影机和视口（动态观察、帧、预设）
创建关键帧动画并导出为图像序列
触发同步或异步渲染，支持取消
应用专业灯光预设和电影构图规则
浏览和查询DAZ内容库
保存和恢复命名的场景检查点
执行任意DazScript代码
访问全面的DazScript文档和示例

服务器充当桥梁： MCP客户端 ↔ 范加德·达兹 ↔ DazScriptServer插件 ↔ DAZ工作室

______________________________________________________________________

先决条件

在使用此服务器之前，您需要：

DAZ工作室4.5+ 已安装并正在运行
DazScriptServer插件 已安装、配置并处于活动状态

- 下载地址：https://github.com/bluemoonfoundry/daz-script-server - 插件必须在端口18811上运行（默认） - 必须配置身份验证（API令牌）

Python 3.11+ 用于运行MCP服务器
紫外线 包管理器（推荐）或pip

______________________________________________________________________

安装

使用紫外线（推荐）

# Clone the repository
git clone https://github.com/bluemoonfoundry/vangard-daz-mcp.git
cd vangard-daz-mcp

# Install dependencies
uv sync

# Run the server
uv run vangard-daz-mcp

使用pip

# Install from source
pip install .

# Run the server
vangard-daz-mcp

______________________________________________________________________

配置

环境变量

通过环境变量配置服务器：

变量	默认值	描述
`DAZ_HOST`	`localhost`	DazScriptServer主机名
`DAZ_PORT`	`18811`	DazScriptServer端口
`DAZ_TIMEOUT`	`30.0`	请求超时（秒）（长渲染时增加）
`DAZ_API_TOKEN`	（来自文件）	用于身份验证的API令牌

认证

服务器自动从中读取API令牌 ~/.daz3d/dazscriptserver_token.txt （DazScriptServer创建的文件）。

用环境变量覆盖：

export DAZ_API_TOKEN="your-token-here"

重要提示： DazScriptServer必须启用身份验证（默认）。没有有效令牌，MCP服务器无法连接。

______________________________________________________________________

Claude桌面配置

将此添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "daz-studio": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/vangard-daz-mcp",
        "run",
        "vangard-daz-mcp"
      ],
      "env": {
        "DAZ_TIMEOUT": "60.0"
      }
    }
  }
}

注：替换 /absolute/path/to/vangard-daz-mcp 使用系统上的实际路径。

保存配置后，重新启动Claude Desktop。DAZ Studio工具将出现在Claude的工具面板中。

______________________________________________________________________

可用工具

📚 文档工具

`daz_script_help`

获取DazScript文档、示例和最佳实践。

论据：

topic （字符串，默认值 "overview")：要检索的文档主题

可用主题：

overview -DazScript环境基础
gotchas -导致超时或错误的关键错误
camera -相机创建、定位和瞄准
light -灯光创建、类型和三点照明
environment -Iray环境设置和照明模式
scene -场景管理（新建、保存、加载、选择）
properties -节点属性、变换和变形
content -浏览和加载库中的内容
coordinates -坐标系和定位基准
posing -人物姿势、骨骼层次、形态与姿势、旋转陷阱
morphs -形态发现、搜索、值范围和管理
hierarchy -场景层次、亲子关系、育儿操作
interaction -多角色互动，看力学，世界空间摆姿势
batch -批处理操作模式和性能优化
viewport -视口和相机控制、球面定位、预设
animation -关键帧动画、时间线控制、图像序列导出
rendering -渲染工作流、多相机、批渲染、动画导出

退货： 带示例的格式化文档

在以下情况下使用： 在编写自定义DazScript代码之前，要学习正确的模式并避免常见错误。

例子：

daz_script_help("camera")  # Get camera documentation
daz_script_help("gotchas") # Learn critical gotchas

______________________________________________________________________

🔍 检测工具

`daz_status`

检查DAZ Studio的连接和版本。

退货：

{
  "running": true,
  "version": "1.3.0"
}

在以下情况下使用： 验证DAZ Studio是否正在运行以及连接是否正常。

______________________________________________________________________

`daz_scene_info`

获取当前场景的快照。

退货：

{
  "sceneFile": "/path/to/scene.duf",
  "selectedNode": "Genesis 9",
  "figures": [
    {"name": "Genesis9", "label": "Genesis 9", "type": "DzFigure"}
  ],
  "cameras": [
    {"name": "Camera", "label": "Camera 1"}
  ],
  "lights": [
    {"name": "DistantLight", "label": "Distant Light", "type": "DzDistantLight"}
  ],
  "totalNodes": 3247
}

在以下情况下使用： 您需要了解场景中的内容（角色、相机、灯光）。

注：不枚举所有节点（场景可以有1000+个节点）。使用 daz_execute 用于细粒度查询。

______________________________________________________________________

`daz_get_node`

通过节点的标签或内部名称读取节点的所有数字属性。

论据：

node_label （string）：显示标签或内部名称（例如“Genesis 9”）

退货：

{
  "name": "Genesis9",
  "label": "Genesis 9",
  "type": "DzFigure",
  "properties": {
    "X Translate": 0.0,
    "Y Translate": 0.0,
    "Z Translate": 0.0,
    "X Rotate": 0.0,
    "Y Rotate": 0.0,
    "Z Rotate": 0.0,
    "Scale": 100.0,
    "Head Size": 0.5
  }
}

在以下情况下使用： 您需要读取节点上的变换、变形或其他数值属性。

______________________________________________________________________

🔬 变形发现工具

`daz_list_morphs`

列出节点上的所有变形（数值属性）及其当前值。

论据：

node_label （string）：节点显示标签或内部名称
include_zero （bool，默认值 False)：包括具有零值的变形

退货：

{
  "morphs": [
    {"label": "Height", "name": "Height", "value": 1.05, "path": "Morphs/Body"},
    {"label": "Head Size", "name": "HeadSize", "value": 0.9, "path": "Morphs/Head"}
  ],
  "count": 2,
  "nodeLabel": "Genesis 9"
}

在以下情况下使用：

发现人物身上有哪些变形
检查哪些变形当前处于活动状态
构建变形选择UI
探索角色自定义选项

例子：

# List only active morphs (non-zero values)
daz_list_morphs("Genesis 9", include_zero=False)

# List ALL available morphs (warning: may return 500-1000+ morphs)
daz_list_morphs("Genesis 9", include_zero=True)

注：创世记人物可以有1000多种变形。使用 include_zero=False 仅查看活动变形，或使用 daz_search_morphs 按模式过滤。

______________________________________________________________________

`daz_search_morphs`

搜索与名称模式匹配的变体。

论据：

node_label （string）：节点显示标签或内部名称
pattern （string）：要搜索的子字符串（不区分大小写）
include_zero （bool，默认值 False)：包括具有零值的变形

退货：

{
  "morphs": [
    {"label": "Smile", "name": "Smile", "value": 0.0, "path": "Morphs/Expressions"},
    {"label": "Smile Open", "name": "SmileOpen", "value": 0.0, "path": "Morphs/Expressions"}
  ],
  "count": 2,
  "pattern": "smile",
  "nodeLabel": "Genesis 9"
}

在以下情况下使用：

查找特定变形（例如，所有微笑变形、头部变形）
按类别或身体部位发现变形
构建过滤变形列表

例子：

# Find all smile-related morphs
daz_search_morphs("Genesis 9", "smile", include_zero=True)

# Find active head morphs only
daz_search_morphs("Genesis 9", "head", include_zero=False)

# Find all facial expression morphs
daz_search_morphs("Genesis 9", "express", include_zero=True)

常见搜索模式：

"smile", "frown", "express" -面部表情
"head", "face", "nose" -面部特征
"arm", "leg", "body" -车身部件
"muscle", "tone", "fit" -身体定义
"height", "scale" -尺寸调整

______________________________________________________________________

🌳 场景层次工具

`daz_get_node_hierarchy`

获取具有所有子体的节点的完整层次结构树。

论据：

node_label （string）：根节点显示标签或内部名称
max_depth （int，默认值 10)：最大递归深度（0=无限制）

退货：

{
  "node": "Genesis 9",
  "hierarchy": {
    "label": "Genesis 9",
    "name": "Genesis9",
    "type": "DzFigure",
    "children": [
      {
        "label": "hip",
        "name": "hip",
        "type": "DzBone",
        "children": [...]
      }
    ]
  },
  "totalDescendants": 127
}

在以下情况下使用：

了解骨架结构
探索骨骼关系
映射复杂的场景层次结构
查找节点的所有子代

例子：

# Get skeleton hierarchy with depth limit
daz_get_node_hierarchy("Genesis 9", max_depth=3)

# Get full hierarchy (warning: Genesis 9 has 100+ bones)
daz_get_node_hierarchy("Genesis 9", max_depth=0)

______________________________________________________________________

`daz_list_children`

列出节点的直接子节点。

论据：

node_label （string）：父节点显示标签或内部名称

退货：

{
  "node": "hip",
  "children": [
    {"label": "pelvis", "name": "pelvis", "type": "DzBone"},
    {"label": "lThighBend", "name": "lThighBend", "type": "DzBone"},
    {"label": "rThighBend", "name": "rThighBend", "type": "DzBone"}
  ],
  "count": 3
}

在以下情况下使用：

逐一探索层次结构
检查节点是否有子节点
构建自定义树结构

例子：

# List children of Genesis 9 root
daz_list_children("Genesis 9")

# Check if node has children
result = daz_list_children("Camera 1")
if result["count"] == 0:
    print("No children")

______________________________________________________________________

`daz_get_parent`

获取节点的父节点。

论据：

node_label （string）：子节点显示标签或内部名称

退货：

{
  "node": "lHand",
  "parent": {
    "label": "lForearmBend",
    "name": "lForearmBend",
    "type": "DzBone"
  }
}

退货 null 如果节点是根（没有父节点），则表示父节点。

在以下情况下使用：

向上遍历层次结构
查找包含节点的内容
检查节点是否为根

例子：

# Get parent of a bone
result = daz_get_parent("lHand")
print(f"Parent: {result['parent']['label']}")

# Check if node is root
result = daz_get_parent("Genesis 9")
if result["parent"] is None:
    print("This is a root node")

______________________________________________________________________

`daz_set_parent`

设置节点的父级（父级操作）。

论据：

node_label （string）：节点到父节点
parent_label （string）：新建父节点
maintain_world_transform （bool，默认值 True)：如果为真，则调整局部变换以保持相同的世界位置

退货：

{
  "success": true,
  "node": "Sword",
  "newParent": "rHand",
  "previousParent": null
}

在以下情况下使用：

在人物身上附加道具（例如，手持武器）
将摄像头与节点关联
重新组织场景层次结构
将衣物固定在骨头上

例子：

# Attach sword to right hand (maintains position)
daz_set_parent("Sword", "rHand", maintain_world_transform=True)

# Parent camera to figure (follows figure)
daz_set_parent("Camera 1", "Genesis 9", maintain_world_transform=True)

# Attach bracelet to forearm
daz_set_parent("Bracelet", "lForearmBend", maintain_world_transform=True)

注：当 maintain_world_transform=True，节点的世界位置保持不变，但局部变换值（X/Y/Z平移、旋转）会更改以考虑新父级的变换。

______________________________________________________________________

⚡ 批量操作

批处理操作允许您在一次调用中修改多个节点或属性，从而显著提高性能。每个操作都有单独的错误处理，因此失败不会中止整个批处理。

性能优势：

单脚本调用（所有操作在一次往返中执行）
操作之间没有HTTP/网络开销
比典型批次的单个呼叫快5-10倍
不中止批处理的单个错误处理

常见用例：

应用面部表情（一次多个变形）
配置照明设置（多个灯光属性）
将多组道具一起移动/旋转
显示/隐藏场景管理的节点组
将多个摄像头或灯光重置为默认值

`daz_batch_set_properties`

在一次调用中为一个或多个节点设置多个属性。

论据：

operations （array）：操作对象列表，每个对象包含：

- nodeLabel （string）：显示节点标签 - propertyName （string）：属性标签或内部名称 - value （浮动）：房产的新价值

退货：

{
  "results": [
    {"success": true, "node": "Genesis 9", "property": "X Translate", "value": 100},
    {"success": false, "node": "Missing", "error": "Node not found: Missing"}
  ],
  "successCount": 1,
  "failureCount": 1,
  "total": 2
}

在以下情况下使用： 设置3+个属性，应用面部表情，配置场景预设。

例子：

# Apply "surprised" facial expression
daz_batch_set_properties([
    {"nodeLabel": "Genesis 9", "propertyName": "PHMEyesWide", "value": 0.8},
    {"nodeLabel": "Genesis 9", "propertyName": "PHMBrowsUp", "value": 0.7},
    {"nodeLabel": "Genesis 9", "propertyName": "PHMMouthOpen", "value": 0.4}
])

# Configure lighting setup
daz_batch_set_properties([
    {"nodeLabel": "Key Light", "propertyName": "Flux", "value": 2000},
    {"nodeLabel": "Fill Light", "propertyName": "Flux", "value": 800},
    {"nodeLabel": "Rim Light", "propertyName": "Flux", "value": 2500}
])

演出通过批量设置10个变形比10个个体快~5-10x daz_set_property 电话。

______________________________________________________________________

`daz_batch_transform`

将相同的变换属性应用于多个节点。

论据：

node_labels （数组）：要转换的节点显示标签列表
transforms （object）：属性名称到值的字典（例如。， {"XTranslate": 50, "YRotate": 45})

退货：

{
  "results": [
    {"success": true, "node": "Prop1", "applied": ["X Translate", "Y Rotate"]},
    {"success": false, "node": "Missing", "error": "Node not found: Missing"}
  ],
  "successCount": 1,
  "failureCount": 1,
  "total": 2
}

在以下情况下使用： 以相同的量移动、旋转或缩放多个对象。

例子：

# Move multiple props to the right
daz_batch_transform(
    ["Chair", "Table", "Lamp"],
    {"XTranslate": 100}
)

# Rotate and scale multiple objects
daz_batch_transform(
    ["Prop1", "Prop2", "Prop3"],
    {"YRotate": 45, "Scale": 1.2}
)

# Reset rotation for all cameras
daz_batch_transform(
    ["Camera 1", "Camera 2", "Camera 3"],
    {"XRotate": 0, "YRotate": 0, "ZRotate": 0}
)

注：仅应用每个节点上存在的属性。缺少的属性将被自动跳过。

______________________________________________________________________

`daz_batch_visibility`

在视口和渲染中显示或隐藏多个节点。

论据：

node_labels （数组）：要修改的节点显示标签列表
visible （bool，默认值 True)：显示节点为True，隐藏节点为False

退货：

{
  "results": [
    {"success": true, "node": "Ground", "visible": false},
    {"success": true, "node": "Sky Dome", "visible": false}
  ],
  "successCount": 2,
  "failureCount": 0,
  "total": 2
}

在以下情况下使用： 场景管理、测试配置、优化渲染时间。

例子：

# Hide all cameras
daz_batch_visibility(["Camera 1", "Camera 2", "Camera 3"], visible=False)

# Hide environment elements for character close-up
daz_batch_visibility(["Ground", "Sky Dome", "Background"], visible=False)

# Show all weapons
daz_batch_visibility(["Sword", "Shield", "Helmet"], visible=True)

注：隐藏节点保留在场景中，但在视口或渲染中不可见。

______________________________________________________________________

`daz_batch_select`

在DAZ Studio场景中选择多个节点。

论据：

node_labels （数组）：要选择的节点显示标签列表
add_to_selection （bool，默认值 False)：如果为True，则添加到当前选择中；如果为False，则替换当前选择

退货：

{
  "selected": ["Genesis 9", "Genesis 8 Female"],
  "count": 2,
  "total": 2
}

在以下情况下使用： 选择要检查或操作的节点组。

例子：

# Select multiple characters
daz_batch_select(["Genesis 9", "Genesis 8 Female"])

# Add props to current selection
daz_batch_select(["Sword", "Shield"], add_to_selection=True)

# Select all lights
daz_batch_select(["Spot Light 1", "Distant Light 1", "Point Light 1"])

注：不存在的节点会被自动跳过。返回成功选择的计数。

______________________________________________________________________

📷 视口和相机控制

视口控制工具支持程序化的相机定位、取景和预设管理，以实现自动场景摄影和一致的相机角度。

关键能力：

切换活动视口摄影机
使用球坐标定位相机（围绕目标轨道）
自动框选相机以显示对象（计算边界框）
将摄像头位置保存/加载为预设（JSON可序列化）
跨场景可重复使用的相机角度

`daz_set_active_camera`

设置DAZ Studio视口中活动的摄影机。

论据：

camera_label （string）：显示要激活的相机标签

退货：

{
  "success": true,
  "camera": "Camera 1",
  "previousCamera": "Perspective View"
}

在以下情况下使用： 在预定义的相机角度之间切换，从多个视点预览。

例子：

# Switch to specific camera
daz_set_active_camera("Camera 1")

# Switch back to default
daz_set_active_camera("Perspective View")

______________________________________________________________________

`daz_orbit_camera_around`

以指定的角度和距离放置围绕目标节点运行的摄影机。

论据：

camera_label （string）：相机定位
target_label （string）：要环绕的目标节点
distance （浮动，默认 200.0)：与目标的距离，单位为厘米
angle_horizontal （浮动，默认 45.0)：水平角度（度）（0=前/+Z，90=右/+X）
angle_vertical （浮动，默认 15.0)：垂直角度，单位为度（正=上方）

退货：

{
  "success": true,
  "camera": "Camera 1",
  "target": "Genesis 9",
  "position": {"x": 141.4, "y": 151.8, "z": 141.4},
  "targetPosition": {"x": 0, "y": 100, "z": 0}
}

在以下情况下使用： 角色摄影、产品拍摄、转盘动画、建立相机角度。

例子：

# Front 3/4 view (classic portrait angle)
daz_orbit_camera_around("Camera 1", "Genesis 9",
                        distance=200, angle_horizontal=45, angle_vertical=15)

# Side view from left
daz_orbit_camera_around("Camera 1", "Genesis 9",
                        distance=150, angle_horizontal=-90, angle_vertical=0)

# Bird's eye view
daz_orbit_camera_around("Camera 1", "Genesis 9",
                        distance=300, angle_horizontal=0, angle_vertical=60)

# Dramatic low angle
daz_orbit_camera_around("Camera 1", "Genesis 9",
                        distance=180, angle_horizontal=25, angle_vertical=-20)

角度参考：

水平：0°=前（+Z），90°=右（+X），180°=后（-Z），-90°=左（-X）
垂直：正=地平线以上，负=地平线以下

距离指南 （身高170厘米）：

全身：350-450cm
人像：80-120cm
面部特写：30-50cm

______________________________________________________________________

`daz_frame_camera_to_node`

通过在计算距离处定位来显示节点的帧相机。

论据：

camera_label （string）：相机定位
node_label （string）：节点到帧
distance （浮动，可选）：距节点中心的距离，单位为厘米。如果未指定，则自动计算为最大边界框尺寸的2.5倍。

退货：

{
  "success": true,
  "camera": "Camera 1",
  "node": "Genesis 9",
  "position": {"x": 0, "y": 100, "z": 450},
  "nodeCenter": {"x": 0, "y": 100, "z": 0},
  "nodeSize": {"x": 50, "y": 170, "z": 40}
}

在以下情况下使用： 自动取景不同大小的对象，跨场景的一致取景。

例子：

# Frame character (auto distance)
daz_frame_camera_to_node("Camera 1", "Genesis 9")

# Frame prop with specific distance
daz_frame_camera_to_node("Camera 1", "Sword", distance=50)

# Close-up on head
daz_frame_camera_to_node("Camera 1", "head", distance=30)

注：摄影机位于前方（+Z），对准节点的边界框中心。自动计算的距离是最大尺寸的2.5倍。

______________________________________________________________________

`daz_save_camera_preset`

将相机位置和旋转保存为预设数据。

论据：

camera_label （string）：要保存的相机

退货：

{
  "preset": {
    "label": "Camera 1",
    "transforms": {
      "XTranslate": 0, "YTranslate": 100, "ZTranslate": 300,
      "XRotate": -10, "YRotate": 0, "ZRotate": 0,
      "XScale": 1.0, "YScale": 1.0, "ZScale": 1.0
    }
  }
}

在以下情况下使用： 保存可重复使用的相机角度，跨项目共享相机位置。

例子：

# Save camera position
preset = daz_save_camera_preset("Camera 1")

# Store to file
import json
with open("portrait_camera.json", "w") as f:
    json.dump(preset, f)

注：预设数据是JSON可序列化的，可以应用于任何相机。

______________________________________________________________________

`daz_load_camera_preset`

根据预设数据恢复相机位置和旋转。

论据：

camera_label （string）：要修改的相机
preset （dict）：预设词典 daz_save_camera_preset() （必须包含 transforms 按键）

退货：

{
  "success": true,
  "camera": "Camera 1",
  "applied": ["XTranslate", "YTranslate", "ZTranslate", "XRotate", "YRotate", "ZRotate"]
}

在以下情况下使用： 恢复已保存的相机位置，对多个相机应用相同的角度。

例子：

# Load preset from file
import json
with open("portrait_camera.json") as f:
    preset = json.load(f)

# Apply to camera
daz_load_camera_preset("Camera 1", preset["preset"])

# Apply same preset to multiple cameras
for cam in ["Camera 1", "Camera 2", "Camera 3"]:
    daz_load_camera_preset(cam, preset["preset"])

注：预设可以应用于任何相机，而不仅仅是原始相机。可用于同步多个摄像头。

______________________________________________________________________

🎬 动画系统

动画工具启用基于关键帧的属性动画。在特定帧处设置关键帧，DAZ Studio会在它们之间平滑插值。支持为任何数值属性（变换、变形、灯光、摄影机）设置动画。

关键能力：

在属性上设置/获取/删除关键帧
时间线控制（当前帧、帧范围）
将动画导出为图像序列
在属性之间复制和偏移动画
以编程方式检查关键帧数据

常见用例：

角色动画（行走周期、手势、面部表情）
摄影机动画（推拉、平移、缩放）
产品转盘（360°旋转）
变形动画（微笑消退、眨眼）
多角色编舞

`daz_set_keyframe`

在指定帧的属性上设置关键帧。

论据：

node_label （字符串）：节点显示标签
property_name （string）：属性标签或内部名称
frame （int）：帧号（从0开始）
value （float）：此帧的值

退货：

{
  "success": true,
  "node": "Genesis 9",
  "property": "X Translate",
  "frame": 0,
  "value": 0.0
}

在以下情况下使用： 创建动画，定义关键姿势。

例子：

# Animate movement (0 to 100cm over 30 frames)
daz_set_keyframe("Genesis 9", "XTranslate", frame=0, value=0)
daz_set_keyframe("Genesis 9", "XTranslate", frame=30, value=100)

# Animate rotation (0 to 90 degrees)
daz_set_keyframe("Genesis 9", "YRotate", frame=0, value=0)
daz_set_keyframe("Genesis 9", "YRotate", frame=60, value=90)

# Animate morph (fade in smile)
daz_set_keyframe("Genesis 9", "PHMSmile", frame=0, value=0)
daz_set_keyframe("Genesis 9", "PHMSmile", frame=15, value=0.8)

注： DAZ Studio会自动在关键帧之间进行插值。在现有帧处设置关键帧会更新该值。

______________________________________________________________________

`daz_get_keyframes`

获取属性的所有关键帧。

论据：

node_label （字符串）：节点显示标签
property_name （string）：属性标签或内部名称

退货：

{
  "keyframes": [
    {"frame": 0, "value": 0.0},
    {"frame": 30, "value": 100.0}
  ],
  "count": 2
}

在以下情况下使用： 检查动画，复制关键帧，检查属性是否已设置动画。

例子：

# Get keyframes
result = daz_get_keyframes("Genesis 9", "XTranslate")
for kf in result['keyframes']:
    print(f"Frame {kf['frame']}: {kf['value']}")

# Copy keyframes to another node
for kf in result['keyframes']:
    daz_set_keyframe("Genesis 8", "XTranslate", kf['frame'], kf['value'])

______________________________________________________________________

`daz_remove_keyframe`

删除指定帧处的关键帧。

论据：

node_label （字符串）：节点显示标签
property_name （string）：属性标签或内部名称
frame （int）：帧编号

退货：

{
  "success": true,
  "node": "Genesis 9",
  "property": "X Translate",
  "frame": 15,
  "removed": true
}

在以下情况下使用： 删除特定关键帧，编辑动画计时。

例子：

# Remove keyframe
daz_remove_keyframe("Genesis 9", "XTranslate", frame=15)

注：退货 removed: false 如果该帧处不存在关键帧（不是错误）。

______________________________________________________________________

`daz_clear_animation`

从属性中删除所有关键帧。

论据：

node_label （字符串）：节点显示标签
property_name （string）：属性标签或内部名称

退货：

{
  "success": true,
  "node": "Genesis 9",
  "property": "X Translate",
  "removed": 5
}

在以下情况下使用： 清除动画，将属性重置为静态。

例子：

# Clear animation
result = daz_clear_animation("Genesis 9", "XTranslate")
print(f"Removed {result['removed']} keyframes")

# Clear all transform animations
for prop in ["XTranslate", "YTranslate", "ZTranslate", "XRotate", "YRotate", "ZRotate"]:
    daz_clear_animation("Genesis 9", prop)

注：比单独删除关键帧更有效。

______________________________________________________________________

`daz_set_frame`

设置当前动画帧。

论据：

frame （int）：要移动到的帧号

退货：

{
  "success": true,
  "frame": 30,
  "previousFrame": 0
}

在以下情况下使用： 预览动画，渲染特定帧。

例子：

# Jump to frame 30
daz_set_frame(30)

# Render all frames
info = daz_get_animation_info()
for frame in range(info['startFrame'], info['endFrame'] + 1):
    daz_set_frame(frame)
    daz_render(output_path=f"frame_{frame:04d}.png")

注：场景更新以显示帧处的动画状态。

______________________________________________________________________

`daz_set_frame_range`

设置动画帧范围（开始和结束）。

论据：

start_frame （int）：第一帧（通常为0）
end_frame （int）：最后一帧

退货：

{
  "success": true,
  "startFrame": 0,
  "endFrame": 119,
  "previousStart": 0,
  "previousEnd": 30
}

在以下情况下使用： 在创建关键帧之前定义动画长度。

例子：

# 4-second animation (120 frames at 30fps)
daz_set_frame_range(0, 119)

# 10-second animation
daz_set_frame_range(0, 299)

注：帧范围包括在内（帧0-119=120帧）。持续时间=（结束-开始+1）/fps。

______________________________________________________________________

`daz_get_animation_info`

获取动画时间线信息（当前帧、范围、fps）。

退货：

{
  "currentFrame": 0,
  "startFrame": 0,
  "endFrame": 119,
  "fps": 30.0,
  "totalFrames": 120,
  "durationSeconds": 4.0
}

在以下情况下使用： 渲染前检查时间线状态，计算持续时间。

例子：

# Get timeline info
info = daz_get_animation_info()
print(f"Animation: {info['durationSeconds']} seconds ({info['totalFrames']} frames)")

# Render entire animation
for frame in range(info['startFrame'], info['endFrame'] + 1):
    daz_set_frame(frame)
    daz_render(output_path=f"frame_{frame:04d}.png")

注： DAZ Studio的FPS通常为30。

______________________________________________________________________

🎥 高级渲染控制

高级渲染工具为多摄影机渲染、动画导出和批渲染操作提供程序控制。

关键能力：

从特定摄影机渲染而不更改视口
从多个摄影机批量渲染
将动画导出为图像序列
查询渲染设置
自动渲染工作流

常见用例：

多角度产品拍摄（正面、侧面、顶部、透视）
角色转盘（8-16个摄像头角度）
动画导出（逐帧图像序列）
从多个角度测试渲染
多摄影机动画渲染

`daz_render_with_camera`

从特定摄影机渲染，而不更改活动视口摄影机。

论据：

camera_label （string）：要渲染的摄影机
output_path （字符串，可选）：输出文件路径（如果未指定，则渲染到视口）

退货：

{
  "success": true,
  "camera": "Camera 1",
  "outputPath": "/path/to/render.png"
}

在以下情况下使用： 多相机批量渲染，在不干扰视口的情况下测试相机角度。

例子：

# Render from specific camera
daz_render_with_camera("Camera 1", output_path="/renders/cam1.png")

# Render from multiple cameras
for cam in ["Front", "Side", "Top"]:
    daz_render_with_camera(cam, output_path=f"/renders/{cam}.png")

注：视口相机保持不变。以前的渲染摄影机会自动恢复。

______________________________________________________________________

`daz_get_render_settings`

获取当前渲染设置和配置。

退货：

{
  "renderToFile": true,
  "outputPath": "/path/to/output.png",
  "currentCamera": "Camera 1",
  "aspectRatio": 1.777,
  "aspectWidth": 16,
  "aspectHeight": 9
}

在以下情况下使用： 在批处理操作之前验证渲染配置，调试渲染问题。

例子：

# Check render settings
settings = daz_get_render_settings()
print(f"Render camera: {settings['currentCamera']}")
print(f"Aspect: {settings['aspectWidth']}x{settings['aspectHeight']}")

# Verify configuration
if not settings['renderToFile']:
    print("Warning: Render configured for viewport, not file")

______________________________________________________________________

`daz_batch_render_cameras`

按顺序从多个摄影机渲染。

论据：

cameras （list\[string\]）：相机标签列表
output_dir （string）：输出目录
base_filename （字符串，默认值 "render")：基本文件名（附加相机名称）

退货：

{
  "success": true,
  "rendered": [
    {"camera": "Front", "outputPath": "/renders/product_Front.png"},
    {"camera": "Side", "outputPath": "/renders/product_Side.png"}
  ],
  "total": 2
}

在以下情况下使用： 产品摄影、转盘渲染、多角度测试渲染。

例子：

# Render from multiple cameras
daz_batch_render_cameras(
    cameras=["Front", "Side", "Top", "Perspective"],
    output_dir="/renders",
    base_filename="product"
)
# Generates: product_Front.png, product_Side.png, product_Top.png, product_Perspective.png

# Turntable (8 cameras around character)
cameras = [f"Cam_{angle}" for angle in [0, 45, 90, 135, 180, 225, 270, 315]]
daz_batch_render_cameras(cameras, "/renders/turntable", "angle")

注：文件名中的相机名称用下划线替换了非字母数字字符。批处理后将恢复之前的渲染摄影机。

______________________________________________________________________

`daz_render_animation`

将动画帧范围渲染为图像序列。

论据：

output_dir （string）：输出目录
start_frame （int，可选）：第一帧（默认：动画范围开始）
end_frame （int，可选）：最后一帧（默认：动画范围结束）
filename_pattern （字符串，默认值 "frame")：文件名模式（附加帧号）
camera （字符串，可选）：要渲染的摄影机（默认值：当前渲染摄影机）

退货：

{
  "success": true,
  "rendered": [
    {"frame": 0, "outputPath": "/animation/frame_0000.png"},
    {"frame": 1, "outputPath": "/animation/frame_0001.png"}
  ],
  "total": 120,
  "frames": {"start": 0, "end": 119}
}

在以下情况下使用： 导出动画，创建视频序列。

例子：

# Render entire animation (uses animation range)
daz_render_animation(output_dir="/animation")
# Generates: frame_0000.png, frame_0001.png, ..., frame_0119.png

# Render specific frame range
daz_render_animation(
    output_dir="/animation/clip",
    start_frame=30,
    end_frame=60,
    filename_pattern="clip"
)

# Render animation from specific camera
daz_render_animation(
    output_dir="/animation",
    camera="Camera 1"
)

# Convert to video (using ffmpeg)
# ffmpeg -framerate 30 -i frame_%04d.png -c:v libx264 -pix_fmt yuv420p output.mp4

注：帧号零填充为4位数字（0000-9999）。完成后恢复时间线位置和渲染相机。

______________________________________________________________________

📐 空间查询工具

这些工具允许您查询世界空间位置、大小和场景节点的关系。

`daz_get_world_position`

获取节点的世界空间位置、局部位置、旋转和比例。

论据：

node_label （string）：节点显示标签或内部名称

退货：

{
  "node": "Genesis 9",
  "worldPosition": {"x": 0, "y": 0, "z": 0},
  "localPosition": {"x": 0, "y": 0, "z": 0},
  "rotation": {"x": 0, "y": 0, "z": 0},
  "scale": {"x": 1, "y": 1, "z": 1}
}

在以下情况下使用： 在放置另一个对象之前，先找到角色或道具的精确世界坐标。

______________________________________________________________________

`daz_get_bounding_box`

获取节点的边界框（最小/最大角、中心、尺寸）。

论据：

node_label （string）：节点显示标签或内部名称

退货：

{
  "node": "Genesis 9",
  "min": {"x": -30, "y": 0, "z": -15},
  "max": {"x": 30, "y": 170, "z": 15},
  "center": {"x": 0, "y": 85, "z": 0},
  "width": 60, "height": 170, "depth": 30
}

在以下情况下使用： 自动取景相机，检查对象大小，将对象放置在曲面上。

______________________________________________________________________

`daz_calculate_distance`

计算两个节点之间的距离和方向向量。

论据：

from_label （字符串）：源节点
to_label （string）：目标节点

退货：

{
  "from": "Alice",
  "to": "Bob",
  "distance": 120.5,
  "direction": {"x": 0.707, "y": 0, "z": 0.707}
}

在以下情况下使用： 检查两个角色是否在交互范围内，相对于人物定位道具。

______________________________________________________________________

`daz_get_spatial_relationship`

两个节点之间的自然语言空间关系。

论据：

from_label （string）：引用节点
to_label （string）：目标节点

退货：

{
  "from": "Camera 1",
  "to": "Genesis 9",
  "distance": 300.0,
  "direction": "in front of",
  "angle": 5.2,
  "overlap": false
}

在以下情况下使用： 用自然语言描述场景布局，验证相机位置。

______________________________________________________________________

`daz_check_overlap`

检查两个节点是否有重叠的边界框。

论据：

node1_label （string）：第一个节点
node2_label （string）：第二个节点

退货：

{
  "overlapping": true,
  "penetrationDepth": {"x": 2.1, "y": 0, "z": 0}
}

在以下情况下使用： 检测角色之间的相互渗透，在渲染前验证姿势。

______________________________________________________________________

🔬 物业反思工具

`daz_inspect_properties`

列出节点上的所有属性，可选择按类型筛选。

论据：

node_label （string）：节点显示标签或内部名称
filter_type （字符串，默认值 "all")：其中之一 "all", "numeric", "transform", "morph", "bool", "string"

退货：

{
  "node": "Spot Light 1",
  "properties": [
    {"label": "Flux", "name": "Flux", "type": "numeric", "value": 1500},
    {"label": "Shadow Softness", "name": "Shadow Softness", "type": "numeric", "value": 0.5}
  ],
  "count": 2
}

在以下情况下使用： 发现节点上可设置的属性（灯光、相机、道具）。

例子：

# List all numeric properties on a spotlight
daz_inspect_properties("Spot Light 1", filter_type="numeric")

# List transform properties only
daz_inspect_properties("Genesis 9", filter_type="transform")

______________________________________________________________________

`daz_get_property_metadata`

获取单个属性的详细元数据（最小值、最大值、默认值、类型、路径）。

论据：

node_label （string）：节点显示标签或内部名称
property_name （string）：属性标签或内部名称

退货：

{
  "node": "Spot Light 1",
  "property": "Flux",
  "type": "numeric",
  "value": 1500,
  "default": 1500,
  "min": 0,
  "max": 100000,
  "path": "General/Luminous Flux"
}

在以下情况下使用： 在设置属性之前查找有效范围，验证属性名称。

______________________________________________________________________

`daz_validate_script`

静态分析DazScript代码中已知的反模式。不需要DAZ Studio连接。

论据：

script （string）：要分析的DazScript源代码

退货：

{
  "valid": false,
  "issues": [
    {"severity": "error", "line": 3, "message": "Bare return at top level — wrap in IIFE"},
    {"severity": "warning", "line": 7, "message": "getElementID() is not a function — use .elementID property"}
  ],
  "issueCount": 2
}

在以下情况下使用： 在通过运行自定义脚本之前 daz_execute，及早发现常见错误。

______________________________________________________________________

💡 照明预设工具

`daz_apply_lighting_preset`

用一个命令创建专业的照明设置。

论据：

preset （string）：照明预设名称
subject_label （字符串）：节点到灯光（预设灯光相对于主体边界框的位置）

预设：

three-point --钥匙（右前）+填充（左前）+轮辋（后）。通用目的。
rembrandt --按键（45°侧，高）+暗填充。戏剧性的肖像。
butterfly --钥匙（正前方，高）。魅力/美容照明。
split --钥匙（90°侧）。半张脸亮着，一半在阴影里。穆迪。
loop --键（35°侧）+填充+边缘。看起来很自然的肖像。

退货：

{
  "success": true,
  "preset": "three-point",
  "subject": "Genesis 9",
  "lights": ["Key Light", "Fill Light", "Rim Light"]
}

所有预设：将灯光对准拍摄对象的面部高度，将环境模式设置为“仅场景”，并首先删除同名现有灯光。

在以下情况下使用： 设置场景进行渲染，而无需手动定位单个灯光。

例子：

# Classic portrait lighting
daz_apply_lighting_preset("three-point", "Genesis 9")

# Dramatic moody lighting
daz_apply_lighting_preset("rembrandt", "Genesis 9")

______________________________________________________________________

`daz_validate_scene`

验证渲染的场景质量——检查照明、相机、碰撞。

退货：

{
  "score": 75,
  "issues": [
    {"category": "lighting", "severity": "medium", "message": "Only one light source — consider adding fill or rim light"},
    {"category": "collision", "severity": "high", "message": "Alice and Bob bounding boxes overlap by 5cm"}
  ],
  "breakdown": {
    "lighting": 60,
    "cameras": 100,
    "figures": 100,
    "collisions": 50
  }
}

分数： 0-100.问题会降低分数。检查：图形之间的边界框碰撞、照明不足、没有摄像头、没有图形。

在以下情况下使用： 在渲染之前，捕捉常见的设置问题。

______________________________________________________________________

🎭 情感导向

`daz_set_emotion`

将情感表达应用于角色（变形+肢体语言）。

论据：

character_label （string）：字符显示标签
emotion （string）：情感名称
intensity （浮动，默认 0.7)：表达式的强度（0.0–1.0）

支持的情绪： happy, sad, angry, surprised, fearful, disgusted, neutral, excited, bored, confident, shy, loving, contemptuous

退货：

{
  "success": true,
  "character": "Genesis 9",
  "emotion": "happy",
  "intensity": 0.7,
  "applied": ["PHMSmile", "PHMBrowsUp", "chest_forward"],
  "notFound": ["PHMEyeSquintL"]
}

缺少变形（由于图形生成差异）的报告如下 not_found 而不会引起错误。

在以下情况下使用： 快速应用可识别的表达式，而不是手动搜索变形名称。

例子：

# Apply full happy expression
daz_set_emotion("Alice", "happy")

# Subtle confident look
daz_set_emotion("Bob", "confident", intensity=0.4)

______________________________________________________________________

📚 内容库导航

`daz_list_categories`

列出父路径下内容库中的子目录。

论据：

parent_path （字符串，默认值 "")：相对于内容库根的路径（例如。， "People/Genesis 9")

退货：

{
  "path": "People/Genesis 9",
  "categories": ["Characters", "Hair", "Clothing", "Expressions"],
  "count": 4
}

在以下情况下使用： 浏览内容库以发现可用类别。

例子：

# List top-level categories
daz_list_categories("")

# Browse Genesis 9 subcategories
daz_list_categories("People/Genesis 9")

______________________________________________________________________

`daz_browse_category`

列表 .duf 内容库类别中的文件。

论据：

category_path （string）：相对于内容库根的路径
sort_by （字符串，默认值 "name")：排序顺序： "name" 或 "date"

退货：

{
  "path": "People/Genesis 9/Hair",
  "files": [
    {"name": "Ade Hair", "path": "/Library/People/Genesis 9/Hair/Ade Hair.duf"},
    {"name": "Braid Updo", "path": "/Library/People/Genesis 9/Hair/Braid Updo.duf"}
  ],
  "count": 2
}

在以下情况下使用： 查找要加载的内容文件路径 daz_load_file.

______________________________________________________________________

`daz_get_content_info`

从读取元数据 .duf 不加载文件。

论据：

file_path （string）：绝对路径 .duf 文件

退货：

{
  "name": "Ade Hair",
  "type": "wearable",
  "requires": ["Genesis 9"],
  "author": "Daz Originals",
  "description": "Long flowing hair for Genesis 9"
}

在以下情况下使用： 加载内容前检查兼容性或要求。

______________________________________________________________________

🎬 场景构图/摄影

`daz_apply_composition_rule`

使用摄影构图规则定位相机。

论据：

camera_label （string）：相机定位
subject_label （string）：以作曲为准
rule （字符串，默认值 "rule-of-thirds")：组成规则

规则：

rule-of-thirds --受试者位于眼睛水平的右侧垂直三分之一处
golden-ratio --主题位于1.618黄金分割
center-frame --以主题为中心，对称
leading-lines --低角度，对角线偏移

退货：

{
  "success": true,
  "camera": "Camera 1",
  "subject": "Genesis 9",
  "rule": "rule-of-thirds"
}

______________________________________________________________________

`daz_frame_shot`

使用标准电影拍摄类型的帧相机。

论据：

camera_label （string）：相机定位
subject_label （string）：以帧为准
shot_type （string）：镜头类型名称

射击类型和距离：

extreme-close-up --25厘米（眼睛/嘴巴细节）
close-up --50厘米（正面）
medium-close-up --90厘米（头部和肩部）
medium-shot --140厘米（腰部以上）
medium-full --200厘米（膝盖向上）
full-shot --400厘米（全身）
wide-shot --700厘米（身体+环境）

退货：

{
  "success": true,
  "camera": "Camera 1",
  "subject": "Genesis 9",
  "shotType": "medium-shot",
  "distance": 140
}

例子：

# Frame a portrait shot
daz_frame_shot("Camera 1", "Genesis 9", "close-up")

# Frame full body
daz_frame_shot("Camera 1", "Genesis 9", "full-shot")

______________________________________________________________________

`daz_apply_camera_angle`

应用相对于对象的标准相机角度预设。

论据：

camera_label （string）：相机定位
subject_label （字符串）：取决于朝向的角度
angle （字符串，默认值 "eye-level")：相机角度预设

角：

eye-level --中性，相机位于被摄对象的眼睛高度
high-angle --上图主体，俯视（脆弱）
low-angle --低于眼睛水平，向上看（有力）
dutch-angle --眼睛水平+15°Z滚动（令人不安）
overhead --正上方（鸟瞰）
worms-eye --地面向上看
over-shoulder --后面和一边

退货：

{
  "success": true,
  "camera": "Camera 1",
  "subject": "Genesis 9",
  "angle": "low-angle"
}

______________________________________________________________________

💾 场景检查点系统

`daz_save_scene_state`

将当前场景状态（变换、变形、灯光属性）保存为命名检查点。

论据：

checkpoint_name （string）：此检查点的名称

捕获内容：

所有图形/骨架：变换属性+活动（非零）变形值
所有摄影机：变换属性
所有灯光：变换属性+通量、阴影柔和度、扩散角度

未捕获的内容： 材质、几何体、HDR圆顶设置、养育关系。

退货：

{
  "success": true,
  "checkpoint": "before_lighting_test",
  "nodesCaptured": 5,
  "savedAt": "2026-04-09T10:15:00"
}

重要提示： 检查点存储在MCP服务器进程内存中，如果服务器重新启动，检查点将丢失。

例子：

# Safe experimentation workflow
daz_save_scene_state("before_lighting_test")
daz_apply_lighting_preset("rembrandt", "Genesis 9")
# Don't like it?
daz_restore_scene_state("before_lighting_test")

______________________________________________________________________

`daz_restore_scene_state`

从指定的检查点还原场景状态。

论据：

checkpoint_name （string）：要还原的检查点的名称

退货：

{
  "success": true,
  "checkpoint": "before_lighting_test",
  "nodesRestored": 5
}

______________________________________________________________________

`daz_list_checkpoints`

列出当前会话中所有已保存的检查点。

退货：

{
  "checkpoints": [
    {"name": "before_lighting_test", "savedAt": "2026-04-09T10:15:00", "nodeCount": 5},
    {"name": "pose_v2", "savedAt": "2026-04-09T10:32:00", "nodeCount": 5}
  ],
  "count": 2
}

______________________________________________________________________

🗺️ 场景布局和邻近度

`daz_get_scene_layout`

所有场景节点的完整空间图，包括位置和边界框。

论据：

include_types （列表，可选）：按类型筛选。价值观： "figures", "cameras", "lights", "props".省略所有类型。

退货：

{
  "nodes": [
    {
      "label": "Genesis 9", "type": "DzFigure",
      "position": {"x": 0, "y": 0, "z": 0},
      "boundingBox": {"min": {...}, "max": {...}, "center": {...}}
    }
  ],
  "count": 8
}

在以下情况下使用： 在添加或移动对象之前，全面了解场景空间布局。

______________________________________________________________________

`daz_find_nearby_nodes`

查找目标节点半径内的所有节点。

论据：

target_label （string）：要四处搜索的中心节点
radius （浮动，默认 200.0)：搜索半径（cm）
include_types （列表，可选）：按类型筛选： "figures", "cameras", "lights", "props"

退货：

{
  "target": "Alice",
  "radius": 200,
  "nearby": [
    {"label": "Bob", "type": "DzFigure", "distance": 120.5, "direction": "front-right"},
    {"label": "Chair", "type": "prop", "distance": 85.0, "direction": "right"}
  ],
  "count": 2
}

方向标签： front, front-right, right, back-right, back, back-left, left, front-left

在以下情况下使用： 查找主题附近的所有角色或道具，检查互动范围。

______________________________________________________________________

⚡ 异步渲染工具

对于长时间运行的操作（完整渲染、动画导出、多相机批处理），异步工具会立即返回 request_id该脚本在DAZ Studio的主线程上连续执行——场景在运行时被锁定，因此后续的场景修改会排在它后面。

关键约束： DAZ Studio是单线程的。异步意味着HTTP连接立即释放——执行仍然是串行的。

`daz_render_async`

异步提交渲染。立即返回 request_id.

论据：

output_path （字符串，可选）：输出文件路径

退货：

{
  "request_id": "render-a3f2b891",
  "status": "queued",
  "submitted_at": "2026-04-09T10:15:00"
}

______________________________________________________________________

`daz_render_with_camera_async`

异步提交特定于摄影机的渲染。

论据：

camera_label （string）：要渲染的摄影机
output_path （字符串，可选）：输出文件路径

______________________________________________________________________

`daz_batch_render_cameras_async`

异步提交多相机批渲染。

论据：

cameras （list\[string\]）：相机标签
output_dir （string）：输出目录
base_filename （字符串，默认值 "render")：基本文件名

______________________________________________________________________

`daz_render_animation_async`

异步提交动画渲染。

论据：

output_dir （string）：输出目录
start_frame （int，可选）：第一帧
end_frame （int，可选）：最后一帧
filename_pattern （字符串，默认值 "frame")：文件名前缀
camera （字符串，可选）：要渲染的摄影机

______________________________________________________________________

`daz_get_request_status`

轮询异步请求的状态（非阻塞、轻量级）。

论据：

request_id （string）：来自异步提交工具的请求ID

退货：

{
  "request_id": "render-a3f2b891",
  "status": "running",
  "progress": 0.0,
  "elapsed_ms": 3200,
  "queue_position": 0
}

状态值： queued, running, completed, failed, cancelled

______________________________________________________________________

`daz_get_request_result`

获取异步请求的最终结果。

论据：

request_id （string）：请求ID
wait （bool，默认值 True)：如果为True，则阻塞直到完成（最多 timeout_seconds)
timeout_seconds （int，默认值 300)：最大等待时间 wait=True

退货（已完成）：

{
  "success": true,
  "result": {...},
  "request_id": "render-a3f2b891",
  "duration_ms": 45230,
  "completed_at": "2026-04-09T10:15:47",
  "status": "completed"
}

______________________________________________________________________

`daz_cancel_request`

取消排队或正在运行的异步请求。

论据：

request_id （string）：请求ID以取消

排队的请求会立即删除。正在运行的请求设置取消标志并调用 killRender().

退货：

{
  "request_id": "render-a3f2b891",
  "status": "cancelled",
  "cancelled_at": "2026-04-09T10:15:05"
}

______________________________________________________________________

`daz_list_requests`

列出所有活动和最近完成的异步请求。

论据：

status_filter （字符串，可选）：按状态筛选： "queued", "running", "completed", "failed", "cancelled"

退货：

{
  "requests": [...],
  "total": 3,
  "queued": 1,
  "running": 1,
  "completed": 1
}

______________________________________________________________________

`daz_set_render_quality`

在渲染之前设置渲染质量预设。

论据：

preset （string）：其中之一 "draft", "preview", "good", "final"

预设	典型时间	用例
`draft`	30s-2min	快速构图检查
`preview`	2-5分钟	客户评论
`good`	10-20分钟	高质量审查
`final`	30分钟至2小时	最终输出

退货：

{
  "preset": "draft",
  "settings": {"Max Samples": 100, "Render Quality": 0.5}
}

______________________________________________________________________

异步工作流示例：

# 1. Set quality and submit
daz_set_render_quality("final")
req = daz_render_async("/renders/final.png")

# 2. Poll status
while True:
    status = daz_get_request_status(req["request_id"])
    if status["status"] in ("completed", "failed", "cancelled"):
        break
    # come back later...

# 3. Or use wait=True in one step
result = daz_get_request_result(req["request_id"], wait=True, timeout_seconds=3600)

______________________________________________________________________

✏️ 修改工具

`daz_set_property`

在场景节点上设置数字属性。

论据：

node_label （string）：节点显示标签或内部名称
property_name （string）：属性显示标签或内部名称
value （float）：新值

退货：

{
  "node": "Genesis 9",
  "property": "X Translate",
  "value": 50.0
}

单位：

翻译：厘米
旋转：度
变形：通常为0-1或百分比

在以下情况下使用： 移动节点、调整变形或更改任何数值属性。

例子：

daz_set_property(node_label="Genesis 9", property_name="X Translate", value=100.0)

______________________________________________________________________

`daz_load_file`

将DAZ Studio文件加载到场景中。

论据：

file_path （string）：文件的绝对路径(.duf, .daz, .obj, .fbx等等）
merge （bool，默认值 True)：如果为真，则合并到场景中；如果为false，则替换场景

退货：

{
  "success": true,
  "file": "/path/to/character.duf"
}

在以下情况下使用： 加载角色、道具、场景或任何内容文件。

例子：

daz_load_file(file_path="/Library/Genesis 9/Character.duf", merge=True)

______________________________________________________________________

🎬 渲染工具

`daz_render`

使用当前DAZ Studio渲染设置触发渲染。

论据：

output_path （string，可选）：输出图像的绝对路径（例如。， "C:/renders/output.png")

退货：

{
  "success": true
}

笔记：

使用DAZ Studio当前配置的渲染设置（尺寸、质量、引擎）
渲染完成前的块数（增加 DAZ_TIMEOUT 对于长渲染）
如果 output_path 省略，使用DAZ Studio配置的输出路径

在以下情况下使用： 渲染当前场景设置。

______________________________________________________________________

🎭 多角色交互工具

`daz_look_at_point`

让角色通过级联的身体参与来看待世界空间点。

论据：

character_label （string）：字符显示标签或内部名称
target_x （float）：要查看的世界X坐标（cm）
target_y （float）：要查看的世界Y坐标（cm）
target_z （float）：要查看的世界Z坐标（cm）
mode （字符串，默认值 "head")：涉及多少身体

- "eyes" -只转动眼睛 - "head" -眼睛+头部旋转 - "neck" -眼睛+头+脖子 - "torso" -眼睛+头部+颈部+胸部 - "full" -包括髋关节在内的全身旋转

退货：

{
  "success": true,
  "character": "Genesis 9",
  "mode": "head",
  "rotatedBones": ["lEye", "rEye", "head"]
}

在以下情况下使用： 让角色通过自然的身体运动来观察3D空间中的特定点。

例子：

# Look at point in front at eye level
daz_look_at_point("Genesis 9", 0, 160, 200, mode="head")

# Full body turn to look behind
daz_look_at_point("Genesis 9", 0, 140, -150, mode="full")

______________________________________________________________________

`daz_look_at_character`

让一个角色看着另一个角色的脸。

论据：

source_label （string）：谁会看
target_label （string）：要查看的字符
mode （字符串，默认值 "head")：身体参与程度（与 daz_look_at_point)

退货：

{
  "success": true,
  "source": "Alice",
  "target": "Bob",
  "mode": "head",
  "targetPosition": {"x": 50, "y": 163, "z": 0},
  "rotatedBones": ["lEye", "rEye", "head"]
}

在以下情况下使用： 在角色之间创造眼神交流或注意力。

例子：

# Alice looks at Bob
daz_look_at_character("Alice", "Bob", mode="head")

# Bob turns whole body to face Alice
daz_look_at_character("Bob", "Alice", mode="full")

______________________________________________________________________

`daz_reach_toward`

使用伪IK将角色的手臂定位到世界空间点。

论据：

character_label （string）：字符显示标签或内部名称
side （弦）：哪只手臂： "left" 或 "right"
target_x （float）：指向的世界X坐标（cm）
target_y （浮动）：世界Y坐标（cm）朝向
target_z （float）：指向的世界Z坐标（cm）

退货：

{
  "success": true,
  "character": "Genesis 9",
  "side": "right",
  "targetDistance": 45.3,
  "bones": ["right shoulder", "right forearm", "right hand"]
}

在以下情况下使用： 用手抓住物体、指向物体或接近目标。

例子：

# Reach right hand toward object at chest height
daz_reach_toward("Genesis 9", "right", 50, 130, 80)

# Reach left hand toward object on left side
daz_reach_toward("Genesis 9", "left", -60, 100, 50)

注：使用简化的IK近似。为了精确定位手部，加载艺术家创建了姿势预设。

______________________________________________________________________

`daz_interactive_pose`

协调两个角色的互动姿势。

论据：

char1_label （string）：第一个字符显示标签
char2_label （string）：第二个字符显示标签
interaction_type （字符串，默认值 "face-each-other")：交互类型

- "face-each-other" -定位并旋转至彼此相对 - "hug" -两个角色互相拥抱 - "shoulder-arm" -Char1用胳膊搂住char2的肩膀 - "handshake" -两人都伸出右手握手

distance （浮动，可选）：字符之间的间距，单位为厘米

退货：

{
  "success": true,
  "char1": "Alice",
  "char2": "Bob",
  "interactionType": "hug",
  "applied": ["facing", "hug arms"]
}

在以下情况下使用： 快速创建常见的双字符交互。

例子：

# Position characters facing each other at conversation distance
daz_interactive_pose("Alice", "Bob", "face-each-other", distance=120)

# Create tight hug
daz_interactive_pose("Alice", "Bob", "hug", distance=30)

# Bob puts arm around Alice's shoulders
daz_interactive_pose("Bob", "Alice", "shoulder-arm")

注：这些是简化的交互姿势。使用后微调位置 daz_set_property.

______________________________________________________________________

🔧 低级工具

`daz_execute`

执行任意内联DazScript代码。

论据：

script （string）：DazScript（JavaScript）源代码
args （dict，可选）：JSON对象在脚本中可作为 args 变量

退货：

{
  "success": true,
  "result": 42,
  "output": ["line from print()"],
  "error": null,
  "request_id": "a3f2b891"
}

脚本要求：

将返回的脚本打包到IIFE中： (function(){ return 42; })()
全局对象可用： Scene, App, MainWindow
通过以下方式访问参数： var value = args.myKey;

在以下情况下使用： 您需要细粒度的控制或高级工具未涵盖的操作。

例子：

script = "(function(){ return Scene.getNumNodes(); })()"

______________________________________________________________________

`daz_execute_file`

从磁盘执行DazScript文件。

论据：

script_file （string）：绝对路径 .dsa 或 .ds 文件
args （dict，可选）：JSON对象可作为 args 在脚本中

退货： 格式与 daz_execute

在以下情况下使用： 运行存储在文件中的复杂脚本，特别是使用 include() 或 getScriptFileName().

______________________________________________________________________

特性

🚀 脚本注册表

高级工具(daz_scene_info, daz_get_node等）使用DazScriptServer脚本注册表：

脚本在启动时注册一次
后续调用按ID执行（无重传）
404上的自动重新注册（DAZ Studio重新启动时）

🔄 自动重新连接

如果DAZ Studio重新启动并清除会话注册表，服务器将自动检测404响应，重新注册所有脚本，并重试该操作。

🛡️ 错误处理

连接失败→ 清除错误消息（“确保DAZ Studio正在运行…”）
超时→ 可采取行动的指导（增加 DAZ_TIMEOUT)
身份验证失败→ 错误消息中的令牌文件位置
脚本错误→ 包含行号和捕获输出的完整错误详细信息

______________________________________________________________________

用法示例

示例1：检查状态

# In Claude Desktop, just ask:
"Check if DAZ Studio is running"

# Claude will use daz_status and report back

示例2：负载和位置字符

1. Load Genesis 9 from /Library/Genesis 9/Genesis9.duf
2. Move it 100cm to the right
3. Get the current scene info

克劳德将：

呼叫 daz_load_file(file_path="/Library/Genesis 9/Genesis9.duf", merge=True)
呼叫 daz_set_property(node_label="Genesis 9", property_name="X Translate", value=100.0)
呼叫 daz_scene_info() 并报告结果

示例3：自定义照明设置

Execute this DazScript to create a three-point light setup:
- Key light at (200, 200, 200) pointing at origin
- Fill light at (-100, 150, 150) pointing at origin
- Rim light at (0, 180, -200) pointing at origin

克劳德将使用 daz_execute 使用适当的DazScript代码。

示例4：批渲染

Render the current scene to these output paths:
- C:/renders/front.png
- C:/renders/side.png
- C:/renders/back.png

Between each render, rotate the character 90 degrees.

克劳德将循环，调整旋转和呼叫 daz_render 对于每个输出。

______________________________________________________________________

故障排除

“无法连接到DAZ Studio”

原因： DazScriptServer插件未运行或未在预期端口上侦听。

解决：

开放DAZ工作室
首选 窗口→ 窗格→ Daz脚本服务器
点击 启动服务器
验证它是否在端口18811上运行（或更新 DAZ_PORT 任何人）

______________________________________________________________________

“身份验证失败（HTTP 401）”

原因： API令牌丢失或不正确。

解决：

检查DazScriptServer UI是否显示身份验证已启用
验证令牌文件是否存在： ~/.daz3d/dazscriptserver_token.txt
从DazScriptServer UI精确复制令牌
集 DAZ_API_TOKEN 使用自定义位置时的环境变量

______________________________________________________________________

“请求在30秒后超时”

原因： 脚本或渲染所花费的时间超过了超时时间。

解决：

增加超时时间： export DAZ_TIMEOUT=120.0
更新Claude Desktop配置，增加超时时间 env 部分
更改配置后重新启动Claude Desktop

______________________________________________________________________

“脚本执行失败”或“找不到节点”

原因： DazScript错误（语法、缺少节点、属性名错误）。

解决：

检查错误消息中的行号和详细信息
验证节点标签是否完全匹配（区分大小写）
使用 daz_get_node 查找可用的属性名称
首先在DAZ Studio Script IDE中手动测试脚本

______________________________________________________________________

发展

运行测试

# Run all tests
uv run pytest tests/ -v

# Run specific test
uv run pytest tests/test_server.py::test_daz_status_ok -v

项目结构

vangard-daz-mcp/
├── src/vangard_daz_mcp/
│   ├── server.py              # Single-file MCP server (all tools)
│   └── dazscript_docs.json    # DazScript documentation loaded by daz_script_help
├── tests/
│   └── test_server.py         # Test suite with respx mocks
├── pyproject.toml             # Project config (version, dependencies)
├── ASYNC_OPERATIONS.md        # Design doc for async rendering system
├── IMPLEMENTATION_PLAN.md     # Phased feature roadmap
└── README.md

建筑

FastMCP 3.x服务器 使用stdio传输
httpx。异步客户端 用于对DazScriptServer的HTTP请求
脚本注册表 用于高级工具（启动时自动注册）
模块级 _http_client 在所有工具调用中共享
生命周期背景 管理客户端初始化和清理

______________________________________________________________________

需求

python 3.11+
依赖关系：

- fastmcp>=2.0 -MCP服务器框架 - httpx>=0.27 -异步HTTP客户端

开发依赖关系：

- pytest>=8.0 - pytest-asyncio>=0.24 - respx>=0.21 -HTTP模拟测试

______________________________________________________________________

局限性

DAZ Studio必须在本地运行（不支持远程DAZ Studio）
DazScriptServer插件必须已安装并处于活动状态
所有场景操作都在DAZ Studio的主线程上执行——即使使用异步工具，操作也会被序列化
渲染运行时，无法执行其他场景操作（场景已锁定）
场景检查点仅在内存中，如果MCP服务器重新启动，则会丢失
不支持二进制数据（渲染图像必须保存到磁盘，不能直接返回）

______________________________________________________________________

贡献

欢迎投稿！需要改进的地方：

材质属性工具（读取/设置表面颜色、纹理、着色器设置）
支持二进制数据（截图，直接返回渲染图像）
使用真实DAZ Studio实例进行集成测试
更多DazScript文档主题，请访问 dazscript_docs.json
其他照明预设和情感定义

______________________________________________________________________

许可证

此项目按原样提供，供DAZ Studio使用。

作者蓝月亮铸造厂

如有疑问或问题，请在GitHub上打开问题。

Vangard Daz MCP

快速接入

详细介绍

范加德·达兹

这是什么？

先决条件

安装

使用紫外线（推荐）

使用pip

配置

环境变量

认证

Claude桌面配置

可用工具

📚 文档工具

daz_script_help

🔍 检测工具

daz_status

daz_scene_info

daz_get_node

🔬 变形发现工具

daz_list_morphs

daz_search_morphs

🌳 场景层次工具

daz_get_node_hierarchy

daz_list_children

daz_get_parent

daz_set_parent

⚡ 批量操作

daz_batch_set_properties

daz_batch_transform

daz_batch_visibility

daz_batch_select

📷 视口和相机控制

daz_set_active_camera

daz_orbit_camera_around

daz_frame_camera_to_node

daz_save_camera_preset

daz_load_camera_preset

🎬 动画系统

daz_set_keyframe

daz_get_keyframes

daz_remove_keyframe

daz_clear_animation

daz_set_frame

daz_set_frame_range

daz_get_animation_info

🎥 高级渲染控制

daz_render_with_camera

daz_get_render_settings

daz_batch_render_cameras

daz_render_animation

📐 空间查询工具

daz_get_world_position

daz_get_bounding_box

daz_calculate_distance

daz_get_spatial_relationship

daz_check_overlap

🔬 物业反思工具

daz_inspect_properties

daz_get_property_metadata

daz_validate_script

💡 照明预设工具

daz_apply_lighting_preset

daz_validate_scene

🎭 情感导向

daz_set_emotion

📚 内容库导航

daz_list_categories

daz_browse_category

daz_get_content_info

🎬 场景构图/摄影

daz_apply_composition_rule

daz_frame_shot

daz_apply_camera_angle

💾 场景检查点系统

daz_save_scene_state

daz_restore_scene_state

daz_list_checkpoints

🗺️ 场景布局和邻近度

`daz_script_help`

`daz_status`

`daz_scene_info`

`daz_get_node`

`daz_list_morphs`

`daz_search_morphs`

`daz_get_node_hierarchy`

`daz_list_children`

`daz_get_parent`

`daz_set_parent`

`daz_batch_set_properties`

`daz_batch_transform`

`daz_batch_visibility`

`daz_batch_select`

`daz_set_active_camera`

`daz_orbit_camera_around`

`daz_frame_camera_to_node`

`daz_save_camera_preset`

`daz_load_camera_preset`

`daz_set_keyframe`

`daz_get_keyframes`

`daz_remove_keyframe`

`daz_clear_animation`

`daz_set_frame`

`daz_set_frame_range`

`daz_get_animation_info`

`daz_render_with_camera`

`daz_get_render_settings`

`daz_batch_render_cameras`

`daz_render_animation`

`daz_get_world_position`

`daz_get_bounding_box`

`daz_calculate_distance`

`daz_get_spatial_relationship`

`daz_check_overlap`

`daz_inspect_properties`

`daz_get_property_metadata`

`daz_validate_script`

`daz_apply_lighting_preset`

`daz_validate_scene`

`daz_set_emotion`

`daz_list_categories`

`daz_browse_category`

`daz_get_content_info`

`daz_apply_composition_rule`

`daz_frame_shot`

`daz_apply_camera_angle`

`daz_save_scene_state`

`daz_restore_scene_state`

`daz_list_checkpoints`

`daz_get_scene_layout`

`daz_find_nearby_nodes`

`daz_render_async`

`daz_render_with_camera_async`

`daz_batch_render_cameras_async`

`daz_render_animation_async`

`daz_get_request_status`

`daz_get_request_result`

`daz_cancel_request`

`daz_list_requests`

`daz_set_render_quality`

`daz_set_property`

`daz_load_file`

`daz_render`

`daz_look_at_point`

`daz_look_at_character`

`daz_reach_toward`

`daz_interactive_pose`

`daz_execute`

`daz_execute_file`