cBioPortal MCP Server

Instructions

Implementation Reference

• cbioportal_mcp/endpoints/molecular_profiles.py:258-331 (handler)

  Core handler function that implements the get_gene_panel_details tool logic, performing input validation, API request to cBioPortal's gene-panels/fetch endpoint, response processing, and comprehensive error handling.

  async def get_gene_panel_details(
      self,
      gene_panel_id: str,
      projection: str = "DETAILED",
  ) -> Dict[str, Any]:
      """
      Get detailed information for a specific gene panel, including the list of genes.
  
      Args:
          gene_panel_id: The ID of the gene panel (e.g., "IMPACT341").
          projection: Level of detail ("ID", "SUMMARY", "DETAILED", "META").
                      "DETAILED" includes the list of genes.
  
      Returns:
          A dictionary containing gene panel details, or an error dictionary.
      """
      if not gene_panel_id or not isinstance(gene_panel_id, str):
          return {"error": "gene_panel_id must be a non-empty string"}
      if projection.upper() not in ["ID", "SUMMARY", "DETAILED", "META"]:
          return {
              "error": "projection must be one of 'ID', 'SUMMARY', 'DETAILED', 'META'"
          }
  
      endpoint = "gene-panels/fetch"
      # API requires query param for projection, and POST body for IDs
      params = {"projection": projection.upper()}
      request_body = [gene_panel_id]  # API expects a list of gene panel IDs
  
      try:
          results = await self.api_client.make_api_request(
              endpoint, method="POST", params=params, json_data=request_body
          )
  
          # The API returns a list, even for a single ID request
          if isinstance(results, list):
              if len(results) > 0:
                  return results[
                      0
                  ]  # Return the first (and expected only) gene panel object
              else:
                  # Successfully queried, but no panel found for this ID
                  return {
                      "error": "Gene panel not found",
                      "gene_panel_id": gene_panel_id,
                  }
          else:
              # This case implies an unexpected API response format (not a list)
              logger.warning(
                  f"Unexpected response format for get_gene_panel_details {gene_panel_id}: {type(results)}"
              )
              return {
                  "error": "Unexpected response format from API",
                  "details": str(results),
              }
  
      except httpx.HTTPStatusError as e:
          logger.error(
              f"API error getting gene panel details for {gene_panel_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 panel details for {gene_panel_id}: {e}"
          )
          return {"error": "Request error", "details": str(e)}
      except Exception as e:
          logger.error(
              f"Unexpected error getting gene panel details for {gene_panel_id}: {e}",
              exc_info=True,
          )
          return {"error": "Unexpected server error", "details": str(e)}

• cbioportal_mcp/server.py:337-345 (handler)

  Thin wrapper handler in the main server class that delegates to the MolecularProfilesEndpoints implementation.

  async def get_gene_panel_details(
      self,
      gene_panel_id: str,
      projection: str = "DETAILED",
  ) -> Dict[str, Any]:
      """Get detailed information for a specific gene panel, including the list of genes."""
      return await self.molecular_profiles.get_gene_panel_details(
          gene_panel_id, projection
      )

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

  Registers the get_gene_panel_details method (and others) as an MCP tool using FastMCP's add_tool.

  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")