cBioPortal MCP Server

Instructions

Implementation Reference

• cbioportal_mcp/endpoints/samples.py:26-51 (handler)

  Core handler function implementing the get_samples_in_study tool logic: validates inputs, constructs cBioPortal API endpoint, and performs paginated request.

  @handle_api_errors("get samples in study")
  @validate_paginated_params
  async def get_samples_in_study(
      self,
      study_id: str,
      page_number: int = 0,
      page_size: int = 50,
      sort_by: Optional[str] = None,
      direction: str = "ASC",
      limit: Optional[int] = None,
  ) -> Dict:
      """
      Get a list of samples associated with a specific cancer study with pagination support.
      """
      # Input Validation
      validate_study_id(study_id)
      
      return await self.paginated_request(
          endpoint=f"studies/{study_id}/samples",
          page_number=page_number,
          page_size=page_size,
          sort_by=sort_by,
          direction=direction,
          limit=limit,
          data_key="samples"
      )

• cbioportal_mcp/server.py:274-286 (handler)

  MCP server entrypoint handler for the get_samples_in_study tool, delegates to the SamplesEndpoints instance.

  async def get_samples_in_study(
      self,
      study_id: str,
      page_number: int = 0,
      page_size: int = 50,
      sort_by: Optional[str] = None,
      direction: str = "ASC",
      limit: Optional[int] = None,
  ) -> Dict:
      """Get a list of samples associated with a specific cancer study with pagination support."""
      return await self.samples.get_samples_in_study(
          study_id, page_number, page_size, sort_by, direction, limit
      )

• cbioportal_mcp/server.py:98-122 (registration)

  Registration of get_samples_in_study as an MCP tool by including it in the tool_methods list processed by _register_tools().

  # List of methods to register as tools (explicitly defined)
  tool_methods = [
      # Pagination utilities
      "paginate_results",
      "collect_all_results",
      # Studies endpoints
      "get_cancer_studies",
      "get_cancer_types",
      "search_studies",
      "get_study_details",
      "get_multiple_studies",
      # Genes endpoints
      "search_genes",
      "get_genes",
      "get_multiple_genes",
      "get_mutations_in_gene",
      # Samples endpoints
      "get_samples_in_study",
      "get_sample_list_id",
      # Molecular profiles endpoints
      "get_molecular_profiles",
      "get_clinical_data",
      "get_gene_panels_for_study",
      "get_gene_panel_details",
  ]

• cbioportal_mcp/utils/validation.py:66-81 (schema)

  Input validation schema/function for study_id parameter used in get_samples_in_study.

  def validate_study_id(study_id: str) -> None:
      """
      Validate study ID parameter.
  
      Args:
          study_id: Study identifier
  
      Raises:
          TypeError: If study_id is not a string
          ValueError: If study_id is empty
      """
      if not isinstance(study_id, str):
          raise TypeError("study_id must be a string")
      if not study_id:
          raise ValueError("study_id cannot be empty")

• cbioportal_mcp/endpoints/base.py:206-264 (helper)

  Helper method called by get_samples_in_study to execute the paginated API request and format the response.

  async def paginated_request(
      self,
      endpoint: str,
      page_number: int = 0,
      page_size: int = 50,
      sort_by: Optional[str] = None,
      direction: str = "ASC",
      limit: Optional[int] = None,
      data_key: str = "results",
      additional_params: Optional[Dict[str, Any]] = None
  ) -> Dict[str, Any]:
      """
      Make a paginated API request with standardized handling.
      
      Args:
          endpoint: API endpoint to call
          page_number: Page number to retrieve (0-based)
          page_size: Number of items per page
          sort_by: Field to sort by
          direction: Sort direction (ASC or DESC)
          limit: Maximum number of items to return
          data_key: Key name for results in response
          additional_params: Additional parameters to include in the request
          
      Returns:
          Standardized paginated response
      """
      # Build base pagination parameters
      api_params = self.build_pagination_params(
          page_number, page_size, sort_by, direction, limit
      )
      
      # Add any additional parameters
      if additional_params:
          api_params.update(additional_params)
      
      # Special behavior for limit=0 (fetch all results)
      if limit == 0:
          results_from_api = await collect_all_results(
              self.api_client, endpoint, params=api_params
          )
          results_for_response = results_from_api
          has_more = False  # We fetched everything
      else:
          # Fetch just the requested page
          results_from_api = await self.api_client.make_api_request(
              endpoint, params=api_params
          )
          
          # Apply limit if specified
          results_for_response = self.apply_limit(results_from_api, limit)
          
          # Determine if there might be more data available
          has_more = self.determine_has_more(results_from_api, api_params)
      
      return self.build_pagination_response(
          results_for_response, page_number, page_size, has_more, data_key
      )