IBM Core Content Services MCP Server

Instructions

Implementation Reference

• src/cs_mcp_server/tools/documents.py:1014-1089 (handler)

  The handler function for the 'get_document_properties' tool. It uses GraphQL to query the document repository for properties by ID or path, handles errors, and returns a Document object or ToolError.

  @mcp.tool(
      name="get_document_properties",
  )
  async def get_document_properties(
      identifier: str,
  ) -> Union[Document, ToolError]:
      """
      Retrieves a document's properties from the content repository by ID or path.
  
      Note: Use this tool ONLY when you need to retrieve a document using its ID or file path.
      For searching documents by other properties, use the repository_search 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").
  
      :returns: If successful, returns the Document object with its properties.
               If unsuccessful, returns a ToolError with details about the failure.
      """
      method_name = "get_document"
      try:
          # Prepare the query
          query = """
          query ($object_store_name: String!, $identifier: String!) {
              document(repositoryIdentifier: $object_store_name, identifier: $identifier) {
                  id
                  name
                  properties {
                      id
                      value
                  }
              }
          }
          """
  
          # Prepare variables for the GraphQL query
          variables = {
              "object_store_name": graphql_client.object_store,
              "identifier": identifier,
          }
  
          # Execute the GraphQL query
          logger.info("Executing document retrieval")
          response = await graphql_client.execute_async(
              query=query, variables=variables
          )
  
          # Handle errors
          if "errors" in response:
              logger.error("GraphQL error: %s", response["errors"])
              return ToolError(message=f"{method_name} failed: {response['errors']}")
  
          # Check if document was found
          if not response.get("data") or not response["data"].get("document"):
              return ToolError(
                  message=f"Document not found with identifier: {identifier}",
                  suggestions=[
                      "Check if the document ID or path is correct",
                      "Verify that the document exists in the repository",
                      "Try using repository_search tool to find the document by other properties",
                  ],
              )
  
          # Create and return a Document instance from the response
          return Document.create_an_instance(
              graphQL_changed_object_dict=response["data"]["document"],
              class_identifier=response["data"]["document"].get(
                  "className", 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:1014-1016 (registration)

  Registration of the 'get_document_properties' tool using the @mcp.tool decorator.

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

• src/cs_mcp_server/tools/documents.py:1017-1019 (schema)

  Input schema (identifier: str) and output type (Union[Document, ToolError]) defined in the function signature and docstring.

  async def get_document_properties(
      identifier: str,
  ) -> Union[Document, ToolError]: