BioContextAI Knowledgebase MCP

Instructions

Implementation Reference

• src/biocontext_kb/core/ols/_get_term_hierarchical_children.py:1-77 (handler)

  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.")

• src/biocontext_kb/core/ols/_get_term_hierarchical_children.py:10-17 (schema)

  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]: