repository_object_search

Instructions

Implementation Reference

• src/cs_mcp_server/tools/search.py:226-248 (handler)

  The repository_object_search tool handler function. It delegates to get_repository_object_main() to execute the actual search logic.

  async def repository_object_search(
      search_parameters: SearchParameters,
  ) -> dict | 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_name for search_class.
      2. get_searchable_property_descriptions to get a list of valid property_name for search_properties
  
      Description:
      This tool retrieves repository objects other than Document instances.
  
      :param search_parameters (SearchParameters): parameters for the searching including the object being searched for and any search conditions.
  
      :returns: A the repository object details, including:
          - repositoryObjects (dict): a dictionary containing independentObjects:
              - independentObjects (list): A list of independent objects, each containing:
              - properties (list): A list of properties, each containing:
                  - label (str): The name of the property.
                  - value (str): The value of the property.
      """
      return await get_repository_object_main(
          search_parameters, graphql_client, metadata_cache
      )

• src/cs_mcp_server/tools/search.py:721-782 (handler)

  The get_repository_object_main() function that executes the repository object search. It processes search parameters, builds a GraphQL query, and calls graphql_client.execute_async() to retrieve matching repository objects.

  async def get_repository_object_main(
      search_parameters: SearchParameters,
      graphql_client: GraphQLClient,
      metadata_cache: MetadataCache,
      additional_filter_string: str = "",
  ) -> dict | ToolError:
      # Process search parameters using the utility function
      result = await process_search_parameters(
          graphql_client, metadata_cache, search_parameters
      )
  
      # Check if we got an error
      if isinstance(result, ToolError):
          return result
  
      # Unpack the result tuple
      search_properties_string, return_properties = result
      if additional_filter_string:
          search_properties_string = (
              f"{search_properties_string} and {additional_filter_string}"
              if search_properties_string
              else additional_filter_string
          )
  
      query = """
      query repositoryObjectsSearch($object_store_name: String!,
          $class_name: String!, $where_statement: String!, $return_props: [String!]){
          repositoryObjects(
          repositoryIdentifier: $object_store_name,
          from: $class_name,
          where: $where_statement
          ) {
          independentObjects {
              properties (includes: $return_props){
              id
              label
              value
              }
          }
          }
      }
      """
      var = {
          "object_store_name": graphql_client.object_store,
          "where_statement": search_properties_string,
          "class_name": search_parameters.search_class,
          "return_props": return_properties,
      }
  
      try:
          response = await graphql_client.execute_async(query=query, variables=var)
          return response  # Return response only if no exception occurs
      except Exception as e:
          return ToolError(
              message=f"Error executing search: {str(e)}",
              suggestions=[
                  "Check that all property names are valid for the class",
                  "Ensure property values match the expected data types",
                  "Verify that the operators are appropriate for the property data types",
              ],
          )

• src/cs_mcp_server/utils/common.py:84-96 (schema)

  SearchParameters schema: Input model for the tool with search_class (str) and search_properties (List[SearchProperty]) fields.

  class SearchParameters(BaseModel):
      """
      Complete set of parameters for executing a repository search.
      """
  
      search_class: str = Field(
          ...,
          description="The class to search for. Must be a valid class in the repository.",
      )
      search_properties: List[SearchProperty] = Field(
          ...,
          description="List of filter conditions to apply to the search. All conditions are combined with AND logic. If no conditions exist, we return all objects of the given class",
      )

• src/cs_mcp_server/utils/common.py:63-81 (schema)

  SearchProperty schema: Defines individual search conditions with property_name, property_value, and operator fields.

  class SearchProperty(BaseModel):
      """
      Defines a single search condition/filter to be applied during repository searches.
      """
  
      property_name: str = Field(
          ...,
          description="The name of the property to filter on. Must be a valid property for the specified class as obtained from the get_searchable_class_properties_tool .",
      )
      property_value: str = Field(
          ...,
          description="The value to filter by. Format should match the property's data type.",
      )
      operator: SearchOperator = Field(
          ...,
          description="The comparison operator that defines how property_name and property_value are compared. "
          "Use CONTAINS for substring matching, STARTS/ENDS for prefix/suffix matching. "
          "Use standard SQL operators: =, >, <, >=, <=, != for other properties.",
      )

• src/cs_mcp_server/tools/search.py:223-248 (registration)

  Registration of the 'repository_object_search' tool via @mcp.tool decorator, inside register_search_tools() which is called from mcp_server_main.py.

  @mcp.tool(
      name="repository_object_search",
  )
  async def repository_object_search(
      search_parameters: SearchParameters,
  ) -> dict | 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_name for search_class.
      2. get_searchable_property_descriptions to get a list of valid property_name for search_properties
  
      Description:
      This tool retrieves repository objects other than Document instances.
  
      :param search_parameters (SearchParameters): parameters for the searching including the object being searched for and any search conditions.
  
      :returns: A the repository object details, including:
          - repositoryObjects (dict): a dictionary containing independentObjects:
              - independentObjects (list): A list of independent objects, each containing:
              - properties (list): A list of properties, each containing:
                  - label (str): The name of the property.
                  - value (str): The value of the property.
      """
      return await get_repository_object_main(
          search_parameters, graphql_client, metadata_cache
      )