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", ]