IBM Core Content Services MCP Server

Instructions

Implementation Reference

• src/cs_mcp_server/tools/folders.py:41-148 (handler)

  The handler function for 'create_folder' tool that performs the GraphQL mutation to create a folder in the repository.

  def create_folder(
      name: str,
      parent_folder: str,
      class_identifier: Optional[str] = None,
      id: 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
  
  
      Creates a folder in the content repository with specified properties. This tool interfaces with the GraphQL API
      to create a new folder object with the provided parameters.
  
      :param name	string	Yes	The name of the folder to be created.
      :param parent_folder	string	Yes	The identifier of the parent folder where this folder will be created.
      :param class_identifier	string	No	The class identifier for the folder. If not provided, defaults to "Folder".
      :param id	string	No	The unique identifier for the folder. If not provided, a new UUID with curly braces will be generated (format: {uuid}).
      :param folder_properties	FolderPropertiesInput No properties of to set.
  
      :returns: If successful, return a folder object with the following properties:
          id: The identifier of the created folder
          name: The name of the folder
          parent_folder: The identifier of the parent folder
          creator: The user who created the folder
          class_identifier: The class identifier of the folder
       Else, return a ToolError instance that describes the error.
      """
      method_name = "create_folder"
      try:
          if not id:
              id = "{" + str(uuid.uuid4()) + "}"
          if not class_identifier:
              class_identifier = DEFAULT_FOLDER_CLASS
          mutation = """
                  mutation createFolder($repo:String!, $id:ID!
                  $className:String, $folderProperties:FolderPropertiesInput!)
                  {
                  createFolder(repositoryIdentifier: $repo,
                      classIdentifier:$className,
                      id: $id
                      folderProperties: $folderProperties
                  )
                  {
                      id
                      className
                      properties {
                      id
                      value
                  }
                  }
                  }
          """
  
          # Build base folder properties
          base_properties = {"name": name, "parent": {"identifier": parent_folder}}
  
          # Process folder properties if provided
          all_properties = base_properties
          if folder_properties:
              base_dict = folder_properties.model_dump(exclude_none=True)
              if "properties" not in base_dict or not base_dict["properties"]:
                  pass  # Continue processing even if there are no properties
              else:
                  try:
                      transformed_props = folder_properties.transform_properties_dict(
                          exclude_none=True
                      )
                      all_properties = {**base_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."
                      )
          logger.info(json.dumps(all_properties, indent=2))
          var = {
              "repo": graphql_client.object_store,
              "folderProperties": all_properties,
              "id": id,
              "className": class_identifier,
          }
  
          response = graphql_client.execute(query=mutation, variables=var)
          # handling exception, for example duplicate folder name
          if "errors" in response:
              return ToolError(
                  message=f"create_folder failed: got err {response}.",
              )
  
          # return response["data"]["createFolder"]
          return Folder.create_an_instance(
              graphQL_changed_object_dict=response["data"]["createFolder"],
              class_identifier=response["data"]["createFolder"]["className"],
          )
  
      except Exception as e:
          error_traceback = traceback.format_exc(limit=TRACEBACK_LIMIT)
          logger.error(
              f"{method_name} failed: {e.__class__.__name__} - {str(e)}\n{error_traceback}"
          )
  
          return ToolError(
              message=f"{method_name} failed: got err {e}. Trace available in server logs.",
          )

• src/cs_mcp_server/tools/folders.py:38-40 (registration)

  Registers the 'create_folder' tool with the MCP server using the @mcp.tool decorator.

  @mcp.tool(
      name="create_folder",
  )

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

  Pydantic model defining the structure for the optional 'folder_properties' input parameter used in create_folder.

  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")

• src/cs_mcp_server/mcp_server_main.py:221-221 (registration)

  Invokes the registration of folder tools, including 'create_folder', for the CORE server type.

  register_folder_tools(mcp, graphql_client)