bc_get_chebi_terms_by_chemical
Retrieve ChEBI terms and details for a specified chemical name using the Ontology Lookup Service (OLS). Enables precise chemical identification for biomedical research.
Instructions
Query the Ontology Lookup Service (OLS) for ChEBI terms related to a chemical name.
This function searches for ChEBI (Chemical Entities of Biological Interest) terms associated with a given chemical name using the OLS API.
Args: chemical_name (str): The chemical or drug name to search for (e.g., "aspirin"). size (int): Maximum number of results to return (default: 10). exact_match (bool): Whether to perform an exact match search (default: False).
Returns: dict: Dictionary containing ChEBI terms and information or error message
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chemical_name | Yes | The chemical or drug name to search for (e.g., 'aspirin', 'glucose') | |
| exact_match | No | Whether to perform an exact match search | |
| size | No | The maximum number of results to return |
Implementation Reference
- The main handler function for the tool, decorated with @core_mcp.tool(). Queries the OLS API for ChEBI terms matching the given chemical name, filters for CHEBI: prefixed terms, and returns structured results.@core_mcp.tool() def get_chebi_terms_by_chemical( chemical_name: Annotated[ str, Field(description="Chemical or drug name to search for (e.g., 'aspirin', 'glucose')") ], size: Annotated[ int, Field(description="Maximum number of results to return"), ] = 10, exact_match: Annotated[ bool, Field(description="Whether to perform exact match search"), ] = False, ) -> Dict[str, Any]: """Search OLS for ChEBI (Chemical Entities of Biological Interest) terms for a chemical or drug name. Returns: dict: ChEBI terms with chebi_terms array containing id, label, description, synonyms or error message. """ if not chemical_name: return {"error": "chemical_name must be provided"} url = "https://www.ebi.ac.uk/ols4/api/v2/entities" params = { "search": chemical_name, "size": str(size), "lang": "en", "exactMatch": str(exact_match).lower(), "includeObsoleteEntities": "false", "ontologyId": "chebi", } def starts_with_chebi_prefix(curie: str) -> bool: """Check if the curie starts with CHEBI prefix.""" return curie.startswith("CHEBI:") try: response = requests.get(url, params=params) response.raise_for_status() data = response.json() # Check that at least one item is in elements with CHEBI prefix if not data.get("elements") or not any( starts_with_chebi_prefix(str(element.get("curie", ""))) for element in data["elements"] ): return {"error": "No ChEBI terms found"} # Extract ChEBI terms and their information chebi_terms = [ { "id": element["curie"].replace(":", "_"), "label": element["label"], "description": element.get("description", ""), "ontology_name": element.get("ontologyName", ""), "synonyms": element.get("synonyms", []), } for element in data["elements"] if starts_with_chebi_prefix(str(element.get("curie", ""))) ] return {"chebi_terms": chebi_terms} except requests.exceptions.RequestException as e: return {"error": f"Failed to fetch ChEBI terms: {e!s}"}
- src/biocontext_kb/core/_server.py:3-6 (registration)Creation of the FastMCP server instance 'core_mcp' with prefix 'BC', to which tools are registered via decorators.core_mcp = FastMCP( # type: ignore "BC", instructions="Provides access to biomedical knowledge bases.", )
- Import of the tool function in the OLS module __init__.py, ensuring it's available for registration.from ._get_chebi_terms_by_chemical import get_chebi_terms_by_chemical