BioContextAI Knowledgebase MCP

Instructions

Implementation Reference

• src/biocontext_kb/core/openfda/_advanced_search.py:56-101 (handler)

  Main handler function for the tool, decorated as @core_mcp.tool(). Queries OpenFDA API using the specified therapeutic class and class_type (default 'epc'). Includes input schema via Annotated Fields.

  @core_mcp.tool()
  def search_drugs_by_therapeutic_class(
      therapeutic_class: Annotated[
          str,
          Field(
              description="Exact therapeutic/pharmacologic class term from FDA (use get_available_pharmacologic_classes first)"
          ),
      ],
      class_type: Annotated[
          str,
          Field(
              description="Class type: 'epc' (Established Pharmacologic Class), 'moa' (Mechanism of Action), 'pe' (Physiologic Effect), or 'cs' (Chemical Structure)"
          ),
      ] = "epc",
      limit: Annotated[int, Field(description="Number of results to return", ge=1, le=1000)] = 25,
  ) -> dict:
      """Search for drugs by therapeutic or pharmacologic class. Use get_available_pharmacologic_classes() first for exact terms.
  
      Returns:
          dict: FDA drug results array with application info, products, sponsor names or error message.
      """
      # Map class type to the appropriate OpenFDA field
      class_field_mapping = {
          "epc": "openfda.pharm_class_epc",  # Established Pharmacologic Class
          "moa": "openfda.pharm_class_moa",  # Mechanism of Action
          "pe": "openfda.pharm_class_pe",  # Physiologic Effect
          "cs": "openfda.pharm_class_cs",  # Chemical Structure
      }
  
      if class_type.lower() not in class_field_mapping:
          return {"error": "class_type must be one of: epc, moa, pe, cs"}
  
      field = class_field_mapping[class_type.lower()]
  
      # Use exact term as provided - no mapping since user should get this from get_available_pharmacologic_classes
      query = f'{field}:"{therapeutic_class}"'
  
      base_url = "https://api.fda.gov/drug/drugsfda.json"
      params: Any = {"search": query, "limit": limit}
  
      try:
          response = requests.get(base_url, params=params)
          response.raise_for_status()
          return response.json()
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch drugs by therapeutic class: {e!s}"}

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

  Main registration point where core_mcp (containing the tool) is imported into the top-level mcp_app with prefix 'bc' (from slugify('BC')), exposing the tool as 'bc_search_drugs_by_therapeutic_class'.

  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-7 (registration)

  Definition of the core_mcp FastMCP instance named 'BC', on which the tool is registered via @core_mcp.tool() decorator.

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

• src/biocontext_kb/core/openfda/_advanced_search.py:9-54 (helper)

  Supporting helper tool to retrieve available therapeutic/pharmacologic classes from OpenFDA, recommended to call first for exact terms.

  @core_mcp.tool()
  def get_available_pharmacologic_classes(
      class_type: Annotated[
          str,
          Field(
              description="Class type: 'epc' (Established Pharmacologic Class), 'moa' (Mechanism of Action), 'pe' (Physiologic Effect), or 'cs' (Chemical Structure)"
          ),
      ] = "epc",
      limit: Annotated[int, Field(description="Number of unique classes to return", ge=1, le=1000)] = 100,
  ) -> dict:
      """Get available pharmacologic classes from FDA database. Call this first to see available options.
  
      Returns:
          dict: Class type, field, available_classes array with term/count, total_found or error message.
      """
      # Map class type to the appropriate OpenFDA field
      class_field_mapping = {
          "epc": "openfda.pharm_class_epc",  # Established Pharmacologic Class
          "moa": "openfda.pharm_class_moa",  # Mechanism of Action
          "pe": "openfda.pharm_class_pe",  # Physiologic Effect
          "cs": "openfda.pharm_class_cs",  # Chemical Structure
      }
  
      if class_type.lower() not in class_field_mapping:
          return {"error": "class_type must be one of: epc, moa, pe, cs"}
  
      field = class_field_mapping[class_type.lower()]
  
      # Use the count endpoint to get unique values
      base_url = "https://api.fda.gov/drug/drugsfda.json"
      params: Any = {"count": field, "limit": limit}
  
      try:
          response = requests.get(base_url, params=params)
          response.raise_for_status()
          data = response.json()
  
          return {
              "class_type": class_type,
              "field": field,
              "available_classes": data.get("results", []),
              "total_found": len(data.get("results", [])),
          }
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch available pharmacologic classes: {e!s}"}

• src/biocontext_kb/core/openfda/_advanced_search.py:57-101 (schema)

  Pydantic schema definitions for tool inputs via Annotated and Field.

  def search_drugs_by_therapeutic_class(
      therapeutic_class: Annotated[
          str,
          Field(
              description="Exact therapeutic/pharmacologic class term from FDA (use get_available_pharmacologic_classes first)"
          ),
      ],
      class_type: Annotated[
          str,
          Field(
              description="Class type: 'epc' (Established Pharmacologic Class), 'moa' (Mechanism of Action), 'pe' (Physiologic Effect), or 'cs' (Chemical Structure)"
          ),
      ] = "epc",
      limit: Annotated[int, Field(description="Number of results to return", ge=1, le=1000)] = 25,
  ) -> dict:
      """Search for drugs by therapeutic or pharmacologic class. Use get_available_pharmacologic_classes() first for exact terms.
  
      Returns:
          dict: FDA drug results array with application info, products, sponsor names or error message.
      """
      # Map class type to the appropriate OpenFDA field
      class_field_mapping = {
          "epc": "openfda.pharm_class_epc",  # Established Pharmacologic Class
          "moa": "openfda.pharm_class_moa",  # Mechanism of Action
          "pe": "openfda.pharm_class_pe",  # Physiologic Effect
          "cs": "openfda.pharm_class_cs",  # Chemical Structure
      }
  
      if class_type.lower() not in class_field_mapping:
          return {"error": "class_type must be one of: epc, moa, pe, cs"}
  
      field = class_field_mapping[class_type.lower()]
  
      # Use exact term as provided - no mapping since user should get this from get_available_pharmacologic_classes
      query = f'{field}:"{therapeutic_class}"'
  
      base_url = "https://api.fda.gov/drug/drugsfda.json"
      params: Any = {"search": query, "limit": limit}
  
      try:
          response = requests.get(base_url, params=params)
          response.raise_for_status()
          return response.json()
      except requests.exceptions.RequestException as e:
          return {"error": f"Failed to fetch drugs by therapeutic class: {e!s}"}