chuk-mcp-vfs

Instructions

Implementation Reference

• src/chuk_mcp_vfs/server.py:48-52 (registration)

  Registers the 'workspace_create' tool with the MCP server using @server.tool decorator, delegating execution to WorkspaceTools instance.
  @server.tool async def workspace_create(request: WorkspaceCreateRequest): """Create a new virtual filesystem workspace.""" return await workspace_tools.workspace_create(request)
• src/chuk_mcp_vfs/workspace_tools.py:27-53 (handler)

  Main handler function in WorkspaceTools class that processes WorkspaceCreateRequest, calls workspace_manager.create_workspace, and constructs WorkspaceCreateResponse.
  async def workspace_create( self, request: WorkspaceCreateRequest ) -> WorkspaceCreateResponse: """ Create a new workspace. Args: request: WorkspaceCreateRequest with name, provider, template, scope, and config Returns: WorkspaceCreateResponse with workspace info """ info = await self.workspace_manager.create_workspace( name=request.name, provider_type=request.provider, provider_config=request.provider_config, template=request.template, scope=request.scope, ) return WorkspaceCreateResponse( name=info.name, provider=info.provider_type, created_at=info.created_at, current_path=info.current_path, is_mounted=info.is_mounted, )
• src/chuk_mcp_vfs/workspace_manager.py:63-152 (helper)

  Core helper method in WorkspaceManager that creates the actual workspace namespace using ArtifactStore.create_namespace, handles scoping, templates, and tracks workspace state.
  async def create_workspace( self, name: str, provider_type: ProviderType = ProviderType.MEMORY, provider_config: dict[str, Any] | None = None, template: str | None = None, scope: StorageScope = StorageScope.SESSION, user_id: str | None = None, session_id: str | None = None, ) -> WorkspaceInfo: """ Create a new workspace using the unified namespace architecture. Args: name: Workspace name provider_type: Storage provider type provider_config: Provider-specific configuration template: Optional template to initialize from scope: Storage scope (SESSION, USER, or SANDBOX) user_id: User ID (auto-detected from context if None) session_id: Session ID (auto-detected from context if None) Returns: WorkspaceInfo for the created workspace Raises: ValueError: If workspace name already exists in current scope """ async with self._lock: # Sync with existing namespaces first await self._sync_namespaces() # Get user_id and session_id from context if not provided if user_id is None and scope in (StorageScope.USER, StorageScope.SESSION): try: user_id = get_user_id() except Exception: user_id = "default" if session_id is None and scope == StorageScope.SESSION: try: session_id = get_session_id() except Exception: session_id = None # Check if workspace with this name already exists in this scope existing = self.list_workspaces() for ws in existing: if ws.name == name: raise ValueError(f"Workspace '{name}' already exists") # Create namespace vfs_type = self._provider_type_to_vfs_type(provider_type) config = provider_config or {} namespace_info = await self._store.create_namespace( type=NamespaceType.WORKSPACE, name=name, scope=scope, user_id=user_id, session_id=session_id, provider_type=vfs_type, provider_config=config, ) # Apply template if specified if template: vfs = self._store.get_namespace_vfs(namespace_info.namespace_id) await self._apply_template(vfs, template) # Create workspace info info = WorkspaceInfo( name=name, provider_type=provider_type, created_at=namespace_info.created_at, current_path="/", metadata={ "namespace_id": namespace_info.namespace_id, "scope": scope.value, "provider_config": config, }, ) self._namespace_to_info[namespace_info.namespace_id] = info # Set as current if first workspace if self._current_namespace_id is None: self._current_namespace_id = namespace_info.namespace_id return info
• src/chuk_mcp_vfs/models.py:48-56 (schema)

  Pydantic schema for WorkspaceCreateRequest, defining input parameters with validation for creating a workspace.
  class WorkspaceCreateRequest(BaseModel): """Request to create a workspace""" name: str = Field(..., min_length=1, pattern=r"^[a-zA-Z0-9_-]+$") provider: ProviderType = ProviderType.MEMORY scope: StorageScope = StorageScope.SESSION template: str | None = None provider_config: dict[str, Any] = Field(default_factory=dict)
• src/chuk_mcp_vfs/models.py:58-66 (schema)

  Pydantic schema for WorkspaceCreateResponse, defining the output structure returned by the tool.
  class WorkspaceCreateResponse(BaseModel): """Response from workspace creation""" name: str provider: ProviderType created_at: datetime current_path: str is_mounted: bool