cBioPortal MCP Server

Instructions

Implementation Reference

• cbioportal_mcp/endpoints/studies.py:69-161 (handler)

  Core handler implementation for search_studies tool: validates inputs, fetches all studies from API, filters by keyword in name/description, applies sorting and pagination, returns structured response.

  @handle_api_errors("search studies")
  async def search_studies(
      self,
      keyword: str,
      page_number: int = 0,
      page_size: int = 50,
      sort_by: Optional[str] = None,
      direction: str = "ASC",
      limit: Optional[int] = None,
  ) -> Dict[str, Any]:
      """
      Search for cancer studies by keyword in their name or description with pagination support.
  
      Args:
          keyword: Keyword to search for
          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 across all pages (None for no limit)
  
      Returns:
          Dictionary containing list of studies and metadata
      """
      # Input Validation
      validate_keyword(keyword)
      validate_page_params(page_number, page_size, limit)
      validate_sort_params(sort_by, direction)
  
      try:
          # Await the asynchronous API call
          all_studies = await self.api_client.make_api_request("studies")
  
          if not isinstance(all_studies, list):
              # Handle cases where API request might not return a list (e.g., error response)
              error_message = (
                  "Unexpected response from API when fetching all studies."
              )
              if isinstance(all_studies, dict) and "error" in all_studies:
                  error_message = all_studies["error"]
              return {
                  "error": f"Failed to search studies for '{keyword}': {error_message}"
              }
  
          keyword_lower = keyword.lower()
          matching_studies = [
              study
              for study in all_studies
              if keyword_lower in study.get("name", "").lower()
              or keyword_lower in study.get("description", "").lower()
          ]
  
          if sort_by:
              reverse = direction.upper() == "DESC"
              matching_studies.sort(
                  key=lambda s: str(s.get(sort_by, "")), reverse=reverse
              )
  
          total_count = len(matching_studies)
          start_idx = page_number * page_size
          end_idx = start_idx + page_size
          paginated_studies = matching_studies[start_idx:end_idx]
  
          if limit and limit > 0 and len(paginated_studies) > limit:
              paginated_studies = paginated_studies[:limit]
  
          has_more = end_idx < total_count
  
          return {
              "studies": paginated_studies,
              "pagination": {
                  "page": page_number,
                  "page_size": page_size
                  if limit != 0
                  else total_count,  # Adjust page_size if all were requested
                  "total_found": total_count,
                  "has_more": has_more
                  if limit != 0
                  else False,  # No more if all were requested
              },
          }
      except httpx.HTTPStatusError as exc:
          return {
              "error": f"Failed to search studies for '{keyword}': API request failed with status {exc.response.status_code}"
          }
      except httpx.RequestError as exc:
          return {
              "error": f"Failed to search studies for '{keyword}': Network error - {str(exc)}"
          }
      except Exception as e:
          return {
              "error": f"Failed to search studies for '{keyword}': An unexpected error occurred - {str(e)}"
          }

• cbioportal_mcp/server.py:193-205 (handler)

  Top-level MCP tool handler for search_studies that delegates to the StudiesEndpoints instance.

  async def search_studies(
      self,
      keyword: str,
      page_number: int = 0,
      page_size: int = 50,
      sort_by: Optional[str] = None,
      direction: str = "ASC",
      limit: Optional[int] = None,
  ) -> Dict[str, Any]:
      """Search for cancer studies by keyword in their name or description with pagination support."""
      return await self.studies.search_studies(
          keyword, page_number, page_size, sort_by, direction, limit
      )

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

  Registration of all MCP tools including 'search_studies' by dynamically adding server methods to the FastMCP instance.

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