chuk-mcp-stage

Instructions

Converts the scene definition into code/files that can be used
with React Three Fiber or Remotion for rendering.

Args:
    scene_id: Scene identifier
    format: Export format - "r3f-component", "remotion-project", "gltf", "json"
    output_path: Optional VFS path for output (auto-generated if None)

Returns:
    ExportSceneResponse with output paths

Tips for LLMs:
    - "r3f-component": Generate React Three Fiber .tsx files
    - "remotion-project": Full Remotion project with package.json
    - "gltf": Static 3D scene file
    - "json": Raw scene JSON data
    - Exported files are in the scene's VFS workspace
    - Use chuk-artifacts to retrieve exported files

Example:
    result = await stage_export_scene(
        scene_id=scene_id,
        format="remotion-project"
    )
    print(f"Exported to {result.output_path}")
    # Files available at result.artifacts paths

Implementation Reference

• src/chuk_mcp_stage/server.py:604-652 (handler)

  Main handler function stage_export_scene decorated with @tool and @requires_auth(). Handles exporting scenes to different formats (R3F, Remotion, glTF, JSON) using SceneExporter.

  @requires_auth()
  @tool  # type: ignore[arg-type]
  async def stage_export_scene(
      scene_id: str, format: str = "r3f-component", output_path: Optional[str] = None
  ) -> ExportSceneResponse:
      """Export scene to R3F, Remotion, or glTF format.
  
      Converts the scene definition into code/files that can be used
      with React Three Fiber or Remotion for rendering.
  
      Args:
          scene_id: Scene identifier
          format: Export format - "r3f-component", "remotion-project", "gltf", "json"
          output_path: Optional VFS path for output (auto-generated if None)
  
      Returns:
          ExportSceneResponse with output paths
  
      Tips for LLMs:
          - "r3f-component": Generate React Three Fiber .tsx files
          - "remotion-project": Full Remotion project with package.json
          - "gltf": Static 3D scene file
          - "json": Raw scene JSON data
          - Exported files are in the scene's VFS workspace
          - Use chuk-artifacts to retrieve exported files
  
      Example:
          result = await stage_export_scene(
              scene_id=scene_id,
              format="remotion-project"
          )
          print(f"Exported to {result.output_path}")
          # Files available at result.artifacts paths
      """
      manager = get_scene_manager()
      scene = await manager.get_scene(scene_id)
      vfs = await manager.get_scene_vfs(scene_id)
  
      export_format = ExportFormat(format)
  
      # Use exporter
      artifacts = await SceneExporter.export_scene(scene, export_format, vfs, output_path)
  
      # Determine main output path
      main_path = artifacts.get("scene") or artifacts.get("component") or artifacts.get("gltf") or "/"
  
      return ExportSceneResponse(
          scene_id=scene_id, format=export_format, output_path=main_path, artifacts=artifacts
      )

• src/chuk_mcp_stage/exporters.py:40-66 (helper)

  SceneExporter.export_scene static method that routes to format-specific export methods (_export_json, _export_r3f, _export_remotion, _export_gltf) based on the ExportFormat enum.

  async def export_scene(
      scene: Scene,
      format: ExportFormat,
      vfs,
      output_path: Optional[str] = None,
  ) -> dict[str, str]:
      """Export scene to specified format.
  
      Args:
          scene: Scene to export
          format: Export format
          vfs: VFS instance for writing files
          output_path: Optional output path override
  
      Returns:
          Dict of generated file paths
      """
      if format == ExportFormat.JSON:
          return await SceneExporter._export_json(scene, vfs, output_path)
      elif format == ExportFormat.R3F_COMPONENT:
          return await SceneExporter._export_r3f(scene, vfs, output_path)
      elif format == ExportFormat.REMOTION_PROJECT:
          return await SceneExporter._export_remotion(scene, vfs, output_path)
      elif format == ExportFormat.GLTF:
          return await SceneExporter._export_gltf(scene, vfs, output_path)
      else:
          raise ValueError(f"Unsupported export format: {format}")

• src/chuk_mcp_stage/models.py:481-491 (schema)

  ExportSceneResponse schema defining the response structure with scene_id, format (ExportFormat enum), output_path, and artifacts dict.

  class ExportSceneResponse(BaseModel):
      """Response from exporting scene."""
  
      scene_id: str
      format: ExportFormat
      output_path: str  # VFS path to exported content
      artifacts: dict[str, str] = Field(
          default_factory=dict, description="Additional generated files"
      )
      message: str = "Scene exported successfully"

• src/chuk_mcp_stage/models.py:91-97 (schema)

  ExportFormat enum defining the supported export formats: R3F_COMPONENT, REMOTION_PROJECT, GLTF, and JSON.

  class ExportFormat(str, Enum):
      """Export template formats."""
  
      R3F_COMPONENT = "r3f-component"  # React Three Fiber component
      REMOTION_PROJECT = "remotion-project"  # Full Remotion project
      GLTF = "gltf"  # Static glTF scene
      JSON = "json"  # Raw JSON scene data

• src/chuk_mcp_stage/exporters.py:19-67 (helper)

  SceneExporter class with helper methods for exporting scenes including _ensure_directory utility and format-specific export implementations.

  class SceneExporter:
      """Exports scenes to various formats."""
  
      @staticmethod
      async def _ensure_directory(vfs, path: str) -> None:
          """Ensure directory exists by creating all parent directories.
  
          Args:
              vfs: VFS instance
              path: Directory path to create
          """
          if path == "/" or not path:
              return
  
          parts = [p for p in path.split("/") if p]
          current = ""
          for part in parts:
              current = f"{current}/{part}"
              await vfs.mkdir(current)
  
      @staticmethod
      async def export_scene(
          scene: Scene,
          format: ExportFormat,
          vfs,
          output_path: Optional[str] = None,
      ) -> dict[str, str]:
          """Export scene to specified format.
  
          Args:
              scene: Scene to export
              format: Export format
              vfs: VFS instance for writing files
              output_path: Optional output path override
  
          Returns:
              Dict of generated file paths
          """
          if format == ExportFormat.JSON:
              return await SceneExporter._export_json(scene, vfs, output_path)
          elif format == ExportFormat.R3F_COMPONENT:
              return await SceneExporter._export_r3f(scene, vfs, output_path)
          elif format == ExportFormat.REMOTION_PROJECT:
              return await SceneExporter._export_remotion(scene, vfs, output_path)
          elif format == ExportFormat.GLTF:
              return await SceneExporter._export_gltf(scene, vfs, output_path)
          else:
              raise ValueError(f"Unsupported export format: {format}")