BioContextAI Knowledgebase MCP

Instructions

Implementation Reference

• src/biocontext_kb/core/openfda/_search_drugs.py:9-113 (handler)

  The core handler function for the 'search_drugs_fda' tool (prefixed to 'bc_search_drugs_fda' upon server import), decorated with @core_mcp.tool(). Includes input schema via Annotated Fields and full execution logic querying the FDA Drugs@FDA API.

  @core_mcp.tool()
  def search_drugs_fda(
      brand_name: Annotated[Optional[str], Field(description="Brand or trade name (e.g., 'Tylenol')")] = None,
      generic_name: Annotated[Optional[str], Field(description="Generic name (e.g., 'acetaminophen')")] = None,
      active_ingredient: Annotated[Optional[str], Field(description="Active ingredient name")] = None,
      sponsor_name: Annotated[Optional[str], Field(description="Company/sponsor name")] = None,
      application_number: Annotated[
          Optional[str], Field(description="FDA application number (NDA, ANDA, or BLA)")
      ] = None,
      marketing_status: Annotated[
          Optional[str],
          Field(
              description="Marketing status: 'Prescription', 'Over-the-counter', 'Discontinued', or 'None (Tentative Approval)'"
          ),
      ] = None,
      dosage_form: Annotated[
          Optional[str], Field(description="Dosage form (e.g., 'TABLET', 'INJECTION', 'CAPSULE')")
      ] = None,
      route: Annotated[
          Optional[str], Field(description="Route of administration (e.g., 'ORAL', 'INJECTION', 'TOPICAL')")
      ] = None,
      search_type: Annotated[str, Field(description="'and' for all terms must match, 'or' for any term matches")] = "or",
      sort_by: Annotated[
          Optional[str], Field(description="Field to sort by (e.g., 'sponsor_name', 'application_number')")
      ] = None,
      limit: Annotated[int, Field(description="Number of results to return", ge=1, le=1000)] = 25,
      skip: Annotated[int, Field(description="Number of results to skip for pagination", ge=0, le=25000)] = 0,
  ) -> dict:
      """Search FDA Drugs@FDA database for approved drug products. Supports multiple search criteria.
  
      Returns:
          dict: Results array with drug products including application numbers, sponsors, products array or error message.
      """
      # Ensure at least one search parameter is provided
      search_params = [
          brand_name,
          generic_name,
          active_ingredient,
          sponsor_name,
          application_number,
          marketing_status,
          dosage_form,
          route,
      ]
      if not any(search_params):
          return {"error": "At least one search parameter must be provided"}
  
      # Build query components - using correct schema field paths
      query_parts = []
  
      if brand_name:
          # Search in both openfda.brand_name and products.brand_name arrays
          query_parts.append(f"(openfda.brand_name:{brand_name} OR products.brand_name:{brand_name})")
  
      if generic_name:
          # openfda.generic_name is an array
          query_parts.append(f"openfda.generic_name:{generic_name}")
  
      if active_ingredient:
          # products.active_ingredients.name
          query_parts.append(f"products.active_ingredients.name:{active_ingredient}")
  
      if sponsor_name:
          query_parts.append(f"sponsor_name:{sponsor_name}")
  
      if application_number:
          query_parts.append(f"application_number.exact:{application_number}")
  
      if marketing_status:
          # Map user-friendly terms to API values - products.marketing_status
          status_mapping = {
              "prescription": "1",
              "discontinued": "2",
              "none (tentative approval)": "3",
              "over-the-counter": "4",
          }
          status_value = status_mapping.get(marketing_status.lower(), marketing_status)
          query_parts.append(f"products.marketing_status:{status_value}")
  
      if dosage_form:
          query_parts.append(f"products.dosage_form:{dosage_form}")
  
      if route:
          query_parts.append(f"products.route:{route}")
  
      # Join query parts based on search type
      query = " AND ".join(query_parts) if search_type.lower() == "and" else " OR ".join(query_parts)
  
      # Build URL parameters for proper encoding
      params = {"search": query, "limit": limit, "skip": skip}
  
      # Add sorting if specified
      if sort_by:
          params["sort"] = f"{sort_by}:desc"
  
      # Build the complete URL
      base_url = "https://api.fda.gov/drug/drugsfda.json"
  
      try:
          response = requests.get(base_url, params=params)  # type: ignore
          response.raise_for_status()
          return response.json()
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch FDA drug data: {e!s}"}

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

  Registers the core_mcp server (containing the search_drugs_fda tool) into the main MCP app with prefix 'bc' via slugify('BC'), resulting in tool name 'bc_search_drugs_fda'.

  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 the core_mcp FastMCP server instance named 'BC' where tools like search_drugs_fda are registered via decorators.

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

• src/biocontext_kb/core/__init__.py:13-14 (registration)

  Imports all tools from openfda module into core namespace, ensuring search_drugs_fda is available for registration in core_mcp.

  from .openfda import *
  from .opentargets import *

• src/biocontext_kb/core/openfda/__init__.py:8-36 (schema)

  Exports the search_drugs_fda tool function (with its inline schema) for import into core module.

  from ._search_drugs import search_drugs_fda
  
  __all__ = [
      "count_drugs_by_field",
      "get_available_pharmacologic_classes",
      "get_drug_by_application_number",
      "get_drug_label_info",
      "get_drug_statistics",
      "get_generic_equivalents",
      "search_drugs_by_therapeutic_class",
      "search_drugs_fda",
  ]