chuk-mcp-stage

Instructions

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)