get_gene_panels_for_study
Retrieve all gene panels for a specific cancer study in cBioPortal MCP Server, with options for pagination, sorting, and result size to efficiently manage large datasets.
Instructions
Get all gene panels in a specific study with pagination support.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| direction | No | ASC | |
| limit | No | ||
| page_number | No | ||
| page_size | No | ||
| sort_by | No | genePanelId | |
| study_id | Yes |
Input Schema (JSON Schema)
{
"additionalProperties": false,
"properties": {
"direction": {
"default": "ASC",
"title": "Direction",
"type": "string"
},
"limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Limit"
},
"page_number": {
"default": 0,
"title": "Page Number",
"type": "integer"
},
"page_size": {
"default": 50,
"title": "Page Size",
"type": "integer"
},
"sort_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "genePanelId",
"title": "Sort By"
},
"study_id": {
"title": "Study Id",
"type": "string"
}
},
"required": [
"study_id"
],
"type": "object"
}
Implementation Reference
- Core handler implementation for get_gene_panels_for_study tool. Fetches gene panels from cBioPortal API with input validation, pagination handling via collect_all_results or single page, and comprehensive error handling.@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)MCP tool handler wrapper in the main server class that delegates execution to MolecularProfilesEndpoints.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, ) -> 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)Tool registration logic where get_gene_panels_for_study is explicitly listed in tool_methods and registered via FastMCP's add_tool method.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")