BioMCP

Instructions

Implementation Reference

• src/biomcp/individual_tools.py:1187-1270 (handler)

  Primary MCP tool handler for 'nci_disease_searcher'. Registers the tool via @mcp_app.tool(), defines input schema via Pydantic Fields, and implements logic by delegating to search_diseases helper with error handling and user-friendly broad-search messages.
  @track_performance("biomcp.nci_disease_searcher") async def nci_disease_searcher( name: Annotated[ str | None, Field(description="Disease name to search for (partial match)"), ] = None, include_synonyms: Annotated[ bool, Field(description="Include synonym matches in search"), ] = True, category: Annotated[ str | None, Field(description="Disease category/type filter"), ] = 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 NCI's controlled vocabulary of cancer conditions. Searches the National Cancer Institute's curated database of cancer conditions and diseases used in clinical trials. This is different from the general disease_getter tool which uses MyDisease.info. NCI's disease vocabulary provides: - Official cancer terminology used in trials - Disease synonyms and alternative names - Hierarchical disease classifications - Standardized disease codes for trial matching Requires NCI API key from: https://clinicaltrialsapi.cancer.gov/ Example usage: - Search for specific cancer types (e.g., "melanoma") - Find all lung cancer subtypes - Look up official names for disease synonyms - Get standardized disease terms for trial searches Note: This is specifically for NCI's cancer disease vocabulary. For general disease information, use the disease_getter tool. """ from biomcp.diseases import search_diseases from biomcp.diseases.search import format_disease_results from biomcp.integrations.cts_api import CTSAPIError try: results = await search_diseases( name=name, include_synonyms=include_synonyms, category=category, page_size=page_size, page=page, api_key=api_key, ) return format_disease_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 disease name (even partial)\n" "- Specify a disease category\n" "- Use more specific search terms\n\n" "**Example searches that work:**\n" "- `nci_disease_searcher(name='melanoma')`\n" "- `nci_disease_searcher(name='lung', category='maintype')`\n" "- `nci_disease_searcher(name='NSCLC')`" ) raise
• src/biomcp/diseases/search.py:67-151 (helper)

  Core helper implementing the NCI CTS API search for diseases, building query params, making the HTTP request, and processing response.
  async def search_diseases( name: str | None = None, include_synonyms: bool = True, # Deprecated - kept for backward compatibility category: str | None = None, disease_type: str | None = None, codes: list[str] | None = None, parent_ids: list[str] | None = None, ancestor_ids: list[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 diseases in the NCI CTS database. This provides access to NCI's controlled vocabulary of cancer conditions used in clinical trials, with official terms and synonyms. Args: name: Disease name to search for (partial match, searches synonyms automatically) include_synonyms: [Deprecated] This parameter is ignored - API always searches synonyms category: Disease category/type filter (deprecated - use disease_type) disease_type: Type of disease (e.g., 'maintype', 'subtype', 'stage') codes: List of disease codes (e.g., ['C3868', 'C5806']) parent_ids: List of parent disease IDs ancestor_ids: List of ancestor disease IDs 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: - diseases: List of disease records with names and synonyms - total: Total number of results - page: Current page - page_size: Results per page Raises: CTSAPIError: If the API request fails """ # Build query parameters params = _build_disease_params( name, disease_type, category, codes, parent_ids, ancestor_ids, include, sort, order, page_size, ) try: # Make API request response = await make_cts_request( url=NCI_DISEASES_URL, params=params, api_key=api_key, ) # Process response diseases = response.get("data", response.get("diseases", [])) total = response.get("total", len(diseases)) return { "diseases": diseases, "total": total, "page": page, "page_size": page_size, } except CTSAPIError: raise except Exception as e: logger.error(f"Failed to search diseases: {e}") raise CTSAPIError(f"Disease search failed: {e!s}") from e
• src/biomcp/diseases/search.py:251-277 (helper)

  Helper function to format raw disease search results into readable markdown output with disease names, IDs, categories, synonyms, and codes.
  def format_disease_results(results: dict[str, Any]) -> str: """ Format disease search results as markdown. Args: results: Search results dictionary Returns: Formatted markdown string """ diseases = results.get("diseases", []) total = results.get("total", 0) if not diseases: return "No diseases found matching the search criteria." # Build markdown output lines = [ f"## Disease Search Results ({total} found)", "", ] for disease in diseases: lines.extend(_format_single_disease(disease)) return "\n".join(lines)