Chuk MCP Stage

楚克mcp舞台

3D场景和相机MCP服务器 -物理模拟与运动渲染之间的导演层

  

🌐 快速安装： uvx stage.chukai.io/mcp

楚克mcp舞台 是桥接以下内容的编排层：

• 丘克mcp物理学 （Rapier模拟）→ 场景动画
• 突兀动作/移动 （视频渲染）→ 出口目标

正是 “导演+布景设计师” 它定义了3D世界中的内容、相机的位置以及物理如何驱动运动。

______________________________________________________________________

🎯 这有什么作用

核心能力：

1. 场景图 -定义三维世界（对象、材质、照明）
2. 相机路径 -电影摄影（轨道、追逐、玩偶、静态拍摄）
3. 物理桥 -将场景对象绑定到物理体（默认情况下使用公共Rapier服务）
4. 动画烘焙 -转换物理模拟→ 关键帧
5. 出口 -生成R3F组件、远程项目、glTF

完整的管道：

Physics Simulation → Stage → Motion/Video
(chuk-mcp-physics) → (chuk-mcp-stage) → (chuk-motion/Remotion)

______________________________________________________________________

🚀 快速开始

安装

选项1：从公共URL安装（推荐）

# Install directly from public URL with uvx
uvx stage.chukai.io/mcp

选项2：从PyPI安装

pip install chuk-mcp-stage

选项3：从源代码安装

cd chuk-mcp-stage
pip install -e .

物理学开箱即用！ 使用公共Rapier服务 https://rapier.chukai.io 默认情况下。物理模拟不需要额外的设置。

运行服务器

# STDIO mode (default - for MCP clients like Claude Desktop)
uv run chuk-mcp-stage

# HTTP mode (REST API on port 8000)
uv run chuk-mcp-stage http

# Streamable mode (Server-Sent Events for streaming responses)
uv run chuk-mcp-stage streamable

运输方式：

• 标准：通过stdin/stdout的标准MCP协议（Claude Desktop的默认协议）
• 超文本传输协议：端口8000上的HTTP REST API服务器（由chuk-mcp-r3f-preview使用）
• 可流式传输的：用于流式响应的SSE（服务器发送事件）传输

📖 完整的运输方式指南 -详细的文档、示例和故障排除

在Claude桌面中配置

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

选项1：使用公共URL（推荐）

{
  "mcpServers": {
    "stage": {
      "command": "uvx",
      "args": ["stage.chukai.io/mcp"],
      "env": {
        "RAPIER_SERVICE_URL": "https://rapier.chukai.io"
      }
    }
  }
}

选项2：使用本地安装

{
  "mcpServers": {
    "stage": {
      "command": "chuk-mcp-stage",
      "env": {
        "RAPIER_SERVICE_URL": "https://rapier.chukai.io"
      }
    }
  }
}

物理集成配置

chuk-mcp级通过以下方式与物理模拟集成 丘克mcp物理学 以及Rapier物理引擎。

三种集成方法：

1. 直接Rapier HTTP （默认）-模拟最快

- 直接调用Rapier服务HTTP API - 由...使用 stage_bake_simulation 工具 - 默认为公共服务： https://rapier.chukai.io

1. 通过MCP工具 -最灵活

- 使用chuk mcp物理mcp服务器工具 - 支持分析计算和Rapier模拟 - 需要运行chuk-mcp物理服务器

1. 混合 -两全其美

- 使用MCP工具创建/设置仿真 - 使用直接HTTP进行烘焙轨迹

环境变量：

# Rapier service URL (default: https://rapier.chukai.io)
RAPIER_SERVICE_URL=https://rapier.chukai.io  # Public service
# RAPIER_SERVICE_URL=http://localhost:9000   # Local development

# Rapier timeout in seconds (default: 30.0)
RAPIER_TIMEOUT=30.0

# Physics provider type (default: auto)
PHYSICS_PROVIDER=auto  # or 'rapier', 'mcp'

