IBM Core Content Services MCP Server

Instructions

Implementation Reference

• src/cs_mcp_server/tools/documents.py:412-498 (handler)

  The main handler function that executes the tool: takes identifier and document_properties, performs GraphQL mutation to update the document, handles errors, and returns Document or ToolError.

  async def update_document_properties(
      identifier: str,
      document_properties: Optional[DocumentPropertiesInput] = None,
  ) -> Union[Document, ToolError]:
      """
      **PREREQUISITES IN ORDER**: To use this tool, you MUST call get_class_property_descriptions first
      to get a list of valid properties for the document's current class.
  
      Description:
      Updates an existing document's properties in the content repository.
      This tool ONLY updates properties and does NOT change the document's class.
      To change a document's class, use the update_document_class tool instead.
  
      :param identifier: The document id or path (required). This can be either the document's ID (GUID) or its path in the repository (e.g., "/Folder1/document.pdf").
      :param document_properties: Properties to update for the document including name, mimeType, etc.
  
      :returns: If successful, returns a Document object with its updated properties.
               If unsuccessful, returns a ToolError with details about the failure.
      """
      method_name = "update_document_properties"
      try:
          # Prepare the mutation
          mutation = """
          mutation ($object_store_name: String!, $identifier: String!, $class_identifier: String,
                   $document_properties: DocumentPropertiesInput) {
            updateDocument(
              repositoryIdentifier: $object_store_name
              identifier: $identifier
              classIdentifier: $class_identifier
              documentProperties: $document_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": None,  # Always None - use update_document_class to change class
              "document_properties": None,
          }
  
          # 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."
                  )
  
          # Execute the GraphQL mutation
          logger.info("Executing document 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 Document instance from the response
          return Document.create_an_instance(
              graphQL_changed_object_dict=response["data"]["updateDocument"],
              class_identifier=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:409-411 (registration)

  The @mcp.tool decorator registers this function as the 'update_document_properties' tool in the MCP server.

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

• src/cs_mcp_server/utils/model/coreInput.py:442-494 (schema)

  Pydantic input model (DocumentPropertiesInput) defining the schema for the document_properties parameter used in the tool.

  class DocumentPropertiesInput(CustomInputBase):
      """Input for document properties."""
  
      properties: Optional[List[PropertyIdentifierAndScalarValue]] = Field(
          default=None, description="Properties for Document"
      )
      name: Optional[str] = Field(
          default=None,
          description="Name sets DocumentTitle or whatever property is configured as the Name property",
      )
      owner: Optional[str] = Field(default=None, description="Owner")
      content: Optional[str] = Field(
          default=None,
          description="Content can be specified if this represents a Reservation document or document creation",
      )
      mimeType: Optional[str] = Field(default=None, description="Mime type")
      compoundDocumentState: Optional[str] = Field(
          default=None, description="Compound document state"
      )
      cmRetentionDate: Optional[datetime] = Field(
          default=None, description="Retention date"
      )
      # contentElements field removed from the model to prevent agents from interpreting and creating this field
      # Instead, we use the methods from CustomInputBase to add content elements programmatically
  
      # Commented out references to ObjectReferenceInput, PermissionListInput, ObjectPropertyInput
      """
      objectProperties: Optional[List[ObjectPropertyInput]] = Field(
          default=None, description="Object properties"
      )
      replicationGroup: Optional[ObjectReferenceInput] = Field(
          default=None, description="Replication group"
      )
      permissions: Optional[PermissionListInput] = Field(
          default=None, description="Permissions"
      )
      securityPolicy: Optional[ObjectReferenceInput] = Field(
          default=None, description="Security policy"
      )
      securityFolder: Optional[ObjectReferenceInput] = Field(
          default=None, description="Security folder"
      )
      storagePolicy: Optional[ObjectReferenceInput] = Field(
          default=None, description="Storage policy"
      )
      documentLifecyclePolicy: Optional[ObjectReferenceInput] = Field(
          default=None, description="Document lifecycle policy"
      )
      storageArea: Optional[ObjectReferenceInput] = Field(
          default=None, description="Storage area"
      )
      """