cBioPortal MCP Server

Instructions

Implementation Reference

• cbioportal_mcp/server.py:167-178 (handler)

  MCP tool handler method registered for 'get_cancer_studies', delegates to StudiesEndpoints instance.
  async def get_cancer_studies( self, page_number: int = 0, page_size: int = 50, sort_by: Optional[str] = None, direction: str = "ASC", limit: Optional[int] = None, ) -> Dict[str, Any]: """Get a list of cancer studies in cBioPortal with pagination support.""" return await self.studies.get_cancer_studies( page_number, page_size, sort_by, direction, limit )
• cbioportal_mcp/endpoints/studies.py:36-67 (handler)

  Core handler logic for fetching paginated list of cancer studies from cBioPortal API.
  @handle_api_errors("get cancer studies") @validate_paginated_params async def get_cancer_studies( self, page_number: int = 0, page_size: int = 50, sort_by: Optional[str] = None, direction: str = "ASC", limit: Optional[int] = None, ) -> Dict[str, Any]: """ Get a list of cancer studies in cBioPortal with pagination support. Args: 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 """ return await self.paginated_request( endpoint="studies", page_number=page_number, page_size=page_size, sort_by=sort_by, direction=direction, limit=limit, data_key="studies" )
• cbioportal_mcp/server.py:96-131 (registration)

  Registers the get_cancer_studies method as an MCP tool using FastMCP.add_tool in a loop over tool_methods list (includes get_cancer_studies at line 104).
  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")
• cbioportal_mcp/endpoints/base.py:206-264 (helper)

  Key helper method implementing pagination logic (single page or collect all), called by get_cancer_studies handler.
  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 )
• cbioportal_mcp/endpoints/base.py:47-76 (schema)

  Input validation decorator for pagination parameters (page_number, page_size, etc.), applied to get_cancer_studies.
  def validate_paginated_params(func): """ Decorator to validate common pagination parameters. Automatically validates page_number, page_size, limit, sort_by, and direction parameters if they exist in the function signature. """ @wraps(func) async def wrapper(self, *args, **kwargs): # Extract parameters from positional args based on function signature import inspect sig = inspect.signature(func) param_names = list(sig.parameters.keys())[1:] # Skip 'self' # Build a dictionary of parameter values bound_args = sig.bind(self, *args, **kwargs) bound_args.apply_defaults() page_number = bound_args.arguments.get('page_number', 0) page_size = bound_args.arguments.get('page_size', 50) limit = bound_args.arguments.get('limit', None) sort_by = bound_args.arguments.get('sort_by', None) direction = bound_args.arguments.get('direction', 'ASC') # Validate pagination parameters - let exceptions bubble up validate_page_params(page_number, page_size, limit) validate_sort_params(sort_by, direction) return await func(self, *args, **kwargs) return wrapper