BioMCP

Instructions

⚠️ PREREQUISITE: Use the 'think' tool FIRST to plan your research strategy!

Returns shortage information including:
- Current shortage status
- Shortage start and resolution dates
- Reason for shortage
- Therapeutic category
- Manufacturer information
- Estimated resolution timeline

Note: Shortage data is cached and updated periodically.
Check FDA.gov for most current information.

Implementation Reference

• src/biomcp/individual_tools.py:1733-1791 (handler)

  The main MCP tool handler for 'openfda_shortage_searcher'. Includes registration via @mcp_app.tool(), input schema definition using Pydantic Field, and core logic that computes pagination and delegates to the underlying search_drug_shortages implementation.

  @mcp_app.tool()
  @track_performance("biomcp.openfda_shortage_searcher")
  async def openfda_shortage_searcher(
      drug: Annotated[
          str | None,
          Field(description="Drug name (generic or brand) to search"),
      ] = None,
      status: Annotated[
          str | None,
          Field(description="Shortage status (current or resolved)"),
      ] = None,
      therapeutic_category: Annotated[
          str | None,
          Field(
              description="Therapeutic category (e.g., Oncology, Anti-infective)"
          ),
      ] = None,
      limit: Annotated[
          int,
          Field(description="Maximum number of results", ge=1, le=100),
      ] = 25,
      page: Annotated[
          int,
          Field(description="Page number (1-based)", ge=1),
      ] = 1,
      api_key: Annotated[
          str | None,
          Field(
              description="Optional OpenFDA API key (overrides OPENFDA_API_KEY env var)"
          ),
      ] = None,
  ) -> str:
      """Search FDA drug shortage records.
  
      ⚠️ PREREQUISITE: Use the 'think' tool FIRST to plan your research strategy!
  
      Returns shortage information including:
      - Current shortage status
      - Shortage start and resolution dates
      - Reason for shortage
      - Therapeutic category
      - Manufacturer information
      - Estimated resolution timeline
  
      Note: Shortage data is cached and updated periodically.
      Check FDA.gov for most current information.
      """
      from biomcp.openfda import search_drug_shortages
  
      skip = (page - 1) * limit
      return await search_drug_shortages(
          drug=drug,
          status=status,
          therapeutic_category=therapeutic_category,
          limit=limit,
          skip=skip,
          api_key=api_key,
      )

• src/biomcp/openfda/drug_shortages.py:174-250 (helper)

  Core helper function implementing the drug shortage search logic: manages caching of FDA shortage data, filters by drug/status/category, handles pagination, formats output with summaries and details.

  async def search_drug_shortages(
      drug: str | None = None,
      status: str | None = None,
      therapeutic_category: str | None = None,
      limit: int = OPENFDA_DEFAULT_LIMIT,
      skip: int = 0,
      api_key: str | None = None,
  ) -> str:
      """
      Search FDA drug shortage records.
  
      Args:
          drug: Drug name (generic or brand) to search for
          status: Shortage status (current, resolved, discontinued)
          therapeutic_category: Therapeutic category to filter by
          limit: Maximum number of results to return
          skip: Number of results to skip (for pagination)
          api_key: Optional OpenFDA API key (overrides OPENFDA_API_KEY env var)
  
      Returns:
          Formatted string with drug shortage information
      """
      # Get shortage data (from cache or fresh)
      data = await _get_cached_shortage_data()
  
      if not data:
          return (
              "⚠️ **Drug Shortage Data Temporarily Unavailable**\n\n"
              "The FDA drug shortage database cannot be accessed at this time. "
              "This feature requires FDA to provide a machine-readable API endpoint.\n\n"
              "**Alternative Options:**\n"
              "• Visit FDA Drug Shortages Database: https://www.accessdata.fda.gov/scripts/drugshortages/\n"
              "• Check ASHP Drug Shortages: https://www.ashp.org/drug-shortages/current-shortages\n\n"
              "Note: FDA currently provides shortage data only as PDF/HTML, not as a queryable API."
          )
  
      shortages = data.get("shortages", [])
  
      # Filter results based on criteria
      filtered = filter_shortages(shortages, drug, status, therapeutic_category)
  
      # Apply pagination
      total = len(filtered)
      filtered = filtered[skip : skip + limit]
  
      if not filtered:
          return "No drug shortages found matching your criteria."
  
      # Format the results
      output = ["## FDA Drug Shortage Information\n"]
  
      # Add header information
      last_updated = data.get("last_updated") or data.get("_fetched_at")
      output.extend(
          format_shortage_search_header(
              drug, status, therapeutic_category, last_updated
          )
      )
  
      output.append(
          f"**Total Shortages Found**: {format_count(total, 'shortage')}\n"
      )
  
      # Summary by status
      if len(filtered) > 1:
          output.extend(_format_shortage_summary(filtered))
  
      # Show results
      output.append(f"### Shortages (showing {len(filtered)} of {total}):\n")
  
      for i, shortage in enumerate(filtered, 1):
          output.extend(_format_shortage_entry(shortage, i))
  
      output.append(f"\n---\n{OPENFDA_SHORTAGE_DISCLAIMER}")
  
      return "\n".join(output)

• tests/tdd/test_mcp_integration.py:55-55 (registration)

  Test confirming the tool 'openfda_shortage_searcher' is properly registered in the MCP server tool list.

  assert "openfda_shortage_searcher" in tool_names