bc_get_cell_ontology_terms
Retrieve Cell Ontology (CL) terms for specific cell types using the Ontology Lookup Service (OLS). This tool enables precise identification of controlled vocabulary terms for cells, aiding in standardized biological data annotation and analysis.
Instructions
Query the Ontology Lookup Service (OLS) for Cell Ontology (CL) terms.
This function searches for Cell Ontology terms associated with cell types using the OLS API. The Cell Ontology provides a controlled vocabulary for cell types.
Args: cell_type (str): The cell type to search for (e.g., "T cell"). 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 Cell Ontology terms and information or error message
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cell_type | Yes | The cell type to search for (e.g., 'T cell', 'neuron', 'hepatocyte') | |
| exact_match | No | Whether to perform an exact match search | |
| size | No | The maximum number of results to return |
Implementation Reference
- The handler function `get_cell_ontology_terms` decorated with `@core_mcp.tool()`, which queries the OLS API for Cell Ontology (CL) terms matching the provided cell_type, filters for CL: prefixed terms, and returns structured term details or error.@core_mcp.tool() def get_cell_ontology_terms( cell_type: Annotated[str, Field(description="Cell type to search for (e.g., 'T cell', 'neuron')")], 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 Cell Ontology (CL) terms using a controlled vocabulary for cell types. Returns: dict: Cell ontology terms with cl_terms array containing id, label, definition, synonyms or error message. """ if not cell_type: return {"error": "cell_type must be provided"} url = "https://www.ebi.ac.uk/ols4/api/v2/entities" params = { "search": cell_type, "size": str(size), "lang": "en", "exactMatch": str(exact_match).lower(), "includeObsoleteEntities": "false", "ontologyId": "cl", } def starts_with_cl_prefix(curie: str) -> bool: """Check if the curie starts with CL prefix.""" return curie.startswith("CL:") try: response = requests.get(url, params=params) response.raise_for_status() data = response.json() # Check that at least one item is in elements with CL prefix if not data.get("elements") or not any( starts_with_cl_prefix(str(element.get("curie", ""))) for element in data["elements"] ): return {"error": "No Cell Ontology terms found"} # Extract Cell Ontology terms with detailed information cl_terms = [ { "id": element["curie"].replace(":", "_"), "label": element.get("label", ""), "definition": element.get("definition", ""), "synonyms": element.get("synonym", []), "ontology_name": element.get("ontologyName", ""), "is_defining_ontology": element.get("isDefiningOntology", False), "has_hierarchical_children": element.get("hasHierarchicalChildren", False), "has_hierarchical_parents": element.get("hasHierarchicalParents", False), "num_descendants": element.get("numDescendants", 0), } for element in data["elements"] if starts_with_cl_prefix(str(element.get("curie", ""))) ] return {"cl_terms": cl_terms} except requests.exceptions.RequestException as e: return {"error": f"Failed to fetch Cell Ontology terms: {e!s}"}
- src/biocontext_kb/core/ols/__init__.py:2-2 (registration)Imports the `get_cell_ontology_terms` function, triggering its registration via the `@core_mcp.tool()` decorator when the module is imported.from ._get_cell_ontology_terms import get_cell_ontology_terms
- src/biocontext_kb/app.py:35-39 (registration)Imports the `core_mcp` server (named 'BC', slugified to 'bc') into the main MCP app, namespacing tools like `get_cell_ontology_terms` under 'bc_' prefix (e.g., 'bc_get_cell_ontology_terms').for mcp in [core_mcp, *(await get_openapi_mcps())]: await mcp_app.import_server( mcp, slugify(mcp.name), )
- Pydantic schema definitions for tool inputs using Annotated and Field for cell_type (str), size (int, default 10), exact_match (bool, default False).def get_cell_ontology_terms( cell_type: Annotated[str, Field(description="Cell type to search for (e.g., 'T cell', 'neuron')")], 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]:
- src/biocontext_kb/core/_server.py:3-6 (registration)Defines the `core_mcp` FastMCP server instance named 'BC' to which tools are registered via @core_mcp.tool() decorator.core_mcp = FastMCP( # type: ignore "BC", instructions="Provides access to biomedical knowledge bases.", )