带定制Rapier服务的Claude桌面：

{
  "mcpServers": {
    "stage": {
      "command": "chuk-mcp-stage",
      "env": {
        "RAPIER_SERVICE_URL": "http://localhost:9000",
        "RAPIER_TIMEOUT": "60.0"
      }
    },
    "physics": {
      "command": "uvx",
      "args": ["chuk-mcp-physics"],
      "env": {
        "RAPIER_SERVICE_URL": "http://localhost:9000"
      }
    }
  }
}

公共猛禽服务：

• 网址： https://rapier.chukai.io
• 不要求进行验证
• 可能适用费率限制
• 非常适合原型制作和演示

当地猛禽服务：

# Run locally with Docker
docker run -p 9000:9000 chuk-rapier-service

# Or from source
cd rapier-service && cargo run --release

看 chuk-mcp物理学自述 获取完整的物理集成指南。

chuk-mcp physics v0.3.1的新功能：

• 52物理工具 （从27扩展）-现在涵盖了约50%的常见物理用例
• 旋转动力学：扭矩、转动惯量、角动量计算
• 弹簧和振荡：简谐运动、阻尼振荡、摆动
• 圆周运动：轨道力学、向心力、逃逸速度
• 高级碰撞：具有恢复系数的三维弹性/非弹性碰撞
• 守恒定律：模拟的能量和动量验证
• 流体动力学：阻力、浮力、终端速度、水下运动

______________________________________________________________________

Google Drive OAuth存储（HTTP模式）

将场景存储在Google云端硬盘中 使用OAuth 2.1身份验证实现安全、持久、用户所有的存储！

跑步时 HTTP模式，chuk-mcp-stage支持Google Drive OAuth集成。用户通过浏览器进行身份验证，场景存储在他们自己的谷歌云端硬盘中 /CHUK/stage/.

优点：

• ✅ 安全OAuth 2.1 -使用PKCE进行行业标准身份验证
• ✅ 用户拥有数据 -场景存储在用户的Google云端硬盘中，而不是您的基础设施中
• ✅ 自动令牌刷新 -无缝身份验证，自动刷新
• ✅ 跨设备访问 -使用Drive从任何设备访问场景
• ✅ 内置共享 -使用Google Drive的原生共享功能共享场景
• ✅ 自然可发现性 -直接在Drive UI中查看/编辑场景文件
• ✅ 无基础设施成本 -提供商的存储成本为零

设置步骤

1.创建谷歌云项目：

• 首选https://console.cloud.google.com/
• 创建新项目（或选择现有项目）
• 启用 Google Drive API
• 首选 OAuth 同意屏幕:

- 用户类型：外部 - 将您的电子邮件添加为测试用户

• 首选 凭证 → 创建 OAuth 2.0客户端ID:

- 应用程序类型：Web应用程序 - 授权重定向URI： http://localhost:8000/oauth/callback

• 复制客户端ID和客户端密码

2.安装谷歌云端硬盘支持：

pip install "chuk-mcp-stage[google_drive]"

3.配置环境：

# Copy example environment file
cp .env.example .env

# Edit .env and add your Google credentials:
# GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
# GOOGLE_CLIENT_SECRET=your-client-secret

4.验证OAuth集成（可选但推荐）：

# Verify that OAuth setup works
python examples/verify_google_drive_oauth.py

这将验证：

• OAuth提供程序正确初始化
• 凭据有效
• 可以注册OAuth端点
• 已准备好与Google Drive集成

5.在HTTP模式下运行服务器：

# Load from .env file
uv run chuk-mcp-stage http

# Or set environment variables directly
export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"
uv run chuk-mcp-stage http

6.授权访问：

当Claude Desktop（或任何MCP客户端）连接时：

1. OAuth流自动启动
2. 浏览器打开进行谷歌授权
3. 用户授予对Google Drive的访问权限
4. 令牌安全存储并自动刷新

OAuth端点 （自动注册）：

