chuk-mcp-stage

Instructions

Returns the full scene definition including all objects, shots,
animations, and configuration.

Args:
    scene_id: Scene identifier

Returns:
    GetSceneResponse with complete Scene object

Implementation Reference

• src/chuk_mcp_stage/server.py:655-671 (handler)

  The stage_get_scene tool handler - gets complete scene data including objects, shots, animations, and configuration. Decorated with @requires_auth() and @tool for MCP registration.

  @requires_auth()
  @tool  # type: ignore[arg-type]
  async def stage_get_scene(scene_id: str) -> GetSceneResponse:
      """Get complete scene data.
  
      Returns the full scene definition including all objects, shots,
      animations, and configuration.
  
      Args:
          scene_id: Scene identifier
  
      Returns:
          GetSceneResponse with complete Scene object
      """
      manager = get_scene_manager()
      scene = await manager.get_scene(scene_id)
      return GetSceneResponse(scene=scene)

• src/chuk_mcp_stage/models.py:493-496 (schema)

  GetSceneResponse schema - defines the output structure for stage_get_scene tool, containing a complete Scene object.

  class GetSceneResponse(BaseModel):
      """Response containing complete scene."""
  
      scene: Scene

• src/chuk_mcp_stage/scene_manager.py:103-127 (helper)

  SceneManager.get_scene method - retrieves a scene by ID from cache or loads from storage. Used by the stage_get_scene handler.

  async def get_scene(self, scene_id: str) -> Scene:
      """Get scene by ID.
  
      Args:
          scene_id: Scene identifier
  
      Returns:
          Scene object
  
      Raises:
          ValueError: If scene not found
      """
      # Check cache first
      if scene_id in self._scenes:
          return self._scenes[scene_id]
  
      # Check if we have namespace mapping
      if scene_id not in self._scene_to_namespace:
          raise ValueError(f"Scene not found: {scene_id}")
  
      # Load from storage
      namespace_id = self._scene_to_namespace[scene_id]
      scene = await self._load_scene(namespace_id)
      self._scenes[scene_id] = scene
      return scene

• src/chuk_mcp_stage/server.py:63-68 (helper)

  get_scene_manager helper function - gets or creates the global SceneManager singleton used by the stage_get_scene handler.

  def get_scene_manager() -> SceneManager:
      """Get or create the global scene manager."""
      global _scene_manager
      if _scene_manager is None:
          _scene_manager = SceneManager()
      return _scene_manager

• src/chuk_mcp_stage/models.py:316-332 (schema)

  Scene schema - defines the complete 3D scene structure including objects, environment, lighting, shots, and baked animations returned by stage_get_scene.

  class Scene(BaseModel):
      """Complete 3D scene definition."""
  
      id: str = Field(description="Unique scene identifier")
      name: Optional[str] = None
      metadata: SceneMetadata = Field(default_factory=SceneMetadata)
  
      # Scene content
      objects: dict[str, SceneObject] = Field(default_factory=dict)
      environment: Environment = Field(default_factory=Environment)
      lighting: Lighting = Field(default_factory=Lighting)
  
      # Cinematography
      shots: dict[str, Shot] = Field(default_factory=dict)
  
      # Physics integration
      baked_animations: dict[str, BakedAnimation] = Field(default_factory=dict)