IBM Core Content Services MCP Server

Instructions

Implementation Reference

• src/cs_mcp_server/tools/documents.py:184-327 (handler)

  The primary handler function for the 'create_document' tool. It constructs and executes a GraphQL mutation to create a new document, handles optional file uploads, property transformations, check-in actions, and returns a Document object or ToolError.

  async def create_document(
      class_identifier: Optional[str] = None,
      id: Optional[str] = None,
      document_properties: Optional[DocumentPropertiesInput] = None,
      file_in_folder_identifier: Optional[str] = None,
      checkin_action: Optional[SubCheckinActionInput] = SubCheckinActionInput(),
      file_paths: Optional[List[str]] = None,
  ) -> Union[Document, 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:
      Creates a document in the content repository with specified properties.
  
      :param classIdentifier: The class identifier for the document. If not provided, defaults to "Document".
      :param id: The unique GUID for the document. If not provided, a new GUID with curly braces will be generated.
      :param documentProperties: Properties for the document including name, content, mimeType, etc.
      :param fileInFolderIdentifier: The identifier or path of the folder to file the document in. This always starts with "/".
      :param checkinAction: Check-in action parameters. CheckinMinorVersion should always be included.
      :param file_paths: Optional list of file paths to upload as the document's content.
  
      :returns: If successful, returns a Document object with its properties.
               If unsuccessful, returns a ToolError with details about the failure.
      """
      method_name = "create_document"
      try:
          # Prepare the mutation
          mutation = """
          mutation ($object_store_name: String!, $class_identifier: String, $id: ID,
                   $document_properties: DocumentPropertiesInput, $file_in_folder_identifier: String,
                   $checkin_action: SubCheckinActionInput) {
            createDocument(
              repositoryIdentifier: $object_store_name
              classIdentifier: $class_identifier
              id: $id
              documentProperties: $document_properties
              fileInFolderIdentifier: $file_in_folder_identifier
              checkinAction: $checkin_action
            ) {
              id
              className
              properties {
                id
                value
              }
            }
          }
          """
  
          # Prepare variables for the GraphQL query with all parameters set to None by default
          variables = {
              "object_store_name": graphql_client.object_store,
              "class_identifier": None,
              "id": None,
              "document_properties": None,
              "file_in_folder_identifier": None,
              "checkin_action": None,
          }
  
          # Add optional parameters if provided
          if class_identifier:
              variables["class_identifier"] = class_identifier
          if id:
              variables["id"] = id
          if file_in_folder_identifier:
              variables["file_in_folder_identifier"] = file_in_folder_identifier
  
          # Process file paths
          file_paths_dict = {}
  
          # Handle file upload if file paths are provided
          if file_paths:
              try:
                  # Initialize document_properties if not provided
                  if not document_properties:
                      document_properties = DocumentPropertiesInput()
  
                  file_paths_dict = document_properties.process_file_content(
                      file_paths
                  )
              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."
                  )
  
          # Process document properties if provided
          if document_properties:
              try:
                  transformed_props = document_properties.transform_properties_dict(
                      exclude_none=True
                  )
                  variables["document_properties"] = transformed_props
              except Exception as e:
                  logger.error("Error transforming document properties: %s", str(e))
                  logger.error(traceback.format_exc())
                  return ToolError(
                      message=f"{method_name} failed: {str(e)}. Trace available in server logs."
                  )
  
          # Handle checkin action if provided
          if checkin_action:
              # Use model_dump with exclude_none for cleaner code
              variables["checkin_action"] = checkin_action.model_dump(
                  exclude_none=True
              )
  
          # Execute the GraphQL mutation
          if file_paths_dict:
              # Use execute with file_paths for file upload
              logger.info("Executing document creation with file upload")
              response = graphql_client.execute(
                  query=mutation, variables=variables, file_paths=file_paths_dict
              )
          else:
              # Use execute_async for regular document creation
              logger.info("Executing document creation")
              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 Document instance from the response
          return Document.create_an_instance(
              graphQL_changed_object_dict=response["data"]["createDocument"],
              class_identifier=(
                  class_identifier if class_identifier else DEFAULT_DOCUMENT_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/tools/documents.py:181-183 (registration)

  The @mcp.tool decorator that registers the 'create_document' handler function with the FastMCP server.

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

• src/cs_mcp_server/tools/documents.py:184-191 (schema)

  Type annotations in the function signature define the input schema (parameters) and output type for the tool, used by FastMCP for validation.

  async def create_document(
      class_identifier: Optional[str] = None,
      id: Optional[str] = None,
      document_properties: Optional[DocumentPropertiesInput] = None,
      file_in_folder_identifier: Optional[str] = None,
      checkin_action: Optional[SubCheckinActionInput] = SubCheckinActionInput(),
      file_paths: Optional[List[str]] = None,
  ) -> Union[Document, ToolError]: