get_samples_in_study
Retrieve paginated sample data for a specific cancer study to analyze genomic information and clinical details.
Instructions
Get a list of samples associated with a specific cancer study with pagination support.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| study_id | Yes | ||
| page_number | No | ||
| page_size | No | ||
| sort_by | No | ||
| direction | No | ASC | |
| limit | No |
Implementation Reference
- Core handler function implementing the get_samples_in_study tool logic: validates inputs, constructs cBioPortal API endpoint, and performs paginated request.
@handle_api_errors("get samples in study") @validate_paginated_params async def get_samples_in_study( 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 samples associated with a specific cancer study with pagination support. """ # Input Validation validate_study_id(study_id) return await self.paginated_request( endpoint=f"studies/{study_id}/samples", page_number=page_number, page_size=page_size, sort_by=sort_by, direction=direction, limit=limit, data_key="samples" ) - cbioportal_mcp/server.py:274-286 (handler)MCP server entrypoint handler for the get_samples_in_study tool, delegates to the SamplesEndpoints instance.
async def get_samples_in_study( 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 samples associated with a specific cancer study with pagination support.""" return await self.samples.get_samples_in_study( study_id, page_number, page_size, sort_by, direction, limit ) - cbioportal_mcp/server.py:98-122 (registration)Registration of get_samples_in_study as an MCP tool by including it in the tool_methods list processed by _register_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", ] - Input validation schema/function for study_id parameter used in get_samples_in_study.
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") - Helper method called by get_samples_in_study to execute the paginated API request and format the response.
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 )