• 授权： http://localhost:8000/oauth/authorize
• 令牌： http://localhost:8000/oauth/token
• 发现： http://localhost:8000/.well-known/oauth-authorization-server
• 回拨： http://localhost:8000/oauth/callback

部署到Fly.io

✅ OAuth现在已配置为https://stage.chukai.io和https://physics.chukai.io

看 OAUTH_SETUP_COMPLETE.md 有关生产OAuth设置的详细信息。

对于生产部署，设置机密而不是使用 .env:

# Set Google OAuth credentials as Fly secrets
fly secrets set GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
fly secrets set GOOGLE_CLIENT_SECRET="your-client-secret"

# Set OAuth server URL (use your Fly.io app URL)
fly secrets set OAUTH_SERVER_URL="https://your-app.fly.dev"
fly secrets set GOOGLE_REDIRECT_URI="https://your-app.fly.dev/oauth/callback"

# Optional: Configure session backend for production
fly secrets set SESSION_PROVIDER="redis"
fly secrets set SESSION_REDIS_URL="redis://your-redis-url:6379/0"

# Deploy
fly deploy

重要：使用生产重定向URI更新谷歌云控制台：

• 添加 https://your-app.fly.dev/oauth/callback 到授权重定向URI

存储提供商

chuk mcp stage支持多个存储后端-请参阅 存储配置.md 了解完整细节。

快速比较:

环境变量:

# Storage provider selection (default: vfs-filesystem)
STORAGE_PROVIDER=vfs-filesystem

# Session metadata storage (default: memory)
SESSION_PROVIDER=memory

# For Redis sessions (production)
SESSION_PROVIDER=redis
REDIS_URL=redis://localhost:6379/0

# For AWS S3 storage
STORAGE_PROVIDER=vfs-s3
AWS_ACCESS_KEY_ID=xxx
AWS_SECRET_ACCESS_KEY=xxx
AWS_S3_BUCKET=chuk-artifacts
AWS_REGION=us-east-1

看 存储配置.md 用于：

• 详细的提供商比较
• 迁移指南
• 生产最佳实践
• 故障排除

你的场景在哪里

使用vfs文件系统（默认）:

~/.chuk-artifacts/
└── grid/
    └── {sandbox_id}/
        └── {session_id}/
            └── {namespace_id}/
                ├── scene.json
                ├── animations/
                └── export/

使用Google Drive（vfs文件系统+OAuth）:

Google Drive
└── chuk-artifacts/
    └── {user_id}/
        └── {namespace_id}/
            ├── scene.json
            ├── animations/
            │   └── cannonball.json
            └── export/
                └── remotion/

使用AWS S3（vfs-S3）:

s3://your-bucket/
└── grid/
    └── {sandbox_id}/
        └── {session_id}/
            └── {namespace_id}/
                ├── scene.json
                └── animations/

存储作用域行为:

• 会话作用域 （未经身份验证）→ 仅限本地文件系统，临时
• 用户范围 （已认证）→ 谷歌云端硬盘（如果启用了OAuth）或S3，持久

______________________________________________________________________

📦 刀具表面

场景管理

# Create a new scene
stage_create_scene(name, author, description)

# Add 3D objects
stage_add_object(
    scene_id,
    object_id,
    object_type,  # "box", "sphere", "cylinder", "plane"
    position_x, position_y, position_z,
    radius, size_x, size_y, size_z,
    material_preset,  # "metal-dark", "glass-blue", "plastic-white"
    color_r, color_g, color_b
)

# Set environment & lighting
stage_set_environment(
    scene_id,
    environment_type,  # "gradient", "solid", "hdri"
    lighting_preset    # "three-point", "studio", "noon"
)

相机和镜头

# Add camera shot
stage_add_shot(
    scene_id,
    shot_id,
    camera_mode,  # "orbit", "static", "chase", "dolly"
    start_time,
    end_time,
    focus_object,      # Object to orbit/chase
    orbit_radius,
    orbit_elevation,
    orbit_speed,
    easing  # "ease-in-out-cubic", "spring", "linear"
)

