BioContextAI Knowledgebase MCP

Instructions

Implementation Reference

• src/biocontext_kb/core/openfda/_advanced_search.py:104-190 (handler)

  The core handler function for the 'get_generic_equivalents' tool (prefixed to 'bc_get_generic_equivalents' in main app). It fetches the brand drug's active ingredients from OpenFDA and searches for matching ANDA (generic) approvals.

  @core_mcp.tool()
  def get_generic_equivalents(
      brand_name: Annotated[str, Field(description="Brand name drug to find generics for")],
  ) -> dict:
      """Find generic equivalents for a brand name drug. Searches ANDA entries with matching active ingredients.
  
      Returns:
          dict: Brand drug info, generic_equivalents array, total_generics_found count or error message.
      """
      # First, search for the brand name drug to get its active ingredient
      brand_query = f"(openfda.brand_name:{brand_name} OR products.brand_name:{brand_name})"
      base_url = "https://api.fda.gov/drug/drugsfda.json"
      brand_params: Any = {"search": brand_query, "limit": 1}
  
      try:
          brand_response = requests.get(base_url, params=brand_params)
          brand_response.raise_for_status()
          brand_data = brand_response.json()
  
          if not brand_data.get("results"):
              return {"error": f"Brand name drug '{brand_name}' not found in FDA database"}
  
          # Extract active ingredients from the brand drug
          brand_drug = brand_data["results"][0]
  
          # Check if we have products and active ingredients
          if not brand_drug.get("products"):
              return {"error": f"Could not find product information for '{brand_name}'"}
  
          # Search for generic drugs (ANDA applications) with similar active ingredients
          generic_results = []
  
          # Try to find active ingredients from the first product
          for product in brand_drug["products"][:1]:  # Just check first product
              if product.get("active_ingredients"):
                  active_ingredients = product["active_ingredients"]
  
                  # Handle case where active_ingredients might be an object or array
                  if isinstance(active_ingredients, dict):
                      ingredient_name = active_ingredients.get("name", "")
                      if ingredient_name:
                          # Search for ANDA applications with this active ingredient
                          generic_query = (
                              f"application_number:ANDA* AND products.active_ingredients.name:{ingredient_name}"
                          )
                          generic_params: Any = {"search": generic_query, "limit": 20}
  
                          try:
                              generic_response = requests.get(base_url, params=generic_params)
                              generic_response.raise_for_status()
                              generic_data = generic_response.json()
  
                              if generic_data.get("results"):
                                  generic_results.extend(generic_data["results"])
                          except requests.exceptions.RequestException:
                              continue  # Skip this ingredient if search fails
  
                  elif isinstance(active_ingredients, list):
                      for ingredient in active_ingredients:
                          if isinstance(ingredient, dict):
                              ingredient_name = ingredient.get("name", "")
                              if ingredient_name:
                                  # Search for ANDA applications with this active ingredient
                                  generic_query = (
                                      f"application_number:ANDA* AND products.active_ingredients.name:{ingredient_name}"
                                  )
                                  generic_params = {"search": generic_query, "limit": 20}
  
                                  try:
                                      generic_response = requests.get(base_url, params=generic_params)
                                      generic_response.raise_for_status()
                                      generic_data = generic_response.json()
  
                                      if generic_data.get("results"):
                                          generic_results.extend(generic_data["results"])
                                  except requests.exceptions.RequestException:
                                      continue  # Skip this ingredient if search fails
  
          return {
              "brand_drug": brand_drug,
              "generic_equivalents": generic_results,
              "total_generics_found": len(generic_results),
          }
  
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch generic equivalents: {e!s}"}

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

  Registers the core_mcp (name='BC') into the main mcp_app with prefix slugify('BC')='bc', making tools available as 'bc_*' including 'bc_get_generic_equivalents'.

  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/_server.py:3-6 (registration)

  Defines core_mcp FastMCP server instance named 'BC' where tools like get_generic_equivalents are decorated and registered.

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

• src/biocontext_kb/core/openfda/_advanced_search.py:105-107 (schema)

  Pydantic schema for input: brand_name (str, required, description provided). Output: dict with brand_drug, generic_equivalents list, total_generics_found.

  def get_generic_equivalents(
      brand_name: Annotated[str, Field(description="Brand name drug to find generics for")],
  ) -> dict:

• src/biocontext_kb/core/openfda/__init__.py:1-5 (registration)

  Exports get_generic_equivalents from _advanced_search.py for use in core_mcp.

  from ._advanced_search import (
      get_available_pharmacologic_classes,
      get_generic_equivalents,
      search_drugs_by_therapeutic_class,
  )