chuk-mcp-stage

Instructions

Implementation Reference

• src/chuk_mcp_stage/server.py:76-143 (handler)

  Main implementation of stage_create_scene tool. Handles creating a new 3D scene with UUID generation, authentication-based storage scope selection (USER for authenticated users, SESSION otherwise), and returns CreateSceneResponse with scene_id.
  @requires_auth() @tool # type: ignore[arg-type] async def stage_create_scene( name: Optional[str] = None, author: Optional[str] = None, description: Optional[str] = None, _external_access_token: Optional[str] = None, # Injected by OAuth middleware _user_id: Optional[str] = None, # Injected by OAuth middleware ) -> CreateSceneResponse: """Create a new 3D scene for composition. Initializes a new scene workspace backed by chuk-artifacts. The scene can contain 3D objects, lighting, camera shots, and physics bindings. Args: name: Optional scene name (e.g., "pendulum-demo", "f1-silverstone-t1") author: Optional author name for metadata description: Optional scene description Returns: CreateSceneResponse with scene_id and success message Tips for LLMs: - Scene ID is auto-generated (UUID) - Scenes are stored in USER scope (Google Drive) if authenticated, SESSION scope otherwise - Use the scene_id for all subsequent operations - Typical workflow: create_scene → add_objects → add_shots → export Example: scene = await stage_create_scene( name="falling-ball-demo", author="Claude", description="Simple gravity demonstration" ) # Use scene.scene_id for next steps """ from chuk_artifacts import StorageScope from chuk_mcp_server import get_user_id from .models import SceneMetadata manager = get_scene_manager() # Generate scene ID import uuid scene_id = f"scene-{uuid.uuid4().hex[:8]}" # Create metadata metadata = SceneMetadata(author=author, description=description) # Determine storage scope and user_id based on authentication user_id = get_user_id() if user_id: # User is authenticated via OAuth - store in USER scope (Google Drive) scope = StorageScope.USER logger.info(f"Creating scene in USER scope for user {user_id}") else: # No authentication - use SESSION scope (ephemeral) scope = StorageScope.SESSION logger.info("Creating scene in SESSION scope (no user authentication)") # Create scene scene = await manager.create_scene( scene_id=scene_id, name=name, metadata=metadata, scope=scope, user_id=user_id ) return CreateSceneResponse(scene_id=scene.id, message=f"Scene '{name or scene_id}' created")
• src/chuk_mcp_stage/models.py:347-351 (schema)

  CreateSceneResponse model - defines the return type for stage_create_scene tool with scene_id and message fields.
  class CreateSceneResponse(BaseModel): """Response from creating a scene.""" scene_id: str message: str = "Scene created successfully"
• src/chuk_mcp_stage/models.py:307-313 (schema)

  SceneMetadata model - defines optional metadata fields (author, created, description, tags) for scenes.
  class SceneMetadata(BaseModel): """Scene metadata.""" author: Optional[str] = None created: Optional[str] = None description: Optional[str] = None tags: list[str] = Field(default_factory=list)
• src/chuk_mcp_stage/scene_manager.py:56-101 (helper)

  SceneManager.create_scene method - core helper that creates workspace namespace via chuk-artifacts, instantiates Scene object, persists to storage, and caches in memory.
  async def create_scene( self, scene_id: str, name: Optional[str] = None, metadata: Optional[SceneMetadata] = None, scope: StorageScope = StorageScope.SESSION, user_id: Optional[str] = None, ) -> Scene: """Create a new scene. Args: scene_id: Unique scene identifier name: Optional scene name metadata: Optional scene metadata scope: Storage scope (SESSION, USER, or SANDBOX) user_id: User ID (required for USER scope) Returns: Created Scene object """ logger.info(f"Creating scene: {scene_id}") # Create workspace namespace for this scene namespace = await self._store.create_namespace( type=NamespaceType.WORKSPACE, name=name or scene_id, scope=scope, user_id=user_id, ) # Create scene object scene = Scene( id=scene_id, name=name, metadata=metadata or SceneMetadata(), ) # Save to storage await self._save_scene(scene, namespace.namespace_id) # Cache self._scenes[scene_id] = scene self._scene_to_namespace[scene_id] = namespace.namespace_id logger.info(f"Scene created: {scene_id} -> namespace {namespace.namespace_id}") return scene
• src/chuk_mcp_stage/server.py:76-77 (registration)

  Tool registration using @requires_auth() and @tool decorators that register stage_create_scene as an MCP tool endpoint.
  @requires_auth() @tool # type: ignore[arg-type]