# Get shot details
stage_get_shot(scene_id, shot_id)

物理集成

# Bind object to physics body
stage_bind_physics(
    scene_id,
    object_id,
    physics_body_id  # "rapier://sim-abc/body-ball"
)

# Bake simulation to keyframes
stage_bake_simulation(
    scene_id,
    simulation_id,
    fps=60,
    duration=10.0,
    physics_server_url=None  # Optional: defaults to https://rapier.chukai.io
)

出口

# Export to R3F/Remotion/glTF
stage_export_scene(
    scene_id,
    format,  # "r3f-component", "remotion-project", "gltf", "json"
    output_path
)

# Get complete scene data
stage_get_scene(scene_id)

______________________________________________________________________

🧩 核心概念

阶段对象

A. 舞台对象 是场景图中表示3D视觉元素的条目。每个对象都有：

示例场景JSON：

{
  "id": "demo-scene",
  "name": "Falling Ball Demo",
  "objects": {
    "ground": {
      "id": "ground",
      "type": "plane",
      "transform": {
        "position": {"x": 0, "y": 0, "z": 0},
        "rotation": {"x": 0, "y": 0, "z": 0},
        "scale": {"x": 1, "y": 1, "z": 1}
      },
      "size": {"x": 20, "y": 20, "z": 1},
      "material": {
        "preset": "metal-dark"
      },
      "physics_binding": null
    },
    "ball": {
      "id": "ball",
      "type": "sphere",
      "transform": {
        "position": {"x": 0, "y": 5, "z": 0},
        "rotation": {"x": 0, "y": 0, "z": 0},
        "scale": {"x": 1, "y": 1, "z": 1}
      },
      "radius": 1.0,
      "material": {
        "preset": "glass-blue",
        "color": {"r": 0.3, "g": 0.6, "b": 1.0}
      },
      "physics_binding": "rapier://sim-falling/body-ball"
    }
  },
  "shots": {
    "main": {
      "id": "main",
      "camera_path": {
        "mode": "orbit",
        "focus": "ball",
        "radius": 8.0,
        "elevation": 30.0
      },
      "start_time": 0.0,
      "end_time": 10.0
    }
  }
}

为什么这对LLMs很重要：

当您使用以下命令创建对象时 stage_add_object，您正在修改此场景图。后续操作，如 stage_bind_physics 或 stage_add_shot 参考 相同的对象ID 你创造了。这使得推理变得容易：“我想修改我刚刚创建的球”→ 只需使用 object_id="ball".

创作vs烘焙

楚克mcp舞台 两个不同的阶段:

1.️⃣ 创作阶段（定义世界）

你在做什么： 规划和构图场景

操作：

• 创建场景结构
• 放置对象（图元、位置、材质）
• 定义相机拍摄和移动
• 将对象ID绑定到物理体ID
• 设置环境和照明

输出： 场景定义（仅元数据，尚无动画）

使用的工具：

• stage_create_scene
• stage_add_object
• stage_add_shot
• stage_bind_physics
• stage_set_environment

2.️⃣ 烘焙阶段（生成动画数据）

你在做什么： 将物理模拟转换为可渲染关键帧

操作：

• 连接到物理模拟（Rapier）
• 以所需FPS采样物理状态
• 转换身体位置/旋转→ 关键帧
• 将动画数据存储在场景VFS中

输出： 带时间戳的关键帧数组（位置、旋转、每帧速度）

使用的工具：

• stage_bake_simulation （连接到物理，生成关键帧）
• stage_export_scene （导出场景+烘焙动画）

典型流量

