README.md

---
title: Pharmacist MCP
emoji: 💊
colorFrom: blue
colorTo: green
sdk: gradio
app_file: app.py
pinned: false
license: apache-2.0
tags:
  - pharmacology
  - clinical-pharmacy
  - healthcare
  - drug-information
  - calculator
  - gradio
  - mcp-server-track
sdk_version: 5.33.1
---
# Pharmacist MCP Server

A comprehensive Model Context Protocol (MCP) server providing pharmaceutical and clinical decision support tools for healthcare applications. Two excample videos demonstrating usage can be found [here](https://youtu.be/Ku2EOHTnPYs) and [here](https://youtu.be/ufPnoJ6TZNI ).

## 🚀 Features

### Drug Information & Safety

- **Adverse Event Search**: Query FAERS database for drug safety reports
- **Drug Label Warnings**: FDA boxed warnings, contraindications, and interactions
- **Drug Recalls**: Recent FDA recall information
- **Pregnancy & Lactation**: Comprehensive safety information with fallback data
- **Dose Adjustments**: Renal and hepatic dosing guidance
- **LiverTox Integration**: Hepatotoxicity information from NIH database

### Advanced ADR Analysis (NEW!)

- **Enhanced FAERS Search**: Advanced filtering by demographics, seriousness, and outcomes
- **Naranjo Probability Scale**: Automated causality assessment for adverse drug reactions
- **Disproportionality Analysis**: Signal detection using PRR, ROR, and IC methods
- **Case Similarity Analysis**: Find similar adverse event cases
- **Temporal Analysis**: Time-to-onset patterns and reporting trends

### Clinical Calculators

- **Creatinine Clearance**: Cockcroft-Gault equation
- **eGFR**: CKD-EPI equation with CKD staging
- **Child-Pugh Score**: Liver function assessment
- **BMI Calculator**: Body mass index and weight categories
- **Ideal Body Weight**: Devine formula
- **Dosing Weight**: Recommendations for medication dosing
- **Drug Burden Index (DBI)**: Anticholinergic and sedative burden assessment

### Utility Functions

- **Brand to Generic Lookup**: International drug name conversion
- **Unit Conversions**: Creatinine units (mg/dL ↔ μmol/L)
- **Cache Management**: Performance optimization with TTL caching
- **Health Monitoring**: Server status and performance metrics

## 🧬 ADR Analysis Capabilities

### Pharmacovigilance Tools

The server now includes comprehensive adverse drug reaction (ADR) analysis tools suitable for clinical decision support and pharmacovigilance:

#### 1. Enhanced FAERS Search

```python
# Search with demographic filters
enhanced_faers_search(
    drug_name="warfarin",
    adverse_event="bleeding", 
    age_range=">65",
    gender="2",  # female
    serious_only=True
)
```

#### 2. Naranjo Causality Assessment

```python
# Automated causality scoring
calculate_naranjo_score(
    adverse_reaction_after_drug="yes",
    reaction_improved_after_stopping="yes",
    # ... 10 standardized questions
)
# Returns: Score, probability (Definite/Probable/Possible/Doubtful)
```

#### 3. Signal Detection

```python
# Disproportionality analysis for signal detection
disproportionality_analysis(
    drug_name="aspirin",
    adverse_event="gastrointestinal bleeding"
)
# Returns: PRR, ROR, IC with confidence intervals
```

## 📊 Performance Improvements

- **Reduced API timeouts**: 3-5s instead of 10s for better responsiveness
- **Enhanced error handling**: Graceful degradation with meaningful error messages
- **Improved caching**: Smart cache management with statistics
- **Input validation**: Comprehensive bounds checking and data validation

## 🔧 Installation

```bash
# Clone the repository
git clone <repository-url>
cd pharmacist_mcp

# Install dependencies
pip install -r requirements.txt

# Run the server
python app.py
```

## 📋 Requirements

- Python 3.8+
- Internet connection for API access
- Dependencies listed in `requirements.txt`

## 🧪 Testing

Run the comprehensive test suite:

```bash
# Test core ADR analysis algorithms
python test_disproportionality.py

# Test individual components
python -c "from adr_analysis import calculate_naranjo_score; print(calculate_naranjo_score(...))"
```

## 🔗 API Endpoints

### MCP Functions Available:

#### Drug Safety & Information

- `search_adverse_events_mcp(drug_name, limit)`
- `fetch_event_details_mcp(event_id)`
- `drug_label_warnings_mcp(drug_name)`
- `drug_recalls_mcp(drug_name, limit)`
- `drug_pregnancy_lactation_mcp(drug_name)`
- `drug_dose_adjustments_mcp(drug_name)`
- `drug_livertox_summary_mcp(drug_name)`

#### ADR Analysis (NEW!)

- `enhanced_faers_search_mcp(drug_name, adverse_event, age_range, gender, serious_only, limit)`
- `calculate_naranjo_score_mcp(...10 parameters...)`
- `disproportionality_analysis_mcp(drug_name, adverse_event, background_limit)`
- `find_similar_cases_mcp(reference_case_id, similarity_threshold, limit)`
- `temporal_analysis_mcp(drug_name, adverse_event, limit)`

#### Clinical Calculators

- `calculate_creatinine_clearance_mcp(age, weight_kg, serum_creatinine, is_female)`
- `calculate_egfr_mcp(age, serum_creatinine, is_female, is_black)`
- `calculate_child_pugh_score_mcp(bilirubin, albumin, inr, ascites, encephalopathy)`
- `calculate_bmi_mcp(weight_kg, height_cm)`
- `calculate_ideal_body_weight_mcp(height_cm, is_male)`
- `recommend_dosing_weight_mcp(actual_weight, height_cm, is_male)`
- `calculate_drug_burden_index_mcp(drug_list, route)`

#### Utilities

- `brand_to_generic_lookup_mcp(brand_name, prefer_countries)`
- `convert_creatinine_units_mcp(value, from_unit, to_unit)`
- `get_cache_stats_mcp()`
- `health_check_mcp()`

## 📚 Data Sources

- **FAERS**: FDA Adverse Event Reporting System
- **FDA Drug Labels**: Official prescribing information
- **LiverTox**: NIH hepatotoxicity database
- **Drug Brand Database**: International brand name mappings

## ⚠️ Important Notes

- This tool is for informational purposes only
- Always consult official prescribing information
- Results should be interpreted by qualified healthcare professionals
- FAERS data has inherent limitations and reporting biases
- Pharmacovigilance analysis requires clinical expertise