IBM Core Content Services MCP Server

Instructions

Implementation Reference

• src/cs_mcp_server/tools/folders.py:391-505 (handler)

  The core handler function for the 'update_folder' MCP tool. It is decorated with @mcp.tool(name="update_folder"), takes folder identifier, optional class_identifier, and folder_properties as inputs, constructs and executes a GraphQL mutation to update the folder, handles errors, and returns the updated Folder object or ToolError.

  @mcp.tool(
      name="update_folder",
  )
  async def update_folder(
      identifier: str,
      class_identifier: Optional[str] = None,
      folder_properties: Optional[FolderPropertiesInput] = None,
  ) -> Union[Folder, ToolError]:
      """
      **PREREQUISITES IN ORDER**: To use this tool, you MUST call two other tools first in a specific sequence.
      1. determine_class tool to get the class_identifier.
      2. get_class_property_descriptions to get a list of valid properties for the given class_identifier
  
      Description:
      Updates an existing folder in the content repository with specified properties.
  
      :param identifier: String The folder identifier or path (required). This can be either the folder's ID (GUID) or its path in the repository (e.g., "/Folder1/folder123").
      :param class_identifier: String Optional. The class identifier for the folder. If provided, allows changing the folder's class.
      :param folder_properties: FolderPropertiesInput Properties to update for the folder including name, etc
  
      :returns: If successful, returns a Folder object with its updated properties.
               If unsuccessful, returns a ToolError with details about the failure.
      """
      method_name = "update_folder"
      try:
          # Prepare the mutation
          if class_identifier:
              mutation = """
              mutation ($object_store_name: String!, $identifier: String!, $class_identifier: String,
                      $folder_properties: FolderPropertiesInput) {
              updateFolder(
                  repositoryIdentifier: $object_store_name
                  identifier: $identifier
                  classIdentifier: $class_identifier
                  folderProperties: $folder_properties
              ) {
                  id
                  className
                  properties {
                  id
                  value
                  }
              }
              }
              """
          else:
              mutation = """
              mutation ($object_store_name: String!, $identifier: String!, 
                      $folder_properties: FolderPropertiesInput) {
              updateFolder(
                  repositoryIdentifier: $object_store_name
                  identifier: $identifier
                  
                  folderProperties: $folder_properties
              ) {
                  id
                  className
                  properties {
                  id
                  value
                  }
              }
              }
          """
  
          # Prepare variables for the GraphQL query
          variables = {
              "object_store_name": graphql_client.object_store,  # Always use the default object store
              "identifier": identifier,
              # "class_identifier": class_identifier if class_identifier else NULL_VALUE,
              "folder_properties": None,
          }
          if class_identifier:
              variables["class_identifier"] = class_identifier
          # Process folder properties if provided
          if folder_properties:
              try:
                  transformed_props = folder_properties.transform_properties_dict(
                      exclude_none=True
                  )
  
                  variables["folder_properties"] = transformed_props
              except Exception as e:
                  logger.error("Error transforming folder properties: %s", str(e))
                  logger.error(traceback.format_exc())
                  return ToolError(
                      message=f"{method_name} failed: {str(e)}. Trace available in server logs."
                  )
  
          # Execute the GraphQL mutation
          logger.info("Executing folder update")
          response = await graphql_client.execute_async(
              query=mutation, variables=variables
          )
  
          # Handle errors
          if "errors" in response:
              logger.error("GraphQL error: %s", response["errors"])
              return ToolError(message=f"{method_name} failed: {response['errors']}")
  
          # Create and return a folder instance from the response
          return Folder.create_an_instance(
              graphQL_changed_object_dict=response["data"]["updateFolder"],
              class_identifier=(
                  class_identifier if class_identifier else DEFAULT_FOLDER_CLASS
              ),
          )
  
      except Exception as e:
          logger.error("%s failed: %s", method_name, str(e))
          logger.error(traceback.format_exc())
          return ToolError(
              message=f"{method_name} failed: {str(e)}. Trace available in server logs."
          )

• src/cs_mcp_server/utils/model/coreInput.py:496-507 (schema)

  Pydantic input schema (FolderPropertiesInput) used by the update_folder tool for validating and transforming folder properties input.

  class FolderPropertiesInput(CustomInputBase):
      """Input for folder properties."""
  
      properties: Optional[List[PropertyIdentifierAndScalarValue]] = Field(
          default=None, description="Properties for Folder"
      )
      name: Optional[str] = Field(
          default=None,
          description="Name sets folder name or whatever property is configured as the Name property",
      )
      owner: Optional[str] = Field(default=None, description="Owner")