bc_get_term_hierarchical_children
Retrieve hierarchical child terms from biomedical ontologies to understand term relationships and structure in knowledge bases.
Instructions
Get hierarchical children of an ontology term from OLS. Includes subclasses and hierarchical properties.
Returns: dict: Parent term, hierarchical_children array with id/label/definition, total_children, page_info or error message.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| term_id | Yes | Term ID in CURIE format (e.g., 'EFO:0000001', 'GO:0008150') | |
| ontology_id | Yes | Ontology ID (e.g., 'efo', 'go', 'chebi') | |
| size | No | Maximum number of children to return |
Implementation Reference
- The core implementation of the 'get_term_hierarchical_children' tool handler, decorated with @core_mcp.tool(). This function queries the OLS API for hierarchical children of a given ontology term. The tool is part of the 'BC' FastMCP server, which is imported with prefix 'bc', resulting in the tool name 'bc_get_term_hierarchical_children'. Includes input schema via Pydantic Annotated fields.from typing import Annotated, Any, Dict import requests from pydantic import Field from biocontext_kb.core._server import core_mcp @core_mcp.tool() def get_term_hierarchical_children( term_id: Annotated[str, Field(description="Term ID in CURIE format (e.g., 'EFO:0000001', 'GO:0008150')")], ontology_id: Annotated[str, Field(description="Ontology ID (e.g., 'efo', 'go', 'chebi')")], size: Annotated[ int, Field(description="Maximum number of children to return"), ] = 20, ) -> Dict[str, Any]: """Get hierarchical children of an ontology term from OLS. Includes subclasses and hierarchical properties. Returns: dict: Parent term, hierarchical_children array with id/label/definition, total_children, page_info or error message. """ if not term_id: return {"error": "term_id must be provided"} if not ontology_id: return {"error": "ontology_id must be provided"} # Double URL encode the term IRI import urllib.parse term_iri = f"http://purl.obolibrary.org/obo/{term_id.replace(':', '_')}" encoded_iri = urllib.parse.quote(urllib.parse.quote(term_iri, safe=""), safe="") url = f"https://www.ebi.ac.uk/ols4/api/v2/ontologies/{ontology_id}/classes/{encoded_iri}/hierarchicalChildren" params = { "size": str(size), "page": "0", } try: response = requests.get(url, params=params) response.raise_for_status() data = response.json() if not data.get("elements"): return {"error": "No hierarchical children found"} # Extract children information children = [ { "id": element.get("curie", "").replace(":", "_"), "curie": element.get("curie", ""), "label": element.get("label", ""), "definition": element.get("definition", ""), "ontology_name": element.get("ontologyName", ""), "has_hierarchical_children": element.get("hasHierarchicalChildren", False), "num_descendants": element.get("numDescendants", 0), } for element in data["elements"] ] return { "parent_term": term_id, "hierarchical_children": children, "total_children": data.get("totalElements", len(children)), "page_info": { "page": data.get("page", 0), "total_pages": data.get("totalPages", 1), "num_elements": data.get("numElements", len(children)), }, } except requests.exceptions.RequestException as e: return {"error": f"Failed to fetch hierarchical children: {e!s}"}
- src/biocontext_kb/core/_server.py:1-6 (registration)Defines the 'core_mcp' FastMCP server instance named 'BC', to which tools like get_term_hierarchical_children are registered via @core_mcp.tool() decorators. This server is later imported into the main app with slugify('BC') = 'bc' prefix.from fastmcp import FastMCP core_mcp = FastMCP( # type: ignore "BC", instructions="Provides access to biomedical knowledge bases.", )
- src/biocontext_kb/app.py:35-40 (registration)Imports the 'core_mcp' server (containing the tool) into the main 'BioContextAI' MCP app using import_server with slugified prefix 'bc', effectively registering all core tools with 'bc_' prefix, including 'bc_get_term_hierarchical_children'.for mcp in [core_mcp, *(await get_openapi_mcps())]: await mcp_app.import_server( mcp, slugify(mcp.name), ) logger.info("MCP server setup complete.")
- Input schema defined using Pydantic's Annotated and Field for the tool parameters: term_id (str), ontology_id (str), size (int, default 20). Output is Dict[str, Any].def get_term_hierarchical_children( term_id: Annotated[str, Field(description="Term ID in CURIE format (e.g., 'EFO:0000001', 'GO:0008150')")], ontology_id: Annotated[str, Field(description="Ontology ID (e.g., 'efo', 'go', 'chebi')")], size: Annotated[ int, Field(description="Maximum number of children to return"), ] = 20, ) -> Dict[str, Any]: