cBioPortal MCP Server

Instructions

Implementation Reference

• cbioportal_mcp/endpoints/molecular_profiles.py:35-81 (handler)

  Core handler function implementing the get_molecular_profiles tool logic: validates inputs, fetches data from cBioPortal API, applies client-side sorting and pagination, and formats the response.

  @handle_api_errors("get molecular profiles")
  async def get_molecular_profiles(
      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 molecular profiles available for a specific cancer study with pagination support.
      """
      # Input Validation
      validate_study_id(study_id)
      validate_page_params(page_number, page_size, limit)
      validate_sort_params(sort_by, direction)
  
      try:
          if limit == 0:
              page_size = FETCH_ALL_PAGE_SIZE
          profiles = await self.api_client.make_api_request(
              f"studies/{study_id}/molecular-profiles"
          )
          if sort_by:
              reverse = direction.upper() == "DESC"
              profiles.sort(key=lambda p: str(p.get(sort_by, "")), reverse=reverse)
          total_count = len(profiles)
          start_idx = page_number * page_size
          end_idx = start_idx + page_size
          paginated_profiles = profiles[start_idx:end_idx]
          if limit and limit > 0 and len(paginated_profiles) > limit:
              paginated_profiles = paginated_profiles[:limit]
          has_more = end_idx < total_count
          return {
              "molecular_profiles": paginated_profiles,
              "pagination": {
                  "page": page_number,
                  "page_size": page_size,
                  "total_found": total_count,
                  "has_more": has_more,
              },
          }
      except Exception as e:
          return {
              "error": f"Failed to get molecular profiles for {study_id}: {str(e)}"
          }

• cbioportal_mcp/server.py:294-306 (registration)

  Thin wrapper method on the MCP server class that delegates to the MolecularProfilesEndpoints handler. This method is registered as the MCP tool.

  async def get_molecular_profiles(
      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 molecular profiles available for a specific cancer study with pagination support."""
      return await self.molecular_profiles.get_molecular_profiles(
          study_id, page_number, page_size, sort_by, direction, limit
      )

• cbioportal_mcp/server.py:97-131 (registration)

  Registers all server methods, including get_molecular_profiles, as MCP tools using FastMCP.add_tool().

  """Register tool methods as MCP 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",
  ]
  
  for method_name in tool_methods:
      if hasattr(self, method_name):
          method = getattr(self, method_name)
          self.mcp.add_tool(method)
          logger.debug(f"Registered tool: {method_name}")
      else:
          logger.warning(f"Method {method_name} not found for tool registration")

• cbioportal_mcp/utils/validation.py:10-81 (helper)

  Input validation helper functions used by the get_molecular_profiles handler for study_id, pagination, and sort parameters.

  def validate_page_params(
      page_number: int,
      page_size: int,
      limit: Optional[int] = None,
  ) -> None:
      """
      Validate pagination parameters.
  
      Args:
          page_number: Page number (0-based)
          page_size: Number of items per page
          limit: Optional limit on total results
  
      Raises:
          TypeError: If parameters are not the correct type
          ValueError: If parameters have invalid values
      """
      if not isinstance(page_number, int):
          raise TypeError("page_number must be an integer")
      if page_number < 0:
          raise ValueError("page_number must be non-negative")
  
      if not isinstance(page_size, int):
          raise TypeError("page_size must be an integer")
      if page_size <= 0:
          raise ValueError("page_size must be positive")
  
      if limit is not None:
          if not isinstance(limit, int):
              raise TypeError("limit must be an integer if provided")
          if limit < 0:
              raise ValueError("limit must be non-negative if provided")
  
  
  def validate_sort_params(
      sort_by: Optional[str],
      direction: str,
  ) -> None:
      """
      Validate sorting parameters.
  
      Args:
          sort_by: Field to sort by (optional)
          direction: Sort direction (ASC or DESC)
  
      Raises:
          TypeError: If parameters are not the correct type
          ValueError: If direction is not valid
      """
      if sort_by is not None and not isinstance(sort_by, str):
          raise TypeError("sort_by must be a string if provided")
  
      if not isinstance(direction, str) or direction.upper() not in ["ASC", "DESC"]:
          raise ValueError("direction must be 'ASC' or 'DESC'")
  
  
  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")