cBioPortal MCP Server

Instructions

Implementation Reference

• cbioportal_mcp/endpoints/molecular_profiles.py:180-256 (handler)

  Core handler function implementing the tool logic: validates inputs, calls cBioPortal API endpoint studies/{study_id}/gene-panels with pagination params, handles full collection if limit provided, manages errors and logging.

  @handle_api_errors("get gene panels for study")
  async def get_gene_panels_for_study(
      self,
      study_id: str,
      page_number: int = 0,
      page_size: int = 50,
      sort_by: Optional[str] = "genePanelId",
      direction: str = "ASC",
      limit: Optional[int] = None,
  ) -> Union[List[Dict[str, Any]], Dict[str, Any]]:
      """
      Get all gene panels in a specific study with pagination support.
  
      Args:
          study_id: The ID of the cancer study (e.g., "acc_tcga").
          page_number: Page number to retrieve (0-based).
          page_size: Number of items per page.
          sort_by: Field to sort by (e.g., "genePanelId").
          direction: Sort direction ("ASC" or "DESC").
          limit: Optional maximum number of gene panels to return. If None, fetches all available based on page_number and page_size for a single page, or all results if limit is used with collect_all_results.
  
      Returns:
          A list of gene panel objects, or an error dictionary.
      """
      if not study_id or not isinstance(study_id, str):
          return {"error": "study_id must be a non-empty string"}
      if not isinstance(page_number, int) or page_number < 0:
          return {"error": "page_number must be a non-negative integer"}
      if not isinstance(page_size, int) or page_size <= 0:
          return {"error": "page_size must be a positive integer"}
      if sort_by is not None and not isinstance(sort_by, str):
          # Allow empty string for sort_by if API supports it, or check against valid fields
          return {"error": "sort_by must be a string or None"}
      if direction.upper() not in ["ASC", "DESC"]:
          return {"error": "direction must be 'ASC' or 'DESC'"}
      if limit is not None and (not isinstance(limit, int) or limit < 0):
          # Allow limit=0 to mean no results, consistent with some APIs
          return {"error": "limit must be a non-negative integer or None"}
  
      endpoint = f"studies/{study_id}/gene-panels"
      params = {
          "pageNumber": page_number,
          "pageSize": page_size,
          "projection": "DETAILED",  # Default to include genes in panels
          "sortBy": sort_by,
          "direction": direction.upper(),
      }
      # Remove None params, especially sortBy if not provided
      params = {k: v for k, v in params.items() if v is not None}
  
      try:
          if limit is not None:
              # collect_all_results handles pagination internally up to the limit
              return await collect_all_results(
                  self.api_client, endpoint, params=params, limit=limit
              )
          else:
              # Fetch a single page as defined by page_number and page_size
              return await self.api_client.make_api_request(endpoint, params=params)
      except httpx.HTTPStatusError as e:
          logger.error(
              f"API error getting gene panels for study {study_id}: {e.response.status_code} - {e.response.text}"
          )
          return {
              "error": f"API error: {e.response.status_code}",
              "details": e.response.text,
          }
      except httpx.RequestError as e:
          logger.error(f"Request error getting gene panels for study {study_id}: {e}")
          return {"error": "Request error", "details": str(e)}
      except Exception as e:
          logger.error(
              f"Unexpected error getting gene panels for study {study_id}: {e}",
              exc_info=True,
          )
          return {"error": "Unexpected server error", "details": str(e)}

• cbioportal_mcp/server.py:323-335 (handler)

  Thin wrapper method in the main server class that delegates to MolecularProfilesEndpoints.get_gene_panels_for_study; this is the method directly registered as the MCP tool.

  async def get_gene_panels_for_study(
      self,
      study_id: str,
      page_number: int = 0,
      page_size: int = 50,
      sort_by: Optional[str] = "genePanelId",
      direction: str = "ASC",
      limit: Optional[int] = None,
  ) -> List[Dict[str, Any]]:
      """Get all gene panels in a specific study with pagination support."""
      return await self.molecular_profiles.get_gene_panels_for_study(
          study_id, page_number, page_size, sort_by, direction, limit
      )

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

  Registers all MCP tools including 'get_gene_panels_for_study' by adding the corresponding server methods to FastMCP instance.

  def _register_tools(self):
      """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")