IBM Core Content Services MCP Server

Instructions

Implementation Reference

• src/cs_mcp_server/tools/documents.py:1093-1167 (handler)

  The handler function for the 'cancel_document_checkout' tool. It takes a document or reservation identifier, executes a GraphQL mutation to cancel the checkout, handles errors, and returns the updated Document object or a ToolError.

  async def cancel_document_checkout(
      identifier: str,
  ) -> Union[Document, ToolError]:
      """
      Cancels a document checkout in the content repository.
  
      :param identifier: The identifier (required). This can be either a reservation_id or document_id.
                        Reservation ID (GUID) is prioritized.
                        Otherwise, we use document_id (GUID).
  
      :returns: If successful, returns a Document object with its updated properties.
               If unsuccessful, returns a ToolError with details about the failure.
      """
      method_name = "cancel_document_checkout"
      try:
          # Prepare the mutation
          mutation = """
          mutation ($object_store_name: String!, $identifier: String!) {
            cancelDocumentCheckout(
              repositoryIdentifier: $object_store_name
              identifier: $identifier
            ) {
              id
              className
              reservation{
                  isReserved
                  id
              }
              currentVersion{
                  contentElements{
                      ... on ContentTransferType {
                          retrievalName
                          contentType
                          contentSize
                          downloadUrl
                      }
                  }
              }
              properties {
                id
                value
              }
            }
          }
          """
  
          # Prepare variables for the GraphQL query
          variables = {
              "object_store_name": graphql_client.object_store,
              "identifier": identifier,
          }
  
          # Execute the GraphQL mutation
          logger.info("Executing document checkout cancellation")
          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"]["cancelDocumentCheckout"],
              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:1090-1092 (registration)

  The MCP tool registration decorator that registers the 'cancel_document_checkout' handler function with the FastMCP server.

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