BioContextAI Knowledgebase MCP

Instructions

Implementation Reference

• src/biocontext_kb/core/ols/_get_chebi_terms_by_chemical.py:1-74 (handler)

  The handler function for the 'bc_get_chebi_terms_by_chemical' tool. It queries the OLS API for ChEBI terms by chemical name, filters for CHEBI: prefixed terms, and returns structured data or error.

  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_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:1-6 (registration)

  Defines the core_mcp FastMCP instance with name 'BC', which prefixes tool names with 'bc_' and is used by @core_mcp.tool() decorator to register the tool.

  from fastmcp import FastMCP
  
  core_mcp = FastMCP(  # type: ignore
      "BC",
      instructions="Provides access to biomedical knowledge bases.",
  )

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

  Imports the get_chebi_terms_by_chemical function, which triggers the @tool decorator registration when the module is imported.

  from ._get_available_ontologies import get_available_ontologies
  from ._get_cell_ontology_terms import get_cell_ontology_terms
  from ._get_chebi_terms_by_chemical import get_chebi_terms_by_chemical
  from ._get_efo_id_by_disease_name import get_efo_id_by_disease_name
  from ._get_go_terms_by_gene import get_go_terms_by_gene
  from ._get_term_details import get_term_details
  from ._get_term_hierarchical_children import get_term_hierarchical_children
  from ._search_ontology_terms import search_ontology_terms
  
  __all__ = [
      "get_available_ontologies",
      "get_cell_ontology_terms",
      "get_chebi_terms_by_chemical",
      "get_efo_id_by_disease_name",
      "get_go_terms_by_gene",
      "get_term_details",
      "get_term_hierarchical_children",
      "search_ontology_terms",
  ]

• src/biocontext_kb/app.py:35-39 (registration)

  Imports the core_mcp (containing the registered OLS tools) into the main BioContextAI MCP application.

  for mcp in [core_mcp, *(await get_openapi_mcps())]:
      await mcp_app.import_server(
          mcp,
          slugify(mcp.name),
      )

• src/biocontext_kb/core/ols/_get_chebi_terms_by_chemical.py:10-22 (schema)

  Pydantic-based input schema with Annotated Fields defining parameters for the 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]: