bc_search_drugs_by_therapeutic_class

Instructions

Implementation Reference

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

  The actual handler function for the 'bc_search_drugs_by_therapeutic_class' MCP tool. It queries the FDA openFDA API to search for drugs by therapeutic/pharmacologic class (EPC, MOA, PE, CS). Decorated with @core_mcp.tool().

  @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/core/openfda/_advanced_search.py:56-75 (schema)

  Pydantic/Annotated Field definitions for the tool's input parameters: therapeutic_class (str), class_type (str with default 'epc'), and limit (int with default 25). The return type is dict.

  @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.

• src/biocontext_kb/core/_server.py:1-6 (registration)

  The core_mcp FastMCP server instance used by the @core_mcp.tool() decorator to register the tool. This is where the tool gets registered as part of the 'BC' MCP server.

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

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

  The function is exported from the openfda package's __init__.py, making it part of the openfda module that is imported in core/__init__.py.

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

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

  Supporting tool get_available_pharmacologic_classes() in the same file is designed to be called first to get exact class terms before using search_drugs_by_therapeutic_class.

  @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}"}