┌──────────────────────────────────────────────────────────────┐
│ AUTHORING PHASE                                              │
├──────────────────────────────────────────────────────────────┤
│ 1. stage_create_scene(name="demo")                           │
│    → Creates empty scene graph                               │
│                                                               │
│ 2. stage_add_object(id="ground", type="plane", ...)          │
│    stage_add_object(id="ball", type="sphere", y=10, ...)     │
│    → Defines visual objects (no motion yet)                  │
│                                                               │
│ 3. stage_set_environment(lighting="three-point")             │
│    → Sets lights, background                                 │
│                                                               │
│ 4. Use physics MCP to create simulation                      │
│    create_simulation(gravity_y=-9.81)                        │
│    add_rigid_body(sim_id, body_id="ball", ...)               │
│    → Physics oracle creates simulation                       │
│                                                               │
│ 5. stage_bind_physics(object_id="ball",                      │
│                       body_id="rapier://sim-id/body-ball")   │
│    → Links visual object to physics body                     │
│                                                               │
│ 6. step_simulation(sim_id, steps=600)  # 10s @ 60 FPS        │
│    → Physics oracle runs simulation                          │
│                                                               │
│ 7. stage_add_shot(mode="orbit", focus="ball", ...)           │
│    → Defines camera cinematography                           │
├──────────────────────────────────────────────────────────────┤
│ BAKING PHASE                                                 │
├──────────────────────────────────────────────────────────────┤
│ 8. stage_bake_simulation(scene_id, sim_id, fps=60, dur=10)  │
│    → Fetches physics data from Rapier                        │
│    → Converts to keyframes                                   │
│    → Stores in /animations/ball.json                         │
│                                                               │
│ 9. stage_export_scene(format="remotion-project")            │
│    → Generates R3F/Remotion code                             │
│    → Includes baked animation data                           │
│    → Returns artifact URIs                                   │
└──────────────────────────────────────────────────────────────┘

   Authoring = "What should exist and where?"
   Baking    = "What motion actually happened?"

关键见解： 创作是 声明式 （你定义意图），烘焙是 计算的 （物理预言机产生运动）。

______________________________________________________________________

🎬 示例工作流程

1.简单的落球演示

# 1. Create scene
scene = await stage_create_scene(
    name="falling-ball-demo",
    description="Ball falling under gravity"
)

# 2. Add ground plane
await stage_add_object(
    scene_id=scene.scene_id,
    object_id="ground",
    object_type="plane",
    size_x=20.0,
    size_y=20.0,
    material_preset="metal-dark"
)

# 3. Add falling ball
await stage_add_object(
    scene_id=scene.scene_id,
    object_id="ball",
    object_type="sphere",
    radius=1.0,
    position_y=5.0,
    material_preset="glass-blue",
    color_r=0.3,
    color_g=0.5,
    color_b=1.0
)

# 4. Add orbiting camera shot
await stage_add_shot(
    scene_id=scene.scene_id,
    shot_id="orbit-shot",
    camera_mode="orbit",
    focus_object="ball",
    orbit_radius=8.0,
    orbit_elevation=30.0,
    orbit_speed=0.1,
    start_time=0.0,
    end_time=10.0
)

# 5. Export to Remotion
result = await stage_export_scene(
    scene_id=scene.scene_id,
    format="remotion-project"
)

2.物理驱动动画

