BioMCP

Instructions

Implementation Reference

• src/biomcp/individual_tools.py:1103-1183 (handler)

  The primary handler function for the 'nci_biomarker_searcher' MCP tool. Includes tool registration via @mcp_app.tool(), input schema via Annotated Fields, and core logic that calls helper functions to perform the NCI biomarker search and format results.
  @track_performance("biomcp.nci_biomarker_searcher") async def nci_biomarker_searcher( name: Annotated[ str | None, Field( description="Biomarker name to search for (e.g., 'PD-L1', 'EGFR mutation')" ), ] = None, biomarker_type: Annotated[ str | None, Field(description="Type of biomarker ('reference_gene' or 'branch')"), ] = None, api_key: Annotated[ str | None, Field( description="NCI API key. Check if user mentioned 'my NCI API key is...' in their message. If not provided here and no env var is set, user will be prompted to provide one." ), ] = None, page: Annotated[ int, Field(description="Page number (1-based)", ge=1), ] = 1, page_size: Annotated[ int, Field(description="Results per page", ge=1, le=100), ] = 20, ) -> str: """Search for biomarkers in the NCI Clinical Trials database. Searches for biomarkers used in clinical trial eligibility criteria. This is essential for precision medicine trials that select patients based on specific biomarker characteristics. Biomarker examples: - Gene mutations (e.g., BRAF V600E, EGFR T790M) - Protein expression (e.g., PD-L1 ≥ 50%, HER2 positive) - Gene fusions (e.g., ALK fusion, ROS1 fusion) - Other molecular markers (e.g., MSI-H, TMB-high) Requires NCI API key from: https://clinicaltrialsapi.cancer.gov/ Note: Biomarker data availability may be limited in CTRP. Results focus on biomarkers used in trial eligibility criteria. Example usage: - Search for PD-L1 expression biomarkers - Find trials requiring EGFR mutations - Look up biomarkers tested by NGS - Search for HER2 expression markers """ from biomcp.biomarkers import search_biomarkers from biomcp.biomarkers.search import format_biomarker_results from biomcp.integrations.cts_api import CTSAPIError try: results = await search_biomarkers( name=name, biomarker_type=biomarker_type, page_size=page_size, page=page, api_key=api_key, ) return format_biomarker_results(results) except CTSAPIError as e: # Check for Elasticsearch bucket limit error error_msg = str(e) if "too_many_buckets_exception" in error_msg or "75000" in error_msg: return ( "⚠️ **Search Too Broad**\n\n" "The NCI API cannot process this search because it returns too many results.\n\n" "**Try adding more specific filters:**\n" "- Add a biomarker name (even partial)\n" "- Specify a gene symbol\n" "- Add an assay type (e.g., 'IHC', 'NGS')\n\n" "**Example searches that work:**\n" "- `nci_biomarker_searcher(name='PD-L1')`\n" "- `nci_biomarker_searcher(gene='EGFR', biomarker_type='mutation')`\n" "- `nci_biomarker_searcher(assay_type='IHC')`" ) raise
• src/biomcp/biomarkers/search.py:81-153 (helper)

  Core helper function that performs the actual API request to NCI CTS for biomarker search, builds query parameters, processes the response, and handles errors.
  async def search_biomarkers( name: str | None = None, eligibility_criterion: str | None = None, biomarker_type: str | None = None, codes: list[str] | None = None, assay_purpose: str | None = None, include: list[str] | None = None, sort: str | None = None, order: str | None = None, page_size: int = 20, page: int = 1, api_key: str | None = None, ) -> dict[str, Any]: """ Search for biomarkers in the NCI CTS database. Note: Biomarker data availability may be limited per CTRP documentation. Results focus on biomarkers used in clinical trial eligibility criteria. Args: name: Biomarker name to search for (e.g., "PD-L1", "EGFR mutation") eligibility_criterion: Eligibility criterion text biomarker_type: Type of biomarker ("reference_gene" or "branch") codes: List of biomarker codes assay_purpose: Purpose of the assay include: Fields to include in response sort: Sort field order: Sort order ('asc' or 'desc') page_size: Number of results per page page: Page number api_key: Optional API key (if not provided, uses NCI_API_KEY env var) Returns: Dictionary with search results containing: - biomarkers: List of biomarker records - total: Total number of results - page: Current page - page_size: Results per page - note: Any limitations about the data Raises: CTSAPIError: If the API request fails """ # Build query parameters params = _build_biomarker_params( name, eligibility_criterion, biomarker_type, codes, assay_purpose, include, sort, order, page_size, ) try: # Make API request response = await make_cts_request( url=NCI_BIOMARKERS_URL, params=params, api_key=api_key, ) # Process response return _process_biomarker_response(response, page, page_size) except CTSAPIError: raise except Exception as e: logger.error(f"Failed to search biomarkers: {e}") raise CTSAPIError(f"Biomarker search failed: {e!s}") from e
• src/biomcp/biomarkers/search.py:302-329 (helper)

  Helper function that formats the raw biomarker search results into a user-friendly markdown string.
  def format_biomarker_results(results: dict[str, Any]) -> str: """ Format biomarker search results as markdown. Args: results: Search results dictionary Returns: Formatted markdown string """ biomarkers = results.get("biomarkers", []) total = results.get("total", 0) note = results.get("note", "") if not biomarkers: msg = "No biomarkers found matching the search criteria." if note: msg += f"\n\n*Note: {note}*" return msg # Build markdown output lines = _format_biomarker_header(total, note) for biomarker in biomarkers: lines.extend(_format_single_biomarker(biomarker)) return "\n".join(lines)
• src/biomcp/individual_tools.py:1105-1129 (schema)

  Pydantic schema definitions for the tool's input parameters using Annotated and Field.
  name: Annotated[ str | None, Field( description="Biomarker name to search for (e.g., 'PD-L1', 'EGFR mutation')" ), ] = None, biomarker_type: Annotated[ str | None, Field(description="Type of biomarker ('reference_gene' or 'branch')"), ] = None, api_key: Annotated[ str | None, Field( description="NCI API key. Check if user mentioned 'my NCI API key is...' in their message. If not provided here and no env var is set, user will be prompted to provide one." ), ] = None, page: Annotated[ int, Field(description="Page number (1-based)", ge=1), ] = 1, page_size: Annotated[ int, Field(description="Results per page", ge=1, le=100), ] = 20, ) -> str:
• src/biomcp/individual_tools.py:1103-1103 (registration)

  MCP tool registration decorator @mcp_app.tool() that registers nci_biomarker_searcher as an available tool.
  @track_performance("biomcp.nci_biomarker_searcher")