BioContextAI Knowledgebase MCP

Instructions

Implementation Reference

• src/biocontext_kb/core/ols/_get_cell_ontology_terms.py:9-76 (handler)

  The handler function implementing the tool logic. Queries the OLS API (https://www.ebi.ac.uk/ols4/api/v2/entities) for Cell Ontology (CL) terms matching the cell_type, filters for CL: prefixed terms, and returns structured data including id, label, definition, synonyms, etc.

  @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/_get_cell_ontology_terms.py:10-20 (schema)

  Pydantic schema definitions for input parameters using Annotated and Field, and output as Dict[str, Any].

  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/app.py:35-40 (registration)

  Registers core_mcp (containing the tool) into the main mcp_app with prefix=slugify('BC')='bc', resulting in the tool name 'bc_get_cell_ontology_terms'.

  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/__init__.py:12-12 (registration)

  Imports all OLS tools (including get_cell_ontology_terms), ensuring their decorators register them in core_mcp.

  from .ols import *

• src/biocontext_kb/core/ols/__init__.py:2-2 (registration)

  Imports the handler function, triggering its @core_mcp.tool() decorator to register it in core_mcp.

  from ._get_cell_ontology_terms import get_cell_ontology_terms