注： 此示例使用 公共猛禽服务 (https://rapier.chukai.io)默认情况下。无需配置！

# 1. Create physics simulation (chuk-mcp-physics)
sim = await create_simulation(gravity_y=-9.81)

await add_rigid_body(
    sim_id=sim.sim_id,
    body_id="ball",
    body_type="dynamic",
    shape="sphere",
    radius=1.0,
    position=[0, 5, 0]
)

# 2. Create scene
scene = await stage_create_scene(name="physics-demo")

await stage_add_object(
    scene_id=scene.scene_id,
    object_id="ball",
    object_type="sphere",
    radius=1.0,
    position_y=5.0
)

# 3. Bind physics to visual
await stage_bind_physics(
    scene_id=scene.scene_id,
    object_id="ball",
    physics_body_id=f"rapier://{sim.sim_id}/body-ball"
)

# 4. Run simulation (chuk-mcp-physics)
await step_simulation(sim_id=sim.sim_id, steps=600)

# 5. Bake physics → keyframes
await stage_bake_simulation(
    scene_id=scene.scene_id,
    simulation_id=sim.sim_id,
    fps=60,
    duration=10.0
)

# 6. Export with animation data
await stage_export_scene(
    scene_id=scene.scene_id,
    format="r3f-component"
)

______________________________________________________________________

📚 例子

这 examples/ 目录包含所有功能的现成运行演示。

🌟 从这里开始：黄金之路

显示完整管道的典型示例：

uv run examples/00_golden_path_ball_throw.py

此示例演示了：

• ✅ 创作阶段 -场景创建、对象放置、相机拍摄
• ✅ 烘烤阶段 -物理模拟→ 关键帧（概念性）
• ✅ 出口阶段 -生成R3F/远程代码
• ✅ 工件URI -chuk-mcp stage如何与chuk工件集成
• ✅ 两相模型 -声明性→ 计算的
• ✅ 完整的管道 -物理学→ 阶段→ 运动→ Video

这是理解CHUK堆栈内聚性的最佳示例。

入门指南

# Run any example
uv run examples/00_golden_path_ball_throw.py  # ⭐ Start here!
uv run examples/01_simple_scene.py
uv run examples/02_physics_integration_demo.py
uv run examples/03_camera_shots_demo.py
uv run examples/04_export_formats.py
uv run examples/05_full_physics_workflow.py

示例指南

输出示例

00_goldn_path_ball_throw.py ⭐ - 完整的管道演示

📂 Artifact URIs (Not file contents!):
   Scene data:  artifact://stage/golden-path-ball-throw/exports/scene.json
   R3F:         artifact://stage/golden-path-ball-throw/exports/r3f/Scene.tsx
   Remotion:    artifact://stage/golden-path-ball-throw/exports/remotion/

🎬 Complete Pipeline:
   1. Authoring   - Define scene structure   ✓
   2. Physics     - Create simulation         (conceptual)
   3. Binding     - Link objects → bodies     ✓
   4. Baking      - Physics → keyframes       (conceptual)
   5. Export      - Scene → R3F/Remotion      ✓
   6. Render      - Remotion → MP4            (external)

01_simple_scene.py -创建落球场景

✓ Created scene: falling-ball
✓ Added ground plane
✓ Added ball at (0, 5, 0)
✓ Added orbit camera shot (10s)

03_camera_shots_demo.py -38秒多镜头序列

📹 Shot Sequence:
   •   0.0s -  10.0s  ORBIT   - Smooth orbit around center
   •  10.0s -  15.0s  STATIC  - Static wide angle
   •  15.0s -  22.0s  DOLLY   - Dolly tracking shot
   •  22.0s -  28.0s  CHASE   - Chase with spring easing
   •  28.0s -  33.0s  ORBIT   - Fast linear orbit
   •  33.0s -  38.0s  STATIC  - Low angle hero shot

04_export_formats.py -导出为所有格式

✓ JSON:     /exports/scene.json
✓ R3F:      /exports/r3f/Scene.tsx
✓ Remotion: /exports/remotion/Root.tsx
✓ glTF:     /exports/scene.gltf

Note: In production, these would be artifact URIs like:
  artifact://stage/{scene_id}/exports/scene.json

05_full_physics_workflow.py -显示完整的管道

🎬 Complete Pipeline:
   1. Physics Simulation (chuk-mcp-physics)
   2. Scene Composition (chuk-mcp-stage) ✓
   3. Bind Physics ✓
   4. Bake Simulation (Rapier service)
   5. Export (R3F/Remotion) ✓
   6. Render Video (Remotion)

学习路径

推荐订单：

1. 从开始 00_golden_path_ball_throw.py ⭐ - 首先查看完整的管道
2. 了解基础知识 01_simple_scene.py
3. 探索相机控制 03_camera_shots_demo.py
4. 学习导出选项 04_export_formats.py
5. 查看物理概念 02_physics_integration_demo.py
6. 完整的工作流程 05_full_physics_workflow.py

为什么要从黄金之路开始？ 它向您展示 目的地 （整个管道），然后再分成单件。您将了解CHUK堆栈中所有工具是如何协同工作的。

______________________________________________________________________

🏗️ 建筑

场景存储

• 后端：chuk工件（VFS支持的工作区）
• 格式：具有嵌套对象的JSON场景定义
• 范围：会话（临时）、用户（持久）、SANDBOX（共享）

每个场景都是一个工作区，包含：

/scene.json          # Scene definition
/animations/         # Baked keyframe data
  ball.json
  car.json
/export/             # Generated R3F/Remotion code
  r3f/
  remotion/

相机路径模式

材质预设

• metal-dark, metal-light
• glass-clear, glass-blue, glass-green
• plastic-red, plastic-blue, plastic-white
• rubber-black
• wood-oak

导出格式

• R3F组件 -React三纤维 .tsx 文件
• 搬迁项目 -完整项目 package.json
• glTF -静态3D场景文件
• JSON -原始场景数据

VFS和工件集成

为什么这很重要

与内联返回大型JSON blob的典型MCP服务器不同，chuk-MCP-stage返回 工件URI:

# ❌ Traditional approach (bloated)
{
  "scene_data": "......",
  "r3f_component": "......",
  "animations": "......"
}

# ✅ CHUK approach (cohesive)
{
  "scene": "artifact://stage/demo-scene/scene.json",
  "component": "artifact://stage/demo-scene/export/r3f/Scene.tsx",
  "animations": "artifact://stage/demo-scene/animations/ball.json"
}

优点：

1. 没有内联膨胀 -工具返回URI，而不是海量数据
2. 持久存储 -场景在会话中存活（如果使用USER作用域）
3. VFS操作 -使用 vfs_ls, vfs_find, vfs_cp 管理场景文件
4. 跨工具共享 -其他MCP服务器可以访问相同的工件
5. 检查点支持 -场景迭代的版本控制

存储模型

每个场景= 一个工作空间 在楚克文物中：

artifact://stage/{scene_id}/
├── scene.json              # Scene definition
├── animations/             # Baked physics keyframes
│   ├── ball.json          # Per-object animation data
│   ├── car.json
│   └── character.json
└── export/                 # Generated code
    ├── r3f/               # React Three Fiber
    │   ├── Scene.tsx
    │   ├── Camera.tsx
    │   └── animations.json
    ├── remotion/          # Remotion project
    │   ├── Composition.tsx
    │   ├── Root.tsx
    │   └── package.json
    └── gltf/              # 3D model exports
        └── scene.gltf

示例：使用工件

# 1. Create scene (returns artifact URI)
result = await stage_create_scene(name="demo")
# → {"scene_id": "demo-xyz", "workspace": "artifact://stage/demo-xyz"}

# 2. Add objects and bake simulation
# ... (authoring phase)

# 3. Export to Remotion (returns artifact URIs)
export_result = await stage_export_scene(
    scene_id="demo-xyz",
    format="remotion-project",
    output_path="/export/remotion"
)
# → {
#     "composition": "artifact://stage/demo-xyz/export/remotion/Composition.tsx",
#     "root": "artifact://stage/demo-xyz/export/remotion/Root.tsx",
#     "package": "artifact://stage/demo-xyz/export/remotion/package.json"
# }

# 4. Use VFS tools to explore (via chuk-virtual-fs MCP)
await vfs_ls("artifact://stage/demo-xyz/export/remotion")
# → ["Composition.tsx", "Root.tsx", "package.json"]

await vfs_read("artifact://stage/demo-xyz/export/remotion/package.json")
# → Returns package.json contents

# 5. Copy to another location
await vfs_cp(
    "artifact://stage/demo-xyz/export/remotion",
    "artifact://projects/my-video"
)

与其他CHUK工具集成

chuk-mcp-r3f-综述 可以直接预览场景：

# Stage creates scene
scene_uri = "artifact://stage/demo-xyz/export/r3f/Scene.tsx"

# R3F preview server loads it
await r3f_preview_scene(scene_uri)
# → Opens interactive 3D preview in browser

突兀运动 可以渲染烘焙动画：

# Stage bakes physics
animation_uri = "artifact://stage/demo-xyz/animations/ball.json"

# Motion applies spring physics to keyframes
await motion_apply_spring(animation_uri, stiffness=100)

这就是 CHUK堆栈凝聚力 闪耀：每个工具都使用相同的工件URI语言。

______________________________________________________________________

🔗 与CHUK Stack集成

┌─────────────────────────────────────────────────────────────┐
│                     chuk-mcp-stage                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ Scene Graph  │  │   Camera     │  │  Physics Bridge  │  │
│  │              │  │   Paths      │  │                  │  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
└─────────┼─────────────────┼───────────────────┼────────────┘
          │                 │                   │
          ▼                 ▼                   ▼
┌─────────────────┐  ┌─────────────┐  ┌─────────────────────┐
│ chuk-artifacts  │  │ chuk-motion │  │  chuk-mcp-physics   │
│                 │  │             │  │      (Rapier)       │
│ • scene.json    │  │ • easing    │  │                     │
│ • assets/       │  │ • springs   │  │ • rigid bodies      │
│ • animations/   │  │ • keyframes │  │ • constraints       │
└─────────────────┘  └──────┬──────┘  │ • sim state         │
                            │         └─────────────────────┘
                            ▼
                   ┌─────────────────┐
                   │ Remotion        │
                   │                 │
                   │ • R3F render    │
                   │ • video export  │
                   │ • MP4 output    │
                   └─────────────────┘

______________________________________________________________________

🎯 用例

立即获胜

1. 物理讲解员视频 -自动生成教育内容
2. 模拟即服务 -LLM可以请求可视化
3. 程序性B-Roll -合成运动图形

垂直播放

1. 赛车运动可视化 -赛道、制动区、超车
2. 3D数据故事 -电影摄影动画数据集
3. 科学新闻学 -直观地渲染模型预测

怪异而强大

1. 可解释的AI动画 -展示模特们在想什么
2. 虚拟物理实验室 -可编程实验
3. 特工摄影 -AI选择相机路径

______________________________________________________________________

📐 数据模型

所有型号均为 Pydantic土著 随着 没有字典:

from chuk_mcp_stage.models import (
    Scene,              # Complete scene definition
    SceneObject,        # 3D object (mesh, material, transform)
    Shot,               # Camera path + time range
    CameraPath,         # Camera movement definition
    Material,           # PBR material properties
    Environment,        # Lighting & background
    BakedAnimation,     # Physics → keyframes
)

到处都有枚举：

ObjectType.SPHERE
MaterialPreset.GLASS_BLUE
CameraPathMode.ORBIT
LightingPreset.THREE_POINT
ExportFormat.R3F_COMPONENT

______________________________________________________________________

🧪 测试

# Run tests
pytest

# With coverage
pytest --cov=chuk_mcp_stage

______________________________________________________________________

🛠️ 发展

# Install dev dependencies
pip install -e ".[dev]"

# Format
black src/ tests/

# Lint
ruff check src/

# Type check
mypy src/

______________________________________________________________________

📄 许可证

MIT许可证-详见许可证

______________________________________________________________________

🌟 为什么这很重要

大多数人可以： ✅ 运行模拟 ✅ 生成图表 ✅ 动态文字

几乎没有人能：

模拟→ 直接→ 渲染→ 解释→ 出口

chuk-mcp stage为您提供了该管道。

你不再渲染东西了。 你是 制作可解释的模拟作为媒介.

______________________________________________________________________

建于❤️ 对于CHUK AI堆栈